http.cookies — HTTP 状态管理

源代码: Lib/http/cookies.py


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

该模块以前严格应用了 RFC 2109RFC 2068 规范中描述的解析规则。此后发现,MSIE 3.0x 没有遵循这些规范中概述的字符规则;许多当今的浏览器和服务器在处理 cookie 时也放宽了解析规则。因此,此模块现在使用的解析规则比以前稍微宽松一些。

字符集 string.ascii_letters, string.digits!#$%&'*+-.^_`|~: 表示此模块在 cookie 名称(作为 key)中允许的有效字符集。

在 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.cookiejarhttp.cookies 模块不相互依赖。

RFC 2109 - HTTP 状态管理机制

这是此模块实现的状态管理规范。

Morsel 对象

class http.cookies.Morsel

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

Morsel 是类似字典的对象,其键集是恒定的 — 有效的 RFC 2109 属性,它们是:

expires
path
comment
domain
max-age
secure
version
httponly
samesite

属性 httponly 指定该 cookie 仅在 HTTP 请求中传输,并且无法通过 JavaScript 访问。这旨在缓解某些形式的跨站脚本攻击。

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

键不区分大小写,其默认值为 ''

在 3.5 版本中更改: __eq__() 现在会考虑 keyvalue

在 3.7 版本中更改: 属性 key, valuecoded_value 是只读的。请使用 set() 来设置它们。

在 3.8 版本中更改: 增加了对 samesite 属性的支持。

Morsel.value

cookie 的值。

Morsel.coded_value

cookie 的编码值 — 这是应该发送的内容。

Morsel.key

cookie 的名称。

Morsel.set(key, value, coded_value)

设置 keyvaluecoded_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 字典中的任何键不是有效的 RFC 2109 属性,则引发错误。

在 3.5 版本中更改: 为无效键引发错误。

Morsel.copy(value)

返回 Morsel 对象的浅拷贝。

在 3.5 版本中更改: 返回一个 Morsel 对象而不是一个字典。

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