====================== 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)