Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(package-discovery): prioritise pyproject.toml #4784

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(package-discovery): prioritise pyproject.toml #4784

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9cd4247
docs(package-discovery): prioritise `pyproject.toml`
mkniewallner Jan 1, 2025
1d5ea90
docs(package-discovery): improve consistency
mkniewallner Jan 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 74 additions & 74 deletions docs/userguide/package_discovery.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 </references/keywords>`
A full specification for the keywords supplied to ``setup.cfg`` or
``setup.py`` can be found at :doc:`keywords reference </references/keywords>`.

.. important::
The examples provided here are only to demonstrate the functionality
Expand All @@ -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
Expand All @@ -36,21 +45,32 @@ 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"]
)


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

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -252,32 +252,32 @@ 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

[options]
packages = find:
#or
# OR
packages = find_namespace:

.. tab:: setup.py

.. code-block:: python

from setuptools import find_packages
# 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
from setuptools import find_namespace_packages


Finding simple packages
Expand All @@ -303,14 +303,31 @@ 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

[options]
packages = find:
package_dir =
=src
= src

[options.packages.find]
where = src
Expand All @@ -328,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"}
# ...
Expand All @@ -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
Expand Down Expand Up @@ -414,13 +414,24 @@ 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

[options]
package_dir =
=src
= src
packages = find_namespace:

[options.packages.find]
Expand All @@ -439,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"}
# ...
)
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand Down
Loading