Skip to content

Commit

Permalink
Remove backend choice and just use Hatchling so the tutorial can be u…
Browse files Browse the repository at this point in the history
…sed without making any choices.
  • Loading branch information
BrenBarn committed Nov 2, 2023
1 parent 0b20b77 commit eca9128
Showing 1 changed file with 17 additions and 36 deletions.
53 changes: 17 additions & 36 deletions source/tutorials/packaging-projects.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Packaging Python Projects
=========================

This tutorial walks you through how to package a simple Python project. It will
show you how to add the necessary files and structure to create the package, how
to build the package, and how to upload it to the Python Package Index (PyPI).
The tools required for building and distributing packages are third-party tools not included with Python. This tutorial uses Hatchling, which is one among several such tools. If you are already using different build tools, or you want to for whatever reason, you will need to look at the documentation for those tools. In many cases it will be fairly easy to adapt this example.

This tutorial walks you through how to package a simple Python project --- that is, one that contains only Python code (although it may depend on libraries that include extensions written in other languages). If you need to package a project that has parts written in a language other than Python (such as a C extension), please look for third-party tools. But, for a simple pure Python project, this tutorial show you how to add the necessary files and structure to create the package, how to build the package, and how to upload it to the Python Package Index (PyPI).

.. tip::

Expand Down Expand Up @@ -103,6 +103,12 @@ Creating a test directory
:file:`tests/` is a placeholder for test files. Leave it empty for now.


Installing the build backend
----------------------------

As mentioned, this tutorial uses the Hatchling build tool. Go to https://hatch.pypa.io/latest/install/ and follow the instructions to install it. (Or, install a different build tool and adapt the example below, following the documentation for that tool.)


Creating pyproject.toml
-----------------------

Expand All @@ -113,7 +119,7 @@ Creating pyproject.toml
:ref:`build` what "backend" tool to use to create
:term:`distribution packages <Distribution Package>` for your project.
You can choose from a number of backends; this tutorial uses :ref:`Hatchling
<hatch>` by default, but it will work identically with :ref:`setuptools`,
<hatch>` by default, but the example can be adapted without much change for :ref:`setuptools`,
:ref:`Flit <flit>`, :ref:`PDM <pdm>`, and others that support the ``[project]``
table for :ref:`metadata <configuring metadata>`.

Expand All @@ -124,40 +130,13 @@ table for :ref:`metadata <configuring metadata>`.
management, as well as building, uploading, and installing packages. This
tutorial uses single-purpose tools that work independently.

Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables:

.. tab:: Hatchling

.. code-block:: toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
.. tab:: setuptools

.. code-block:: toml
Open :file:`pyproject.toml` and enter the following:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
.. tab:: Flit

.. code-block:: toml
[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"
.. tab:: PDM

.. code-block:: toml
[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"
.. code-block:: toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
- ``requires`` is a list of packages that are needed to build your package. You
don't need to install them; build frontends like :ref:`pip` will install them
Expand All @@ -166,6 +145,8 @@ Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables:
- ``build-backend`` is the name of the Python object that frontends will use to
perform the build.

If you use a different build backend, you'll need to change this section to reflect that. See the documentation for your chosen build backend for information on how to do that.

.. TODO: Add note to check the tools' documentation for the current snippet?
.. _configuring metadata:
Expand Down

0 comments on commit eca9128

Please sign in to comment.