Python module

Download/install

Overview

Write job scripts

GooseSLURM.scripts.plain([filename, …]) Return simple SBATCH-file (as text).
GooseSLURM.scripts.tempdir([filename, …]) Return SBATCH-file (as text) that uses a temporary working directory on the compute node.
GooseSLURM.files.cmake() Return a list of typical build files/folders generated by CMake.

Parse ps

GooseSLURM.ps.read_interpret([data, theme]) Read and interpret ps -eo pid,user,rss,%cpu,command.
GooseSLURM.ps.read([data]) Read ps -eo pid,user,rss,%cpu,command.
GooseSLURM.ps.interpret(lines[, theme]) Interpret the output of GooseSLURM.ps.read.
GooseSLURM.ps.colors([theme]) Return dictionary of colors.

Parse squeue

GooseSLURM.squeue.read_interpret([data, …]) Read and interpret squeue -o "%all".
GooseSLURM.squeue.read([data]) Read squeue -o "%all".
GooseSLURM.squeue.interpret(lines[, now, theme]) Interpret the output of GooseSLURM.squeue.read.
GooseSLURM.squeue.colors([theme]) Return dictionary of colors.

Parse sinfo

GooseSLURM.sinfo.read_interpret([data, theme]) Read and interpret sinfo -o "%all".
GooseSLURM.sinfo.read([data]) Read sinfo -o "%all".
GooseSLURM.sinfo.interpret(lines[, theme]) Interpret the output of GooseSLURM.sinfo.read.
GooseSLURM.sinfo.colors([theme]) Return dictionary of colors.

Rich strings

GooseSLURM.rich.String(data[, width, align, …]) Rich string.
GooseSLURM.rich.Integer(data, **kwargs) Rich integer.
GooseSLURM.rich.Float(data, **kwargs) Rich float.
GooseSLURM.rich.Duration(data, **kwargs) Rich duration (seconds).
GooseSLURM.rich.Memory(data, **kwargs) Rich memory (bytes).

Print

GooseSLURM.table.print_long(lines) Print full data without much formatting.
GooseSLURM.table.print_columns(lines, …[, …]) Print table to fit the screen.
GooseSLURM.table.print_list(lines, key[, sep]) Print a single column as a list.

Duration

GooseSLURM.duration.asSeconds(data[, default]) Convert string to seconds.
GooseSLURM.duration.asUnit(data, unit, precision) Convert to rich-string with a certain unit and precision.
GooseSLURM.duration.asHuman(data[, precision]) Convert to string that has the biggest possible unit.
GooseSLURM.duration.asSlurm(data) Convert to a SLURM time string.

Memory

GooseSLURM.memory.asBytes(data[, default, …]) Convert string to bytes.
GooseSLURM.memory.asUnit(data, unit, precision) Convert to rich-string with a certain unit and precision.
GooseSLURM.memory.asHuman(data[, precision]) Convert to string that has the biggest possible unit.
GooseSLURM.memory.asSlurm(data) Convert to a SLURM string.

Documentation

GooseSLURM.scripts

GooseSLURM.scripts.plain(filename='job.slurm', command=[], cd_submitdir=True, **sbatch)

Return simple SBATCH-file (as text).

Options:
filename (<str> | ['job.slurm'])

The filename to assume to construct default paths for the out file.

command (<str> | <list>)

Command(s) to execute. If the input is a list each entry is included as an individual line.

cd_submitdir ([True] | False)

Include cd "${SLURM_SUBMIT_DIR}" at the beginning of the script.

SBATCH options:
mem (<int> | <str>)

Memory claim (may be human readable, see GooseSLUM.memory.asSlurm).

time (<str>)

Wall-time claim (may be human readable, see GooseSLUM.duration.asSlurm).

out ([filename+'.out'] | <str>)

Name of the output file.

GooseSLURM.scripts.tempdir(filename='job.slurm', remove=[], command=[], **sbatch)

Return SBATCH-file (as text) that uses a temporary working directory on the compute node.

Options:
filename (['job.slurm'] | <str>)

The filename to assume to construct default paths for the out- and JSON files.

remove (<list>)

List with files/folders to remove from the temporary directory before copying.

command (<str> | <list>)

Command(s) to execute. If the input is a list each entry is included as an individual line.

SBATCH options:
mem (<int> | <str>)

Memory claim (may be human readable, see GooseSLUM.memory.asSlurm).

time (<str>)

Wall-time claim (may be human readable, see GooseSLUM.duration.asSlurm).

out ([filename+'.out'] | <str>)

Name of the output file.

GooseSLURM.files

GooseSLURM.files.cmake()

Return a list of typical build files/folders generated by CMake.

