aiida.cmdline package¶
-
aiida.cmdline.
_print_dictionary_json_date
(dictionary)[source]¶ Print a dictionary using the json format (with indent=2), and converting dates to strings.
-
aiida.cmdline.
delayed_load_node
(*args, **kwargs)[source]¶ Call the aiida.orm.load_node, but import the module only at the first execution. This is needed in the command line, because an import would “freeze” the imported modules to the BACKEND currently set (and when ‘verdi’ starts to run, this has not been fixed yet).
Note: either import load_node AFTER the load_dbenv call, inside each function, or if you want to import it only once for convenience reasons, import this function:
from aiida.cmdline import delayed_load_node as load_node
-
aiida.cmdline.
delayed_load_workflow
(*args, **kwargs)[source]¶ Same as aiida.cmdline.delayed_load_node. This method is needed in the command line in order not to “freeze” what is imported to a specific backend.
-
aiida.cmdline.
pass_to_django_manage
(argv, profile=None)[source]¶ Call the corresponding django manage.py command
-
aiida.cmdline.
wait_for_confirmation
(valid_positive=('Y', 'y'), valid_negative=('N', 'n'), print_to_stderr=True, catch_ctrl_c=True)[source]¶ Wait for confirmation, until a valid confirmation is given. If the confirmation is not valid, keep asking.
Parameters: - valid_positive – a list of strings with all possible valid positive confirmations.
- valid_negative – a list of strings with all possible valid negative confirmations.
- print_to_stderr – If True, print messages to stderr, otherwise to stdout
- catch_ctrl_c – If True, a CTRL+C command is catched and interpreted as a negative response. If False, CTRL+C is not catched.
Returns: True if the reply was positive, False if it was negative.
Submodules¶
-
class
aiida.cmdline.baseclass.
VerdiCommand
[source]¶ Bases:
object
This command has no documentation yet.
-
__dict__
= dict_proxy({'_abstract': True, 'get_full_command_name': <function get_full_command_name>, '__module__': 'aiida.cmdline.baseclass', '__metaclass__': <class 'aiida.cmdline.baseclass.__metaclass__'>, 'complete': <function complete>, 'get_command_name': <classmethod object>, '_custom_command_name': None, '__dict__': <attribute '__dict__' of 'VerdiCommand' objects>, 'run': <function run>, '__weakref__': <attribute '__weakref__' of 'VerdiCommand' objects>, '__doc__': '\n This command has no documentation yet.\n '})¶
-
class
__metaclass__
[source]¶ Bases:
type
Some python black magic to set correctly the logger also in subclasses.
-
__module__
= 'aiida.cmdline.baseclass'¶
-
-
__module__
= 'aiida.cmdline.baseclass'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
_abstract
= True¶
-
_custom_command_name
= None¶
-
complete
(subargs_idx, subargs)[source]¶ Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.
Parameters: - subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
- subargs – a list of subarguments to this command
-
classmethod
get_command_name
()[source]¶ Return the name of the verdi command associated to this class. By default, the lower-case version of the class name.
-
-
class
aiida.cmdline.baseclass.
VerdiCommandRouter
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
-
__module__
= 'aiida.cmdline.baseclass'¶
-
_abstract
= True¶
-
complete
(subargs_idx, subargs)[source]¶ Relay tab-completion requests to subcommand complete functions.
Click-implemented commands (filtered by isinstance check) pose a special case. Here we use aiida.cmdline.commands.click_subcmd_complete to create a completion function on the fly, leveraging click functionality. Since VerdiCommands with click subcommands must actually rout to the root (aiida.cmdline.commands.verdi) for each subcommand, we have only access to the root as a python object through routed_subcommands, Not to the active subcommand. This means we must follow the chain up through cli parameters. Since this function is only passed subargs, we need to use sys.argv.
sys.argv in this case follows the signature of
verdi completion
:verdi completion <num_subargs> verdi [<subgroup>, ...] <subcommand> ([<subcmd param>, ...] | '')
Therefore we can disregard the first four and the last element of argv and loop through sys.argv[4:len(sys.argv)-1], for each determine wether it’s a subcommand, if so, retrieve it’s python object until we find the last subcommand, for which we then build the completion function. We can safely disregard the last one, because it is never a (complete) subcommand and it will be passed to the completion function we build in any case (as part of
subargs
).
-
routed_subcommands
= {}¶
-
-
class
aiida.cmdline.baseclass.
VerdiCommandWithSubcommands
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Used for commands with subcommands. Just define, in the __init__, the self.valid_subcommands dictionary, in the format:
self.valid_subcommands = { 'uploadfamily': (self.uploadfamily, self.complete_auto), 'listfamilies': (self.listfamilies, self.complete_none), }
where the key is the subcommand name to give on the command line, and the value is a tuple of length 2, the first is the function to call on execution, the second is the function to call on complete.
This class already defined the complete_auto and complete_none commands, that respectively call the default bash completion for filenames/folders, or do not give any completion suggestion. Other functions can of course be defined.
Todo
Improve the docstrings for commands with subcommands.
-
__module__
= 'aiida.cmdline.baseclass'¶
-
_abstract
= True¶
-
complete
(subargs_idx, subargs)[source]¶ Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.
Parameters: - subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
- subargs – a list of subarguments to this command
-
get_full_command_name
(*args, **kwargs)[source]¶ Return the current command name. Also tries to get the subcommand name.
Also tries to see if the caller function was one specific submethod.
Parameters: with_exec_name – if True, return the full string, including the executable name (‘verdi’). If False, omit it.
-
valid_subcommands
= {}¶
-
Load the dbenv lazily, especially useful in commandline commands
Always avoids trying to load the dbenv twice. When it has to be loaded, a spinner ASCII widget is displayed.
- Provides:
- with_dbenv, a decorator to frontload the dbenv for functions
- dbenv, a contextmanager to load the dbenv only if a specific
- code branch gets visited and possibly avoiding the overhead if not
-
aiida.cmdline.dbenv_lazyloading.
dbenv
(*args, **kwds)[source]¶ 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.dbenv_lazyloading.
load_dbenv_if_not_loaded
(**kwargs)[source]¶ load dbenv if necessary, run spinner meanwhile to show command hasn’t crashed
-
aiida.cmdline.dbenv_lazyloading.
with_dbenv
(function)[source]¶ Function decorator that loads the dbenv if necessary before running the function
Example:
@with_dbenv def create_my_calculation(): from aiida.orm import CalculationFactory # note the local import my_calc = CalculationFactory('mycalc.mycalc')
Command line commands for the main executable ‘verdi’ of aiida
If you want to define a new command line parameter, just define a new class inheriting from VerdiCommand, and define a run(self,*args) method accepting a variable-length number of parameters args (the command-line parameters), which will be invoked when this executable is called as verdi NAME
Don’t forget to add the docstring to the class: the first line will be the short description, the following ones the long description.
-
class
aiida.cmdline.verdilib.
Completion
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Manage bash completion
Return a list of available commands, separated by spaces. Calls the correct function of the command if the TAB has been pressed after the first command.
Returning without printing will use the default bash completion.
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
-
class
aiida.cmdline.verdilib.
CompletionCommand
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Return the bash completion function to put in ~/.bashrc
This command prints on screen the function to be inserted in your .bashrc command. You can copy and paste the output, or simply add eval “verdi completioncommand” to your .bashrc, AFTER having added the aiida/bin directory to the path.
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
complete
(subargs_idx, subargs)[source]¶ Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.
Parameters: - subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
- subargs – a list of subarguments to this command
-
run
(*args)[source]¶ I put the documentation here, and I don’t print it, so we don’t clutter too much the .bashrc.
- “${THE_WORDS[@]}” (with the @) puts each element as a different parameter; note that the variable expansion etc. is performed
- I add a ‘x’ at the end and then remove it; in this way, $( ) will not remove trailing spaces
- If the completion command did not print anything, we use the default bash completion for filenames
- If instead the code prints something empty, thanks to the workaround above $OUTPUT is not empty, so we do go the the ‘else’ case and then, no substitution is suggested.
-
-
class
aiida.cmdline.verdilib.
Help
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Describe a specific command
Pass a further argument to get a description of a given command.
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
complete
(subargs_idx, subargs)[source]¶ Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.
Parameters: - subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
- subargs – a list of subarguments to this command
-
-
class
aiida.cmdline.verdilib.
Install
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Install/setup aiida for the current user
This command creates the ~/.aiida folder in the home directory of the user, interactively asks for the database settings and the repository location, does a setup of the daemon and runs a migrate command to create/setup the database.
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
-
class
aiida.cmdline.verdilib.
ListParams
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
List available commands
List available commands and their short description. For the long description, use the ‘help’ command.
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
-
exception
aiida.cmdline.verdilib.
ProfileParsingException
(*args, **kwargs)[source]¶ Bases:
aiida.common.exceptions.AiidaException
Exception raised when parsing the profile command line option, if only -p is provided, and no profile is specified
-
__module__
= 'aiida.cmdline.verdilib'¶
-
-
class
aiida.cmdline.verdilib.
Quicksetup
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Quick setup for the most common usecase (1 user, 1 machine).
Creates a database user ‘aiida_qs_<login-name>’ with random password (if it doesn’t exist). Creates a database ‘<profile>_<username>’ (if it exists, prompts user to use or change the name).
-
BACKEND_DJANGO
= 'django'¶
-
BACKEND_SQLA
= 'sqlalchemy'¶
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
-
class
aiida.cmdline.verdilib.
Run
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Execute an AiiDA script
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
-
class
aiida.cmdline.verdilib.
Setup
[source]¶ Bases:
aiida.cmdline.baseclass.VerdiCommand
Setup aiida for the current user
This command creates the ~/.aiida folder in the home directory of the user, interactively asks for the database settings and the repository location, does a setup of the daemon and runs a migrate command to create/setup the database.
-
__module__
= 'aiida.cmdline.verdilib'¶
-
_abstract
= False¶
-
-
aiida.cmdline.verdilib.
_check_db_name
(dbname, postgres)[source]¶ looks up if a database with the name exists, prompts for using or creating a differently named one
-
aiida.cmdline.verdilib.
exec_from_cmdline
(argv)[source]¶ The main function to be called. Pass as parameter the sys.argv.
-
aiida.cmdline.verdilib.
get_command_suggestion
(command)[source]¶ A function that prints on stderr a list of similar commands
-
aiida.cmdline.verdilib.
get_listparams
()[source]¶ Return a string with the list of parameters, to be printed
The advantage of this function is that the calling routine can choose to print it on stdout or stderr, depending on the needs.
-
aiida.cmdline.verdilib.
parse_profile
(argv, merge_equal=False)[source]¶ Parse the argv to see if a profile has been specified, return it with the command position shift (index where the commands start)
Parameters: merge_equal – if True, merge things like (‘verdi’, ‘–profile’, ‘=’, ‘x’, ‘y’) to (‘verdi’, ‘–profile=x’, ‘y’) but then return the correct index for the original array. Raises: ProfileParsingException – if there is only ‘verdi’ specified, or if only ‘verdi -p’ (in these cases, one has respectively exception.minus_p_provided equal to False or True)
-
aiida.cmdline.verdilib.
setup
(profile, only_config, non_interactive=False, **kwargs)[source]¶ setup an aiida profile and aiida user (and the aiida default user).
Parameters: - profile – Profile name
- only_config – do not create a new user
- non_interactive – do not prompt for configuration values, fail if not all values are given as kwargs.
- backend – one of ‘django’, ‘sqlalchemy’
- email – valid email address for the user
- db_host – hostname for the database
- db_port – port to connect to the database
- db_user – name of the db user
- db_pass – password of the db user