The core

All three modules depend on the Utility:

See also

Files, Locations, Structures, System

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

Git Tool, Mail Tool, Ping Tool, Signal Tool

Settings

class 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

(get locations by keyword and join paths)

(get variables by keyword and join strings)

See also

Example Settings File, Mail Tool Example, Ping Tool Example

Meta

class 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.
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(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:
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:
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.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.