Merge pull request #1450 from jeanas/distributing-guide

Start updating distributing-packages-using-setuptools guide

Author: chrysle

source/guides/distributing-packages-using-setuptools.rst

@@ -4,6 +4,9 @@
 Packaging and distributing projects
 ===================================
 
+:Page Status: Outdated
+:Last Reviewed: 2023-12-14
+
 This section covers some additional details on configuring, packaging and
 distributing Python projects with ``setuptools`` that aren't covered by the
 introductory tutorial in :doc:`/tutorials/packaging-projects`.  It still assumes
@@ -153,206 +156,21 @@ As mentioned above, the primary feature of :file:`setup.py` is that it contains
 a global ``setup()`` function.  The keyword arguments to this function are how
 specific details of your project are defined.
 
-The most relevant arguments are explained below. Most of the snippets given are
+Some are temporarily explained below until their information is moved elsewhere.
+The full list can be found :doc:`in the setuptools documentation
+<setuptools:references/keywords>`.
+
+Most of the snippets given are
 taken from the `setup.py
 <https://github.com/pypa/sampleproject/blob/db5806e0a3204034c51b1c00dde7d5eb3fa2532e/setup.py>`_ contained in the
 `PyPA sample project <https://github.com/pypa/sampleproject>`_.
 
 
-.. _`setup() name`:
-
-``name``
-~~~~~~~~
-
-::
-
-  name='sample',
-
-This is the name of your project, determining how your project is listed on
-:term:`PyPI <Python Package Index (PyPI)>`.  Per :pep:`508`, valid project
-names must:
-
-- Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``),
-  and/or periods (``.``), and
-- Start & end with an ASCII letter or digit.
-
-Comparison of project names is case insensitive and treats arbitrarily-long
-runs of underscores, hyphens, and/or periods as equal.  For example, if you
-register a project named ``cool-stuff``, users will be able to download it or
-declare a dependency on it using any of the following spellings::
-
-    Cool-Stuff
-    cool.stuff
-    COOL_STUFF
-    CoOl__-.-__sTuFF
-
-
-``version``
-~~~~~~~~~~~
-
-::
-
-  version='1.2.0',
-
-This is the current version of your project, allowing your users to determine whether or not
-they have the latest version, and to indicate which specific versions they've tested their own
-software against.
-
-Versions are displayed on :term:`PyPI <Python Package Index (PyPI)>` for each release if you
-publish your project.
 
 See :ref:`Choosing a versioning scheme` for more information on ways to use versions to convey
 compatibility information to your users.
 