GooseSLURM.ps

GooseSLURM.ps.colors(theme=None)

Return dictionary of colors.

{
  'selection' : '...',
}
Options:
theme (['dark'] | <str>)

Select color-theme.

GooseSLURM.ps.interpret(lines, theme={'selection': ''})

Interpret the output of GooseSLURM.ps.read. All fields are converted to the GooseSLURM.rich classes adding useful colors in the process.

Arguments:
lines <list<dict>>

The output of GooseSLURM.ps.read

Options:
theme (<dict>)

The color-theme, as selected by GooseSLURM.ps.colors.

Returns:

lines (<list<dict>>)

A list of dictionaries, that contain the different fields. All data are GooseSLURM.rich.String or derived types.

GooseSLURM.ps.read(data=None)

Read ps -eo pid,user,rss,%cpu,command.

Options:
data (<str>)

For debugging: specify the output of ps -eo pid,user,rss,%cpu,command as string.

Returns:

lines <list<dict>>

A list of dictionaries, that contain the different fields. All data are strings.

GooseSLURM.ps.read_interpret(data=None, theme={'selection': ''})

Read and interpret ps -eo pid,user,rss,%cpu,command.

Returns:
lines (<list<dict>>)
A list of dictionaries, that contain the different fields. All data are GooseSLURM.rich.String or derived types.

GooseSLURM.squeue

GooseSLURM.squeue.colors(theme=None)

Return dictionary of colors.

{
  'selection' : '...',
  'queued'    : '...',
}
Options:
theme (['dark'] | <str>)

Select color-theme.

GooseSLURM.squeue.interpret(lines, now=None, theme={'queued': '', 'selection': ''})

Interpret the output of GooseSLURM.squeue.read. All fields are converted to the GooseSLURM.rich classes adding useful colors in the process.

Arguments:
lines <list<dict>>

The output of GooseSLURM.squeue.read

Options:
theme (<dict>)

The color-theme, as selected by GooseSLURM.squeue.colors.

Returns:

lines (<list<dict>>)

A list of dictionaries, that contain the different fields. All data are GooseSLURM.rich.String or derived types.

GooseSLURM.squeue.read(data=None)

Read squeue -o "%all".

Options:
data (<str>)

For debugging: specify the output of squeue -o "%all" as string.

Returns:

lines <list<dict>>

A list of dictionaries, that contain the different fields. All data are strings.

GooseSLURM.squeue.read_interpret(data=None, now=None, theme={'queued': '', 'selection': ''})

Read and interpret squeue -o "%all".

Returns:
lines (<list<dict>>)
A list of dictionaries, that contain the different fields. All data are GooseSLURM.rich.String or derived types.

GooseSLURM.sinfo

GooseSLURM.sinfo.colors(theme=None)

Return dictionary of colors.

{
  'selection' : '...',
  'free'      : '...',
  'error'     : '...',
  'warning'   : '...',
  'low'       : '...',
}
Options:
theme (['dark'] | <str>)

Select color-theme.

GooseSLURM.sinfo.interpret(lines, theme={'error': '', 'free': '', 'low': '', 'selection': '', 'warning': ''})

Interpret the output of GooseSLURM.sinfo.read. All fields are converted to the GooseSLURM.rich classes adding useful colors in the process.

Arguments:
lines <list<dict>>

The output of GooseSLURM.sinfo.read

Options:
theme (<dict>)

The color-theme, as selected by GooseSLURM.sinfo.colors.

Returns:

lines (<list<dict>>)

A list of dictionaries, that contain the different fields. All data are GooseSLURM.rich.String or derived types.

GooseSLURM.sinfo.read(data=None)

Read sinfo -o "%all".

Options:
data (<str>)

For debugging: specify the output of sinfo -o "%all" as string.

Returns:

lines <list<dict>>

A list of dictionaries, that contain the different fields. All data are strings.

GooseSLURM.sinfo.read_interpret(data=None, theme={'error': '', 'free': '', 'low': '', 'selection': '', 'warning': ''})

Read and interpret sinfo -o "%all".

Returns:
lines (<list<dict>>)
A list of dictionaries, that contain the different fields. All data are GooseSLURM.rich.String or derived types.

GooseSLURM.rich

class GooseSLURM.rich.Duration(data, **kwargs)

Rich duration (seconds).

Note

All options are attributes, that can be modified at all times.

Options:
data (<str> | None)

The data.

width ([None] | <int>)

Print width (formatted print only).

color ([None] | <str>)

Print color, e.g. “1;32” for bold green (formatted print only).

align (['<'] | '>')

Print alignment (formatted print only).

precision ([None] | <int>)

