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.
Module contents¶
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:
pyzenkit.zenscript.ZenScript
Minimalistic class for demonstration purposes.
-
class
pyzenkit.zenscript.
ZenScript
(**kwargs)[source]¶ Bases:
pyzenkit.baseapp.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:
pyzenkit.baseapp.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 asfloat
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