The core

All three modules depend on the Utility:

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.

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 to True) 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
  • verbose – Sets the verbose flag for the underlying Utility functions

See also

util.structures.yaml_str_join() and util.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() and util.structures.yaml_loc_join()

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)

  • !str_join: util.structures.yaml_str_join()

    (get variables by keyword and join strings)

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:
  • meta – Initial, clean meta file to use. See stage() for more
  • verbose – Sets the verbose flag for the underlying Utility functions
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
  • clean

    What to do with preexisting meta files?

    • False: Merge current meta with preexisting one
    • True: Replace preexisting meta with current one

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 and meta.Meta and a handler for each tool from Tools by it’s methods.

Parameters:
  • defaults – Pass defaults down to settings.Settings
  • config – Pass config down to settings.Settings
  • meta – Pass meta down to meta.Meta
  • verbose – Sets the global verbose flag. Passes it down to the underlying Utility functions and The core
Variables:
  • settings – The settings handler initialized with defaults and config
  • meta – The meta handler initialized with meta

At startup the loaded settings are imported into meta

git_handler(*args, **kwargs)[source]
Returns:A new git handler

See also

Git Tool

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 (using util.system.shell_notify() with state set to True) whole application on failure of cmdd contents.

    • Similar to util.system.shell_run() critical-flag
  • 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
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 into meta.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

Mail Tool

ping_handler(*args, **kwargs)[source]
Returns:A new ping handler

See also

Ping Tool

s2m

Imports settings to meta

signal_handler(*args, **kwargs)[source]
Returns:A new signal handler

See also

Signal Tool

template_handler(*args, **kwargs)[source]
Returns:A new template handler

See also

Template Tool

photon.photon.check_m(pm)[source]

Shared helper function for all Tools to check if the passed m-function is indeed photon.Photon.m()

Params pm:Suspected m-function
Returns:Now to be proven correct m-function, tears down whole application otherwise.