Setuptools

=======


Documentation changes
---------------------
* 3529: Added clarification to :doc:`/userguide/quickstart` about support
to ``setup.py``.

Misc
----
* 3526: Fixed backward compatibility of editable installs and custom ``build_ext``
commands inheriting directly from ``distutils``.
* 3528: Fixed ``buid_meta.prepare_metadata_for_build_wheel`` when
given ``metadata_directory`` is ``"."``.

=======


Breaking Changes
----------------
* 3505: Removed 'msvccompiler' and 'msvc9compiler' modules from distutils.
* 3521: Remove bdist_msi and bdist_wininst commands, which have been deprecated since Python 3.9. Use older Setuptools for these behaviors if needed.

Documentation changes
---------------------
* 3519: Changed the note in ``keywords`` documentation regarding editable installations
to specify which ``setuptools`` version require a minimal ``setup.py`` file or not.

=======


Misc
----
* 3515: Fixed "inline" file copying for editable installations and
optional extensions.
* 3517: Fixed ``editable_wheel`` to ensure other commands are finalized before using
them. This should prevent errors with plugins trying to use different commands
or reinitializing them.
* 3517: Augmented filter to prevent transient/temporary source files from being
considered ``package_data`` or ``data_files``.

=======


Misc
----
* 3506: Suppress errors in custom ``build_py`` implementations when running editable
installs in favor of a warning indicating what is the most appropriate
migration path.
This is a *transitional* measure. Errors might be raised in future versions of
``setuptools``.
* 3512: Added capability of handling namespace packages created
accidentally/purposefully via discovery configuration during editable installs.
This should emulate the behaviour of a non-editable installation.

=======


Misc
----
* 3497: Fixed ``editable_wheel`` for legacy namespaces.
* 3502: Fixed issue with editable install and single module distributions.
* 3503: Added filter to ignore external ``.egg-info`` files in manifest.

Some plugins might rely on the fact that the ``.egg-info`` directory is
produced inside the project dir, which may not be the case in editable installs
(the ``.egg-info`` directory is produced inside the metadata directory given by
the build frontend via PEP 660 hooks).

=======


Deprecations
------------
* 3380: Passing some types of parameters via ``--global-option`` to setuptools PEP 517/PEP 660 backend
is now considered deprecated. The user can pass the same arbitrary parameter
via ``--build-option`` (``--global-option`` is now reserved for flags like
``--verbose`` or ``--quiet``).

Both ``--build-option`` and ``--global-option`` are supported as a **transitional** effort (a.k.a. "escape hatch").
In the future a proper list of allowed ``config_settings`` may be created.

Breaking Changes
----------------
* 3265: Added implementation for *editable install* hooks (PEP 660).

By default the users will experience a *lenient* behavior which prioritises
the ability of the users of changing the distributed packages (e.g. adding new
files or removing old ones).
But they can also opt into a *strict* mode, which will try to replicate as much
as possible the behavior of the package as if it would be normally installed by
end users. The *strict* editable installation is not able to detect if files
are added or removed from the project (a new installation is required).

This implementation might also affect plugins and customizations that assume
certain ``build`` subcommands don't run during editable installs or that they
always copy files to the temporary build directory.

.. important::
The *editable* aspect of the *editable install* supported this implementation
is restricted to the Python modules contained in the distributed package.
Changes in binary extensions (e.g. C/C++), entry-point definitions,
dependencies, metadata, datafiles, etc may require a new installation.

Changes
-------
* 3380: Improved the handling of the ``config_settings`` parameter in both PEP 517 and
PEP 660 interfaces:

- It is possible now to pass both ``--global-option`` and ``--build-option``.
As discussed in 1928, arbitrary arguments passed via ``--global-option``
should be placed before the name of the setuptools' internal command, while
``--build-option`` should come after.

- Users can pass ``editable-mode=strict`` to select a strict behaviour for the
editable installation.
* 3392: Exposed ``get_output_mapping()`` from ``build_py`` and ``build_ext``
subcommands. This interface is reserved for the use of ``setuptools``
Extensions and third part packages are explicitly disallowed to calling it.
However, any implementation overwriting ``build_py`` or ``build_ext`` are
required to honour this interface.
* 3412: Added ability of collecting source files from custom build sub-commands to
``sdist``. This allows plugins and customization scripts to automatically
add required source files in the source distribution.
* 3414: Users can *temporarily* specify an environment variable
``SETUPTOOLS_ENABLE_FEATURES=legacy-editable`` as a escape hatch for the
:pep:`660` behavior. This setting is **transitional** and may be removed in the
future.
* 3484: Added *transient* ``compat`` mode to editable installs.
This more will be temporarily available (to facilitate the transition period)
for those that want to emulate the behavior of the ``develop`` command
(in terms of what is added to ``sys.path``).
This mode is provided "as is", with limited support, and will be removed in
future versions of ``setuptools``.

Documentation changes
---------------------
* 3414: Updated :doc:`Development Mode </userguide/development_mode>` to reflect on the
implementation of :pep:`660`.