aiida.cmdline package

The command line interface of AiiDA.

class aiida.cmdline.LazyChoice(get_choices)

Bases: click.types.ParamType

This is a delegate of click’s Choice ParamType that evaluates the set of choices lazily. This is useful if the choices set requires an import that is slow. Using the vanilla click.Choice will call this on import which will slow down verdi and its autocomplete. This type will generate the choices set lazily through the choices property

__init__(get_choices)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.cmdline.params.types.choice'

__repr__() <==> repr(x)

_click_choice

Get the internal click Choice object that we delegate functionality to. Will construct it lazily if necessary.

Returns:The click Choice Return type:click.Choice

choices

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

get_metavar(param)

Returns the metavar default for this param if it provides one.

get_missing_message(param)

Optionally might return extra information about a missing parameter.

New in version 2.0.

name = 'choice'

class aiida.cmdline.IdentifierParamType(sub_classes=None)

Bases: click.types.ParamType

An extension of click.ParamType for a generic identifier parameter. In AiiDA, orm entities can often be identified by either their ID, UUID or optionally some LABEL identifier. This parameter type implements the convert method, which attempts to convert a value passed to the command for a parameter with this type, to an orm entity. The actual loading of the entity is delegated to the orm class loader. Subclasses of this parameter type should implement the orm_class_loader method to return the appropriate orm class loader, which should be a subclass of aiida.orm.utils.loaders.OrmEntityLoader for the corresponding orm class.

__abstractmethods__ = frozenset(['orm_class_loader'])

__init__(sub_classes=None)

Construct the parameter type, optionally specifying a tuple of entry points that reference classes that should be a sub class of the base orm class of the orm class loader. The classes pointed to by these entry points will be passed to the OrmEntityLoader when converting an identifier and they will restrict the query set by demanding that the class of the corresponding entity matches these sub classes.

To prevent having to load the database environment at import time, the actual loading of the entry points is deferred until the call to convert is made. This is to keep the command line autocompletion light and responsive. The entry point strings will be validated, however, to see if the correspond to known entry points.

Parameters:sub_classes – a tuple of entry point strings that can narrow the set of orm classes that values will be mapped upon. These classes have to be strict sub classes of the base orm class defined by the orm class loader

__module__ = 'aiida.cmdline.params.types.identifier'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

convert(**kwargs)

Attempt to convert the given value to an instance of the orm class using the orm class loader.

Returns:

the loaded orm entity

Raises:

• click.BadParameter – if the value is ambiguous and leads to multiple entities
• click.BadParameter – if the value cannot be mapped onto any existing instance
• RuntimeError – if the defined orm class loader is not a subclass of the OrmEntityLoader class

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.CalculationParamType(sub_classes=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying Calculation entities or its subclasses

__abstractmethods__ = frozenset([])

__module__ = 'aiida.cmdline.params.types.calculation'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

name = 'Calculation'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.CodeParamType(sub_classes=None, entry_point=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying Code entities or its subclasses

__abstractmethods__ = frozenset([])

__init__(sub_classes=None, entry_point=None)

Construct the param type

Parameters:

• sub_classes – specify a tuple of Code sub classes to narrow the query set
• entry_point – specify an optional calculation entry point that the Code’s input plugin should match

__module__ = 'aiida.cmdline.params.types.code'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

convert(value, param, ctx)

Attempt to convert the given value to an instance of the orm class using the orm class loader.

Returns:

the loaded orm entity

Raises:

• click.BadParameter – if the value is ambiguous and leads to multiple entities
• click.BadParameter – if the value cannot be mapped onto any existing instance
• RuntimeError – if the defined orm class loader is not a subclass of the OrmEntityLoader class

name = 'Code'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.ComputerParamType(sub_classes=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying Computer entities or its subclasses

__abstractmethods__ = frozenset([])

__module__ = 'aiida.cmdline.params.types.computer'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

name = 'Computer'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.ConfigOptionParamType

Bases: click.types.StringParamType

ParamType for configuration options.

__module__ = 'aiida.cmdline.params.types.config'

complete(ctx, incomplete)

Return possible completions based on an incomplete value

Returns:list of tuples of valid entry points (matching incomplete) and a description

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'config option'

class aiida.cmdline.DataParamType(sub_classes=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying Data entities or its subclasses

__abstractmethods__ = frozenset([])

__module__ = 'aiida.cmdline.params.types.data'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

name = 'Data'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.GroupParamType(create_if_not_exist=False)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying Group entities or its subclasses.

__abstractmethods__ = frozenset([])

__init__(create_if_not_exist=False)

Construct the parameter type, optionally specifying a tuple of entry points that reference classes that should be a sub class of the base orm class of the orm class loader. The classes pointed to by these entry points will be passed to the OrmEntityLoader when converting an identifier and they will restrict the query set by demanding that the class of the corresponding entity matches these sub classes.

To prevent having to load the database environment at import time, the actual loading of the entry points is deferred until the call to convert is made. This is to keep the command line autocompletion light and responsive. The entry point strings will be validated, however, to see if the correspond to known entry points.

Parameters:sub_classes – a tuple of entry point strings that can narrow the set of orm classes that values will be mapped upon. These classes have to be strict sub classes of the base orm class defined by the orm class loader

__module__ = 'aiida.cmdline.params.types.group'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

convert(**kwargs)

Attempt to convert the given value to an instance of the orm class using the orm class loader.

Returns:

the loaded orm entity

Raises:

• click.BadParameter – if the value is ambiguous and leads to multiple entities
• click.BadParameter – if the value cannot be mapped onto any existing instance
• RuntimeError – if the defined orm class loader is not a subclass of the OrmEntityLoader class

name = 'Group'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.NodeParamType(sub_classes=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying Node entities or its subclasses

__abstractmethods__ = frozenset([])

__module__ = 'aiida.cmdline.params.types.node'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

name = 'Node'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.MpirunCommandParamType

Bases: click.types.StringParamType

Custom click param type for mpirun-command

Note

requires also a scheduler to be provided, and the scheduler must be called first!

Validate that the provided ‘mpirun’ command only contains replacement fields (e.g. {tot_num_mpiprocs}) that are known.

Return a list of arguments (by using ‘value.strip().split(” “) on the input string)

__module__ = 'aiida.cmdline.params.types.computer'

__repr__() <==> repr(x)

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'mpiruncommandstring'

class aiida.cmdline.MultipleValueParamType(param_type)

Bases: click.types.ParamType

An extension of click.ParamType that can parse multiple values for a given ParamType

__init__(param_type)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.cmdline.params.types.multiple'

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

get_metavar(param)

Returns the metavar default for this param if it provides one.

class aiida.cmdline.NonEmptyStringParamType

Bases: click.types.StringParamType

Parameter that cannot be an an empty string.

__module__ = 'aiida.cmdline.params.types.nonemptystring'

__repr__() <==> repr(x)

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'nonemptystring'

class aiida.cmdline.PluginParamType(group=None, load=False, *args, **kwargs)

Bases: click.types.ParamType

AiiDA Plugin name parameter type.

Parameters:

• group – string or tuple of strings, where each is a valid entry point group. Adding the aiida. prefix is optional. If it is not detected it will be prepended internally.
• load – when set to True, convert will not return the entry point, but the loaded entry point

Usage:

click.option(... type=PluginParamType(group='aiida.calculations')

or:

click.option(... type=PluginParamType(group=('calculations', 'data'))

__init__(group=None, load=False, *args, **kwargs)

Validate that group is either a string or a tuple of valid entry point groups, or if it is not specified use the tuple of all recognized entry point groups.

__module__ = 'aiida.cmdline.params.types.plugin'

_init_entry_points()

Populate entry point information that will be used later on. This should only be called once in the constructor after setting self.groups because the groups should not be changed after instantiation

complete(ctx, incomplete)

Return possible completions based on an incomplete value

Returns:list of tuples of valid entry points (matching incomplete) and a description

convert(**kwargs)

Convert the string value to an entry point instance, if the value can be successfully parsed into an actual entry point. Will raise click.BadParameter if validation fails.

get_entry_point_from_string(entry_point_string)

Validate a given entry point string, which means that it should have a valid entry point string format and that the entry point unambiguously corresponds to an entry point in the groups configured for this instance of PluginParameterType.

Returns:the entry point if valid Raises:ValueError if the entry point string is invalid

get_missing_message(param)

Optionally might return extra information about a missing parameter.

New in version 2.0.

get_possibilities(incomplete='')

Return a list of plugins starting with incomplete

get_valid_arguments()

Return a list of all available plugins for the groups configured for this PluginParamType instance. If the entry point names are not unique, because there are multiple groups that contain an entry point that has an identical name, we need to prefix the names with the full group name

Returns:list of valid entry point strings

groups

has_potential_ambiguity

Returns whether the set of supported entry point groups can lead to ambiguity when only an entry point name is specified. This will happen if one ore more groups share an entry point with a common name

name = 'plugin'

class aiida.cmdline.AbsolutePathParamType(exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False, allow_dash=False, path_type=None)

Bases: click.types.Path

The ParamType for identifying absolute Paths (derived from click.Path).

__module__ = 'aiida.cmdline.params.types.path'

__repr__() <==> repr(x)

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'AbsolutePath'

class aiida.cmdline.ShebangParamType

Bases: click.types.StringParamType

Custom click param type for shebang line

__module__ = 'aiida.cmdline.params.types.computer'

__repr__() <==> repr(x)

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'shebangline'

class aiida.cmdline.UserParamType(create=False)

Bases: click.types.ParamType

The user parameter type for click. Can get or create a user.

__init__(create=False)

Parameters:create – If the user does not exist, create a new instance (unstored).

__module__ = 'aiida.cmdline.params.types.user'

complete(**kwargs)

Return possible completions based on an incomplete value

Returns:list of tuples of valid entry points (matching incomplete) and a description

convert(**kwargs)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'user'

class aiida.cmdline.TestModuleParamType

Bases: click.types.ParamType

Parameter type to represent a unittest module.

__module__ = 'aiida.cmdline.params.types.test_module'

complete(ctx, incomplete)

Return possible completions based on an incomplete value

Returns:list of tuples of valid entry points (matching incomplete) and a description

static get_test_modules()

Returns a list of known test modules.

name = 'test module'

class aiida.cmdline.ProfileParamType

Bases: click.types.ParamType

The profile parameter type for click.

__module__ = 'aiida.cmdline.params.types.profile'

complete(ctx, incomplete)

Return possible completions based on an incomplete value

Returns:list of tuples of valid entry points (matching incomplete) and a description

convert(value, param, ctx)

Attempt to match the given value to a valid profile.

name = 'profile'

class aiida.cmdline.WorkflowParamType(sub_classes=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying WorkflowNode entities or its subclasses

__abstractmethods__ = frozenset([])

__module__ = 'aiida.cmdline.params.types.workflow'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

name = 'WorkflowNode'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

class aiida.cmdline.ProcessParamType(sub_classes=None)

Bases: aiida.cmdline.params.types.identifier.IdentifierParamType

The ParamType for identifying ProcessNode entities or its subclasses

__abstractmethods__ = frozenset([])

__module__ = 'aiida.cmdline.params.types.process'

_abc_cache = <_weakrefset.WeakSet object>

_abc_negative_cache = <_weakrefset.WeakSet object>

_abc_negative_cache_version = 39

_abc_registry = <_weakrefset.WeakSet object>

name = 'Process'

orm_class_loader

Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed to be used to load the entity for a given identifier

Returns:the orm entity loader class for this ParamType

aiida.cmdline.with_dbenv(*load_dbenv_args, **load_dbenv_kwargs)

Function decorator that will load the database environment only when the function is called.

aiida.cmdline.dbenv(*args, **kwds)

Loads the dbenv for a specific region of code, does not unload afterwards

Only use when it makes it possible to avoid loading the dbenv for certain code paths

Good Example:

# do this
@click.command()
@click.option('--with-db', is_flag=True)
def profile_info(with_db):
    # read the config file
    click.echo(profile_config)

    # load the db only if necessary
    if with_db:
        with dbenv():
            # gather db statistics for the profile
            click.echo(db_statistics)

This will run very fast without the –with-db flag and slow only if database info is requested

Do not use if you will end up loading the dbenv anyway

Bad Example:

# don't do this
def my_function():
    with dbenv():
        # read from db

    # do db unrelated stuff

aiida.cmdline.only_if_daemon_running(echo_function=<function echo_critical>, message=None)

Function decorator for CLI command to print critical error and exit automatically when daemon is not running.

The error printing and exit behavior can be controlled with the decorator keyword arguments. The default message that is printed can be overridden as well as the echo function that is to be used. By default it uses the aiida.cmdline.utils.echo.echo_critical function which automatically aborts the command. The function can be substituted by for example aiida.cmdline.utils.echo.echo_warning to instead print just a warning and continue.

Example:

@only_if_daemon_running(echo_function=echo.echo_warning, message='beware that the daemon is not running')
def create_my_calculation():
    pass

Parameters:

• echo_function – echo function to issue the message, should be from aiida.cmdline.utils.echo
• message – optional message to override the default message

aiida.cmdline.echo(message, bold=False, nl=True, err=False)

Print a normal message through click’s echo function to stdout

Parameters:

• message – the string representing the message to print
• bold – whether to print the message in bold
• nl – whether to print a newline at the end of the message
• err – whether to print to stderr

aiida.cmdline.echo_info(message, bold=False, nl=True, err=False)

Print an info message through click’s echo function to stdout, prefixed with ‘Info:’

Parameters:

• message – the string representing the message to print
• bold – whether to print the message in bold
• nl – whether to print a newline at the end of the message
• err – whether to print to stderr

aiida.cmdline.echo_success(message, bold=False, nl=True, err=False)

Print a success message through click’s echo function to stdout, prefixed with ‘Success:’

Parameters:

• message – the string representing the message to print
• bold – whether to print the message in bold include a newline character
• nl – whether to print a newline at the end of the message
• err – whether to print to stderr

aiida.cmdline.echo_warning(message, bold=False, nl=True, err=False)

Print a warning message through click’s echo function to stdout, prefixed with ‘Warning:’

Parameters:

• message – the string representing the message to print
• bold – whether to print the message in bold
• nl – whether to print a newline at the end of the message
• err – whether to print to stderr

aiida.cmdline.echo_error(message, bold=False, nl=True, err=True)

Print an error message through click’s echo function to stdout, prefixed with ‘Error:’

Parameters:

• message – the string representing the message to print
• bold – whether to print the message in bold
• nl – whether to print a newline at the end of the message
• err – whether to print to stderr

aiida.cmdline.echo_critical(message, bold=False, nl=True, err=True)

Print an error message through click’s echo function to stdout, prefixed with ‘Critical:’ and then calls sys.exit with the given exit_status.

This should be used to print messages for errors that cannot be recovered from and so the script should be directly terminated with a non-zero exit status to indicate that the command failed

Parameters:

• message – the string representing the message to print
• bold – whether to print the message in bold
• nl – whether to print a newline at the end of the message
• err – whether to print to stderr

aiida.cmdline.echo_dictionary(dictionary, fmt='json+date')

Print the given dictionary to stdout in the given format

Parameters:

• dictionary – the dictionary
• fmt – the format to use for printing, valid options: [‘json+data’]

Subpackages

• aiida.cmdline.commands package
  • Subpackages
    • aiida.cmdline.commands.cmd_data package
      • Submodules
  • Submodules
• aiida.cmdline.params package
  • Subpackages
    • aiida.cmdline.params.arguments package
      • Submodules
    • aiida.cmdline.params.options package
      • Subpackages
        • aiida.cmdline.params.options.commands package
          • Submodules
      • Submodules
    • aiida.cmdline.params.types package
      • Submodules
• aiida.cmdline.utils package
  • Subpackages
    • aiida.cmdline.utils.query package
      • Submodules
  • Submodules