pyzenkit.zenscript module

This module provides base implementation of generic script represented by the pyzenkit.zenscript.ZenScript class with built-in support for regular executions. It builds on top of pyzenkit.baseapp module and adds couple of other usefull features:

Support for executing multiple different commands.
Support for multiple execution modes (default, regular, shell).
Support for executions in regular time intervals.

Script commands

Every script provides support for more, possibly similar, commands to be implemented within one script. The use case for this may be a fictional example backup script, that can provide separate commands for backup and restore features, but pack both of them nicelly into one package/module/executable.

Commands are implemented very easily by adding new method according to following convention:

Command callback must be method without any mandatory arguments.
Command callback method name must begin with cbk_command_ prefix.
Command name in the method name after the prefix must also be snake_cased`.
Command name will be calculated by replacing _ with -.

Following are examples of valid command callbacks:

cbk_command_test(self)         # Will be mapped to 'test' command.
cbk_command_another_test(self) # Will be mapped to 'another-test' command.

When a method is implemented according to these guidelines, it will be automatically recognized and executable.

Commands may be executed by selecting the desired command by command line argument:

path/to/zenscript.py --command default
path/to/zenscript.py --command=alternative

Command may also be selected permanently inside configuration file under the dictionary key command.

Script execution modes

Script execution supports following modes:

regular

In a regular mode the script is intended to be executed in regular time intervals from a cron-like service (usually). The internal application configuration is forced into following state:

Console output is explicitly suppressed
Console logging level is explicitly forced to warning level
Logging to log file is explicitly forced to be enabled
Runlog saving is explicitly forced to be enabled
Persistent state saving is explicitly forced to be enabled

shell

In a shell mode the script is intended to be executed by hand from interactive shell. It is intended to be used for debugging or experimental purposes, or for applications that are executed by hand by a user. The internal application configuration is forced into following state:

Logging to log file is explicitly disabled
Runlog saving is explicitly disables
Persistent state saving is explicitly disabled

default

In a default mode the script directs its output both to the files and stdout and runlog and persistent state saving are enabled.

Regular executions

Following is a list of predefined regular execution time intervals:

5_minutes
10_minutes
15_minutes
20_minutes
30_minutes
hourly
2_hourly
3_hourly
4_hourly
6_hourly
12_hourly
daily
weekly
2_weekly
4_weekly

The ZenScript.calculate_interval_thresholds() method can be used to calculate time interval thresholds (lower and upper boundary) for given time interval and time. These values can be then used for a number of use cases like fetching data from database etc.

Programming API

public methods:
- calculate time interval thresholds: ZenScript.calculate_interval_thresholds()
- execute script command by name: ZenScript.execute_script_command()
- get a name of a default command: ZenScript.get_default_command()

class pyzenkit.zenscript.DemoZenScript(name=None, description=None)[source]

Bases: ZenScript

Minimalistic class for demonstration purposes.

cbk_command_alternative()[source]: Alternative script command.

cbk_command_default()[source]: Default script command.

get_default_command()[source]: Return the name of a default script operation.

class pyzenkit.zenscript.ZenScript(**kwargs)[source]

Bases: BaseApp

Base implementation of generic one-time execution script with built-in regular execution interval support.

CONFIG_ADJUST_THRESHOLDS = 'adjust_thresholds'

CONFIG_COMMAND = 'command'

CONFIG_INTERVAL = 'interval'

CONFIG_REGULAR = 'regular'

CONFIG_SHELL = 'shell'

CONFIG_TIME_HIGH = 'time_high'

PTRN_COMMAND_CBK = 'cbk_command_'

RLKEY_COMMAND = 'command'

calculate_interval_thresholds(time_high=None, interval='daily', adjust=False)[source]

Calculate time interval thresholds based on given upper time interval boundary and time interval size.

Parameters

time_high – Upper time threshold as float (unix timestamp), string (RFC3339), or datetime.datetime object.
interval (str) – Time interval, one of the interval defined in pyzenkit.zenscript.
adjust (bool) – Adjust time thresholds to round values (floor).

Returns

Lower and upper time interval boundaries.

Return type

tuple of datetime.datetime

calculate_upper_threshold(time_high=None, interval='daily', adjust=False)[source]

Calculate upper time threshold based on given upper time interval boundary and time interval size.

Parameters

time_high – Upper time threshold as float (unix timestamp), string (RFC3339), or datetime.datetime object.
interval (str) – Time interval, one of the interval defined in pyzenkit.zenscript.
adjust (bool) – Adjust time thresholds to round values (floor).

Returns

Lower and upper time interval boundaries.

Return type

tuple of datetime.datetime

execute_script_command(command_name)[source]

Execute given script command and store the received results into script runlog.

Following method will call appropriate callback method to service the requested script command.

Name of the callback method is generated from the name of the command by prepending string cbk_command_ and replacing all - with _.

get_default_command()[source]

Return the name of the default command. This method must be present and overriden in subclass and must return the name of desired default command. Following code is just a reminder for developer to not forget to implement this method.

Returns: Name of the default command.
Return type: str

exception pyzenkit.zenscript.ZenScriptException(description, **params)[source]

Bases: ZenAppProcessException

Describes problems specific to scripts.

pyzenkit.zenscript.t_datetime(val)[source]

Convert/validate datetime. The value received by this conversion function may be either datetime.datetime object (in that case no action will be done), unix timestamp as float or datetime as RFC3339 string.

Parameters: val (any) – Value to be converted/validated
Returns: Datetime object
Return type: datetime.datetime
Raises: ValueError – if the value could not be converted to datetime.datetime object