Python/docs/3.9/library/http.cookies

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