From 52805ce26daf4c330febd5b857c82c6db095a7a9 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Thu, 26 Mar 2015 16:50:30 +0100 Subject: [PATCH 1/4] documented deprecated functionality w.r.t. error reporting --- docs/Changelog.rst | 3 +++ docs/Deprecated-functionality.rst | 36 +++++++++++++++++++++++++++++-- docs/conf.py | 2 +- 3 files changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/Changelog.rst b/docs/Changelog.rst index 5a3d5429..7ffac9e2 100644 --- a/docs/Changelog.rst +++ b/docs/Changelog.rst @@ -3,6 +3,9 @@ Changelog for EasyBuild documentation ------------------------------------- +* **release 20150326.01** (`Mar 26th 2015`): + + * documented deprecated functionality w.r.t. error reporting (see :ref:`depr_error_reporting`) * **release 20150316.01** (`Mar 16th 2015`): * include list of EasyBuild repositories cloned by ``install-EasyBuild-develop.sh`` script diff --git a/docs/Deprecated-functionality.rst b/docs/Deprecated-functionality.rst index 071d40c6..c4da0432 100644 --- a/docs/Deprecated-functionality.rst +++ b/docs/Deprecated-functionality.rst @@ -34,11 +34,43 @@ For authors of easyconfig files: For developers of easyblocks: -*(nothing yet)* +* ref:`depr_error_reporting` For EasyBuild framework developers: -*(nothing yet)* +* ref:`depr_error_reporting` + +.. _depr_error_reporting: + +Report errors by raising ``EasyBuildError`` rather than using ``error()``/``exception()`` log methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Use of the** ``error`` **and** ``exception`` **log methods is deprecated.** + +* *deprecated since:* EasyBuild v2.1.0 (April'15) +* *removed in:* EasyBuild v3.0 +* *alternative(s)*: **use** ``raise EasyBuildError(...)`` **instead** + +The `error() `_ and +`exception() `_ log methods defined by +EasyBuild (in the ``easybuild.tools.build_log`` module) do not ahder to the semantics of the standard Python log +methods, in the sense that they also raise an exception next to logging messages. + +This causes problems when 3rd party libraries are being used together with EasyBuild, since they may be using these +log methods without expecting an exception being raised. + +The custom definitions for the ``error()`` and ``exception()`` log methods will be removed in EasyBuild v3.0, +so they should no longer be used. Note that this applies both to the EasyBuild framework and to (custom) easyblocks. + +To report errors, an ``EasyBuildError`` should be raised instead:: + + from easybuild.tools.build_log import EasyBuildError + ... + def configure_step(self): + """Example configure step implementation where things may go wrong.""" + ... + if errors: + raise EasyBuildError("One or more errors were detected: %s", errors) .. _deprecation_policy: diff --git a/docs/conf.py b/docs/conf.py index d6adf8b9..91ae3d4b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,7 +43,7 @@ # The short X.Y version. version = '2.0.0' # this is meant to reference the version of EasyBuild # The full version, including alpha/beta/rc tags. -release = '20150316.01' # this is meant to reference the version of the documentation itself +release = '20150326.01' # this is meant to reference the version of the documentation itself # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: From 67b70d075bd8daae2a6b8178bf5350a7c8e531ce Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 27 Mar 2015 09:00:33 +0100 Subject: [PATCH 2/4] reword section on deprecating log.error --- docs/Deprecated-functionality.rst | 42 +++++++++++++++---------------- docs/conf.py | 2 +- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/Deprecated-functionality.rst b/docs/Deprecated-functionality.rst index c4da0432..5c0eb57b 100644 --- a/docs/Deprecated-functionality.rst +++ b/docs/Deprecated-functionality.rst @@ -34,43 +34,43 @@ For authors of easyconfig files: For developers of easyblocks: -* ref:`depr_error_reporting` +* :ref:`depr_error_reporting` For EasyBuild framework developers: -* ref:`depr_error_reporting` +* :ref:`depr_error_reporting` .. _depr_error_reporting: -Report errors by raising ``EasyBuildError`` rather than using ``error()``/``exception()`` log methods -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Report errors by raising ``EasyBuildError`` rather than using log methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Use of the** ``error`` **and** ``exception`` **log methods is deprecated.** +**Use of the** ``error()`` **and** ``exception()`` **log methods is deprecated.** * *deprecated since:* EasyBuild v2.1.0 (April'15) * *removed in:* EasyBuild v3.0 * *alternative(s)*: **use** ``raise EasyBuildError(...)`` **instead** -The `error() `_ and -`exception() `_ log methods defined by -EasyBuild (in the ``easybuild.tools.build_log`` module) do not ahder to the semantics of the standard Python log -methods, in the sense that they also raise an exception next to logging messages. +The ``error()`` and ``exception()`` log methods defined by EasyBuild (in the ``easybuild.tools.build_log`` module) +do not match the semantics of the `standard Python log methods +`_, in the sense that they also raise an +exception next to logging messages. -This causes problems when 3rd party libraries are being used together with EasyBuild, since they may be using these -log methods without expecting an exception being raised. +This may cause problems when 3rd party libraries (e.g., `gc3pie `_) are being +used by EasyBuild, since they may be using these log methods without expecting an exception being raised. -The custom definitions for the ``error()`` and ``exception()`` log methods will be removed in EasyBuild v3.0, -so they should no longer be used. Note that this applies both to the EasyBuild framework and to (custom) easyblocks. +The custom definitions for the ``error()`` and ``exception()`` log methods will be removed in EasyBuild v3.0. -To report errors, an ``EasyBuildError`` should be raised instead:: +Hence, these log methods should no longer be used to report errors since they will not raise an exception anymore once +their custom definitions are removed. Note that this applies both to the EasyBuild framework and to (custom) easyblocks. - from easybuild.tools.build_log import EasyBuildError - ... - def configure_step(self): - """Example configure step implementation where things may go wrong.""" - ... - if errors: - raise EasyBuildError("One or more errors were detected: %s", errors) +To report errors, an ``EasyBuildError`` should be raised instead. For example: + +.. code:: python + + # make sure config.sh script is there + if not os.path.exists(os.path.join(self.builddir, 'config.sh'): + raise EasyBuildError("config.sh script is missing in %s", self.builddir) .. _deprecation_policy: diff --git a/docs/conf.py b/docs/conf.py index 91ae3d4b..62bce78d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,7 +43,7 @@ # The short X.Y version. version = '2.0.0' # this is meant to reference the version of EasyBuild # The full version, including alpha/beta/rc tags. -release = '20150326.01' # this is meant to reference the version of the documentation itself +release = '20150327.01' # this is meant to reference the version of the documentation itself # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: From 32c8212f354a02b4800a121e0e58406247e67374 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 27 Mar 2015 09:40:50 +0100 Subject: [PATCH 3/4] fix typo and code formatting --- docs/Deprecated-functionality.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Deprecated-functionality.rst b/docs/Deprecated-functionality.rst index 5c0eb57b..458cd32d 100644 --- a/docs/Deprecated-functionality.rst +++ b/docs/Deprecated-functionality.rst @@ -66,10 +66,10 @@ their custom definitions are removed. Note that this applies both to the EasyBui To report errors, an ``EasyBuildError`` should be raised instead. For example: -.. code:: python +.. code:: # make sure config.sh script is there - if not os.path.exists(os.path.join(self.builddir, 'config.sh'): + if not os.path.exists(os.path.join(self.builddir, 'config.sh')): raise EasyBuildError("config.sh script is missing in %s", self.builddir) .. _deprecation_policy: From 54dfc6ab1835e3a502dcfcab1e47ea5cca67c325 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 27 Mar 2015 10:15:35 +0100 Subject: [PATCH 4/4] fix date in Changelog --- docs/Changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Changelog.rst b/docs/Changelog.rst index 7ffac9e2..aff4af40 100644 --- a/docs/Changelog.rst +++ b/docs/Changelog.rst @@ -3,7 +3,7 @@ Changelog for EasyBuild documentation ------------------------------------- -* **release 20150326.01** (`Mar 26th 2015`): +* **release 20150327.01** (`Mar 27th 2015`): * documented deprecated functionality w.r.t. error reporting (see :ref:`depr_error_reporting`) * **release 20150316.01** (`Mar 16th 2015`):