# Plugin class reference

The plugin system in nose2 is based on the plugin system in unittest2’s `plugins` branch.

## Plugin base class

class nose2.events.Plugin(*args, **kwargs)

  Base class for nose2 plugins

  All nose2 plugins must subclass this class.

  session

    The `nose2.session.Session` under which the plugin has been loaded.

  config

    The `nose2.config.Config` representing the plugin’s config section as loaded from the session’s config files.

  commandLineSwitch

    A tuple of (short opt, long opt, help text) that defines a command line flag that activates this plugin. The short opt may be `None`. If defined, it must be a single upper-case character. Both short and long opt must not start with dashes.

    Example:

        commandLineSwitch = ('B', 'buffer-output', 'Buffer output during
        tests')

  configSection

    The name config file section to load into this plugin’s config.

  alwaysOn

    If this plugin should automatically register itself, set alwaysOn to `True`. Default is `False`.

  Note

  Plugins that use config values from config files and want to use the nose2 sphinx extension to automatically generate documentation must extract all config values from `self.config` in `__init__`. Otherwise the extension will not be able to detect the config keys that the plugin uses.

  addArgument(callback, short_opt, long_opt, help_text=None)

    Add command-line option that takes one argument.

    Parameters:

      - callback – Callback function to run when flag is seen. The callback will receive one argument.

      - short_opt – Short option. Must be uppercase, no dashes.

      - long_opt – Long option. Must not start with dashes

      - help_text – Help text for users so they know what this flag does.

  addFlag(callback, short_opt, long_opt, help_text=None)

    Add command-line flag that takes no arguments

    Parameters:

      - callback – Callback function to run when flag is seen. The callback will receive one empty argument.

      - short_opt – Short option. Must be uppercase, no dashes.

      - long_opt – Long option. Must not start with dashes

      - help_text – Help text for users so they know what this flag does.

  addMethods(*methods)

    Add new plugin methods to hooks registry

    Any plugins that are already registered and implement a method added here will be registered for that method as well.

  addOption(callback, short_opt, long_opt, help_text=None, nargs=0)

    Add command-line option.

    Parameters:

      - callback – Callback function to run when flag is seen. The callback will receive one argument. The “callback” may also be a list, in which case values submitted on the command line will be appended to the list.

      - short_opt – Short option. Must be uppercase, no dashes.

      - long_opt – Long option. Must not start with dashes

      - help_text – Help text for users so they know what this flag does.

      - nargs – Number of arguments to consume from command line.

  register()

    Register with appropriate hooks.

    This activates the plugin and enables it to receive events.

## Plugin interface classes

class nose2.events.PluginInterface

  Definition of plugin interface.

  Instances of this class contain the methods that may be called, and a dictionary of `nose2.events.Hook` instances bound to each method.

  In a plugin, PluginInterface instance is typically available as self.session.hooks, and plugin hooks may be called on it directly:

      event = events.LoadFromModuleEvent(module=the_module)
      self.session.hooks.loadTestsFromModule(event)

  preRegistrationMethods

    Tuple of methods that are called before registration.

  methods

    Tuple of available plugin hook methods.

  hookClass

    Class to instantiate for each hook. Default: `nose2.events.Hook`.

  addMethod(method)

    Add a method to the available method.

    This allows plugins to register for this method.

    Parameters:

      method – A method name

  hookClass

    alias of `Hook`

  register(method, plugin)

    Register a plugin for a method.

    Parameters:

      - method – A method name

      - plugin – A plugin instance

class nose2.events.Hook(method)

  A plugin hook

  Each plugin method in the `nose2.events.PluginInterface` is represented at runtime by a Hook instance that lists the plugins that should be called by that hook.

  method

    The name of the method that this Hook represents.

  plugins

    The list of plugin instances bound to this hook.