Skip to content

Commit fbb06a7

Browse files
committed
Deploying to gh-pages from @ ddf3315 🚀
1 parent 519b8d5 commit fbb06a7

File tree

546 files changed

+2293
-1696
lines changed

Some content is hidden

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

546 files changed

+2293
-1696
lines changed

.buildinfo

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
22
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: 106f195981453e29bee0878755abb3cc
3+
config: 0f6df315d03b26c465022e5afc65623d
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

_images/logging_flow.png

-21.4 KB
Binary file not shown.

_sources/c-api/init.rst.txt

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -388,9 +388,16 @@ Initializing and finalizing the interpreter
388388
:c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
389389
the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory
390390
allocated by the Python interpreter. This is a no-op when called for a second
391-
time (without calling :c:func:`Py_Initialize` again first). Normally the
392-
return value is ``0``. If there were errors during finalization
393-
(flushing buffered data), ``-1`` is returned.
391+
time (without calling :c:func:`Py_Initialize` again first).
392+
393+
Since this is the reverse of :c:func:`Py_Initialize`, it should be called
394+
in the same thread with the same interpreter active. That means
395+
the main thread and the main interpreter.
396+
This should never be called while :c:func:`Py_RunMain` is running.
397+
398+
Normally the return value is ``0``.
399+
If there were errors during finalization (flushing buffered data),
400+
``-1`` is returned.
394401
395402
This function is provided for a number of reasons. An embedding application
396403
might want to restart Python without having to restart the application itself.

_sources/howto/enum.rst.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1129,6 +1129,14 @@ the following are true:
11291129
>>> (Color.RED | Color.GREEN).name
11301130
'RED|GREEN'
11311131

1132+
>>> class Perm(IntFlag):
1133+
... R = 4
1134+
... W = 2
1135+
... X = 1
1136+
...
1137+
>>> (Perm.R & Perm.W).name is None # effectively Perm(0)
1138+
True
1139+
11321140
- multi-bit flags, aka aliases, can be returned from operations::
11331141

11341142
>>> Color.RED | Color.BLUE

_sources/howto/logging.rst.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -381,8 +381,8 @@ Logging Flow
381381
The flow of log event information in loggers and handlers is illustrated in the
382382
following diagram.
383383

384-
.. image:: logging_flow.png
385-
:class: invert-in-dark-mode
384+
.. raw:: html
385+
:file: logging_flow.svg
386386

387387
Loggers
388388
^^^^^^^

_sources/library/asyncio-eventloop.rst.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1139,6 +1139,14 @@ DNS
11391139

11401140
Asynchronous version of :meth:`socket.getnameinfo`.
11411141

1142+
.. note::
1143+
Both *getaddrinfo* and *getnameinfo* internally utilize their synchronous
1144+
versions through the loop's default thread pool executor.
1145+
When this executor is saturated, these methods may experience delays,
1146+
which higher-level networking libraries may report as increased timeouts.
1147+
To mitigate this, consider using a custom executor for other user tasks,
1148+
or setting a default executor with a larger number of workers.
1149+
11421150
.. versionchanged:: 3.7
11431151
Both *getaddrinfo* and *getnameinfo* methods were always documented
11441152
to return a coroutine, but prior to Python 3.7 they were, in fact,

_sources/library/inspect.rst.txt

Lines changed: 227 additions & 214 deletions
Large diffs are not rendered by default.

_sources/library/pathlib.rst.txt

Lines changed: 40 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1380,30 +1380,19 @@ Renaming and deleting
13801380
Remove this directory. The directory must be empty.
13811381

13821382

1383-
Other methods
1384-
^^^^^^^^^^^^^
1385-
1386-
.. classmethod:: Path.cwd()
1387-
1388-
Return a new path object representing the current directory (as returned
1389-
by :func:`os.getcwd`)::
1390-
1391-
>>> Path.cwd()
1392-
PosixPath('/home/antoine/pathlib')
1393-
1383+
Ownership and permissions
1384+
^^^^^^^^^^^^^^^^^^^^^^^^^
13941385

