[pull] main from python:main

Doc/builtins/index.rst

@@ -0,0 +1,35 @@
+.. _builtins-index:
+
+##############################
+  Python built-ins reference
+##############################
+
+Python comes with a number of built-in functions and classes.
+
+The built-in classes include data types that would normally be considered part
+of the "core" of a language, such as numbers and lists.  For these types, the
+Python language core defines the form of literals and places some constraints
+on their semantics, but does not fully define the semantics.
+
+The built-ins also include functions and exceptions --- objects that can
+be used by all Python code without the need of an :keyword:`import` statement.
+Some of these are defined by the core language, but many are not essential for
+the core semantics and are only described here.
+
+.. seealso::
+
+   In addition to the built-ins, Python provides an extensive importable
+   standard library, see :ref:`library-index`.
+
+.. We don't use :numbered: option for the TOC below as it enforces
+   numbered sections for the entire builtin docs.  If desired,
+   :numbered: can be enabled on a per-page basis.
+.. toctree::
+   :maxdepth: 2
+
+   stdtypes.rst
+   constants.rst
+   functions.rst
+   exceptions.rst
+   threadsafety.rst
+   time-complexity.rst

Doc/conf.py

@@ -44,6 +44,7 @@
     'sphinx_linklint.ext',
     'notfound.extension',
     'sphinxext.opengraph',
+    'sphinxext.rediraffe',
     'sphinxcontrib.rsvgconverter',
 )
 for optional_ext in _OPTIONAL_EXTENSIONS:
@@ -359,7 +360,13 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
-    ('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'),
+    (
+        'c-api/index',
+        'c-api.tex',
+        'The Python/C API',
+        _doc_authors,
+        'manual',
+    ),
     (
         'extending/index',
         'extending.tex',
@@ -374,6 +381,13 @@
         _doc_authors,
         'manual',
     ),
+    (
+        'builtins/index',
+        'builtins.tex',
+        'Python Built-ins Reference',
+        _doc_authors,
+        'manual',
+    ),
     (
         'library/index',
         'library.tex',
@@ -606,3 +620,16 @@
         '<meta property="og:image:width" content="200">',
         '<meta property="og:image:height" content="200">',
     )
+
+# Options for sphinxext-rediraffe
+# -------------------------------
+
+rediraffe_redirects = {
+    # Splitting builtins from library
+    "library/functions.rst": "builtins/functions.rst",
+    "library/stdtypes.rst": "builtins/stdtypes.rst",
+    "library/constants.rst": "builtins/constants.rst",
+    "library/exceptions.rst": "builtins/exceptions.rst",
+    "library/threadsafety.rst": "builtins/threadsafety.rst",
+    "library/time-complexity.rst": "builtins/time-complexity.rst",
+}

Doc/contents.rst

@@ -8,6 +8,7 @@
    tutorial/index.rst
    using/index.rst
    reference/index.rst
+   builtins/index.rst
    library/index.rst
    extending/index.rst
    c-api/index.rst

Doc/extending/index.rst

@@ -16,9 +16,10 @@ underlying operating system supports this feature.
 
 This document assumes basic knowledge about C and Python.  For an informal
 introduction to Python, see :ref:`tutorial-index`.  :ref:`reference-index`
-gives a more formal definition of the language.  :ref:`library-index` documents
-the existing object types, functions and modules (both built-in and written in
-Python) that give the language its wide application range.
+gives a more formal definition of the language.  :ref:`builtins-index` documents
+the built-in functions and object types, and :ref:`library-index` documents the
+modules (both built-in and written in Python) that give the language its wide
+application range.
 
 For a detailed description of the whole Python/C API, see the separate
 :ref:`c-api-index`.

Doc/library/index.rst

@@ -1,16 +1,18 @@
 .. _library-index:
 
 ###############################
-  The Python Standard Library
+  The Python standard library
 ###############################
 
-While :ref:`reference-index` describes the exact syntax and
-semantics of the Python language, this library reference manual
-describes the standard library that is distributed with Python. It also
-describes some of the optional components that are commonly included
-in Python distributions.
+This library reference manual describes the standard library
+distributed with Python. It also describes some of the optional
+components that are commonly included in Python distributions.
 
-Python's standard library is very extensive, offering a wide range of
+Elsewhere, :ref:`reference-index` describes the exact syntax and
+semantics of the Python language, and :ref:`builtins-index` describes
+the built-in functions.
+
+Python's standard library is extensive, offering a wide range of
 facilities as indicated by the long table of contents listed below. The
 library contains built-in modules (written in C) that provide access to
 system functionality such as file I/O that would otherwise be
@@ -39,12 +41,6 @@ the `Python Package Index <https://pypi.org>`_.
    :maxdepth: 2
 
    intro.rst
-   functions.rst
-   constants.rst
-   stdtypes.rst
-   exceptions.rst
-   threadsafety.rst
-   time-complexity.rst
 
    text.rst
    binary.rst

Doc/library/intro.rst

@@ -4,48 +4,34 @@
 Introduction
 ************
 
