Merge "Use custom warnings, not logging.warning"

doc/source/user/index.rst

@@ -162,6 +162,7 @@ can be customized.
    resource
    service_description
    utils
+   warnings
 
 Presentations
 -------------

doc/source/user/warnings.rst

@@ -0,0 +1,18 @@
+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

openstack/resource.py

@@ -48,6 +48,7 @@ from openstack import _log
 from openstack import exceptions
 from openstack import format
 from openstack import utils
+from openstack import warnings as os_warnings
 
 _SEEN_FORMAT = '{name}_seen'
 
@@ -196,29 +197,27 @@ class _BaseComponent:
             return None
 
         # This warning are pretty intruisive. Every time attribute is accessed
-        # a warning is being thrown. In Neutron clients we have way too many
-        # places that still refer to tenant_id even they may also properly
-        # support project_id. For now we can silence tenant_id warnings and do
-        # this here rather then addining support for something similar to
-        # "suppress_deprecation_warning".
+        # a warning is being thrown. In neutron clients we have way too many
+        # places that still refer to tenant_id even though they may also
+        # properly support project_id. For now we silence tenant_id warnings.
         if self.name != "tenant_id":
             self.warn_if_deprecated_property(value)
         return _convert_type(value, self.type, self.list_type)
 
     def warn_if_deprecated_property(self, value):
         deprecated = object.__getattribute__(self, 'deprecated')
-        deprecate_reason = object.__getattribute__(self, 'deprecation_reason')
+        deprecation_reason = object.__getattribute__(
+            self, 'deprecation_reason',
+        )
 
-        if value and deprecated and not self.already_warned_deprecation:
-            self.already_warned_deprecation = True
-            if not deprecate_reason:
-                LOG.warning(
-                    "The option [%s] has been deprecated. "
-                    "Please avoid using it.",
+        if value and deprecated:
+            warnings.warn(
+                "The field %r has been deprecated. %s" % (
                     self.name,
-                )
-            else:
-                LOG.warning(deprecate_reason)
+                    deprecation_reason or "Avoid usage."
+                ),
+                os_warnings.RemovedFieldWarning,
+            )
         return value
 
     def __set__(self, instance, value):
@@ -676,10 +675,10 @@ class Resource(dict):
             for attr, component in self._attributes_iterator(tuple([Body])):
                 if component.name == name:
                     warnings.warn(
-                        'Access to "%s[%s]" is deprecated. '
-                        'Please access using "%s.%s" attribute.'
+                        "Access to '%s[%s]' is deprecated. "
+                        "Use '%s.%s' attribute instead"
                         % (self.__class__, name, self.__class__, attr),
-                        DeprecationWarning,
+                        os_warnings.LegacyAPIWarning,
                     )
                     return getattr(self, attr)
             if self._allow_unknown_attrs_in_body:

openstack/warnings.py

@@ -0,0 +1,31 @@
+# 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."""

releasenotes/notes/switch-to-warnings-333955d19afc99ca.yaml

@@ -0,0 +1,7 @@
+---
+upgrade:
+  - |
+    Warnings about deprecated behavior or deprecated/modified APIs are now
+    raised using the ``warnings`` module, rather than the ``logging`` module.
+    This allows users to filter these warnings or silence them entirely if
+    necessary.