api.rst
58 lines
| 1.2 KiB
| text/x-rst
|
RstLexer
CONTRIBUTING TO API
Naming conventions
We keep the calls in the form {verb}_{noun}.
Change and Deprecation
API deprecation is documented in the section deprecated together with other notes about deprecated parts of the application.
Deprecated API calls
Use deprecated inside of the call docstring to make our users aware of the deprecation:
.. deprecated:: 1.2.3 Use `new_call_name` instead to fetch this information.
Make sure to log on level logging.WARNING a message that the API call or specific parameters are deprecated.
If possible return deprecation information inside of the result from the API call. Use the attribute _warning_ to contain a message.
Changed API calls
If the change is significant, consider to use versionchanged in the docstring:
.. versionchanged:: 1.2.3 Optional explanation if reasonable.
Added API calls
Use versionadded to document since which version this API call is available:
.. versionadded:: 1.2.3 Optional explanation if reasonable.