know of any deficiencies you find in Python.
It can be sometimes faster to fix bugs yourself and contribute patches to
-Python as it streamlines the process and involves less people. Learn how to
+Python as it streamlines the process and involves fewer people. Learn how to
:ref:`contribute <contributing-to-python>`.
Documentation bugs
.. c:macro:: Py_INFINITY
- This macro expands a to constant expression of type :c:expr:`double`, that
+ This macro expands to a constant expression of type :c:expr:`double`, that
represents the positive infinity.
It is equivalent to the :c:macro:`!INFINITY` macro from the C11 standard
.. c:macro:: Py_NAN
- This macro expands a to constant expression of type :c:expr:`double`, that
+ This macro expands to a constant expression of type :c:expr:`double`, that
represents a quiet not-a-number (qNaN) value.
On most platforms, this is equivalent to the :c:macro:`!NAN` macro from
Note that Python will do a best effort at freeing all memory allocated by the Python
interpreter. Therefore, any C-Extension should make sure to correctly clean up all
- of the preveiously allocated PyObjects before using them in subsequent calls to
+ of the previously allocated PyObjects before using them in subsequent calls to
:c:func:`Py_Initialize`. Otherwise it could introduce vulnerabilities and incorrect
behavior.
Get the current interpreter.
- Issue a fatal error if there no :term:`attached thread state`.
+ Issue a fatal error if there is no :term:`attached thread state`.
It cannot return NULL.
.. versionadded:: 3.9
*what* when after any bytecode is processed after which the exception becomes
set within the frame being executed. The effect of this is that as exception
propagation causes the Python stack to unwind, the callback is called upon
- return to each frame as the exception propagates. Only trace functions receives
+ return to each frame as the exception propagates. Only trace functions receive
these events; they are not needed by the profiler.
the tracer function is called. Return ``0`` on success. Set an exception and
return ``-1`` on error.
- Not that tracer functions **must not** create Python objects inside or
+ Note that tracer functions **must not** create Python objects inside or
otherwise the call will be re-entrant. The tracer also **must not** clear
any existing exception or set an exception. A :term:`thread state` will be active
every time the tracer function is called.
Visibility:
-* Public: Can by get by :c:func:`PyConfig_Get` and set by
+* Public: Can be retrieved by :c:func:`PyConfig_Get` and set by
:c:func:`PyConfig_Set`.
-* Read-only: Can by get by :c:func:`PyConfig_Get`, but cannot be set by
+* Read-only: Can be retrieved by :c:func:`PyConfig_Get`, but cannot be set by
:c:func:`PyConfig_Set`.
Most ``PyConfig`` methods :ref:`preinitialize Python <c-preinit>` if needed.
In that case, the Python preinitialization configuration
- (:c:type:`PyPreConfig`) in based on the :c:type:`PyConfig`. If configuration
+ (:c:type:`PyPreConfig`) is based on the :c:type:`PyConfig`. If configuration
fields which are in common with :c:type:`PyPreConfig` are tuned, they must
be set before calling a :c:type:`PyConfig` method:
General utility macros
----------------------
-The following macros common tasks not specific to Python.
+The following macros are for common tasks not specific to Python.
.. c:macro:: Py_UNUSED(arg)
In debug mode, and on unsupported compilers, the macro expands to a call to
:c:func:`Py_FatalError`.
- A use for ``Py_UNREACHABLE()`` is following a call a function that
+ A use for ``Py_UNREACHABLE()`` is following a call to a function that
never returns but that is not declared ``_Noreturn``.
If a code path is very unlikely code but can be reached under exceptional
.. versionchanged:: 3.9
:c:member:`m_traverse`, :c:member:`m_clear` and :c:member:`m_free`
- functions are longer called before the module state is allocated.
+ functions are no longer called before the module state is allocated.
.. _moduledef-dynamic:
These two constants are not used to indicate the calling convention but the
-binding when use with methods of classes. These may not be used for functions
+binding when used with methods of classes. These may not be used for functions
defined for modules. At most one of these flags may be set for any given
method.
objects *globals* and *locals* with the compiler flags specified by
*flags*. *globals* must be a dictionary; *locals* can be any object
that implements the mapping protocol. The parameter *start* specifies
- the start symbol and must one of the :ref:`available start symbols <start-symbols>`.
+ the start symbol and must be one of the :ref:`available start symbols <start-symbols>`.
Returns the result of executing the code as a Python object, or ``NULL`` if an
exception was raised.
* :func:`~threading.RLock` will take no arguments in Python 3.15.
Passing any arguments has been deprecated since Python 3.14,
- as the Python version does not permit any arguments,
+ as the Python version does not permit any arguments,
but the C version allows any number of positional or keyword arguments,
ignoring every argument.
'email.mime.text'
race condition
- A condition of a program where the its behavior
+ A condition of a program where the behavior
depends on the relative timing or ordering of events, particularly in
multi-threaded programs. Race conditions can lead to
:term:`non-deterministic` behavior and bugs that are difficult to
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
- remove more than one flag at a time, *flag* maybe a string of more than
+ remove more than one flag at a time, *flag* may be a string of more than
one character. If "info" contains experimental information rather than
flags, the current "info" is not modified.
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
- remove more than one flag at a time, *flag* maybe a string of more than
+ remove more than one flag at a time, *flag* may be a string of more than
one character.
When an :class:`!mboxMessage` instance is created based upon a
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
- remove more than one flag at a time, *flag* maybe a string of more than
+ remove more than one flag at a time, *flag* may be a string of more than
one character.
When an :class:`!MMDFMessage` instance is created based upon a
.. exception:: Error()
- The based class for all other module-specific exceptions.
+ The base class for all other module-specific exceptions.
.. exception:: NoSuchMailboxError()
Raised when some mailbox-related condition beyond the control of the program
causes it to be unable to proceed, such as when failing to acquire a lock that
- another program already holds a lock, or when a uniquely generated file name
+ another program already holds, or when a uniquely generated file name
already exists.
Set the path of the Python interpreter to use when starting a child process.
(By default :data:`sys.executable` is used). Embedders will probably need to
- do some thing like ::
+ do something like ::
set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
duration of the Pool's work queue. A frequent pattern found in other
systems (such as Apache, mod_wsgi, etc) to free resources held by
workers is to allow a worker within a pool to complete only a set
- amount of work before being exiting, being cleaned up and a new
+ amount of work before exiting, being cleaned up and a new
process spawned to replace the old one. The *maxtasksperchild*
argument to the :class:`Pool` exposes this ability to the end user.
.. versionchanged:: 3.15
Python UTF-8 mode is now enabled by default (:pep:`686`).
- It may be disabled
with by setting :envvar:`PYTHONUTF8=0 <PYTHONUTF8>` as
+ It may be disabled by setting :envvar:`PYTHONUTF8=0 <PYTHONUTF8>` as
an environment variable or by using the :option:`-X utf8=0 <-X>` command line option.
The Python UTF-8 Mode ignores the :term:`locale encoding` and forces the usage
.. warning::
This function is not thread-safe. Calling it while the environment is
- being modified in an other thread is an undefined behavior. Reading from
+ being modified in another thread is an undefined behavior. Reading from
:data:`os.environ` or :data:`os.environb`, or calling :func:`os.getenv`
while reloading, may return an empty result.
except it includes any time that the system is suspended.
The file descriptor's behaviour can be modified by specifying a *flags* value.
- Any of the following variables may used, combined using bitwise OR
+ Any of the following variables may be used, combined using bitwise OR
(the ``|`` operator):
- :const:`TFD_NONBLOCK`
*fd* must be a valid timer file descriptor.
The timer's behaviour can be modified by specifying a *flags* value.
- Any of the following variables may used, combined using bitwise OR
+ Any of the following variables may be used, combined using bitwise OR
(the ``|`` operator):
- :const:`TFD_TIMER_ABSTIME`
Return a two-item tuple of floats (``next_expiration``, ``interval``).
- ``next_expiration`` denotes the relative time until next the timer next fires,
+ ``next_expiration`` denotes the relative time until the timer next fires,
regardless of if the :const:`TFD_TIMER_ABSTIME` flag is set.
``interval`` denotes the timer's interval.
* classes accessible from the top level of a module;
-* instances of such classes whose the result of calling :meth:`~object.__getstate__`
+* instances of such classes for which the result of calling :meth:`~object.__getstate__`
is picklable (see section :ref:`pickle-inst` for details).
Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
.. method:: object.__getnewargs_ex__()
- In protocols 2 and newer, classes that implements the
+ In protocols 2 and newer, classes that implement the
:meth:`__getnewargs_ex__` method can dictate the values passed to the
:meth:`__new__` method upon unpickling. The method must return a pair
``(args, kwargs)`` where *args* is a tuple of positional arguments
...``). The *doctypeName* is provided exactly as presented. The *systemId* and
*publicId* parameters give the system and public identifiers if specified, or
``None`` if omitted. *has_internal_subset* will be true if the document
- contains and internal document declaration subset. This requires Expat version
+ contains an internal document declaration subset. This requires Expat version
1.2 or newer.
print(getrusage(RUSAGE_SELF))
The fields of the return value each describe how a particular system resource
- has been used, e.g. amount of time spent running is user mode or number of times
+ has been used, e.g. amount of time spent running in user mode or number of times
the process was swapped out of main memory. Some values are dependent on the
- clock tick internal, e.g. the amount of memory the process is using.
+ clock tick interval, e.g. the amount of memory the process is using.
For backward compatibility, the return value is also accessible as a tuple of 16
elements.
as the number of bytes of randomness to use.
Otherwise, if no argument is provided, or if the argument is ``None``,
-the ``token_*`` functions uses :const:`DEFAULT_ENTROPY` instead.
+the ``token_*`` functions use :const:`DEFAULT_ENTROPY` instead.
.. data:: DEFAULT_ENTROPY
The minimum number of bytes which can be written without blocking to a pipe
when the pipe has been reported as ready for writing by :func:`~select.select`,
:func:`!poll` or another interface in this module. This doesn't apply
- to other kind of file-like objects such as sockets.
+ to other kinds of file-like objects such as sockets.
This value is guaranteed by POSIX to be at least 512.
implement :meth:`!fileno`, so they can also be used as the argument.
*eventmask* is an optional bitmask describing the type of events you want to
- check for. The constants are the same that with :c:func:`!poll`
+ check for. The constants are the same as with :c:func:`!poll`
object. The default value is a combination of the constants :const:`POLLIN`,
:const:`POLLPRI`, and :const:`POLLOUT`.
.. method:: devpoll.modify(fd[, eventmask])
This method does an :meth:`unregister` followed by a
- :meth:`register`. It is (a bit) more efficient that doing the same
+ :meth:`register`. It is (a bit) more efficient than doing the same
explicitly.
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_DELETE` | Removes an event from the queue |
+---------------------------+---------------------------------------------+
- | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event |
+ | :const:`KQ_EV_ENABLE` | Permits control() to return the event |
+---------------------------+---------------------------------------------+
- | :const:`KQ_EV_DISABLE` | Disablesevent |
+ | :const:`KQ_EV_DISABLE` | Disables event |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_ONESHOT` | Removes event after first occurrence |
+---------------------------+---------------------------------------------+
In the following, *events* is a bitwise mask indicating which I/O events should
-be waited for on a given file object. It can be a combination of the modules
+be waited for on a given file object. It can be a combination of the module's
constants below:
+-----------------------+-----------------------------------------------+
:term:`bytes-like object`; the *protocol* value may be ignored by the
serializer.
- The *deserializer* argument must be callable which takes a serialized object
+ The *deserializer* argument must be a callable which takes a serialized object
given as a :class:`bytes` object and returns the corresponding object.
A :exc:`ShelveError` is raised if *serializer* is given but *deserializer*
to load a shelf from an untrusted source. Like with pickle, loading a shelf
can execute arbitrary code.
-Shelf objects support most of methods and operations supported by dictionaries
+Shelf objects support most of the methods and operations supported by dictionaries
(except copying, constructors and operators ``|`` and ``|=``). This eases the
transition from dictionary based scripts to those requiring persistent storage.
Parsing Rules
-------------
-When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
+When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey the
following rules.
* Quote characters are not recognized within words (``Do"Not"Separate`` is
* It's not possible to parse empty strings, even if quoted.
-When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
+When operating in POSIX mode, :class:`~shlex.shlex` will try to obey the
following parsing rules.
* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
* Enclosing characters in quotes which are part of
:attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
of all characters within the quotes, with the exception of the characters
- mentioned in :attr:`~shlex.escape`. The escape characters retain its
+ mentioned in :attr:`~shlex.escape`. The escape characters retain their
special meaning only when followed by the quote in use, or the escape
character itself. Otherwise the escape character will be considered a
normal character.
On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB
instead of 64 KiB) and a :func:`memoryview`-based variant of
-:func:`shutil.copyfileobj` is used, which is still reads and writes in a loop.
+:func:`shutil.copyfileobj` is used, which still reads and writes in a loop.
:func:`shutil.copy2` uses the native ``CopyFile2`` call on Windows, which is the most
efficient method, supports copy-on-write, and preserves metadata.
If the fast-copy operation fails and no data was written in the destination
-file then shutil will silently fallback on using less efficient
+file then shutil will silently fall back to less efficient
:func:`copyfileobj` function internally.
.. versionchanged:: 3.8
A Python signal handler does not get executed inside the low-level (C) signal
handler. Instead, the low-level signal handler sets a flag which tells the
:term:`virtual machine` to execute the corresponding Python signal handler
-at a later point(for example at the next :term:`bytecode` instruction).
+at a later point (for example, at the next :term:`bytecode` instruction).
This has consequences:
* It makes little sense to catch synchronous errors like :const:`SIGFPE` or
.. class:: Handlers
- :class:`enum.IntEnum` collection the constants :const:`SIG_DFL` and :const:`SIG_IGN`.
+ :class:`enum.IntEnum` collection of the constants :const:`SIG_DFL` and :const:`SIG_IGN`.
.. versionadded:: 3.5
.. class:: Sigmasks
- :class:`enum.IntEnum` collection the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`.
+ :class:`enum.IntEnum` collection of the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`.
.. availability:: Unix.
It is typically created by a system administrator in the site-packages
directory. If this import fails with an :exc:`ImportError` or its subclass
exception, and the exception's :attr:`~ImportError.name`
-attribute equals to ``'sitecustomize'``,
+attribute equals ``'sitecustomize'``,
it is silently ignored. If Python is started without output streams available, as
with :file:`pythonw.exe` on Windows (which is used by default to start IDLE),
attempted output from :mod:`!sitecustomize` is ignored. Any other exception
user site-packages directory (see below), which is part of ``sys.path`` unless
disabled by :option:`-s`. If this import fails with an :exc:`ImportError` or
its subclass exception, and the exception's :attr:`~ImportError.name`
-attribute equals to ``'usercustomize'``, it is silently ignored.
+attribute equals ``'usercustomize'``, it is silently ignored.
Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
empty, and the path manipulations are skipped; however the import of
On systems that support :mod:`readline`, this module will also import and
configure the :mod:`rlcompleter` module, if Python is started in
:ref:`interactive mode <tut-interactive>` and without the :option:`-S` option.
-The default behavior is enable tab-completion and to use
+The default behavior is to enable tab completion and to use
:file:`~/.python_history` as the history save file. To disable it, delete (or
override) the :data:`sys.__interactivehook__` attribute in your
:mod:`sitecustomize` or :mod:`usercustomize` module or your
``'can0'``. The network interface name ``''`` can be used to receive packets
from all network interfaces of this family.
- - :const:`CAN_ISOTP` protocol require a tuple ``(interface, rx_addr, tx_addr)``
+ - :const:`CAN_ISOTP` protocol requires a tuple ``(interface, rx_addr, tx_addr)``
where both additional parameters are unsigned long integer that represent a
CAN identifier (standard or extended).
- - :const:`CAN_J1939` protocol require a tuple ``(interface, name, pgn, addr)``
+ - :const:`CAN_J1939` protocol requires a tuple ``(interface, name, pgn, addr)``
where additional parameters are 64-bit unsigned integer representing the
ECU name, a 32-bit unsigned integer representing the Parameter Group Number
(PGN), and an 8-bit integer representing the address.
.. function:: close(fd)
Close a socket file descriptor. This is like :func:`os.close`, but for
- sockets. On some platforms (most noticeable Windows) :func:`os.close`
+ sockets. On some platforms (most notably Windows) :func:`os.close`
does not work for socket file descriptors.
.. versionadded:: 3.7
address family --- see above.)
If the connection is interrupted by a signal, the method waits until the
- connection completes, or raise a :exc:`TimeoutError` on timeout, if the
+ connection completes, or raises a :exc:`TimeoutError` on timeout, if the
signal handler doesn't raise an exception and the socket is blocking or has
a timeout. For non-blocking sockets, the method raises an
:exc:`InterruptedError` exception if the connection is interrupted by a
Set the value of the given socket option (see the Unix manual page
:manpage:`setsockopt(2)`). The needed symbolic constants are defined in this
module (:ref:`!SO_\* etc. <socket-unix-constants>`). The value can be an integer,
- ``None`` or a :term:`bytes-like object` representing a buffer. In the later
+ ``None`` or a :term:`bytes-like object` representing a buffer. In the latter
case it is up to the caller to ensure that the bytestring contains the
proper bits (see the optional built-in module :mod:`struct` for a way to
encode C structures as bytestrings). When *value* is set to ``None``,
- *optlen* argument is required. It's equivalent to call :c:func:`setsockopt` C
+ *optlen* argument is required. It's equivalent to calling :c:func:`setsockopt` C
function with ``optval=NULL`` and ``optlen=optlen``.
.. versionchanged:: 3.5
Set it to any combination (using ``|``, bitwise or) of
:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`
to enable this.
- Column names takes precedence over declared types if both flags are set.
+ Column names take precedence over declared types if both flags are set.
By default (``0``), type detection is disabled.
:param isolation_level:
in the range 0--127, and produce undefined results otherwise. Some systems
have a convention for assigning specific meanings to specific exit codes, but
these are generally underdeveloped; Unix programs generally use 2 for command
- line syntax errors and 1 for all other kind of errors. If another type of
+ line syntax errors and 1 for all other kinds of errors. If another type of
object is passed, ``None`` is equivalent to passing zero, and any other
object is printed to :data:`stderr` and results in an exit code of 1. In
particular, ``sys.exit("some error message")`` is a quick way to exit a
Display the version of the module and exit.
.. versionadded:: 3.8
- Added ``--module`` option that allows to run an executable module.
+ Added ``--module`` option that allows running an executable module.
Main options
^^^^^^^^^^^^
If *cumulative* is ``True``, cumulate size and count of memory blocks of
all frames of the traceback of a trace, not only the most recent frame.
- The cumulative mode can only be used with *key_type* equals to
+ The cumulative mode can only be used with *key_type* equal to
``'filename'`` and ``'lineno'``.
The result is sorted from the biggest to the smallest by:
When a snapshot is taken, tracebacks of traces are limited to
:func:`get_traceback_limit` frames. See the :func:`take_snapshot` function.
The original number of frames of the traceback is stored in the
- :attr:`Traceback.total_nframe` attribute. That allows to know if a traceback
+ :attr:`Traceback.total_nframe` attribute. That allows one to know if a traceback
has been truncated by the traceback limit.
- The :attr:`Trace.traceback` attribute is an instance of :class:`Traceback`
- instance.
+ The :attr:`Trace.traceback` attribute is a :class:`Traceback` instance.
.. versionchanged:: 3.7
Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.
def __len__(self) -> int: ...
def __iter__(self) -> Iterator[int]: ...
-:pep:`544` allows to solve this problem by allowing users to write
+:pep:`544` solves this problem by allowing users to write
the above code without explicit base classes in the class definition,
allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized``
and ``Iterable[int]`` by static type checkers. This is known as
What the :func:`parse` and :func:`parseString` functions do is connect an XML
parser with a "DOM builder" that can accept parse events from any SAX parser and
-convert them into a DOM tree. The name of the functions are perhaps misleading,
+convert them into a DOM tree. The names of the functions are perhaps misleading,
but are easy to grasp when learning the interfaces. The parsing of the document
will be completed before these functions return; it's simply that these
functions do not provide a parser implementation themselves.
Enabling the *allow_dotted_names* option allows intruders to access your
module's global variables and may allow intruders to execute arbitrary code on
- your machine. Only use this example only within a secure, closed network.
+ your machine. Only use this example within a secure, closed network.
::
'Buddy'
As discussed in :ref:`tut-object`, shared data can have possibly surprising
-effects with involving :term:`mutable` objects such as lists and dictionaries.
+effects involving :term:`mutable` objects such as lists and dictionaries.
For example, the *tricks* list in the following code should not be used as a
class variable because just a single list would be shared by all *Dog*
instances::
6
Later we will see more functions that return iterables and take iterables as
-arguments. In chapter :ref:`tut-structures`, we will discuss in more detail about
-:func:`list`.
+arguments. In chapter :ref:`tut-structures`, we will discuss :func:`list` in more
+detail.
.. _tut-break:
``False`` and ``None`` are compared by identity.
- Patterns may use named constants. These must be dotted names
- to prevent them from being interpreted as capture variable::
+ to prevent them from being interpreted as capture variables::
from enum import Enum
class Color(Enum):
Now that you are about to write longer, more complex pieces of Python, it is a
good time to talk about *coding style*. Most languages can be written (or more
-concise, *formatted*) in different styles; some are more readable than others.
+concisely, *formatted*) in different styles; some are more readable than others.
Making it easy for others to read your code is always a good idea, and adopting
a nice coding style helps tremendously for that.
------------------------------------------
The section on :ref:`tut-unpacking-arguments` describes the use of ``*`` to
-"unpack" the elements of an iterable object, providing each one seperately as
+"unpack" the elements of an iterable object, providing each one separately as
an argument to a function. Unpacking can also be used in other contexts, for
example, when creating lists. When specifying elements of a list, prefixing an
expression by a ``*`` will unpack the result of that expression, adding each of
.. rubric:: Footnotes
-.. [#] "Cheese Shop" is a Monty Python's sketch: a customer enters a cheese shop,
+.. [#] "Cheese Shop" is a Monty Python sketch: a customer enters a cheese shop,
but whatever cheese he asks for, the clerk says it's missing.
projects / thirdparty / Python / cpython.git / commitdiff
