From f5806d06e0c453c189c99a1dce5ef98208c4d8cf Mon Sep 17 00:00:00 2001 From: kotfu Date: Sat, 22 Feb 2020 12:22:35 -0700 Subject: Revisions and improvements for hooks and plugins --- docs/features/plugins.rst | 56 +++++++++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 29 deletions(-) (limited to 'docs/features/plugins.rst') diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst index d6e3eb9c..ecd3a32d 100644 --- a/docs/features/plugins.rst +++ b/docs/features/plugins.rst @@ -5,18 +5,15 @@ Plugins a ``cmd2`` plugin which can extend basic ``cmd2`` functionality and can be used by multiple applications. -Adding functionality --------------------- - There are many ways to add functionality to ``cmd2`` using a plugin. Most plugins will be implemented as a mixin. A mixin is a class that encapsulates and injects code into another class. Developers who use a plugin in their -``cmd2`` project, will inject the plugin's code into their subclass of -``cmd2.Cmd``. +``cmd2`` project will inject the plugin's code into their subclass of +:class:`cmd2.Cmd`. Mixin and Initialization -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ The following short example shows how to mix in a plugin and how the plugin gets initialized. @@ -29,7 +26,6 @@ Here's the plugin:: super().__init__(*args, **kwargs) # code placed here runs after cmd2.Cmd initializes - and an example app which uses the plugin:: import cmd2 @@ -44,23 +40,24 @@ and an example app which uses the plugin:: # code placed here runs after cmd2.Cmd and # all plugins have initialized -Note how the plugin must be inherited (or mixed in) before ``cmd2.Cmd``. +Note how the plugin must be inherited (or mixed in) before :class:`cmd2.Cmd`. This is required for two reasons: -- The ``cmd.Cmd.__init__()`` method in the python standard library does not +- The ``cmd.Cmd.__init__`` method in the python standard library does not call ``super().__init__()``. Because of this oversight, if you don't inherit from ``MyPlugin`` first, the ``MyPlugin.__init__()`` method will never be called. -- You may want your plugin to be able to override methods from ``cmd2.Cmd``. - If you mixin the plugin after ``cmd2.Cmd``, the python method resolution - order will call ``cmd2.Cmd`` methods before it calls those in your plugin. +- You may want your plugin to be able to override methods from + :class:`cmd2.Cmd`. If you mixin the plugin after ``cmd2.Cmd``, the python + method resolution order will call :class:`cmd2.Cmd` methods before it calls + those in your plugin. Add commands -~~~~~~~~~~~~ +------------ Your plugin can add user visible commands. You do it the same way in a plugin -that you would in a ``cmd2.Cmd`` app:: +that you would in a :class:`cmd2.Cmd` app:: class MyPlugin: def do_say(self, statement): @@ -68,12 +65,12 @@ that you would in a ``cmd2.Cmd`` app:: self.poutput(statement) You have all the same capabilities within the plugin that you do inside a -``cmd2.Cmd`` app, including argument parsing via decorators and custom help -methods. +:class:`cmd2.Cmd` app, including argument parsing via decorators and custom +help methods. Add (or hide) settings -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- A plugin may add user controllable settings to the application. Here's an example:: @@ -86,33 +83,34 @@ example:: self.mysetting = 'somevalue' self.add_settable(cmd2.Settable('mysetting', str, 'short help message for mysetting')) -You can also hide settings from the user by removing them from -``self.settables``. +You can hide settings from the user by calling +:meth:`~cmd2.Cmd.remove_settable`. See :ref:`features/settings:Settings` for +more information. Decorators -~~~~~~~~~~ +---------- Your plugin can provide a decorator which users of your plugin can use to wrap functionality around their own commands. Override methods -~~~~~~~~~~~~~~~~ +---------------- -Your plugin can override core ``cmd2.Cmd`` methods, changing their behavior. -This approach should be used sparingly, because it is very brittle. If a -developer chooses to use multiple plugins in their application, and several -of the plugins override the same method, only the first plugin to be mixed in -will have the overridden method called. +Your plugin can override core :class:`cmd2.Cmd` methods, changing their +behavior. This approach should be used sparingly, because it is very brittle. +If a developer chooses to use multiple plugins in their application, and +several of the plugins override the same method, only the first plugin to be +mixed in will have the overridden method called. Hooks are a much better approach. Hooks -~~~~~ +----- -Plugins can register hook methods, which are called by :class:`~cmd2.Cmd` +Plugins can register hook methods, which are called by :class:`cmd2.Cmd` during various points in the application and command processing lifecycle. Plugins should not override any of the deprecated hook methods, instead they should register their hooks as described in the :ref:`features/hooks:Hooks` @@ -147,7 +145,7 @@ ways hooks can influence the lifecycle. Classes and Functions -~~~~~~~~~~~~~~~~~~~~~ +--------------------- Your plugin can also provide classes and functions which can be used by developers of ``cmd2`` based applications. Describe these classes and -- cgit v1.2.1