diff options
Diffstat (limited to 'docs/userguide/quickstart.rst')
| -rw-r--r-- | docs/userguide/quickstart.rst | 47 |
1 files changed, 24 insertions, 23 deletions
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index bcb282ed..da904bab 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -14,9 +14,9 @@ Python packaging at a glance ============================ The landscape of Python packaging is shifting and ``Setuptools`` has evolved to only provide backend support, no longer being the de-facto packaging tool in -the market. All python package must provide a ``pyproject.toml`` and specify +the market. Every python package must provide a ``pyproject.toml`` and specify the backend (build system) it wants to use. The distribution can then -be generated with whatever tools that provides a ``build sdist``-alike +be generated with whatever tool that provides a ``build sdist``-like 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:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general, @@ -76,7 +76,7 @@ This is what your project would look like:: setup.cfg # or setup.py mypackage/__init__.py -Then, you need an builder, such as :std:doc:`PyPA build <pypa-build:index>` +Then, you need a builder, such as :std:doc:`PyPA build <pypa-build:index>` which you can obtain via ``pip install build``. After downloading it, invoke the builder:: @@ -89,15 +89,15 @@ 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 sections, -we will walk through those additional but essential information you need +we will walk through the additional but essential information you need to specify to properly package your project. Automatic package discovery =========================== For simple projects, it's usually easy enough to manually add packages to -the ``packages`` keyword in ``setup.cfg``. However, for very large projects -, it can be a big burden to keep the package list updated. ``setuptools`` +the ``packages`` keyword in ``setup.cfg``. However, for very large projects, +it can be a big burden to keep the package list updated. ``setuptools`` therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and :literal:`find_namespace:\ `. To use it in your project: @@ -110,11 +110,11 @@ therefore provides two convenient tools to ease the burden: :literal:`find:\ ` a include=pkg1, pkg2 exclude=pk3, pk4 -When you pass the above information, alongside other necessary ones, +When you pass the above information, alongside other necessary information, ``setuptools`` walks through the directory specified in ``where`` (omitted -here as the package reside in current directory) and filters the packages -it can find following the ``include`` (default to none), then remove -those that match the ``exclude`` and return a list of Python packages. Note +here as the package resides in the current directory) and filters the packages +it can find following the ``include`` (defaults to none), then removes +those that match the ``exclude`` and returns a list of Python packages. Note that each entry in the ``[options.packages.find]`` is optional. The above setup also allows you to adopt a ``src/`` layout. For more details and advanced use, go to :ref:`package_discovery` @@ -122,7 +122,7 @@ use, go to :ref:`package_discovery` Entry points and automatic script creation =========================================== -Setuptools support automatic creation of scripts upon installation, that runs +Setuptools supports automatic creation of scripts upon installation, that runs code within your package if you specify them with the ``entry_points`` keyword. This is what allows you to run commands like ``pip install`` instead of having to type ``python -m pip install``. To accomplish this, add the entry_points @@ -157,9 +157,9 @@ operators <, >, <=, >=, == or !=, followed by a version identifier): When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. -This, of course, is a simplified scenarios. ``setuptools`` also provide +This, of course, is a simplified scenarios. ``setuptools`` also provides additional keywords such as ``setup_requires`` that allows you to install -dependencies before running the script, and ``extras_requires`` that take +dependencies before running the script, and ``extras_require`` that take care of those needed by automatically generated scripts. It also provides mechanisms to handle dependencies that are not in PyPI. For more advanced use, see :doc:`dependency_management` @@ -186,17 +186,18 @@ For more details, see :doc:`datafiles` Development mode ================ -``setuptools`` allows you to install a package without copying any files -to your interpreter directory (e.g. the ``site-packages`` directory). This -allows you to modify your source code and have the changes take effect without -you having to rebuild and reinstall. This is currently incompatible with -PEP 517 and therefore it requires a ``setup.py`` script with the following -content:: - import setuptools - setuptools.setup() +.. tip:: + + Prior to :ref:`pip v21.1 <pip:v21-1>`, a ``setup.py`` script was + required to be compatible with development mode. With late + versions of pip, any project may be installed in this mode. -Then:: +``setuptools`` allows you to install a package without copying any files +to your interpreter directory (e.g. the ``site-packages`` directory). +This allows you to modify your source code and have the changes take +effect without you having to rebuild and reinstall. +Here's how to do it:: pip install --editable . @@ -206,7 +207,7 @@ associate with your source code. For more information, see :doc:`development_mod Uploading your package to PyPI ============================== -After generating the distribution files, next step would be to upload your +After generating the distribution files, the next step would be to upload your distribution so others can use it. This functionality is provided by `twine <https://pypi.org/project/twine/>`_ and we will only demonstrate the basic use here. |