Warning
THIS MODULE DOES NOT HAVE STABLE PUBLIC API
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.