Skip to content

Data files fix #2

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

Merged
merged 2 commits into from
Jun 7, 2022
Merged

Data files fix #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10cbf95
Add a more realistic example for exclude-package-data
abravalheri Jun 7, 2022
463b340
Small changes avoiding mentioning distutils directly
abravalheri Jun 7, 2022
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
33 changes: 21 additions & 12 deletions docs/userguide/datafiles.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,19 @@
Data Files Support
====================

The distutils have traditionally allowed installation of "data files", which
Old packaging installation methods in the Python ecosystem
have traditionally allowed installation of "data files", which
are placed in a platform-specific location. However, the most common use case
for data files distributed with a package is for use *by* the package, usually
by including the data files **inside the package directory**.

Setuptools focuses on this most common type of data files and offers three ways
of specifying which files should be included in your packages, as described in
the following sections.

include_package_data
====================

Setuptools offers three ways to specify this most common type of data files to
be included in your packages.
First, you can simply use the ``include_package_data`` keyword.
For example, if the package tree looks like this::

Expand Down Expand Up @@ -239,10 +242,15 @@ exclude_package_data
Sometimes, the ``include_package_data`` or ``package_data`` options alone
aren't sufficient to precisely define what files you want included. For example,
consider a scenario where you have ``include_package_data=True``, and you are using
a revision control system with an appropriate plugin. Your README is probably being
tracked by the revision control system, and therefore by default it will be included
when your package is installed. Supposing you want to prevent this README from being
included in the installation, then you could use the ``exclude_package_data`` option:
a revision control system with an appropriate plugin.
Sometimes developers add directory-specific marker files (such as `.gitignore`,
`.gitkeep`, `.gitattributes`, or `.hgignore`), these files are probably being
tracked by the revision control system, and therefore by default they will be
included when the package is installed.

Supposing you want to prevent these files from being included in the
installation (they are not relevant to Python or the package), then you could
use the ``exclude_package_data`` option:

.. tab:: setup.cfg

Expand All @@ -260,7 +268,7 @@ included in the installation, then you could use the ``exclude_package_data`` op

[options.exclude_package_data]
mypkg =
README.txt
.gitattributes

.. tab:: setup.py

Expand All @@ -272,7 +280,7 @@ included in the installation, then you could use the ``exclude_package_data`` op
packages=find_packages(where="src"),
package_dir={"": "src"},
include_package_data=True,
exclude_package_data={"mypkg": ["README.txt"]},
exclude_package_data={"mypkg": [".gitattributes"]},
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
Expand All @@ -283,13 +291,14 @@ included in the installation, then you could use the ``exclude_package_data`` op
where = ["src"]

[tool.setuptools.exclude-package-data]
mypkg = ["README.txt"]
mypkg = [".gitattributes"]

The ``exclude_package_data`` option is a dictionary mapping package names to
lists of wildcard patterns, just like the ``package_data`` option. And, just
as with that option, you can use the empty string key ``""`` in ``setup.py`` and the
asterisk ``*`` in ``setup.cfg`` and ``pyproject.toml`` to match all top-level packages.
However, any files that match these patterns will be *excluded* from installation,

Any files that match these patterns will be *excluded* from installation,
even if they were listed in ``package_data`` or were included as a result of using
``include_package_data``.

Expand Down Expand Up @@ -434,7 +443,7 @@ In summary, the three options allow you to:
been included due to the use of the preceding options.

.. note::
Due to the way the distutils build process works, a data file that you
Due to the way the build process works, a data file that you
include in your project and then stop including may be "orphaned" in your
project's build directories, requiring you to run ``setup.py clean --all`` to
fully remove them. This may also be important for your users and contributors
Expand Down