TypeHintedDict

class Stoner.core.base.TypeHintedDict(*args: Any, **kwargs: Any)

Bases: RegexpDict

Extends a blist.sorteddict to include type hints of what each key contains.

The CM Physics Group at Leeds makes use of a standard file format that closely matches the DataFile data structure. However, it is convenient for this file format to be ASCII text for ease of use with other programs. In order to represent metadata which can have arbitrary types, the LabVIEW code that generates the data file from our measurements adds a type hint string. The Stoner Python code can then make use of this type hinting to choose the correct representation for the metadata. The type hinting information is retained so that files output from Python will retain type hints to permit them to be loaded into strongly typed languages (sch as LabVIEW).

_typehints

The backing store for the type hint information

Type:

dict

_regex_get_type

Used to extract the type hint from a string

Type:

re

_regex_signed_int

matches type hint strings for signed integers

Type:

re

_regex_unsigned_int

matches the type hint string for unsigned integers

Type:

re

_regex_float

matches the type hint strings for floats

Type:

re

_regex_boolean

matches the type hint string for a boolean

Type:

re

_regex_strng

matches the type hint string for a string variable

Type:

re

_regex_evaluatable

matches the type hint string for a compoind data type

Type:

re

_types

mapping of type hinted types to actual Python types

Type:

dict

_tests

mapping of the regex patterns to actual python types

Type:

dict

Notes

Rather than subclassing a plain dict, this is a subclass of a blist.sorteddict which stores the entries in a binary list structure. This makes accessing the keys much faster and also ensures that keys are always returned in alphabetical order.

Attributes Summary

allowed_keys
types	Return the dictionary of value types.

Methods Summary

clear()	Remove all items from ordered dict.
copy()	Provide a copy method that is aware of the type hinting strings.
export(key)	Export a single metadata value to a string representation with type hint.
export_all()	Return all the entries in the TypeHintedDict as a list of exported lines.
filter(name)	Filter the dictionary keys by name.
findtype(value)	Determine the correct string type to return for common python classes.
fromkeys(iterable[, value])	Create a new ordered dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
has_key(name)	Key is definitely in dictionary as literal.
import_all(lines)	Read multiple lines of strings and tries to import keys from them.
import_key(line)	Import a single key from a string like key{type hint} = value.
items()	Return a set-like object providing a view on the dict's items.
keys()	Return a set-like object providing a view on the dict's keys.
move_to_end(key[, last])	Move an existing element to the end (or beginning if last is false).
pop(key[,default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
popitem([last])	Remove and return a (key, value) pair from the dictionary.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
type(key)	Return the typehint for the given k(s).
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()	Return an object providing a view on the dict's values.

Attributes Documentation

allowed_keys: Tuple = (<class 'str'>,)

types

Return the dictionary of value types.

Methods Documentation

clear()

Remove all items from ordered dict.

copy() → TypeHintedDict

Provide a copy method that is aware of the type hinting strings.

This produces a flat dictionary with the type hint embedded in the key name.

Returns:

A copy of the current TypeHintedDict

export(key: str | Pattern) → str

Export a single metadata value to a string representation with type hint.

In the ASCII based file format, the type hinted metadata is represented in the first column of a tab delimited text file as a series of lines with format keyname{typhint}=string_value.

Parameters:

key (string) – The metadata key to export

Returns:

A string of the format – key{type hint} = value

export_all() → List[str]

Return all the entries in the TypeHintedDict as a list of exported lines.

Returns:

(list of str) – A list of exported strings

Notes

The keys are returned in sorted order as a result of the underlying blist.sorteddict meothd.

filter(name: str | Pattern | Callable) → None

Filter the dictionary keys by name.

Reduce the metadata dictionary leaving only keys satisfied by name.

Keyword Arguments:

name (str or callable) – either a str to match or a callable function that takes metadata key-value as an argument and returns True or False

findtype(value: Any) → str

Determine the correct string type to return for common python classes.

Parameters:

value (any) – The data value to determine the type hint for.

Returns:

A type hint string

Note

Understands booleans, strings, integers, floats and np arrays(as arrays), and dictionaries (as clusters).

classmethod fromkeys(iterable, value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

has_key(name: Any) → bool

Key is definitely in dictionary as literal.

import_all(lines: List[str]) → None

Read multiple lines of strings and tries to import keys from them.

Parameters:

lines (list of str) – The lines of metadata values to import.

import_key(line: str) → None

Import a single key from a string like key{type hint} = value.

This is the inverse of the TypeHintedDict.export() method.

Parameters:

line (str) – he string line to be interpreted as a key-value pair.

items()

Return a set-like object providing a view on the dict’s items.

keys()

Return a set-like object providing a view on the dict’s keys.

move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(key[, default]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

type(key: str | Pattern | Sequence[str | Pattern]) → str | List[str]

Return the typehint for the given k(s).

This simply looks up the type hinting dictionary for each key it is given.

Parameters:

key (string or sequence of strings) – Either a single string key or a iterable type containing keys

Returns:

The string type hint (or a list of string type hints)

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

Return an object providing a view on the dict’s values.