### Configure Entry Points for Custom Setup Keywords and Egg Info Writers

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/extension.rst

Configuration example using setup.cfg to define custom setup keywords and egg_info.writers entry points. This allows custom arguments to be processed and written to EGG-INFO files.

```ini
# setup.cfg
...
[options.entry_points]
distutils.setup_keywords =
    foo_bar = setuptools.dist:assert_string_list
egg_info.writers =
    foo_bar.txt = setuptools.command.egg_info:write_arg
```

--------------------------------

### Install Setuptools Core

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Install the latest version of setuptools with core dependencies using pip.

```bash
pip install --upgrade setuptools[core]
```

--------------------------------

### Adding Custom setup() Arguments

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/extension.rst

How to add custom arguments to the setup() function by defining entry points in the distutils.setup_keywords group.

```APIDOC
## Adding Custom setup() Keywords

### Description
Enable custom arguments in `setup()` by providing a validation function via entry points. Note that this is discouraged in favor of declarative configuration.

### Configuration
Add the following to your `setup.cfg`:

```ini
[options.entry_points]
distutils.setup_keywords =
    bar_baz = mypackage.some_module:validate_bar_baz
```

### Behavior
- The entry point must point to a validation function.
- The function is called if the argument is provided in the `setup()` call.
```

--------------------------------

### Example MANIFEST.in Configuration

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/miscellaneous.rst

Illustrates common commands for including directories and files, and excluding specific patterns.

```bash
# MANIFEST.in -- just for illustration
graft src
graft tests
graft docs
# `-> adds all files inside a directory

include tox.ini
# `-> matches file paths relative to the root of the project

global-exclude *~ *.py[cod] *.so
# `-> matches file names (regardless of directory)
```

--------------------------------

### Console script example with fallback

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Demonstrates the expected output when only the 'timmins' package is installed, showing the default 'Hello world' output.

```pycon
>>> from timmins import hello_world
>>> hello_world()
Hello world
```

--------------------------------

### Install with Legacy Editable Mode

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/development_mode.rst

Use this command to install in compat mode, emulating the legacy 'python setup.py develop' behavior. This mode is transitional and may be removed in future versions.

```bash
pip install -e . --config-settings editable_mode=compat
```

--------------------------------

### setup.cfg Project Metadata

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Specifies project metadata and install requirements using setup.cfg.

```ini
[metadata]
name = mypackage
version = 0.0.1

[options]
install_requires =
    requests
    importlib-metadata; python_version<"3.10"
```

--------------------------------

### Minimal setup.py for editable installs

Source: https://github.com/pypa/setuptools/blob/main/docs/references/keywords.rst

Use this minimal configuration for setuptools versions older than 64.0.0 to support editable installs when using declarative configuration.

```python
from setuptools import setup

setup()
```

--------------------------------

### Configure Package Data in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/datafiles.rst

Define package data within the setup() function in setup.py using the 'package_data' argument. This example includes .txt files for 'mypkg' and .rst files for 'mypkg.data'. Use find_namespace_packages for namespace packages.

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

--------------------------------

### Console script example with plugin

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Demonstrates the expected output when both 'timmins' and a plugin like 'timmins-plugin-fancy' are installed, showing the plugin's customized output.

```pycon
>>> from timmins import hello_world
>>> hello_world()
!!! Hello world !!!
```

--------------------------------

### Define Custom setup() Argument Entry Point

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/extension.rst

Add a custom argument to the setup() call by defining an entry point in the 'distutils.setup_keywords' group. The entry point specifies a validation function for the argument. The validation function is called only if the argument is provided during the setup() call.

```ini
# setup.cfg
...
[options.entry_points]
distutils.commands =
     foo = mypackage.some_module:foo
distutils.setup_keywords =
    bar_baz = mypackage.some_module:validate_bar_baz
```

--------------------------------

### Enable Setuptools Self-Installation

Source: https://github.com/pypa/setuptools/blob/main/NEWS.rst

Include ez_setup.py in your source distribution and call use_setuptools() to automatically bootstrap setuptools during installation.

```python
from ez_setup import use_setuptools
use_setuptools()

