LocalPath — biskit 3.0.0a1 documentation

# LocalPath

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

  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)

    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)

    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)

    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`()

    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`()

    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)

    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)

    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)

    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)

    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`()

    Check if path exists

    Returns: | 1 if if current path exists
    Return type: | 1|0

  `load`()

    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)

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

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