1395-
.. classmethod:: Path.home()
1386+
.. method:: Path.owner()
13961387

1397-
Return a new path object representing the user's home directory (as
1398-
returned by :func:`os.path.expanduser` with ``~`` construct). If the home
1399-
directory can't be resolved, :exc:`RuntimeError` is raised.
1388+
Return the name of the user owning the file. :exc:`KeyError` is raised
1389+
if the file's user identifier (UID) isn't found in the system database.
14001390

1401-
::
14021391

1403-
>>> Path.home()
1404-
PosixPath('/home/antoine')
1392+
.. method:: Path.group()
14051393

1406-
.. versionadded:: 3.5
1394+
Return the name of the group owning the file. :exc:`KeyError` is raised
1395+
if the file's group identifier (GID) isn't found in the system database.
14071396

14081397

14091398
.. method:: Path.chmod(mode, *, follow_symlinks=True)
@@ -1427,37 +1416,51 @@ Other methods
14271416
The *follow_symlinks* parameter was added.
14281417

14291418

1430-
.. method:: Path.expanduser()
1419+
.. method:: Path.lchmod(mode)
14311420

1432-
Return a new path with expanded ``~`` and ``~user`` constructs,
1433-
as returned by :meth:`os.path.expanduser`. If a home directory can't be
1434-
resolved, :exc:`RuntimeError` is raised.
1421+
Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
1422+
symbolic link's mode is changed rather than its target's.
14351423

1436-
::
14371424

1438-
>>> p = PosixPath('~/films/Monty Python')
1439-
>>> p.expanduser()
1440-
PosixPath('/home/eric/films/Monty Python')
1425+
Other methods
1426+
^^^^^^^^^^^^^
14411427

1442-
.. versionadded:: 3.5
1428+
.. classmethod:: Path.cwd()
14431429

1430+
Return a new path object representing the current directory (as returned
1431+
by :func:`os.getcwd`)::
14441432

1445-
.. method:: Path.group()
1433+
>>> Path.cwd()
1434+
PosixPath('/home/antoine/pathlib')
14461435

1447-
Return the name of the group owning the file. :exc:`KeyError` is raised
1448-
if the file's gid isn't found in the system database.
14491436

1437+
.. classmethod:: Path.home()
14501438

1451-
.. method:: Path.lchmod(mode)
1439+
Return a new path object representing the user's home directory (as
1440+
returned by :func:`os.path.expanduser` with ``~`` construct). If the home
1441+
directory can't be resolved, :exc:`RuntimeError` is raised.
14521442

1453-
Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
1454-
symbolic link's mode is changed rather than its target's.
1443+
::
1444+
1445+
>>> Path.home()
1446+
PosixPath('/home/antoine')
14551447

1448+
.. versionadded:: 3.5
14561449

1457-
.. method:: Path.owner()
14581450

1459-
Return the name of the user owning the file. :exc:`KeyError` is raised
1460-
if the file's uid isn't found in the system database.
1451+
.. method:: Path.expanduser()
1452+
1453+
Return a new path with expanded ``~`` and ``~user`` constructs,
1454+
as returned by :meth:`os.path.expanduser`. If a home directory can't be
1455+
resolved, :exc:`RuntimeError` is raised.
1456+
1457+
::
1458+
1459+
>>> p = PosixPath('~/films/Monty Python')
1460+
>>> p.expanduser()
1461+
PosixPath('/home/eric/films/Monty Python')
1462+
1463+
.. versionadded:: 3.5
14611464

14621465

14631466
.. method:: Path.readlink()

_sources/library/pprint.rst.txt

Lines changed: 89 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -35,52 +35,85 @@ Dictionaries are sorted by key before the display is computed.
3535
Functions
3636
---------
3737