from setuptools import setup
# etc...
```

--------------------------------

### Build and install distribution

Source: https://github.com/pypa/setuptools/blob/main/docs/build_meta.rst

Commands to install the build tool, generate distribution files, and install the resulting packages.

```bash
$ pip install -q build
$ python -m build
```

```bash
$ pip install dist/meowpkg-0.0.1.whl
```

```bash
$ pip install dist/meowpkg-0.0.1.tar.gz
```

--------------------------------

### Configure package discovery and exclusions in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/datafiles.rst

Use the setup function with find_packages and the exclude_package_data dictionary to manage package contents.

```python
from setuptools import setup, find_packages
setup(
    # ...,
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    include_package_data=True,
    exclude_package_data={"mypkg": [".gitattributes"]},
)
```

--------------------------------

### Configure Package Data in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/datafiles.rst

Specify package data using the [options.package_data] section in setup.cfg. This example includes .txt files for 'mypkg' and .rst files for 'mypkg.data'. Ensure 'packages = find_namespace:' and 'package_dir = = src' are set for namespace packages.

```ini
[options]
# ...
packages = find_namespace:
package_dir =
    = src

[options.packages.find]
where = src

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

--------------------------------

### Interpreting Entry Point Syntax

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Examples showing how different entry point syntax configurations are resolved by the Python ecosystem.

```python
import <package_or_module>
parsed_value = <package_or_module>
```

```python
from <package_or_module> import <object>
parsed_value = <object>
```

```python
from <package_or_module> import <object>
parsed_value = <object>.<attr>.<nested_attr>
```

--------------------------------

### Specify Project Dependencies (setup.cfg)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Declare project dependencies in setup.cfg. These will be automatically installed with your package.

```ini
[options]
install_requires =
    docutils
    requests <= 0.4
```

--------------------------------

### Configure Console Scripts Entry Points (setup.py)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Define console script entry points in setup.py. This allows users to run commands directly after installation.

```python
setup(
    # ...
    entry_points={
        'console_scripts': [
            'cli-name = mypkg.mymodule:some_func',
        ]
    }
)
```

--------------------------------

### Specify Project Dependencies (setup.py)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Declare project dependencies in setup.py. These will be automatically installed with your package.

```python
setup(
    # ...
    install_requires=["docutils", "requests <= 0.4"],
    # ...
)
```

--------------------------------

### Run Setup Script in Sandbox

Source: https://github.com/pypa/setuptools/blob/main/NEWS.rst

Use the setuptools.sandbox.run_setup() API to invoke a setup script within a directory sandbox. This prevents the script from writing outside the designated build area.

```python
from setuptools.sandbox import run_setup

# Example usage (assuming setup_script.py exists):
# run_setup('setup_script.py')
```

--------------------------------

### Configure Console Scripts Entry Points (setup.cfg)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Define console script entry points in setup.cfg. This allows users to run commands directly after installation.

```ini
[options.entry_points]
console_scripts =
    cli-name = mypkg.mymodule:some_func
```

--------------------------------

### Execute a setup.py alias

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/distribution.rst

Once defined, an alias can be used like any other setuptools command. This example shows how to execute the 'release' alias, which in turn runs 'sdist' and 'bdist_egg'.

```shell
setup.py release sdist bdist_egg
```

--------------------------------

### Define a setup.py alias

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/distribution.rst

Use the 'alias' command to create a shortcut for a sequence of operations. This example defines an alias for 'release' that first runs 'egg_info -Db ""'.

```shell
setup.py alias -u release egg_info -Db ""
```

--------------------------------

### Include Package Data (setup.cfg)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Enable inclusion of data files within packages using setup.cfg. Setuptools will install data files found in your packages.

```ini
[options]
include_package_data = True
```

--------------------------------

### Project directory structure for data files

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/datafiles.rst

Example layout showing data files placed in a subdirectory versus the package root.

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

--------------------------------

### Include Package Data (setup.py)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Enable inclusion of data files within packages using setup.py. Setuptools will install data files found in your packages.

```python
setup(
    # ...
    include_package_data=True,
    # ...
)
```

--------------------------------

