pyrocko.squirrel.environment

Manage separate databases and caches for different user projects.

Squirrel based applications can either use the user’s global database which lives in Pyrocko’s global cache directory (by default under '$HOME/.pyrocko/cache/squirrel') or a project specific local database which can be conveniently created in the top level directory of a user’s project under '.squirrel' or 'squirrel'. The choice of database and associated cache directory locations is referred to here as the Squirrel environment. This module provides functions to create local environments and to look for a usable environment in the hierarchy of a user’s project directory.

Functions

get_config_path(squirrel_path)	Get path of environment's configuration file, given its directory.
get_environment([path])	Get default Squirrel environment relevant for a given file system path.
get_squirrel_path([path])	Detect the Squirrel environment directory relevant for a given path.
init_environment([path])	Initialize empty Squirrel environment.

Classes

Environment(*args, **kwargs)

Configuration object providing paths to database and cache.

get_config_path(squirrel_path)

Get path of environment’s configuration file, given its directory.

Parameters:

squirrel_path (str) – Path to the Squirrel environment directory ('.squirrel' or the global cache directory).

get_squirrel_path(path=None)

Detect the Squirrel environment directory relevant for a given path.

Parameters:

path (str) – Directory path to use as starting point for the search. By default, the current working directory is used. Searches the given (or current) directory and its parents upwards for a 'squirrel' or '.squirrel' directory containing an already initialized database; falls back to the user’s global Squirrel cache directory if none is found.

Returns:

Detected environment directory path.

Return type:

str

get_environment(path=None)

Get default Squirrel environment relevant for a given file system path.

Parameters:

path – Directory path to use as starting point for detection of the Squirrel environment. By default, the current working directory is used as starting point. When searching for a usable environment the directory '.squirrel' or 'squirrel' in the current (or starting point) directory is used if it exists, otherwise the parent directories are search upwards for the existence of such a directory. If no such directory is found, the user’s global Squirrel environment, usually '$HOME/.pyrocko/cache/squirrel', is used.

Returns:

Environment object containing the detected database and cache directory paths.

init_environment(path=None)

Initialize empty Squirrel environment.

Parameters:

path – Path to the directory where the new environment’s '.squirrel' directory should be created. If set to None, the current working directory is used.

If a '.squirrel' directory already exists at the given location, SquirrelError is raised.

class Environment(*args, **kwargs)

Bases: HasPaths

Configuration object providing paths to database and cache.

♦ database_path

str (pyrocko.has_paths.Path), optional

Path to the SQLite database file holding the index.

♦ cache_path

str (pyrocko.has_paths.Path), optional

Path to the directory used for cached content, e.g. downloaded waveforms.

♦ persistent

str, optional

Name of a persistent selection to reuse, or None to use a temporary selection (see Selection).

classmethod make(squirrel_path)

Create a new environment configuration for a given directory.

Parameters:

squirrel_path (str) – Path to the Squirrel environment directory. Used as base path for database_path/cache_path.

Return type:

Environment

classmethod load(squirrel_path)

Load environment configuration from a directory’s config file.

Parameters:

squirrel_path (str) – Path to the Squirrel environment directory containing the configuration file (see get_config_path()).

Return type:

Environment

Raises:

SquirrelError – If the config file cannot be read or does not contain a valid Environment.