plainbox.impl – implementation package



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

Decorator for marking functions as deprecated

  • 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.

Due to the way python warning module works, to see deprecated function notices re-run your application with PYTHONWARNINGS=once

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