38-
.. function:: pp(object, *args, sort_dicts=False, **kwargs)
39-
40-
Prints the formatted representation of *object* followed by a newline.
41-
If *sort_dicts* is false (the default), dictionaries will be displayed with
42-
their keys in insertion order, otherwise the dict keys will be sorted.
43-
*args* and *kwargs* will be passed to :func:`~pprint.pprint` as formatting
44-
parameters.
45-
46-
>>> import pprint
47-
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
48-
>>> stuff.insert(0, stuff)
49-
>>> pprint.pp(stuff)
50-
[<Recursion on list with id=...>,
51-
'spam',
52-
'eggs',
53-
'lumberjack',
54-
'knights',
55-
'ni']
38+
.. function:: pp(object, stream=None, indent=1, width=80, depth=None, *, \
39+
compact=False, sort_dicts=False, underscore_numbers=False)
40+
41+
Prints the formatted representation of *object*, followed by a newline.
42+
This function may be used in the interactive interpreter
43+
instead of the :func:`print` function for inspecting values.
44+
Tip: you can reassign ``print = pprint.pp`` for use within a scope.
45+
46+
:param object:
47+
The object to be printed.
48+
49+
:param stream:
50+
A file-like object to which the output will be written
51+
by calling its :meth:`!write` method.
52+
If ``None`` (the default), :data:`sys.stdout` is used.
53+
:type stream: :term:`file-like object` | None
54+
55+
:param int indent:
56+
The amount of indentation added for each nesting level.
57+
58+
:param int width:
59+
The desired maximum number of characters per line in the output.
60+
If a structure cannot be formatted within the width constraint,
61+
a best effort will be made.
62+
63+
:param depth:
64+
The number of nesting levels which may be printed.
65+
If the data structure being printed is too deep,
66+
the next contained level is replaced by ``...``.
67+
If ``None`` (the default), there is no constraint
68+
on the depth of the objects being formatted.
69+
:type depth: int | None
70+
71+
:param bool compact:
72+
Control the way long :term:`sequences <sequence>` are formatted.
73+
If ``False`` (the default),
74+
each item of a sequence will be formatted on a separate line,
75+
otherwise as many items as will fit within the *width*
76+
will be formatted on each output line.
77+
78+
:param bool sort_dicts:
79+
If ``True``, dictionaries will be formatted with
80+
their keys sorted, otherwise
81+
they will be displayed in insertion order (the default).
82+
83+
:param bool underscore_numbers:
84+
If ``True``,
85+
integers will be formatted with the ``_`` character for a thousands separator,
86+
otherwise underscores are not displayed (the default).
87+
88+
>>> import pprint
89+
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
90+
>>> stuff.insert(0, stuff)
91+
>>> pprint.pp(stuff)
92+
[<Recursion on list with id=...>,
93+
'spam',
94+
'eggs',
95+
'lumberjack',
96+
'knights',
97+
'ni']
5698

5799
.. versionadded:: 3.8
58100

59101

60102
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
61103
compact=False, sort_dicts=True, underscore_numbers=False)
62104

63-
Prints the formatted representation of *object* on *stream*, followed by a
64-
newline. If *stream* is ``None``, :data:`sys.stdout` is used. This may be used
65-
in the interactive interpreter instead of the :func:`print` function for
66-
inspecting values (you can even reassign ``print = pprint.pprint`` for use
67-
within a scope).
68-
69-
The configuration parameters *stream*, *indent*, *width*, *depth*,
70-
*compact*, *sort_dicts* and *underscore_numbers* are passed to the
71-
:class:`PrettyPrinter` constructor and their meanings are as
72-
described in its documentation below.
105+
Alias for :func:`~pprint.pp` with *sort_dicts* set to ``True`` by default,
106+
which would automatically sort the dictionaries' keys,
107+
you might want to use :func:`~pprint.pp` instead where it is ``False`` by default.
73108

74-
Note that *sort_dicts* is ``True`` by default and you might want to use
75-
:func:`~pprint.pp` instead where it is ``False`` by default.
76109

77110
.. function:: pformat(object, indent=1, width=80, depth=None, *, \
78111
compact=False, sort_dicts=True, underscore_numbers=False)
79112

80113
Return the formatted representation of *object* as a string. *indent*,
81114
*width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
82115
passed to the :class:`PrettyPrinter` constructor as formatting parameters
83-
and their meanings are as described in its documentation below.
116+
and their meanings are as described in the documentation above.
84117

85118

