Re-export errors from distutils

changelog.d/2698.change.rst

@@ -0,0 +1 @@
+Exposed exception classes from ``distutils.errors`` via ``setuptools.errors``.

changelog.d/2698.doc.1.rst

@@ -0,0 +1,2 @@
+Added mentions to ``setuptools.errors`` as a way of handling custom command
+errors.

changelog.d/2698.doc.2.rst

@@ -0,0 +1,2 @@
+Added instructions to migrate from ``distutils.commands`` and
+``distutils.errors`` in the porting guide.

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.

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
 ----------------------------
 

setuptools/errors.py

@@ -3,6 +3,7 @@
 Provides exceptions used by setuptools modules.
 """
 
+from distutils import errors as _distutils_errors
 from distutils.errors import DistutilsError
 
 
@@ -14,3 +15,26 @@ class RemovedCommandError(DistutilsError, RuntimeError):
     error is raised if a command exists in ``distutils`` but has been actively
     removed in ``setuptools``.
     """
+
+
+# Re-export errors from distutils to facilitate the migration to PEP632
+
+ByteCompileError = _distutils_errors.DistutilsByteCompileError
+CCompilerError = _distutils_errors.CCompilerError
+ClassError = _distutils_errors.DistutilsClassError
+CompileError = _distutils_errors.CompileError
+ExecError = _distutils_errors.DistutilsExecError
+FileError = _distutils_errors.DistutilsFileError
+InternalError = _distutils_errors.DistutilsInternalError
+LibError = _distutils_errors.LibError
+LinkError = _distutils_errors.LinkError
+ModuleError = _distutils_errors.DistutilsModuleError
+OptionError = _distutils_errors.DistutilsOptionError
+PlatformError = _distutils_errors.DistutilsPlatformError
+PreprocessError = _distutils_errors.PreprocessError
+SetupError = _distutils_errors.DistutilsSetupError
+TemplateError = _distutils_errors.DistutilsTemplateError
+UnknownFileError = _distutils_errors.UnknownFileError
+
+# The root error class in the hierarchy
+BaseError = _distutils_errors.DistutilsError