From 95e94f768a49e4fa7317e86c288450efd3aa922c Mon Sep 17 00:00:00 2001 From: Joshua Harlow Date: Thu, 27 Nov 2014 21:56:07 -0800 Subject: [PATCH] Include documentation of the utility modules Add a documentation section that uses the automodule sphinx documentation generator to build a utility page that shows people what the utility modules taskflow uses for *internal* usage are and include a warning to try to avoid end-users from using these modules (better to warn than not warn). This also adds on docstrings to various functions that were missing it so that they appear correctly in the generated documentation. Change-Id: Ibd5695927601614f31793ea5450887694f4320ae --- doc/source/index.rst | 11 +++----- doc/source/utils.rst | 49 +++++++++++++++++++++++++++++++++++ taskflow/utils/deprecation.py | 9 ++++--- taskflow/utils/kazoo_utils.py | 8 ++++-- taskflow/utils/misc.py | 26 +++++++++++++++---- 5 files changed, 86 insertions(+), 17 deletions(-) create mode 100644 doc/source/utils.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index d3820470..657a08be 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -70,13 +70,9 @@ TaskFlow into your project: ``[TaskFlow]`` to your emails subject to get an even faster response). * Follow (or at least attempt to follow) some of the established `best practices`_ (feel free to add your own suggested best practices). - -.. warning:: - - External usage of internal helpers and other internal utility functions - and modules should be kept to a *minimum* as these may be altered, - refactored or moved *without* notice. If you are unsure whether to use - a function, class, or module, please ask (see above). +* Keep in touch with the team (see above); we are all friendly and enjoy + knowing your use cases and learning how we can help make your lives easier + by adding or adjusting functionality in this library. .. _IRC: irc://chat.freenode.net/openstack-state-management .. _best practices: http://wiki.openstack.org/wiki/TaskFlow/Best_practices @@ -92,6 +88,7 @@ Miscellaneous exceptions states types + utils Indices and tables ================== diff --git a/doc/source/utils.rst b/doc/source/utils.rst new file mode 100644 index 00000000..968c2c04 --- /dev/null +++ b/doc/source/utils.rst @@ -0,0 +1,49 @@ +--------- +Utilities +--------- + +.. warning:: + + External usage of internal utility functions and modules should be kept + to a **minimum** as they may be altered, refactored or moved to other + locations **without** notice (and without the typical deprecation cycle). + +Async +~~~~~ + +.. automodule:: taskflow.utils.async_utils + +Deprecation +~~~~~~~~~~~ + +.. automodule:: taskflow.utils.deprecation + +Kazoo +~~~~~ + +.. automodule:: taskflow.utils.kazoo_utils + +Locks +~~~~~ + +.. automodule:: taskflow.utils.lock_utils + +Miscellaneous +~~~~~~~~~~~~~ + +.. automodule:: taskflow.utils.misc + +Persistence +~~~~~~~~~~~ + +.. automodule:: taskflow.utils.persistence_utils + +Reflection +~~~~~~~~~~ + +.. automodule:: taskflow.utils.reflection + +Threading +~~~~~~~~~ + +.. automodule:: taskflow.utils.threading_utils diff --git a/taskflow/utils/deprecation.py b/taskflow/utils/deprecation.py index a5c7148f..db9c3790 100644 --- a/taskflow/utils/deprecation.py +++ b/taskflow/utils/deprecation.py @@ -14,7 +14,6 @@ # License for the specific language governing permissions and limitations # under the License. -import functools import warnings import six @@ -193,8 +192,12 @@ def _moved_decorator(kind, new_attribute_name, message=None, return decorator -"""Decorates a *instance* property that was moved to another location.""" -moved_property = functools.partial(_moved_decorator, 'Property') +def moved_property(new_attribute_name, message=None, + version=None, removal_version=None): + """Decorates a *instance* property that was moved to another location.""" + + return _moved_decorator('Property', new_attribute_name, message=message, + version=version, removal_version=removal_version) def moved_class(new_class, old_class_name, old_module_name, message=None, diff --git a/taskflow/utils/kazoo_utils.py b/taskflow/utils/kazoo_utils.py index 93da2cdd..0a9922bb 100644 --- a/taskflow/utils/kazoo_utils.py +++ b/taskflow/utils/kazoo_utils.py @@ -95,8 +95,12 @@ class KazooTransactionException(k_exc.KazooException): def checked_commit(txn): - # Until https://github.com/python-zk/kazoo/pull/224 is fixed we have - # to workaround the transaction failing silently. + """Commits a kazoo transcation and validates the result. + + NOTE(harlowja): Until https://github.com/python-zk/kazoo/pull/224 is fixed + or a similar pull request is merged we have to workaround the transaction + failing silently. + """ if not txn.operations: return [] results = txn.commit() diff --git a/taskflow/utils/misc.py b/taskflow/utils/misc.py index b4357cf4..583cdd1a 100644 --- a/taskflow/utils/misc.py +++ b/taskflow/utils/misc.py @@ -342,11 +342,27 @@ def capture_failure(): For example:: - except Exception: - with capture_failure() as fail: - LOG.warn("Activating cleanup") - cleanup() - save_failure(fail) + >>> from taskflow.utils import misc + >>> + >>> def cleanup(): + ... pass + ... + >>> + >>> def save_failure(f): + ... print("Saving %s" % f) + ... + >>> + >>> try: + ... raise IOError("Broken") + ... except Exception: + ... with misc.capture_failure() as fail: + ... print("Activating cleanup") + ... cleanup() + ... save_failure(fail) + ... + Activating cleanup + Saving Failure: IOError: Broken + """ exc_info = sys.exc_info() if not any(exc_info):