Framework Package

TODO.

Authors:

• Philipp Schuette

class pyzeta.framework.aop.advice.Advice(preFunc=None, postFunc=None)

Class representation of advice, i.e. an action to perform at runtime.

__call__(instanceMethod)

Wrap a given method with the pre and post callbacks of the advice.

Parameters:

instanceMethod (Callable[[ParamSpec(P)], TypeVar(T)]) – the method to wrap

Returns:

Callable[[ParamSpec(P)], TypeVar(T)] – the wrapped method

__init__(preFunc=None, postFunc=None)

Initialize a new advice from callables to be applied around a point cut. At least one of the callbacks must be given. The pre callback must accept the same arguments as the wrapped method while the post callback must additionally accept the return value of the wrapped method as its first argument.

Parameters:

• preFunc (Optional[Callable[[ParamSpec(P)], None]]) – callback to be invoked before the point cut (default: None)

• postFunc (Optional[Callable[[TypeVar(T), ParamSpec(P)], TypeVar(T)]]) – callback to be invoked after the point cut (default: None)

TODO.

Authors:

• Philipp Schuette

class pyzeta.framework.aop.aspect.Aspect(rules)

Implementation of the central abstraction of aspect oriented programming.

__call__(cls)

Apply a given aspect to some class.

Parameters:

cls (Type[TypeVar(S)]) – class to modify with the aspect

Return type:

None

__init__(rules)

Initialize a new aspect from a given set of rules, i.e. pairs of point cuts and corresponding advice. For consistency reasons rules cannot be added or deleted after initialization.

Parameters:

rules (List[Rule[TypeVar(T), ParamSpec(P)]]) – rules contained in the created aspect instance

TODO.

Author:

• Philipp Schuette

class pyzeta.framework.aop.point_cut.PointCut(pattern='.*')

Class representation of a point cut, i.e. point in time at which some advice may be applied.

__init__(pattern='.*')

Initialize a new point cut from a given (method) name pattern.

Parameters:

pattern (str) – name pattern for selection of applicable methods (default: '.*')

match(methodName)

Determine whether a given runtime configuration matches this point cut.

Parameters:

methodName (str) – method to apply advice to

Returns:

bool – boolean flag indicate match status

TODO.

Authors:

• Philipp Schuette

class pyzeta.framework.aop.rule.Rule(pointCut, advice)

Simple container structure representing pairs of point cuts and advice.

__eq__(other)

Return self==value.

__hash__ = None

__init__(pointCut, advice)

__repr__()

Return repr(self).

Very basic implementation of feature flags. Instances of these flags are useful to e.g. toggle certain (parts of) workflows in complex numerical experiments.

Authors:

• Philipp Schuette

class pyzeta.framework.feature_toggle.feature_flag.FeatureFlag(name, value, description, logger, timesAccessible=1)

Simple implementation of a feature flag.

__bool__()

Custom boolean evaluation that makes the flag delegate boolean behavior to its value attribute after checking the current status of timesAccessible.

Return type:

bool

__eq__(other)

Return self==value.

__hash__ = None

__init__(name, value, description, logger, timesAccessible=1)

__repr__()

Return repr(self).

Very simple base implementation for collections of feature flags. This is part of the PyZeta framework.

Usage example:

MyToggles(ToggleCollection):
    toggle1: bool
    toggle2: bool

toggles = MyToggles("toggles.json")

Authors:

• Philipp Schuette

class pyzeta.framework.feature_toggle.toggle_collection.LoadedToggle

The type of a toggle configuration loaded from json.

class pyzeta.framework.feature_toggle.toggle_collection.LoadedToggleRequired

This is need to be able to mix required and optional keys pre python3.11.

class pyzeta.framework.feature_toggle.toggle_collection.ToggleCollection(filename)

Subclass this class to implement your own collection of feature flags.

__init__(filename)

Initialize a new collection of feature toggles from a given .json config file.

Parameters:

filename (str) – name of the .json config file

Module container.py from the package pyzeta.framework.ioc. This module provides a way to register and locate services used throughout the project, to enable loading additional services for the plugin system.

Authors:

• Philipp Schuette

class pyzeta.framework.ioc.container.Container

Container class used to add and resolve services as part of dependency inversion.

__init__()

Initialize a new container instance.

clearConfigurations()

Clear all previous configurations, unsealing the container in the process.

Return type:

None

isSealed()

Return True if the container is sealed.

Returns:

bool – True if container is sealed

registerAsSingleton(serviceType, instance)

Register service instance as a singleton service. The instance resolved will be identical to the instance registered.

Parameters:

• serviceType (Type[TypeVar(T)]) – Type of service

• instance (TypeVar(T)) – Service instance

Raises:

• ValueError – If the container is sealed, no new services can be registered.

• InvalidServiceConfiguration – Given instance must implement the given type

Returns:

Container – Return the container instance itself for method chaining

registerAsTransient(serviceType, factory)

