Setuptools

=======


Changes
-------
* 3215: Ignored a subgroup of invalid ``pyproject.toml`` files that use the ``[project]``
table to specify only ``requires-python`` (**transitional**).

.. warning::
Please note that future releases of setuptools will halt the build process
if a ``pyproject.toml`` file that does not match doc:`the PyPA Specification
<PyPUG:specifications/section-distribution-metadata>` is given.
* 3215: Updated ``pyproject.toml`` validation, as generated by ``validate-pyproject==0.6.1``.
* 3218: Prevented builds from erroring if the project specifies metadata via
``pyproject.toml``, but uses other files (e.g. ``setup.py``) to complement it,
without setting ``dynamic`` properly.

.. important::
This is a **transitional** behaviour.
Future releases of ``setuptools`` may simply ignore externally set metadata
not backed by ``dynamic`` or even halt the build with an error.
* 3224: Merge changes from pypa/distutilse1d5c9b1f6

Documentation changes
---------------------
* 3217: Fixed typo in ``pyproject.toml`` example in Quickstart -- by :user:`pablo-cardenas`.

Misc
----
* 3223: Fixed missing requirements with environment markers when
``optional-dependencies`` is set in ``pyproject.toml``.

=======


Misc
----
* 3212: Fixed missing dependencies when running ``setup.py install``.
Note that calling ``setup.py install`` directly is still deprecated and
will be removed in future versions of ``setuptools``.
Please check the release notes for :ref:`setup_install_deprecation_note`.

=======


Deprecations
------------
* 3206: Changed ``setuptools.convert_path`` to an internal function that is not exposed
as part of setuptools API.
Future releases of ``setuptools`` are likely to remove this function.

Changes
-------
* 3202: Changed behaviour of auto-discovery to not explicitly expand ``package_dir``
for flat-layouts and to not use relative paths starting with ``./``.
* 3203: Prevented ``pyproject.toml`` parsing from overwriting
``dist.include_package_data`` explicitly set in ``setup.py`` with default
value.
* 3208: Added a warning for non existing files listed with the ``file`` directive in
``setup.cfg`` and ``pyproject.toml``.
* 3208: Added a default value for dynamic ``classifiers`` in ``pyproject.toml`` when
files are missing and errors being ignored.
* 3211: Disabled auto-discovery when distribution class has a ``configuration``
attribute (e.g. when the ``setup.py`` script contains ``setup(...,
configuration=...)``). This is done to ensure extension-only packages created
with ``numpy.distutils.misc_util.Configuration`` are not broken by the safe
guard
behaviour to avoid accidental multiple top-level packages in a flat-layout.

.. note::
Users that don't set ``packages``, ``py_modules``, or ``configuration`` are
still likely to observe the auto-discovery behavior, which may halt the
build if the project contains multiple directories and/or multiple Python
files directly under the project root.

To disable auto-discovery please explicitly set either ``packages`` or
``py_modules``. Alternatively you can also configure :ref:`custom-discovery`.

=======


Deprecations
------------
* 3068: Deprecated ``setuptools.config.read_configuration``,
``setuptools.config.parse_configuration`` and other functions or classes
from ``setuptools.config``.

Users that still need to parse and process configuration from ``setup.cfg`` can
import a direct replacement from ``setuptools.config.setupcfg``, however this
module is transitional and might be removed in the future
(the ``setup.cfg`` configuration format itself is likely to be deprecated in the future).

Breaking Changes
----------------
* 2894: If you purposefully want to create an *"empty distribution"*, please be aware
that some Python files (or general folders) might be automatically detected and
included.

Projects that currently don't specify both ``packages`` and ``py_modules`` in their
configuration and contain extra folders or Python files (not meant for distribution),
might see these files being included in the wheel archive or even experience
the build to fail.

You can check details about the automatic discovery (and how to configure a
different behaviour) in :doc:`/userguide/package_discovery`.
* 3067: If the file ``pyproject.toml`` exists and it includes project
metadata/config (via ``[project]`` table or ``[tool.setuptools]``),
a series of new behaviors that are not backward compatible may take place:

- The default value of ``include_package_data`` will be considered to be ``True``.
- Setuptools will attempt to validate the ``pyproject.toml`` file according
to PEP 621 specification.
- The values specified in ``pyproject.toml`` will take precedence over those
specified in ``setup.cfg`` or ``setup.py``.

Changes
-------
* 2887: **[EXPERIMENTAL]** Added automatic discovery for ``py_modules`` and ``packages``
-- by :user:`abravalheri`.

Setuptools will try to find these values assuming that the package uses either
the *src-layout* (a ``src`` directory containing all the packages or modules),
the *flat-layout* (package directories directly under the project root),
or the *single-module* approach (an isolated Python file, directly under
the project root).

