From 9cd42473880bae93f4bbeed3faf0184fa333baad Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Wed, 1 Jan 2025 11:50:59 +0100 Subject: [PATCH] docs(package-discovery): prioritise `pyproject.toml` --- docs/userguide/package_discovery.rst | 124 +++++++++++++-------------- 1 file changed, 62 insertions(+), 62 deletions(-) diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index c33877e1f6..9086eb269b 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -19,6 +19,15 @@ support for namespace packages. Normally, you would specify the packages to be included manually in the following manner: +.. tab:: pyproject.toml + + .. code-block:: toml + + # ... + [tool.setuptools] + packages = ["mypkg", "mypkg.subpkg1", "mypkg.subpkg2"] + # ... + .. tab:: setup.cfg .. code-block:: ini @@ -39,18 +48,29 @@ Normally, you would specify the packages to be included manually in the followin packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2'] ) + +If your packages are not in the root of the repository or do not correspond +exactly to the directory structure, you also need to configure ``package_dir``: + .. tab:: pyproject.toml .. code-block:: toml - # ... [tool.setuptools] - packages = ["mypkg", "mypkg.subpkg1", "mypkg.subpkg2"] # ... + package-dir = {"" = "src"} + # directory containing all the packages (e.g. src/mypkg1, src/mypkg2) + # OR -If your packages are not in the root of the repository or do not correspond -exactly to the directory structure, you also need to configure ``package_dir``: + [tool.setuptools.package-dir] + mypkg = "lib" + # mypkg.module corresponds to lib/module.py + "mypkg.subpkg1" = "lib1" + # mypkg.subpkg1.module1 corresponds to lib1/module1.py + "mypkg.subpkg2" = "lib2" + # mypkg.subpkg2.module2 corresponds to lib2/module2.py + # ... .. tab:: setup.cfg @@ -93,26 +113,6 @@ exactly to the directory structure, you also need to configure ``package_dir``: } ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [tool.setuptools] - # ... - package-dir = {"" = "src"} - # directory containing all the packages (e.g. src/mypkg1, src/mypkg2) - - # OR - - [tool.setuptools.package-dir] - mypkg = "lib" - # mypkg.module corresponds to lib/module.py - "mypkg.subpkg1" = "lib1" - # mypkg.subpkg1.module1 corresponds to lib1/module1.py - "mypkg.subpkg2" = "lib2" - # mypkg.subpkg2.module2 corresponds to lib2/module2.py - # ... - This can get tiresome really quickly. To speed things up, you can rely on setuptools automatic discovery, or use the provided tools, as explained in the following sections. @@ -252,6 +252,16 @@ reserved names such as ``tasks``, ``example`` or ``docs``, or you want to *exclude* nested packages that would be otherwise included), you can use the provided tools for package discovery: +.. tab:: pyproject.toml + + .. code-block:: toml + + # ... + [tool.setuptools.packages] + find = {} # Scanning implicit namespaces is active by default + # OR + find = {namespaces = false} # Disable implicit namespaces + .. tab:: setup.cfg .. code-block:: ini @@ -269,16 +279,6 @@ the provided tools for package discovery: # or from setuptools import find_namespace_packages -.. tab:: pyproject.toml - - .. code-block:: toml - - # ... - [tool.setuptools.packages] - find = {} # Scanning implicit namespaces is active by default - # OR - find = {namespaces = false} # Disable implicit namespaces - Finding simple packages ----------------------- @@ -303,6 +303,23 @@ it, consider the following directory:: To have setuptools to automatically include packages found in ``src`` that start with the name ``pkg`` and not ``additional``: +.. tab:: pyproject.toml + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + include = ["pkg*"] # alternatively: `exclude = ["additional*"]` + namespaces = false + + .. note:: + When using ``tool.setuptools.packages.find`` in ``pyproject.toml``, + setuptools will consider :pep:`implicit namespaces <420>` by default when + scanning your project directory. + To avoid ``pkg.namespace`` from being added to your package list + you can set ``namespaces = false``. This will prevent any folder + without an ``__init__.py`` file from being scanned. + .. tab:: setup.cfg .. code-block:: ini @@ -341,23 +358,6 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: ``pkg.namespace`` is ignored by ``find_packages()`` (see ``find_namespace_packages()`` below). -.. tab:: pyproject.toml - - .. code-block:: toml - - [tool.setuptools.packages.find] - where = ["src"] - include = ["pkg*"] # alternatively: `exclude = ["additional*"]` - namespaces = false - - .. note:: - When using ``tool.setuptools.packages.find`` in ``pyproject.toml``, - setuptools will consider :pep:`implicit namespaces <420>` by default when - scanning your project directory. - To avoid ``pkg.namespace`` from being added to your package list - you can set ``namespaces = false``. This will prevent any folder - without an ``__init__.py`` file from being scanned. - .. important:: ``include`` and ``exclude`` accept strings representing :mod:`glob` patterns. These patterns should match the **full** name of the Python module (as if it @@ -414,6 +414,17 @@ by creating a project directory organized as follows:: If you want the ``timmins.foo`` to be automatically included in the distribution, then you will need to specify: +.. tab:: pyproject.toml + + .. code-block:: toml + + [tool.setuptools.packages.find] + where = ["src"] + + When using ``tool.setuptools.packages.find`` in ``pyproject.toml``, + setuptools will consider :pep:`implicit namespaces <420>` by default when + scanning your project directory. + .. tab:: setup.cfg .. code-block:: ini @@ -449,17 +460,6 @@ distribution, then you will need to specify: On the other hand, ``find_namespace_packages()`` will scan all directories. -.. tab:: pyproject.toml - - .. code-block:: toml - - [tool.setuptools.packages.find] - where = ["src"] - - When using ``tool.setuptools.packages.find`` in ``pyproject.toml``, - setuptools will consider :pep:`implicit namespaces <420>` by default when - scanning your project directory. - After installing the package distribution, ``timmins.foo`` would become available to your interpreter.