materials_commons.cli.functions module

class materials_commons.cli.functions.ProjectConfig(project_path)[source]

Bases: object

Facilitates reading and writing a JSON file storing local project configuration values

Project .mc/config.json file format:

{
    "remote": {
        "mcurl": <url>,
        "email": <email>
    },
    "project_id": <id>,
    "project_uuid": <uuid>,
    "experiment_id": <id>,
    "experiment_uuid": <uuid>,
    "remote_updatetime": <number>,
    "globus_upload_id": <id>,
    "globus_download_id": <id>
}

project_path

Absolute path to local project directory.

Type:: str

config_dir

Absolute path to local project configuration directory (“.mc”).

Type:: str

config_path

Absolute path to local project configuration file (“.mc/config.json”).

Type:: str

project_id

Project ID

Type:: int or None

project_uuid

Project UUID

Type:: str or None

experiment_id

Current experiment ID

Type:: int or None

experiment_uuid

Current experiment UUID

Type:: str or None

remote

Holds configuration variables (email, url, apikey) for the remote instance of Materials Commons where the project is stored.

Type:: user_config.RemoteConfig

remote_updatetime

For use with optional caching, holds the last time local cache data was updated from the remote.

Type:: number or None

globus_upload_id

ID specifying which Globus upload directory should be used for Globus uploads.

Type:: int or None

globus_download_id

ID specifying which Globus download directory should be used for Globus downloads.

Type:: int or None

Construct by reading local project configuration file if it exists

Parameters:: project_path (str) – Absolute path to local project directory. Will read <project_path>/.mc/config.json. All attributes will be None if the configuration file does not exist.

save()[source]: Save project configuration as a JSON file

to_dict()[source]: Returns the project configuration as a dict

class materials_commons.cli.functions.ProjectTable(proj_local_path)[source]

Bases: SqlTable

The ProjectTable creates a sqlite “project” table to cache some basic project data

Parameters:: proj_local_path (str) – Path to local project directory

static default_print_fmt()[source]: Returns project table print formatting parameters

select_all()[source]

Select record by id

Returns:: sqlite3.Row or None

static tablecolumns()[source]

Returns sqlite project table creating parameters

Returns:: A dict, with column name as key, and list of column creation args for value.

static tablename()[source]: Returns sqlite project table name “project”

materials_commons.cli.functions.add_remote_option(parser, help)[source]

Add the “–remote <email> <url>” cli option to an ArgumentParser

This standardizes the use of the “–remote <email> <url>” cli option which is needed in some contexts, but not others

Parameters:: parser (argparse.ArgumentParser) – The initial ArgumentParser
Returns:: argparse.ArgumentParser – The ArgumentParser, with the added option “–remote <email> <url>”.

materials_commons.cli.functions.as_is(value)[source]: Returns value without any changes. A placeholder for when a function is needed.

materials_commons.cli.functions.checksum(path)[source]: Generate MD5 checksum for the file at “path”

materials_commons.cli.functions.clone_project(remote_config, project_id, parent_dest, name=None)[source]

Clone a remote project to a local directory

Will create the local project directory “<parent_dest>/<project_name>”
Will save local project configuration “<parent_dest>/.mc/config.json” with project info

Parameters:

remote_config (user_config.RemoteConfig) – Holds configuration variables (email, url, apikey) for the remote instance of Materials Commons where the project to be cloned is stored.
project_id (int) – ID of the project to clone
parent_dest (str) – Absolute path to a local directory which will become the parent of the cloned project directory.
name (str) – Name of created project directory. Default is remote project name.

Returns:

materials_commons.api.models.Project – Object representing the cloned project

materials_commons.cli.functions.epoch_time(time_value)[source]

Attempts to convert various time representations into s since the epoch

Parameters:: time_value – A representation of time, expects UTC time.
Returns:: An float s since the epoch. Uses the following – +——————-+————————————————————+ | If this type | Then do this conversion | +——————-+————————————————————+ | str | dateutil.parser.parse(time_value).timestamp() | +——————-+————————————————————+ | float, int | time_value | +——————-+————————————————————+ | datetime.datetime | time_value.replace(tzinfo=datetime.timezone.utc).timestamp() | +——————-+————————————————————+ | dict | float(time_value[‘epoch_time’]) | +——————-+————————————————————+ | None | None | +——————-+————————————————————+ | Else | str(type(time_value)) | +——————-+————————————————————+

materials_commons.cli.functions.format_time(time_value, fmt='%Y %b %d %H:%M:%S')[source]

Attempts to put various time representations into specified format for printing

Parameters:

time_value – A representation of time, expects UTC time.
fmt (str) – Format to use for the return value.

Returns:

A string representation, in local time, using the specified format. Uses the following – +——————-+————————————————-+ | If this type | Then do this conversion | +——————-+————————————————-+ | str | dateutil.parser.parse(time_value).strftime(fmt) | +——————-+————————————————-+ | float, int | time.strftime(fmt, time.localtime(time_value)) | +——————-+————————————————-+ | datetime.datetime | time_value.strftime(fmt) | +——————-+————————————————-+ | dict | format_time(time_value[‘epoch_time’]) | +——————-+————————————————-+ | None | “-” | +——————-+————————————————-+ | Else | str(type(time_value)) | +——————-+————————————————-+

materials_commons.cli.functions.getit(obj, name, default=None)[source]: Returns the “name” attribute (or default value) whether “obj” is a dict or an object.