-If the project code itself needs run-time access to the version, the simplest
-way is to keep the version in both :file:`setup.py` and your code. If you'd
-rather not duplicate the value, there are a few ways to manage this. See the
-":ref:`Single sourcing the version`" Advanced Topics section.
-
-.. _`description`:
-
-``description``
-~~~~~~~~~~~~~~~
-
-::
-
-  description='A sample Python project',
-  long_description=long_description,
-  long_description_content_type='text/x-rst',
-
-Give a short and long description for your project.
-
-These values will be displayed on :term:`PyPI <Python Package Index (PyPI)>`
-if you publish your project. On ``pypi.org``, the user interface displays
-``description`` in the grey banner and ``long_description`` in the section
-named "Project Description".
-
-``description`` is also displayed in lists of projects. For example, it's
-visible in the search results pages such as https://pypi.org/search/?q=jupyter,
-the front-page lists of trending projects and new releases, and the list of
-projects you maintain within your account profile (such as
-https://pypi.org/user/jaraco/).
-
-A :ref:`content type <core-metadata-description-content-type>`
-can be specified with the ``long_description_content_type`` argument, which can
-be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, corresponding
-to no formatting, `reStructuredText (reST)
-<https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names>`_,
-and the GitHub-flavored Markdown dialect of `Markdown
-<https://daringfireball.net/projects/markdown/>`_ respectively.
-
-``url``
-~~~~~~~
-
-::
-
-  url='https://github.com/pypa/sampleproject',
-
-
-Give a homepage URL for your project.
-
-
-``author``
-~~~~~~~~~~
-
-::
-
-  author='A. Random Developer',
-  author_email='author@example.com',
-
-Provide details about the author.
-
-
-``license``
-~~~~~~~~~~~
-
-::
-
-  license='MIT',
-
-The ``license`` argument doesn't have to indicate the license under
-which your package is being released, although you may optionally do
-so if you want.  If you're using a standard, well-known license, then
-your main indication can and should be via the ``classifiers``
-argument. Classifiers exist for all major open-source licenses.
-
-The ``license`` argument is more typically used to indicate differences
-from well-known licenses, or to include your own, unique license. As a
-general rule, it's a good idea to use a standard, well-known license,
-both to avoid confusion and because some organizations avoid software
-whose license is unapproved.
-
-
-``classifiers``
-~~~~~~~~~~~~~~~
-
-::
-
-  classifiers=[
-      # How mature is this project? Common values are
-      #   3 - Alpha
-      #   4 - Beta
-      #   5 - Production/Stable
-      'Development Status :: 3 - Alpha',
-
-      # Indicate who your project is intended for
-      'Intended Audience :: Developers',
-      'Topic :: Software Development :: Build Tools',
-
-      # Pick your license as you wish (should match "license" above)
-      'License :: OSI Approved :: MIT License',
-
-      # Specify the Python versions you support here. In particular, ensure
-      # that you indicate whether you support Python 2, Python 3 or both.
-      'Programming Language :: Python :: 2',
-      'Programming Language :: Python :: 2.7',
-      'Programming Language :: Python :: 3',
-      'Programming Language :: Python :: 3.6',
-      'Programming Language :: Python :: 3.7',
-      'Programming Language :: Python :: 3.8',
-      'Programming Language :: Python :: 3.9',
-  ],
-
-Provide a list of classifiers that categorize your project. For a full listing,
-see https://pypi.org/classifiers/.
-
-Although the list of classifiers is often used to declare what Python versions
-a project supports, this information is only used for searching & browsing
-projects on PyPI, not for installing projects.  To actually restrict what
-Python versions a project can be installed on, use the :ref:`python_requires`
-argument.
-
-To prevent a package from being uploaded to PyPI, use the special
-``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages with
-classifiers beginning with ``"Private ::'``.
-
-
-``keywords``
-~~~~~~~~~~~~
-
-::
 
-  keywords='sample setuptools development',
-
-List keywords that describe your project.
-
-
-``project_urls``
-~~~~~~~~~~~~~~~~
-
-::
-
-  project_urls={
-      'Documentation': 'https://packaging.python.org/tutorials/distributing-packages/',
-      'Funding': 'https://donate.pypi.org',
-      'Say Thanks!': 'http://saythanks.io/to/example',
-      'Source': 'https://github.com/pypa/sampleproject/',
-      'Tracker': 'https://github.com/pypa/sampleproject/issues',
-  },
-
-List additional relevant URLs about your project. This is the place to link to
-bug trackers, source repositories, or where to support package development.
-The string of the key is the exact text that will be displayed on PyPI.
 
 
 ``packages``
@@ -396,38 +214,6 @@ specification that is used to install its dependencies.
 For more on using "install_requires" see :ref:`install_requires vs Requirements files`.
 
 
-.. _python_requires:
-
-``python_requires``
-~~~~~~~~~~~~~~~~~~~
-
-If your project only runs on certain Python versions, setting the
-``python_requires`` argument to the appropriate :pep:`440` version specifier
-string will prevent :ref:`pip` from installing the project on other Python
-versions.  For example, if your package is for Python 3+ only, write::
-
-    python_requires='>=3',
-
-If your package is for Python 2.6, 2.7, and all versions of Python 3 starting
-with 3.3, write::
-
-    python_requires='>=2.6, !=3.0.*, !=3.1.*, !=3.2.*',
-
-And so on.
-
-.. note::
-
-    Support for this feature is relatively recent.  Your project's source
-    distributions and wheels (see :ref:`Packaging Your Project`) must be built
-    using at least version 24.2.0 of :ref:`setuptools` in order for the
-    ``python_requires`` argument to be recognized and the appropriate metadata
-    generated.
-
-    In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the
-    ``python_requires`` metadata.  Users with earlier versions of pip will be
-    able to download & install projects on any Python version regardless of the
-    projects' ``python_requires`` values.
-
 
 .. _`Package Data`:
 
@@ -500,47 +286,8 @@ keyword for pointing to pre-made scripts to install, the recommended approach to
 achieve cross-platform compatibility is to use :ref:`console_scripts` entry
 points (see below).
 
-``entry_points``
-~~~~~~~~~~~~~~~~
-
-::
-
-  entry_points={
-    ...
-  },
 
 
-Use this keyword to specify any plugins that your project provides for any named
-entry points that may be defined by your project or others that you depend on.
-
-For more information, see the section on
-:ref:`Advertising Behavior <setuptools:dynamic discovery of services and plugins>`
-from the :ref:`setuptools` docs.
-
-The most commonly used entry point is "console_scripts" (see below).
-
-.. _`console_scripts`:
-
-``console_scripts``
-*******************
-
-::
-
-  entry_points={
-      'console_scripts': [
-          'sample=sample:main',
-      ],
-  },
-
-Use ``console_script``
-:ref:`entry points <setuptools:dynamic discovery of services and plugins>`
-to register your script interfaces. You can then let the toolchain handle the
-work of turning these interfaces into actual scripts [2]_.  The scripts will be
-generated during the install of your :term:`distribution <Distribution
-Package>`.
-
-For more information, see :doc:`Entry Points <setuptools:userguide/entry_point>`
-from the :doc:`setuptools docs <setuptools:index>`.
 
 .. _`Choosing a versioning scheme`:
 
@@ -956,10 +703,3 @@ your project to appear on the site.
        access. :ref:`pip` is currently considering changing this by `making user
        installs the default behavior
        <https://github.com/pypa/pip/issues/1668>`_.
-
-
-.. [2] Specifically, the "console_script" approach generates ``.exe`` files on
-       Windows, which are necessary because the OS special-cases ``.exe`` files.
-       Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for
-       Windows <397>` allow scripts to
-       be used in many cases, but not all.

source/guides/single-sourcing-package-version.rst

@@ -4,6 +4,7 @@
 Single-sourcing the package version
 ===================================
 
+.. todo:: Update this page for build backends other than setuptools.
 
 There are many techniques to maintain a single source of truth for the version
 number of your project: