setuptools

To share a Python library or program, you must build a distribution package. This involves adding metadata and configuration files that instruct setuptools on how to build the distribution and assist installers like pip during the installation process.

Note that setuptools acts as a build backend. While setuptools handles the build logic, users typically interact with it through front-end tools like pip or build. To use setuptools as a build backend, you must explicitly create a pyproject.toml file.

In setuptools, "data files" refers to non-Python files that are installed alongside Python modules and packages when a distribution is installed via a wheel. These files are typically intended for use at runtime by the package itself or to influence the behavior of other packages or systems.

Setuptools provides three primary ways to specify which non-Python files should be included in your packages, primarily focusing on including them inside the package directory.

The primary test suite for Setuptools is managed using tox. Ensure you have tox installed in your environment before running the command.

To execute the tests, run:

$ tox

SPDX expressions and the license-files field require setuptools v77.0.0 or later. Because build frontends like pip and build often use isolated environments, you should specify this requirement in your [build-system] table to ensure the build backend can parse the new license format.

[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
license = "Apache-2.0"
license-files = ["LICENSE"]

If your Python source code is located in a subdirectory (commonly src/), you must configure package_dir and packages.find in your setup.cfg to ensure correct discovery.

To map the root package directory to the src folder, use package_dir = =src. The =src syntax is parsed as {"": "src"}, where the empty string key indicates that all packages are contained within that directory.

In the [options.packages.find] section, set where=src to match the directory specified in package_dir.

[options]
package_dir =
    =src
packages = find:

[options.packages.find]
where = src

To add a new keyword argument to the setup() function, define an entry point in the distutils.setup_keywords group. The entry point must point to a validation function that accepts three arguments: the Distribution object, the attribute name, and the attribute value.

Note: Adding arguments to setup() is discouraged as it is only supported through imperative execution and not through declarative configuration. The default value for these arguments is always None.

To allow plugins to include application-specific metadata in the .egg-info directory, use the egg_info.writers entry point group.

A writer function must accept three arguments:

1. The egg_info command instance (cmd).
2. The basename of the file to write (e.g., foo_bar.txt).
3. The full filename to be written.

To ensure compatibility with dry_run settings and proper logging, use the command object's file methods: cmd.write_file(), cmd.delete_file(), or cmd.write_or_delete_file().

# setup.cfg
[options.entry_points]
egg_info.writers =
    foo_bar.txt = setuptools.command.egg_info:write_arg

If you are not using pyproject.toml, you can define console scripts using setup.cfg or setup.py.

# setup.cfg
[options.entry_points]
console_scripts =
    hello-world = timmins:hello_world

# setup.py
from setuptools import setup

setup(
    # ...
    entry_points={
        'console_scripts': [
            'hello-world = timmins:hello_world',
        ]
    }
)

The setuptools logo is designed to be used primarily over a white or light background. Depending on your use case, you can use the following variations:

• Standard: Over a white/light background.
• negative: For dark backgrounds (e.g., dark mode). Swap the background color (#FFFFFF) with the design's blue color (#336790).
• monochrome: For black and white media. Use a completely black or white version.
• banner: Use the symbol and text alongside each other depending on available space.

Design Specifications:

• Blue: #336790 (dark pastel azure)
• Yellow: #E5B62F (pale orange)
• Typography: Monoid typeface (open source webfont).