Merge branch 'master' into feature/34632-importlib-metadata

Author: jaraco

Doc/c-api/unicode.rst

@@ -22,14 +22,14 @@ in the Unicode object.  The :c:type:`Py_UNICODE*` representation is deprecated
 and inefficient; it should be avoided in performance- or memory-sensitive
 situations.
 
-Due to the transition between the old APIs and the new APIs, unicode objects
+Due to the transition between the old APIs and the new APIs, Unicode objects
 can internally be in two states depending on how they were created:
 
-* "canonical" unicode objects are all objects created by a non-deprecated
-  unicode API.  They use the most efficient representation allowed by the
+* "canonical" Unicode objects are all objects created by a non-deprecated
+  Unicode API.  They use the most efficient representation allowed by the
   implementation.
 
-* "legacy" unicode objects have been created through one of the deprecated
+* "legacy" Unicode objects have been created through one of the deprecated
   APIs (typically :c:func:`PyUnicode_FromUnicode`) and only bear the
   :c:type:`Py_UNICODE*` representation; you will have to call
   :c:func:`PyUnicode_READY` on them before calling any other API.
@@ -152,7 +152,7 @@ access internal read-only data of Unicode objects:
 
 .. c:function:: void* PyUnicode_DATA(PyObject *o)
 
-   Return a void pointer to the raw unicode buffer.  *o* has to be a Unicode
+   Return a void pointer to the raw Unicode buffer.  *o* has to be a Unicode
    object in the "canonical" representation (not checked).
 
    .. versionadded:: 3.3
@@ -430,7 +430,7 @@ APIs:
 .. c:function:: PyObject* PyUnicode_FromFormat(const char *format, ...)
 
    Take a C :c:func:`printf`\ -style *format* string and a variable number of
-   arguments, calculate the size of the resulting Python unicode string and return
+   arguments, calculate the size of the resulting Python Unicode string and return
    a string with the values formatted into it.  The variable arguments must be C
    types and must correspond exactly to the format characters in the *format*
    ASCII-encoded string. The following format characters are allowed:
@@ -504,9 +504,9 @@ APIs:
    | :attr:`%A`        | PyObject\*          | The result of calling          |
    |                   |                     | :func:`ascii`.                 |
    +-------------------+---------------------+--------------------------------+
-   | :attr:`%U`        | PyObject\*          | A unicode object.              |
+   | :attr:`%U`        | PyObject\*          | A Unicode object.              |
    +-------------------+---------------------+--------------------------------+
