54b257220f
We were using logging.warning() to warn the user about fields that had
been removed in recent API versions or behavior that was now considered
deprecated in SDK. This was the wrong API to use. We shouldn't have been
logging, we have been using 'warnings'. From the Python docs [1]:
Task you want to perform: Issue a warning regarding a particular
runtime event
warnings.warn() in library code if the issue is avoidable and the
client application should be modified to eliminate the warning
logging.warning() if there is nothing the client application can do
about the situation, but the event should still be noted
Based on this, introduce a new module, 'openstack.warnings', containing
a number of custom 'DeprecationWarning' subclasses. 'DeprecationWarning'
isn't show by default in most cases [2] but users can opt-in to showing
them and do so selectively. For example, they may wish to ignore
warnings about fields that have been removed in recent API versions
while raising errors if they are relying on deprecated SDK behavior.
[1] https://docs.python.org/3/howto/logging.html#when-to-use-logging
[2] https://docs.python.org/3/library/exceptions.html#DeprecationWarning
Change-Id: I3846e8fcffdb5de2afe64365952d90b5ecb0f74a
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
19 lines
734 B
ReStructuredText
19 lines
734 B
ReStructuredText
Warnings
|
|
========
|
|
|
|
openstacksdk uses the `warnings`__ infrastructure to warn users about
|
|
deprecated resources and resource fields, as well as deprecated behavior in
|
|
openstacksdk itself. Currently, these warnings are all derived from
|
|
``DeprecationWarning``. In Python, deprecation warnings are silenced by
|
|
default. You must turn them on using the ``-Wa`` Python command line option or
|
|
the ``PYTHONWARNINGS`` environment variable. If you are writing an application
|
|
that uses openstacksdk, you may wish to enable some of these warnings during
|
|
test runs to ensure you migrate away from deprecated behavior.
|
|
|
|
Available warnings
|
|
------------------
|
|
|
|
.. automodule:: openstack.warnings
|
|
|
|
.. __: https://docs.python.org/3/library/warnings.html
|