The core¶
All three modules depend on the Utility:
See also
Settings and Meta could be used independently or both together.
Bundling Settings and Meta together plus adding the Tools, Photon provides a interface to use in your scripts.
See also
Settings¶
-
class
photon.settings.
Settings
(defaults, config='config.yaml', verbose=True)[source]¶ Settings is a class which provides access to compiled settings loaded from YAML-files.
The YAML-files will be read with specific loaders which enables certain logic within the configuration. It is possible to:
- Insert references to existing fields via anchors and
!str_join
or!loc_join
- Insert keywords like hostname or timestamp using
!str_join
- Combine path-segments using
!loc_join
- Insert keywords like home_dir or conf_dir using
!loc_join
It is also possible to import or merge further content.
Parameters: - defaults –
The initial configuration to load. Will be located using
util.locations.search_location()
- The common way is to use a short-filename to locate it next to the script using Photon.
- Can also be a full path.
- Can also passed directly as a dict
- Bring your own defaults! Tears down (using
util.system.shell_notify()
with state set toTrue
) whole application if not found or none passed.
- config –
Where to store the loaded output from the defaults. Will be located using
util.locations.search_location()
- File must already exist, will be created in ‘conf_dir’ from
util.locations.get_locations()
otherwise- Therefore use a short name (or full path) if one should be created
Note
The last loaded file wins
- The config is intended to provide a editable file for the end-user
- If a value differs from the original values in defaults, the value in config wins
- Other values which not exist in config will be set from defaults
- If a value in config contains a loader call which expresses the same as the value in defaults it will be skipped.
- Be careful using timestamp s in a config. The timestamp of the first launch will always be used.
- Simply delete all lines within the config to completely reset it to the defaults
- Can be skipped by explicitly setting it to
None
- File must already exist, will be created in ‘conf_dir’ from
- verbose – Sets the verbose flag for the underlying Utility functions
See also
util.structures.yaml_str_join()
andutil.structures.yaml_loc_join()
as well as the Example Settings File-
get
¶ Returns: Current settings
-
load
(skey, sdesc, sdict=None, loaders=None, merge=False, writeback=False)[source]¶ Loads a dictionary into current settings
Parameters: - skey – Type of data to load. Is be used to reference the data in the files sections within settings
- sdesc – Either filename of yaml-file to load or further description of imported data when sdict is used
- sdict (dict) – Directly pass data as dictionary instead of loading it from a yaml-file. Make sure to set skey and sdesc accordingly
- loaders (list) – Append custom loaders to the YAML-loader.
- merge – Merge received data into current settings or place it under skey within meta
- writeback – Write back loaded (and merged/imported) result back to the original file. This is used to generate the summary files
Returns: The loaded (or directly passed) content
See also
util.structures.yaml_str_join()
andutil.structures.yaml_loc_join()
- Insert references to existing fields via anchors and
Example Settings File¶
defaults.sample.yaml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | # The syntax of the settings files is YAML:
01_syntax:
dictionary: 'value is a string'
dictionary_with_list: ['value', 'is', 'a', 'list']
dictionary_with_list2:
- this
- is
- another
- list
# ----
# YAML supports backreferences by anchors.
# First yo have define a dictionary value as anchor:
02_anchor:
prefix: &MY_PRFX 'Photon is a software that '
# Then use them together with !str_join:
poll:
yay: !str_join [*MY_PRFX, 'realy helps me']
nay: !str_join [*MY_PRFX, 'sucks']
# This turns into:
# yay: Photon is a software that really helps me
# nay: Photon is a software that sucks
# (The anchor ('&'-sign) must appear before the Reference ('*'-sign) in the YAML-file.
# (Note the whitespace.)
# ----
# !str_join can listen to the keywords - 'hostname' & 'timestamp':
03_keywords:
message:
- !str_join ['my machine "', 'hostname', '" is the best']
- !str_join ['yours, herbert. date: ', 'timestamp']
# This turns into:
# message:
# - my machine "blechschachtel" is the best
# - 'yours, herbert. date: YYYY.MM.DD-HH.MM.SS'
# (with current date expanded)
# ----
# Use !loc_join to combine files and paths:
04_locations:
simple_file: !loc_join ['/', 'usr', 'local', 'bin', 'myscript.sh']
same_simple_file: !loc_join ['/usr/local/bin', 'myscript.sh']
# This turns into:
# simple_file: /usr/local/bin/myscript.sh
# same_simple_file: /usr/local/bin/myscript.sh
# But be careful with leading '/'-signs:
not_the_simple_file: !loc_join ['/usr/local', '/bin', 'myscript.sh']
# This turns into not what we wanted:
# not_the_simple_file: /bin/myscript.sh
# It can also listen to keywords:
in_the_home_dir: !loc_join ['home_dir', 'my_directory']
# in_the_home_dir: /home/herbert/my_directory
# ----
# Combine them alltogether:
05_combined:
name: &MY_ASS my_awesome_server_software
main: &OH_MY !loc_join ['home_dir', *MY_ASS, 'main']
main_run: !loc_join [*OH_MY, 'run.py']
backup_dir: !loc_join ['data_dir', *MY_ASS, !str_join ['backup-', 'timestamp']]
git-remote: !str_join
- 'https://github.com/user404/'
- *MY_ASS
- .git
# This turns into:
# name: my_awesome_server_software
# main: /home/herbert/my_awesome_server_software/main
# main_run: /home/herbert/my_awesome_server_software/main/run.py
# backup_dir: /home/herbert/.local/share/photon/my_awesome_server_software/backup-YYYY.MM.DD-HH.MM.SS
# git-remote: https://github.com/user404/my_awesome_server_software.git
|
See also
The wikipedia page on YAML for some syntax reference.
See also
- !loc_join:
util.structures.yaml_loc_join()
(get locations by keyword and join paths)
- !loc_join:
- !str_join:
util.structures.yaml_str_join()
(get variables by keyword and join strings)
- !str_join:
Meta¶
-
class
photon.meta.
Meta
(meta='meta.json', verbose=True)[source]¶ Meta is a class which bounds to an actual json-file on disk. It provides a logger storing the entries in that json-file.
It is also possible to import contents. By staging out to a different directory meta-files are left behind for further debugging or to see what was going on.
Parameters: -
load
(mkey, mdesc, mdict=None, merge=False)[source]¶ Loads a dictionary into current meta
Parameters: - mkey – Type of data to load. Is be used to reference the data from the ‘header’ within meta
- mdesc – Either filename of json-file to load or further description of imported data when mdict is used
- mdict (dict) – Directly pass data as dictionary instead of loading it from a json-file. Make sure to set mkey and mdesc accordingly
- merge – Merge received data into current meta or place it under ‘import’ within meta
Returns: The loaded (or directly passed) content
-
log
¶ Parameters: elem – Add a new log entry to the meta.
- Can be anything.
- The log is a dictionary with keys generated from the output of
util.system.get_timestamp()
and elem as value
Returns: Current meta
-
stage
(name, clean=False)[source]¶ Switch stage
Parameters: - name –
Filename of new meta file. Will be located using
util.locations.search_location()
- File must not already exist, will be created in ‘data_dir’ from
util.locations.get_locations()
- Can also be a full path to place it anywhere desired
- File must not already exist, will be created in ‘data_dir’ from
- clean –
What to do with preexisting meta files?
False
: Merge current meta with preexisting oneTrue
: Replace preexisting meta with current one
- name –
-
Photon¶
-
class
photon.photon.
Photon
(defaults, config='config.yaml', meta='meta.json', verbose=True)[source]¶ Photon uses The core and some functions from Utility in its
m()
-method.The
m()
-method itself is used in each tool to interact with photon to:- Launch shell commands, and receive the results
- Add messages to the meta-file
- Show the messages if necessary
- Tear down application completely in case of any serious problems
Further, Photon provides direct handlers for
settings.Settings
andmeta.Meta
and a handler for each tool from Tools by it’s methods.Parameters: Variables: At startup the loaded settings are imported into meta
-
m
(msg, state=False, more=None, cmdd=None, critical=True, verbose=None)[source]¶ Mysterious mega method managing multiple meshed modules magically
Note
If this function is used, the code contains facepalms:
m(
- It is possible to just show a message, or to run a command with message.
- But it is not possible to run a command without a message, use the verbose-flag to hide your debug message.
Parameters: - msg – Add a message. Shown depending on verbose (see below)
- state – Pass state down to
util.system.shell_notify()
- more – Pass more down to
util.system.shell_notify()
- cmdd (dict) – If given,
util.system.shell_run()
is launched with it’s values - critical –
If set to
True
: Tears down (usingutil.system.shell_notify()
with state set toTrue
) whole application on failure of cmdd contents.- Similar to
util.system.shell_run()
critical-flag
- Similar to
- verbose –
Overrules parent’s class verbose-flag.
- If left to
None
, the verbose value Photon was started with is used - Messages are shown/hidden if explicitly set to
True
/False
- If left to
Returns: A dictionary specified the following:
- ‘more’:
more if it is not a dictionary otherwise it gets merged in if more is specified
The output of
util.system.shell_run()
gets merged in if cmdd is specified‘failed’:
True
if command failed
util.system.shell_notify()
is used with this dictionary to pipe it’s output intometa.Meta.log()
before returning.
-
mail_handler
(punchline=None, add_meta=False, add_settings=True, *args, **kwargs)[source]¶ Parameters: - punchline – Adds a punchline before further text
- add_meta – Appends current meta to the mail
- add_settings – Appends current settings to the mail
Returns: A new mail handler
See also
-
s2m
¶ Imports settings to meta