Skip to content

Commit f5e28f9

Browse files
authored
Merge branch 'main' into email-utils-doc-param-names
2 parents c08b89b + 7ac989f commit f5e28f9

62 files changed

Lines changed: 1832 additions & 357 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/faq/design.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -401,7 +401,7 @@ library that are impossible to free (e.g. a tool like Purify will complain about
401401
these). Python is, however, aggressive about cleaning up memory on exit and
402402
does try to destroy every single object.
403403

404-
If you want to force Python to delete certain things on deallocation use the
404+
If you want to force Python to delete certain things when Python exits, use the
405405
:mod:`atexit` module to run a function that will force those deletions.
406406

407407

‎Doc/faq/extending.rst‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -209,25 +209,20 @@ minor that it doesn't seem worth the effort.)
209209
How do I debug an extension?
210210
----------------------------
211211

212-
When using GDB with dynamically loaded extensions, you can't set a breakpoint in
213-
your extension until your extension is loaded.
214-
215-
In your ``.gdbinit`` file (or interactively), add the command:
216-
217-
.. code-block:: none
218-
219-
br _PyImport_LoadDynamicModule
220-
221-
Then, when you run GDB:
212+
When using GDB with dynamically loaded extensions, enable pending breakpoints
213+
to set a breakpoint before the extension is loaded. For example, to stop in
214+
a function named ``myfunction``:
222215

223216
.. code-block:: shell-session
224217
225218
$ gdb /local/bin/python
226-
gdb) run myscript.py
227-
gdb) continue # repeat until your extension is loaded
228-
gdb) finish # so that your extension is loaded
229-
gdb) br myfunction.c:50
230-
gdb) continue
219+
(gdb) set breakpoint pending on
220+
(gdb) break myfunction
221+
(gdb) run myscript.py
222+
223+
GDB resolves the breakpoint when the extension is loaded and stops when the
224+
function is called. You can also set a pending breakpoint directly in your
225+
extension's source code, for example with ``break myfunction.c:50``.
231226

232227
I want to compile a Python module on my Linux system, but some files are missing. Why?
233228
--------------------------------------------------------------------------------------

‎Doc/faq/programming.rst‎

Lines changed: 4 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1198,8 +1198,7 @@ Use the :func:`reversed` built-in function::
11981198
for x in reversed(sequence):
11991199
... # do something with x ...
12001200

1201-
This won't touch your original sequence, but build a new copy with reversed
1202-
order to iterate over.
1201+
This returns a reverse iterator without modifying your original sequence.
12031202

12041203

12051204
How do you remove duplicates from a list?
@@ -1642,8 +1641,8 @@ Use the built-in :func:`super` function::
16421641

