11. Plugin base functions

The following decorators and the PluginBase class may be used in any Plugin SDK based plugin to get some basic functionality.

safeguard.sessions.plugin.plugin_base.lazy_property(factory)

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)

safeguard.sessions.plugin.plugin_base.cookie_property(factory)

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.

safeguard.sessions.plugin.plugin_base.named_cookie_property(key=None)

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

safeguard.sessions.plugin.plugin_base.session_cookie_property(factory)

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.

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

The PluginBase implements:

• parsing the textual plugin configuration

• setting the log level

• setting HTTPS proxy environment variables https_proxy and HTTPS_PROXY

• basic cookie handling methods