LocalPath

class biskit.LocalPath(path=None, checkEnv=1, minLen=3, maxSub=1, absolute=1, resolveLinks=0, **vars)[source]

Bases: object

Encapsulate a file name that might look differently in different environments depending on environment settings. The file name has an absolute (original) variant but parts of it can be looked up from environment or Biskit settings variables (if the original path doesn’t exist in the current environment).

Creating a LocalPath:

Creating a LocalPath is simple. By default, LocalPath takes a normal filename and browses the local biskit.settings and run-time environment for variables that can replace part of that path.

Variable values must be at least 3 char long and contain at least one ‘/’ in order to avoid substitution of single letters or ‘/a’ etc. $PYTHONPATH, $PATH and $PWD are ignored.

Variables from biskit.settings (thus also .biskit/settings.cfg) have priority over normal environment variables both during the construction of LocalPath instances and during the reconstruction of a locally valid path.

Using a LocalPath:

LocalPath tries behaving like the simple absolute path string when it comes to slicing etc:

l = LocalPath( '{/home/raik|$USER}/data/x.txt' )
l[:] == '/home/raik/data/x.txt' == l.local()
l[-4:] == '.txt'
str( l ) == l.local()

l.formatted() == '{/home/raik|$USER}/data/x.txt'
@todo: input: allow multiple or overlapping substitutions
output: only substitute what is necessary until path exists

Methods Overview

__init__ Create a new environment-dependent path from either a list of fragments and their substitution variable names or from a path or from a formatted string (not implemented).
absfile
dump Try to pickle an object to the currently valid path.
exists Check if path exists
formatted Get a string representation that describes the original path and all possible substitutions by environment variables.
get_local Return a valid, absolute path.
get_substitution_dict
get_substitution_pairs Get all variable/value pairs that are available for path substitutions.
load Try to unpickle an object from the currently valid path.
local Cached variant of get_local.
original Get the original path (also non-absolute) that is used if the file exists or if there are no environment variables for any of the substitutions.
set Assign a new file name.
set_fragments Set new path from list of path fragments and their possible environment variable substitutions.
set_path Set a new path and try to identify settings/environment variables that could substitute parts of it.
set_string Set a new path and its substitutable parts from a formatted string.

Attributes Overview

ex_fragment
ex_minpath
exclude_vars

LocalPath Method & Attribute Details

__init__(path=None, checkEnv=1, minLen=3, maxSub=1, absolute=1, resolveLinks=0, **vars)[source]

Create a new environment-dependent path from either a list of fragments and their substitution variable names or from a path or from a formatted string (not implemented). A path will be analyzed to substitute as big chunks as possible by environment variables. ~ and ../../ will be expanded both in the given path and in the environment variables.

Parameters:
  • path ([ (str, str) ] OR str) – path(s)
  • checkEnv (1|0) – look for substitution values among environment variables (default 1)
  • absolute (1|0) – normalize file name [1]
  • resolveLinks (1|0) – resolve symbolic links [0]
  • maxSub (int) – maximal number of substitutions [1]
  • vars (param=value) – additional param=value pairs with suggested substitutors
get_local(existing=0)[source]

Return a valid, absolute path. Either the existing original or with all substitutions for which environment variables exist. This function is time consuming (absfile - os.realpath is the culprit).

Parameters:existing (0|1) – don’t return a non-existing path
Returns:valid absolute path in current environment
Return type:str
Raises:LocalPathError – if existing==1 and no existing path can be constructed via environment variables
local(existing=0, force=1)[source]

Cached variant of get_local. Return a valid, absolute path. Either the existing original or with all substitutions for which environment variables exist. This function is time consuming (absfile - os.realpath is the culprit).

Parameters:
  • existing (0|1) – don’t return a non-existing path [0]
  • force (0|1) – override cached value [0]
Returns:

valid absolute (not necessarily existing) path in current environment

Return type:

str

Raises:

LocalPathError – if existing==1 and no existing path can be constructed via environment variables

formatted()[source]

Get a string representation that describes the original path and all possible substitutions by environment variables.

Returns:formated path e.g. C{ ‘{/home/raik|$USER}/data/x.txt’ }
Return type:str
original()[source]

Get the original path (also non-absolute) that is used if the file exists or if there are no environment variables for any of the substitutions.

Returns:original path
Return type:str
set(v, checkEnv=1, minLen=3, maxSub=1, absolute=1, resolveLinks=0, **vars)[source]

Assign a new file name. checkEnv, minLen, resolve*, maxSub are only considered for path name input.

Parameters:
  • v ([ (str,str) ] OR str) – fragment tuples or path or custom-formatted string
  • checkEnv (0|1) – look for possible substitutions in environment [1] (iggnored if v is already formatted like ‘{/x/y|$xy}/z.txt’ )
  • minLen (int) – mininal length of environment variables to consider [3]
  • absolute (1|0) – normalize file name [1]
  • resolveLinks (1|0) – resolve symbolic links [0]
  • maxSub (int) – maximal number of substitutions [1]
  • vars (param=value) – additional param=value pairs with suggested substitutors
set_fragments(*fragments)[source]

Set new path from list of path fragments and their possible environment variable substitutions. Fragments that can not be substituted are given as (str, None).

Parameters:fragments ([ (str, str), (str, None), . ]) – list of fragment tuples
set_string(s)[source]

Set a new path and its substitutable parts from a formatted string.

Parameters:s (str) – formatted like {/home/raik|$USER}/data/test.txt
Raises:PathError – formatted input is not yet implemented
set_path(fname, minLen=3, absolute=1, resolveLinks=0, maxSub=1, **vars)[source]

Set a new path and try to identify settings/environment variables that could substitute parts of it.

Parameters:
  • fname (str) – relative or absolute file name
  • minLen (int) – minimal length of string o to be counted as path
  • absolute (1|0) – normalize file name [1]
  • resolveLinks (1|0) – resolve symbolic links [0]
  • maxSub (int) – maximal number of substitutions [1]
  • vars (param=value) – additional param=value pairs with suggested substitutors
exists()[source]

Check if path exists

Returns:1 if if current path exists
Return type:1|0
load()[source]

Try to unpickle an object from the currently valid path.

Returns:unpickled object
Return type:any
Raises:IOError – if file can not be found
dump(o)[source]

Try to pickle an object to the currently valid path.

Returns:the absolute path to which o was pickled
Return type:str
get_substitution_pairs(minLen=3, vars={}, exclude=[])[source]

Get all variable/value pairs that are available for path substitutions.

Parameters:
  • minLen (int) – minimal path length [3]
  • vars (param=value) – additional param=value pairs to consider
Returns:

[ (variable name, value) ] sorted by priority (mostly length of value)

Return type:

[ (str,str) ]