Utility

This is the toolbox used by The core:

See also

Settings, Meta, Photon

As well as used by the Tools:

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

photon.util.files.write_json(filename, content)[source]

Writes json files

Parameters:
  • filename – The full path to the json file
  • content – The content to dump
Returns:

The size written

photon.util.files.write_yaml(filename, content)[source]

Writes YAML files

Parameters:
  • filename – The full path to the YAML file
  • content – The content to dump
Returns:

The size 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
  • move

    Deletes original location after copy (a.k.a. move)

    • To delete src , set tgt explicitly to False and move to True (be careful!!1!)
  • 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

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 of get_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 to True) 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 of get_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.
  • use_keys – If i is a dictionary, use the keys instead of values
Returns:

All items in i as list

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 in settings.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

System

photon.util.system.get_hostname()[source]

Determines the current hostname by probing uname -n. Falls back to hostname in case of problems.

Tears down (using util.system.shell_notify() with state set to True) 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 to True
Returns:

A timestamp string of now in the format %Y.%m.%d-%H.%M.%S-%f

See also

strftime.org is awesome!

photon.util.system.shell_notify(msg, state=False, more=None, exitcode=None, verbose=True)[source]

A pretty long wrapper for a print() function. But this print() 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() instead

Parameters:
  • 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)
  • 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 to True) whole application with given code
  • verbose

    Show message or not (see below)

    • If set to False, you can use shell_notify() for the dictionary it returns.
    • Will be overruled if exitcode is set.
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() instead

Parameters:
  • 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 (using util.system.shell_notify() with state set to True) 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’)