runcommands.util.get_commands_in_namespace(namespace=None, level=1)[source]

Get commands in namespace.

  • namespace (dict|module) – Typically a module. If not passed, the globals from the call site will be used.
  • level (int) – If not called from the global scope, set this appropriately to account for the call stack.

The commands found in the namespace, ordered by


Return type:


Can be used to create __all__ lists:

__all__ = list(get_commands_in_namespace())
class runcommands.util.Data(**data)[source]

A bucket for arbitrary data.

Data can be added and retrieved as attributes (dot notation) or items (bracket notation).

When a dict is added, it will be converted to an instance of Data.

class runcommands.util.Color[source]

An enumeration.

class runcommands.util.StreamOptions[source]

Choices for stream handling.

runcommands.util.flatten_args(args: list, join=False, *, empty=(None, [](), '')) → list[source]

Flatten args and remove empty items.

  • args – A list of items (typically but not necessarily strings), which may contain sub-lists, that will be flattened into a single list with empty items removed. Empty items include None and empty lists, tuples, and strings.
  • join – If True or a string, the final flattened list will be joined into a single string. The default join string is a space.
  • empty – Items that are considered empty.

The list of args flattened with empty items removed

and the remaining items converted to strings. If join is specified, the list of flattened args will be joined into a single string.

Return type:



>>> flatten_args([])
>>> flatten_args(())
>>> flatten_args([(), (), [(), ()]])
>>> flatten_args(['executable', '--flag' if True else None, ('--option', 'value'), [None]])
['executable', '--flag', '--option', 'value']
>>> flatten_args(['executable', '--option', 0])
['executable', '--option', '0']
runcommands.util.format_if(value, format_kwargs)[source]

Apply format args to value if value or return value as is.

runcommands.util.load_object(obj) → object[source]

Load an object.

Parameters:obj (str|object) –

Load the indicated object if this is a string; otherwise, return the object as is.

To load a module, pass a dotted path like ‘package.module’; to load an an object from a module pass a path like ‘package.module:name’.


Merge all dicts.

Dicts later in the list take precedence over dicts earlier in the list.

runcommands.util.abs_path(path, format_kwargs={}, relative_to=None, keep_slash=False)[source]

Get abs. path for path.

path may be a relative or absolute file system path or an asset path. If path is already an abs. path, it will be returned as is. Otherwise, it will be converted into a normalized abs. path.

If relative_to is passed and path is not absolute, the path will be joined to the specified prefix before it’s made absolute.

If path ends with a slash, it will be stripped unless keep_slash is set (for use with rsync, for example).

>>> file_path = os.path.normpath(__file__)
>>> dir_name = os.path.dirname(file_path)
>>> file_name = os.path.basename(file_path)
>>> os.chdir(dir_name)
>>> abs_path(file_name) == file_path
>>> abs_path('runcommands.util:') == dir_name
>>> abs_path('runcommands.util:path.py') == file_path
>>> abs_path('/{xyz}', format_kwargs={'xyz': 'abc'})
>>> abs_path('banana', relative_to='/usr')
>>> abs_path('/usr/banana/')
>>> abs_path('banana/', relative_to='/usr', keep_slash=True)
>>> abs_path('runcommands.util:banana/', keep_slash=True) == (dir_name + '/banana/')
runcommands.util.asset_path(path, format_kwargs={}, keep_slash=False)[source]

Get absolute path to asset in package.

path can be just a package name like ‘package’ or it can be a package name and a relative file system path like ‘package:util’.

If path ends with a slash, it will be stripped unless keep_slash is set (for use with rsync, for example).

>>> file_path = os.path.normpath(__file__)
>>> dir_name = os.path.dirname(file_path)
>>> file_name = os.path.basename(file_path)
>>> os.chdir(dir_name)
>>> asset_path('runcommands.util') == dir_name
>>> asset_path('runcommands.util:path.py') == file_path
>>> asset_path('runcommands.util:{name}.py', format_kwargs={'name': 'path'}) == file_path
>>> asset_path('runcommands.util:dir/') == (dir_name + '/dir')
>>> asset_path('runcommands.util:dir/', keep_slash=True) == (dir_name + '/dir/')
runcommands.util.paths_to_str(paths, format_kwargs={}, delimiter=':', asset_paths=False, check_paths=False)[source]

Convert paths to a single string.

  • paths (str|list) – A string like “/a/path:/another/path” or a list of paths; may include absolute paths and/or asset paths; paths that are relative will be left relative
  • format_kwargs (dict) – Will be injected into each path
  • delimiter (str) – The string used to separate paths
  • asset_paths (bool) – Whether paths that look like asset paths will be converted to absolute paths
  • check_paths (bool) – Whether paths should be checked to ensure they exist
runcommands.util.confirm(prompt='Really?', color='warning', yes_values=('y', 'yes'), abort_on_unconfirmed=False, abort_options=None)[source]

Prompt for confirmation.

Confirmation can be aborted by typing in a no value instead of one of the yes values or with Ctrl-C.

  • prompt (str) – Prompt to present user [“Really?”]
  • color (string|Color|bool) – False or None to print without color [“yellow”]
  • yes_values (list[str]) – Values user must type in to confirm [(“y”, “yes”)]
  • abort_on_unconfirmed (bool|int|str) –

    When user does not confirm:

    • If this is an integer, print “Aborted” to stdout if it’s 0 or to stderr if it’s not 0 and then exit with this code
    • If this is a string, print it to stdout and exit with code 0
    • If this is True (or any other truthy value), print “Aborted” to stdout and exit with code 0
  • abort_options (dict) – Options to pass to abort() when not confirmed (these options will override any options set via abort_on_unconfirmed)

Convert camel case name to underscore name.


>>> camel_to_underscore('HttpRequest')
>>> camel_to_underscore('httpRequest')
>>> camel_to_underscore('HTTPRequest')
>>> camel_to_underscore('myHTTPRequest')
>>> camel_to_underscore('MyHTTPRequest')
>>> camel_to_underscore('my_http_request')
>>> camel_to_underscore('MyHTTPRequestXYZ')
>>> camel_to_underscore('_HTTPRequest')
>>> camel_to_underscore('Request')
>>> camel_to_underscore('REQUEST')
>>> camel_to_underscore('_Request')
>>> camel_to_underscore('__Request')
>>> camel_to_underscore('_request')
>>> camel_to_underscore('Request_')

Invert the logical meaning of a string.


>>> invert_string('Yes')
>>> invert_string('No')
>>> invert_string("don't")
runcommands.util.is_type(obj, type)[source]

Is the object a type object of the specified type?