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().

Changed in version 3.1.0: Add a vep handler

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

__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:

TemplateNotFound – if no template file is found.
PEPError – if tep rule or content is invalid.

_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)

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,]
Raises:	PEPError – if filter rule or content is invalid.

New in version 3.2.0.

_error_handler(plugin_info, errhandler_rule)[source]¶

Error code handler.

Parameters:	errhandler_rule – like {err_code=func, }
Raises:	PEPError – if error handler rule or content is invalid.

New in version 3.2.0.

_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)[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

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>
</body>
</html>

Parameters:	plugin_name – name of the plugin, which is __plugin_name__ filename – file name in the static directory of the plugin package
Returns:	html code with `Markup`.

emit_config(conf_name)[source]¶: Get configuration information in the template context, like config.

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.

get_all_plugins¶: Get all plugins, enabled and disabled

get_enabled_beps¶

Get all bep of the enabled plugins.

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

get_enabled_errhandlers¶

Get all error handlers for the enabled plugins.

Returns:	dict, like {code: view_func,}

New in version 3.2.0.

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.

get_enabled_heps¶

Get all hep of the enabled plugins.

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

get_enabled_plugins¶: Get all enabled plugins

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.

get_enabled_teps¶

Get all tep of the enabled plugins.

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

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.

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

list¶

list all data

Returns:	dict

set(key, value)[source]¶

Set persistent data with shelve.

Parameters:	key – string: 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

list¶: list redis hash data

remove(key)[source]¶: delete key from redis

set(key, value)[source]¶: set key data

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:	PluginError – the param event or position error NotCallableError – the param callback is not callable

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

API¶

PluginManager Object¶

Inherited Application Objects¶

Storage Objects¶

Useful Functions and Classes¶

Custom Exceptions¶

flask_pluginkit.exceptions¶

Contents

Navigation