command_interpreter.types – The keyword types

Define enumerate-like classes that allows to map from keys to key types and to the functions that needs to be called to deal with any of them.

It uses pkg_resources and entry points to make the framework extendible

vdat.command_interpreter.types._load_entrypoints(group)

Get all the entry points for the group and load them.

Parameters:

group : string

name of the group to load

Returns:

entry_points : dictionary

key: name; value: callable loaded from the entry point

class vdat.command_interpreter.types._Types

Bases: object

ABC class for the types.

If a type loop exists, it can be accessed as instance.loop or instance['loop']

Attributes:

known_types : list of strings

list of known types

entry_point_group : string

Abstract property with the name of the group to load

entry_point_group

Abstract property with the name of the group to load

known_types

list of known types

class vdat.command_interpreter.types.PrimaryTypes

Bases: vdat.command_interpreter.types._Types

Fill the type<–>function mapping using the vdat.cit.primary entry point.

entry_point_group

Abstract property with the name of the group to load

class vdat.command_interpreter.types.KeywordTypes

Bases: vdat.command_interpreter.types._Types

Fill the type<–>function mapping using the vdat.cit.keyword entry point.

entry_point_group

Abstract property with the name of the group to load

class vdat.command_interpreter.types.ExecuteTypes

Bases: vdat.command_interpreter.types._Types

Fill the type<–>function mapping using the vdat.cit.execute entry point.

entry_point_group

Abstract property with the name of the group to load

vdat.command_interpreter.types.primary_template(target_dir, key_val)

Template for a function that deals with a primary keyword.

It collects the files from the target_dir according to the instructions in key_val, if any and either yield a value or return an iterable.

Parameters:

target_dir : string

directory in which the files must be collected

key_val : dictionary

configuration for the key handle

Yields:

yield a string or iterable of strings

Raises:

CIPrimaryError

if something goes wrong when handling the primary key

vdat.command_interpreter.types.keyword_template(primary, key_val)

Template for a function that deals with a non-primary keyword.

A keyword has a value either statically stored in key_val or its value need to be extracted from the value of the primary file(s).

Parameters:

primary : string

the value of one of the items returned by primary_template()

key_val : dictionary

configuration for the key handle

Returns:

string

value to associate to the keyword

Raises:

CIKeywordError

if something goes wrong when handling the key

vdat.command_interpreter.types.execute_template(primary, config)

For each of the primary entry, this function is called to decide whether to execute or skip the command.

Parameters:

primary : string

the value of one of the items returned by primary_template()

config : dictionary

configuration for the command

Returns:

bool

True: the command is executed; False: the command is skipped

vdat.command_interpreter.types.primary_plain(target_dir, key_val)

Get all the files in target_dir matching the string in key_val['value']

Parameters:

target_dir : string

directory in which the files must be collected

key_val : dictionary

configuration for the key handle

Returns:

iterator

yields file names matching the value recursively

vdat.command_interpreter.types.primary_loop(target_dir, key_val)

Make a nested loop over the set of given keys, in each step of the loop construct the value using python format string syntax and then get all the files matching it.

If the key returns is found, the output string is manipulated according to the instruction in the value of returns. The type of returns can be any available keyword type.

If any of the steps doesn’t produce any file, no value is yielded.

Parameters:

target_dir : string

directory in which the files must be collected

key_val : dictionary

configuration for the key handle

Yields:

string of space separated file names

vdat.command_interpreter.types.primary_groupby(target_dir, key_val)

Loop over all the files matching the value entry. For each one, create a list of file names replacing the regex in pattern with the elements of replace.

Parameters:

target_dir : string

directory in which the files must be collected

key_val : dictionary

configuration for the key handle

Yields:

string of space separated file names

vdat.command_interpreter.types.primary_all_files(target_dir, key_val)

Get all the files in target_dir matching the string in key_val['value'] and returns all the files as a single string, so that they can be used all at once in a command.

This primary type relies on primary_plain() to collect all the files or values.

Parameters:

