DataclassTable

class openmsistream.utilities.DataclassTable(dataclass_type, *, filepath=None, **kwargs)

Bases: DataclassTableAppendOnly

An atomic csv file linked to a set of dataclass entries. Provides methods for interacting with the set of objects and the file in a thread-safe way.

Parameters:

dataclass_type (dataclasses.dataclass) – The dataclasses.dataclass defining the entries in the table/csv file
filepath (pathlib.Path or None, optional) – The path to the .csv file that should be created (or read from) on startup. The default is a file named after the dataclass type in the current directory.

remove_entries(entry_obj_addresses)

Remove an entry or entries from the table

Parameters:: entry_obj_addresses (hex(id(object)) or list(hex(id(object)))) – a single value or container of entry addresses (object IDs in hex form) to remove from the table
Raises:: ValueError – if any of the hex addresses in entry_obj_addresses is not present in the table

set_entry_attrs(entry_obj_address, **kwargs)

Modify attributes of an entry that already exists in the table

Parameters:

entry_obj_address (hex(id(object))) – The address in memory of the entry object to modify
kwargs (dict) – Attributes to set (keys are names, values are values for those named attrs)

Raises:

ValueError – if entry_obj_address doesn’t correspond to an object listed in the table

add_entries(new_entries)

Add a new set of entries to the table.

Parameters:: new_entries (dataclasses.dataclass or list(dataclasses.dataclass)) – the new entry or entries to add to the table
Raises:: ValueError – if any of the objects in new_entries already exists in the table

as_read_only(): Returns a “read only” version of the table

property csv_header_line: The first line in the CSV file (OS-dependent)

property dataclass_type: The type of the Dataclass objects contained in the table

dump_to_file(reraise_exc=True, retries=2)

Dump the contents of the table to a csv file. Call this to force the file to update and reflect the current state of objects. Automatically called in several contexts.

Parameters:

reraise_exc (bool, optional) – if True, Exceptions raised when writing out to the file will be re-raised
retries (int, optional) – how many times to retry writing out the file

property filepath: Path to the CSV file

classmethod get_command_line_arguments() → Tuple[List[str], Dict[str, Any]]: Return the names of arguments for the logger stream and file levels.

get_entry_attrs(entry_obj_address, *args)

Return copies of all or some of the current attributes of an entry in the table. Returning copies ensures the original objects cannot be modified by accident.

Use args to get a dictionary of desired attribute values returned. If only one arg is given the return value is just that single attribute. The default (no additional arguments) returns a dictionary of all attributes for the entry

Parameters:

entry_obj_address (hex(id(object))) – the address in memory of the object to return copies of attributes for
args (str, optional) – Add other arguments that are names of attributes to get only those specific attributes of the entry

Returns:

copies of some or all attributes for an entry in the table

Return type:

depends on arguments, or dict

Raises:

ValueError – if entry_obj_address doesn’t correspond to an object listed in the table

classmethod get_init_args_kwargs(parsed_args: Namespace) → Tuple[List[str], Dict[str, Any]]

Get the list of init arguments and the dictionary of init keyword arguments for this class given a namespace of, for example, parsed arguments.

Parameters:: parsed_args (argparse.Namespace) – A namespace containing entries needed to determine the init args and kwargs for this class
Returns:: A list of init args
Returns:: A dictionary of init kwargs

property logger: The logger object that the class can use

property n_entries: The number of entries in the file

property obj_addresses: All recognized object hex addresses

obj_addresses_by_key_attr(key_attr_name)

Return a dictionary whose keys are the values of some given attribute for each object and whose values are lists of the addresses in memory of the objects in the table that have each value of the requested attribute.

Useful to find objects in the table by attribute values so they can be efficiently updated without compromising the integrity of the objects in the table and their attributes.

Up to five calls are cached so if nothing changes this happens a little faster.

Parameters:: key_attr_name (str) – the name of the attribute whose values should be used as keys in the returned dictionary
Returns:: A dictionary listing all objects in the table, keyed by their values of key_attr_name
Return type:: dict
Raises:: ValueError – if key_attr_name is not recognized as the name of an attribute for entries in the table