From 974dbb03769a500c5077d37291817f30359a0d7b Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 5 Nov 2021 18:44:15 +0000 Subject: [PATCH 1/3] Expose distutils errors As mentioned in #2698, exposing distutil errors via setuptools help the migration stated by PEP 632. --- changelog.d/2698.change.rst | 1 + setuptools/errors.py | 24 ++++++++++++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 changelog.d/2698.change.rst 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/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 From eca0111c29721056e8af7ac0d08d5f678fe7473e Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 5 Nov 2021 19:03:05 +0000 Subject: [PATCH 2/3] Document setuptools replacements --- changelog.d/2698.doc.1.rst | 2 ++ changelog.d/2698.doc.2.rst | 2 ++ docs/deprecated/distutils-legacy.rst | 9 +++++++++ docs/userguide/extension.rst | 8 ++++++++ 4 files changed, 21 insertions(+) create mode 100644 changelog.d/2698.doc.1.rst create mode 100644 changelog.d/2698.doc.2.rst 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..966c6fde9b 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 ---------------------------- From 172ea3681ce1f2b7da1044c5215cb8058b866324 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 7 Nov 2021 04:51:19 -0500 Subject: [PATCH 3/3] Prefer imperative voice. --- docs/userguide/extension.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/userguide/extension.rst b/docs/userguide/extension.rst index 966c6fde9b..d74ca3fe08 100644 --- a/docs/userguide/extension.rst +++ b/docs/userguide/extension.rst @@ -47,8 +47,8 @@ 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``, + 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.