Print precision to use for the conversion (formatted print only). None means automatic precision. See GooseSLURM.duration.asHuman.

dummy ([0] | <int> | <float>)

Dummy numerical value, used in case of non-numerical data.

Methods:
A.format()

Formatted string, after unit conversion.

str(A)

Unformatted string, after unit conversion.

A.isnumeric()

Return if the “data” is numeric.

int(A)

Return data as integer (dummy is returned if data is not numeric).

float(A)

Return data as float (dummy is returned if data is not numeric).

class GooseSLURM.rich.Float(data, **kwargs)

Rich float.

Note

All options are attributes, that can be modified at all times.

Options:
data (<str> | None)

The data.

width ([None] | <int>)

Print width (formatted print only).

color ([None] | <str>)

Print color, e.g. “1;32” for bold green (formatted print only).

align (['<'] | '>')

Print alignment (formatted print only).

precision ([2] | <int>)

Print precision (formatted print only).

dummy ([0] | <int> | <float>)

Dummy numerical value, used in case of non-numerical data.

Methods:
A.format()

Formatted string.

str(A)

Unformatted string.

A.isnumeric()

Return if the “data” is numeric.

int(A)

Return data as integer (dummy is returned if data is not numeric).

float(A)

Return data as float (dummy is returned if data is not numeric).

isnumeric()

Return if the “data” is numeric : always zero for this class.

class GooseSLURM.rich.Integer(data, **kwargs)

Rich integer.

Note

All options are attributes, that can be modified at all times.

Options:
data (<str> | None)

The data.

width ([None] | <int>)

Print width (formatted print only).

color ([None] | <str>)

Print color, e.g. “1;32” for bold green (formatted print only).

align (['<'] | '>')

Print alignment (formatted print only).

dummy ([0] | <int> | <float>)

Dummy numerical value, used in case of non-numerical data.

Methods:
A.format()

Formatted string.

str(A)

Unformatted string.

A.isnumeric()

Return if the “data” is numeric.

int(A)

Return data as integer (dummy is returned if data is not numeric).

float(A)

Return data as float (dummy is returned if data is not numeric).

isnumeric()

Return if the “data” is numeric : always zero for this class.

class GooseSLURM.rich.Memory(data, **kwargs)

Rich memory (bytes).

Note

All options are attributes, that can be modified at all times.

Options:
data (<str> | None)

The data.

width ([None] | <int>)

Print width (formatted print only).

color ([None] | <str>)

Print color, e.g. “1;32” for bold green (formatted print only).

align (['<'] | '>')

Print alignment (formatted print only).

precision ([None] | <int>)

Print precision to use for the conversion (formatted print only). None means automatic precision. See GooseSLURM.memory.asHuman.

dummy ([0] | <int> | <float>)

Dummy numerical value, used in case of non-numerical data.

default_unit (int)

The unit to assume if no unit if specified (specify the number of bytes).

Methods:
A.format()

Formatted string, after unit conversion.

str(A)

Unformatted string, after unit conversion.

A.isnumeric()

Return if the “data” is numeric.

int(A)

Return data as integer (dummy is returned if data is not numeric).

float(A)

Return data as float (dummy is returned if data is not numeric).

class GooseSLURM.rich.String(data, width=None, align='<', color=None, dummy=0)

Rich string.

Note

All options are attributes, that can be modified at all times.

Options:
data (<str> | None)

The data.

width ([None] | <int>)

Print width (formatted print only).

color ([None] | <str>)

Print color, e.g. “1;32” for bold green (formatted print only).

align (['<'] | '>')

Print alignment (formatted print only).

dummy ([0] | <int> | <float>)

Dummy numerical value.

Methods:
A.format()

Formatted string.

str(A)

Unformatted string.

A.isnumeric()

Return if the “data” is numeric.

int(A)

Dummy integer.

float(A)

Dummy float.

format()

Return formatted string: align/width/color are applied.

isnumeric()

Return if the “data” is numeric : always zero for this class.

GooseSLURM.table

GooseSLURM.table.print_columns(lines, columns, header, no_truncate=False, sep=', ', cols=None)

Print table to fit the screen. This function can show data truncated, or even suppress columns if there is insufficient room.

Arguments:
lines ([ {'JOBID': '1234', ...}, ...])

List of lines, with each line stored as a dictionary. Note that all data has to be stored as one of the GooseSLURM.rich classes (to customize the color, precision, …) or as string.

columns ([ {'key': 'JOBID', 'width': 7, 'align': '>', 'priority': True}, ...])

List with print settings of each column: - ‘key’ : the key-name used to store each line (see lines below) - ‘width’ : minimum print width (expanded as much as possible to fit the data) - ‘align’ : alignment of the column - ‘priority’: priority of column expansion, columns marked True are expanded first