materials_commons.cli.functions.humanize(file_size_bytes)[source]

Get a nice string representation of file size

Parameters:: file_size_bytes (int) – File size in bytes
Returns:: str – File size as human readable string (ex: “10B”, “8K”, “5M”, “2G”, etc.)

materials_commons.cli.functions.make_file(path, text)[source]: Convenience function for writing “text” to a file at “path”.

materials_commons.cli.functions.make_local_expt(proj)[source]

Read local project configuration to construct “current experiment” object

The “current experiment” is a default experiment for putting newly created samples or processes

Parameters:: proj (materials_commons.api.models.Project) – A Project instance, including the materials_commons.cli added attribute “local_path”.
Returns:: Returns the local project’s “current experiment” (materials_commons.api.models.Experiment), or None if not set.

materials_commons.cli.functions.make_local_project(path, data=None)[source]

Read local project config file and use to construct materials_commons.api.models.Project

Checks if “path” is a path located inside a local project directory (by looking for the “.mc” directory).
Use local project configuration to:
- Construct a “remote” instance (materials_commons.api.Client)
- Call Materials Commons and construct a project instance (materials_commons.api.Project)
Add attributes to the project:
- “local_path” (str) providing the absolute path to the local project directory
- “remote” (materials_commons.api.Client) project specific client instance

Parameters:

path (str) – Path inside a local project directory
data (dict) – Optional, project data. If stored in cache this avoids an extra API call.

Notes

Caching behavior is currently disabled while updating materials_commons.cli for MC2.0. It allows setting a “fetch lock” so that data that is not cached or older than the time the lock was set will be queried from the remote, otherwise the local cache data is used.

materials_commons.cli.functions.make_local_project_client(path)[source]

Construct a client to access project data from the local project configuration

Parameters:: path (str) – Path to anywhere inside a local project directory
Returns:: materials_commons.api.Client – A client for the instance of Materials Commons that is storing the project

materials_commons.cli.functions.mkdir_if(path)[source]: Convenience function for making a directory, if it does not exist.

materials_commons.cli.functions.optional_remote(args, default_client=None)[source]

Return remote specified by cli option “–remote”, or the user’s default remote

Parameters:

args (argparse args) – The result of argparse’s “parse_args()” method. Checks for “args.remote”.
default_client (materials_commons.api.Client) –
The default client to use. If None, uses the default remote specified in the user’s configuration file:
```
`materials_commons.cli.user_config.Config().default_remote.make_client()`.
```

Returns:

materials_commons.api.Client – The appropriate client: the value specified using the “–remote <email> <url>” option, or else the user’s configured default.

materials_commons.cli.functions.optional_remote_config(args)[source]

Return remote configuration parameters specified by cli option “–remote”, or the user’s default remote

Parameters:: args (argparse.Namespace) – The result of argparse’s “parse_args()” method. Checks for “args.remote”.
Returns:: user_config.RemoteConfig – The remote configuration parameters for the appropriate client: either the value specified using the “–remote <email> <url>” option, or else the user’s configured default.

materials_commons.cli.functions.print_projects(projects, current=None)[source]

Prints a list of projects, including a ‘*’ indicating the project containing the current working directory

Parameters:

projects – A list of materials_commons.api.Project
current – A materials_commons.api.Project containing the current working directory as determined by “os.getcwd()”, or None if not in a local project directory.

materials_commons.cli.functions.print_remote_help()[source]: Print a help message for cases when no remotes are configured

materials_commons.cli.functions.print_remotes(config_remotes, show_apikey=False)[source]

Print a table with remote Materials Commons instance configuration parameters (email, url, apikey)

Parameters:

config_remotes – A dict of user_config.RemoteConfig, grouped like: “{<url>: {<email>: RemoteConfig, …}, …}”
show_apikey (bool) – If True, print apikeys also.

materials_commons.cli.functions.print_table(data, columns=[], headers=[], out=None)[source]

Print table from list of dict

Parameters:

data – list of dict, Data to print
columns – list of str, Keys of data to print, in order
headers – list of str, Header strings
out – stream, Output stream

materials_commons.cli.functions.project_exists(path)[source]: Returns True if a local project directory exists containing “path”

materials_commons.cli.functions.project_path(path)[source]: Returns the path to a local project directory if it contains “path”, else None

materials_commons.cli.functions.random_name(n=3, max_letters=6, sep='-')[source]: Generates a random name for “n” words of max “max_letters” length, joined by “sep”

materials_commons.cli.functions.read_project_config(path)[source]

Read local project configuration

Returns:: If the project configuration file (“<project>/.mc/config.json”) exists, returns a ProjectConfig instance. Else, returns None.

materials_commons.cli.functions.remove_hidden_project_files(project_path)[source]: Removes a local project’s configuration files and directory

materials_commons.cli.functions.remove_if(path)[source]: Convenience function for removing a file, if it exists.

materials_commons.cli.functions.request_confirmation(msg, force=False)[source]

Request user confirmation

Parameters:

msg (str) –
For example, the value “Are you sure you want to permanently delete these?”, will prompt user with:
```
"Are you sure you want to permanently delete these? ('Yes'/'No'): "
```
force (bool) – Proceed without user confirmation

Returns:

bool – True if confirmed or forced, False if not confirmed.

materials_commons.cli.functions.rmdir_if(path)[source]: Convenience function for removing a directory, if it exists.