API

This part of the documentation covers all the interfaces of Flask-PluginKit.

PluginManager Object

class flask_pluginkit.PluginManager(app=None, plugins_base=None, plugins_folder='plugins', **options)[source]

Flask Plugin Manager Extension, collects all plugins and maps the metadata to the plugin.

The plugin is a directory or a locally importable module, and the plugin entry file is __init__.py, including __plugin_name__, __version__, __author__ and other metadata.

A meaningful plugin structure should look like this:

plugins/
├── plugin1
│   ├── __init__.py
│   ├── LICENCE
│   ├── README
│   ├── static
│   │   └── plugin1.css
│   └── templates
│       └── plugin1
│           └── plugin1.html
└── plugin2
    ├── __init__.py
    ├── LICENCE
    ├── README
    ├── static
    │   └── plugin2.css
    └── templates
        └── plugin2
            └── plugin2.html

Initializes the PluginManager. It is also possible to initialize the PluginManager via a factory:

from flask_pluginkit import Flask, PluginManager
app = Flask(__name__)
pm = PluginManager()
pm.init_app(app)
Parameters
  • app – flask application.

  • plugins_base – plugin folder where the plugins resides.

  • plugins_folder – base folder for the application. It is used to build the plugins package name.

  • logger – logging instance, for debug.

  • stpl – turn on template sorting when the value is True.

  • stpl_reverse – Collation, True descending, False ascending (Default).

  • plugin_packages – list of third-party plugin packages.

  • static_url_path – can be used to specify a different path for the static files on the plugins. Defaults to the name of the static_endpoint folder.

  • static_endpoint – the endpoint name of plugins static files that should be served at static_url_path. Defaults to the 'assets'

  • pluginkit_config – additional configuration can be used in the template via emit_config().

  • try_compatible – Boolean, default True, try to load the registration method of getPluginClass in 2.x and convert.

Changed in version 3.1.0: Add a vep handler

Changed in version 3.2.0: Add filter handler, error handler, template context processor

Changed in version 3.3.1: Add try_compatible, if True, it will try to load old version

Changed in version 3.4.0: Add hep named before_first_request.

Changed in version 3.4.0: The param stpl allows to be set to asc or desc, respectively, ascending, descending, which will also open the template sorting. So, the param stpl_reverse will be deprecated.

__init__(app=None, plugins_base=None, plugins_folder='plugins', **options)[source]

Receive initialization parameters and pass options to init_app() method.

init_app(app, plugins_base=None, plugins_folder='plugins')[source]
_tep_handler(plugin_info, tep_rule)[source]

Template extension point handler.

Parameters
  • plugin_info – if tep is valid, will update it.

  • tep_rule

    the tep rule, like {tep_name: your_html_file_or_code}

    1. This must be dict, where key means that tep is the extension point identifier, and each extension point can contain only one template type, either HTML or string, which requires string, and other types trigger exceptions.

    2. HTML template type suffix for html or htm as template file (the other as pure HTML code), to be real, will adopt a render_template way rendering, using template type can be specified when rendering and introduced to additional data.

Raises
_hep_handler(plugin_info, hep_rule)[source]

Hook extension point handler.

Parameters

hep_rule

like {hook: func}, the supporting hooks are as follows:

1. before_request, Before request (intercept requests are allowed)

2. after_request, After request (no exception before return)

3. teardown_request, After request (before return, with or without exception)

4. before_first_request, Before first request (Registers a function to be run before the first request to this instance of the application.)

Raises

PEPError – if hep rule or content is invalid.

_bep_handler(plugin_info, bep_rule)[source]

Blueprint extension point handler.

Parameters

bep_rule – like {blueprint=, prefix=}

Raises

PEPError – if bep rule or content is invalid.

_vep_handler(plugin_info, vep_rule)[source]

Viewfunc extension point handler.

Parameters

vep_rule – like [{rule=, view_func=, other options}, etc.]

Raises

PEPError – if bep rule or content is invalid.

New in version 3.1.0.

_filter_handler(plugin_info, filter_rule)[source]

Template filter handler.

Parameters

filter_rule – like {filter_name=func,} or [func, (name,func)]

Raises

PEPError – if filter rule or content is invalid.

New in version 3.2.0.

Changed in version 3.4.0: If filter_rule is list or tuple, allow nested tuple to set name

_error_handler(plugin_info, errhandler_rule)[source]

Error code handler.

Parameters

errhandler_rule – eg: {err_code=func} or [{error=exception_class, handler=func}, {error=err_code, handler=func}]

Raises

PEPError – if error handler rule or content is invalid.

New in version 3.2.0.

Changed in version 3.4.0: Allow registration of class-based exception handlers

_context_processor_handler(plugin_info, processor_rule)[source]

Template context processor(tcp) handler.

Parameters

processor_rule – like {var_name=var, func_name=func,}

Raises

PEPError – if tcp rule or content is invalid.

New in version 3.2.0.

_dcp_manager

the instance of DcpManager

New in version 3.2.0.

disable_plugin(plugin_name)[source]

Disable a plugin (that is, create a DISABLED empty file) and restart the application to take effect.