Register a transient service. Note that you MUST implement a (dummy) default constructor if you want to register a class without constructor as an instance factory and that class inherits from typing.Protocol.

Parameters:

• serviceType (Type[TypeVar(T)]) – Type of service to register.

• factory (Callable[..., TypeVar(T)]) – Factory for the given service

Raises:

ValueError – If the container is sealed, no new services can be registered.

Returns:

Container – Return the container instance itself for method chaining

registerAspect(aspect, serviceType)

Register an aspect for a given type of service. The aspect intercepts calls to resolve the service type and adorns the concrete return types lazily.

Parameters:

• aspect (Aspect[TypeVar(S), TypeVar(T), ParamSpec(P)]) – Aspect to apply to the service

• serviceType (Type[TypeVar(S)]) – The type of service whose implementations gets aspect gets applied to

Returns:

Container – Return the container instance for method chaining

seal()

Seal the container to prevent additional services from being registered.

Raises:

ValueError – Raises an exception if the container has already been sealed.

Return type:

None

tryResolve(serviceType, **kwargs)

Try to resolve the requested service type by first searching registered singleton and then registered transient configurations.

Parameters:

serviceType (Type[TypeVar(T)]) – Type of service to resolve

Raises:

InvalidServiceConfiguration – If the given serviceType can not be resolved, an exception is raised

Returns:

TypeVar(T) – An instance of the given service. If the service is transient, the factory is called with the parameters given by **kwargs.

Module container_provider.py from the package PyZeta. The static (global) ContainerProvider exposes the global container instance valid for the current project instance. Every object that requires a container and cannot obtain it from anywhere else should request it from here.

Authors:

• Philipp Schuette

class pyzeta.framework.ioc.container_provider.ContainerProvider

Static folder providing a pre-built (during initialization) container.

static getContainer()

Return the pre-built container instance.

Return type:

Container

static registerAspectGlobally(aspect, serviceType)

Register an aspect for a type on the global container instance.

Return type:

None

static setContainer(container)

Register a pre-built container instance.

Return type:

None

This module contains the base interface for plugins. Its methods provide the necessary functions for plugin handling.

Authors:

• Philipp Schuette

class pyzeta.framework.plugins.pyzeta_plugin.PyZetaPlugin

Interface for plugins. Methods for instantiation and plugin information need to be implemented by concrete subclasses.

abstract static getInstance()

Return the singleton instance of PyZetaPlugin which provides a service of type T_co.

Returns:

PyZetaPlugin[TypeVar(T_co, bound= Union[SettingsService, PyZetaParserInterface, SymmetryGroup], covariant=True)] – PyZetaPlugin instance.

abstract static initialize()

Returns a factory for the plugin’s implementation of T_co.

Returns:

Callable[..., TypeVar(T_co, bound= Union[SettingsService, PyZetaParserInterface, SymmetryGroup], covariant=True)] – Factory for plugin implementation of T_co.

abstract property pluginName: str

Return the name of the plugin.

Returns:

Plugin name.

abstract property pluginType: Type[T_co]

Return the type provided by the plugin.

Returns:

Service type of plugin.

abstract property pluginVersion: Tuple[int, int, int]

Return the version of the plugin as (major, minor, patch).

Returns:

Plugin version.

Module plugin_loader.py from the PyZeta project. This module handles discovering, loading and registering of plugins.

Authors:

• Philipp Schuette

class pyzeta.framework.plugins.plugin_loader.PluginLoader(*args, **kwargs)

This class handles plugin discovery, loading and registration.

static discoverAttributes(candidateModule)

Discover attributes of a candidate module. Ignores attributes starting with __.

Parameters:

candidateModule (ModuleType) – Candidate module

Returns:

List[str] – List of attributes.

static discoverModules(path='/home/docs/checkouts/readthedocs.org/user_builds/pyzeta/envs/latest/lib/python3.9/site-packages/pyzeta/framework/plugins/custom_plugins')

Discover all possible plugin files in path. Ignore files starting with __.

Parameters:

path (str) – Path to search, defaults to PLUGIN_INSTALL_DIR (default: '/home/docs/checkouts/readthedocs.org/user_builds/pyzeta/envs/latest/lib/python3.9/site-packages/pyzeta/framework/plugins/custom_plugins')

Returns:

List[str] – List of plugin candidates.

static getInstance()

Return the global PluginLoader instance. If no instance exists, a new one is created and returned.

Returns:

PluginLoader – PluginLoader singleton instance.

static isPyFile(filename)

Returns True if filename corresponds to a python file.

Parameters:

filename (str) – File to evaluate

Returns:

str – True if filename corresponds to a python file.

loadPlugin(candidateModule)

Try to load a candidate plugin and return it if successful.

Parameters:

candidateModule (ModuleType) – Candidate plugin module

Returns:

Optional[Type[PyZetaPlugin[Union[SettingsService, PyZetaParserInterface, SymmetryGroup]]]] – Plugin if an implementation has been found, else None.

