Skip to content

gh-151945: Fix reference warnings in http.cookiejar docs #152816

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
harjothkhara wants to merge 2 commits into
base: main
Choose a base branch
from
+59 −48
Open

gh-151945: Fix reference warnings in http.cookiejar docs #152816

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eecbef2
gh-151945: Fix reference warnings in http.cookiejar docs
harjothkhara Jul 1, 2026
097e9ce
gh-151945: Address review — sentence-case headers, plain language, ma…
harjothkhara Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 59 additions & 47 deletions Doc/library/http.cookiejar.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ introduced with RFC 2965.
.. note::

The various named parameters found in :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
:mailheader:`Set-Cookie2` headers (for example, ``domain`` and ``expires``) are
conventionally referred to as :dfn:`attributes`. To distinguish them from
Python attributes, the documentation for this module uses the term
:dfn:`cookie-attribute` instead.
Expand Down Expand Up @@ -85,20 +85,20 @@ The following classes are provided:

Constructor arguments should be passed as keyword arguments only.
*blocked_domains* is a sequence of domain names that we never accept cookies
from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
from, nor return cookies to. *allowed_domains* if not ``None``, this is a
sequence of the only domains for which we accept and return cookies.
*secure_protocols* is a sequence of protocols for which secure cookies can be
added to. By default *https* and *wss* (secure websocket) are considered
secure protocols. For all other arguments, see the documentation for
:class:`CookiePolicy` and :class:`DefaultCookiePolicy` objects.

:class:`DefaultCookiePolicy` implements the standard accept / reject rules for
Netscape and :rfc:`2965` cookies. By default, :rfc:`2109` cookies (ie. cookies
Netscape and :rfc:`2965` cookies. By default, :rfc:`2109` cookies (that is, cookies
received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
is turned off or :attr:`rfc2109_as_netscape` is ``True``, RFC 2109 cookies are
'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
setting the :attr:`version` attribute of the :class:`Cookie` instance to 0.
setting the :attr:`~Cookie.version` attribute of the :class:`Cookie` instance to 0.
:class:`DefaultCookiePolicy` also provides some parameters to allow some
fine-tuning of policy.

Expand All @@ -107,7 +107,7 @@ The following classes are provided:

This class represents Netscape, :rfc:`2109` and :rfc:`2965` cookies. It is not
expected that users of :mod:`!http.cookiejar` construct their own :class:`Cookie`
instances. Instead, if necessary, call :meth:`make_cookies` on a
instances. Instead, if necessary, call :meth:`~CookieJar.make_cookies` on a
:class:`CookieJar` instance.


Expand Down Expand Up @@ -141,7 +141,7 @@ The following classes are provided:

.. _cookie-jar-objects:

CookieJar and FileCookieJar Objects
CookieJar and FileCookieJar objects
-----------------------------------

:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
Expand All @@ -154,20 +154,27 @@ contained :class:`Cookie` objects.

Add correct :mailheader:`Cookie` header to *request*.

If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
If policy allows (that is, the :attr:`~CookiePolicy.rfc2965` and
:attr:`~CookiePolicy.hide_cookie2` attributes of
the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
respectively), the :mailheader:`Cookie2` header is also added when appropriate.

The *request* object (usually a :class:`urllib.request.Request` instance)
must support the methods :meth:`get_full_url`, :meth:`has_header`,
:meth:`get_header`, :meth:`header_items`, :meth:`add_unredirected_header`
and the attributes :attr:`host`, :attr:`!type`, :attr:`unverifiable`
and :attr:`origin_req_host` as documented by :mod:`urllib.request`.
must support the methods :meth:`~urllib.request.Request.get_full_url`,
:meth:`~urllib.request.Request.has_header`,
:meth:`~urllib.request.Request.get_header`,
:meth:`~urllib.request.Request.header_items`,
:meth:`~urllib.request.Request.add_unredirected_header`
and the attributes :attr:`~urllib.request.Request.host`, :attr:`!type`,
:attr:`~urllib.request.Request.unverifiable`
and :attr:`~urllib.request.Request.origin_req_host` as documented by
:mod:`urllib.request`.

.. versionchanged:: 3.3

*request* object needs :attr:`origin_req_host` attribute. Dependency on a
deprecated method :meth:`get_origin_req_host` has been removed.
*request* object needs :attr:`~urllib.request.Request.origin_req_host`
attribute. Dependency on a deprecated method
:meth:`!get_origin_req_host` has been removed.


.. method:: CookieJar.extract_cookies(response, request)
Expand All @@ -180,20 +187,24 @@ contained :class:`Cookie` objects.
as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval).

The *response* object (usually the result of a call to
:meth:`urllib.request.urlopen`, or similar) should support an :meth:`info`
method, which returns an :class:`email.message.Message` instance.
:meth:`urllib.request.urlopen`, or similar) should support an
:meth:`~urllib.response.addinfourl.info` method, which returns an

