Community descriptions
Envprobe implements the programs responsible for interfacing with the Variable Descriptions Knowledge Base in the community_descriptions module.
Local storage
The data downloaded from the knowledge-base is stored in a dedicated location (see envprobe.settings.get_data_directory()), separate from the user’s own configuration.
The MetaConfiguration class allows accessing the metadata of the storage.
- get_storage_configuration(read_only=True)
Returns the configuration manager for the metainformation about the local storage.
- class MetaConfiguration(configuration=None)
Represents a persisted configuration file of the local description storage.
Initialises the metadata configuration manager.
This instantiation is cheap. Accessing the underlying data is only done when a query or a setter function is called.
- Parameters
configuration (context-capable dict, optional) –
- delete_source(source)
Delete the record associated with the given source.
- get_comment_for(source)
Returns the textual comment associated with the given information source.
- set_comment_for(source, comment)
Save the textual comment associated with the given information source.
- property version
Returns the commit identifier of the data in the storage.
The individual configuration for variables can be accessed through a envprobe.settings.variable_information.VariableInformation instance, in the exact same fashion as the user’s local configuration is accessible.
- 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, using the locally installed community descriptions data as source.
- Parameters
- Returns
The configuration handler engine. Access to the underlying file is handled automatically through this instance.
- Return type
Downloader
The following program elements are used from the higher-level logic to handle downloading and unpacking the contents of the knowledge-base.
- fetch_latest_version_information()
Obtain the version of the latest downloadable knowledge base.
Note
Executing this function requires Internet connection, and will make a connection to GitHub’s API.
- Raises
URLError – Executing the request may fail due to configuration issues, bad connection, or GitHub API’s throttling of the user. Throttling is implemented for unauthenticated requests against the IP address of the machine. Read more at http://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting.
- download_latest_data(location)
Downloads the latest information to the given location.
- Parameters
location (str) – The path the downloader can use to extract the data to. This directory must exist already, and will not be cleared up by this function. This is only used temporarily.
- Returns
The handlers of the extracted knowledge source documents.
- Return type
Note
Executing this function requires Internet connection, and will make a connection to GitHub’s API.
- Raises
URLError – Executing the request may fail due to configuration issues, bad connection, or GitHub API’s throttling of the user. Throttling is implemented for unauthenticated requests against the IP address of the machine. Read more at http://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting.
- class DescriptionSource(source_file_path)
The handler class that is used to parse and understand the files of the downloaded knowledge-base.
- Parameters
source_file_path (str) – The path to the CSV database.
Note
Instantiating the object is a cheap operation. To load the data, call the
parse()method.- __getitem__(variable)
Get the information for the given variable.
- Returns
The configuration mapping of the variable as parsed from the source file. The format of the dictionary is appropriate for use with
envprobe.vartypes.envvar.EnvVarExtendedInformation.- Return type
- __iter__()
Iterate over the variables in the source.
- __len__()
The number of variables in the source.
- property comment
A textual comment about the contents of the source.
- property name
The identifier of the source.
- parse()
Execute loading of the data from the backing file.
Layout of the knowledge-base repository
The repository is hosted on GitHub and managed as a separate Git repository.
format.ver
The format of the repository is versioned internally and the current version of the data files in the commit is specified in the format.ver file.
Versions are expressed in the X.Y (major and minor version) format.
Envprobe will only accept the download if the format is supported.
- MIN_SUPPORTED_FORMAT = '1.0'
The minimum version of description releases that is supported by the current implementation.
- MAX_SUPPORTED_FORMAT = '1.0'
The maximum version of description releases that is supported by the current implementation.
Data files (something.csv)
The data itself is stored in comma-separated values (CSV) files.
(Read more about CSV files in the csv module documentation.)
CSV files allow easy editing and diffing of the files, and also easy handling during download.
The CSV file beings with a header row that defines the title of each column. Each data file identifies a conceptual “group” of variables by usage, scope, or associated context. However, the downloader merges the information from all data files together when creating the local copy.
Variable,TypeKind,Description
__META__,COMMENT,"Example datafile."
MY_VARIABLE,string,"A variable."
NAMES,comma_separated,"A list of names."