target_dir : string

directory in which the files must be collected

key_val : dictionary

configuration for the key handle

Returns:

files : list of one element

space separated list of file names or return values.

vdat.command_interpreter.types.keyword_plain(_, key_val)

Returns the value contained in the keyword

Parameters:

primary : string

ignored

key_val : dictionary

configuration for the key handle

Returns:

string

value to associate to the keyword

vdat.command_interpreter.types.keyword_regex(primary, key_val)

Extract a string from the primary using regular expression substitution. If do_split is False (default True), do not split the primary on white spaces and use only the first entry.

After performing the substitution, it checks that the expected number of substitutions is performed; the number is given by the option n_subs (default 1), with the following meaning:

• negative: no check performed
• positive integer: exactly n_subs must be performed
• list of integers: the number of substitutions must be in n_subs
• string: interpreted a [start]:[stop][:step] or [start],[stop][,step] and is used to initialise vdat.command_interpreter.utils.SliceLike; the number of substitutions must be in n_subs, as defined by the above class.

Parameters:

primary : string

primary file name(s)

key_val : dictionary

configuration for the key handle

Returns:

string

string built from the primary file name

Raises:

CIKeywordError

if the number of substitutions is not the expected or the value of the n_subs key is not correct

vdat.command_interpreter.types.keyword_header(primary, key_val)

Extract and parse an fits header keyword from the first file.

Extract the value keyword from the header.

If formatter is not given, cast the value to a string, otherwise use convert it to a string using the give formatter; e.g. "{0:03d}" assumes that the value is an integer and converts it into a zero padded-three digits string; see format string syntax

If extract is in the configuration, it instruct how to build a variable out of the extracted header value using the machinery from keyword_regex().

If do_split keyword is given and is False, the value is extracted from the header of every file, converted to a string and all the values are concatenated with white spaces.

Parameters:

primary : string

primary file name(s)

key_val : dictionary

configuration for the key handle

Returns:

string

value to associate to the keyword

vdat.command_interpreter.types.keyword_format(primary, key_val)

Create a new string formatting value according to the provided keys.

The keys are substituted using format string syntax.

The value of keys is a map between values to substitute in value and keyword types used to extract them from the primary file name. Strings are interpreted as of type plain.

Parameters:

primary : string

primary file name(s)

key_val : dictionary

configuration for the key handle

Returns:

string

value to associate to the keyword

vdat.command_interpreter.types.keyword_fplane_map(primary, key_val)

Create a new ID from the one extracted from primary using the fplane file for the mapping.

For informations about the fplane file parser and the internals, specifically the type of the IDs, see pyhetdex.het.fplane.FPlane and pyhetdex.het.fplane.IFU.

Warning

currently the fplane_file value is a string. If we need more flexibility, we can very easily modify it to act like the in_id key.

Parameters:

primary : string

primary file name(s)

key_val : dictionary

configuration for the key handle

Returns:

string

value to associate to the keyword

vdat.command_interpreter.types.execute_new_file(primary, config)

Given the instructions, the new_file type constructs, for each primary entry, a string and check if it exists on the file system as a file. If the string is a new file, returns True.

The instruction on how to build the string are encoded in the mandatory key value, whose value can be any of the available keyword types.

If the path to the file cannot be easily extracted from the primary itself, it is possible to build it using the path optional key. If path is present, the value of path and the basename from value are joined. path can be either one of the available keyword types or a $identifier, where identifier is an other key in the command configuration (not the execute configuration).

Parameters:

primary : string

the value of one of the items returned by primary_template()

config : dictionary

configuration for the command (not for the type)

Returns:

bool

True: if the output of the keyword handling does not exist

vdat.command_interpreter.types.value_to_dict(value)

If it’s a string, convert it to a dictionary with two entries:

• type: plain
• value: value

And also check that the type entry is in value

Parameters:

value : string or dict

value to check

Returns:

value : dictionary

dictionary defining the type

Raises:

CIKeywordError

if value is not a dictionary or a string