header ({'JOBID': 'JobID', ...})

Header name for each column.

Options:
no_truncate ([False] | True)

Disable truncation of columns. In this case each column is expanded to fit the data.

sep ([', '] | <str>)

Separator between columns.

cols ([None] | <int>)

Number of characters on one line. If None the current terminal’s width is used.

GooseSLURM.table.print_list(lines, key, sep=' ')

Print a single column as a list.

Arguments:
lines ([ {'JOBID': '1234', ...}, ...])

List of lines, with each line stored as a dictionary. Note that all data has to be stored as one as string, or as one the GooseSLURM.rich classes (no rich printing is used though).

key ('JOBID')

Column to print.

Options:
sep ([' '] | <str>)

Separator between columns.

GooseSLURM.table.print_long(lines)

Print full data without much formatting. The output looks as follows:

+------------------+
| line 1, column 1 |
| line 1, column 2 |
| ...              |
+-----------------+
| line 2, column 1 |
| line 2, column 2 |
| ...              |
+------------------+
Arguments:
lines ([ {'JOBID': '1234', ...}, ...])

List of lines, with each line stored as a dictionary. Note that all data has to be stored as one as string, or as one the GooseSLURM.rich classes (no rich printing is used though).

GooseSLURM.duration

GooseSLURM.duration.asHuman(data, precision=None)

Convert to string that has the biggest possible unit. For example: 100 (seconds) -> "1.7m".

Arguments:
data (<str> | <float> | <int>)

A time, see GooseSLURM.duration.asSeconds for conversion.

precision (<int>)

The precision with which to print. By default a precision of one is used for 0 < value < 10, while a precision of zero is used otherwise.

Returns:

<str>

The rich-string.

GooseSLURM.duration.asSeconds(data, default=None)

Convert string to seconds. The following input is accepted:

  • A humanly readable time (e.g. “1d”).
  • A SLURM time string (e.g. “1-00:00:00”).
  • A time string (e.g. “24:00:00”).
  • int or float: interpreted as seconds.
Arguments:
data (<str> | <float> | <int>)

The input string (number are equally accepted; they are directly interpreted as seconds).

Options:
default ([None] | <int>)

Value to return if the conversion fails.

Returns:

<int>

Number of seconds as integer (or default value if the conversion fails).

GooseSLURM.duration.asSlurm(data)

Convert to a SLURM time string. For example "1d" -> "1-00:00:00".

Arguments:
data (<str> | <float> | <int>)

A time, see GooseSLURM.duration.asSeconds for conversion.

Returns:

<str>

The rich-string.

GooseSLURM.duration.asUnit(data, unit, precision)

Convert to rich-string with a certain unit and precision. The output is e.g. "1.1d".

Arguments:
data (<int> | <float>)

Numerical value (e.g. 1.1).

unit (<str>)

The unit (e.g. "d").

precision (<int>)

The precision with which to print (e.g. 1).

Returns:

<str>

The rich-string.

GooseSLURM.memory

GooseSLURM.memory.asBytes(data, default=None, default_unit=1)

Convert string to bytes. The following input is accepted:

  • A humanly readable string (e.g. “1G”).
  • int or float: interpreted as bytes.
Arguments:
data (<str> | <float> | <int>)

The input string (number are equally accepted; they are directly interpreted as bytes).

Options:
default ([None] | <int>)

Value to return if the conversion fails.

default_unit (int)

The unit to assume if no unit if specified (specify the number of bytes).

Returns:

<int>

Number of bytes as integer (or default value if the conversion fails).

GooseSLURM.memory.asHuman(data, precision=None)

Convert to string that has the biggest possible unit. For example 1e6 (bytes) -> "1.0M".

Arguments:
data (<str> | <float> | <int>)

An amount of memory, see GooseSLURM.duration.asBytes for conversion.

precision (<int>)

The precision with which to print. By default a precision of one is used for 0 < value < 10, while a precision of zero is used otherwise.

Returns:

<str>

The rich-string.

GooseSLURM.memory.asSlurm(data)

Convert to a SLURM string. For example "1G".

Arguments:
data (<str> | <float> | <int>)

An amount of memory, see GooseSLURM.duration.asBytes for conversion.

Returns:

<str>

The rich-string.

GooseSLURM.memory.asUnit(data, unit, precision)

Convert to rich-string with a certain unit and precision. The output is e.g. "1.1G".

Arguments:
data (<int> | <float>)

Numerical value (e.g. 1.1).

unit (<str>)

The unit (e.g. "G").

precision (<int>)

The precision with which to print (e.g. 1).

Returns:

<str>

The rich-string.