16431642
In the example, :func:`super` will automatically determine the instance from
16441643
which it was called (the ``self`` value), look up the :term:`method resolution
1645-
order` (MRO) with ``type(self).__mro__``, and return the next in line after
1646-
``Derived`` in the MRO: ``Base``.
1644+
order` (MRO) with ``type(self).__mro__``, and return a proxy that searches for
1645+
methods starting with the next class after ``Derived`` in the MRO: ``Base``.
16471646

16481647

16491648
How can I organize my code to make it easier to change the base class?
@@ -1686,7 +1685,7 @@ C)`` holds, unless overridden by ``c`` itself or by some class on the base-class
16861685
search path from ``c.__class__`` back to ``C``.
16871686

16881687
Caution: within a method of C, an assignment like ``self.count = 42`` creates a
1689-
new and unrelated instance named "count" in ``self``'s own dict. Rebinding of a
1688+
new and unrelated attribute named "count" in ``self``'s own dict. Rebinding of a
16901689
class-static data name must always specify the class whether inside a method or
16911690
not::
16921691

@@ -2055,30 +2054,6 @@ relevant instance attributes are mutable, the ``cached_property`` approach
20552054
can't be made to work because it cannot detect changes to the
20562055
attributes.
20572056

2058-
To make the ``lru_cache`` approach work when the *station_id* is mutable,
2059-
the class needs to define the :meth:`~object.__eq__` and :meth:`~object.__hash__`
2060-
methods so that the cache can detect relevant attribute updates::
2061-
2062-
class Weather:
2063-
"Example with a mutable station identifier"
2064-
2065-
def __init__(self, station_id):
2066-
self.station_id = station_id
2067-
2068-
def change_station(self, station_id):
2069-
self.station_id = station_id
2070-
2071-
def __eq__(self, other):
2072-
return self.station_id == other.station_id
2073-
2074-
def __hash__(self):
2075-
return hash(self.station_id)
2076-
2077-
@lru_cache(maxsize=20)
2078-
def historic_rainfall(self, date, units='cm'):
2079-
'Rainfall on a given date'
2080-
# Depends on the station_id, date, and units.
2081-
20822057

20832058
Modules
20842059
=======

‎Doc/library/http.client.rst‎

Lines changed: 116 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,29 @@ The following exceptions are raised as appropriate:
230230
Previously, :exc:`BadStatusLine`\ ``('')`` was raised.
231231

232232

233+
.. exception:: ProxyTunnelError
234+
235+
A subclass of :exc:`OSError`. Raised when the proxy server answers the
236+
CONNECT request sent for :meth:`HTTPConnection.set_tunnel` with a status
237+
other than 200.
238+
239+
.. attribute:: code
240+
241+
The HTTP status code of the proxy's response, such as ``407``.
242+
243+
.. attribute:: reason
244+
245+
The reason phrase of the proxy's response.
246+
247+
.. attribute:: headers
248+
249+
The headers of the proxy's response, as an
250+
:class:`http.client.HTTPMessage` instance.
251+
252+
.. versionadded:: next
253+
Previously, :exc:`OSError` was raised.
254+
255+
233256
The constants defined in this module are:
234257

235258
.. data:: HTTP_PORT
@@ -259,7 +282,7 @@ HTTPConnection Objects
259282

260283

261284
.. method:: HTTPConnection.request(method, url, body=None, headers={}, *, \
262-
encode_chunked=False)
285+
encode_chunked=False, continue_timeout=2.5)
263286

264287
This will send a request to the server using the HTTP request
265288
method *method* and the request URI *url*. The provided *url* must be
@@ -335,11 +358,33 @@ HTTPConnection Objects
335358
No attempt is made to determine the Content-Length for file
336359
objects.
337360

338-
.. method:: HTTPConnection.getresponse()
361+
.. versionchanged:: next
362+
The *continue_timeout* parameter was added.
363+
364+
If the headers include ``Expect: 100-Continue`` and *body* is set, the
365+
body will not be sent until either a ``100 Continue`` response is
366+
received from the server or *continue_timeout* seconds have elapsed; if a
367+
response code other than 100 is received, the body will not be sent at all.
368+
369+
*continue_timeout* value must be greater than zero, otherwise
370+
:exc:`ValueError` is raised.
371+
372+
.. method:: HTTPConnection.getresponse(support_continue=False)
339373

340374
Should be called after a request is sent to get the response from the server.
341375
Returns an :class:`HTTPResponse` instance.
342376

377+
By default, ``100 Continue`` responses are skipped and the method returns
378+
the first response with a status other than 100. If *support_continue*
379+
is true, a ``100 Continue`` response is returned to the caller, which must
380+
then send the request body and call :meth:`getresponse` again to obtain
381+
the final response.
382+
383+
.. note::
384+
385+
The whole response must be read before a new request can be sent to
386+
the server.
387+
343388
.. versionchanged:: 3.5
344389
If a :exc:`ConnectionError` or subclass is raised, the
345390
:class:`HTTPConnection` object will be ready to reconnect when
@@ -349,6 +394,10 @@ HTTPConnection Objects
349394
socket. Instead the caller is responsible to call :meth:`close` on the
350395
existing connection.
351396

397+
.. versionchanged:: next
398+
Added the *support_continue* parameter. (In prior versions
399+
a ``Continue`` response was always ignored.)
400+
352401

353402
.. method:: HTTPConnection.set_debuglevel(level)
354403

@@ -398,6 +447,9 @@ HTTPConnection Objects
398447
one will be automatically generated and transmitted if not provided in
399448
the headers argument.
400449

450+
.. versionchanged:: next
451+
:exc:`ProxyTunnelError` is raised if the proxy rejects the CONNECT request.
452+
401453

402454
.. method:: HTTPConnection.get_proxy_response_headers()
403455

@@ -444,7 +496,8 @@ also send your request step by step, by using the four functions below.
444496

445497

446498
.. method:: HTTPConnection.putrequest(method, url, skip_host=False, \
447-
skip_accept_encoding=False)
499+
skip_accept_encoding=False, \
500+
continue_timeout=2.5)
448501

449502
This should be the first call after the connection to the server has been
450503
made. It sends a line to the server consisting of the *method* string,
@@ -453,6 +506,14 @@ also send your request step by step, by using the four functions below.
453506
additional content encodings), specify *skip_host* or *skip_accept_encoding*
454507
with non-False values.
455508

509+
If an ``Expect: 100-Continue`` header is sent, the optional
510+
*continue_timeout* parameter sets how many seconds the client will wait for
511+
a ``100 Continue`` response before sending the message body, It must be
512+
greater than zero, otherwise :exc:`ValueError` is raised.
513+
514+
.. versionchanged:: next
515+
*continue_timeout* parameter was added.
516+
456517

457518
.. method:: HTTPConnection.putheader(header, argument[, ...])
458519

@@ -466,7 +527,12 @@ also send your request step by step, by using the four functions below.
466527

467528
Send a blank line to the server, signalling the end of the headers. The
468529
optional *message_body* argument can be used to pass a message body
469-
associated with the request.
530+
associated with the request. If a body is provided and an
531+
``Expect: 100-Continue`` header has been sent, the body will not be sent
532+
until a ``100 Continue`` response is received from the server; if another
533+
response code is received, the body is not sent at all. If no response
534+
is received within the *continue_timeout* given to :meth:`putrequest`,
535+
the body will be sent regardless.
470536

471537
If *encode_chunked* is ``True``, the result of each iteration of
472538
*message_body* will be chunk-encoded as specified in :rfc:`7230`,
@@ -487,6 +553,12 @@ also send your request step by step, by using the four functions below.
487553
.. versionchanged:: 3.6
488554
Added chunked encoding support and the *encode_chunked* parameter.
489555

556+
.. versionchanged:: next
557+
If an ``Expect: 100-Continue`` header has been sent, the body will not be
558+
sent until a ``100 Continue`` response is received from the server, or a
559+
contine_timeout has elapsed. If the response code is not 100, the body
560+
will not be sent at all.
561+
490562

491563
.. method:: HTTPConnection.send(data)
492564

@@ -665,6 +737,46 @@ method attribute. Here is an example session that uses the ``PUT`` method::
665737
>>> print(response.status, response.reason)
666738
200 OK
667739

740+
Conditional transmission of the body is supported when an ``Expect: 100-Continue``
741+
header is set. To use this in a simple case, just set the header, and
742+
optionally the time for which the client should wait for a ``100 Continue``
743+
response before sending the body regardless::
744+
745+
>>> import http.client
746+
>>> BODY = "***filecontents***"
747+
>>> conn = http.client.HTTPConnection("localhost", 8080)
748+
>>> conn.request("PUT", "/file", BODY, headers={'Expect': '100-Continue'},
749+
... continue_timeout=1.0)
750+
>>> response = conn.getresponse()
751+
>>> # You will not see the '100' response, as it is handled internally
752+
>>> print(response.status, response.reason)
753+
200, OK
754+
755+
Here is a more complex example in which we manually check the response and
756+
decide whether to send the body. This may be useful if the body must be
757+
generated by some resource-intensive process which should be skipped if the
758+
server will not accept it. *continue_timeout* does not apply here, so this
759+
should only be used with servers known to support ``Expect: 100-Continue``;
760+
otherwise :meth:`~HTTPConnection.getresponse` may block until the
761+
connection's *timeout* expires. ::
762+
763+
>>> import http.client
764+
>>> conn = http.client.HTTPConnection("localhost", 8080)
765+
>>> conn.putrequest("PUT", "/file")
766+
>>> conn.putheader('Expect', '100-Continue')
767+
>>> # Assuming you know in advance what the length will be
768+
>>> # If not, you will need to encode it as chunked
769+
>>> conn.putheader('Content-Length', '42')
770+
>>> conn.endheaders()
771+
>>> response = conn.getresponse(support_continue=True)
772+
>>> print(response.status, response.reason)
773+
100, Continue
774+
>>> BODY = resource_intensive_calculation()
775+
>>> conn.send(BODY)
776+
>>> response = conn.getresponse()
777+
>>> print(response.status, response.reason)
778+
200, OK
779+
668780
.. _httpmessage-objects:
669781

670782
HTTPMessage Objects

‎Doc/library/http.cookies.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,11 @@ Morsel Objects
188188
.. versionchanged:: 3.14
189189
Added support for the :attr:`partitioned` attribute.
190190

191+
.. versionchanged:: next
192+
:meth:`!__setitem__` and :meth:`!__ior__` now raise :exc:`CookieError` if
193+
a value string for any attribute except :attr:`comment` contains the
194+
reserved separator character ``;``. (If :attr:`comment` contains ``;``
195+
it will be escaped in the output.)
191196

192197
.. attribute:: Morsel.value
193198

@@ -253,6 +258,10 @@ Morsel Objects
253258
.. versionchanged:: 3.5
254259
an error is raised for invalid keys.
255260

261+
.. versionchanged:: next
262+
:exc:`CookieError` is now raised if a value string for any attribute
263+
except :attr:`comment` contains the reserved separator character ``;``.
264+
(If :attr:`comment` contains ``;`` it will be escaped in the output.)
256265

257266
.. method:: Morsel.copy(value)
258267

@@ -267,6 +276,10 @@ Morsel Objects
267276
Raise an error if key is not a valid :rfc:`2109` attribute, otherwise
268277
behave the same as :meth:`dict.setdefault`.
269278

279+
.. versionchanged:: next
280+
:exc:`CookieError` is now raised if the value string for any attribute
281+
except :attr:`comment` contains the reserved separator character ``;``.
282+
(If :attr:`comment` contains ``;`` it will be escaped in the output.)
270283

271284
.. _cookie-example:
272285

‎Doc/library/ssl.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ Client socket example with custom context and IPv4::
101101

102102
with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
103103
with context.wrap_socket(sock, server_hostname=hostname) as ssock:
104+
ssock.connect((hostname, 443))
104105
print(ssock.version())
105106

106107

@@ -2236,13 +2237,12 @@ to speed up repeated connections from the same clients.
22362237
The parameter ``server_side`` is a boolean which identifies whether
22372238
server-side or client-side behavior is desired from this socket.
22382239

2239-
For client-side sockets, the context construction is lazy; if the
2240-
underlying socket isn't connected yet, the context construction will be
2241-
performed after :meth:`connect` is called on the socket. For
2242-
server-side sockets, if the socket has no remote peer, it is assumed
2240+
For client-side sockets, if *sock* is not yet connected, the underlying
2241+
SSL object is created when :meth:`~socket.socket.connect` is called.
2242+
For server-side sockets, if the socket has no remote peer, it is assumed
22432243
to be a listening socket, and the server-side SSL wrapping is
22442244
automatically performed on client connections accepted via the
2245-
:meth:`accept` method. The method may raise :exc:`SSLError`.
2245+
:meth:`~socket.socket.accept` method. The method may raise :exc:`SSLError`.
22462246

22472247
On client connections, the optional parameter *server_hostname* specifies
22482248
the hostname of the service which we are connecting to. This allows a

0 commit comments

Comments
 (0)