### Configure Package Directory in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/package_discovery.rst

Use the 'package_dir' argument in the setup() function in setup.py to map package names to directory paths. This allows flexibility in project structure.

```python
setup(
    # ...
    package_dir = {"" = "src"}
    # directory containing all the packages (e.g.  src/mypkg, src/mypkg/subpkg1, ...)
)

# OR

setup(
    # ...
    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
        # ...
    }
)
```

--------------------------------

### Configure package data in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/datafiles.rst

Pass the `package_data` argument to the `setup` function. Use an empty string `""` to apply patterns to all packages, and specific package names for individual packages.

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

--------------------------------

### Optional Dependencies in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Define optional dependencies for a package using the 'extras_require' argument in setup.py. This allows users to install specific sets of dependencies for optional features.

```python
setup(
    name="Package-B",
    ...,
    extras_require={
        "PDF": ["ReportLab"],
        "Image": ["Pillow"],
    },
)
```

--------------------------------

### Manually Specify Packages in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/package_discovery.rst

Use the 'packages' argument in the setup() function in setup.py to list packages explicitly. This method is common for Python-based build configurations.

```python
setup(
    # ...
    packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2']
)
```

--------------------------------

### Optional Dependencies in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Define optional dependencies for a package using the 'extras_require' argument in setup.cfg. This allows users to install specific sets of dependencies for optional features.

```ini
[options]
#...
extras_require = 
    PDF = ReportLab
    Image = Pillow

```

--------------------------------

### Install Virtual Environment Tool

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/development_mode.rst

If the venv module is not installed by default, you may need to install it using your OS package manager or install the 'virtualenv' package. This example shows installation on Debian/Ubuntu-based systems.

```bash
sudo apt install python3-venv
```

--------------------------------

### Define Custom distutils Command Entry Point

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/extension.rst

Add a custom command by defining an entry point in the 'distutils.commands' group. The handler must be a setuptools.Command subclass. This command will be available after the package is installed.

```ini
# setup.cfg
...
[options.entry_points]
distutils.commands =
     foo = mypackage.some_module:foo
```

--------------------------------

### Set up package metadata and options in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/declarative_config.rst

Use setup.cfg to declare package metadata and build options. Supports directives like 'file:', 'attr:', and 'find:'.

```ini
[metadata]
name = my_package
version = attr: my_package.VERSION
author = Josiah Carberry
author_email = josiah_carberry@brown.edu
description = My package description
long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
keywords = one, two
license = BSD-3-Clause
classifiers =
    Framework :: Django
    Programming Language :: Python :: 3

[options]
zip_safe = False
include_package_data = True
packages = find:
python_requires = >=3.8
install_requires =
    requests
    importlib-metadata; python_version<"3.10"

[options.package_data]
* = *.txt, *.rst
hello = *.msg

[options.entry_points]
console_scripts =
    executable-name = my_package.module:function

[options.extras_require]
pdf = ReportLab>=1.2; RXP
rest = docutils>=0.3; pack ==1.1, ==1.3

[options.packages.find]
exclude =
    examples*
    tools*
    docs*
    my_package.tests*
```

--------------------------------

### Compare version strings

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/distribution.rst

Demonstrates how setuptools parses and compares different versioning schemes.

```python
>>> parse_version("1.9.a.dev") == parse_version("1.9a0dev")
True
>>> parse_version("2.1-rc2") < parse_version("2.1")
True
>>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9")
True
```

--------------------------------

### setup.py Project Metadata

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Configures project name, version, and dependencies using a setup.py script.

```python
from setuptools import setup

setup(
    name='mypackage',
    version='0.0.1',
    install_requires=[
        'requests',
        'importlib-metadata; python_version<"3.10"',
    ],
)
```

--------------------------------

### Configure multiple entry points in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Configures two entry points, 'excl' and 'lined', under the 'timmins.display' group using setup.py. Entry points are provided as a list of strings.

```python
from setuptools import setup

setup(
    # ...,
    entry_points = {
        'timmins.display': [
            'excl = timmins_plugin_fancy:excl_display',
            'lined = timmins_plugin_fancy:lined_display',
        ]
    }
)
```

