Implementation reference

Envprobe is implemented as a single Python package, named envprobe.

Warning

While we strive to make the code as modular and easily extensible as possible, at the core, Envprobe is a single program that is offered whole. The core functions that people use Envprobe for are not fully available if the Python package is used as a library, as some of the business logic is part of the command implementations; and as such, the below documentation is geared and intended more for people who would like to contribute to the tool, rather than people who would import it as a library.

• Shell interface
  • Dynamic loading
    • Registering implementations
• Environment variable types
  • Implemented types
    • envprobe.vartypes.string.String
    • envprobe.vartypes.numeric.Numeric
    • envprobe.vartypes.array.Array
    • envprobe.vartypes.colon_separated.ColonSeparatedArray
    • envprobe.vartypes.semi_separated.SemicolonSeparatedArray
    • envprobe.vartypes.path.Path
  • Dynamic loading
    • Registering implementations
• Environment management
  • Difference of environments
  • Type heuristics
    • Available heuristics
• Handling user configuration
  • Snapshot configuration
  • Storing additional information about variables
  • Tracking variables
  • Abstract configuration files
• Community descriptions
  • Local storage
  • Downloader
  • Layout of the knowledge-base repository
    • format.ver
    • Data files (something.csv)

Miscellaneous functions

The envprobe.library module contains some miscellaneous functions that are used to tie the creation of the global objects accessing the environment and the user’s state in a meaningful way.

get_shell_and_env_always(env_dict=None, vartype_pipeline=None)

Return an environment.Environment and shell.Shell, no matter what.

Parameters

• env_dict (dict, optional) – The raw mapping of environment variables to their values, as in os.environ.

• vartype_pipeline (envprobe.environment.HeuristicStack, optional) – The type resolution heuristics pipeline to use. If not specified, the environment.default_heuristic will be used.

Returns

• shell (.shell.Shell) – The shell which use can be deduced from the current environment (by calling shell.get_current_shell()). If none such can be deduced, a shell.FakeShell is returned, which is a valid shell.Shell subclass that tells the client code it is not capable of anything.

• env (.environment.Environment) – The environment associated with the current context and the instantiated Shell.

get_snapshot(snapshot_name, read_only=True)

Creates the snapshot instance for the snapshot of the given name.

Parameters

• snapshot_name (str) – The name of the snapshot to load or create.

• read_only (bool) – If True, the file will be opened read-only and not saved at exit.

Returns

The snapshot manager object. Access to the underlying file is handled automatically through this instance.

Return type

settings.snapshot.Snapshot

get_variable_information_manager(variable_name, read_only=True)

Creates the extended information attribute manager for environment variables based on the requested variable’s name.

Parameters

• varable_name (str) – The name of the variable to configure.

• read_only (bool) – If True, the associated file will be opened read-only and not saved at exit.

Returns

The configuration handler engine. Access to the underlying file is handled automatically through this instance.

Return type

settings.variable_information.VariableInformation

get_variable_tracking(shell=None)

Creates a read-only tracking manager for the standard global and local configuration files.

Parameters

shell (shell.Shell, optional) – The shell which is used in the current environment, used to retrieve the local configuration directory.

Returns

The tracking handler engine. The configuration files are opened read-only.

Return type

settings.variable_tracking.VariableTracking