Merge branch 'main' into _nb_ops

Doc/c-api/typeobj.rst

@@ -1697,7 +1697,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
        to a pointer, are valid C99 address constants.
 
        However, the unary '&' operator applied to a non-static variable
-       like :c:func:`PyBaseObject_Type` is not required to produce an address
+       like :c:data:`PyBaseObject_Type` is not required to produce an address
        constant.  Compilers may support this (gcc does), MSVC does not.
        Both compilers are strictly standard conforming in this particular
        behavior.

Doc/conf.py

@@ -157,6 +157,77 @@
     ('envvar', 'USER'),
     ('envvar', 'USERNAME'),
     ('envvar', 'USERPROFILE'),
+]
+
+# Temporary undocumented names.
+# In future this list must be empty.
+nitpick_ignore += [
+    # C API: Standard Python exception classes
+    ('c:data', 'PyExc_ArithmeticError'),
+    ('c:data', 'PyExc_AssertionError'),
+    ('c:data', 'PyExc_AttributeError'),
+    ('c:data', 'PyExc_BaseException'),
+    ('c:data', 'PyExc_BlockingIOError'),
+    ('c:data', 'PyExc_BrokenPipeError'),
+    ('c:data', 'PyExc_BufferError'),
+    ('c:data', 'PyExc_ChildProcessError'),
+    ('c:data', 'PyExc_ConnectionAbortedError'),
+    ('c:data', 'PyExc_ConnectionError'),
+    ('c:data', 'PyExc_ConnectionRefusedError'),
+    ('c:data', 'PyExc_ConnectionResetError'),
+    ('c:data', 'PyExc_EOFError'),
+    ('c:data', 'PyExc_Exception'),
+    ('c:data', 'PyExc_FileExistsError'),
+    ('c:data', 'PyExc_FileNotFoundError'),
+    ('c:data', 'PyExc_FloatingPointError'),
+    ('c:data', 'PyExc_GeneratorExit'),
+    ('c:data', 'PyExc_ImportError'),
+    ('c:data', 'PyExc_IndentationError'),
+    ('c:data', 'PyExc_IndexError'),
+    ('c:data', 'PyExc_InterruptedError'),
+    ('c:data', 'PyExc_IsADirectoryError'),
+    ('c:data', 'PyExc_KeyboardInterrupt'),
+    ('c:data', 'PyExc_KeyError'),
+    ('c:data', 'PyExc_LookupError'),
+    ('c:data', 'PyExc_MemoryError'),
+    ('c:data', 'PyExc_ModuleNotFoundError'),
+    ('c:data', 'PyExc_NameError'),
+    ('c:data', 'PyExc_NotADirectoryError'),
+    ('c:data', 'PyExc_NotImplementedError'),
+    ('c:data', 'PyExc_OSError'),
+    ('c:data', 'PyExc_OverflowError'),
+    ('c:data', 'PyExc_PermissionError'),
+    ('c:data', 'PyExc_ProcessLookupError'),
+    ('c:data', 'PyExc_RecursionError'),
+    ('c:data', 'PyExc_ReferenceError'),
+    ('c:data', 'PyExc_RuntimeError'),
+    ('c:data', 'PyExc_StopAsyncIteration'),
+    ('c:data', 'PyExc_StopIteration'),
+    ('c:data', 'PyExc_SyntaxError'),
+    ('c:data', 'PyExc_SystemError'),
+    ('c:data', 'PyExc_SystemExit'),
+    ('c:data', 'PyExc_TabError'),
+    ('c:data', 'PyExc_TimeoutError'),
+    ('c:data', 'PyExc_TypeError'),
+    ('c:data', 'PyExc_UnboundLocalError'),
+    ('c:data', 'PyExc_UnicodeDecodeError'),
+    ('c:data', 'PyExc_UnicodeEncodeError'),
+    ('c:data', 'PyExc_UnicodeError'),
+    ('c:data', 'PyExc_UnicodeTranslateError'),
+    ('c:data', 'PyExc_ValueError'),
+    ('c:data', 'PyExc_ZeroDivisionError'),
+    # C API: Standard Python warning classes
+    ('c:data', 'PyExc_BytesWarning'),
+    ('c:data', 'PyExc_DeprecationWarning'),
+    ('c:data', 'PyExc_FutureWarning'),
+    ('c:data', 'PyExc_ImportWarning'),
+    ('c:data', 'PyExc_PendingDeprecationWarning'),
+    ('c:data', 'PyExc_ResourceWarning'),
+    ('c:data', 'PyExc_RuntimeWarning'),
+    ('c:data', 'PyExc_SyntaxWarning'),
+    ('c:data', 'PyExc_UnicodeWarning'),
+    ('c:data', 'PyExc_UserWarning'),
+    ('c:data', 'PyExc_Warning'),
     # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.
@@ -283,8 +354,6 @@
 latex_documents = [
     ('c-api/index', 'c-api.tex',
      'The Python/C API', _stdauthor, 'manual'),
-    ('distributing/index', 'distributing.tex',
-     'Distributing Python Modules', _stdauthor, 'manual'),
     ('extending/index', 'extending.tex',
      'Extending and Embedding Python', _stdauthor, 'manual'),
     ('installing/index', 'installing.tex',

Doc/contents.rst

@@ -11,7 +11,6 @@
    library/index.rst
    extending/index.rst
    c-api/index.rst
-   distributing/index.rst
    installing/index.rst
    howto/index.rst
    faq/index.rst

Doc/distributing/index.rst

@@ -1,174 +1,19 @@
+:orphan:
+
+.. This page is retained solely for existing links to /distributing/index.html.
+   Direct readers to the PPUG instead.
+
 .. _distributing-index:
 
 ###############################
   Distributing Python Modules
 ###############################
 
-:Email: [email protected]
-
-
-As a popular open source development project, Python has an active
-supporting community of contributors and users that also make their software
-available for other Python developers to use under open source license terms.
-
-This allows Python users to share and collaborate effectively, benefiting
-from the solutions others have already created to common (and sometimes
-even rare!) problems, as well as potentially contributing their own
-solutions to the common pool.
-
-This guide covers the distribution part of the process. For a guide to
-installing other Python projects, refer to the
-:ref:`installation guide <installing-index>`.
-
 .. note::
 
-   For corporate and other institutional users, be aware that many
-   organisations have their own policies around using and contributing to
-   open source software. Please take such policies into account when making
-   use of the distribution and installation tools provided with Python.
-
-
-Key terms
-=========
-
-* the `Python Package Index <https://pypi.org>`__ is a public
-  repository of open source licensed packages made available for use by
-  other Python users
-* the `Python Packaging Authority
-  <https://www.pypa.io/>`__ are the group of
-  developers and documentation authors responsible for the maintenance and
-  evolution of the standard packaging tools and the associated metadata and
-  file format standards. They maintain a variety of tools, documentation
-  and issue trackers on `GitHub <https://github.com/pypa>`__.
-* ``distutils`` is the original build and distribution system first added
-  to the Python standard library in 1998. While direct use of ``distutils``
-  is being phased out, it still laid the foundation for the current packaging
-  and distribution infrastructure, and it not only remains part of the
-  standard library, but its name lives on in other ways (such as the name
-  of the mailing list used to coordinate Python packaging standards
-  development).
-* `setuptools`_ is a (largely) drop-in replacement for ``distutils`` first
-  published in 2004. Its most notable addition over the unmodified
-  ``distutils`` tools was the ability to declare dependencies on other
-  packages. It is currently recommended as a more regularly updated
-  alternative to ``distutils`` that offers consistent support for more
-  recent packaging standards across a wide range of Python versions.
-* `wheel`_ (in this context) is a project that adds the ``bdist_wheel``
-  command to ``distutils``/`setuptools`_. This produces a cross platform
-  binary packaging format (called "wheels" or "wheel files" and defined in
-  :pep:`427`) that allows Python libraries, even those including binary
-  extensions, to be installed on a system without needing to be built
-  locally.
-
-.. _setuptools: https://setuptools.readthedocs.io/en/latest/
-.. _wheel: https://wheel.readthedocs.io/
-
-Open source licensing and collaboration
-=======================================
-
-In most parts of the world, software is automatically covered by copyright.
-This means that other developers require explicit permission to copy, use,
-modify and redistribute the software.
-
-Open source licensing is a way of explicitly granting such permission in a
-relatively consistent way, allowing developers to share and collaborate
-efficiently by making common solutions to various problems freely available.
-This leaves many developers free to spend more time focusing on the problems
-that are relatively unique to their specific situation.
-
-The distribution tools provided with Python are designed to make it
-reasonably straightforward for developers to make their own contributions
-back to that common pool of software if they choose to do so.
-
-The same distribution tools can also be used to distribute software within
-an organisation, regardless of whether that software is published as open
-source software or not.
-
-
-Installing the tools
-====================
-
-The standard library does not include build tools that support modern
-Python packaging standards, as the core development team has found that it
-is important to have standard tools that work consistently, even on older
-versions of Python.
-
-The currently recommended build and distribution tools can be installed
-by invoking the ``pip`` module at the command line::
-
-    python -m pip install setuptools wheel twine
-
-.. note::
-
-   For POSIX users (including macOS and Linux users), these instructions
-   assume the use of a :term:`virtual environment`.
-
-   For Windows users, these instructions assume that the option to
-   adjust the system PATH environment variable was selected when installing
-   Python.
-
-The Python Packaging User Guide includes more details on the `currently
-recommended tools`_.
-
-.. _currently recommended tools: https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations
-
-.. index::
-   single: Python Package Index (PyPI)
-   single: PyPI; (see Python Package Index (PyPI))
-
-.. _publishing-python-packages:
-
-Reading the Python Packaging User Guide
-=======================================
-
-The Python Packaging User Guide covers the various key steps and elements
-involved in creating and publishing a project:
-
-* `Project structure`_
-* `Building and packaging the project`_
-* `Uploading the project to the Python Package Index`_
-* `The .pypirc file`_
-
-.. _Project structure: https://packaging.python.org/tutorials/packaging-projects/#packaging-python-projects
-.. _Building and packaging the project: https://packaging.python.org/tutorials/packaging-projects/#creating-the-package-files
-.. _Uploading the project to the Python Package Index: https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives
-.. _The .pypirc file: https://packaging.python.org/specifications/pypirc/
-
-
-How do I...?
-============
-
-These are quick answers or links for some common tasks.
-
-... choose a name for my project?
----------------------------------
-
-This isn't an easy topic, but here are a few tips:
-
-* check the Python Package Index to see if the name is already in use
-* check popular hosting sites like GitHub, Bitbucket, etc to see if there
-  is already a project with that name
-* check what comes up in a web search for the name you're considering
-* avoid particularly common words, especially ones with multiple meanings,
-  as they can make it difficult for users to find your software when
-  searching for it
-
-
-... create and distribute binary extensions?
---------------------------------------------
-
-This is actually quite a complex topic, with a variety of alternatives
-available depending on exactly what you're aiming to achieve. See the
-Python Packaging User Guide for more information and recommendations.
-
-.. seealso::
-
-   `Python Packaging User Guide: Binary Extensions
-   <https://packaging.python.org/guides/packaging-binary-extensions/>`__
-
-.. other topics:
+   Information and guidance on distributing Python modules and packages
+   has been moved to the `Python Packaging User Guide`_,
+   and the tutorial on `packaging Python projects`_.
 
-   Once the Development & Deployment part of PPUG is fleshed out, some of
-   those sections should be linked from new questions here (most notably,
-   we should have a question about avoiding depending on PyPI that links to
-   https://packaging.python.org/en/latest/mirrors/)
+   .. _Python Packaging User Guide: https://packaging.python.org/
+   .. _packaging Python projects: https://packaging.python.org/en/latest/tutorials/packaging-projects/

Doc/extending/extending.rst

@@ -242,7 +242,7 @@ needed to ensure that it will not be discarded, causing :c:data:`!SpamError` to
 become a dangling pointer. Should it become a dangling pointer, C code which
 raises the exception could cause a core dump or other unintended side effects.
 
-We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in this
+We discuss the use of :c:macro:`PyMODINIT_FUNC` as a function return type later in this
 sample.
 
 The :exc:`!spam.error` exception can be raised in your extension module using a
@@ -363,7 +363,7 @@ only non-\ ``static`` item defined in the module file::
        return PyModule_Create(&spammodule);
    }
 
-Note that PyMODINIT_FUNC declares the function as ``PyObject *`` return type,
+Note that :c:macro:`PyMODINIT_FUNC` declares the function as ``PyObject *`` return type,
 declares any special linkage declarations required by the platform, and for C++
 declares the function as ``extern "C"``.
 

Doc/installing/index.rst

@@ -19,7 +19,9 @@ solutions to the common pool.
 
 This guide covers the installation part of the process. For a guide to
 creating and sharing your own Python projects, refer to the
-:ref:`distribution guide <distributing-index>`.
+`Python packaging user guide`_.
+
+.. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/
 
 .. note::
 

Doc/tutorial/venv.rst

@@ -207,4 +207,6 @@ necessary packages with ``install -r``:
 ``pip`` has many more options.  Consult the :ref:`installing-index`
 guide for complete documentation for ``pip``.  When you've written
 a package and want to make it available on the Python Package Index,
-consult the :ref:`distributing-index` guide.
+consult the `Python packaging user guide`_.
+
+.. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/

Doc/using/configure.rst

@@ -746,8 +746,8 @@ Example on Linux x86-64::
 At the beginning of the files, C extensions are built as built-in modules.
 Extensions defined after the ``*shared*`` marker are built as dynamic libraries.
 
-The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_API()` and
-:c:macro:`PyMODINIT_FUNC()` macros of :file:`Include/pyport.h` are defined
+The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_DATA()` and
+:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/pyport.h` are defined
 differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:
 
 * Use ``Py_EXPORTED_SYMBOL`` if the ``Py_BUILD_CORE_MODULE`` is defined

Doc/whatsnew/2.2.rst

@@ -1109,7 +1109,7 @@ code, none of the changes described here will affect you very much.
   definition tables to simplify implementation of methods with no arguments or a
   single untyped argument. Calling such methods is more efficient than calling a
   corresponding method that uses :c:macro:`METH_VARARGS`.  Also, the old
-  :c:macro:`METH_OLDARGS` style of writing C methods is  now officially deprecated.
+  :c:macro:`!METH_OLDARGS` style of writing C methods is  now officially deprecated.
 
 * Two new wrapper functions, :c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf`
   were added to provide  cross-platform implementations for the relatively new

Doc/whatsnew/2.3.rst

@@ -1886,7 +1886,7 @@ Changes to Python's build process and to the C API include:
   (:file:`libpython2.3.so`) by supplying :option:`!--enable-shared` when running
   Python's :program:`configure` script.  (Contributed by Ondrej Palkovsky.)
 
-* The :c:macro:`DL_EXPORT` and :c:macro:`DL_IMPORT` macros are now deprecated.
+* The :c:macro:`!DL_EXPORT` and :c:macro:`!DL_IMPORT` macros are now deprecated.
   Initialization functions for Python extension modules should now be declared
   using the new macro :c:macro:`PyMODINIT_FUNC`, while the Python core will
   generally use the :c:macro:`PyAPI_FUNC` and :c:macro:`PyAPI_DATA` macros.

Doc/whatsnew/2.4.rst

@@ -1476,7 +1476,7 @@ Some of the changes to Python's build process and to the C API are:
   :c:func:`PyArg_ParseTupleAndKeywords` but takes a  :c:type:`va_list` instead of a
   number of arguments. (Contributed by Greg Chapman.)
 
-* A new method flag, :c:macro:`METH_COEXISTS`, allows a function defined in slots
+* A new method flag, :c:macro:`METH_COEXIST`, allows a function defined in slots
   to co-exist with a :c:type:`PyCFunction` having the same name.  This can halve
   the access time for a method such as :meth:`set.__contains__`.  (Contributed by
   Raymond Hettinger.)

Doc/whatsnew/2.6.rst

@@ -3060,9 +3060,9 @@ Changes to Python's build process and to the C API include:
 
 * Some macros were renamed in both 3.0 and 2.6 to make it clearer that
   they are macros,
-  not functions.  :c:macro:`Py_Size()` became :c:macro:`Py_SIZE()`,
-  :c:macro:`Py_Type()` became :c:macro:`Py_TYPE()`, and
-  :c:macro:`Py_Refcnt()` became :c:macro:`Py_REFCNT()`.
+  not functions.  :c:macro:`!Py_Size()` became :c:macro:`Py_SIZE()`,
+  :c:macro:`!Py_Type()` became :c:macro:`Py_TYPE()`, and
+  :c:macro:`!Py_Refcnt()` became :c:macro:`Py_REFCNT()`.
   The mixed-case macros are still available
   in Python 2.6 for backward compatibility.
   (:issue:`1629`)