diff options
author | Michał Górny <mgorny@gentoo.org> | 2022-02-12 09:02:51 +0100 |
---|---|---|
committer | Michał Górny <mgorny@gentoo.org> | 2022-02-12 09:02:51 +0100 |
commit | c9fe7f7c31f9a6beba1472fd0bc68a3e50b6b687 (patch) | |
tree | 75fac36e13ae2070f5816b13822181def4a53a17 /guide/_sources | |
parent | Update Guide to 02a98c4 (diff) | |
download | python-c9fe7f7c31f9a6beba1472fd0bc68a3e50b6b687.tar.gz python-c9fe7f7c31f9a6beba1472fd0bc68a3e50b6b687.tar.bz2 python-c9fe7f7c31f9a6beba1472fd0bc68a3e50b6b687.zip |
Update Guide to f8676dc
Signed-off-by: Michał Górny <mgorny@gentoo.org>
Diffstat (limited to 'guide/_sources')
-rw-r--r-- | guide/_sources/basic.rst.txt | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/guide/_sources/basic.rst.txt b/guide/_sources/basic.rst.txt index c3c6c03..0ac0c0d 100644 --- a/guide/_sources/basic.rst.txt +++ b/guide/_sources/basic.rst.txt @@ -94,3 +94,150 @@ either by calls to ``python_foreach_impl`` from ``python-r1``, or inside sub-phase functions in ``distutils-r1``. The global scope setup is done via calling ``python_setup``, either directly or via default ``pkg_setup`` in ``python-any-r1`` and ``python-single-r1``. + + +Dependencies in Python packages +=============================== +.. Note:: + + The following sections focus specifically on dependencies that + are Python packages. Python software often depends on external + tools, libraries written in other programming languages, etc. + For these dependencies, the usual Gentoo rules apply. + + +.. index:: BDEPEND +.. index:: DEPEND +.. index:: RDEPEND + +The most common dependency types +-------------------------------- +The dependencies found in Python packages can usually be classified +into two categories: runtime dependencies and build-time dependencies. + +*Runtime dependencies* are packages that are required to be present +in order for the installed Python modules and scripts to be usable. +In general, these are all packages whose modules are imported +in the installed Python files. Generally runtime dependencies +are not needed at build time and therefore the build systems +do not verify whether they are installed. However, modern Python +scripts based on entry points often refuse to run if their dependencies +are not satisfied. Runtime dependencies should be placed +in ``RDEPEND``. + +A special subclass of runtime dependencies are *optional runtime +dependencies* (often called 'extra' dependencies). The dependencies are +optional if the package can still be meaningfully functional when they +are not installed. This usually means that the package either handles +failing imports gracefully, or that they are imported only in a subset +of package's installed modules and that the package can still be +meaningfully used without importing these modules. + +There are multiple approaches to handling optional dependencies. +Depending on the specifics, they can: + +1. be added unconditionally to ``RDEPEND`` (if they are considered + important and/or light enough); + +2. be listed as an informational message in ``pkg_postinst`` (usually + utilizing ``optfeature.eclass``); + +3. be added to ``RDEPEND`` conditionally to USE flags (this is only + acceptable if the package is cheap to rebuild). + +*Build-time dependencies* are the packages needed for the package +to be built and installed. In general, they include the packages +providing the build system. In some cases, they may also include some +runtime dependencies, e.g. when they are needed to import +the ``__init__.py`` of the package. As a rule of thumb, if the package +can be built correctly when the specific dependency is not installed, +it does not need to be listed as a build dependency. Most of the time, +build dependencies belong in ``BDEPEND``. + +The ``distutils-r1`` class generally takes care of adding the dependency +on the build system and basic tooling. However, additional plugins +(e.g. ``dev-python/setuptools_scm``) need to be listed explicitly. + +A special class of build-time dependencies are requirements specific +to running the test suite and building documentation. Most of the time +the former include not only the test runner but also all runtime +dependencies of the package (since the test suite runs its code). +Sometimes this is also required to build documentation. These classes +of dependencies go into ``BDEPEND`` under ``test`` and ``doc`` USE flags +respectively. + +Note that sometimes test dependencies can also be optional (including +optional runtime dependencies). They should generally be added +unconditionally to ensure maximum test coverage. Also note that +(as explained further in the Guide), some test dependencies +(e.g. on linters or coverage reporting tools) may actually +be undesirable. + +Again, ``distutils-r1`` provides functions to conveniently add support +for common test runner and Sphinx-based documentation. The former also +takes care of copying ``RDEPEND`` into test dependencies. + +Some Python packages include C extensions that depend on external +libraries. In this case, similarly to non-Python packages, +the dependency on packages providing these libraries needs to go +into ``RDEPEND`` and ``DEPEND`` (not ``BDEPEND``). + +Finally, there are Python packages providing C headers such +as ``dev-python/numpy``. If the package in question uses both headers +and Python code from NumPy, the dependency may need to be included +in all three of ``RDEPEND``, ``DEPEND`` and ``BDEPEND`` (unconditionally +or for tests). + + +Finding dependency lists from build systems +------------------------------------------- +Most of the modern Python build systems include all the package metadata +in the ``pyproject.toml`` file. Setuptools are using ``setup.cfg`` +and/or ``setup.py``. Some packages also include custom code to read +dependencies from external files; it is usually worthwhile to look +for ``requirements`` in the name. + +The keys commonly used to list specific kinds of dependencies in common +Python build systems: + +1. Runtime dependencies (unconditional): + + - `PEP 621`_ metadata: ``project.dependencies`` + - older flit versions: ``tool.flit.metadata.requires`` + - poetry: ``tool.poetry.dependencies`` (note: this also includes + special ``python`` entry to indicate compatible Python versions) + - setuptools: ``install_requires`` + +2. Optional runtime and/or build-time dependencies: + + - `PEP 621`_ metadata: ``project.optional-dependencies`` + - older flit versions: ``tool.flit.metadata.requires-extra`` + - poetry: ``tool.poetry.dependencies`` with ``optional = true``, + sometimes grouped using ``tool.poetry.extras`` + - setuptools: ``extras_require`` + +3. Build-time dependencies (unconditional): + + - all ``pyproject.toml`` build systems: ``build-system.requires`` + - poetry: ``tool.poetry.dev-dependencies`` + - setuptools: ``setup_requires`` (deprecated) + +4. Test dependencies (in addition to ``RDEPEND``): + + - often listed as ``test`` key in optional dependencies + - setuptools: ``tests_require`` (deprecated) + - in some cases they can also be found in ``tox.ini`` + or ``noxfile.py`` + +5. Doc building dependencies: + + - often listed as ``doc`` key in optional dependencies + +6. Python version compatibility: + + - `PEP 621`_ metadata: ``project.requires-python`` + - older flit versions: ``tool.flit.metadata.requires-python`` + - poetry: ``python`` in ``tool.poetry.dependencies`` + - setuptools: ``python_requires`` + +.. _PEP 621: https://www.python.org/dev/peps/pep-0621 |