static loadPlugins(container, path='/home/docs/checkouts/readthedocs.org/user_builds/pyzeta/envs/latest/lib/python3.9/site-packages/pyzeta/framework/plugins/custom_plugins')

Load plugins present in path.

Parameters:

• container (Container) – Container to load the discovered plugins into

• path (str) – Path to search for plugins, defaults to PLUGIN_INSTALL_DIR (default: '/home/docs/checkouts/readthedocs.org/user_builds/pyzeta/envs/latest/lib/python3.9/site-packages/pyzeta/framework/plugins/custom_plugins')

Returns:

List[PyZetaPlugin[Union[SettingsService, PyZetaParserInterface, SymmetryGroup]]] – List of loaded plugins.

locateAndLoadPlugins(path='/home/docs/checkouts/readthedocs.org/user_builds/pyzeta/envs/latest/lib/python3.9/site-packages/pyzeta/framework/plugins/custom_plugins')

Discover plugins at a given path and load them.

Parameters:

path (str) – Path to search for plugins, defaults to PLUGIN_INSTALL_DIR (default: '/home/docs/checkouts/readthedocs.org/user_builds/pyzeta/envs/latest/lib/python3.9/site-packages/pyzeta/framework/plugins/custom_plugins')

Returns:

List[Type[PyZetaPlugin[Union[SettingsService, PyZetaParserInterface, SymmetryGroup]]]] – List of found plugins.

Class CoreSettingsService from the package pyzeta_settings. This module defines a protocol for a generic settings provider pertaining to the core features of PyZeta.

Authors:

• Philipp Schuette

class pyzeta.framework.settings.core_settings_service.CoreSettingsService(*args, **kwargs)

Class providing a layer of abstraction for storage and retrieval of PyZeta core settings. Concrete SettingService implementations can choose freely their data model and persistence layer.

__init__(*args, **kwargs)

property logLevel: LogLevel

Get the current LogLevel setting.

Returns:

Current LogLevel

Class SettingsService from the package pyzeta_settings. This module defines a protocol for a generic settings provider.

Authors:

• Philipp Schuette

class pyzeta.framework.settings.settings_service.SettingsService(*args, **kwargs)

Class providing a layer of abstraction for storage and retrieval of PyZeta related settings. Concrete SettingService implementations can choose freely their data model and persistence layer.

__init__(*args, **kwargs)

property verbose: bool

Get current verbosity setting.

Returns:

True if verbose mode is enabled.

Class PyZetaLogger from the package pyzeta_logging.

This module provides a facade for logging.Logger class from the standard library logging module. Any access to loggers in this project should happen only through this interface.

Authors:

• Philipp Schuette

class pyzeta.framework.pyzeta_logging.logger_facade.PyZetaLogger(*args, **kwargs)

The logging interface used throughout the PyZeta project.

__init__(*args, **kwargs)

critical(msg, *args)

Log msg with severity CRITICAL.

Parameters:

msg (str) – Message to log

Return type:

None

debug(msg, *args)

Log msg with severity DEBUG.

Parameters:

msg (str) – Message to log

Return type:

None

error(msg, *args)

Log msg with severity ERROR.

Parameters:

msg (str) – Message to log

Return type:

None

info(msg, *args)

Log msg with severity INFO.

Parameters:

msg (str) – Message to log

Return type:

None

isEnabledFor(level)

Test if logging is enabled for level level.

Parameters:

level (int) – Level to test

Returns:

bool – If logging is enabled for level level

setLevel(level)

Set the logging level to level

Parameters:

level (int) – New level of the logger

Return type:

None

warning(msg, *args)

Log msg with severity WARNING.

Parameters:

msg (str) – Message to log

Return type:

None

Module providing a simple mixin class which enables logging functionality.

Authors:

• Philipp Schuette

class pyzeta.framework.pyzeta_logging.loggable.Loggable(*args, **kwargs)

Mixin for combination with classes which support logging.

__init__(*args, **kwargs)

property logger: PyZetaLogger

The logger instance associated with this Loggable class. Instance creation happens upon first property access.

Returns:

the logger of this class

setLevel(level)

Set the log level.

Parameters:

level (LogLevel) – the new log level

Return type:

None

Module log_manager.py of the pyzeta_logging package. This module contains the basic logging setup to be used with all PyZeta related modules.

Authors:

• Philipp Schuette

class pyzeta.framework.pyzeta_logging.log_manager.LogManager

This class handles basic logging functionalities to be used by PyZeta related modules.

static buildFileName()

Build a name for a (new or existing) log file based on the PyZeta logging naming convention.

Returns:

str – convention compliant log file name

static initLogger(logName, logLevel)

Initialize a module-level logger for the module ‘modName’. Default logging level is retrieved from SettingsService. All logs are stored in a ./logs directory in a file pyzeta_<datetime.now>.log, where the date is determined at the start of every new session (upon first creation of a module logger within a session).

Parameters:

logName (str) – the name of the logger, should equal the module name

Returns:

PyZetaLogger – the (module-level) logger