Utility¶
This is the toolbox used by The core:
As well as used by the Tools:
See also
Note
If you have no explicit reason, do not use the functions here directly.
Always try to work trough
photon.Photon
and it’s handlers.- If you discover you are repeatedly calling backend functions
consider adding a tool for that job!
Files¶
-
photon.util.files.
read_file
(filename)[source]¶ Reads files
Parameters: filename – The full path of the file to read Returns: The content of the file as string (if filename exists) Note
If filename‘s content is empty,
None
will also returned.To check if a file really exists use
util.locations.search_location()
-
photon.util.files.
read_json
(filename)[source]¶ Reads json files
Parameters: filename – The full path to the json file Returns: Loaded json content as represented data structure
-
photon.util.files.
read_yaml
(filename, add_constructor=None)[source]¶ Reads YAML files
Parameters: - filename – The full path to the YAML file
- add_constructor – A list of yaml constructors (loaders)
Returns: Loaded YAML content as represented data structure
See also
util.structures.yaml_str_join()
,util.structures.yaml_loc_join()
-
photon.util.files.
write_file
(filename, content)[source]¶ Writes files
Parameters: - filename – The full path of the file to write (enclosing folder must already exist)
- content – The content to write
Returns: The size of the data written
Locations¶
-
photon.util.locations.
backup_location
(src, loc=None)[source]¶ Writes Backups of locations
Parameters: - src – The source file/folder to backup
- loc –
The target folder to backup into
The backup will be called src +
util.system.get_timestamp()
. * If loc left to none, the backup gets written in the same folder like src resides in- Otherwise the specified path will be used.
-
photon.util.locations.
change_location
(src, tgt, move=False, verbose=True)[source]¶ Copies/moves/deletes locations
Parameters: - src – Source location where to copy from
- tgt –
Target location where to copy to
- To backup src, set tgt explicitly to
True
. tgt will be set to src + ‘_backup_’ +util.system.get_timestamp()
then
- To backup src, set tgt explicitly to
- move –
Deletes original location after copy (a.k.a. move)
- To delete src , set tgt explicitly to
False
and move toTrue
(be careful!!1!)
- To delete src , set tgt explicitly to
- verbose – Show warnings
-
photon.util.locations.
get_locations
()[source]¶ Compiles default locations
Returns: A dictionary with folders as values: - ‘home_dir’: Your home-directory (
~
) - ‘call_dir’: Where you called the first Python script from. (
argv[0]
) - ‘conf_dir’: The
XDG_CONFIG_HOME
-directory +photon
(~/.config/photon
) - ‘data_dir’: The
XDG_DATA_HOME
-directory +photon
(~/.local/share/photon
)
Note
- Both
search_location()
andmake_locations()
have the argument locations. - If locations is set to
None
(by default), it will be filled with the output ofget_locations()
.
- ‘home_dir’: Your home-directory (
-
photon.util.locations.
make_locations
(locations=None, verbose=True)[source]¶ Creates folders
Parameters: - locations – A list of folders to create (can be a dictionary, see note below)
- verbose – Warn if any folders were created
Note
- If locations is not a list, but a dictionary,
all values in the dictionary will be used
(as specified in
util.structures.to_list()
) - If locations is set to
None
(by default), it will be filled with the output ofget_locations()
.
-
photon.util.locations.
search_location
(loc, locations=None, critical=False, create_in=None, verbose=True)[source]¶ Locates files with a twist:
- Check the existence of a file using the full path in loc
- Search for the filename loc in locations
- Create it’s enclosing folders if the file does not exist. use create_in
Parameters: - loc – Filename to search
- locations – A list of possible locations to search within (can be a dictionary, see note below)
- critical – Tears down (using
util.system.shell_notify()
with state set toTrue
) whole application if file was not found - create_in – If loc was not found, the folder create_in is created. If locations is a dictionary, create_in can also specify a key of locations. The value will be used then.
- verbose – Pass verbose flag to
make_locations()
Returns: The full path of loc in matched location
Note
- If locations is not a list, but a dictionary,
all values in the dictionary will be used
(as specified in
util.structures.to_list()
) - If locations is set to
None
(by default), it will be filled with the output ofget_locations()
.
Structures¶
-
photon.util.structures.
dict_merge
(o, v)[source]¶ Recursively climbs through dictionaries and merges them together.
Parameters: - o – The first dictionary
- v – The second dictionary
Returns: A dictionary (who would have guessed?)
Note
Make sure o & v are indeed dictionaries, bad things will happen otherwise!
-
photon.util.structures.
to_list
(i, use_keys=False)[source]¶ Converts items to a list.
Parameters: - i –
Item to convert
- If i is
None
, the result is an empty list - If i is ‘string’, the result won’t be
['s', 't', 'r',...]
rather more like['string']
- If i is a nested dictionary, the result will be a flattened list.
- If i is
- use_keys – If i is a dictionary, use the keys instead of values
Returns: All items in i as list
- i –
-
photon.util.structures.
yaml_loc_join
(l, n)[source]¶ YAML loader to join paths
The keywords come directly from
util.locations.get_locations()
. See there!Returns: A path seperator ( /
) joined string with keywords extended. Used insettings.Settings.load()
See also
The YAML files mentioned in Example Settings File, Mail Tool Example, Ping Tool Example
-
photon.util.structures.
yaml_str_join
(l, n)[source]¶ YAML loader to join strings
The keywords are as following:
- hostname: Your hostname (from
util.system.get_hostname()
) - timestamp: Current timestamp (from
util.system.get_timestamp()
)
Returns: A non character joined string with keywords extended. Used in settings.Settings.load()
Note
Be careful with timestamps when using a config in Settings.
See also
The YAML files mentioned in Example Settings File, Mail Tool Example, Ping Tool Example
- hostname: Your hostname (from
System¶
-
photon.util.system.
get_hostname
()[source]¶ Determines the current hostname by probing
uname -n
. Falls back tohostname
in case of problems.Tears down (using
util.system.shell_notify()
with state set toTrue
) whole application if both failed (usually they don’t but consider this if you are debugging weird problems..)Returns: The hostname as string. Domain parts will be split off
-
photon.util.system.
get_timestamp
(time=True, precice=False)[source]¶ What time is it?
Parameters: - time – Append
-%H.%M.%S
to the final string. - precice – Append
-%f
to the final string. Is only recognized when time is set toTrue
Returns: A timestamp string of now in the format
%Y.%m.%d-%H.%M.%S-%f
See also
strftime.org is awesome!
- time – Append
-
photon.util.system.
shell_notify
(msg, state=False, more=None, exitcode=None, verbose=True)[source]¶ A pretty long wrapper for a
print()
function. But thisprint()
is the only one in Photon.Note
This method is just a helper method within photon. If you need this functionality use
photon.Photon.m()
insteadParameters: - msg – The message to show
- state –
The message will be prefixed with [state]
- If
False
(default): Prefixed with ~ - If
None
: Prefixed with [WARNING] - If
True
: Prefixed with [FATAL] and the exitcode will be set (see below)
- If
- more –
Something to add to the message (see below)
- Anything you have. Just for further information.
- Will be displayed after the message, pretty printed using
pprint.pformat()
- exitcode – Tears down (using
util.system.shell_notify()
with state set toTrue
) whole application with given code - verbose –
Show message or not (see below)
- If set to
False
, you can useshell_notify()
for the dictionary it returns. - Will be overruled if exitcode is set.
- If set to
Returns: A dictionary containing untouched msg, more and verbose
-
photon.util.system.
shell_run
(cmd, cin=None, cwd=None, timeout=10, critical=True, verbose=True)[source]¶ Runs a shell command within a controlled environment.
Note
This method is just a helper method within photon. If you need this functionality use
photon.Photon.m()
insteadParameters: - cmd –
The command to run
- A string one would type into a console like git push -u origin master.
- Will be split using
shlex.split()
. - It is possible to use a list here, but then no splitting is done.
- cin – Add something to stdin of cmd
- cwd – Run cmd insde specified current working directory
- timeout – Catch infinite loops (e.g.
ping
). Exit after timeout seconds - critical – If set to
True
: Tears down (usingutil.system.shell_notify()
with state set toTrue
) whole application on failure of cmd - verbose – Show messages and warnings
Returns: A dictionary containing the results from running cmd with the following:
- ‘command’: cmd
- ‘stdin’: cin (If data was set in cin)
- ‘cwd’: cwd (If cwd was set)
- ‘exception’: exception message (If an exception was thrown)
- ‘timeout’: timeout (If a timeout exception was thrown)
- ‘stdout’: List from stdout (If any)
- ‘stderr’: List from stderr (If any)
- ‘returncode’: The returncode (If not any exception)
- ‘out’: The most urgent message as joined string. (‘exception’ > ‘stderr’ > ‘stdout’)
- cmd –