Data Model

Command

class aclimatise.model.Command(command: List[str], positional: List[Positional] = NOTHING, named: List[Flag] = NOTHING, parent: Optional[Command] = None, subcommands: List[Command] = NOTHING, usage: List[UsageInstance] = NOTHING, help_flag: Optional[Flag] = None, usage_flag: Optional[Flag] = None, version_flag: Optional[Flag] = None, help_text: Optional[str] = None, generated_using: Optional[str] = None, docker_image: Optional[str] = None)

Class representing an entire command or subcommand, e.g. bwa mem or grep

property all_synonyms

Returns all flag synonyms for all flags in this command

ancestor(levels: int = 1) → Optional[aclimatise.model.Command]

Returns the ancestor of the command levels steps up the family tree. For example, cmd.ancestor(1) is equivalent to cmd.parent. cmd.ancestor(2) is equivalent to cmd.parent.parent.

property as_filename

Returns a sample filename that might be used to store this command (without a suffix)

static best(commands: Collection[aclimatise.model.Command]) → aclimatise.model.Command

Given a list of commands generated from the same executable, but with different flags, determine the best one and return it :param commands: :return:

command: List[str]

The command line used to invoke this command, e.g. [“bwa”, “mem”]

command_tree() → Generator[aclimatise.model.Command, None, None]

Returns a generator over the entire command tree. e.g. if this command has 2 subcommands, each with 2

subcommands, this will return a generator with 7 Commands

property depth

Returns the “depth” of this command, aka how many ancestors it has. An orphan command has depth 0, a subcommand has depth 1, a sub-sub-command has depth 2 etc

docker_image: Optional[str]

If available, a docker image in which to run this command

property empty

True if we think this command failed in parsing, ie it has no arguments

generated_using: Optional[str]

Optionally, the flag that was used to generate this command. Often this will be the same as the help_flag

help_flag: Optional[aclimatise.model.Flag]

If identified, this is the flag that returns help text

help_text: Optional[str]

Optionally, the entire help text that was used to generate this Command

named: List[aclimatise.model.Flag]

All named arguments (flags) supported by this command

property outputs

Returns a list of inputs which are also outputs, for example the “-o” flag is normally an input (you have to provide a filename), but also an output (you are interested in the contents of the file at that path after the command has been run)

parent: Optional[aclimatise.model.Command]

The parent command, if this is a subcommand

positional: List[aclimatise.model.Positional]

All positional arguments supported by this command

reanalyse(parent: Optional[aclimatise.model.Command] = None) → aclimatise.model.Command

Re-analyses the entire command tree using the existing help text but the current parser, and returns the new tree

subcommands: List[aclimatise.model.Command]

A list of subcommands of this command, e.g. “bwa” has the subcommand “bwa mem”

usage: List[aclimatise.usage_parser.model.UsageInstance]

Different usage examples provided by the help

usage_flag: Optional[aclimatise.model.Flag]

If identified, this is the flag that returns usage examples

valid_subcommand(compare_depth=1) → bool

Returns true if command is a valid subcommand, relative to its parent

version_flag: Optional[aclimatise.model.Flag]

If identified, this is the flag that returns the version of the executable

Command Inputs

class aclimatise.model.CliArgument(description: str, optional: bool = False)

A generic parent class for both named and positional CLI arguments

description: str

Description of the function of this argument

abstract full_name() → str

Return a human-readable representation of this argument

abstract get_type() → aclimatise.cli_types.CliType

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

optional: bool

If true, this argument is not required

class aclimatise.model.Positional(*, optional: bool = False, position: int, name: str, description: str)

A positional command-line argument. This probably means that it is required, and has no arguments like flags do

description: str

A description of the function of this argument

full_name() → str

Getting the full name for a positional argument is easy - it’s just the parameter name

get_type() → aclimatise.cli_types.CliType

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

static merge(other: List[aclimatise.model.Positional]) → aclimatise.model.Positional

Combine the information contained within two Positionals, and return the new Positional

name: str

The name of this argument

position: int

The position in the command line that this argument must occupy

class aclimatise.model.Flag(*, optional: bool = True, synonyms: List[str], description: Optional[str], args: FlagArg)

Represents one single flag, with all synonyms for it, and all arguments, e.g. -h, –help

args: aclimatise.model.FlagArg

Describes the arguments to this flag, e.g. -n 1 has a single numeric argument

static combine(flag_lists: Iterable[Iterable[aclimatise.model.Flag]]) → Iterable[aclimatise.model.Flag]

Combines the flags from several sources, choosing the first one preferentially

description: Optional[str]

A description of the function of this flag

static from_synonyms(synonyms: Iterable[aclimatise.model.FlagSynonym], description: Optional[str])

Creates a usable Flag object by combining the synonyms provided

full_name() → str

Getting the full name for a named flag is slightly harder, we need to find the longest synonym

get_type() → aclimatise.cli_types.CliType

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

property longest_synonym

Returns the longest synonym this flag has. e.g. for -h, –help, it will return –help

static merge(flags: List[aclimatise.model.Flag]) → aclimatise.model.Flag

Combine the information contained within two Flags, and return the new Flag

optional: bool

If true, this argument is not required

property shortest_synonym

