From 9cd42473880bae93f4bbeed3faf0184fa333baad Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Wed, 1 Jan 2025 11:50:59 +0100 Subject: [PATCH 1/2] 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. From 1d5ea90e7c3b76946662911800097a1a17d5894d Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Wed, 1 Jan 2025 12:03:21 +0100 Subject: [PATCH 2/2] docs(package-discovery): improve consistency --- docs/userguide/package_discovery.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 9086eb269b..d629d58c86 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -5,8 +5,8 @@ Package Discovery and Namespace Packages ======================================== .. note:: - a full specification for the keywords supplied to ``setup.cfg`` or - ``setup.py`` can be found at :doc:`keywords reference ` + A full specification for the keywords supplied to ``setup.cfg`` or + ``setup.py`` can be found at :doc:`keywords reference `. .. important:: The examples provided here are only to demonstrate the functionality @@ -45,7 +45,7 @@ Normally, you would specify the packages to be included manually in the followin setup( # ... - packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2'] + packages=["mypkg", "mypkg.subpkg1", "mypkg.subpkg2"] ) @@ -268,7 +268,7 @@ the provided tools for package discovery: [options] packages = find: - #or + # OR packages = find_namespace: .. tab:: setup.py @@ -276,7 +276,7 @@ the provided tools for package discovery: .. code-block:: python from setuptools import find_packages - # or + # OR from setuptools import find_namespace_packages @@ -327,7 +327,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: [options] packages = find: package_dir = - =src + = src [options.packages.find] where = src @@ -345,8 +345,8 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: setup( # ... packages=find_packages( - where='src', - include=['pkg*'], # alternatively: `exclude=['additional*']` + where="src", + include=["pkg*"], # alternatively: `exclude=["additional*"]` ), package_dir={"": "src"} # ... @@ -431,7 +431,7 @@ distribution, then you will need to specify: [options] package_dir = - =src + = src packages = find_namespace: [options.packages.find] @@ -450,7 +450,7 @@ distribution, then you will need to specify: setup( # ... - packages=find_namespace_packages(where='src'), + packages=find_namespace_packages(where="src"), package_dir={"": "src"} # ... ) @@ -542,7 +542,7 @@ And the ``namespace_packages`` keyword in your ``setup.cfg`` or ``setup.py``: setup( # ... - namespace_packages=['timmins'] + namespace_packages=["timmins"] ) And your directory should look like this @@ -568,7 +568,7 @@ file contains the following: .. code-block:: python - __path__ = __import__('pkgutil').extend_path(__path__, __name__) + __path__ = __import__("pkgutil").extend_path(__path__, __name__) The project layout remains the same and ``pyproject.toml/setup.cfg`` remains the same.