emit_assets(plugin_name, filename, _raw=False)[source]

Get the static file in template context. This global function, which can be used directly in the template, is used to quickly reference the static resources of the plugin.

In addition, static resources can still pass through the blueprint, but emit_assets can be used if there is no blueprint.

Of course, you can also use flask.url_for() instead.

If filename ends with .css, then this function will return the link code, like this:

<link rel="stylesheet" href="/assets/plugin/css/demo.css">

If filename ends with .js, then this function will return the script code, like this:

<script type="text/javascript" src="/assets/plugin/js/demo.js"></script>

Other types of files, only return file url path segment, like this:

/assets/plugin/img/logo.png
/assets/plugin/attachment/test.zip

However, the _raw parameter has been added in v3.4.0, and if it is True, only uri is generated.

The following is a mini example:

<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
    {{ emit_assets('demo','css/demo.css') }}
</head>
<body>
    <div class="logo">
        <img src="{{ emit_assets('demo', 'img/logo.png') }}">
    </div>
    <div class="showJsPath">
        <scan>
            {{ emit_assets('demo', 'js/demo.js', _raw=True) }}
        </scan>
    </div>
</body>
</html>
Parameters
  • plugin_name – name of the plugin, which is __plugin_name__

  • filename – filename in the static directory of the plugin package

  • _raw – if True, not to parse automatically, only generate uri. Default False.

Returns

html code with Markup.

Changed in version 3.4.0: Add _raw, only generate uri without parse

emit_config(conf_name)[source]

Get configuration information in the template context.

emit_tep(tep, typ='all', **context)[source]

Emit a tep and get the tep data(html code) with flask.render_template() or flask.render_template_string()

Please use this function in the template file or code. The emit_tep needs to be defined by yourself. It can render HTML code and files for a tep, or even pass in extra data at render time.

Suppose you have a tep named hello, only need to enable custom extension points in the template context, eg:

{{ emit_tep("hello", context="world") }}
Parameters
  • tep – Template extension point name, it is the only one. A tep parsing result is list, within which can be HTML code and files, or one of them.

  • typ

    Render type, default is all.

    all - render HTML file and code;

    fil - render HTML file only;

    cod - render HTML code only.

  • context – Keyword params, additional data passed to the template

Returns

html code with Markup.

enable_plugin(plugin_name)[source]

Enable a plugin (that is, create a ENABLED empty file) and restart the application to take effect.

property get_all_plugins

Get all plugins, enabled and disabled

property get_enabled_beps

Get all bep of the enabled plugins.

Returns

List of nested dictionaries, like [{blueprint=,prefix=},]

property get_enabled_errhandlers

Get all error handlers for the enabled plugins.

Returns

list, like [(err_code_class, func_handler), …]

New in version 3.2.0.

Changed in version 3.4.0: Return type changed from dict to list

property get_enabled_filters

Get all template filters for the enabled plugins.

Returns

List of nested tuples, like [(filter_name, filter_func),]

New in version 3.2.0.

property get_enabled_heps

Get all hep of the enabled plugins.

Returns

dictionary with nested tuples, like {hook:[]}

property get_enabled_plugins

Get all enabled plugins

property get_enabled_tcps

Get all template context processors for the enabled plugins.

Returns

List of Nested Dictionaries, like [{name:var_or_func},]

New in version 3.2.0.

property get_enabled_teps

Get all tep of the enabled plugins.

Returns

dict like {tep_1: dict(fil=[], cod=[]), tep_n…}

property get_enabled_veps

Get all vep for the enabled plugins.

Returns

List of nested tuples, like [(path, view_func),]

New in version 3.1.0.

get_plugin_info(plugin_name)[source]

Get plugin information from all plugins

logger = None

logging Logger instance

plugin_packages = None

Third-party plugin package

pluginkit_config = None

Configuration Dictionary of Flask-PLuginKit in Project

static_endpoint = None

Static endpoint

static_url_path = None

Static url prefix

stpl = None

Template sorting

stpl_reverse = None

Template sort order, True descending, False ascending (default).

flask_pluginkit.push_dcp(event, callback, position='right')[source]

Push a callable for with push().

Example usage:

push_dcp('demo', lambda:'Hello dcp')

New in version 3.2.0.

flask_pluginkit.blueprint

The Blueprint instance for managing plugins.

New in version 3.3.0.

Inherited Application Objects

class flask_pluginkit.Flask(import_name, static_url_path=None, static_folder='static', static_host=None, host_matching=False, subdomain_matching=False, template_folder='templates', instance_path=None, instance_relative_config=False, root_path=None)[source]
before_request_second(f)[source]

Registers a function to run before each request. Priority Second.

before_request_top(f)[source]

Registers a function to run before each request. Priority First.

The usage is equivalent to the flask.Flask.before_request() decorator, and before_request registers the function at the end of the before_request_funcs, while this decorator registers the function at the top of the before_request_funcs (index 0).

Because flask-pluginkit has registered all cep into the app at load time, if your web application uses before_request and plugins depend on one of them (like g), the plugin will not run properly, so your web application should use this decorator at this time.

