Skip to main content

21.23. http.cookies — HTTP状态管理

源代码: Lib/http/cookies.py


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

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

字符集,string.ascii_lettersstring.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() 分别覆盖为身份和 str()

参见

模块 http.cookiejar

Web clients 的HTTP cookie处理。 http.cookiejarhttp.cookies 模块不依赖于彼此。

RFC 2109 - HTTP状态管理机制

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

21.23.2. Morsel对象

class http.cookies.Morsel

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

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

  • expires

  • path

  • comment

  • domain

  • max-age

  • secure

  • version

  • httponly

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

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

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

Morsel.value

Cookie的值。

3.5 版后已移除: 分配给 value;使用 set()

Morsel.coded_value

Cookie的编码值 - 这是应该发送的内容。

3.5 版后已移除: 分配给 coded_value;使用 set()

Morsel.key

Cookie的名称。

3.5 版后已移除: 分配给 key;使用 set()

Morsel.set(key, value, coded_value)

设置 keyvaluecoded_value 属性。

3.5 版后已移除: 未记录的 LegalChars 参数将被忽略,并将在以后的版本中删除。

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() 的行为相同。

21.23.3. 例

以下示例演示如何使用 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