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
-
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) ]