Differential D403 Diff 1087 docs/dev/plugins.rst

Changeset View

Standalone View

docs/dev/plugins.rst

This file was added.


				.. _plugins:

				####################
				Writing scap plugins
				####################

				As of version 3.3.0, scap supports a rudimentary plugin API to allow users to
				build their own command line interfaces utilizing scap's argument parser and
				rich set of utility methods.

				Features
				--------

				Scap provides a robust command line tool with infrastructure for easily defining
				and validating arguments. In addition to validation, scap will handle generating
				`--help` documentation for your commands and comprehensive bash autocompletion
				of complex argument values.

				How it works
				------------

				#. At runtime, scap calls :func:`scap.plugins.find_plugins` which scans for any
				`*.py` files in a couple of standard locations:

				* the current project :file:`./scap/plugins/{*}.py`
				* the current user's home directory :file:`~/.scap/plugins/{*}.py`

				#. Any matching files are loaded by :func:`scap.plugins.load_plugins` and
				the code evaluated in the context of the scap.plugins package namespace.
				#. Finally, any classes within a plugin module which inherit from
				:class:`scap.cli.Application` are registered as scap subcommands
				(see :func:`scap.cli.subcommand`).

				So, for example, if you have a file named `scap/plugins/hello.py` relative
				to either the current working directory or your user's home directory, then
				scap will evaluate hello.py as a module named :mod:`scap.plugins.hello`.
				Now if you want it to actually work, then hopefully you have included a
				class inside hello.py, defined similarly to the following example.

				Subcommand Example::

				from scap import cli

				@cli.command('hello', subcommands=True,
				help='prints "hello world" and exits',)
				class HelloCommand(cli.Application):
				@cli.subcommand('world')
				def world_subcommand(extra_args):
				print('hello world')

				.. seealso::
				* The core command-line application infrastructure is in :mod:`scap.cli`
				* Many of the built-in subcommands are defined in :mod:`scap.main`
				* :class:`scap.plugins.Say`