plainbox.impl – implementation package

Warning

THIS MODULE DOES NOT HAVE STABLE PUBLIC API

plainbox.impl.deprecated(version, explanation=None)[source]

Decorator for marking functions as deprecated

Parameters:
  • version – Version in which a function is deprecated
  • explanation – Explanation of the deprecation. Ideally this will include hints on how to get a modern replacement.

Deprecated functions are candidates for removal. Existing code should be adapted not to make any calls to the deprecated functions. New code should not use such functions.

..note::
Due to the way python warning module works, to see deprecated function notices re-run your application with PYTHONWARNINGS=once
plainbox.impl.get_plainbox_dir()[source]

Return the root directory of the plainbox package.

plainbox.impl.public(import_path, introduced=None, deprecated=None)[source]

Public API decorator generator.

This decorator serves multiple uses:

  • It clearly documents all public APIs. This is visible to both developers reading the source code directly and to people reading code documentation (by adjusting __doc__)
  • It provides a stable import location while allowing to move the implementation around as the code evolves. This unbinds the name and documentation of the symbol from the code.
  • It documents when each function was introduced. This is also visible in the generated documentation.
  • It documents when each function will be decommissioned. This is visible in the generated documentation and at runtime. Each initial call to a deprecated function will cause a PendingDeprecationWarnings to be logged.

The actual implementation of the function must be in in a module specified by import_path. It can be a module name or a module name and a function name, when separated by a colon.

comments powered by Disqus