86119
.. function:: isreadable(object)
@@ -119,51 +152,39 @@ Functions
119152
PrettyPrinter Objects
120153
---------------------
121154

122-
This module defines one class:
123-
124-
.. First the implementation class:
125-
126-
127155
.. index:: single: ...; placeholder
128156

129157
.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
130158
compact=False, sort_dicts=True, underscore_numbers=False)
131159

132-
Construct a :class:`PrettyPrinter` instance. This constructor understands
133-
several keyword parameters.
134-
135-
*stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to
136-
which the output will be written by calling its :meth:`!write` method.
137-
If both *stream* and :data:`!sys.stdout` are ``None``, then
138-
:meth:`~PrettyPrinter.pprint` silently returns.
160+
Construct a :class:`PrettyPrinter` instance.
139161

140-
Other values configure the manner in which nesting of complex data
141-
structures is displayed.
162+
Arguments have the same meaning as for :func:`~pprint.pp`.
163+
Note that they are in a different order, and that *sort_dicts* defaults to ``True``.
142164

143-
*indent* (default 1) specifies the amount of indentation added for
144-
each nesting level.
145-
146-
*depth* controls the number of nesting levels which may be printed; if
147-
the data structure being printed is too deep, the next contained level
148-
is replaced by ``...``. By default, there is no constraint on the
149-
depth of the objects being formatted.
150-
151-
*width* (default 80) specifies the desired maximum number of characters per
152-
line in the output. If a structure cannot be formatted within the width
153-
constraint, a best effort will be made.
154-
155-
*compact* impacts the way that long sequences (lists, tuples, sets, etc)
156-
are formatted. If *compact* is false (the default) then each item of a
157-
sequence will be formatted on a separate line. If *compact* is true, as
158-
many items as will fit within the *width* will be formatted on each output
159-
line.
160-
161-
If *sort_dicts* is true (the default), dictionaries will be formatted with
162-
their keys sorted, otherwise they will display in insertion order.
165+
>>> import pprint
166+
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
167+
>>> stuff.insert(0, stuff[:])
168+
>>> pp = pprint.PrettyPrinter(indent=4)
169+
>>> pp.pprint(stuff)
170+
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
171+
'spam',
172+
'eggs',
173+
'lumberjack',
174+
'knights',
175+
'ni']
176+
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
177+
>>> pp.pprint(stuff)
178+
[['spam', 'eggs', 'lumberjack',
179+
'knights', 'ni'],
180+
'spam', 'eggs', 'lumberjack', 'knights',
181+
'ni']
182+
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
183+
... ('parrot', ('fresh fruit',))))))))
184+
>>> pp = pprint.PrettyPrinter(depth=6)
185+
>>> pp.pprint(tup)
186+
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
163187

164-
If *underscore_numbers* is true, integers will be formatted with the
165-
``_`` character for a thousands separator, otherwise underscores are not
166-
displayed (the default).
167188

168189
.. versionchanged:: 3.4
169190
Added the *compact* parameter.
@@ -177,29 +198,6 @@ This module defines one class:
177198
.. versionchanged:: 3.11
178199
No longer attempts to write to :data:`!sys.stdout` if it is ``None``.
179200

180-
>>> import pprint
181-
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
182-
>>> stuff.insert(0, stuff[:])
183-
>>> pp = pprint.PrettyPrinter(indent=4)
184-
>>> pp.pprint(stuff)
185-
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
186-
'spam',
187-
'eggs',
188-
'lumberjack',
189-
'knights',
190-
'ni']
191-
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
192-
>>> pp.pprint(stuff)
193-
[['spam', 'eggs', 'lumberjack',
194-
'knights', 'ni'],
195-
'spam', 'eggs', 'lumberjack', 'knights',
196-
'ni']
197-
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
198-
... ('parrot', ('fresh fruit',))))))))
199-
>>> pp = pprint.PrettyPrinter(depth=6)
200-
>>> pp.pprint(tup)
201-
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
202-
203201

204202
:class:`PrettyPrinter` instances have the following methods:
205203

0 commit comments

Comments
 (0)