ramble.cmd package

exception ramble.cmd.CommandNameError(name)

Bases: RambleError

Exception class thrown for impermissible command names

exception ramble.cmd.PythonNameError(name)

Bases: RambleError

Exception class thrown for impermissible python names

ramble.cmd.all_commands()

Get a sorted list of all ramble commands.

This will list the lib/ramble/ramble/cmd directory and find the commands there to construct the list. It does not actually import the python files – just gets the names.

ramble.cmd.cmd_name(python_name)

Convert module name (with _) to command name (with -).

ramble.cmd.find_workspace(args)

Find active workspace from args or environment variable.

Check for a workspace in this order:

1. via ramble -w WRKSPC or ramble -D DIR (arguments)

2. via a path in the ramble.workspace.RAMBLE_WORKSPACE_VAR environment variable.

If a workspace is found, read it in. If not, return None.

Parameters:

args (argparse.Namespace) – argparse namespace with command arguments

Returns:

a found workspace, or None

Return type:

(ramble.workspace.Workspace)

ramble.cmd.find_workspace_path(args)

Find path to active workspace from args or environment variable.

Check for a workspace in this order:

1. via ramble -w WRKSPC or ramble -D DIR (arguments)

2. via a path in the ramble.workspace.RAMBLE_WORKSPACE_VAR environment variable.

If a workspace is found, return it’s path. If not, return None.

Parameters:

args (argparse.Namespace) – argparse namespace with command arguments

Returns:

Path to workspace root, or None

Return type:

(str)

ramble.cmd.get_command(cmd_name)

Imports the command function associated with cmd_name.

The function’s name is derived from cmd_name using python_name().

Parameters:

cmd_name (str) – name of the command (contains -, not _).

ramble.cmd.get_module(cmd_name)

Imports the module for a particular command name and returns it.

Parameters:

cmd_name (str) – name of the command for which to get a module (contains -, not _).

ramble.cmd.python_name(cmd_name)

Convert - to _ in command name, to make a valid identifier.

ramble.cmd.remove_options(parser, *options)

Remove some options from a parser.

ramble.cmd.require_active_workspace(cmd_name, dry_run: bool = False)

Used by commands to get the active workspace

If a workspace is not found, print an error message that says the calling command needs an active workspace.

Parameters:

• cmd_name (str) – name of calling command

• dry_run (bool) – whether this is a dry run

Returns:

the active workspace

Return type:

(ramble.workspace.Workspace)

ramble.cmd.require_cmd_name(cname)

Require that the provided name is a valid command name (per cmd_name()). Useful for checking parameters for function prerequisites.

ramble.cmd.require_python_name(pname)

Require that the provided name is a valid python name (per python_name()). Useful for checking parameters for function prerequisites.

Subpackages

• ramble.cmd.common package
  • shell_init_instructions()
  • Submodules
  • ramble.cmd.common.arguments module
    • add_common_arguments()
    • allows_unknown_args()
    • validate_unknown_args()
  • ramble.cmd.common.info module
    • all_object_attributes()
    • print_all_attributes()
    • print_attribute_header()
    • print_info()
    • print_object_header()
    • print_object_overview()
    • print_single_attribute()
    • setup_info_parser()
    • supported_formats
      • supported_formats.lists
      • supported_formats.text
  • ramble.cmd.common.list module
    • formatter()
    • html()
    • name_only()
    • perform_list()
    • rows_for_ncols()
    • setup_list_parser()
    • version_json()

Submodules

ramble.cmd.attributes module

ramble.cmd.attributes.attributes(parser, args)

ramble.cmd.attributes.attributes_to_objects(users=None, attr_name='maintainers', object_type=ObjectTypes.applications)

ramble.cmd.attributes.defined_objects(attr_name='maintainers', object_type=ObjectTypes.applications)

ramble.cmd.attributes.objects_to_attributes(object_names=None, attr_name='maintainers', object_type=ObjectTypes.applications)

ramble.cmd.attributes.setup_parser(subparser)

ramble.cmd.attributes.union_values(dictionary)

Given a dictionary with values that are Collections, return their union.

Parameters:

dictionary (dict) – dictionary whose values are all collections.

