ptypes module¶

This module provides several pseudo-type definitions which can be enforced and/or validated with custom contracts defined using the putil.pcontracts module

Pseudo-types¶

ColorSpaceOption¶

String representing a Matplotlib color space, one 'binary', 'Blues', 'BuGn', 'BuPu', 'GnBu', 'Greens', 'Greys', 'Oranges', 'OrRd', 'PuBu', 'PuBuGn', 'PuRd', 'Purples', 'RdPu', 'Reds', 'YlGn', 'YlGnBu', 'YlOrBr‘, 'YlOrRd' or None

CsvColFilter¶

String, integer, a list of strings or a list of integers that identify a column or columns within a comma-separated values (CSV) file.

Integers identify a column by position (column 0 is the leftmost column) whereas strings identify the column by name. Columns can be identified either by position or by name when the file has a header (first row of file containing column labels) but only by position when the file does not have a header.

None indicates that no column filtering should be done

CsvColSort¶

Integer, string, dictionary or list of integers, strings or dictionaries that specify the sort direction of a column or columns in a comma-separated values (CSV) file.

The sort direction can be either ascending, specified by the string 'A', or descending, specified by the string 'B' (case insensitive). The default sort direction is ascending.

The column can be specified numerically or with labels depending on whether the CSV file was loaded with or without a header.

The full specification is a dictionary (or list of dictionaries if multiple columns are to be used for sorting) where the key is the column and the value is the sort order, thus valid examples are {'MyCol':'A'} and [{'MyCol':'A'}, {3:'d'}].

When the default direction suffices it can be omitted; for example in [{'MyCol':'D'}, 3], the data is sorted first by MyCol in descending order and then by the 4th column (column 0 is the leftmost column in a CSV file) in ascending order

CsvDataFilter¶

In its most general form a two-item tuple, where one item is of CsvColFilter pseudo-type and the other item is of CsvRowFilter pseudo-type (the order of the items is not mandated, i.e. the first item could be of pseudo-type CsvRowFilter and the second item could be of pseudo-type CsvColFilter or vice-versa).

The two-item tuple can be reduced to a one-item tuple when only a row or column filter needs to be specified, or simply to an object of either CsvRowFilter or CsvColFilter pseudo-type.

For example, all of the following are valid CsvDataFilter objects: ('MyCol', {'MyCol':2.5}), ({'MyCol':2.5}, 'MyCol') (filter in the column labeled MyCol and rows where the column labeled MyCol has the value 2.5), ('MyCol', ) (filter in column labeled MyCol and all rows) and {'MyCol':2.5} (filter in all columns and only rows where the column labeled MyCol has the values 2.5)

None, (None, ) or (None, None) indicate that no row or column filtering should be done

CsvFiltered¶

String or a boolean that indicates what type of row and column filtering is to be performed in a comma-separated values (CSV) file. If True, 'B' or 'b' it indicates that both row- and column-filtering are to be performed; if False, 'N' or 'n' no filtering is to be performed, if 'R' or 'r' only row-filtering is to be performed, if 'C' or 'c' only column-filtering is to be performed

CsvRowFilter¶

Dictionary whose elements are sub-filters with the following structure:

column identifier (CsvColFilter) – Dictionary key. Column to filter (as it appears in the comma-separated values file header when a string is given) or column number (when an integer is given, column zero is the leftmost column)
value (list of strings or numbers, or string or number) – Dictionary value. Column value to filter if a string or number, column values to filter if a list of strings or numbers

If a row filter sub-filter is a column value all rows which contain the specified value in the specified column are kept for that particular individual filter. The overall data set is the intersection of all the data sets specified by each individual sub-filter. For example, if the file to be processed is:

Ctrl	Ref	Result
1	3	10
1	4	20
2	4	30
2	5	40
3	5	50

Then the filter specification rfilter = {'Ctrl':2, 'Ref':5} would result in the following filtered data set:

Ctrl	Ref	Result
2	5	40

However, the filter specification rfilter = {'Ctrl':2, 'Ref':3} would result in an empty list because the data set specified by the Ctrl individual sub-filter does not overlap with the data set specified by the Ref individual sub-filter.

If a row sub-filter is a list, the items of the list represent all the values to be kept for a particular column (strings or numbers). So for example rfilter = {'Ctrl':[2, 3], 'Ref':5} would result in the following filtered data set:

Ctrl	Ref	Result
2	5	40
3	5	50

None indicates that no row filtering should be done

EngineeringNotationNumber¶

String with a number represented in engineering notation. Optional leading whitespace can precede the mantissa; optional whitespace can also follow the engineering suffix. An optional sign (+ or -) can precede the mantissa after the leading whitespace. The suffix must be one of 'y', 'z', 'a', 'f', 'p', 'n', 'u', 'm', ' ' (space), 'k', 'M', 'G', 'T', 'P', 'E', 'Z' or 'Y'. The correspondence between suffix and floating point exponent is:

Exponent	Name	Suffix
1E-24	yocto	y
1E-21	zepto	z
1E-18	atto	a
1E-15	femto	f
1E-12	pico	p
1E-9	nano	n
1E-6	micro	u
1E-3	milli	m
1E+0
1E+3	kilo	k
1E+6	mega	M
1E+9	giga	G
1E+12	tera	T
1E+15	peta	P
1E+18	exa	E
1E+21	zetta	Z
1E+24	yotta	Y

EngineeringNotationSuffix¶

A single character string, one of 'y', 'z', 'a', 'f', 'p', 'n', 'u', 'm', ' ' (space), 'k', 'M', 'G', 'T', 'P', 'E', 'Z' or 'Y'. EngineeringNotationNumber lists the correspondence between suffix and floating point exponent

FileName¶

String with a valid file name

FileNameExists¶

String with a file name that exists in the file system

Function¶

Callable pointer or None

IncreasingRealNumpyVector¶

Numpy vector in which all elements are real (integers and/or floats) and monotonically increasing (each element is strictly greater than the preceding one)

InterpolationOption¶

String representing an interpolation type, one of 'STRAIGHT', 'STEP', 'CUBIC', 'LINREG' (case insensitive) or None

LineStyleOption¶

String representing a Matplotlib line style, one of '-', '--', '-.', ':' or None

NodeName¶

String where hierarchy levels are denoted by node separator characters ('.' by default). Node names cannot contain spaces, empty hierarchy levels, start or end with a node separator character.

For this example tree:

root
├branch1
│├leaf1
│└leaf2
└branch2

The node names are 'root', 'root.branch1', 'root.branch1.leaf1', 'root.branch1.leaf2' and 'root.branch2'

NodesWithData¶

Dictionary or list of dictionaries; each dictionary must contain exactly two keys:

name (NodeName) Node name. See NodeName pseudo-type specification
data (any) node data

The node data should be an empty list to create a node without data, for example: {'name':'a.b.c', 'data':[]}

NonNegativeInteger¶

Integer greater or equal to zero

OffsetRange¶

Number in the [0, 1] range

PositiveRealNum¶

Integer or float greater than zero or None

RealNum¶

Integer, float or None

RealNumpyVector¶

Numpy vector in which all elements are real (integers and/or floats)

Contracts¶

putil.ptypes.color_space_option(obj)¶

Validates if an object is a ColorSpaceOption pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to RuntimeError (Argument `[argument_name]` is not one of ‘binary’, ‘Blues’, ‘BuGn’, ‘BuPu’, ‘GnBu’, ‘Greens’, ‘Greys’, ‘Oranges’, ‘OrRd’, ‘PuBu’, ‘PuBuGn’, ‘PuRd’, ‘Purples’, ‘RdPu’, ‘Reds’, ‘YlGn’, ‘YlGnBu’, ‘YlOrBr’ or ‘YlOrRd). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.csv_col_filter(obj)¶

Validates if an object is a CsvColFilter pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.csv_col_sort(obj)¶

Validates if an object is a CsvColSort pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.csv_data_filter(obj)¶

Validates if an object is a CsvDataFilter pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.csv_filtered(obj)¶

Validates if an object is a CsvFilter pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.csv_row_filter(obj)¶

Validates if an object is a CsvRowFilter pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to ValueError (Argument `[argument_name]` is empty). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.engineering_notation_number(obj)¶

Validates if an object is an EngineeringNotationNumber pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.engineering_notation_suffix(obj)¶

Validates if an object is an EngineeringNotationSuffix pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.file_name(obj)¶

Validates if an object is a legal name for a file (i.e. does not have extraneous characters, etc.)

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.file_name_exists(obj)¶

Validates if an object is a legal name for a file (i.e. does not have extraneous characters, etc.) and that the file exists

Parameters:	obj (any) – Object
Raises:	OSError (File [fname] could not be found). The token [fname] is replaced by the value of the argument the contract is attached to RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.function(obj)¶

Validates if an object is a function pointer or None

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.increasing_real_numpy_vector(obj)¶

Validates if an object is IncreasingRealNumpyVector pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.interpolation_option(obj)¶

Validates if an object is an InterpolationOption pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to RuntimeError (Argument `[argument_name]` is not one of [‘STRAIGHT’, ‘STEP’, ‘CUBIC’, ‘LINREG’] (case insensitive)). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.line_style_option(obj)¶

Validates if an object is a LineStyleOption pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to RuntimeError (Argument `[argument_name]` is not one of [‘-‘, ‘–’, ‘-.’, ‘:’]). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.non_negative_integer(obj)¶

Validates if an object is a non-negative (zero or positive) integer

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.offset_range(obj)¶

Validates if an object is a number in the [0, 1] range

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.positive_real_num(obj)¶

Validates if an object is a positive integer, positive float or None

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.real_num(obj)¶

Validates if an object is an integer, float or None

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None

putil.ptypes.real_numpy_vector(obj)¶

Validates if an object is a RealNumpyVector pseudo-type object

Parameters:	obj (any) – Object
Raises:	RuntimeError (Argument `[argument_name]` is not valid). The token [argument_name] is replaced by the name of the argument the contract is attached to
Return type:	None