diff options
| -rw-r--r-- | changelog.d/2698.doc.1.rst | 2 | ||||
| -rw-r--r-- | changelog.d/2698.doc.2.rst | 2 | ||||
| -rw-r--r-- | docs/deprecated/distutils-legacy.rst | 9 | ||||
| -rw-r--r-- | docs/userguide/extension.rst | 8 |
4 files changed, 21 insertions, 0 deletions
diff --git a/changelog.d/2698.doc.1.rst b/changelog.d/2698.doc.1.rst new file mode 100644 index 00000000..1e4dde38 --- /dev/null +++ b/changelog.d/2698.doc.1.rst @@ -0,0 +1,2 @@ +Added mentions to ``setuptools.errors`` as a way of handling custom command +errors. diff --git a/changelog.d/2698.doc.2.rst b/changelog.d/2698.doc.2.rst new file mode 100644 index 00000000..784dbf2e --- /dev/null +++ b/changelog.d/2698.doc.2.rst @@ -0,0 +1,2 @@ +Added instructions to migrate from ``distutils.commands`` and +``distutils.errors`` in the porting guide. diff --git a/docs/deprecated/distutils-legacy.rst b/docs/deprecated/distutils-legacy.rst index a5d96260..94104fe8 100644 --- a/docs/deprecated/distutils-legacy.rst +++ b/docs/deprecated/distutils-legacy.rst @@ -18,8 +18,17 @@ As Distutils is deprecated, any usage of functions or objects from distutils is ``distutils.cmd.Command`` → ``setuptools.Command`` +``distutils.command.{build_clib,build_ext,build_py,sdist}`` → ``setuptools.command.*`` + ``distutils.log`` → (no replacement yet) ``distutils.version.*`` → ``packaging.version.*`` +``distutils.errors.*`` → ``setuptools.errors.*`` [#errors]_ + If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker <https://github.com/pypa/setuptools/issues/>`_ and file a request, describing the use-case so that Setuptools' maintainers can investigate. Please provide enough detail to help the maintainers understand how distutils is used, what value it provides, and why that behavior should be supported. + + +.. [#errors] Please notice errors related to the command line usage of + ``setup.py``, such as ``DistutilsArgError``, are intentionally not exposed + by setuptools, since this is considered a deprecated practice. diff --git a/docs/userguide/extension.rst b/docs/userguide/extension.rst index 93b59501..966c6fde 100644 --- a/docs/userguide/extension.rst +++ b/docs/userguide/extension.rst @@ -45,6 +45,14 @@ entry points in the active distributions on ``sys.path``. In fact, this is how setuptools' own commands are installed: the setuptools project's setup script defines entry points for them! +.. note:: + When creating commands, and specially when defining custom ways of building + compiled extensions (for example via ``build_ext``), you might want to + handle exceptions such as ``CompileError``, ``LinkError``, ``LibError``, + among others. These exceptions are available in the ``setuptools.errors`` + module. + + Adding ``setup()`` Arguments ---------------------------- |