diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_templates/tidelift-sidebar.html | 6 | ||||
| -rw-r--r-- | docs/build_meta.rst | 13 | ||||
| -rw-r--r-- | docs/conf.py | 113 | ||||
| -rw-r--r-- | docs/pkg_resources.rst | 10 | ||||
| -rw-r--r-- | docs/references/keywords.rst | 11 | ||||
| -rw-r--r-- | docs/requirements.txt | 7 | ||||
| -rw-r--r-- | docs/setuptools.rst | 4 | ||||
| -rw-r--r-- | docs/userguide/declarative_config.rst | 15 | ||||
| -rw-r--r-- | docs/userguide/dependency_management.rst | 248 | ||||
| -rw-r--r-- | docs/userguide/development_mode.rst | 6 | ||||
| -rw-r--r-- | docs/userguide/entry_point.rst | 4 | ||||
| -rw-r--r-- | docs/userguide/package_discovery.rst | 114 | ||||
| -rw-r--r-- | docs/userguide/quickstart.rst | 55 |
13 files changed, 323 insertions, 283 deletions
diff --git a/docs/_templates/tidelift-sidebar.html b/docs/_templates/tidelift-sidebar.html new file mode 100644 index 00000000..ce48f46b --- /dev/null +++ b/docs/_templates/tidelift-sidebar.html @@ -0,0 +1,6 @@ +<h3 class="donation">For Enterprise</h3> + +<p> +Professionally-supported {{ project }} is available with the +<a href="https://tidelift.com/subscription/pkg/pypi-{{ project }}?utm_source=pypi-{{ project }}&utm_medium=referral">Tidelift Subscription</a>. +</p> diff --git a/docs/build_meta.rst b/docs/build_meta.rst index c36e2bab..2ad5ae26 100644 --- a/docs/build_meta.rst +++ b/docs/build_meta.rst @@ -7,7 +7,7 @@ What is it? Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_. -The traditional ``setuptools`` way of packgaging Python modules +The traditional ``setuptools`` way of packaging Python modules uses a ``setup()`` function within the ``setup.py`` script. Commands such as ``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a distribution bundle and ``python setup.py install`` installs the distribution. @@ -67,14 +67,11 @@ specify the package information:: [options] packages = find: -Now generate the distribution. Although the PyPA is still working to -`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_ -to build packages, the `pep517 package <https://pypi.org/project/pep517>`_ -provides this functionality. To build the package:: +Now generate the distribution. To build the package, use +`PyPA build <https://pypa-build.readthedocs.io/en/latest/>`_:: - $ pip install -q pep517 - $ mkdir dist - $ python -m pep517.build . + $ pip install -q build + $ python -m build And now it's done! The ``.whl`` file and ``.tar.gz`` can then be distributed and installed:: diff --git a/docs/conf.py b/docs/conf.py index de9fe3f8..65078c96 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,81 +1,6 @@ -import subprocess -import sys -import os +extensions = ['sphinx.ext.autodoc', 'jaraco.packaging.sphinx', 'rst.linker'] - -# hack to run the bootstrap script so that jaraco.packaging.sphinx -# can invoke setup.py -'READTHEDOCS' in os.environ and subprocess.check_call( - [sys.executable, '-m', 'bootstrap'], - cwd=os.path.join(os.path.dirname(__file__), os.path.pardir), -) - -# -- Project information ----------------------------------------------------- - -github_url = 'https://github.com' -github_sponsors_url = f'{github_url}/sponsors' - -# -- General configuration -- - -extensions = [ - 'sphinx.ext.extlinks', # allows to create custom roles easily - 'sphinx.ext.intersphinx', # allows interlinking external docs sites - 'jaraco.packaging.sphinx', - 'rst.linker', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The master toctree document. -master_doc = 'index' - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# -- Options for extlinks extension --------------------------------------- -extlinks = { - 'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323 -} - -# -- Options for HTML output -- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'nature' - -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = ['_theme'] - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -html_sidebars = { - 'index': [ - 'relations.html', 'sourcelink.html', 'indexsidebar.html', - 'searchbox.html']} - -# If false, no module index is generated. -html_use_modindex = False - -# If false, no index is generated. -html_use_index = False - -# -- Options for LaTeX output -- - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, -# documentclass [howto/manual]). -latex_documents = [( - 'index', 'Setuptools.tex', 'Setuptools Documentation', - 'The fellowship of the packaging', 'manual', -)] +master_doc = "index" link_files = { '../CHANGES.rst': dict( @@ -148,10 +73,38 @@ link_files = { ), } +intersphinx_mapping = { + 'pypa-build': ('https://pypa-build.readthedocs.io/en/latest/', None) +} + +# Add support for linking usernames +github_url = 'https://github.com' +github_sponsors_url = f'{github_url}/sponsors' +extlinks = { + 'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323 +} +extensions += ['sphinx.ext.extlinks', 'sphinx.ext.intersphinx'] # Be strict about any broken references: nitpicky = True +# Ref: https://github.com/python-attrs/attrs/pull/571/files\ +# #diff-85987f48f1258d9ee486e3191495582dR82 +default_role = 'any' + +# Custom sidebar templates, maps document names to template names. +html_theme = 'alabaster' +templates_path = ['_templates'] +html_sidebars = {'index': ['tidelift-sidebar.html']} + +# Add support for inline tabs +extensions += ['sphinx_inline_tabs'] + +## Support for distutils + +# allow interlinking external docs sites +extensions += ['sphinx.ext.intersphinx'], + # Ref: https://stackoverflow.com/a/30624034/595220 nitpick_ignore = [ ('c:func', 'SHGetSpecialFolderPath'), # ref to MS docs @@ -188,12 +141,6 @@ nitpick_ignore = [ ('py:mod', 'docutils'), # there's no Sphinx site documenting this ] - -# Ref: https://github.com/python-attrs/attrs/pull/571/files\ -# #diff-85987f48f1258d9ee486e3191495582dR82 -default_role = 'any' - - # Allow linking objects on other Sphinx sites seamlessly: intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), diff --git a/docs/pkg_resources.rst b/docs/pkg_resources.rst index 364e2183..994bea6f 100644 --- a/docs/pkg_resources.rst +++ b/docs/pkg_resources.rst @@ -10,6 +10,13 @@ eggs, support for merging packages that have separately-distributed modules or subpackages, and APIs for managing Python's current "working set" of active packages. +Use of ``pkg_resources`` is discouraged in favor of +`importlib.resources <https://docs.python.org/3/library/importlib.html#module-importlib.resources>`_, +`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_, +and their backports (`resources <https://pypi.org/project/importlib_resources>`_, +`metadata <https://pypi.org/project/importlib_metadata>`_). +Please consider using those libraries instead of pkg_resources. + .. contents:: **Table of Contents** @@ -703,7 +710,7 @@ entry point group and look for entry points named "pre_process" and To advertise an entry point, a project needs to use ``setuptools`` and provide an ``entry_points`` argument to ``setup()`` in its setup script, so that the entry points will be included in the distribution's metadata. For more -details, see the [``setuptools`` documentation](https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins). +details, see :ref:`Advertising Behavior<dynamic discovery of services and plugins>`. Each project distribution can advertise at most one entry point of a given name within the same entry point group. For example, a distutils extension @@ -1939,4 +1946,3 @@ History 0.3a1 * Initial release. - diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 03ce9fa2..619b2d14 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -76,6 +76,17 @@ Keywords ``license`` A string specifying the license of the package. +``license_file`` + + .. warning:: + ``license_file`` is deprecated. Use ``license_files`` instead. + +``license_files`` + + A list of glob patterns for license related files that should be included. + If neither ``license_file`` nor ``license_files`` is specified, this option + defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``. + ``keywords`` A list of strings or a comma-separated string providing descriptive meta-data. See: `PEP 0314`_. diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 104d68fa..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,7 +0,0 @@ -# keep these in sync with setup.cfg -sphinx -jaraco.packaging>=6.1 -rst.linker>=1.9 -pygments-github-lexers==0.0.5 - -setuptools>=34 diff --git a/docs/setuptools.rst b/docs/setuptools.rst index 1000a0ce..541bec51 100644 --- a/docs/setuptools.rst +++ b/docs/setuptools.rst @@ -54,7 +54,7 @@ Feature Highlights: Developer's Guide ----------------- - +The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`. @@ -157,7 +157,7 @@ To use this feature: ] build-backend = "setuptools.build_meta" -* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``pep517``. +* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``. .. warning:: diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst index bc66869b..7c97ca1c 100644 --- a/docs/userguide/declarative_config.rst +++ b/docs/userguide/declarative_config.rst @@ -184,7 +184,7 @@ maintainer_email maintainer-email str classifiers classifier file:, list-comma license str license_file str -license_files list-comma +license_files list-comma 42.0.0 description summary file:, str long_description long-description file:, str long_description_content_type str 38.6.0 @@ -243,6 +243,19 @@ data_files dict 40.6.0 **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3. + Notes: 1. In the ``package_data`` section, a key named with a single asterisk (``*``) refers to all packages, in lieu of the empty string used in ``setup.py``. + +2. In the ``extras_require`` section, values are parsed as ``list-semi``. This implies that in +order to include markers, they **must** be *dangling*: + +.. code-block:: ini + + [options.extras_require] + rest = docutils>=0.3; pack ==1.1, ==1.3 + pdf = + ReportLab>=1.2 + RXP + importlib-metadata; python_version < "3.8" diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst index 354a9f8c..188083e0 100644 --- a/docs/userguide/dependency_management.rst +++ b/docs/userguide/dependency_management.rst @@ -3,7 +3,7 @@ Dependencies Management in Setuptools ===================================== There are three types of dependency styles offered by setuptools: -1) build system requirement, required dependency and 3) optional +1) build system requirement, 2) required dependency and 3) optional dependency. .. Note:: @@ -19,8 +19,8 @@ Build system requirement Package requirement ------------------- After organizing all the scripts and files and getting ready for packaging, -there needs to be a way to tell Python what programs it need to actually -do the packgaging (in our case, ``setuptools`` of course). Usually, +there needs to be a way to tell Python what programs it needs to actually +do the packaging (in our case, ``setuptools`` of course). Usually, you also need the ``wheel`` package as well since it is recommended that you upload a ``.whl`` file to PyPI alongside your ``.tar.gz`` file. Unlike the other two types of dependency keyword, this one is specified in your @@ -47,32 +47,36 @@ Declaring required dependency This is where a package declares its core dependencies, without which it won't be able to run. ``setuptools`` support automatically download and install these dependencies when the package is installed. Although there is more -finess to it, let's start with a simple example. +finesse to it, let's start with a simple example. -.. code-block:: ini +.. tab:: setup.cfg - [options] - #... - install_requires = - docutils - BazSpam ==1.1 + .. code-block:: ini + + [options] + #... + install_requires = + docutils + BazSpam ==1.1 + +.. tab:: setup.py -.. code-block:: python + .. code-block:: python - setup( - #..., - install_requires = [ - 'docutils', - 'BazSpam ==1.1' - ] - ) + setup( + #..., + install_requires = [ + 'docutils', + 'BazSpam ==1.1' + ] + ) When your project is installed (e.g. using pip), all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed and 2) Any scripts in your project will be installed with wrappers that verify the availability of the specified dependencies at runtime. - + Platform specific dependencies ------------------------------ @@ -82,41 +86,49 @@ specific dependencies. For example, the ``enum`` package was added in Python 3.4, therefore, package that depends on it can elect to install it only when the Python version is older than 3.4. To accomplish this -.. code-block:: ini +.. tab:: setup.cfg - [options] - #... - install_requires = - enum34;python_version<'3.4' + .. code-block:: ini -.. code-block:: python - - setup( + [options] #... - install_requires=[ - "enum34;python_version<'3.4'",] - ) + install_requires = + enum34;python_version<'3.4' + +.. tab:: setup.py + + .. code-block:: python + + setup( + #... + install_requires=[ + "enum34;python_version<'3.4'",] + ) Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0 and only install it if the user is using a Windows operating system: -.. code-block:: ini - - [options] - #... - install_requires = - enum34;python_version<'3.4' - pywin32 >= 1.0;platform_system=='Windows' +.. tab:: setup.cfg -.. code-block:: python + .. code-block:: ini - setup( + [options] #... - install_requires=[ - "enum34;python_version<'3.4'", - "pywin32 >= 1.0;platform_system=='Windows'" - ] - ) + install_requires = + enum34;python_version<'3.4' + pywin32 >= 1.0;platform_system=='Windows' + +.. tab:: setup.py + + .. code-block:: python + + setup( + #... + install_requires=[ + "enum34;python_version<'3.4'", + "pywin32 >= 1.0;platform_system=='Windows'" + ] + ) The environmental markers that may be used for testing platform types are detailed in `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_. @@ -181,20 +193,24 @@ The ``dependency_links`` option takes the form of a list of URL strings. For example, this will cause a search of the specified page for eggs or source distributions, if the package's dependencies aren't already installed: -.. code-block:: ini - - [options] - #... - dependency_links = http://peak.telecommunity.com/snapshots/ +.. tab:: setup.cfg -.. code-block:: python + .. code-block:: ini - setup( + [options] #... - dependency_links=[ - "http://peak.telecommunity.com/snapshots/" - ], - ) + dependency_links = http://peak.telecommunity.com/snapshots/ + +.. tab:: setup.py + + .. code-block:: python + + setup( + #... + dependency_links=[ + "http://peak.telecommunity.com/snapshots/" + ], + ) Optional dependencies @@ -202,7 +218,7 @@ Optional dependencies Setuptools allows you to declare dependencies that only get installed under specific circumstances. These dependencies are specified with ``extras_require`` keyword and are only installed if another package depends on it (either -directly or indirectly) This makes it convenient to declare dependencies for +directly or indirectly) This makes it convenient to declare dependencies for ancillary functions such as "tests" and "docs". .. note:: @@ -211,24 +227,28 @@ ancillary functions such as "tests" and "docs". For example, Package-A offers optional PDF support and requires two other dependencies for it to work: -.. code-block:: ini +.. tab:: setup.cfg - [metadata] - name = Package-A + .. code-block:: ini - [options.extras_require] - PDF = ReportLab>=1.2; RXP + [metadata] + name = Package-A + [options.extras_require] + PDF = ReportLab>=1.2; RXP -.. code-block:: python - setup( - name="Project-A", - #... - extras_require={ - "PDF": ["ReportLab>=1.2", "RXP"], - } - ) +.. tab:: setup.py + + .. code-block:: python + + setup( + name="Project-A", + #... + extras_require={ + "PDF": ["ReportLab>=1.2", "RXP"], + } + ) The name ``PDF`` is an arbitary identifier of such a list of dependencies, to which other components can refer and have them installed. There are two common @@ -236,57 +256,69 @@ use cases. First is the console_scripts entry point: -.. code-block:: ini +.. tab:: setup.cfg - [metadata] - name = Project A - #... + .. code-block:: ini - [options] - #... - entry_points= - [console_scripts] - rst2pdf = project_a.tools.pdfgen [PDF] - rst2html = project_a.tools.htmlgen - -.. code-block:: python - - setup( - name = "Project-A" - #..., - entry_points={ - "console_scripts": [ - "rst2pdf = project_a.tools.pdfgen [PDF]", - "rst2html = project_a.tools.htmlgen", - ], - } - ) + [metadata] + name = Project A + #... -When the script ``rst2pdf`` is run, it will trigger the installation of -the two dependencies ``PDF`` maps to. + [options] + #... + entry_points= + [console_scripts] + rst2pdf = project_a.tools.pdfgen [PDF] + rst2html = project_a.tools.htmlgen + +.. tab:: setup.py + + .. code-block:: python + + setup( + name = "Project-A" + #..., + entry_points={ + "console_scripts": [ + "rst2pdf = project_a.tools.pdfgen [PDF]", + "rst2html = project_a.tools.htmlgen", + ], + } + ) + +This syntax indicates that the entry point (in this case a console script) +is only valid when the PDF extra is installed. It is up to the installer +to determine how to handle the situation where PDF was not indicated +(e.g. omit the console script, provide a warning when attempting to load +the entry point, assume the extras are present and let the implementation +fail later). The second use case is that other package can use this "extra" for their own dependencies. For example, if "Project-B" needs "project A" with PDF support installed, it might declare the dependency like this: -.. code-block:: ini +.. tab:: setup.cfg - [metadata] - name = Project-B - #... + .. code-block:: ini - [options] - #... - install_requires = - Project-A[PDF] + [metadata] + name = Project-B + #... + + [options] + #... + install_requires = + Project-A[PDF] + +.. tab:: setup.py -.. code-block:: python + .. code-block:: python - setup( - name="Project-B", - install_requires=["Project-A[PDF]"], - ... - ) + setup( + name="Project-B", + install_requires=["Project-A[PDF]"], + ... + ) This will cause ReportLab to be installed along with project A, if project B is installed -- even if project A was already installed. In this way, a project diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst index bce724a7..3c477ec1 100644 --- a/docs/userguide/development_mode.rst +++ b/docs/userguide/development_mode.rst @@ -3,9 +3,9 @@ Under normal circumstances, the ``distutils`` assume that you are going to build a distribution of your project, not use it in its "raw" or "unbuilt" -form. If you were to use the ``distutils`` that way, you would have to rebuild -and reinstall your project every time you made a change to it during -development. +form. However, if you were to use the ``distutils`` to build a distribution, +you would have to rebuild and reinstall your project every time you made a +change to it during development. Another problem that sometimes comes up with the ``distutils`` is that you may need to do development on two related projects at the same time. You may need diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst index edab4465..63d30a48 100644 --- a/docs/userguide/entry_point.rst +++ b/docs/userguide/entry_point.rst @@ -28,7 +28,7 @@ with ``__init__.py`` as: .. code-block:: python - def helloworld(): + def hello_world(): print("Hello world") and ``__main__.py`` providing a hook: @@ -64,7 +64,7 @@ After installing the package, a user may invoke that function by simply calling The syntax for entry points is specified as follows: -.. code-block:: +.. code-block:: ini <name> = [<package>.[<subpackage>.]]<module>[:<object>.<object>] diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index de4ef668..0a8070ae 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -19,36 +19,44 @@ Package Discovery and Namespace Package support for namespace package. Normally, you would specify the package to be included manually in the following manner: -.. code-block:: ini - - [options] - #... - packages = - mypkg1 - mypkg2 +.. tab:: setup.cfg -.. code-block:: python + .. code-block:: ini - setup( + [options] #... - packages = ['mypkg1', 'mypkg2'] - ) + packages = + mypkg1 + mypkg2 + +.. tab:: setup.py + + .. code-block:: python + + setup( + #... + packages = ['mypkg1', 'mypkg2'] + ) This can get tiresome reallly quickly. To speed things up, we introduce two functions provided by setuptools: -.. code-block:: ini +.. tab:: setup.cfg - [options] - packages = find: - #or - packages = find_namespace: + .. code-block:: ini -.. code-block:: python + [options] + packages = find: + #or + packages = find_namespace: + +.. tab:: setup.py - from setuptools import find_packages - #or - from setuptools import find_namespace_packages + .. code-block:: python + + from setuptools import find_packages + #or + from setuptools import find_namespace_packages Using ``find:`` or ``find_packages`` @@ -71,30 +79,34 @@ it, consider the following directory To have your setup.cfg or setup.py to automatically include packages found in ``src`` that starts with the name ``pkg`` and not ``additional``: -.. code-block:: ini +.. tab:: setup.cfg - [options] - packages = find: - package_dir = - =src + .. code-block:: ini - [options.packages.find] - where = src - include = pkg* - exclude = additional + [options] + packages = find: + package_dir = + =src -.. code-block:: python + [options.packages.find] + where = src + include = pkg* + exclude = additional - setup( - #... - packages = find_packages( - where = 'src', - include = ['pkg*',], - exclude = ['additional',] - ), - package_dir = {"":"src"} - #... - ) +.. tab:: setup.py + + .. code-block:: python + + setup( + #... + packages = find_packages( + where = 'src', + include = ['pkg*',], + exclude = ['additional',] + ), + package_dir = {"":"src"} + #... + ) .. _Namespace Packages: @@ -144,7 +156,7 @@ to use ``find_namespace:``: =src packages = find_namespace: - [options.packages.find_namespace] + [options.packages.find] where = src When you install the zipped distribution, ``timmins.foo`` would become @@ -195,17 +207,21 @@ following: And the ``namespace_packages`` keyword in your ``setup.cfg`` or ``setup.py``: -.. code-block:: ini +.. tab:: setup.cfg - [options] - namespace_packages = timmins + .. code-block:: ini -.. code-block:: python + [options] + namespace_packages = timmins + +.. tab:: setup.py + + .. code-block:: python - setup( - # ... - namespace_packages = ['timmins'] - ) + setup( + # ... + namespace_packages = ['timmins'] + ) And your directory should look like this diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 697087ed..2807f59b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -21,7 +21,7 @@ the backend (build system) it wants to use. The distribution can then be generated with whatever tools that provides a ``build sdist``-alike functionality. While this may appear cumbersome, given the added pieces, it in fact tremendously enhances the portability of your package. The -change is driven under :pep:`517 <517#build-requirements>`. To learn more about Python packaging in general, +change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general, navigate to the `bottom <Resources on python packaging>`_ of this page. @@ -37,33 +37,52 @@ package your project: requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" -Then, you will need a ``setup.cfg`` to specify your package information, -such as metadata, contents, dependencies, etc. Here we demonstrate the minimum +Then, you will need a ``setup.cfg`` or ``setup.py`` to specify your package +information, such as metadata, contents, dependencies, etc. Here we demonstrate +the minimum -.. code-block:: ini +.. tab:: setup.cfg - [metadata] - name = "mypackage" - version = 0.0.1 + .. code-block:: ini - [options] - packages = "mypackage" - install_requires = - requests - importlib; python_version == "2.6" + [metadata] + name = mypackage + version = 0.0.1 + + [options] + packages = mypackage + install_requires = + requests + importlib; python_version == "2.6" + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup + + setup( + name='mypackage', + version='0.0.1', + packages=['mypackage'], + install_requires=[ + 'requests', + 'importlib; python_version == "2.6"', + ], + ) This is what your project would look like:: ~/mypackage/ pyproject.toml - setup.cfg + setup.cfg # or setup.py mypackage/__init__.py -Then, you need an installer, such as `pep517 <https://pypi.org/project/pep517/>`_ -which you can obtain via ``pip install pep517``. After downloading it, invoke -the installer:: +Then, you need an builder, such as :std:doc:`PyPA build <pypa-build:index>` +which you can obtain via ``pip install build``. After downloading it, invoke +the builder:: - python -m pep517.build + python -m build You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl`` file in the ``dist`` directory), which you can upload to PyPI! @@ -71,7 +90,7 @@ file in the ``dist`` directory), which you can upload to PyPI! Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few -dependencies, and perhaps some data files and scripts. In the next few section, +dependencies, and perhaps some data files and scripts. In the next few sections, we will walk through those additional but essential information you need to specify to properly package your project. |