diff --git a/changelog.d/2698.change.rst b/changelog.d/2698.change.rst new file mode 100644 index 0000000000..138629a292 --- /dev/null +++ b/changelog.d/2698.change.rst @@ -0,0 +1 @@ +Exposed exception classes from ``distutils.errors`` via ``setuptools.errors``. diff --git a/changelog.d/2698.doc.1.rst b/changelog.d/2698.doc.1.rst new file mode 100644 index 0000000000..1e4dde383a --- /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 0000000000..784dbf2e7b --- /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 a5d9626097..94104fe8b3 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 `_ 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 93b59501a9..d74ca3fe08 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``), consider + handling exceptions such as ``CompileError``, ``LinkError``, ``LibError``, + among others. These exceptions are available in the ``setuptools.errors`` + module. + + Adding ``setup()`` Arguments ---------------------------- diff --git a/setuptools/errors.py b/setuptools/errors.py index 2701747f56..f4d35a630a 100644 --- a/setuptools/errors.py +++ b/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