/usr/share/doc/python-openstackclient-doc/html/_sources/command-wrappers.txt is in python-openstackclient-doc 2.3.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | ======================
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)
|