openstacksdk/openstack/warnings.py
Stephen Finucane 54b257220f Use custom warnings, not logging.warning
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>
2023-03-27 14:43:27 +01:00

32 lines
1.1 KiB
Python

# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
class OpenStackDeprecationWarning(DeprecationWarning):
"""Base class for warnings about deprecated features in openstacksdk."""
class RemovedResourceWarning(OpenStackDeprecationWarning):
"""Indicates that a resource has been removed in newer API versions and
should not be used.
"""
class RemovedFieldWarning(OpenStackDeprecationWarning):
"""Indicates that a field has been removed in newer API versions and should
not be used.
"""
class LegacyAPIWarning(OpenStackDeprecationWarning):
"""Indicates an API that is in 'legacy' status, a long term deprecation."""