5e46176540
This is a follow-up to I6c750730963615895f5d9953487d2d5a905885a8 that removed a command deprecation warning wrapper. This documents the technique for later use. Change-Id: Ieaa1e6b7eed4e5b037b4bfb6cf488e1290fc69f7
53 lines
2.0 KiB
ReStructuredText
53 lines
2.0 KiB
ReStructuredText
======================
|
|
Command Class Wrappers
|
|
======================
|
|
|
|
When we want to deprecate a command, policy says we need to alert the user.
|
|
We do this with a message logged at WARNING level before any command output
|
|
is emitted.
|
|
|
|
OpenStackClient command classes are derived from the ``cliff`` classes.
|
|
Cliff uses ``setuptools`` entry points for dispatching the parsed command
|
|
to the respective handler classes. This lends itself to modifying the
|
|
command execution at run-time.
|
|
|
|
The obvious approach to adding the deprecation message would be to just add
|
|
the message to the command class ``take_action()`` method directly. But then
|
|
the various deprecations are scattered throughout the code base. If we
|
|
instead wrap the deprecated command class with a new class we can put all of
|
|
the wrappers into a separate, dedicated module. This also lets us leave the
|
|
original class unmodified and puts all of the deprecation bits in one place.
|
|
|
|
This is an example of a minimal wrapper around a command class that logs a
|
|
deprecation message as a warning to the user then calls the original class.
|
|
|
|
* Subclass the deprecated command.
|
|
|
|
* Set class attribute ``deprecated`` to ``True`` to signal cliff to not
|
|
emit help text for this command.
|
|
|
|
* Log the deprecation message at WARNING level and refer to the replacement
|
|
for the deprecated command in the log warning message.
|
|
|
|
* Change the entry point class in ``setup.cfg`` to point to the new class.
|
|
|
|
Example Deprecation Class
|
|
-------------------------
|
|
|
|
.. code-block: python
|
|
|
|
class ListFooOld(ListFoo):
|
|
"""List resources"""
|
|
|
|
# This notifies cliff to not display the help for this command
|
|
deprecated = True
|
|
|
|
log = logging.getLogger('deprecated')
|
|
|
|
def take_action(self, parsed_args):
|
|
self.log.warning(
|
|
"%s is deprecated, use 'foobar list'",
|
|
getattr(self, 'cmd_name', 'this command'),
|
|
)
|
|
return super(ListFooOld, self).take_action(parsed_args)
|