--------------------------------

### Declare Required Dependencies

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Define core package dependencies that are automatically installed during package installation.

```toml
[project]
# ...
dependencies = [
    "docutils",
    "BazSpam == 1.1",
]
# ...
```

```ini
[options]
#...
install_requires =
    docutils
    BazSpam ==1.1
```

```python
setup(
    ...,
    install_requires=[
        'docutils',
        'BazSpam ==1.1',
    ],
)
```

--------------------------------

### Install Build Tool

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Install the 'build' tool using pip, which is recommended for creating Python packages.

```bash
pip install --upgrade build
```

--------------------------------

### setuptools.setup() Configuration Keywords

Source: https://github.com/pypa/setuptools/blob/main/docs/references/keywords.rst

A comprehensive list of parameters accepted by the setuptools.setup() function to define package metadata and build behavior.

```APIDOC
## setuptools.setup() Configuration

### Description
Configures the build process and metadata for a Python distribution.

### Parameters
- **name** (string) - Package name.
- **version** (string) - Package version number.
- **description** (string) - Single-line package description.
- **long_description** (string) - Detailed package description.
- **long_description_content_type** (string) - Content type of long_description (e.g., text/markdown).
- **author** (string) - Author name.
- **author_email** (string) - Author email address.
- **maintainer** (string) - Maintainer name.
- **maintainer_email** (string) - Maintainer email address.
- **url** (string) - Package homepage URL.
- **download_url** (string) - Package download URL.
- **packages** (list) - List of packages to include.
- **py_modules** (list) - List of modules to include.
- **scripts** (list) - List of standalone script files.
- **ext_package** (string) - Base package name for extensions.
- **ext_modules** (list) - List of setuptools.Extension instances.
- **classifiers** (list) - List of category strings.
- **distclass** (object) - Subclass of Distribution.
- **script_name** (string) - Name of the setup.py script.
- **script_args** (list) - Arguments for the setup script.
- **options** (dict) - Default options for the setup script.
- **license** (string) - Package license.
- **license_files** (list) - Glob patterns for license files.
- **keywords** (list/string) - Descriptive metadata keywords.
- **platforms** (list/string) - Supported platforms.
- **cmdclass** (dict) - Mapping of command names to Command subclasses.
- **data_files** (list) - Files to be installed (discouraged).
```

--------------------------------

### Configure src/ layout for package discovery

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/declarative_config.rst

Set up setup.cfg for a src/ directory layout, specifying package_dir and using 'packages=find:'. Ensure 'where' in [options.packages.find] matches the package_dir.

```ini
# This example contains just the necessary options for a src-layout, set up
# the rest of the file as described above.

[options]
package_dir=
    =src
packages=find:

[options.packages.find]
where=src
```

--------------------------------

### Configure entry point in setup.py

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Configures a single entry point named 'excl' under the 'timmins.display' group using setup.py. This method uses a dictionary structure to define entry points.

```python
from setuptools import setup

setup(
    # ...,
    entry_points = {
        'timmins.display': [
            'excl = timmins_plugin_fancy:excl_display'
        ]
    }
)
```

--------------------------------

### Install Project in Strict Development Mode

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/development_mode.rst

To enforce a stricter editable install that mimics a regular installation more closely, use the --config-settings editable_mode=strict flag with pip. This mode will not expose new files automatically and requires auxiliary files to be managed carefully.

```bash
pip install -e . --config-settings editable_mode=strict
```

--------------------------------

### Setuptools Package Discovery with Inclusion/Exclusion (setup.cfg)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/package_discovery.rst

Configuration in setup.cfg to specify package discovery rules. It uses 'find:' and defines package directories, inclusion patterns, and exclusion patterns.

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

[options.packages.find]
where = src
include = pkg*
# alternatively: `exclude = additional*`
```

--------------------------------

### Install Project in Development Mode

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/development_mode.rst

Use pip's --editable flag to install a project in development mode. This allows changes in the source code to take effect immediately without re-installation. Ensure you are in a virtual environment and have activated it.

```bash
cd your-python-project
python -m venv .venv
# Activate your environment with:
#      `source .venv/bin/activate` on Unix/macOS
# or   `.venv\Scripts\activate` on Windows

