1.. _module-pw_cli-api: 2 3============= 4API Reference 5============= 6.. pigweed-module-subpage:: 7 :name: pw_cli 8 9----------------- 10pw_cli.decorators 11----------------- 12.. automodule:: pw_cli.decorators 13 :members: 14 15------------------ 16pw_cli.file_filter 17------------------ 18.. automodule:: pw_cli.file_filter 19 :members: 20 21--------------- 22pw_cli.git_repo 23--------------- 24.. automodule:: pw_cli.git_repo 25 :members: 26 27---------- 28pw_cli.log 29---------- 30.. automodule:: pw_cli.log 31 :members: 32 33-------------- 34pw_cli.plugins 35-------------- 36:py:mod:`pw_cli.plugins` provides general purpose plugin functionality. The 37module can be used to create plugins for command line tools, interactive 38consoles, or anything else. Pigweed's ``pw`` command uses this module for its 39plugins. 40 41To use plugins, create a :py:class:`pw_cli.plugins.Registry`. The registry may 42have an optional validator function that checks plugins before they are 43registered (see :py:meth:`pw_cli.plugins.Registry.__init__`). 44 45Plugins may be registered in a few different ways. 46 47* **Direct function call.** Register plugins by calling 48 :py:meth:`pw_cli.plugins.Registry.register` or 49 :py:meth:`pw_cli.plugins.Registry.register_by_name`. 50 51 .. code-block:: python 52 53 import pw_cli 54 55 _REGISTRY = pw_cli.plugins.Registry() 56 57 _REGISTRY.register('plugin_name', my_plugin) 58 _REGISTRY.register_by_name('plugin_name', 'module_name', 'function_name') 59 60* **Decorator.** Register using the :py:meth:`pw_cli.plugins.Registry.plugin` 61 decorator. 62 63 .. code-block:: python 64 65 import pw_cli 66 67 _REGISTRY = pw_cli.plugins.Registry() 68 69 # This function is registered as the "my_plugin" plugin. 70 @_REGISTRY.plugin 71 def my_plugin(): 72 pass 73 74 # This function is registered as the "input" plugin. 75 @_REGISTRY.plugin(name='input') 76 def read_something(): 77 pass 78 79 The decorator may be aliased to give a cleaner syntax (e.g. ``register = 80 my_registry.plugin``). 81 82* **Plugins files.** Plugins files use a simple format: 83 84 .. code-block:: 85 86 # Comments start with "#". Blank lines are ignored. 87 name_of_the_plugin module.name module_member 88 89 another_plugin some_module some_function 90 91 These files are placed in the file system and apply similarly to Git's 92 ``.gitignore`` files. From Python, these files are registered using 93 :py:meth:`pw_cli.plugins.Registry.register_file` and 94 :py:meth:`pw_cli.plugins.Registry.register_directory`. 95 96.. automodule:: pw_cli.plugins 97 :members: 98 99------------- 100pw_cli.plural 101------------- 102.. automodule:: pw_cli.plural 103 :members: 104 105---------------------- 106pw_cli.status_reporter 107---------------------- 108.. automodule:: pw_cli.status_reporter 109 :members: 110 111------------------ 112pw_cli.tool_runner 113------------------ 114.. automodule:: pw_cli.tool_runner 115 :members: 116 :exclude-members: ToolRunner 117 118 .. autoclass:: pw_cli.tool_runner.ToolRunner 119 :special-members: +__call__ 120 :private-members: +_run_tool, _custom_args 121