diff options
| -rw-r--r-- | changelog.d/2698.change.rst | 1 | ||||
| -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 | ||||
| -rw-r--r-- | setuptools/errors.py | 24 |
6 files changed, 46 insertions, 0 deletions
diff --git a/changelog.d/2698.change.rst b/changelog.d/2698.change.rst new file mode 100644 index 00000000..138629a2 --- /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 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..d74ca3fe 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 2701747f..f4d35a63 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 |