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