Manager Module

The browsepy’s Manager Module module centralizes all plugin-related logic, hook calls and component registration methods.

For an extended explanation head over Plugin Development.

Argument Plugin Manager

This class represents a subset of PluginManager functionality, and an instance of this class will be passed to register_arguments() plugin module-level functions.

class browsepy.manager.ArgumentPluginManager(app=None)[source]

Plugin manager for command-line argument registration.

This function is used by browsepy’s __main__ module in order to attach extra arguments at argument-parsing time.

This is done by load_arguments() which imports all plugin modules and calls their respective register_arguments() module-level function.

clear()[source]

Clear plugin manager state.

Registered command-line arguments will be disposed after calling this method.

extract_plugin_arguments(plugin)[source]

Given a plugin name, extracts its registered_arguments as an iterable of (args, kwargs) tuples.

Parameters:plugin (str) – plugin name
Returns:iterable if (args, kwargs) tuples.
Return type:iterable
get_argument(name, default=None)[source]

Get argument value from last load_arguments() call.

Keep in mind argparse.ArgumentParser.parse_args() generates its own command-line arguments if dest kwarg is not provided, so ie. –my-option became available as my_option.

Parameters:
  • name (str) – command-line argument name
  • default – default value if parameter is not found
Returns:

command-line argument or default value
import_plugin(plugin)

Import plugin by given name, looking at namespaces.

Parameters:plugin (str) – plugin module name
Raises:PluginNotFoundError – if not found on any namespace
init_app(app)

Initialize this Flask extension for given app.

load_arguments(argv, base=None)[source]

Process given argument list based on registered arguments and given optional base argparse.ArgumentParser instance.

This method saves processed arguments on itself, and this state won’t be lost after clean() calls.

Processed argument state will be available via get_argument() method.

Parameters:
Returns:

argparse.Namespace instance with processed arguments as given by argparse.ArgumentParser.parse_args().
Return type:

argparse.Namespace
load_plugin(plugin)

Import plugin (see import_plugin()) and load related data.

Parameters:plugin (str) – plugin module name
Raises:PluginNotFoundError – if not found on any namespace
namespaces

List of plugin namespaces taken from app config.

register_argument(*args, **kwargs)[source]

Register command-line argument.

All given arguments will be passed directly to argparse.ArgumentParser.add_argument() calls by load_arguments() method.

See argparse.ArgumentParser.add_argument() documentation for further information.

reload()

Clear plugin manager state and reload plugins.

This method will make use of clear() and load_plugin(), so all internal state will be cleared, and all plugins defined in self.app.config['plugin_modules'] will be loaded.

Plugin Manager

This class includes are the plugin registration functionality, and itself will be passed to register_plugin() plugin module-level functions.

class browsepy.manager.PluginManager(app=None)[source]

Main plugin manager

Provides:
  • Plugin module loading and Flask extension logic.
  • Plugin registration via register_plugin() functions at plugin module level.
  • Plugin blueprint registration via register_plugin() calls.
  • Widget registration via register_widget() method.
  • Mimetype function registration via register_mimetype_function() method.
  • Command-line argument registration calling register_arguments() at plugin module level and providing register_argument() method.

This class also provides a dictionary of widget types at its widget_types attribute. They can be referenced by their keys on both create_widget() and register_widget() methods’ type parameter, or instantiated directly and passed to register_widget() via widget parameter.

widget_types = {'base': <class 'browsepy.manager.Widget'>, 'link': <class 'browsepy.manager.Link'>, 'button': <class 'browsepy.manager.Button'>, 'upload': <class 'browsepy.manager.Upload'>, 'stylesheet': <class 'browsepy.manager.Stylesheet'>, 'script': <class 'browsepy.manager.Script'>, 'html': <class 'browsepy.manager.Html'>}

Dictionary with widget type names and their corresponding class (based on namedtuple, see defaultsnamedtuple()) so it could be instanced and reused (see register_widget()).

clear()[source]

Clear plugin manager state.

Registered widgets will be disposed after calling this method.

Registered mimetype functions will be disposed after calling this method.

Registered command-line arguments will be disposed after calling this method.

create_widget(place, type, file=None, **kwargs)

Create a widget object based on given arguments.

If file object is provided, callable arguments will be resolved: its return value will be used after calling them with file as first parameter.

All extra kwargs parameters will be passed to widget constructor.

