jip.cli

The JIP command line package contains utilities and the modules that expose command line functions for the JIP command. The module hosts a set of utility functions that can be used to simplify the process of interacting with the JIP API from within a command line tool.

Functions in this module might have certain limitations when you want to use them as general API calls. Most of the output generation functions print to stdout and this can not be changed. In addition, be very careful the dry(), it calles sys.exit(1) in case of a failure.

Warning

Both run() and dry() call sys.exit(1) in case of a failure! Be very careful when you want to call them outside of a command line tool that is allowed terminate!

Note

Please note that you can use the module to implement custom command line utilities, but it was written to support the commands that are shipped with JIP. That means the modules functions might change according to the needs of the internal command line utilities.

jip.cli.STATE_COLORS = {'Canceled': '\x1b[93m', 'Failed': '\x1b[91m', 'Running': '\x1b[94m', 'Done': '\x1b[92m', 'Hold': '\x1b[93m', 'Queued': ''}

Maps job states to colors

jip.cli.colorize(string, color)

Colorize a string using ANSI colors.

The jip.cli module contains a few ANSI color definitions that are used quiet often in the system.

Parameters:

• string – the string to colorize
• color – the color that should be used

jip.cli.confirm(msg, default=True)

Print the message and ask the user to confirm. Return True if the user confirmed with Y.

Parameters:

• msg – the message
• default – Default answer

jip.cli.create_table(header, rows, empty='', to_string=<function table_to_string at 0x7f88eefbe500>, widths=None, deco=2)

Create a table.

Parameters:

• header – list of table column names
• rows – list of list of row values
• empty – string representation for None values
• to_string – function reference to the converter function that creates string representation for row values
• width – optional list of columns widths
• deco – Texttable decorations

Returns:

Texttable table instance

jip.cli.dry(script, script_args, dry=True, show=False)

Load the script and initialize it with the given arguments, then perform a dry run and print the options and commands

Warning

This method calls sys.exit(1) in case an Exception is raised

Parameters:

• script – the script
• script_args – script arguments
• dry – print job options
• show – print job commands

jip.cli.parse_args(docstring, argv=None, options_first=True)

Parse the command line options

Parameters:

• docstring – the docstring that will be parsed
• argv – the arguments. Defaults to sys.argv if this is not specified

Returns:

parsed options as dictionary

jip.cli.parse_job_ids(args, read_stdin=True)

Resolves job and clsuter ids specified in the args –job and –cluster-job options. In additon, this reads job ids from stdin.

Parameters:args – parsed command line options Returns:tuple of job ids and cluster ids

jip.cli.read_ids_from_pipe()

Read job ids from a stream

jip.cli.render_table(header, rows, empty='', widths=None, to_string=<function table_to_string at 0x7f88eefbe500>, deco=2)

Create a simple ASCII table and returns its string representation.

Parameters:

• header – list of table column names
• rows – list of list of row values
• empty – string representation for None values
• to_string – function reference to the converter function that creates string representation for row values
• width – optional list of columns widths

Returns:

string representation of the table

jip.cli.resolve_job_range(ids)

Resolve ranges from a list of ids. Given list of id strings can contain ranges separated with ‘-‘. For example, ‘1-10’ will result in a range from 1..10.

Parameters:ids (string or list of strings) – string or list of strings of ids Returns:resolved list of ids Return type:list of integers Raises ValueError:  if on of the ids could not be converted to a valid, positive id

jip.cli.show_commands(jobs)

Print the commands for the given list of jobs

Parameters:jobs (list of jip.db.Job) – list of jobs

jip.cli.show_dry(jobs, options=None, profiles=False)

Print the dry-run table to stdout

Parameters:

• jobs – list of jobs
• options – the parent script options
• profiles – render job profiles table

jip.cli.show_job_profiles(jobs, title='Job profiles')

Print the job profile for a given list of jobs.

The job profile contains the following properties:

Name

The job name

Queue

The queue assigned to the job

Priority

The jobs priority

Threads

Number of threads assigned to the job

Time

Maximum run time assigned to the job

Memory

Maximum memory assigned to the job

Account

The account assigned to the job

Directory

The jobs working directory

Parameters:

• jobs (list of jip.db.Job) – list of jobs
• title – a title for the table

jip.cli.show_job_states(jobs, title='Job states')

Print the job states table for a list of jobs.

Parameters:

• jobs (list of jip.db.Job) – list of jobs
• title – a title for the table

jip.cli.show_job_tree(jobs, title='Job hierarchy')

Prints the job hierarchy as a tree structure

Parameters:

• jobs (list of jip.db.Job) – list of jobs
• title – a title for the table

jip.cli.show_options(options, title=None, excludes=None, show_defaults=True)

Print the options to a table

Parameters:

• options (jip.options.Options) – the options
• title – a title for the table
• excludes – list of option names that will be excluded
• show_defaults – if True, all options will be printed, otherwise, only options that are different from their default value will be included

jip.cli.table_to_string(value, empty='')

Translates the given value to a string that can be rendered in a table. This functions deals primarily with datatime.datetime and datetime.timedelta values. For all other types, the default string representation is returned.

Parameters:

• value – the value
• empty – the replacement used for None value

Returns:

table compatible string representation

Return type:

string