[Python-checkins] gh-118508: Clarify which characters are matched by `\s` (#119155)
https://github.com/python/cpython/commit/22fdb8cf899d2dd29f2ac0bf61309af6809719fb commit: 22fdb8cf899d2dd29f2ac0bf61309af6809719fb branch: main author: Nice Zombies committer: nedbat date: 2024-09-02T07:48:15-04:00 summary: gh-118508: Clarify which characters are matched by `\s` (#119155) Clarify re syntax files: M Doc/library/re.rst diff --git a/Doc/library/re.rst b/Doc/library/re.rst index cc979fe66f7fe9..efb2722f18038f 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -600,10 +600,9 @@ character ``'$'``. ``\s`` For Unicode (str) patterns: - Matches Unicode whitespace characters (which includes - ``[ \t\n\r\f\v]``, and also many other characters, for example the - non-breaking spaces mandated by typography rules in many - languages). + Matches Unicode whitespace characters (as defined by :py:meth:`str.isspace`). + This includes ``[ \t\n\r\f\v]``, and also many other characters, for example the + non-breaking spaces mandated by typography rules in many languages. Matches ``[ \t\n\r\f\v]`` if the :py:const:`~re.ASCII` flag is used. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] Prefer "similar" over "equivalent" in tutorial (#125343)
https://github.com/python/cpython/commit/4a2282b0679bbf7b7fbd36aae1b1565145238961 commit: 4a2282b0679bbf7b7fbd36aae1b1565145238961 branch: main author: Stephen Rosen committer: nedbat date: 2024-10-12T16:21:55-04:00 summary: Prefer "similar" over "equivalent" in tutorial (#125343) In the datastructures tutorial doc, some operations are described as "equivalent to" others. This has led to some user-confusion -- at least in the Discourse forums -- about cases in which the operations differ. This change doesn't systematically eliminate the word "equivalent" from the tutorial. It just substitutes "similar to" in several cases in which "equivalent to" could mislead users into expecting exact equivalence. files: M Doc/tutorial/datastructures.rst diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst index 73f17adeea72de..31941bc112a135 100644 --- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -19,13 +19,13 @@ objects: .. method:: list.append(x) :noindex: - Add an item to the end of the list. Equivalent to ``a[len(a):] = [x]``. + Add an item to the end of the list. Similar to ``a[len(a):] = [x]``. .. method:: list.extend(iterable) :noindex: - Extend the list by appending all the items from the iterable. Equivalent to + Extend the list by appending all the items from the iterable. Similar to ``a[len(a):] = iterable``. @@ -56,7 +56,7 @@ objects: .. method:: list.clear() :noindex: - Remove all items from the list. Equivalent to ``del a[:]``. + Remove all items from the list. Similar to ``del a[:]``. .. method:: list.index(x[, start[, end]]) @@ -93,7 +93,7 @@ objects: .. method:: list.copy() :noindex: - Return a shallow copy of the list. Equivalent to ``a[:]``. + Return a shallow copy of the list. Similar to ``a[:]``. An example that uses most of the list methods:: ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] Docs: make a tutorial example more precise (#125066)
https://github.com/python/cpython/commit/6e3c70c61bf961e55e9912a31ca11f61c8e2cd0c
commit: 6e3c70c61bf961e55e9912a31ca11f61c8e2cd0c
branch: main
author: Ned Batchelder
committer: nedbat
date: 2024-10-07T19:41:13-04:00
summary:
Docs: make a tutorial example more precise (#125066)
Based on discussion here:
https://discuss.python.org/t/omission-in-the-documentation/66816
files:
M Doc/tutorial/introduction.rst
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index 054bac59c955d5..65e3b1938bca9c 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -197,21 +197,19 @@ and workarounds.
String literals can span multiple lines. One way is using triple-quotes:
``"""..."""`` or ``'''...'''``. End of lines are automatically
included in the string, but it's possible to prevent this by adding a ``\`` at
-the end of the line. The following example::
-
- print("""\
+the end of the line. In the following example, the initial newline is not
+included::
+
+ >>> print("""\
+ ... Usage: thingy [OPTIONS]
+ ... -hDisplay this usage message
+ ... -H hostname Hostname to connect to
+ ... """)
Usage: thingy [OPTIONS]
-hDisplay this usage message
-H hostname Hostname to connect to
- """)
-
-produces the following output (note that the initial newline is not included):
-.. code-block:: text
-
- Usage: thingy [OPTIONS]
--hDisplay this usage message
--H hostname Hostname to connect to
+ >>>
Strings can be concatenated (glued together) with the ``+`` operator, and
repeated with ``*``::
___
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
[Python-checkins] docs: restore an anchor to for/else (#126154)
https://github.com/python/cpython/commit/2d9d10179ff3f13029bf4430e62c455a839987ca commit: 2d9d10179ff3f13029bf4430e62c455a839987ca branch: main author: Ned Batchelder committer: nedbat date: 2024-10-29T20:11:50-04:00 summary: docs: restore an anchor to for/else (#126154) files: M Doc/tutorial/controlflow.rst diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index b830ce94ba4f47..8261bbdbfb7a01 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -196,6 +196,7 @@ iteration of the loop:: Found an odd number 9 .. _tut-for-else: +.. _break-and-continue-statements-and-else-clauses-on-loops: :keyword:`!else` Clauses on Loops = ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] Docs: re-create pages for removed modules to document their removal. (#126622)
https://github.com/python/cpython/commit/036930d84409d0725a4ab95fb976f74d1698c41f commit: 036930d84409d0725a4ab95fb976f74d1698c41f branch: main author: Ned Batchelder committer: nedbat date: 2024-11-11T17:49:48-05:00 summary: Docs: re-create pages for removed modules to document their removal. (#126622) Will also need to change the redirects that were created here: https://github.com/python/psf-salt/pull/521/files files: A Doc/library/aifc.rst A Doc/library/asynchat.rst A Doc/library/asyncore.rst A Doc/library/audioop.rst A Doc/library/cgi.rst A Doc/library/cgitb.rst A Doc/library/chunk.rst A Doc/library/crypt.rst A Doc/library/distutils.rst A Doc/library/imghdr.rst A Doc/library/imp.rst A Doc/library/mailcap.rst A Doc/library/msilib.rst A Doc/library/nis.rst A Doc/library/nntplib.rst A Doc/library/ossaudiodev.rst A Doc/library/pipes.rst A Doc/library/removed.rst A Doc/library/smtpd.rst A Doc/library/sndhdr.rst A Doc/library/spwd.rst A Doc/library/sunau.rst A Doc/library/telnetlib.rst A Doc/library/uu.rst A Doc/library/xdrlib.rst A Misc/NEWS.d/next/Documentation/2024-11-09-19-43-10.gh-issue-126622.YacfDc.rst M Doc/library/index.rst M Doc/whatsnew/3.12.rst diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst new file mode 100644 index 00..a756d679036ecb --- /dev/null +++ b/Doc/library/aifc.rst @@ -0,0 +1,15 @@ +:mod:`!aifc` --- Read and write AIFF and AIFC files +=== + +.. module:: aifc + :synopsis: Removed in 3.13. + :deprecated: + +.. deprecated-removed:: 3.11 3.13 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.13 ` after +being deprecated in Python 3.11. The removal was decided in :pep:`594`. + +The last version of Python that provided the :mod:`!aifc` module was +`Python 3.12 <https://docs.python.org/3.12/library/aifc.html>`_. diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst new file mode 100644 index 00..5e5c3a99fe66f1 --- /dev/null +++ b/Doc/library/asynchat.rst @@ -0,0 +1,17 @@ +:mod:`!asynchat` --- Asynchronous socket command/response handler += + +.. module:: asynchat + :synopsis: Removed in 3.12. + :deprecated: + +.. deprecated-removed:: 3.6 3.12 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.12 ` after +being deprecated in Python 3.6. The removal was decided in :pep:`594`. + +Applications should use the :mod:`asyncio` module instead. + +The last version of Python that provided the :mod:`!asynchat` module was +`Python 3.11 <https://docs.python.org/3.11/library/asynchat.html>`_. diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst new file mode 100644 index 00..22c9881c3cca36 --- /dev/null +++ b/Doc/library/asyncore.rst @@ -0,0 +1,17 @@ +:mod:`!asyncore` --- Asynchronous socket handler + + +.. module:: asyncore + :synopsis: Removed in 3.12. + :deprecated: + +.. deprecated-removed:: 3.6 3.12 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.12 ` after +being deprecated in Python 3.6. The removal was decided in :pep:`594`. + +Applications should use the :mod:`asyncio` module instead. + +The last version of Python that provided the :mod:`!asyncore` module was +`Python 3.11 <https://docs.python.org/3.11/library/asyncore.html>`_. diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst new file mode 100644 index 00..3bc580b0bd3433 --- /dev/null +++ b/Doc/library/audioop.rst @@ -0,0 +1,15 @@ +:mod:`!audioop` --- Manipulate raw audio data += + +.. module:: audioop + :synopsis: Removed in 3.13. + :deprecated: + +.. deprecated-removed:: 3.11 3.13 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.13 ` after +being deprecated in Python 3.11. The removal was decided in :pep:`594`. + +The last version of Python that provided the :mod:`!audioop` module was +`Python 3.12 <https://docs.python.org/3.12/library/audioop.html>`_. diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst new file mode 100644 index 00..f9108fa954a906 --- /dev/null +++ b/Doc/library/cgi.rst @@ -0,0 +1,19 @@ +:mod:`!cgi` --- Common Gateway Interface support + + +.. module:: cgi + :synopsis: Removed in 3.13. + :deprecated: + +.. deprecated-removed:: 3.11 3.13 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.13 ` after +being deprecated in Python 3.11. The removal was decided in :pep:`594`. + +A fork of the module on PyPI can be used instead: :pypi:`legacy-cgi`. +This is a copy of the cgi module, no longer maintained or supported by the core +Python team. + +The last version of Python that provide
[Python-checkins] gh-124370: Add "howto" for free-threaded Python (#124371)
https://github.com/python/cpython/commit/68e384c2179fba41bc3be469e6ef34927a37f4a5 commit: 68e384c2179fba41bc3be469e6ef34927a37f4a5 branch: main author: Sam Gross committer: nedbat date: 2024-09-25T17:31:53-04:00 summary: gh-124370: Add "howto" for free-threaded Python (#124371) * gh-124370: Add "howto" for free-threaded Python This is a guide aimed at people writing Python code, as oppposed to the existing guide for C API extension authors. * Add missing new line * Update Doc/howto/free-threading-python.rst Co-authored-by: Jelle Zijlstra * interned -> immortalized * Apply suggestions from code review Co-authored-by: Hugo van Kemenade <[email protected]> * Update Doc/howto/free-threading-python.rst Co-authored-by: mpage * Update docs * Apply suggestions from code review Co-authored-by: Carol Willing * A few more updates * Additional comment on immortal objects * Mention specializing adaptive interpreter * Remove trailing whitespace * Remove mention of C macro - Co-authored-by: Jelle Zijlstra Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: mpage Co-authored-by: Carol Willing files: A Doc/howto/free-threading-python.rst M Doc/howto/index.rst M Doc/reference/datamodel.rst diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst new file mode 100644 index 00..b21e3287ecaa3f --- /dev/null +++ b/Doc/howto/free-threading-python.rst @@ -0,0 +1,154 @@ +.. _freethreading-python-howto: + +** +Python experimental support for free threading +** + +Starting with the 3.13 release, CPython has experimental support for a build of +Python called :term:`free threading` where the :term:`global interpreter lock` +(GIL) is disabled. Free-threaded execution allows for full utilization of the +available processing power by running threads in parallel on available CPU cores. +While not all software will benefit from this automatically, programs +designed with threading in mind will run faster on multi-core hardware. + +**The free-threaded mode is experimental** and work is ongoing to improve it: +expect some bugs and a substantial single-threaded performance hit. + +This document describes the implications of free threading +for Python code. See :ref:`freethreading-extensions-howto` for information on +how to write C extensions that support the free-threaded build. + +.. seealso:: + + :pep:`703` – Making the Global Interpreter Lock Optional in CPython for an + overall description of free-threaded Python. + + +Installation + + +Starting with Python 3.13, the official macOS and Windows installers +optionally support installing free-threaded Python binaries. The installers +are available at https://www.python.org/downloads/. + +For information on other platforms, see the `Installing a Free-Threaded Python +<https://py-free-threading.github.io/installing_cpython/>`_, a +community-maintained installation guide for installing free-threaded Python. + +When building CPython from source, the :option:`--disable-gil` configure option +should be used to build a free-threaded Python interpreter. + + +Identifying free-threaded Python + + +To check if the current interpreter supports free-threading, :option:`python -VV <-V>` +and :attr:`sys.version` contain "experimental free-threading build". +The new :func:`sys._is_gil_enabled` function can be used to check whether +the GIL is actually disabled in the running process. + +The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can +be used to determine whether the build supports free threading. If the variable +is set to ``1``, then the build supports free threading. This is the recommended +mechanism for decisions related to the build configuration. + + +The global interpreter lock in free-threaded Python +=== + +Free-threaded builds of CPython support optionally running with the GIL enabled +at runtime using the environment variable :envvar:`PYTHON_GIL` or +the command-line option :option:`-X gil`. + +The GIL may also automatically be enabled when importing a C-API extension +module that is not explicitly marked as supporting free threading. A warning +will be printed in this case. + +In addition to individual package documentation, the following websites track +the status of popular packages support for free threading: + +* https://py-free-threading.github.io/tracking/ +* https://hugovk.github.io/free-threaded-wheels/ + + +Thread safety += + +The free-threaded build of CPython aims to provide similar thread-safety +behavior at the Python level to the default GIL-enabled build. Built-in +types like :class:`dict`, :class:`list`, and :class:`set` use inter
[Python-checkins] For-else deserves its own section in the tutorial (#123946)
https://github.com/python/cpython/commit/ffdc80e93d9d947531fa0123e5b392c6f1fd9136
commit: ffdc80e93d9d947531fa0123e5b392c6f1fd9136
branch: main
author: Ned Batchelder
committer: nedbat
date: 2024-09-25T19:18:18-04:00
summary:
For-else deserves its own section in the tutorial (#123946)
* For-else deserves its own section in the tutorial
* remove mention of unrolling the loop
* Update Doc/tutorial/controlflow.rst
Co-authored-by: Jelle Zijlstra
-
Co-authored-by: Jelle Zijlstra
files:
M Doc/tutorial/controlflow.rst
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 677d7ca02c3f2f..c97c65f7a3988e 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -160,16 +160,52 @@ arguments. In chapter :ref:`tut-structures`, we will
discuss in more detail abo
.. _tut-break:
-:keyword:`!break` and :keyword:`!continue` Statements, and :keyword:`!else`
Clauses on Loops
-
+:keyword:`!break` and :keyword:`!continue` Statements
+=
The :keyword:`break` statement breaks out of the innermost enclosing
-:keyword:`for` or :keyword:`while` loop.
+:keyword:`for` or :keyword:`while` loop::
-A :keyword:`!for` or :keyword:`!while` loop can include an :keyword:`!else`
clause.
+>>> for n in range(2, 10):
+... for x in range(2, n):
+... if n % x == 0:
+... print(f"{n} equals {x} * {n//x}")
+... break
+...
+4 equals 2 * 2
+6 equals 2 * 3
+8 equals 2 * 4
+9 equals 3 * 3
+
+The :keyword:`continue` statement continues with the next
+iteration of the loop::
+
+>>> for num in range(2, 10):
+... if num % 2 == 0:
+... print(f"Found an even number {num}")
+... continue
+... print(f"Found an odd number {num}")
+...
+Found an even number 2
+Found an odd number 3
+Found an even number 4
+Found an odd number 5
+Found an even number 6
+Found an odd number 7
+Found an even number 8
+Found an odd number 9
+
+.. _tut-for-else:
+
+:keyword:`!else` Clauses on Loops
+=
+
+In a :keyword:`!for` or :keyword:`!while` loop the :keyword:`!break` statement
+may be paired with an :keyword:`!else` clause. If the loop finishes without
+executing the :keyword:`!break`, the :keyword:`!else` clause executes.
In a :keyword:`for` loop, the :keyword:`!else` clause is executed
-after the loop reaches its final iteration.
+after the loop finishes its final iteration, that is, if no break occurred.
In a :keyword:`while` loop, it's executed after the loop's condition becomes
false.
@@ -198,32 +234,19 @@ which searches for prime numbers::
9 equals 3 * 3
(Yes, this is the correct code. Look closely: the ``else`` clause belongs to
-the :keyword:`for` loop, **not** the :keyword:`if` statement.)
-
-When used with a loop, the ``else`` clause has more in common with the
-``else`` clause of a :keyword:`try` statement than it does with that of
-:keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
-when no exception occurs, and a loop's ``else`` clause runs when no ``break``
-occurs. For more on the :keyword:`!try` statement and exceptions, see
-:ref:`tut-handling`.
-
-The :keyword:`continue` statement, also borrowed from C, continues with the
next
-iteration of the loop::
-
->>> for num in range(2, 10):
-... if num % 2 == 0:
-... print("Found an even number", num)
-... continue
-... print("Found an odd number", num)
-...
-Found an even number 2
-Found an odd number 3
-Found an even number 4
-Found an odd number 5
-Found an even number 6
-Found an odd number 7
-Found an even number 8
-Found an odd number 9
+the ``for`` loop, **not** the ``if`` statement.)
+
+One way to think of the else clause is to imagine it paired with the ``if``
+inside the loop. As the loop executes, it will run a sequence like
+if/if/if/else. The ``if`` is inside the loop, encountered a number of times. If
+the condition is ever true, a ``break`` will happen. If the condition is never
+true, the ``else`` clause outside the loop will execute.
+
+When used with a loop, the ``else`` clause has more in common with the ``else``
+clause of a :keyword:`try` statement than it does with that of ``if``
+statements: a ``try`` statement's ``else`` clause runs when no exception
+occurs, and a loop's ``else`` clause runs when no ``break`` occurs. For more on
+the ``try`` statement and exceptions, see :ref:`tut-handling`.
.. _tut-pass:
___
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to python-checki
[Python-checkins] Docs: for for/else clarify that return or raise also skip the else (#124591)
https://github.com/python/cpython/commit/5329d1b74a86b3a22ff36f7976bfe720ee06d10d commit: 5329d1b74a86b3a22ff36f7976bfe720ee06d10d branch: main author: Ned Batchelder committer: nedbat date: 2024-09-27T06:17:25-04:00 summary: Docs: for for/else clarify that return or raise also skip the else (#124591) Co-authored-by: Jelle Zijlstra files: M Doc/tutorial/controlflow.rst diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index c97c65f7a3988e..fd765e58ff2485 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -209,8 +209,10 @@ after the loop finishes its final iteration, that is, if no break occurred. In a :keyword:`while` loop, it's executed after the loop's condition becomes false. -In either kind of loop, the :keyword:`!else` clause is **not** executed -if the loop was terminated by a :keyword:`break`. +In either kind of loop, the :keyword:`!else` clause is **not** executed if the +loop was terminated by a :keyword:`break`. Of course, other ways of ending the +loop early, such as a :keyword:`return` or a raised exception, will also skip +execution of the :keyword:`else` clause. This is exemplified in the following :keyword:`!for` loop, which searches for prime numbers:: ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] [3.12] Docs: re-create pages for removed modules to document their removal, based on GH-126622 (#126781)
https://github.com/python/cpython/commit/73dedbd22345e5546ac0d201280588f5274b7085 commit: 73dedbd22345e5546ac0d201280588f5274b7085 branch: 3.12 author: Ned Batchelder committer: nedbat date: 2024-11-13T19:02:09-05:00 summary: [3.12] Docs: re-create pages for removed modules to document their removal, based on GH-126622 (#126781) [3.12] Docs: re-create pages for removed modules to document their removal, based on #126622 files: A Doc/library/asynchat.rst A Doc/library/asyncore.rst A Doc/library/distutils.rst A Doc/library/imp.rst A Doc/library/removed.rst A Doc/library/smtpd.rst M Doc/library/index.rst M Doc/whatsnew/3.12.rst diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst new file mode 100644 index 00..5e5c3a99fe66f1 --- /dev/null +++ b/Doc/library/asynchat.rst @@ -0,0 +1,17 @@ +:mod:`!asynchat` --- Asynchronous socket command/response handler += + +.. module:: asynchat + :synopsis: Removed in 3.12. + :deprecated: + +.. deprecated-removed:: 3.6 3.12 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.12 ` after +being deprecated in Python 3.6. The removal was decided in :pep:`594`. + +Applications should use the :mod:`asyncio` module instead. + +The last version of Python that provided the :mod:`!asynchat` module was +`Python 3.11 <https://docs.python.org/3.11/library/asynchat.html>`_. diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst new file mode 100644 index 00..22c9881c3cca36 --- /dev/null +++ b/Doc/library/asyncore.rst @@ -0,0 +1,17 @@ +:mod:`!asyncore` --- Asynchronous socket handler + + +.. module:: asyncore + :synopsis: Removed in 3.12. + :deprecated: + +.. deprecated-removed:: 3.6 3.12 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.12 ` after +being deprecated in Python 3.6. The removal was decided in :pep:`594`. + +Applications should use the :mod:`asyncio` module instead. + +The last version of Python that provided the :mod:`!asyncore` module was +`Python 3.11 <https://docs.python.org/3.11/library/asyncore.html>`_. diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst new file mode 100644 index 00..af63e035bf3c4a --- /dev/null +++ b/Doc/library/distutils.rst @@ -0,0 +1,17 @@ +:mod:`!distutils` --- Building and installing Python modules + + +.. module:: distutils + :synopsis: Removed in 3.12. + :deprecated: + +.. deprecated-removed:: 3.10 3.12 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.12 ` after +being deprecated in Python 3.10. The removal was decided in :pep:`632`, +which has `migration advice +<https://peps.python.org/pep-0632/#migration-advice>`_. + +The last version of Python that provided the :mod:`!distutils` module was +`Python 3.11 <https://docs.python.org/3.11/library/distutils.html>`_. diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst new file mode 100644 index 00..3dc4c568b1ae2f --- /dev/null +++ b/Doc/library/imp.rst @@ -0,0 +1,18 @@ +:mod:`!imp` --- Access the import internals +=== + +.. module:: imp + :synopsis: Removed in 3.12. + :deprecated: + +.. deprecated-removed:: 3.4 3.12 + +This module is no longer part of the Python standard library. +It was :ref:`removed in Python 3.12 ` after +being deprecated in Python 3.4. + +The :ref:`removal notice ` includes guidance for +migrating code from :mod:`!imp` to :mod:`importlib`. + +The last version of Python that provided the :mod:`!imp` module was +`Python 3.11 <https://docs.python.org/3.11/library/imp.html>`_. diff --git a/Doc/library/index.rst b/Doc/library/index.rst index 0b348ae6f5c8c0..951fbcf13fbb13 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -75,4 +75,5 @@ the `Python Package Index <https://pypi.org>`_. unix.rst cmdline.rst superseded.rst + removed.rst security_warnings.rst diff --git a/Doc/library/removed.rst b/Doc/library/removed.rst new file mode 100644 index 00..4aafb0882c0a03 --- /dev/null +++ b/Doc/library/removed.rst @@ -0,0 +1,20 @@ +:tocdepth: 1 + +.. _removed: + +*** +Removed Modules +*** + +The modules described in this chapter have been removed from the Python +standard library. They are documented here to help people find replacements. + + +.. toctree:: + :maxdepth: 1 + + asynchat.rst + asyncore.rst + distutils.rst + imp.rst + smtpd.rst diff --git a/Doc/library/smtpd.rst b/Doc/library/smtpd.rst new file mode 100644 index 00..c704f4a241b469 --- /dev/null +++ b/Doc/library/smtpd.rst @@ -0,0 +1,18 @@ +:mod:`!smtpd` --- SMTP Server += + +.. module:: smtpd + :synops
[Python-checkins] Fix "useable" typo in docs (#127200)
https://github.com/python/cpython/commit/dbd23790dbd662169905be6300259992639d4e69 commit: dbd23790dbd662169905be6300259992639d4e69 branch: main author: Stan U. <[email protected]> committer: nedbat date: 2024-11-23T16:41:01-05:00 summary: Fix "useable" typo in docs (#127200) Fix typo in docs files: M README.rst diff --git a/README.rst b/README.rst index 29db15b41d2c72..394cdc3638485d 100644 --- a/README.rst +++ b/README.rst @@ -64,7 +64,7 @@ the executable is called ``python.exe``; elsewhere it's just ``python``. Building a complete Python installation requires the use of various additional third-party libraries, depending on your build platform and configure options. Not all standard library modules are buildable or -useable on all platforms. Refer to the +usable on all platforms. Refer to the `Install dependencies <https://devguide.python.org/getting-started/setup-building.html#build-dependencies>`_ section of the `Developer Guide`_ for current detailed information on dependencies for various Linux distributions and macOS. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] [3.12] Fix "useable" typo in docs (GH-127200) (#127206)
https://github.com/python/cpython/commit/e26ba9670f31df3db471365ddef7b0c293ef6871 commit: e26ba9670f31df3db471365ddef7b0c293ef6871 branch: 3.12 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2024-11-23T16:45:47-05:00 summary: [3.12] Fix "useable" typo in docs (GH-127200) (#127206) Fix "useable" typo in docs (GH-127200) Fix typo in docs (cherry picked from commit dbd23790dbd662169905be6300259992639d4e69) Co-authored-by: Stan U <[email protected]> files: M README.rst diff --git a/README.rst b/README.rst index f7fbe2083d8774..0e8da6088322bd 100644 --- a/README.rst +++ b/README.rst @@ -64,7 +64,7 @@ the executable is called ``python.exe``; elsewhere it's just ``python``. Building a complete Python installation requires the use of various additional third-party libraries, depending on your build platform and configure options. Not all standard library modules are buildable or -useable on all platforms. Refer to the +usable on all platforms. Refer to the `Install dependencies <https://devguide.python.org/getting-started/setup-building.html#build-dependencies>`_ section of the `Developer Guide`_ for current detailed information on dependencies for various Linux distributions and macOS. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] [3.13] Fix "useable" typo in docs (GH-127200) (#127207)
https://github.com/python/cpython/commit/9dbce9f38262ad03844521b7ec56a7f9cd5d60d9 commit: 9dbce9f38262ad03844521b7ec56a7f9cd5d60d9 branch: 3.13 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2024-11-23T17:50:06-05:00 summary: [3.13] Fix "useable" typo in docs (GH-127200) (#127207) Fix "useable" typo in docs (GH-127200) Fix typo in docs (cherry picked from commit dbd23790dbd662169905be6300259992639d4e69) Co-authored-by: Stan U <[email protected]> files: M README.rst diff --git a/README.rst b/README.rst index 7c1e463273b418..d4edf5ca1c2860 100644 --- a/README.rst +++ b/README.rst @@ -64,7 +64,7 @@ the executable is called ``python.exe``; elsewhere it's just ``python``. Building a complete Python installation requires the use of various additional third-party libraries, depending on your build platform and configure options. Not all standard library modules are buildable or -useable on all platforms. Refer to the +usable on all platforms. Refer to the `Install dependencies <https://devguide.python.org/getting-started/setup-building.html#build-dependencies>`_ section of the `Developer Guide`_ for current detailed information on dependencies for various Linux distributions and macOS. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] docs: -I also implies -P (#131539)
https://github.com/python/cpython/commit/00f0771e4dbd8c8b66b302ebc16bb21f5d46b304 commit: 00f0771e4dbd8c8b66b302ebc16bb21f5d46b304 branch: main author: Ned Batchelder committer: nedbat date: 2025-03-28T14:59:03-04:00 summary: docs: -I also implies -P (#131539) files: ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] docs: internal notes have moved, correct references (#130762)
https://github.com/python/cpython/commit/efbc5929ca022661bd311b075116746d294bd71b
commit: efbc5929ca022661bd311b075116746d294bd71b
branch: main
author: Ned Batchelder
committer: nedbat
date: 2025-03-03T06:38:49-05:00
summary:
docs: internal notes have moved, correct references (#130762)
files:
M Include/internal/pycore_code.h
M Python/assemble.c
diff --git a/Include/internal/pycore_code.h b/Include/internal/pycore_code.h
index 6d45d5f0c4071f..fa0e0bd01c99e9 100644
--- a/Include/internal/pycore_code.h
+++ b/Include/internal/pycore_code.h
@@ -474,7 +474,7 @@ read_obj(uint16_t *p)
return val;
}
-/* See Objects/exception_handling_notes.txt for details.
+/* See InternalDocs/exception_handling.md for details.
*/
static inline unsigned char *
parse_varint(unsigned char *p, int *result) {
diff --git a/Python/assemble.c b/Python/assemble.c
index 6dcac332f076d8..070be1ca54e3ea 100644
--- a/Python/assemble.c
+++ b/Python/assemble.c
@@ -126,7 +126,7 @@ assemble_emit_exception_table_item(struct assembler *a, int
value, int msb)
write_except_byte(a, (value&0x3f) | msb);
}
-/* See Objects/exception_handling_notes.txt for details of layout */
+/* See InternalDocs/exception_handling.md for details of layout */
#define MAX_SIZE_OF_ENTRY 20
static int
___
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
[Python-checkins] Replace link to historical TypedDict PEP with current document on typing.python… (#131096)
https://github.com/python/cpython/commit/e0bc9d2a0c448cf46df233f8d84344c1f55a190f commit: e0bc9d2a0c448cf46df233f8d84344c1f55a190f branch: main author: Gerardwx committer: nedbat date: 2025-03-11T12:45:31-04:00 summary: Replace link to historical TypedDict PEP with current document on typing.python… (#131096) * Replace link to historical PEP with current document on typing.python.org * Update Doc/library/typing.rst Co-authored-by: Ned Batchelder - Co-authored-by: Ned Batchelder files: M Doc/library/typing.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 3bbc8c0e818975..6d5ee75f11efa7 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2771,7 +2771,7 @@ types. .. versionadded:: 3.13 - See :pep:`589` for more examples and detailed rules of using ``TypedDict``. + See the `TypedDict <https://typing.python.org/en/latest/spec/typeddict.html#typeddict>`_ section in the typing documentation for more examples and detailed rules. .. versionadded:: 3.8 ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] Docs: Add note to tutorial clarifying scope (#134534)
https://github.com/python/cpython/commit/742d5b5c5d75eae44c66a43ebfa24a4f286ea8a1 commit: 742d5b5c5d75eae44c66a43ebfa24a4f286ea8a1 branch: main author: Kattni committer: nedbat date: 2025-05-22T14:26:47-04:00 summary: Docs: Add note to tutorial clarifying scope (#134534) * Add note to tutorial * Update formatting files: M Doc/tutorial/index.rst diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst index 96791f88c867ab..d0bf77dc40d0a1 100644 --- a/Doc/tutorial/index.rst +++ b/Doc/tutorial/index.rst @@ -4,6 +4,10 @@ The Python Tutorial ## +.. Tip:: This tutorial is designed for + *programmers* that are new to the Python language, + **not** *beginners* who are new to programming. + Python is an easy to learn, powerful programming language. It has efficient high-level data structures and a simple but effective approach to object-oriented programming. Python's elegant syntax and dynamic typing, @@ -21,7 +25,8 @@ implemented in C or C++ (or other languages callable from C). Python is also suitable as an extension language for customizable applications. This tutorial introduces the reader informally to the basic concepts and -features of the Python language and system. It helps to have a Python +features of the Python language and system. Be aware that it expects you to +have a basic understanding of programming in general. It helps to have a Python interpreter handy for hands-on experience, but all examples are self-contained, so the tutorial can be read off-line as well. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] [3.14] Docs: Add note to tutorial clarifying scope (GH-134534) (#134536)
https://github.com/python/cpython/commit/37c2c8c9d8a20fdc9e9d5247d96ea6719de3134d commit: 37c2c8c9d8a20fdc9e9d5247d96ea6719de3134d branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2025-05-22T18:32:49Z summary: [3.14] Docs: Add note to tutorial clarifying scope (GH-134534) (#134536) Docs: Add note to tutorial clarifying scope (GH-134534) * Add note to tutorial * Update formatting (cherry picked from commit 742d5b5c5d75eae44c66a43ebfa24a4f286ea8a1) Co-authored-by: Kattni files: M Doc/tutorial/index.rst diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst index 96791f88c867ab..d0bf77dc40d0a1 100644 --- a/Doc/tutorial/index.rst +++ b/Doc/tutorial/index.rst @@ -4,6 +4,10 @@ The Python Tutorial ## +.. Tip:: This tutorial is designed for + *programmers* that are new to the Python language, + **not** *beginners* who are new to programming. + Python is an easy to learn, powerful programming language. It has efficient high-level data structures and a simple but effective approach to object-oriented programming. Python's elegant syntax and dynamic typing, @@ -21,7 +25,8 @@ implemented in C or C++ (or other languages callable from C). Python is also suitable as an extension language for customizable applications. This tutorial introduces the reader informally to the basic concepts and -features of the Python language and system. It helps to have a Python +features of the Python language and system. Be aware that it expects you to +have a basic understanding of programming in general. It helps to have a Python interpreter handy for hands-on experience, but all examples are self-contained, so the tutorial can be read off-line as well. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] Docs: add dunder and walrus to the glossary (#137430)
https://github.com/python/cpython/commit/44ff6b545149ea59837fc74122d435572f21e489 commit: 44ff6b545149ea59837fc74122d435572f21e489 branch: main author: Ned Batchelder committer: nedbat date: 2025-08-05T16:30:38-04:00 summary: Docs: add dunder and walrus to the glossary (#137430) files: M Doc/glossary.rst diff --git a/Doc/glossary.rst b/Doc/glossary.rst index a4dc986c313c57..69e8857af894e4 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -435,6 +435,11 @@ Glossary with :term:`abstract base classes `.) Instead, it typically employs :func:`hasattr` tests or :term:`EAFP` programming. + dunder + An informal short-hand for "double underscore", used when talking about a + :term:`special method`. For example, ``__init__`` is often pronounced + "dunder init". + EAFP Easier to ask for forgiveness than permission. This common Python coding style assumes the existence of valid keys or attributes and catches @@ -1474,6 +1479,11 @@ Glossary A computer defined entirely in software. Python's virtual machine executes the :term:`bytecode` emitted by the bytecode compiler. + walrus operator + A light-hearted way to refer to the :ref:`assignment expression + ` operator ``:=`` because it looks a bit like a + walrus if you turn your head. + Zen of Python Listing of Python design principles and philosophies that are helpful in understanding and using the language. The listing can be found by typing ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] gh-133986: Document string split algorithm when sep is None and maxsplit is 0 (#133987)
https://github.com/python/cpython/commit/3e23047363f384b7254b7af51afe4e353be94167 commit: 3e23047363f384b7254b7af51afe4e353be94167 branch: main author: Joey Smith committer: nedbat date: 2025-05-14T06:17:26-04:00 summary: gh-133986: Document string split algorithm when sep is None and maxsplit is 0 (#133987) * Document string split algorithm when sep is None and maxsplit is 0 * Update Doc/library/stdtypes.rst Co-authored-by: Semyon Moroz - Co-authored-by: Ned Batchelder Co-authored-by: Semyon Moroz files: M Doc/library/stdtypes.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 1d9a655c7664ea..3486a18b5cb1f0 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2269,6 +2269,18 @@ expression support in the :mod:`re` module). >>> ' 1 2 3 '.split() ['1', '2', '3'] + If *sep* is not specified or is ``None`` and *maxsplit* is ``0``, only + leading runs of consecutive whitespace are considered. + + For example:: + + >>> "".split(None, 0) + [] + >>> " ".split(None, 0) + [] + >>> " foo ".split(maxsplit=0) + ['foo '] + .. index:: single: universal newlines; str.splitlines method ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] [3.14] gh-134150: Clarify distinction between JSON and Python objects (GH-134154) (#134166)
https://github.com/python/cpython/commit/bf39decabdc7feff3a7441fa93136c22596c2d67 commit: bf39decabdc7feff3a7441fa93136c22596c2d67 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2025-05-18T01:54:00Z summary: [3.14] gh-134150: Clarify distinction between JSON and Python objects (GH-134154) (#134166) gh-134150: Clarify distinction between JSON and Python objects (GH-134154) * gh-134150: Clarify distinction between JSON objects and Python objects in json module docs * Revert change to JSON introduction * Clarify occurrences of "object literal" as JSON (cherry picked from commit fa4e088668d4a41f9be5babe7edd5409290ee92a) Co-authored-by: Micha Albert files: M Doc/library/json.rst diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 26579ec6328860..12a5a96a3c56f3 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -18,12 +18,17 @@ is a lightweight data interchange format inspired by `JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax (although it is not a strict subset of JavaScript [#rfc-errata]_ ). +.. note:: + The term "object" in the context of JSON processing in Python can be + ambiguous. All values in Python are objects. In JSON, an object refers to + any data wrapped in curly braces, similar to a Python dictionary. + .. warning:: Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended. -:mod:`json` exposes an API familiar to users of the standard library +This module exposes an API familiar to users of the standard library :mod:`marshal` and :mod:`pickle` modules. Encoding basic Python object hierarchies:: @@ -60,7 +65,7 @@ Pretty printing:: "6": 7 } -Specializing JSON object encoding:: +Customizing JSON object encoding:: >>> import json >>> def custom_json(obj): @@ -83,7 +88,7 @@ Decoding JSON:: >>> json.load(io) ['streaming API'] -Specializing JSON object decoding:: +Customizing JSON object decoding:: >>> import json >>> def as_complex(dct): @@ -279,7 +284,7 @@ Basic Usage :param object_hook: If set, a function that is called with the result of - any object literal decoded (a :class:`dict`). + any JSON object literal decoded (a :class:`dict`). The return value of this function will be used instead of the :class:`dict`. This feature can be used to implement custom decoders, @@ -289,7 +294,7 @@ Basic Usage :param object_pairs_hook: If set, a function that is called with the result of - any object literal decoded with an ordered list of pairs. + any JSON object literal decoded with an ordered list of pairs. The return value of this function will be used instead of the :class:`dict`. This feature can be used to implement custom decoders. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] [3.13] gh-134150: Clarify distinction between JSON and Python objects (GH-134154) (#134167)
https://github.com/python/cpython/commit/ebe54d7ab7ccafbd0a8a6036fd12de971dd2f55b commit: ebe54d7ab7ccafbd0a8a6036fd12de971dd2f55b branch: 3.13 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2025-05-18T01:53:37Z summary: [3.13] gh-134150: Clarify distinction between JSON and Python objects (GH-134154) (#134167) gh-134150: Clarify distinction between JSON and Python objects (GH-134154) * gh-134150: Clarify distinction between JSON objects and Python objects in json module docs * Revert change to JSON introduction * Clarify occurrences of "object literal" as JSON (cherry picked from commit fa4e088668d4a41f9be5babe7edd5409290ee92a) Co-authored-by: Micha Albert files: M Doc/library/json.rst diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 1b5bd51cce2025..40427755ebcc28 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -18,12 +18,17 @@ is a lightweight data interchange format inspired by `JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax (although it is not a strict subset of JavaScript [#rfc-errata]_ ). +.. note:: + The term "object" in the context of JSON processing in Python can be + ambiguous. All values in Python are objects. In JSON, an object refers to + any data wrapped in curly braces, similar to a Python dictionary. + .. warning:: Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended. -:mod:`json` exposes an API familiar to users of the standard library +This module exposes an API familiar to users of the standard library :mod:`marshal` and :mod:`pickle` modules. Encoding basic Python object hierarchies:: @@ -60,7 +65,7 @@ Pretty printing:: "6": 7 } -Specializing JSON object encoding:: +Customizing JSON object encoding:: >>> import json >>> def custom_json(obj): @@ -83,7 +88,7 @@ Decoding JSON:: >>> json.load(io) ['streaming API'] -Specializing JSON object decoding:: +Customizing JSON object decoding:: >>> import json >>> def as_complex(dct): @@ -279,7 +284,7 @@ Basic Usage :param object_hook: If set, a function that is called with the result of - any object literal decoded (a :class:`dict`). + any JSON object literal decoded (a :class:`dict`). The return value of this function will be used instead of the :class:`dict`. This feature can be used to implement custom decoders, @@ -289,7 +294,7 @@ Basic Usage :param object_pairs_hook: If set, a function that is called with the result of - any object literal decoded with an ordered list of pairs. + any JSON object literal decoded with an ordered list of pairs. The return value of this function will be used instead of the :class:`dict`. This feature can be used to implement custom decoders. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] gh-134150: Clarify distinction between JSON and Python objects (#134154)
https://github.com/python/cpython/commit/fa4e088668d4a41f9be5babe7edd5409290ee92a commit: fa4e088668d4a41f9be5babe7edd5409290ee92a branch: main author: Micha Albert committer: nedbat date: 2025-05-17T21:47:37-04:00 summary: gh-134150: Clarify distinction between JSON and Python objects (#134154) * gh-134150: Clarify distinction between JSON objects and Python objects in json module docs * Revert change to JSON introduction * Clarify occurrences of "object literal" as JSON files: M Doc/library/json.rst diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 26579ec6328860..12a5a96a3c56f3 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -18,12 +18,17 @@ is a lightweight data interchange format inspired by `JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax (although it is not a strict subset of JavaScript [#rfc-errata]_ ). +.. note:: + The term "object" in the context of JSON processing in Python can be + ambiguous. All values in Python are objects. In JSON, an object refers to + any data wrapped in curly braces, similar to a Python dictionary. + .. warning:: Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended. -:mod:`json` exposes an API familiar to users of the standard library +This module exposes an API familiar to users of the standard library :mod:`marshal` and :mod:`pickle` modules. Encoding basic Python object hierarchies:: @@ -60,7 +65,7 @@ Pretty printing:: "6": 7 } -Specializing JSON object encoding:: +Customizing JSON object encoding:: >>> import json >>> def custom_json(obj): @@ -83,7 +88,7 @@ Decoding JSON:: >>> json.load(io) ['streaming API'] -Specializing JSON object decoding:: +Customizing JSON object decoding:: >>> import json >>> def as_complex(dct): @@ -279,7 +284,7 @@ Basic Usage :param object_hook: If set, a function that is called with the result of - any object literal decoded (a :class:`dict`). + any JSON object literal decoded (a :class:`dict`). The return value of this function will be used instead of the :class:`dict`. This feature can be used to implement custom decoders, @@ -289,7 +294,7 @@ Basic Usage :param object_pairs_hook: If set, a function that is called with the result of - any object literal decoded with an ordered list of pairs. + any JSON object literal decoded with an ordered list of pairs. The return value of this function will be used instead of the :class:`dict`. This feature can be used to implement custom decoders. ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
[Python-checkins] [3.13] gh-134789: Document del s[i] operation for mutable sequences (GH-134804) (#134809)
https://github.com/python/cpython/commit/73e432896bcd4d1008fc04394e1d7a33877d4aeb commit: 73e432896bcd4d1008fc04394e1d7a33877d4aeb branch: 3.13 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2025-05-27T18:54:16Z summary: [3.13] gh-134789: Document del s[i] operation for mutable sequences (GH-134804) (#134809) gh-134789: Document del s[i] operation for mutable sequences (GH-134804) [main] Update stdtypes.rst - Added explicit mention of `del s[i]` (item deletion by index) to the Mutable Sequence Types section. - Clarified that this operation removes the item at the specified index from the sequence. - Addresses issue GH-134789. (cherry picked from commit 967f361993c9c97eb3ff3076a409b78ea32938df) Co-authored-by: Rishabh Singh <[email protected]> files: M Doc/library/stdtypes.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 2c1ca4627795f3..b279c693a6cc31 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1172,6 +1172,8 @@ accepts integers that meet the value restriction ``0 <= x <= 255``). | ``s[i] = x`` | item *i* of *s* is replaced by | | | | *x*| | +--++-+ +| ``del s[i]`` | removes item *i* of *s*| | ++--++-+ | ``s[i:j] = t`` | slice of *s* from *i* to *j* | | | | is replaced by the contents of | | | | the iterable *t* | | ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] gh-134789: Document del s[i] operation for mutable sequences (#134804)
https://github.com/python/cpython/commit/967f361993c9c97eb3ff3076a409b78ea32938df commit: 967f361993c9c97eb3ff3076a409b78ea32938df branch: main author: Rishabh Singh <[email protected]> committer: nedbat date: 2025-05-27T14:48:04-04:00 summary: gh-134789: Document del s[i] operation for mutable sequences (#134804) [main] Update stdtypes.rst - Added explicit mention of `del s[i]` (item deletion by index) to the Mutable Sequence Types section. - Clarified that this operation removes the item at the specified index from the sequence. - Addresses issue #134789. files: M Doc/library/stdtypes.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 31d71031bca12c..f0b4b09ff10dce 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1214,6 +1214,8 @@ accepts integers that meet the value restriction ``0 <= x <= 255``). | ``s[i] = x`` | item *i* of *s* is replaced by | | | | *x*| | +--++-+ +| ``del s[i]`` | removes item *i* of *s*| | ++--++-+ | ``s[i:j] = t`` | slice of *s* from *i* to *j* | | | | is replaced by the contents of | | | | the iterable *t* | | ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] [3.14] gh-134789: Document del s[i] operation for mutable sequences (GH-134804) (#134808)
https://github.com/python/cpython/commit/0ea41f8464454cf4e44d281b780623a106ab93de commit: 0ea41f8464454cf4e44d281b780623a106ab93de branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: nedbat date: 2025-05-27T18:53:52Z summary: [3.14] gh-134789: Document del s[i] operation for mutable sequences (GH-134804) (#134808) gh-134789: Document del s[i] operation for mutable sequences (GH-134804) [main] Update stdtypes.rst - Added explicit mention of `del s[i]` (item deletion by index) to the Mutable Sequence Types section. - Clarified that this operation removes the item at the specified index from the sequence. - Addresses issue GH-134789. (cherry picked from commit 967f361993c9c97eb3ff3076a409b78ea32938df) Co-authored-by: Rishabh Singh <[email protected]> files: M Doc/library/stdtypes.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 31d71031bca12c..f0b4b09ff10dce 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1214,6 +1214,8 @@ accepts integers that meet the value restriction ``0 <= x <= 255``). | ``s[i] = x`` | item *i* of *s* is replaced by | | | | *x*| | +--++-+ +| ``del s[i]`` | removes item *i* of *s*| | ++--++-+ | ``s[i:j] = t`` | slice of *s* from *i* to *j* | | | | is replaced by the contents of | | | | the iterable *t* | | ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] docs: be clearer that glob results are unordered (#140184)
https://github.com/python/cpython/commit/ed672f7a8a3c843d8e6e6b673d5a7c1f752f208c commit: ed672f7a8a3c843d8e6e6b673d5a7c1f752f208c branch: main author: Ned Batchelder committer: nedbat date: 2025-10-19T16:16:35-04:00 summary: docs: be clearer that glob results are unordered (#140184) * docs: be clearer that glob results are unordered * trim down the opening paragraph files: M Doc/library/glob.rst M Lib/glob.py diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 59ad1b07f27338..52c44928153337 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -18,23 +18,27 @@ single: - (minus); in glob-style wildcards single: . (dot); in glob-style wildcards -The :mod:`glob` module finds all the pathnames matching a specified pattern -according to the rules used by the Unix shell, although results are returned in -arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character +The :mod:`!glob` module finds pathnames +using pattern matching rules similar to the Unix shell. +No tilde expansion is done, but ``*``, ``?``, and character ranges expressed with ``[]`` will be correctly matched. This is done by using the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a subshell. -Note that files beginning with a dot (``.``) can only be matched by +.. note:: + The pathnames are returned in no particular order. If you need a specific + order, sort the results. + +Files beginning with a dot (``.``) can only be matched by patterns that also start with a dot, unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`. -(For tilde and shell variable expansion, use :func:`os.path.expanduser` and -:func:`os.path.expandvars`.) +For tilde and shell variable expansion, use :func:`os.path.expanduser` and +:func:`os.path.expandvars`. For a literal match, wrap the meta-characters in brackets. For example, ``'[?]'`` matches the character ``'?'``. -The :mod:`glob` module defines the following functions: +The :mod:`!glob` module defines the following functions: .. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, \ @@ -51,7 +55,7 @@ The :mod:`glob` module defines the following functions: If *root_dir* is not ``None``, it should be a :term:`path-like object` specifying the root directory for searching. It has the same effect on - :func:`glob` as changing the current directory before calling it. If + :func:`!glob` as changing the current directory before calling it. If *pathname* is relative, the result will contain paths relative to *root_dir*. diff --git a/Lib/glob.py b/Lib/glob.py index 5d42077003a240..c2f8ce279aba64 100644 --- a/Lib/glob.py +++ b/Lib/glob.py @@ -22,6 +22,9 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, dot are special cases that are not matched by '*' and '?' patterns by default. +The order of the returned list is undefined. Sort it if you need a +particular order. + If `include_hidden` is true, the patterns '*', '?', '**' will match hidden directories. @@ -40,6 +43,9 @@ def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, dot are special cases that are not matched by '*' and '?' patterns. +The order of the returned paths is undefined. Sort them if you need a +particular order. + If recursive is true, the pattern '**' will match any files and zero or more directories and subdirectories. """ ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] Docs: replace an esoteric Von Neumann mention (#137598)
https://github.com/python/cpython/commit/237dca52ba1e850758a3dd7e46adb78a4f70d43c commit: 237dca52ba1e850758a3dd7e46adb78a4f70d43c branch: main author: Ned Batchelder committer: nedbat date: 2025-10-20T10:01:20-04:00 summary: Docs: replace an esoteric Von Neumann mention (#137598) * Docs: replace an esoteric Von Neumann mention * oops, don't need to edit topics.py files: M Doc/reference/datamodel.rst diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 28ef5825159cb2..882b05e87319fa 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -16,9 +16,8 @@ Objects, values and types single: data :dfn:`Objects` are Python's abstraction for data. All data in a Python program -is represented by objects or by relations between objects. (In a sense, and in -conformance to Von Neumann's model of a "stored program computer", code is also -represented by objects.) +is represented by objects or by relations between objects. Even code is +represented by objects. .. index:: pair: built-in function; id @@ -29,9 +28,6 @@ represented by objects.) single: mutable object single: immutable object -.. XXX it *is* now possible in some cases to change an object's - type, under certain controlled conditions - Every object has an identity, a type and a value. An object's *identity* never changes once it has been created; you may think of it as the object's address in memory. The :keyword:`is` operator compares the identity of two objects; the ___ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
[Python-checkins] gh-138307: Update the Ellipsis documentation (#138306)
https://github.com/python/cpython/commit/88665de120d7f89e18774b136f3c898bcfe52c7b commit: 88665de120d7f89e18774b136f3c898bcfe52c7b branch: main author: Adorilson Bezerra committer: nedbat date: 2025-09-03T07:27:22-04:00 summary: gh-138307: Update the Ellipsis documentation (#138306) * Doc: Change Ellipsis doc at library/constants * Doc: Change Ellipsis doc at library/stdtypes * Doc: Add NumPy reference into Ellipsis doc at library/stdtypes * Doc: Add Ellipsis reference into the pass statement section at tutorial * Doc: Update Ellipsis doc concerns assignments at library/constants * Update Doc/library/stdtypes.rst Co-authored-by: Stan Ulbrych <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/constants.rst) Co-authored-by: Éric * Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) Co-authored-by: Éric * Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) Co-authored-by: Éric * Doc: Remove pretty printers reference from Ellipsis doc at library/stdtypes * Doc: Update index concerns Ellipsis object and pass statement * Doc: Improve Ellipsis doc at library/constants * Doc: Improve Ellipsis doc at library/stdtypes * Doc: Change the "..." glossary entry to mention the Ellipsis object * Doc: Some improvements concern ellipsis into typing doc * Minor update Doc/tutorial/controlflow.rst Co-authored-by: Ned Batchelder * Update Doc/library/constants.rst Co-authored-by: Ned Batchelder * Update Doc/library/stdtypes.rst Co-authored-by: Ned Batchelder - Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Éric Co-authored-by: Ned Batchelder files: M Doc/glossary.rst M Doc/library/constants.rst M Doc/library/stdtypes.rst M Doc/library/typing.rst M Doc/tutorial/controlflow.rst diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 453445211672da..d0fd05cdbdfabe 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -21,7 +21,9 @@ Glossary right delimiters (parentheses, square brackets, curly braces or triple quotes), or after specifying a decorator. - * The :const:`Ellipsis` built-in constant. + .. index:: single: ...; ellipsis literal + + * The three dots form of the :ref:`Ellipsis ` object. abstract base class Abstract base classes complement :term:`duck-typing` by diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 04080fd0d865ec..d058ba206c6cd6 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -65,8 +65,9 @@ A small number of constants live in the built-in namespace. They are: .. index:: single: ...; ellipsis literal .. data:: Ellipsis - The same as the ellipsis literal "``...``". Special value used mostly in conjunction - with extended slicing syntax for user-defined container data types. + The same as the ellipsis literal "``...``", an object frequently used to + indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but + assignment to ``...`` raises a :exc:`SyntaxError`. ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 3320f7c3bba728..5bc8257c37b89b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5869,13 +5869,34 @@ It is written as ``None``. The Ellipsis Object --- -This object is commonly used by slicing (see :ref:`slicings`). It supports no -special operations. There is exactly one ellipsis object, named +This object is commonly used used to indicate that something is omitted. +It supports no special operations. There is exactly one ellipsis object, named :const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the :const:`Ellipsis` singleton. It is written as ``Ellipsis`` or ``...``. +In typical use, ``...`` as the ``Ellipsis`` object appears in a few different +places, for instance: + +- In type annotations, such as :ref:`callable arguments ` + or :ref:`tuple elements `. + +- As the body of a function instead of a :ref:`pass statement `. + +- In third-party libraries, such as `Numpy's slicing and striding + <https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_. + +Python also uses three dots in ways that are not ``Ellipsis`` objects, for instance: + +- Doctest's :const:`ELLIPSIS `, as a pattern for missing content. + +- The default Python prompt of the :term:`interactive` shell when partial input is incomplete. + +Lastly, the Python documentation often uses three dots in conventional English +usage to mean omitted content, even in code examples that also use them as the +``Ellipsis``. + .. _bltin-notimplemented-object: diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 9dbac8ce75d489..c8eb1d08a1bb2a 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/t