class flask_pluginkit.JsonResponse(response=None, status=None, headers=None, mimetype=None, content_type=None, direct_passthrough=False)[source]

In response to a return type that cannot be processed. If it is a dict, return json.

New in version 3.4.0.

classmethod force_type(rv, environ=None)[source]

Enforce that the WSGI response is a response object of the current type. Werkzeug will use the BaseResponse internally in many situations like the exceptions. If you call get_response() on an exception you will get back a regular BaseResponse object, even if you are using a custom subclass.

This method can enforce a given response type, and it will also convert arbitrary WSGI callables into response objects if an environ is provided:

# convert a Werkzeug response object into an instance of the
# MyResponseClass subclass.
response = MyResponseClass.force_type(response)

# convert any WSGI application into a response object
response = MyResponseClass.force_type(response, environ)

This is especially useful if you want to post-process responses in the main dispatcher and use functionality provided by your subclass.

Keep in mind that this will modify response objects in place if possible!

Parameters
  • response – a response object or wsgi application.

  • environ – a WSGI environment object.

Returns

a response object.

Storage Objects

class flask_pluginkit.LocalStorage[source]

Local file system storage based on the shelve module.

index

The default index, as the only key, you can override it.

get(key, default=None)[source]

Get persistent data from shelve.

Returns

data

property list

list all data

Returns

dict

set(key, value)[source]

Set persistent data with shelve.

Parameters
  • key – str: Index key

  • value – All supported data types in python

Raises

Returns

class flask_pluginkit.RedisStorage(redis_url=None, redis_connection=None)[source]

Use redis stand-alone storage

index

The default index, as the only key, you can override it.

get(key, default=None)[source]

get key data from redis

property list

list redis hash data

remove(key)[source]

delete key from redis

set(key, value)[source]

set key data

class flask_pluginkit.MongoStorage(mongo_url=None, mongo_connection=None)[source]

Use mongodb stand-alone storage

New in version 3.4.0.

index

The default index, as the default database, you can override it.

property db

Return the mongo connection

Useful Functions and Classes

flask_pluginkit.utils.isValidSemver(version)[source]

Semantic version number - determines whether the version is qualified. The format is MAJOR.Minor.PATCH, more with https://semver.org

flask_pluginkit.utils.sortedSemver(versions, sort='ASC')[source]

Semantically sort the list of version Numbers

class flask_pluginkit.utils.BaseStorage[source]

This is the base class for storage. The available storage classes need to inherit from BaseStorage and override the get and set methods, it’s best to implement the remote method as well.

This base class customizes the __getitem__, __setitem__ and __delitem__ methods so that the user can call it like a dict.

index = 'flask_pluginkit_dat'

The default index, as the only key, you can override it.

class flask_pluginkit.utils.DcpManager[source]
emit(event, *args, **kwargs)[source]

Emits events for the template context.

Returns

strings with Markup

push(event, callback, position='right')[source]

Connect a dcp, push a function.

Parameters
  • event – a unique identifier name for dcp.

  • callback – corresponding to the event to perform a function.

  • position – the position of the insertion function, right(default) or left. The default right is inserted at the end of the event, and left is inserted into the event first.

Raises

New in version 3.2.0.

remove(event, callback)[source]

Remove a callback again.

class flask_pluginkit.PluginInstaller(plugin_abspath, **kwargs)[source]

plugin installer for installing a compressed local/remote plugin

addPlugin(method='remote', **kwargs)[source]

Add a plugin, support only for .tar.gz or .zip compression packages.

Parameters
  • method

    supported method:

    remote, download and unpack a remote plugin package;

    local, unzip a local plugin package.

    pip, install package with pip command.

  • url – for method is remote, plugin can be downloaded from the address.

  • filepath – for method is local, plugin local absolute path

  • remove – for method is local, remove the plugin source code package, default is False.

  • package_or_url – for method is pip, pypi’s package or VCS url.

Returns

the result of adding the plugin, like {msg:str, code:int}, code=0 is successful.

Changed in version 3.3.0: Add pip method, with package_or_url param.

removePlugin(package)[source]

Remove a local plugin

Parameters

package – The plugin package name, not __plugin_name.

Custom Exceptions

flask_pluginkit.exceptions

Exception Classes

exception flask_pluginkit.exceptions.InstallError[source]

Bases: flask_pluginkit.exceptions.PluginError

exception flask_pluginkit.exceptions.NotCallableError[source]

Bases: flask_pluginkit.exceptions.PluginError

exception flask_pluginkit.exceptions.PEPError[source]

Bases: flask_pluginkit.exceptions.PluginError

exception flask_pluginkit.exceptions.PluginError[source]

Bases: Exception

exception flask_pluginkit.exceptions.TarError[source]

Bases: flask_pluginkit.exceptions.PluginError

exception flask_pluginkit.exceptions.TemplateNotFound[source]

Bases: flask_pluginkit.exceptions.PluginError

exception flask_pluginkit.exceptions.VersionError[source]

Bases: flask_pluginkit.exceptions.PluginError

exception flask_pluginkit.exceptions.ZipError[source]

Bases: flask_pluginkit.exceptions.PluginError