`, ``delete_file()``, and
``write_or_delete_file()`` methods exclusively for your file operations.
See those methods' docstrings for more details.


.. _Adding Support for Revision Control Systems:

Adding Support for Revision Control Systems
-------------------------------------------------

If the files you want to include in the source distribution are tracked using
Git, Mercurial or SVN, you can use the following packages to achieve that:

- Git and Mercurial: :pypi:`setuptools_scm`
- SVN: :pypi:`setuptools_svn`

If you would like to create a plugin for ``setuptools`` to find files tracked
by another revision control system, you can do so by adding an entry point to
the ``setuptools.file_finders`` group.  The entry point should be a function
accepting a single directory name, and should yield all the filenames within
that directory (and any subdirectories thereof) that are under revision
control.

For example, if you were going to create a plugin for a revision control system
called "foobar", you would write a function something like this:

.. code-block:: python

    def find_files_for_foobar(dirname):
        ...  # loop to yield paths that start with `dirname`

And you would register it in a setup script using something like this:

.. code-block:: ini

    # setup.cfg
    ...

    [options.entry_points]
    setuptools.file_finders =
        foobar = my_foobar_module:find_files_for_foobar

Then, anyone who wants to use your plugin can simply install it, and their
local setuptools installation will be able to find the necessary files.

It is not necessary to distribute source control plugins with projects that
simply use the other source control system, or to specify the plugins in
``setup_requires``.  When you create a source distribution with the ``sdist``
command, setuptools automatically records what files were found in the
``SOURCES.txt`` file.  That way, recipients of source distributions don't need
to have revision control at all.  However, if someone is working on a package
by checking out with that system, they will need the same plugin(s) that the
original author is using.

A few important points for writing revision control file finders:

* Your finder function MUST return relative paths, created by appending to the
  passed-in directory name.  Absolute paths are NOT allowed, nor are relative
  paths that reference a parent directory of the passed-in directory.

* Your finder function MUST accept an empty string as the directory name,
  meaning the current directory.  You MUST NOT convert this to a dot; just
  yield relative paths.  So, yielding a subdirectory named ``some/dir`` under
  the current directory should NOT be rendered as ``./some/dir`` or
  ``/somewhere/some/dir``, but *always* as simply ``some/dir``

* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
  with the absence of needed programs (i.e., ones belonging to the revision
  control system itself.  It *may*, however, use ``logging.warning()`` to
  inform the user of the missing program(s).


.. _distutils: https://docs.python.org/3.9/library/distutils.html


Final Remarks
-------------

* To use a ``setuptools`` plugin, your users will need to add your package as a
  build requirement to their build-system configuration. Please check out our
  guides on :doc:`/userguide/dependency_management` for more information.

* Directly calling ``python setup.py ...`` is considered a **deprecated** practice.
  You should not add new commands to ``setuptools`` expecting them to be run
  via this interface.
               doc/alt-python311-setuptools/docs/userguide/datafiles.rst                                           0000644                 00000043761 15022576663 0017515 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       ====================
Data Files Support
====================

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
====================

First, you can simply use the ``include_package_data`` keyword.
For example, if the package tree looks like this::

    project_root_directory
    ├── setup.py        # and/or setup.cfg, pyproject.toml
    └── src
        └── mypkg
            ├── __init__.py
            ├── data1.rst
            ├── data2.rst
            ├── data1.txt
            └── data2.txt

and you supply this configuration:

.. tab:: setup.cfg

   .. code-block:: ini

        [options]
        # ...
        packages = find:
        package_dir =
            = src
        include_package_data = True

        [options.packages.find]
        where = src

.. tab:: setup.py

   .. code-block:: python

    from setuptools import setup, find_packages
    setup(
        # ...,
        packages=find_packages(where="src"),
        package_dir={"": "src"},
        include_package_data=True
    )

.. tab:: pyproject.toml (**BETA**) [#beta]_

   .. code-block:: toml

        [tool.setuptools]
        # ...
        # By default, include-package-data is true in pyproject.toml, so you do
        # NOT have to specify this line.
        include-package-data = true

        [tool.setuptools.packages.find]
        where = ["src"]

then all the ``.txt`` and ``.rst`` files will be automatically installed with
your package, provided:

1. These files are included via the |MANIFEST.in|_ file, like so::

        include src/mypkg/*.txt
        include src/mypkg/*.rst

2. OR, they are being tracked by a revision control system such as Git, Mercurial
   or SVN, and you have configured an appropriate plugin such as
   :pypi:`setuptools-scm` or :pypi:`setuptools-svn`.
   (See the section below on :ref:`Adding Support for Revision
   Control Systems` for information on how to write such plugins.)

package_data
============

By default, ``include_package_data`` considers **all** non ``.py`` files found inside
the package directory (``src/mypkg`` in this case) as data files, and includes those that
satisfy (at least) one of the above two conditions into the source distribution, and
consequently in the installation of your package.
If you want finer-grained control over what files are included, then you can also use
the ``package_data`` keyword.
For example, if the package tree looks like this::

    project_root_directory
    ├── setup.py        # and/or setup.cfg, pyproject.toml
    └── src
        └── mypkg
            ├── __init__.py
            ├── data1.rst
            ├── data2.rst
            ├── data1.txt
            └── data2.txt

then you can use the following configuration to capture the ``.txt`` and ``.rst`` files as
data files:

.. tab:: setup.cfg

   .. code-block:: ini

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

        [options.packages.find]
        where = src

        [options.package_data]
        mypkg =
            *.txt
            *.rst

.. tab:: setup.py

    .. code-block:: python

        from setuptools import setup, find_packages
        setup(
            # ...,
            packages=find_packages(where="src"),
            package_dir={"": "src"},
            package_data={"mypkg": ["*.txt", "*.rst"]}
        )

.. tab:: pyproject.toml (**BETA**) [#beta]_

   .. code-block:: toml

        [tool.setuptools.packages.find]
        where = ["src"]

        [tool.setuptools.package-data]
        mypkg = ["*.txt", "*.rst"]

The ``package_data`` argument is a dictionary that maps from package names to
lists of glob patterns. Note that the data files specified using the ``package_data``
option neither require to be included within a |MANIFEST.in|_ file, nor
require to be added by a revision control system plugin.

.. note::
        If your glob patterns use paths, you *must* use a forward slash (``/``) as
        the path separator, even if you are on Windows.  Setuptools automatically
        converts slashes to appropriate platform-specific separators at build time.

.. note::
        Glob patterns do not automatically match dotfiles (directory or file names
        starting with a dot (``.``)). To include such files, you must explicitly start
        the pattern with a dot, e.g. ``.*`` to match ``.gitignore``.

If you have multiple top-level packages and a common pattern of data files for all these
packages, for example::

    project_root_directory
    ├── setup.py        # and/or setup.cfg, pyproject.toml
    └── src
        ├── mypkg1
        │   ├── data1.rst
        │   ├── data1.txt
        │   └── __init__.py
        └── mypkg2
            ├── data2.txt
            └── __init__.py

Here, both packages ``mypkg1`` and ``mypkg2`` share a common pattern of having ``.txt``
data files. However, only ``mypkg1`` has ``.rst`` data files. In such a case, if you want to
use the ``package_data`` option, the following configuration will work:

.. tab:: setup.cfg

   .. code-block:: ini

        [options]
        packages = find:
        package_dir =
            = src

        [options.packages.find]
        where = src

        [options.package_data]
        * =
          *.txt
        mypkg1 =
          data1.rst

.. tab:: setup.py

   .. code-block:: python

        from setuptools import setup, find_packages
        setup(
            # ...,
            packages=find_packages(where="src"),
            package_dir={"": "src"},
            package_data={"": ["*.txt"], "mypkg1": ["data1.rst"]},
        )

.. tab:: pyproject.toml (**BETA**) [#beta]_

   .. code-block:: toml

        [tool.setuptools.packages.find]
        where = ["src"]

        [tool.setuptools.package-data]
        "*" = ["*.txt"]
        mypkg1 = ["data1.rst"]

Notice that if you list patterns in ``package_data`` under the empty string ``""`` in
``setup.py``, and the asterisk ``*`` in ``setup.cfg`` and ``pyproject.toml``, these
patterns are used to find files in every package. For example, we use ``""`` or ``*``
to indicate that the ``.txt`` files from all packages should be captured as data files.
Also note how we can continue to specify patterns for individual packages, i.e.
we specify that ``data1.rst`` from ``mypkg1`` alone should be captured as well.

.. note::
    When building an ``sdist``, the datafiles are also drawn from the
    ``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if
    the ``setup.py`` ``package_data`` list is updated before calling ``setup.py``.

.. note::
   If using the ``include_package_data`` argument, files specified by
   ``package_data`` will *not* be automatically added to the manifest unless
   they are listed in the |MANIFEST.in|_ file or by a plugin like
   :pypi:`setuptools-scm` or :pypi:`setuptools-svn`.

.. https://docs.python.org/3/distutils/setupscript.html#installing-package-data

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.
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

   .. code-block:: ini

        [options]
        # ...
        packages = find:
        package_dir =
            = src
        include_package_data = True

        [options.packages.find]
        where = src

        [options.exclude_package_data]
        mypkg =
            .gitat