Returns the shortest synonym this flag has. e.g. for -h, –help, it will return -h

synonyms: List[str]

A list of different ways to invoke this same option, e.g. -v and --verbose

variable_name(description_name: List[str] = []) → List[str]

Returns a list of words that should be used in a variable name for this argument

class aclimatise.model.FlagSynonym(name: str, argtype: FlagArg)

Internal class for storing the arguments for a single synonym

argtype: aclimatise.model.FlagArg

The number and type of arguments that this flag takes

name: str

The entire flag string, e.g. “-n” or “–lines”

Flag Arguments

class aclimatise.model.FlagArg

The data model for the argument or arguments for a flag, for example a flag might have no arguments, it might have one argument, it might accept one option from a list of options, or it might accept an arbitrary number of inputs

abstract get_type() → aclimatise.cli_types.CliType

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

abstract num_args() → int

Calculate the multiplicity of this argument

text() → List[str]

Returns the text of the argument, e.g. for name generation purposes

class aclimatise.model.EmptyFlagArg

A flag that has no arguments, e.g. –quiet that is either present or not present

get_type()

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

num_args() → int

Calculate the multiplicity of this argument

class aclimatise.model.OptionalFlagArg(names: list, separator: str)

When the flag has multiple arguments, some of which are optional, e.g. -I FLOAT[,FLOAT[,INT[,INT]]]

get_type()

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

names: list

Names of each argument

num_args() → int

Calculate the multiplicity of this argument

separator: str

Separator between each argument

text() → List[str]

Returns the text of the argument, e.g. for name generation purposes

class aclimatise.model.SimpleFlagArg(name: str)

When a flag has one single argument, e.g. -e PATTERN, where PATTERN is the argument

get_type()

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

name: str

Name of this argument

num_args() → int

Calculate the multiplicity of this argument

text() → List[str]

Returns the text of the argument, e.g. for name generation purposes

class aclimatise.model.RepeatFlagArg(name: str)

When a flag accepts 1 or more arguments, e.g. –samout SAMOUTS [SAMOUTS …]

get_type()

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

name: str

The name of this argument

num_args() → int

Calculate the multiplicity of this argument

text() → List[str]

Returns the text of the argument, e.g. for name generation purposes

class aclimatise.model.ChoiceFlagArg(choices: Set[str])

When a flag accepts one option from a list of options, e.g. -s {yes,no,reverse}

choices: Set[str]

Set of possible choices that could be used for this argument

get_type()

Return a type object indicating the type of data this argument holds. e.g. If it’s an array type this will be a CliList.

num_args() → int

Calculate the multiplicity of this argument

text() → List[str]

Returns the text of the argument, e.g. for name generation purposes

Argument Types

Contains the objects that represent a “type” of data a flag argument might store

class aclimatise.cli_types.CliBoolean

Bases: aclimatise.cli_types.CliType

Takes a boolean value

class aclimatise.cli_types.CliDict(key: aclimatise.cli_types.CliType, value: aclimatise.cli_types.CliType)

Bases: aclimatise.cli_types.CliType

Takes a dictionary value

key: aclimatise.cli_types.CliType

Data type of the keys to this dictionary

value: aclimatise.cli_types.CliType

Data type of the values to this dictionary

class aclimatise.cli_types.CliDir(output: bool = False)

Bases: aclimatise.cli_types.CliFileSystemType

Takes a directory path

output: bool

Indicator if it is input or output

class aclimatise.cli_types.CliEnum(enum: enum.Enum)

Bases: aclimatise.cli_types.CliType

One of a list of possible options

enum: enum.Enum

The possible options as a Python Enum

class aclimatise.cli_types.CliFile(output: bool = False)

Bases: aclimatise.cli_types.CliFileSystemType

Takes a file path

output: bool

Indicator if it is input or output

class aclimatise.cli_types.CliFileSystemType(output: bool = False)

Bases: aclimatise.cli_types.CliType

Takes a directory / file path

output: bool

Indicator if it is input or output

class aclimatise.cli_types.CliFloat

Bases: aclimatise.cli_types.CliType

Takes a floating-point value

class aclimatise.cli_types.CliInteger

Bases: aclimatise.cli_types.CliType

Takes an integer value

class aclimatise.cli_types.CliList(value: aclimatise.cli_types.CliType)

Bases: aclimatise.cli_types.CliType

Takes a list value

value: aclimatise.cli_types.CliType

Data type of the values in this list

class aclimatise.cli_types.CliString

Bases: aclimatise.cli_types.CliType

Takes a string value

class aclimatise.cli_types.CliTuple(values: List[aclimatise.cli_types.CliType])

Bases: aclimatise.cli_types.CliType

Takes a list of values with a fixed length, possibly each with different types

property homogenous

A tuple is homogenous if all types in the tuple are the same, aka the set of all types has length 1

values: List[aclimatise.cli_types.CliType]

List of types, in order, held within the tuple

class aclimatise.cli_types.CliType

Bases: aclimatise.yaml.AttrYamlMixin

A data type used in the command-line

static lowest_common_type(types: Iterable[aclimatise.cli_types.CliType]) → aclimatise.cli_types.CliType

property representable

Returns a set of types that this type could alternatively be represented as. Adds the class’s own type to the _representable set