Skip to content

Commit 097e9ce

Browse files
harjothkharaclaude
andcommitted
gh-151945: Address review — sentence-case headers, plain language, markup
Apply Hugo's review feedback for Doc/library/http.cookiejar.rst: - Use sentence case for the four "... Objects" section headers. - Replace the Latin abbreviations "ie."/"eg." with "that is"/"for example" per the devguide simple-language guidance. - Use ``None`` literal markup instead of :const:`None`. - Reference the removed method as :meth:`!get_origin_req_host` to match the surrounding formatting. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent eecbef2 commit 097e9ce

1 file changed

Lines changed: 30 additions & 31 deletions

File tree

Doc/library/http.cookiejar.rst

Lines changed: 30 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ introduced with RFC 2965.
2626
.. note::
2727

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

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

9595
:class:`DefaultCookiePolicy` implements the standard accept / reject rules for
96-
Netscape and :rfc:`2965` cookies. By default, :rfc:`2109` cookies (ie. cookies
96+
Netscape and :rfc:`2965` cookies. By default, :rfc:`2109` cookies (that is, cookies
9797
received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
9898
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
9999
is turned off or :attr:`rfc2109_as_netscape` is ``True``, RFC 2109 cookies are
@@ -141,7 +141,7 @@ The following classes are provided:
141141

142142
.. _cookie-jar-objects:
143143

144-
CookieJar and FileCookieJar Objects
144+
CookieJar and FileCookieJar objects
145145
-----------------------------------
146146

147147
:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
@@ -154,7 +154,7 @@ contained :class:`Cookie` objects.
154154

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

157-
If policy allows (ie. the :attr:`~CookiePolicy.rfc2965` and
157+
If policy allows (that is, the :attr:`~CookiePolicy.rfc2965` and
158158
:attr:`~CookiePolicy.hide_cookie2` attributes of
159159
the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
160160
respectively), the :mailheader:`Cookie2` header is also added when appropriate.
@@ -173,8 +173,8 @@ contained :class:`Cookie` objects.
173173
.. versionchanged:: 3.3
174174

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

179179

180180
.. method:: CookieJar.extract_cookies(response, request)
@@ -203,8 +203,8 @@ contained :class:`Cookie` objects.
203203
.. versionchanged:: 3.3
204204

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

209209
.. method:: CookieJar.set_policy(policy)
210210

@@ -268,7 +268,7 @@ contained :class:`Cookie` objects.
268268
*filename* is the name of file in which to save cookies. If *filename* is not
269269
specified, :attr:`~FileCookieJar.filename` is used (whose default is the
270270
value passed to the constructor, if any); if
271-
:attr:`~FileCookieJar.filename` is :const:`None`,
271+
:attr:`~FileCookieJar.filename` is ``None``,
272272
:exc:`ValueError` is raised.
273273

274274
*ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
@@ -361,7 +361,7 @@ writing.
361361

362362
.. _cookie-policy-objects:
363363

364-
CookiePolicy Objects
364+
CookiePolicy objects
365365
--------------------
366366

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

446446
.. _default-cookie-policy-objects:
447447

448-
DefaultCookiePolicy Objects
448+
DefaultCookiePolicy objects
449449
---------------------------
450450

451451
Implements the standard rules for accepting and returning cookies.
@@ -478,8 +478,7 @@ participate in cookie setting and returning. Use the *blocked_domains*
478478
constructor argument, and :meth:`~DefaultCookiePolicy.blocked_domains` and
479479
:meth:`~DefaultCookiePolicy.set_blocked_domains` methods (and the corresponding
480480
argument and methods for *allowed_domains*). If you set an allowlist, you can
481-
turn it off again by
482-
setting it to :const:`None`.
481+
turn it off again by setting it to ``None``.
483482

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

512511
.. method:: DefaultCookiePolicy.allowed_domains()
513512

514-
Return :const:`None`, or the sequence of allowed domains (as a tuple).
513+
Return ``None``, or the sequence of allowed domains (as a tuple).
515514

516515

517516
.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)
518517

519-
Set the sequence of allowed domains, or :const:`None`.
518+
Set the sequence of allowed domains, or ``None``.
520519

521520

522521
.. method:: DefaultCookiePolicy.is_not_allowed(domain)
@@ -532,9 +531,9 @@ all be assigned to.
532531
.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
533532

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

@@ -587,15 +586,15 @@ both flags are set).
587586

588587
.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
589588

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

594593

595594
.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
596595

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

@@ -610,7 +609,7 @@ combinations of the above flags:
610609

611610
.. attribute:: DefaultCookiePolicy.DomainLiberal
612611

613-
Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
612+
Equivalent to 0 (that is, all of the above Netscape domain strictness flags switched
614613
off).
615614

616615

@@ -619,7 +618,7 @@ combinations of the above flags:
619618
Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
620619

621620

622-
Cookie Objects
621+
Cookie objects
623622
--------------
624623

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

638637
.. attribute:: Cookie.version
639638

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

651650
.. attribute:: Cookie.value
652651

653-
Cookie value (a string), or :const:`None`.
652+
Cookie value (a string), or ``None``.
654653

655654

656655
.. attribute:: Cookie.port
657656

658-
String representing a port or a set of ports (eg. '80', or '80,8080'), or
659-
:const:`None`.
657+
String representing a port or a set of ports (for example, '80', or '80,8080'), or
658+
``None``.
660659

661660

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

667666
.. attribute:: Cookie.path
668667

669-
Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
668+
Cookie path (a string, for example, ``'/acme/rocket_launchers'``).
670669

671670

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

677676
.. attribute:: Cookie.expires
678677

679-
Integer expiry date in seconds since epoch, or :const:`None`. See also the
678+
Integer expiry date in seconds since epoch, or ``None``. See also the
680679
:meth:`is_expired` method.
681680

682681

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

690689
String comment from the server explaining the function of this cookie, or
691-
:const:`None`.
690+
``None``.
692691

693692

694693
.. attribute:: Cookie.comment_url
695694

696695
URL linking to a comment from the server explaining the function of this cookie,
697-
or :const:`None`.
696+
or ``None``.
698697

699698

700699
.. attribute:: Cookie.rfc2109
701700

702-
``True`` if this cookie was received as an :rfc:`2109` cookie (ie. the cookie
701+
``True`` if this cookie was received as an :rfc:`2109` cookie (that is, the cookie
703702
arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
704703
cookie-attribute in that header was 1). This attribute is provided because
705704
:mod:`!http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in

0 commit comments

Comments
 (0)