Parameters:
  • place (str) – place hint where widget should be shown.
  • type (browsepy.files.Node or None) – widget type name as taken from widget_types dict keys.
  • file – optional file object for widget attribute resolving
Returns:

widget instance
Return type:

object
extract_plugin_arguments(plugin)

Given a plugin name, extracts its registered_arguments as an iterable of (args, kwargs) tuples.

Parameters:plugin (str) – plugin name
Returns:iterable if (args, kwargs) tuples.
Return type:iterable
get_argument(name, default=None)

Get argument value from last load_arguments() call.

Keep in mind argparse.ArgumentParser.parse_args() generates its own command-line arguments if dest kwarg is not provided, so ie. –my-option became available as my_option.

Parameters:
  • name (str) – command-line argument name
  • default – default value if parameter is not found
Returns:

command-line argument or default value
get_mimetype(path)

Get mimetype of given path calling all registered mime functions (and default ones).

Parameters:path (str) – filesystem path of file
Returns:mimetype
Return type:str
get_widgets(file=None, place=None)

List registered widgets, optionally matching given criteria.

Parameters:
  • file (browsepy.file.Node or None) – optional file object will be passed to widgets’ filter functions.
  • place (str) – optional template place hint.
Returns:

list of widget instances
Return type:

list of objects
import_plugin(plugin)

Import plugin by given name, looking at namespaces.

Parameters:plugin (str) – plugin module name
Raises:PluginNotFoundError – if not found on any namespace
init_app(app)

Initialize this Flask extension for given app.

iter_widgets(file=None, place=None)

Iterate registered widgets, optionally matching given criteria.

Parameters:
  • file (browsepy.file.Node or None) – optional file object will be passed to widgets’ filter functions.
  • place (str) – optional template place hint.
Yields:

widget instances
Ytype:

object
load_arguments(argv, base=None)

Process given argument list based on registered arguments and given optional base argparse.ArgumentParser instance.

This method saves processed arguments on itself, and this state won’t be lost after clean() calls.

Processed argument state will be available via get_argument() method.

Parameters:
Returns:

argparse.Namespace instance with processed arguments as given by argparse.ArgumentParser.parse_args().
Return type:

argparse.Namespace
load_plugin(plugin)

Import plugin (see import_plugin()) and load related data.

If available, plugin’s module-level register_plugin() function will be called with current plugin manager instance as first argument.

Parameters:plugin (str) – plugin module name
Raises:PluginNotFoundError – if not found on any namespace
namespaces

List of plugin namespaces taken from app config.

register_argument(*args, **kwargs)

Register command-line argument.

All given arguments will be passed directly to argparse.ArgumentParser.add_argument() calls by load_arguments() method.

See argparse.ArgumentParser.add_argument() documentation for further information.

register_blueprint(blueprint)

Register given blueprint on curren app.

This method is provided for using inside plugin’s module-level register_plugin() functions.

Parameters:blueprint (flask.Blueprint) – blueprint object with plugin endpoints
register_mimetype_function(fnc)

Register mimetype function.

Given function must accept a filesystem path as string and return a mimetype string or None.

Parameters:fnc (callable) – callable accepting a path string
register_widget(place=None, type=None, widget=None, filter=None, **kwargs)

Create (see create_widget()) or use provided widget and register it.

This method provides this dual behavior in order to simplify widget creation-registration on an functional single step without sacrifycing the reusability of a object-oriented approach.

Parameters:
  • place (str or None) – where widget should be placed. This param conflicts with widget argument.
  • type (str or None) – widget type name as taken from widget_types dict keys. This param conflicts with widget argument.
  • widget (object or None) – optional widget object will be used as is. This param conflicts with both place and type arguments.
Raises:

TypeError – if both widget and place or type are provided at the same time (they’re mutually exclusive).
Returns:

created or given widget object
Return type:

object
reload()

Clear plugin manager state and reload plugins.

This method will make use of clear() and load_plugin(), so all internal state will be cleared, and all plugins defined in self.app.config['plugin_modules'] will be loaded.

Utility functions

browsepy.manager.defaultsnamedtuple(name, fields, defaults=None)[source]

Generate namedtuple with default values.

Parameters:
  • name – name
  • fields – iterable with field names
  • defaults – iterable or mapping with field defaults
Returns:

defaultdict with given fields and given defaults
Return type:

collections.defaultdict