Docs4dev
Docs
python / 3.7.2rc1 / all / library-http.cookies.html

http.cookies — HTTP 状态 Management

源代码： Lib/http/cookies.py

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

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

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

在版本 3.3 中更改：允许使用“：”作为有效的 Cookie 名称字符。

Note

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

  • exception http.cookies. CookieError

    • 由于 RFC 2109无效而导致异常失败：错误的属性，错误的* Set-Cookie *Headers 等。
    • class * http.cookies. BaseCookie([* input *])
    • 此类是类似于字典的对象，其键是字符串，其值是Morsel个实例。请注意，在将键设置为值时，该值首先转换为包含键和值的Morsel。

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

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

See also

  • BaseCookie. value_decode(* val *)

    • 从字符串表示形式返回 Tuples(real_value, coded_value)。 real_value可以是任何类型。此方法在BaseCookie中不进行解码-它存在，因此可以覆盖它。

  • BaseCookie. value_encode(* val *)

    • 返回一个 Tuples(real_value, coded_value)。 * val *可以是任何类型，但是coded_value将始终转换为字符串。此方法在BaseCookie中不进行编码-它存在，因此可以覆盖它。

通常，应该是value_encode()和value_decode()在* value_decode *的范围内是倒数的情况。

  • BaseCookie. output(* attrs = None ， header ='Set-Cookie：'， sep =' rn'*)

    • 返回适合作为 HTTPHeaders 发送的字符串表示形式。 * attrs 和 header *被发送到每个Morsel的output()方法。 * sep *用于将 Headers 连接在一起，默认情况下为'\r\n'(CRLF)组合。

  • BaseCookie. js_output(* attrs = None *)

    • 返回一个可嵌入的 JavaScript 代码段，如果该代码段运行在支持 JavaScript 的浏览器上，则其行为将与发送 HTTPHeaders 相同。
  • attrs *的含义与output()中的含义相同。
  • BaseCookie. load(* rawdata *)
    • 如果* rawdata *是字符串，则将其解析为HTTP_COOKIE并将在此找到的值添加为Morsel。如果是字典，则等同于：

Morsel Objects

  • 类别 http.cookies. Morsel
    • 抽象一个具有一些 RFC 2109属性的键/值对。

杂项是类似于字典的对象，其键集是恒定的，即有效的 RFC 2109属性，即

  • expires

  • path

  • comment

  • domain

  • max-age

  • secure

  • version

  • httponly

  • samesite

属性httponly指定 cookie 仅在 HTTP 请求中传输，并且不能pass 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 的字符串表示形式，适合作为 HTTPHeaders 发送。默认情况下，包括所有属性，除非给出* attrs *，在这种情况下，它应该是要使用的属性列表。 * header *默认为"Set-Cookie:"。

  • Morsel. js_output(* attrs = None *)

    • 返回可嵌入的 JavaScript 代码段，如果该代码段在支持 JavaScript 的浏览器上运行，则其行为与发送 HTTPHeaders 的行为相同。
  • 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 对象而不是 dict。

  • Morsel. setdefault(* key ， value = None *)

Example

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