11. Plugin base functions

11.1. cookie_property

plugin_base.cookie_property()

The @cookie_property decorator is used to mark attributes that should be passed in the cookie between invocations of the same plugin. Setting up such property is an easy way to store and retrieve data in self.cookie. Similarly to @lazy_property attributes, the evaulation of a @cookie_property attribute is also delayed until usage.

Usage

To use self.foobar as a cookie property, simply define it on the Plugin class, and decorate it with @cookie_property decorator:

from safeguard.sessions.plugin import AAPlugin
from safeguard.sessions.plugin.plugin_base import cookie_property

class MyPlugin(AAPlugin):
    @cookie_property
    def foobar(self):
        return 42

    def do_authenticate(self):
        assert self.foobar == 42
        self.foobar = 0

    def do_authorize(self):
        assert self.foobar == 0

The decorator @cookie_property together with code in AAPlugin will ensure that foobar is stored and retrieved from the cookie passed to the plugin.

The initial definition of foobar is 42 in this case, but it can be any function - this function is only called if foobar was not accessed before. To be more precise foobar is initialized with its factory function if it is being accessed and it is not present in self.cookie.

11.2. session_cookie_property

plugin_base.session_cookie_property()

The @session_cookie_property decorator is used to mark attributes that should be passed in the session cookie between invocations of all plugins relevant to the session. Setting up such property is an easy way to store and retrieve data in self.session_cookie. Similarly to @lazy_property attributes, the evaulation of a @session_cookie_property attribute is also delayed until usage.

Usage

To use self.foobar as a session cookie property, simply define it on the Plugin class, and decorate it with @session_cookie_property decorator:

from safeguard.sessions.plugin import AAPlugin
from safeguard.sessions.plugin.plugin_base import session_cookie_property

class MyPlugin(AAPlugin):
    @session_cookie_property
    def foobar(self):
        return 42

    def do_authenticate(self):
        assert self.foobar == 42
        self.foobar = 0

    def do_authorize(self):
        assert self.foobar == 0

The decorator @session_cookie_property together with code in AAPlugin will ensure that foobar is stored and retrieved from the session cookie passed to the plugin.

The initial definition of foobar is 42 in this case, but it can be any function - this function is only called if foobar was not accessed before. To be more precise foobar is initialized with its factory function if it is being accessed and it is not present in self.session_cookie.

11.3. lazy_property

plugin_base.lazy_property()

The @lazy_property decorator is used to mark attributes that should only be evaluated when accessed. This is useful when the calculation of the attribute is heavy, but not always necessary.

Usage

To use self.foobar as a lazy property, simply define it on the Plugin class, and decorate it with @lazy_property decorator:

from safeguard.sessions.plugin import AAPlugin
from safeguard.sessions.plugin.plugin_base import lazy_property

class MyPlugin(AAPlugin):
    @lazy_property
    def foobar(self):
        return calculate_answer()

    def do_authenticate(self):
        if need_foobar:
            print(self.foobar)

11.4. named_cookie_property

plugin_base.named_cookie_property()

The @named_cookie_property decorator is working similarly to the @cookie_property decorator. The only difference is you can specify the key you want to save value in the self.cookie It is important that you have to call the decorator with the desired key name, see usage.

Usage

To use self.my_custom_key as a cookie property, simply define it on the Plugin class, and decorate it with @named_cookie_property(key=my_custom_key) decorator:

from safeguard.sessions.plugin import AAPlugin
from safeguard.sessions.plugin.plugin_base import named_cookie_property

class MyPlugin(AAPlugin):
    @named_cookie_property(key=my_custom_key)
    def foobar(self):
        return 42

    def do_authenticate(self):
        assert self.cookie.my_custom_key == 42

11.5. PluginBase

class safeguard.sessions.plugin.plugin_base.PluginBase(configuration, defaults=None, logger=None)

The PluginBase class is a common base class for every kind of plugins. This class is not meant to be used directly.

PLUGIN_NAME

The cls.PLUGIN_NAME class attribute will be used to prefix any logs that the plugin emits. It should be set by the plugin developer to identify the plugin in the system logs.

from safeguard.sessions.plugin.plugin_base import PluginBase

class SimplePlugin(PluginBase):
    PLUGIN_NAME="SimplePlugin"

cookie

The self.cookie attribute is a dict that retains its contents between invocations of plugin hooks of the same plugin instance. This is the way to pass data between these functions.

session_cookie

The self.session_cookie is similar to self.cookie, but it is also visible in other plugins in the same session.

plugin_configuration

The self.plugin_configuration attribute provides access to the plugin configuration via the PluginConfiguration class.

logger

The self.logger attribute should be used to access Python logging. Its log level is set up from the plugin configuration.

https_proxy_server

The self.https_proxy_server attribute contains the IP address or hostname of the HTTPS proxy which is set either system wide or in the plugin configuration via the https_proxy section.

https_proxy_port

The self.https_proxy_port attribute contains the port number of the HTTPS proxy which is set either system wide or in the plugin configuration via the https_proxy section.

https_proxy_username

The self.https_proxy_username attribute contains the basic authentication username of the HTTPS proxy which is set either system wide or in the plugin configuration via the https_proxy section.

https_proxy_password

The self.https_proxy_password attribute contains the basic authentication password of the HTTPS proxy which is set either system wide or in the plugin configuration via the https_proxy section.

proxy_settings

The self.proxy_settings attribute is a dictionary of the HTTPS settings.

box_configuration

The self.box_configuration attribute provides access to system settings.

The __init__() constructor method parses the configuration and sets up logging and http proxy environment variables.