pip install --editable .

# Now you have access to your package
# as if it was installed in .venv
python -c "import your_python_project"
```

--------------------------------

### eager_resources Configuration

Source: https://github.com/pypa/setuptools/blob/main/docs/references/keywords.rst

Defines resources that must be extracted together when installed as a zipfile.

```APIDOC
## eager_resources

### Description
A list of strings naming resources that should be extracted together, if any of them is needed, or if any C extensions included in the project are imported. This is only useful if the project is installed as a zipfile.

### Parameters
- **resources** (list of strings) - Required - '/'-separated paths relative to the source root (e.g., 'bar/baz/foo.png').
```

--------------------------------

### Invoke a console script command

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Running the installed console script directly from the terminal.

```bash
$ hello-world
Hello world
```

--------------------------------

### Create a feature changelog fragment

Source: https://github.com/pypa/setuptools/blob/main/newsfragments/README.rst

Example of a feature-related changelog entry for PR 2355.

```rst
When pip is imported as part of a build, leave :py:mod:`distutils`
patched -- by :user:`jaraco`
```

--------------------------------

### Read configuration file with setuptools

Source: https://github.com/pypa/setuptools/blob/main/docs/setuptools.rst

Parses a setup.cfg file into a dictionary using the read_configuration function.

```python
from setuptools.config import read_configuration

conf_dict = read_configuration("/home/user/dev/package/setup.cfg")
```

--------------------------------

### Create a miscellaneous changelog fragment

Source: https://github.com/pypa/setuptools/blob/main/newsfragments/README.rst

Example of a miscellaneous changelog entry for PR 1354.

```rst
Added ``towncrier`` for changelog management -- by :user:`pganssle`
```

--------------------------------

### Build documentation locally

Source: https://github.com/pypa/setuptools/blob/main/docs/development/developer-guide.rst

Use tox to build the project documentation using Sphinx.

```bash
$ tox -e docs
```

--------------------------------

### Create a documentation changelog fragment

Source: https://github.com/pypa/setuptools/blob/main/newsfragments/README.rst

Example of a documentation-related changelog entry for PR 2395.

```rst
Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`
```

--------------------------------

### Configure entry point in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Configures a single entry point named 'excl' under the 'timmins.display' group using setup.cfg. This format is common for older setuptools projects.

```ini
[options.entry_points]
timmins.display =
    excl = timmins_plugin_fancy:excl_display
```

--------------------------------

### Specify Project Dependencies (pyproject.toml)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/quickstart.rst

Declare project dependencies in pyproject.toml. These will be automatically installed with your package.

```toml
[project]
# ...
dependencies = [
    "docutils",
    "requests <= 0.4",
]
# ...
```

--------------------------------

### Configure multiple entry points in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

Configures two entry points, 'excl' and 'lined', under the 'timmins.display' group using setup.cfg. Each entry point is listed on a new line.

```ini
[options.entry_points]
timmins.display =
    excl = timmins_plugin_fancy:excl_display
    lined = timmins_plugin_fancy:lined_display
```

--------------------------------

### Define Optional Dependencies

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Declare extra sets of dependencies that are not installed by default, allowing for optional package functionality.

```toml
[project]
name = "Package-A"
# ...
[project.optional-dependencies]
PDF = ["ReportLab>=1.2", "RXP"]
```

```ini
[metadata]
name = Package-A

[options.extras_require]
PDF =
    ReportLab>=1.2
    RXP
```

```python
setup(
    name="Package-A",
    ...,
    extras_require={
        "PDF": ["ReportLab>=1.2", "RXP"],
    },
)
```

--------------------------------

### Define Environment-Specific Dependencies

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Use environment markers to conditionally install packages based on Python version or platform.

```python
setup(
    ...,
    install_requires=[
        "enum34;python_version<'3.4'",
    ],
)
```

```toml
[project]
# ...
dependencies = [
    "enum34; python_version<'3.4'",
    "pywin32 >= 1.0; platform_system=='Windows'",
]
# ...
```