The automatic discovery will also respect layouts that are explicitly
configured using the ``package_dir`` option.

For backward-compatibility, this behavior will be observed **only if both**
``py_modules`` **and** ``packages`` **are not set**.
(**Note**: specifying ``ext_modules`` might also prevent auto-discover from
taking place)

If setuptools detects modules or packages that are not supposed to be in the
distribution, please manually set ``py_modules`` and ``packages`` in your
``setup.cfg`` or ``setup.py`` file.
If you are using a *flat-layout*, you can also consider switching to
*src-layout*.
* 2887: **[EXPERIMENTAL]** Added automatic configuration for the ``name`` metadata
-- by :user:`abravalheri`.

Setuptools will adopt the name of the top-level package (or module in the case
of single-module distributions), **only when** ``name`` **is not explicitly
provided**.

Please note that it is not possible to automatically derive a single name when
the distribution consists of multiple top-level packages or modules.
* 3066: Added vendored dependencies for :pypi:`tomli`, :pypi:`validate-pyproject`.

These dependencies are used to read ``pyproject.toml`` files and validate them.
* 3067: **[EXPERIMENTAL]** When using ``pyproject.toml`` metadata,
the default value of ``include_package_data`` is changed to ``True``.
* 3068: **[EXPERIMENTAL]** Add support for ``pyproject.toml`` configuration
(as introduced by :pep:`621`). Configuration parameters not covered by
standards are handled in the ``[tool.setuptools]`` sub-table.

In the future, existing ``setup.cfg`` configuration
may be automatically converted into the ``pyproject.toml`` equivalent before taking effect
(as proposed in 1688). Meanwhile users can use automated tools like
:pypi:`ini2toml` to help in the transition.

Please note that the legacy backend is not guaranteed to work with
``pyproject.toml`` configuration.

-- by :user:`abravalheri`
* 3125: Implicit namespaces (as introduced in :pep:`420`) are now considered by default
during :doc:`package discovery </userguide/package_discovery>`, when
``setuptools`` configuration and project metadata are added to the
``pyproject.toml`` file.

To disable this behaviour, use ``namespaces = False`` when explicitly setting
the ``[tool.setuptools.packages.find]`` section in ``pyproject.toml``.

This change is backwards compatible and does not affect the behaviour of
configuration done in ``setup.cfg`` or ``setup.py``.
* 3152: **[EXPERIMENTAL]** Added support for ``attr:`` and ``cmdclass`` configurations
in ``setup.cfg`` and ``pyproject.toml`` when ``package_dir`` is implicitly
found via auto-discovery.
* 3178: Postponed importing ``ctypes`` when hiding files on Windows.
This helps to prevent errors in systems that might not have ``libffi`` installed.
* 3179: Merge with pypa/distutils267dbd25ac

Documentation changes
---------------------
* 3172: Added initial documentation about configuring ``setuptools`` via ``pyproject.toml``
(using standard project metadata).

Misc
----
* 3065: Refactored ``setuptools.config`` by separating configuration parsing (specific
to the configuration file format, e.g. ``setup.cfg``) and post-processing
(which includes directives such as ``file:`` that can be used across different
configuration formats).

========


Changes
-------
* 2971: Deprecated upload_docs command, to be removed in the future.
* 3137: Use samefile from stdlib, supported on Windows since Python 3.2.
* 3170: Adopt nspektr (vendored) to implement Distribution._install_dependencies.

Documentation changes
---------------------
* 3144: Added documentation on using console_scripts from setup.py, which was previously only shown in setup.cfg -- by :user:`xhlulu`
* 3148: Added clarifications about ``MANIFEST.in``, that include links to PyPUG docs
and more prominent mentions to using a revision control system plugin as an
alternative.
* 3148: Removed mention to ``pkg_resources`` as the recommended way of accessing data
files, in favour of importlib.resources.
Additionally more emphasis was put on the fact that *package data files* reside
**inside** the *package directory* (and therefore should be *read-only*).

Misc
----
* 3120: Added workaround for intermittent failures of backend tests on PyPy.
These tests now are marked with `XFAIL
<https://docs.pytest.org/en/stable/how-to/skipping.html>`_, instead of erroring
out directly.
* 3124: Improved configuration for :pypi:`rst-linker` (extension used to build the
changelog).
* 3133: Enhanced isolation of tests using virtual environments - PYTHONPATH is not leaking to spawned subprocesses -- by :user:`befeleme`
* 3147: Added options to provide a pre-built ``setuptools`` wheel or sdist for being
used during tests with virtual environments.
Paths for these pre-built distribution files can now be set via the environment
variables: ``PRE_BUILT_SETUPTOOLS_SDIST`` and ``PRE_BUILT_SETUPTOOLS_WHEEL``.

=======


Misc
----
* 3093: Repaired automated release process.