From 4707bd91b64d9f7cbee89db3fca4aa00a453419c Mon Sep 17 00:00:00 2001 From: Joshua Harlow Date: Wed, 10 Jun 2015 20:00:49 -0700 Subject: [PATCH] Use sphinx deprecated docstring markup Along with using the `debtcollector` library we should also be marking the docstrings of deprecated functions/methods/properties with the appropriate deprecated information so that the generated docs also show what is deprecated. Change-Id: I8a1960731fd53434bf04d22cc6ff208998adb4f3 --- taskflow/conductors/backends/impl_blocking.py | 10 ++++--- taskflow/engines/base.py | 10 ++++++- taskflow/engines/helpers.py | 28 +++++++++++++++++++ taskflow/listeners/base.py | 9 ++++++ 4 files changed, 52 insertions(+), 5 deletions(-) diff --git a/taskflow/conductors/backends/impl_blocking.py b/taskflow/conductors/backends/impl_blocking.py index fb8a3c3a..895f7d31 100644 --- a/taskflow/conductors/backends/impl_blocking.py +++ b/taskflow/conductors/backends/impl_blocking.py @@ -81,10 +81,12 @@ class BlockingConductor(base.Conductor): The method returns immediately regardless of whether the conductor has been stopped. - :param timeout: This parameter is **deprecated** and is present for - backward compatibility **only**. In order to wait for - the conductor to gracefully shut down, :meth:`wait` - should be used instead. + .. deprecated:: 0.8 + + The ``timeout`` parameter is **deprecated** and is present for + backward compatibility **only**. In order to wait for the + conductor to gracefully shut down, :py:meth:`wait` should be used + instead. """ self._wait_timeout.interrupt() diff --git a/taskflow/engines/base.py b/taskflow/engines/base.py index 824d9087..f41ae583 100644 --- a/taskflow/engines/base.py +++ b/taskflow/engines/base.py @@ -57,7 +57,15 @@ class Engine(object): @moves.moved_property('atom_notifier', version="0.6", removal_version="?") def task_notifier(self): - """The task notifier.""" + """The task notifier. + + .. deprecated:: 0.6 + + The property is **deprecated** and is present for + backward compatibility **only**. In order to access this + property going forward the :py:attr:`.atom_notifier` should + be used instead. + """ return self._atom_notifier @property diff --git a/taskflow/engines/helpers.py b/taskflow/engines/helpers.py index 2646eea1..a9171e46 100644 --- a/taskflow/engines/helpers.py +++ b/taskflow/engines/helpers.py @@ -146,6 +146,13 @@ def load(flow, store=None, flow_detail=None, book=None, :py:func:`~taskflow.persistence.backends.fetch` to obtain a viable backend. + .. deprecated:: 0.6 + + The ``engine_conf`` argument is **deprecated** and is present + for backward compatibility **only**. In order to provide this + argument going forward the ``engine`` string (or URI) argument + should be used instead. + :param flow: flow to load :param store: dict -- data to put to storage to satisfy flow requirements :param flow_detail: FlowDetail that holds the state of the flow (if one is @@ -199,6 +206,13 @@ def run(flow, store=None, flow_detail=None, book=None, The arguments are interpreted as for :func:`load() `. + .. deprecated:: 0.6 + + The ``engine_conf`` argument is **deprecated** and is present + for backward compatibility **only**. In order to provide this + argument going forward the ``engine`` string (or URI) argument + should be used instead. + :returns: dictionary of all named results (see :py:meth:`~.taskflow.storage.Storage.fetch_all`) """ @@ -264,6 +278,13 @@ def load_from_factory(flow_factory, factory_args=None, factory_kwargs=None, Further arguments are interpreted as for :func:`load() `. + .. deprecated:: 0.6 + + The ``engine_conf`` argument is **deprecated** and is present + for backward compatibility **only**. In order to provide this + argument going forward the ``engine`` string (or URI) argument + should be used instead. + :returns: engine """ @@ -324,6 +345,13 @@ def load_from_detail(flow_detail, store=None, engine_conf=None, backend=None, Further arguments are interpreted as for :func:`load() `. + .. deprecated:: 0.6 + + The ``engine_conf`` argument is **deprecated** and is present + for backward compatibility **only**. In order to provide this + argument going forward the ``engine`` string (or URI) argument + should be used instead. + :returns: engine """ flow = flow_from_detail(flow_detail) diff --git a/taskflow/listeners/base.py b/taskflow/listeners/base.py index 75b0db09..a83cd79b 100644 --- a/taskflow/listeners/base.py +++ b/taskflow/listeners/base.py @@ -215,6 +215,15 @@ class LoggingBase(moves.moved_class(DumpingListener, 'LoggingBase', __name__, version="0.6", removal_version="?")): + """Legacy logging base. + + .. deprecated:: 0.6 + + This class is **deprecated** and is present for backward + compatibility **only**, its replacement + :py:class:`.DumpingListener` should be used going forward. + """ + def _dump(self, message, *args, **kwargs): self._log(message, *args, **kwargs)