```ini
[options]
#...
install_requires =
    enum34;python_version<'3.4'
    pywin32 >= 1.0;platform_system=='Windows'
```

```python
setup(
    ...,
    install_requires=[
        "enum34;python_version<'3.4'",
        "pywin32 >= 1.0;platform_system=='Windows'",
    ],
)
```

--------------------------------

### Setuptools Custom Package Discovery (setup.cfg)

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/package_discovery.rst

Configuration for custom package discovery using 'find:' or 'find_namespace:' in setup.cfg. This allows explicit control over which packages are included.

```ini
[options]
packages = find:
#or
packages = find_namespace:
```

--------------------------------

### Declare Platform-Specific Dependencies

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Use environment markers to conditionally install dependencies based on platform or Python version.

```toml
[project]
# ...
dependencies = [
    "enum34; python_version<'3.4'",
]
# ...
```

--------------------------------

### Deprecated Entry Points with Extras in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/dependency_management.rst

Historically, setuptools supported associating entry points with extra dependencies in setup.cfg. This practice is now deprecated due to potential compatibility issues with tools like pip.

```ini
[metadata]
name = Package-A
#...

[options]
#...
entry_points=
    [console_scripts]
    rst2pdf = project_a.tools.pdfgen [PDF]
    rst2html = project_a.tools.htmlgen

```

--------------------------------

### Configure Dynamic Metadata in pyproject.toml

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/pyproject_config.rst

Examples of using 'attr' and 'file' directives to define project metadata dynamically.

```toml
version = {attr = "my_package.__version__"}  # any module attribute compatible with ast.literal_eval
readme = {file = ["README.rst", "USAGE.rst"]}
```

```toml
readme = {file = ["README.txt", "USAGE.txt"], content-type = "text/plain"}
```

--------------------------------

### Example DistributionNotFound Error Message

Source: https://github.com/pypa/setuptools/blob/main/NEWS.rst

This represents the format of the error message raised by pkg_resources when a required distribution is missing.

```text
pkg_resources.DistributionNotFound: The 'colorama>=0.3.1' distribution was not found and is required by smlib.log.
```

--------------------------------

### Configure package discovery and exclusions in setup.cfg

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/datafiles.rst

Define package options and exclusions using the [options] and [options.exclude_package_data] sections.

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

[options.packages.find]
where = src

[options.exclude_package_data]
mypkg =
    .gitattributes
```

--------------------------------

### Distributing Extensions Compiled with Cython

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/ext_modules.rst

Guidance on how setuptools handles Cython extensions and how to include them in distributions.

```APIDOC
## Distributing Extensions Compiled with Cython

### Overview

When extension modules are declared using the `setuptools.Extension` class, setuptools automatically detects and utilizes Cython if it's installed during the build process. If Cython is not present, setuptools attempts to compile equivalent C files generated by the Cython command-line tool.

### Build Dependencies

To ensure Cython is always installed in the build environment, include it in your `pyproject.toml` under `[build-system].requires`:

```toml
[build-system]
requires = [
    # ... other dependencies
    "cython",
]
```

### Including Pre-compiled C Files

Alternatively, you can include C files pre-compiled by Cython alongside the original `.pyx` files in your source distribution. This can speed up builds from source distributions (`sdist`). It is also recommended to include these C files in your version control system to ensure compatibility and allow building without a local Cython installation.

For more information, refer to the documentation on controlling files in the distribution.
```

--------------------------------

### Basic hello_world Function

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/entry_point.rst

A simple Python function that prints 'Hello world'. This serves as a basic example for an entry point.

```python
def hello_world():
    print('Hello world')
```

--------------------------------

### Specify Cython as a Build Dependency

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/ext_modules.rst

Include Cython in the build-system.requires list in pyproject.toml to ensure it's automatically installed in the build environment.

```toml
[build-system]
requires = [
    # ...,
    "cython",
]

```

--------------------------------

### Demonstrate namespace package import behavior

Source: https://github.com/pypa/setuptools/blob/main/docs/userguide/package_discovery.rst

Example showing how two separate packages on the PYTHONPATH can be imported as a single namespace package.

```pycon
>>> import timmins.foo
>>> import timmins.bar
```