Returns:

the union of all collections in the dictionary’s values.

Return type:

(set)

ramble.cmd.clean module

class ramble.cmd.clean.AllClean(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: Action

Activates flags -d -m and -p simultaneously

ramble.cmd.clean.clean(parser, args)

ramble.cmd.clean.remove_python_caches()

ramble.cmd.clean.remove_reports_files()

ramble.cmd.clean.setup_parser(subparser)

ramble.cmd.commands module

class ramble.cmd.commands.BashCompletionWriter(prog, out=None, aliases=False)

Bases: ArgparseCompletionWriter

Write argparse output as bash programmable tab completion.

body(positionals, optionals, subcommands)

Returns the body of the function.

Parameters:

• positionals (list) – list of positional arguments

• optionals (list) – list of optional arguments

• subcommands (list) – list of subcommand parsers

Returns:

the function body

Return type:

str

optionals(optionals)

Returns the syntax for reporting optional flags.

Parameters:

optionals (list) – list of optional arguments

Returns:

the syntax for optional flags

Return type:

str

positionals(positionals)

Returns the syntax for reporting positional arguments.

Parameters:

positionals (list) – list of positional arguments

Returns:

the syntax for positional arguments

Return type:

str

subcommands(subcommands)

Returns the syntax for reporting subcommands.

Parameters:

subcommands (list) – list of subcommand parsers

Returns:

the syntax for subcommand parsers

Return type:

str

class ramble.cmd.commands.RambleArgparseRstWriter(prog, out=None, aliases=False, documented_commands=None, rst_levels=None)

Bases: ArgparseRstWriter

RST writer tailored for ramble documentation.

usage(*args)

class ramble.cmd.commands.SubcommandWriter(prog, out=None, aliases=False)

Bases: ArgparseWriter

format(cmd)

Returns the string representation of a single node in the parser tree.

Override this in subclasses to define how each subcommand should be displayed.

Parameters:

(Command) – parsed information about a command or subcommand

Returns:

the string representation of this subcommand

Return type:

str

ramble.cmd.commands.bash(args, out)

ramble.cmd.commands.commands(parser, args)

ramble.cmd.commands.formatter(func)

Decorator used to register formatters

ramble.cmd.commands.formatters = {'bash': <function bash>, 'names': <function names>, 'rst': <function rst>, 'subcommands': <function subcommands>}

list of command formatters

ramble.cmd.commands.names(args, out)

ramble.cmd.commands.prepend_header(args, out)

ramble.cmd.commands.rst(args, out)

ramble.cmd.commands.rst_index(out)

ramble.cmd.commands.setup_parser(subparser)

ramble.cmd.commands.subcommands(args, out)

ramble.cmd.commands.update_completion(parser, args)

Iterate through the shells and update the standard completion files.

This is a convenience method to avoid calling this command many times, and to simplify completion update for developers.

ramble.cmd.commands.update_completion_args = {'base_with_aliases': {'aliases': True, 'format': 'bash', 'header': '/home/docs/checkouts/readthedocs.org/user_builds/ramble-dev-dapomeroy/checkouts/latest/lib/ramble/docs/_ramble_root/share/ramble/bash/ramble-completion.in', 'update': '/home/docs/checkouts/readthedocs.org/user_builds/ramble-dev-dapomeroy/checkouts/latest/lib/ramble/docs/_ramble_root/share/ramble/custom-ramble-completion.bash'}, 'bash_no_aliases': {'aliases': False, 'format': 'bash', 'header': '/home/docs/checkouts/readthedocs.org/user_builds/ramble-dev-dapomeroy/checkouts/latest/lib/ramble/docs/_ramble_root/share/ramble/bash/ramble-completion.in', 'update': '/home/docs/checkouts/readthedocs.org/user_builds/ramble-dev-dapomeroy/checkouts/latest/lib/ramble/docs/_ramble_root/share/ramble/ramble-completion.bash'}}

standard arguments for updating completion scripts we iterate through these when called with –update-completion

ramble.cmd.config module

ramble.cmd.config.config(parser, args)

ramble.cmd.config.config_add(args)

Add the given configuration to the specified config scope

This is a stateful operation that edits the config files.

ramble.cmd.config.config_blame(args)

Print out line-by-line blame of merged YAML.

ramble.cmd.config.config_edit(args)

Edit the configuration file for a specific scope and config section.

With no arguments and an active workspace, edit the ramble.yaml for the active workspace.

ramble.cmd.config.config_get(args)

Dump merged YAML configuration for a specific section.

With no arguments and an active workspace, print the contents of the workspace’s config file (ramble.yaml).

ramble.cmd.config.config_list(args)

List the possible configuration sections.

Used primarily for shell tab completion scripts.

ramble.cmd.config.config_remove(args)

Remove the given configuration from the specified config scope

This is a stateful operation that edits the config files.

ramble.cmd.config.config_revert(args)

ramble.cmd.config.config_update(args) → None

ramble.cmd.config.setup_parser(subparser)

ramble.cmd.data module

ramble.cmd.data.data(parser, args, unknown_args=None)

Look for a function called data_<name> and call it.

ramble.cmd.data.data_create_db(args)

create the database

ramble.cmd.data.data_create_db_setup_parser(subparser)

create the database

ramble.cmd.data.sanitize_arg_name(base_name)

Allow function names to be remapped (eg - to _)

ramble.cmd.data.setup_parser(subparser)

ramble.cmd.data.subcommand_functions = {}

Dictionary mapping subcommand names and aliases to functions

ramble.cmd.debug module

ramble.cmd.debug.debug(parser, args)

ramble.cmd.debug.report(args)

ramble.cmd.debug.setup_parser(subparser)

ramble.cmd.deployment module

ramble.cmd.deployment.deployment(parser, args)

Look for a function called deployment_<name> and call it.

ramble.cmd.deployment.deployment_pull(args)

ramble.cmd.deployment.deployment_pull_setup_parser(subparser)

Pull a workspace deployment into current workspace

ramble.cmd.deployment.deployment_push(args)

ramble.cmd.deployment.deployment_push_setup_parser(subparser)

Push a workspace deployment

ramble.cmd.deployment.deployment_run_pipeline(args, pipeline)

ramble.cmd.deployment.sanitize_arg_name(base_name)

Allow function names to be remapped (eg - to _)

ramble.cmd.deployment.setup_parser(subparser)

ramble.cmd.deployment.subcommand_functions = {'pull': <function deployment_pull>, 'push': <function deployment_push>}

Dictionary mapping subcommand names and aliases to functions

ramble.cmd.docs module

ramble.cmd.docs.docs(parser, args)

ramble.cmd.edit module

ramble.cmd.edit.edit(parser, args)

ramble.cmd.edit.edit_object(name, obj_type_name, repo_path, namespace)

Opens the requested application file in your favorite $EDITOR.

Parameters:

• name (str) – The name of the application

• obj_type_name (str) – Name of the object type to edit

• repo_path (str) – The path to the repository containing this application

• namespace (str) – A valid namespace registered with Ramble

ramble.cmd.edit.setup_parser(subparser)

ramble.cmd.help module

ramble.cmd.help.help(parser, args)

ramble.cmd.help.setup_parser(subparser)

ramble.cmd.info module

ramble.cmd.info.info(parser, args)

ramble.cmd.info.setup_parser(subparser)

ramble.cmd.license module

class ramble.cmd.license.LicenseError

Bases: object

add_error(error)

error_messages()

has_errors()

ramble.cmd.license.apache2_mit_spdx = '(Apache-2.0 OR MIT)'

Ramble’s license identifier

ramble.cmd.license.git = <exe: ['/usr/bin/git']>

need the git command to check new files

ramble.cmd.license.lgpl_exceptions = ['lib/ramble/ramble/cmd/license.py', 'lib/ramble/ramble/test/cmd/license.py']

licensed files that can have LGPL language in them so far, just this command – so it can find LGPL things elsewhere

ramble.cmd.license.license(parser, args)

ramble.cmd.license.license_lines = 9

SPDX license id must appear in the first <license_lines> lines of a file

ramble.cmd.license.licensed_files = ['bin/ramble$', 'bin/ramble-python$', 'lib/ramble/ramble/.*\\.py$', 'lib/ramble/ramble/.*\\.sh$', 'lib/ramble/llnl/.*\\.py$', 'lib/ramble/docs/(?!command_index|ramble|llnl).*\\.rst$', 'lib/ramble/docs/.*\\.py$', 'lib/ramble/external/__init__.py$', 'lib/ramble/external/ordereddict_backport.py$', 'share/ramble/.*\\.sh$', 'share/ramble/.*\\.bash$', 'share/ramble/.*\\.csh$', 'share/ramble/qa/run-[^/]*$', 'share/ramble/bash/.*$', 'share/ramble/cloud-build/.*\\.yaml$', 'examples/.*\\.yaml$', 'var/ramble/repos/.*/application.py$', 'var/ramble/repos/.*/modifier.py$', 'var/ramble/repos/.*/package_manager.py$', 'var/ramble/repos/.*/workflow_manager.py$', 'var/ramble/repos/.*/system.py$', 'var/ramble/repos/.*/platform.py$', 'var/ramble/repos/.*/base_class.py$', 'var/ramble/repos/.*/base_application.py$', 'var/ramble/repos/.*/base_modifier.py$', 'var/ramble/repos/.*/base_package_manager.py$', 'var/ramble/repos/.*/base_workflow_manager.py$', 'var/ramble/repos/.*/base_system.py$', 'var/ramble/repos/.*/base_platform.py$']

regular expressions for licensed files.

ramble.cmd.license.list_files(args)

list files in ramble that should have license headers

ramble.cmd.license.setup_parser(subparser)

ramble.cmd.license.update_copyright_year(args)

update copyright header for the current year (utc-based) in all licensed files

ramble.cmd.license.verify(args)

verify that files in ramble have the right license header

ramble.cmd.list module

ramble.cmd.list.list(parser, args)

ramble.cmd.list.setup_parser(subparser)

ramble.cmd.mirror module

ramble.cmd.mirror.mirror(parser, args)

ramble.cmd.mirror.mirror_add(args)

Add a mirror to Ramble.

ramble.cmd.mirror.mirror_destroy(args)

Given a url, recursively delete everything under it.

ramble.cmd.mirror.mirror_list(args)

Print out available mirrors to the console.

ramble.cmd.mirror.mirror_remove(args)

Remove a mirror by name.

ramble.cmd.mirror.mirror_set_url(args)

Change the URL of a mirror.

ramble.cmd.mirror.setup_parser(subparser)

ramble.cmd.on module

ramble.cmd.on.on(parser, args)

Execute ramble_on command

ramble.cmd.on.ramble_on(args)

ramble.cmd.on.setup_parser(subparser)

ramble.cmd.python module

ramble.cmd.python.ipython_interpreter(args)

An ipython interpreter is intended to be interactive, so it doesn’t support running a script or arguments

ramble.cmd.python.propagate_exceptions_from(console)

Set sys.excepthook to let uncaught exceptions return 1 to the shell.

Parameters:

console (code.InteractiveConsole) – the console that needs a change in sys.excepthook

ramble.cmd.python.python(parser, args, unknown_args)

ramble.cmd.python.python_interpreter(args)

A python interpreter is the default interpreter

ramble.cmd.python.setup_parser(subparser)

ramble.cmd.repo module

ramble.cmd.repo.repo(parser, args)

ramble.cmd.repo.repo_add(args)

Add a repository to Ramble’s configuration.

ramble.cmd.repo.repo_create(args)

Create a new repository.

ramble.cmd.repo.repo_list(args)

Show registered repositories and their namespaces.

ramble.cmd.repo.repo_remove(args)

Remove a repository from Ramble’s configuration.

ramble.cmd.repo.setup_parser(subparser)

Setup the repo command parser.

The repo command helps manage Ramble repositories, which are the locations ramble reads object definition files from.

This command has subcommands for create, add, remove, and list.

ramble.cmd.results module

ramble.cmd.results.import_results_file(filename)

Import Ramble experiment results from a JSON or YAML file.

Returns a results dictionary.

ramble.cmd.results.results(parser, args)

ramble.cmd.results.results_index(args)

List attributes in results including FOMs and template variables

ramble.cmd.results.results_report(args)

Create a report with charts from Ramble experiment results.

ramble.cmd.results.results_upload(args)

Imports Ramble experiment results from JSON file and uploads them as specified in the upload block of Ramble’s config file.

ramble.cmd.results.setup_parser(subparser)

ramble.cmd.software_definitions module

ramble.cmd.software_definitions.collect_definitions()

Build software definition data structures

Iterate over all defined objects and extract their software definitions. Built maps representing which objects use a given software definition, and where detected conflicts have occurred.

The maps are global to this module, and reused in other internal methods.

ramble.cmd.software_definitions.count_conflicts()

Iterate over conflicts and count how many were detected

ramble.cmd.software_definitions.print_conflicts()

Print conflict information, if any exist

ramble.cmd.software_definitions.print_summary()

Print a summary of all software definitions

ramble.cmd.software_definitions.setup_parser(subparser)

Setup the parser for software-definitions

ramble.cmd.software_definitions.software_definitions(parser, args, unknown_args)

Perform software-definitions actions

ramble.cmd.style module

ramble.cmd.style.add_pattern_exemptions(line, codes)

Add a flake8 exemption to a line.

ramble.cmd.style.changed_files(base=None, untracked=True, all_files=False, root='/home/docs/checkouts/readthedocs.org/user_builds/ramble-dev-dapomeroy/checkouts/latest/lib/ramble/docs/_ramble_root')

Get list of changed files in the Ramble repository.

ramble.cmd.style.filter_file(source, dest, output=False)

Filter a single file through all the patterns in pattern_exemptions.

ramble.cmd.style.get_tool_args(args, tool_name)

Helper to get tool-specific arguments from args.

ramble.cmd.style.is_object(f)

Whether flake8 should consider a file as a core file or an object.

We run flake8 with different exceptions for the core and for objects, since we allow from ramble import * and poking globals into objects.

ramble.cmd.style.print_output(output, args)

ramble.cmd.style.print_tool_header(tool, file_list)

ramble.cmd.style.print_tool_result(tool, returncode)

ramble.cmd.style.run_black(black_cmd, file_list, args)

ramble.cmd.style.run_flake8(flake8_cmd, file_list, args)

ramble.cmd.style.run_isort(isort_cmd, file_list, args)

ramble.cmd.style.run_mypy(mypy_cmd, file_list, args)

ramble.cmd.style.run_ruff(ruff_cmd, file_list, args)

ramble.cmd.style.setup_parser(subparser)

ramble.cmd.style.style(parser, args)

class ramble.cmd.style.tool(name)

Bases: object

ramble.cmd.style.validate_toolset(arg_value)

Validate –tool and –skip arguments (sets of optionally comma-separated tools).

ramble.cmd.unit_test module

ramble.cmd.unit_test.add_back_pytest_args(args, unknown_args)

Add parsed pytest args, unknown args, and remainder together.

We add some basic pytest arguments to the Ramble parser to ensure that they show up in the short help, so we have to reassemble things here.

ramble.cmd.unit_test.do_list(args, extra_args)

Print a lists of tests than what pytest offers.

ramble.cmd.unit_test.setup_parser(subparser)

ramble.cmd.unit_test.unit_test(parser, args, unknown_args)

ramble.cmd.workspace module

ramble.cmd.workspace.create_temp_workspace_directory()

Returns the path of a temporary directory in which to create a workspace

ramble.cmd.workspace.sanitize_arg_name(base_name)

Allow function names to be remapped (eg - to _)

ramble.cmd.workspace.setup_parser(subparser)

ramble.cmd.workspace.subcommand_functions = {'activate': <function workspace_activate>, 'analyze': <function workspace_analyze>, 'archive': <function workspace_archive>, 'concretize': <function workspace_concretize>, 'config': <function workspace_config>, 'create': <function workspace_create>, 'deactivate': <function workspace_deactivate>, 'edit': <function workspace_edit>, 'experiment-logs': <function workspace_experiment_logs>, 'generate-config': <function workspace_generate_config>, 'info': <function workspace_info>, 'list': <function workspace_list>, 'ls': <function workspace_list>, 'manage': <function workspace_manage>, 'mirror': <function workspace_mirror>, 'push-to-cache': <function workspace_push_to_cache>, 'remove': <function workspace_remove>, 'rm': <function workspace_remove>, 'setup': <function workspace_setup>}

Dictionary mapping subcommand names and aliases to functions

ramble.cmd.workspace.workspace(parser, args, unknown_args)

Look for a function called workspace_<name> and call it.

ramble.cmd.workspace.workspace_activate(args)

ramble.cmd.workspace.workspace_activate_setup_parser(subparser)

Set the current workspace

ramble.cmd.workspace.workspace_analyze(args)

ramble.cmd.workspace.workspace_analyze_setup_parser(subparser)

Analyze a workspace

ramble.cmd.workspace.workspace_archive(args)

ramble.cmd.workspace.workspace_archive_setup_parser(subparser)

archive current workspace state

ramble.cmd.workspace.workspace_concretize(args)

ramble.cmd.workspace.workspace_concretize_setup_parser(subparser)

Concretize a workspace

ramble.cmd.workspace.workspace_config(args)

ramble.cmd.workspace.workspace_config_setup_parser(subparser)

Squashed workspace config

ramble.cmd.workspace.workspace_create(args)

ramble.cmd.workspace.workspace_create_setup_parser(subparser)

create a new workspace

ramble.cmd.workspace.workspace_deactivate(args)

ramble.cmd.workspace.workspace_deactivate_setup_parser(subparser)

deactivate any active workspace in the shell

ramble.cmd.workspace.workspace_edit(args, unknown_args)

ramble.cmd.workspace.workspace_edit_setup_parser(subparser)

edit workspace config or template

ramble.cmd.workspace.workspace_experiment_logs(args)

Print log information for workspace

ramble.cmd.workspace.workspace_experiment_logs_setup_parser(subparser)

print log information for workspace

ramble.cmd.workspace.workspace_generate_config(args)

Generate a configuration file for this ramble workspace

ramble.cmd.workspace.workspace_generate_config_setup_parser(subparser)

generate current workspace config

ramble.cmd.workspace.workspace_info(args)

ramble.cmd.workspace.workspace_info_setup_parser(subparser)

Information about a workspace

ramble.cmd.workspace.workspace_list(args)

ramble.cmd.workspace.workspace_list_setup_parser(subparser)

list available workspaces

ramble.cmd.workspace.workspace_manage(args)

Look for a function for the manage subcommand, and execute it.

ramble.cmd.workspace.workspace_manage_experiments(args)

Perform experiment management

ramble.cmd.workspace.workspace_manage_experiments_setup_parser(subparser)

manage experiment definitions

ramble.cmd.workspace.workspace_manage_includes(args)

Execute workspace manage include command

ramble.cmd.workspace.workspace_manage_includes_setup_parser(subparser)

manage workspace includes

ramble.cmd.workspace.workspace_manage_modifiers(args)

Execute workspace manage modifiers command

ramble.cmd.workspace.workspace_manage_modifiers_setup_parser(subparser)

manage workspace modifiers

ramble.cmd.workspace.workspace_manage_setup_parser(subparser)

manage workspace definitions

ramble.cmd.workspace.workspace_manage_software(args)

Execute workspace manage software command

ramble.cmd.workspace.workspace_manage_software_setup_parser(subparser)

manage workspace software definitions

ramble.cmd.workspace.workspace_mirror(args)

ramble.cmd.workspace.workspace_mirror_setup_parser(subparser)

mirror current workspace state

ramble.cmd.workspace.workspace_push_to_cache(args)

ramble.cmd.workspace.workspace_push_to_cache_setup_parser(subparser)

push workspace envs to a given buildcache

ramble.cmd.workspace.workspace_remove(args)

Remove a named workspace.

This removes an environment managed by Ramble. Directory workspaces should be removed manually.

ramble.cmd.workspace.workspace_remove_setup_parser(subparser)

remove an existing workspace

ramble.cmd.workspace.workspace_run_pipeline(args, pipeline)

ramble.cmd.workspace.workspace_setup(args)

ramble.cmd.workspace.workspace_setup_setup_parser(subparser)

Setup a workspace