-   | :attr:`%V`        | PyObject\*,         | A unicode object (which may be |
+   | :attr:`%V`        | PyObject\*,         | A Unicode object (which may be |
    |                   | const char\*        | *NULL*) and a null-terminated  |
    |                   |                     | C character array as a second  |
    |                   |                     | parameter (which will be used, |
@@ -1670,7 +1670,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 
 .. c:function:: int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)
 
-   Compare a unicode object, *uni*, with *string* and return ``-1``, ``0``, ``1`` for less
+   Compare a Unicode object, *uni*, with *string* and return ``-1``, ``0``, ``1`` for less
    than, equal, and greater than, respectively. It is best to pass only
    ASCII-encoded strings, but the function interprets the input string as
    ISO-8859-1 if it contains non-ASCII characters.
@@ -1680,7 +1680,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 
 .. c:function:: PyObject* PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
 
-   Rich compare two unicode strings and return one of the following:
+   Rich compare two Unicode strings and return one of the following:
 
    * ``NULL`` in case an exception was raised
    * :const:`Py_True` or :const:`Py_False` for successful comparisons
@@ -1708,7 +1708,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 .. c:function:: void PyUnicode_InternInPlace(PyObject **string)
 
    Intern the argument *\*string* in place.  The argument must be the address of a
-   pointer variable pointing to a Python unicode string object.  If there is an
+   pointer variable pointing to a Python Unicode string object.  If there is an
    existing interned string that is the same as *\*string*, it sets *\*string* to
    it (decrementing the reference count of the old string object and incrementing
    the reference count of the interned string object), otherwise it leaves
@@ -1721,6 +1721,6 @@ They all return *NULL* or ``-1`` if an exception occurs.
 .. c:function:: PyObject* PyUnicode_InternFromString(const char *v)
 
    A combination of :c:func:`PyUnicode_FromString` and
-   :c:func:`PyUnicode_InternInPlace`, returning either a new unicode string
+   :c:func:`PyUnicode_InternInPlace`, returning either a new Unicode string
    object that has been interned, or a new ("owned") reference to an earlier
    interned string object with the same value.

Doc/distutils/packageindex.rst

@@ -8,246 +8,10 @@
 The Python Package Index (PyPI)
 *******************************
 
-The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>`
-describing distributions packaged with distutils, as well as package data like
-distribution files if a package author wishes.
-
-Distutils provides the :command:`register` and :command:`upload` commands for
-pushing meta-data and distribution files to PyPI, respectively.  See
-:ref:`package-commands` for information on these commands.
-
-
-PyPI overview
-=============
-
-PyPI lets you submit any number of versions of your distribution to the index.
-If you alter the meta-data for a particular version, you can submit it again
-and the index will be updated.
-
-PyPI holds a record for each (name, version) combination submitted.  The first
-user to submit information for a given name is designated the Owner of that
-name.  Changes can be submitted through the :command:`register` command or
-through the web interface.  Owners can designate other users as Owners or
-Maintainers.  Maintainers can edit the package information, but not designate
-new Owners or Maintainers.
-
-By default PyPI displays only the newest version of a given package.  The web
-interface lets one change this default behavior and manually select which
-versions to display and hide.
-
-For each version, PyPI displays a home page.  The home page is created from
-the ``long_description`` which can be submitted via the :command:`register`
-command.  See :ref:`package-display` for more information.
-
-
-.. _package-commands:
-
-Distutils commands
-==================
-
-Distutils exposes two commands for submitting package data to PyPI: the
-:ref:`register <package-register>` command for submitting meta-data to PyPI
-and the :ref:`upload <package-upload>` command for submitting distribution
-files.  Both commands read configuration data from a special file called a
-:ref:`.pypirc file <pypirc>`.
-
-
-.. _package-register:
-
-The ``register`` command
-------------------------
-
-The distutils command :command:`register` is used to submit your distribution's
-meta-data to an index server. It is invoked as follows::
-
-    python setup.py register
-
-Distutils will respond with the following prompt::
-
-    running register
-    We need to know who you are, so please choose either:
-        1. use your existing login,
-        2. register as a new user,
-        3. have the server generate a new password for you (and email it to you), or
-        4. quit
-    Your selection [default 1]:
-
-Note: if your username and password are saved locally, you will not see this
-menu.  Also, refer to :ref:`pypirc` for how to store your credentials in a
-:file:`.pypirc` file.
-
-If you have not registered with PyPI, then you will need to do so now. You
-should choose option 2, and enter your details as required. Soon after
-submitting your details, you will receive an email which will be used to confirm
-your registration.
-
-Once you are registered, you may choose option 1 from the menu. You will be
-prompted for your PyPI username and password, and :command:`register` will then
-submit your meta-data to the index.
-
-See :ref:`package-cmdoptions` for options to the :command:`register` command.
-
-
-.. _package-upload:
-
-The ``upload`` command
-----------------------
-
-The distutils command :command:`upload` pushes the distribution files to PyPI.
-
-The command is invoked immediately after building one or more distribution
-files.  For example, the command ::
-
-    python setup.py sdist bdist_wininst upload
-
-will cause the source distribution and the Windows installer to be uploaded to
-PyPI.  Note that these will be uploaded even if they are built using an earlier
-invocation of :file:`setup.py`, but that only distributions named on the command
-line for the invocation including the :command:`upload` command are uploaded.
-
-If a :command:`register` command was previously called in the same command,
-and if the password was entered in the prompt, :command:`upload` will reuse the
-entered password.  This is useful if you do not want to store a password in
-clear text in a :file:`.pypirc` file.
-
-You can use the ``--sign`` option to tell :command:`upload` to sign each
-uploaded file using GPG (GNU Privacy Guard).  The  :program:`gpg` program must
-be available for execution on the system :envvar:`PATH`.  You can also specify
-which key to use for signing using the ``--identity=name`` option.
-
-See :ref:`package-cmdoptions` for additional options to the :command:`upload`
-command.
-
-
-.. _package-cmdoptions:
-
-Additional command options
---------------------------
-
-This section describes options common to both the :command:`register` and
-:command:`upload` commands.
-
-The ``--repository`` or ``-r`` option lets you specify a PyPI server
-different from the default.  For example::
-
-    python setup.py sdist bdist_wininst upload -r https://example.com/pypi
-
-For convenience, a name can be used in place of the URL when the
-:file:`.pypirc` file is configured to do so.  For example::
-
-    python setup.py register -r other
-
-See :ref:`pypirc` for more information on defining alternate servers.
-
-The ``--show-response`` option displays the full response text from the PyPI
-server, which is useful when debugging problems with registering and uploading.
-
-
-.. index::
-   single: .pypirc file
-   single: Python Package Index (PyPI); .pypirc file
-
-.. _pypirc:
-
-The ``.pypirc`` file
---------------------
-
-The :command:`register` and :command:`upload` commands both check for the
-existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`.
-If this file exists, the command uses the username, password, and repository
-URL configured in the file.  The format of a :file:`.pypirc` file is as
-follows:
-
-.. code-block:: ini
-
-    [distutils]
-    index-servers =
-        pypi
-
-    [pypi]
-    repository: <repository-url>
-    username: <username>
-    password: <password>
-
-The *distutils* section defines an *index-servers* variable that lists the
-name of all sections describing a repository.
-
-Each section describing a repository defines three variables:
-
-- *repository*, that defines the url of the PyPI server. Defaults to
-    ``https://upload.pypi.org/legacy/``.
-- *username*, which is the registered username on the PyPI server.
-- *password*, that will be used to authenticate. If omitted the user
-    will be prompt to type it when needed.
-
-If you want to define another server a new section can be created and
-listed in the *index-servers* variable:
-
-.. code-block:: ini
-
-    [distutils]
-    index-servers =
-        pypi
-        other
-
-    [pypi]
-    repository: <repository-url>
-    username: <username>
-    password: <password>
-
-    [other]
-    repository: https://example.com/pypi
-    username: <username>
-    password: <password>
-
-This allows the :command:`register` and :command:`upload` commands to be
-called with the ``--repository`` option as described in
-:ref:`package-cmdoptions`.
-
-Specifically, you might want to add the `PyPI Test Repository
-<https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate
-testing before doing your first upload to ``PyPI`` itself.
-
-
-.. _package-display:
-
-PyPI package display
-====================
-
-The ``long_description`` field plays a special role at PyPI. It is used by
-the server to display a home page for the registered package.
-
-If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
-syntax for this field, PyPI will parse it and display an HTML output for
-the package home page.
-
-The ``long_description`` field can be attached to a text file located
-in the package::
-
-    from distutils.core import setup
-
-    with open('README.txt') as file:
-        long_description = file.read()
-
-    setup(name='Distutils',
-          long_description=long_description)
-
-In that case, :file:`README.txt` is a regular reStructuredText text file located
-in the root of the package besides :file:`setup.py`.
-
-To prevent registering broken reStructuredText content, you can use the
-:program:`rst2html` program that is provided by the :mod:`docutils` package and
-check the ``long_description`` from the command line:
-
-.. code-block:: shell-session
-
-    $ python setup.py --long-description | rst2html.py > output.html
-
-:mod:`docutils` will display a warning if there's something wrong with your
-syntax.  Because PyPI applies additional checks (e.g. by passing ``--no-raw``
-to ``rst2html.py`` in the command above), being able to run the command above
-without warnings does not guarantee that PyPI will convert the content
-successfully.
+The `Python Package Index (PyPI)`_ stores metadata describing distributions
+packaged with distutils and other publishing tools, as well the distribution
+archives themselves.
 
+Detailed instructions on using PyPI at :ref:`distributing-index`.
 
 .. _Python Package Index (PyPI): https://pypi.org

Doc/distutils/setupscript.rst

@@ -612,9 +612,8 @@ Notes:
     provided, distutils lists it as the author in :file:`PKG-INFO`.
 
 (4)
-    The ``long_description`` field is used by PyPI when you are
-    :ref:`registering <package-register>` a package, to
-    :ref:`build its home page <package-display>`.
+    The ``long_description`` field is used by PyPI when you publish a package,
+    to build its project page.
 
 (5)
     The ``license`` field is a text indicating the license covering the

Doc/howto/unicode.rst

@@ -157,7 +157,7 @@ difficult reading.  `A chronology <http://www.unicode.org/history/>`_ of the
 origin and development of Unicode is also available on the site.
 
 On the Computerphile Youtube channel, Tom Scott briefly
-`discusses the history of Unicode and UTF-8 <https://www.youtube.com/watch?v=MijmeoH9LT4>`
+`discusses the history of Unicode and UTF-8 <https://www.youtube.com/watch?v=MijmeoH9LT4>`_
 (9 minutes 36 seconds).
 
 To help understand the standard, Jukka Korpela has written `an introductory