http.cookies — HTTP 状态管理

源代码： :source:`Lib/http/cookies.py`

http.cookies 模块定义了用于抽象 cookie 概念的类，cookie 是一种 HTTP 状态管理机制。它支持简单的纯字符串 cookie，并提供了一个抽象，用于将任何可序列化的数据类型作为 cookie 值。

该模块以前严格应用了 RFC 2109 和 RFC 2068 规范中描述的解析规则。后来发现，MSIE 3.0x 不遵循这些规范中概述的字符规则，而且当今许多浏览器和服务器在处理 Cookie 时都放宽了解析规则。因此，使用的解析规则不太严格。

字符集 string.ascii_letters、string.digits 和 !#$%&'*+-.^_`|~: 表示该模块在 Cookie 名称中允许的有效字符集（如 key[ X171X]）。

在 3.3 版中更改：允许 ':' 作为有效的 Cookie 名称字符。

笔记

在遇到无效 cookie 时，会引发 CookieError，因此如果您的 cookie 数据来自浏览器，您应该始终为无效数据做好准备并在解析时捕获 CookieError。

exception http.cookies.CookieError: 由于 RFC 2109 无效，异常失败：不正确的属性、不正确的 Set-Cookie 标头等。

class http.cookies.BaseCookie([input])

这个类是一个类似字典的对象，其键是字符串，其值是 Morsel 实例。请注意，将键设置为值后，该值首先转换为包含键和值的 Morsel。

如果给出 input，则将其传递给 load() 方法。

class http.cookies.SimpleCookie([input]): 此类派生自 BaseCookie 并覆盖 value_decode() 和 value_encode()。 SimpleCookie 支持字符串作为 cookie 值。在设置值时，SimpleCookie 调用内置的 str() 将值转换为字符串。从 HTTP 接收的值保留为字符串。

也可以看看

模块 http.cookiejar: Web 客户端 的 HTTP cookie 处理。 http.cookiejar 和 http.cookies 模块不相互依赖。
RFC 2109 - HTTP 状态管理机制: 这是该模块实现的状态管理规范。

Cookie 对象

BaseCookie.value_decode(val): 从字符串表示中返回一个元组 (real_value, coded_value)。 real_value 可以是任何类型。这个方法在 BaseCookie 中没有解码——它存在所以它可以被覆盖。

BaseCookie.value_encode(val)

返回一个元组 (real_value, coded_value)。 val 可以是任何类型，但 coded_value 将始终转换为字符串。这个方法在 BaseCookie 中没有编码——它存在所以它可以被覆盖。

一般来说，value_encode()和value_decode()应该是value_decode范围的倒数。

BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\\r\\n'): 返回适合作为 HTTP 标头发送的字符串表示形式。 attrs 和 header 被发送到每个 Morsel 的 output() 方法。 sep 用于将标头连接在一起，默认情况下是组合 '\r\n' (CRLF)。

BaseCookie.js_output(attrs=None)

返回一个可嵌入的 JavaScript 片段，如果在支持 JavaScript 的浏览器上运行，它的行为将与发送 HTTP 标头一样。

attrs 的含义与 output() 中的含义相同。

BaseCookie.load(rawdata)

如果 rawdata 是字符串，则将其解析为 HTTP_COOKIE 并将在那里找到的值添加为 Morsels。如果是字典，则相当于：

for k, v in rawdata.items():
    cookie[k] = v

小物件

class http.cookies.Morsel

抽象一个键/值对，它有一些 RFC 2109 属性。

Morsels 是类似字典的对象，其键集是常量——有效的 RFC 2109 属性，它们是

expires
path
comment
domain
max-age
secure
version
httponly
samesite

属性 httponly 指定 cookie 仅在 HTTP 请求中传输，不能通过 JavaScript 访问。这旨在减轻某些形式的跨站点脚本。

属性 samesite 指定浏览器不允许将 cookie 与跨站点请求一起发送。这有助于减轻 CSRF 攻击。此属性的有效值为“Strict”和“Lax”。

键不区分大小写，默认值为。

在 3.5 版更改：__eq__() 现在考虑 key 和 value。

3.7 版更改：属性 key、value 和 coded_value 是只读的。使用 set() 来设置它们。

3.8 版更改：添加了对 samesite 属性的支持。

Morsel.value: cookie 的值。

Morsel.coded_value: cookie 的编码值——这是应该发送的。

Morsel.key: cookie 的名称。

Morsel.set(key, value, coded_value): 设置 key、value 和 coded_value 属性。

Morsel.isReservedKey(K): K 是否是 Morsel 的键集的成员。

Morsel.output(attrs=None, header='Set-Cookie:'): 返回 Morsel 的字符串表示，适合作为 HTTP 标头发送。默认情况下，所有属性都包含在内，除非给出 attrs，在这种情况下，它应该是要使用的属性列表。 header 默认为 "Set-Cookie:"。

Morsel.js_output(attrs=None)

返回一个可嵌入的 JavaScript 片段，如果在支持 JavaScript 的浏览器上运行，它的行为与发送 HTTP 标头的行为相同。

attrs 的含义与 output() 中的含义相同。

Morsel.OutputString(attrs=None)

返回一个表示 Morsel 的字符串，不包含任何 HTTP 或 JavaScript。

attrs 的含义与 output() 中的含义相同。

Morsel.update(values): 使用字典 values 中的值更新 Morsel 字典中的值。如果 values dict 中的任何键不是有效的 RFC 2109 属性，则会引发错误。

3.5 版更改：无效密钥引发错误。

Morsel.copy(value): 返回 Morsel 对象的浅拷贝。

3.5 版更改：返回一个 Morsel 对象而不是一个 dict。

Morsel.setdefault(key, value=None): 如果密钥不是有效的 RFC 2109 属性，则引发错误，否则行为与 dict.setdefault() 相同。

例子

以下示例演示了如何使用 http.cookies 模块。

>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = cookies.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print(C.output(header="Cookie:"))
Cookie: rocky=road; Path=/cookie
>>> print(C.output(attrs=[], header="Cookie:"))
Cookie: rocky=road
>>> C = cookies.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print(C)
Set-Cookie: number=7
Set-Cookie: string=seven

http.cookies — HTTP 状态管理 — Python 文档

目录

http.cookies — HTTP 状态管理

小物件

例子