Skip to content

Commit

Permalink
Merge pull request #1450 from jeanas/distributing-guide
Browse files Browse the repository at this point in the history 
Start updating distributing-packages-using-setuptools guide
  • Loading branch information
@chrysle
chrysle committed Dec 14, 2023
2 parents 9f7c6ae + ad43be9 commit 6454a06
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 280 deletions.
276 changes: 8 additions & 268 deletions source/guides/distributing-packages-using-setuptools.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -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`:

Expand Down Expand Up @@ -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`:

Expand Down Expand Up @@ -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.
1 change: 1 addition & 0 deletions source/guides/single-sourcing-package-version.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit 6454a06

Please sign in to comment.