@StanFromIreland StanFromIreland Jul 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This method is deprecated, this should link to http.client.HTTPResponse.

:class:`email.message.Message` instance.

The *request* object (usually a :class:`urllib.request.Request` instance)
must support the method :meth:`get_full_url` and the attributes
:attr:`host`, :attr:`unverifiable` and :attr:`origin_req_host`,
must support the method :meth:`~urllib.request.Request.get_full_url` and
the attributes :attr:`~urllib.request.Request.host`,
:attr:`~urllib.request.Request.unverifiable`
and :attr:`~urllib.request.Request.origin_req_host`,
as documented by :mod:`urllib.request`. The request is used to set
default values for cookie-attributes as well as for checking that the
cookie is allowed to be set.

.. versionchanged:: 3.3

*request* object needs :attr:`origin_req_host` attribute. Dependency on a
deprecated method :meth:`get_origin_req_host` has been removed.
*request* object needs :attr:`~urllib.request.Request.origin_req_host`
attribute. Dependency on a deprecated method
:meth:`!get_origin_req_host` has been removed.

.. method:: CookieJar.set_policy(policy)

Expand Down Expand Up @@ -236,13 +247,13 @@ contained :class:`Cookie` objects.

Discard all session cookies.

Discards all contained cookies that have a true :attr:`discard` attribute
Discards all contained cookies that have a true :attr:`~Cookie.discard` attribute
(usually because they had either no ``max-age`` or ``expires`` cookie-attribute,
or an explicit ``discard`` cookie-attribute). For interactive browsers, the end
of a session usually corresponds to closing the browser window.

Note that the :meth:`save` method won't save session cookies anyway, unless you
ask otherwise by passing a true *ignore_discard* argument.
Note that the :meth:`~FileCookieJar.save` method won't save session cookies
anyway, unless you ask otherwise by passing a true *ignore_discard* argument.

:class:`FileCookieJar` implements the following additional methods:

Expand All @@ -255,8 +266,9 @@ contained :class:`Cookie` objects.
method unimplemented.

*filename* is the name of file in which to save cookies. If *filename* is not
specified, :attr:`self.filename` is used (whose default is the value passed to
the constructor, if any); if :attr:`self.filename` is :const:`None`,
specified, :attr:`~FileCookieJar.filename` is used (whose default is the

@StanFromIreland StanFromIreland Jul 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's keep it as self.filename here, otherwise it renders confusingly as "filename."

value passed to the constructor, if any); if
:attr:`~FileCookieJar.filename` is ``None``,
:exc:`ValueError` is raised.

*ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
Expand Down Expand Up @@ -349,7 +361,7 @@ writing.

.. _cookie-policy-objects:

CookiePolicy Objects
CookiePolicy objects
--------------------

Objects implementing the :class:`CookiePolicy` interface have the following
Expand Down Expand Up @@ -433,7 +445,7 @@ setting and receiving any and all cookies (this is unlikely to be useful).

.. _default-cookie-policy-objects:

DefaultCookiePolicy Objects
DefaultCookiePolicy objects
---------------------------

Implements the standard rules for accepting and returning cookies.
Expand Down Expand Up @@ -463,10 +475,10 @@ blocking some benign cookies).
A domain blocklist and allowlist is provided (both off by default). Only domains
not in the blocklist and present in the allowlist (if the allowlist is active)
participate in cookie setting and returning. Use the *blocked_domains*
constructor argument, and :meth:`blocked_domains` and
:meth:`set_blocked_domains` methods (and the corresponding argument and methods
for *allowed_domains*). If you set an allowlist, you can turn it off again by
setting it to :const:`None`.
constructor argument, and :meth:`~DefaultCookiePolicy.blocked_domains` and
:meth:`~DefaultCookiePolicy.set_blocked_domains` methods (and the corresponding
argument and methods for *allowed_domains*). If you set an allowlist, you can
turn it off again by setting it to ``None``.

Domains in block or allow lists that do not start with a dot must equal the
cookie domain to be matched. For example, ``"example.com"`` matches a blocklist
Expand Down Expand Up @@ -498,12 +510,12 @@ and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.

.. method:: DefaultCookiePolicy.allowed_domains()

Return :const:`None`, or the sequence of allowed domains (as a tuple).
Return ``None``, or the sequence of allowed domains (as a tuple).


.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)

Set the sequence of allowed domains, or :const:`None`.
Set the sequence of allowed domains, or ``None``.


.. method:: DefaultCookiePolicy.is_not_allowed(domain)
Expand All @@ -519,9 +531,9 @@ all be assigned to.
.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape

If true, request that the :class:`CookieJar` instance downgrade :rfc:`2109` cookies
(ie. cookies received in a :mailheader:`Set-Cookie` header with a version
(that is, cookies received in a :mailheader:`Set-Cookie` header with a version
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
the :class:`Cookie` instance to 0. The default value is :const:`None`, in which
the :class:`Cookie` instance to 0. The default value is ``None``, in which
case RFC 2109 cookies are downgraded if and only if :rfc:`2965` handling is turned
off. Therefore, RFC 2109 cookies are downgraded by default.

Expand Down Expand Up @@ -574,15 +586,15 @@ both flags are set).

.. attribute:: DefaultCookiePolicy.DomainStrictNoDots

When setting cookies, the 'host prefix' must not contain a dot (eg.
When setting cookies, the 'host prefix' must not contain a dot (for example,
``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
contains a dot).


.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain

Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
be returned to a domain equal to the domain that set the cookie (eg.
be returned to a domain equal to the domain that set the cookie (for example,
``spam.example.com`` won't be returned cookies from ``example.com`` that had no
``domain`` cookie-attribute).

Expand All @@ -597,7 +609,7 @@ combinations of the above flags:

.. attribute:: DefaultCookiePolicy.DomainLiberal

Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
Equivalent to 0 (that is, all of the above Netscape domain strictness flags switched
off).


Expand All @@ -606,7 +618,7 @@ combinations of the above flags:
Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.


Cookie Objects
Cookie objects
--------------

:class:`Cookie` instances have Python attributes roughly corresponding to the
Expand All @@ -624,7 +636,7 @@ internal consistency, so you should know what you're doing if you do that.

.. attribute:: Cookie.version

Integer or :const:`None`. Netscape cookies have :attr:`version` 0. :rfc:`2965` and
Integer or ``None``. Netscape cookies have :attr:`version` 0. :rfc:`2965` and
:rfc:`2109` cookies have a ``version`` cookie-attribute of 1. However, note that
:mod:`!http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
case :attr:`version` is 0.
Expand All @@ -637,13 +649,13 @@ internal consistency, so you should know what you're doing if you do that.

.. attribute:: Cookie.value

Cookie value (a string), or :const:`None`.
Cookie value (a string), or ``None``.


.. attribute:: Cookie.port

String representing a port or a set of ports (eg. '80', or '80,8080'), or
:const:`None`.
String representing a port or a set of ports (for example, '80', or '80,8080'), or
``None``.


.. attribute:: Cookie.domain
Expand All @@ -653,7 +665,7 @@ internal consistency, so you should know what you're doing if you do that.

.. attribute:: Cookie.path

Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
Cookie path (a string, for example, ``'/acme/rocket_launchers'``).


.. attribute:: Cookie.secure
Expand All @@ -663,7 +675,7 @@ internal consistency, so you should know what you're doing if you do that.

.. attribute:: Cookie.expires

Integer expiry date in seconds since epoch, or :const:`None`. See also the
Integer expiry date in seconds since epoch, or ``None``. See also the
:meth:`is_expired` method.


Expand All @@ -675,18 +687,18 @@ internal consistency, so you should know what you're doing if you do that.
.. attribute:: Cookie.comment

String comment from the server explaining the function of this cookie, or
:const:`None`.
``None``.


.. attribute:: Cookie.comment_url

URL linking to a comment from the server explaining the function of this cookie,
or :const:`None`.
or ``None``.


.. attribute:: Cookie.rfc2109

``True`` if this cookie was received as an :rfc:`2109` cookie (ie. the cookie
``True`` if this cookie was received as an :rfc:`2109` cookie (that is, the cookie
arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
cookie-attribute in that header was 1). This attribute is provided because
:mod:`!http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ Doc/library/ast.rst
Doc/library/asyncio-extending.rst
Doc/library/email.charset.rst
Doc/library/email.parser.rst
Doc/library/http.cookiejar.rst
Doc/library/http.server.rst
Doc/library/importlib.rst
Doc/library/logging.config.rst
Expand Down
Loading