-The "Python library" contains several different kinds of components.
-
-It contains data types that would normally be considered part of the "core" of a
-language, such as numbers and lists.  For these types, the Python language core
-defines the form of literals and places some constraints on their semantics, but
-does not fully define the semantics.  (On the other hand, the language core does
-define syntactic properties like the spelling and priorities of operators.)
-
-The library also contains built-in functions and exceptions --- objects that can
-be used by all Python code without the need of an :keyword:`import` statement.
-Some of these are defined by the core language, but many are not essential for
-the core semantics and are only described here.
-
-The bulk of the library, however, consists of a collection of modules. There are
-many ways to dissect this collection.  Some modules are written in C and built
-in to the Python interpreter; others are written in Python and imported in
-source form.  Some modules provide interfaces that are highly specific to
+The Python standard library consists of a collection of modules. There are
+many ways to dissect this collection.  Most modules are written in Python,
+but some are written in C. All can be imported into your program to add
+functionality.  Some modules provide interfaces that are highly specific to
 Python, like printing a stack trace; some provide interfaces that are specific
 to particular operating systems, such as access to specific hardware; others
 provide interfaces that are specific to a particular application domain, like
-the World Wide Web. Some modules are available in all versions and ports of
+web development. Some modules are available in all versions and ports of
 Python; others are only available when the underlying system supports or
 requires them; yet others are available only when a particular configuration
 option was chosen at the time when Python was compiled and installed.
 
-This manual is organized "from the inside out:" it first describes the built-in
-functions, data types and exceptions, and finally the modules, grouped in
-chapters of related modules.
-
-This means that if you start reading this manual from the start, and skip to the
+If you start reading this manual from the start, and skip to the
 next chapter when you get bored, you will get a reasonable overview of the
 available modules and application areas that are supported by the Python
 library.  Of course, you don't *have* to read it like a novel --- you can also
 browse the table of contents (in front of the manual), or look for a specific
 function, module or term in the index (in the back).  And finally, if you enjoy
-learning about random subjects, you choose a random page number (see module
-:mod:`random`) and read a section or two.  Regardless of the order in which you
-read the sections of this manual, it helps to start with chapter
-:ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with
-this material.
+learning about random subjects, you choose a random page
+and read a section or two.  Regardless of the order in which you
+read the sections of this manual, it helps to first read
+:ref:`built-in-funcs`, as the remainder of this section
+assumes familiarity with this material.
+
+.. seealso::
 
-Let the show begin!
+   The built-in functions and classes (which can be used without an
+   :keyword:`import` statement) are described in :ref:`builtins-index`.
 
 
 .. _availability:

Doc/library/xml.dom.minidom.rst

@@ -187,13 +187,23 @@ module documentation.  This section lists the differences between the API and
 
    The *standalone* argument behaves exactly as in :meth:`writexml`.
 
+   No indentation is added inside an element
+   which is marked with ``xml:space="preserve"``,
+   which is declared in the DTD as not having element content,
+   or, in absence of such declaration, which contains text,
+   because this would change its content.
+
    .. versionchanged:: 3.8
       The :meth:`toprettyxml` method now preserves the attribute order specified
       by the user.
 
    .. versionchanged:: 3.9
       The *standalone* parameter was added.
 
+   .. versionchanged:: next
+      Whitespace is no longer added inside an element with mixed content
+      or marked with ``xml:space="preserve"``.
+
 .. _dom-example:
 
 DOM Example
@@ -274,6 +284,10 @@ rules apply:
      and produced an invalid document,
      but removing an absent attribute raised :exc:`~xml.dom.NotFoundErr`.
 
+  .. versionchanged:: next
+     Namespaces are now validated in the factory methods and when setting
+     :attr:`~xml.dom.Node.prefix` of an attribute.
+
 The following interfaces have no implementation in :mod:`!xml.dom.minidom`:
 
 * :class:`DOMTimeStamp`

Doc/library/xml.dom.rst

@@ -687,6 +687,10 @@ inherits properties from :class:`Node`.
    :meth:`~Node.insertBefore` or :meth:`~Node.appendChild`.
 
    Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+   Raise :exc:`NamespaceErr` if the qualified name is malformed,
+   if it has a prefix and the namespace URI is empty,
+   or if the prefix is ``'xml'``
+   and the namespace URI is not the XML namespace.
 
 
 .. method:: Document.createTextNode(data)
@@ -740,6 +744,11 @@ inherits properties from :class:`Node`.
    :class:`Element` object to use the newly created attribute instance.
 
    Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+   Raise :exc:`NamespaceErr` if the qualified name is malformed,
+   if it has a prefix and the namespace URI is empty,
+   if the prefix is ``'xml'`` and the namespace URI is not the XML namespace,
+   or if the name or the prefix is ``'xmlns'``
+   and the namespace URI is not the XMLNS namespace, or vice versa.
 
 
 .. method:: Document.getElementById(id)
@@ -905,6 +914,11 @@ of that class.
    Note that a qname is the whole attribute name.  This is different than above.
 
    Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+   Raise :exc:`NamespaceErr` if the qualified name is malformed,
+   if it has a prefix and the namespace URI is empty,
+   if the prefix is ``'xml'`` and the namespace URI is not the XML namespace,
+   or if the name or the prefix is ``'xmlns'``
+   and the namespace URI is not the XMLNS namespace, or vice versa.
 
 
 .. _dom-attr-objects: