xmu.containers

Defines containers to read and write various EMu objects

class xmu.containers.EMuConfig(path: str = None)[source]

Bases: MutableMapping

Reads and writes a configuration file

Automatically loaded when EMuRecord is first accessed. The current configuration can be accessed using the config attribute on each of the EMu classes.

Parameters:: path (str) – path to the config file. If omitted, checks the current and home directories for the file.

path

path to the config file

Type:: str

title

title to write at the top of the config file

Type:: str

filename

default filename for config file

Type:: str

classes

list of classes to add the config object to

Type:: list

load_rcfile(path: str = None) → dict[source]

Loads a configuration file

Parameters:: path (str, optional) – path to the rcfile. If not given, checks the current then home directory for the filename.
Returns:: either a custom configuration loaded from a file or the default configuration defined in this function
Return type:: dict

save_rcfile(path: str = None, overwrite: bool = False) → None[source]

Saves a configuration file

Parameters:

path (str) – path for the rcfile. If a directory, adds the filename. Defaults to the user’s home directory.
overwrite (bool) – whether to overwrite the file if it exists

update(obj: dict, path: list = None) → None[source]

Recusrively updates configuration from dict

Parameters:

obj (dict) – configuration object. User should always supply a dict, although the function itself may pass a variety of object types here.
path (list, optional) – path to the current item. User should omit.

Return type:

None

class xmu.containers.EMuSchema(*args, **kwargs)[source]

Bases: dict

Reads and queries an EMu schema file

Sets the schema class attribute on all classes defined in this module when called. If a schema_path is specified in the config file, the schema is loaded automatically the first time an EMuRecord is created.

Parameters:

args – any arguments that can be used to create a dict. If a single string, tries to load the dict from the path represented by that string. If omitted, will check the config attribute for a schema path.
kwargs – any arguments that can be used to create a dict. If a single string, tries to load the dict from the path represented by that string. If omitted, will check the config attribute for a schema path.

path

path to the schema file, if used

Type:: str

visible_only

whether to resolve fields without an ItemName attribute in the schema

Type:: bool

validate_paths

whether to validate paths as they are added to an EMuRecord

Type:: bool

config

module-wide configuration parameters. Set automatically when an EMuConfig object is created.

Type:: EMuConfig

property modules: list[str]: Gets the list of modules in the schema

get(key: str, default: Any = None) → Any[source]

Overrides the native get method to support paths

Parameters:

key (str) – key to retrieve
default (Any, optional) – default value to return if key not found

Returns:

value for the key or default if not found

Return type:

Any

from_file(path: str) → None[source]

Loads schema from a file, creating a JSON version if not found

Parameters:: path (str) – path to a schema file

from_pl(path: str) → None[source]

Loads schema from an EMu schema.pl file

Parameters:: path (str) – path to a schema file

from_json(path: str) → None[source]

Loads schema from JSON

Parameters:: path (str) – path to a JSON schema file

to_json(path: str, **kwargs) → None[source]

Saves schema to JSON

Parameters:

path (str) – path to a JSON schema file
kwargs – keyword arguments to pass to json.dump() to control the format of the JSON file. Method saves the JSON compactly by default.

fields() → Generator[source]

Iterates over all modules and fields

Yields:: tuple – module name, fields

walk() → Generator[str, str, dict][source]

Iterates over all fields in the schema

Yields:: tuple – (module, field, field info) for each field

define_group(module: str, fields: list) → None[source]

Maps a group definition to each member field

Groups are read from a schema if possible but can also be defined manually.

Parameters:

module (str) – backend module name
fields (list) – list of fields in the group

static get_field_info(module: str, path: str, allow_hidden: bool = None, allow_views: bool = None) → dict[source]

Gets data about the field specified by a path

Parameters:

module (str) – backend module name
path (str) – path to the field in EMu
allow_hidden (bool) – whether to resolve fields that do not appear in the client
allow_views (bool) – whether to resolve views

Returns:

information about the field (names, data types, etc.)

Return type:

dict

static map_short_name(module: str, key: str) → str[source]

Maps a short column name to the full name

The short name omits either the tab suffix, ref suffix, or both. Short names are used inside tables and by the EMu API.

Parameters:

module (str) – backend module name
key (str) – the EMu field name

Returns:

The full column name

Return type:

str

static get_client_path(module: str, path: str | list[str] | tuple[str])[source]

Gets the client path for a given field or path

Parameters:

module (str) – backend module name
path (str | list[str] | tuple[str]) – path to the field in EMu

Returns:

the path to the field in the format used by EMu, for example, in the estandards module

Return type:

str

static get_group_info(module: str, path: str | list[str]) → dict[source]

Gets data about the group the path belongs to

Parameters:

module (str) – backend module name
path (str) – path to the field in EMu
allow_hidden (bool) – whether to resolve fields that do not appear in the client
allow_views (bool) – whether to resolve views

Returns:

information about the field (names, data types, etc.)

Return type:

dict

class xmu.containers.EMuColumn(vals: list = None, module: str = None, field: str = None, dict_class: Callable = None, list_class: Callable = None)[source]

Bases: list

Reads and writes data in a table field

Parameters:

vals (iterable) – values for the column
module (str) – backend name of an EMu module
field (str) – name of an EMu field
dict_class (EMuRecord) – class to use for dicts
list_class (EMuColumn) – class to use for lists

module

backend name of an EMu module

Type:: str

field

name of an EMu field

Type:: str

dict_class

class to use for dicts

Type:: EMuRecord

list_class

class to use for lists

Type:: EMuColumn

config

module-wide configuration parameters. Set automatically when an EMuConfig object is created.

Type:: EMuConfig

schema

info about a specific EMu configuration. Set automatically when an EMuSchema object is created.

Type:: EMuSchema

insert(i: int, val: Any) → None[source]: Insert object before index.

append(val: Any) → None[source]: Append object to the end of the list.

extend(vals: list) → None[source]: Extend list by appending elements from the iterable.

copy() → EMuColumn[source]: Overrides the native list.copy method to return an object of this class

to_xml(root: etree.Element | etree.SubElement = None, kind: str = None, row_ids: tuple = None) → etree.Element[source]

Converts column to XML formatted for EMu

Normally called without specifying arguments.

Parameters:

root (lxml.etree.Element | lxml.etree.SubElement) – parent element in the XML tree
kind (str) – kind of XML file. One of “import”, “update”, or “emu”.
row_ids (tuple) – list of values for the tuple group attribute

Returns:

table as XML

Return type:

lxml.etree.Element or SubElement

class xmu.containers.EMuRow(rec: EMuRecord, path: str, index: int, fill_value: Any = None)[source]

Bases: MutableMapping

Reads and writes data in a grid row

Changes to the row are reflected in the original EMuRecord

Parameters:

rec (EMuRecord) – the EMu record the grid is from
path (str) – path to a field that is part of the grid
index (int) – the index of the row
fill_value (Any) – value used when deleting an item from the row

group

names for all columns that are part of the parent grid, whether they appear in the current record or not

Type:: tuple

fill_value

value used when deleting an item from the row

Type:: Any

config

module-wide configuration parameters. Set automatically when an EMuConfig object is created.

Type:: EMuConfig

schema

info about a specific EMu configuration. Set automatically when an EMuSchema object is created.

Type:: EMuSchema

property columns: list[str]: List of columns in the row that exist in the record

property replace_mod: str: Modifier needed to replace a cell in this row in an import

row_id() → str[source]: Calculates an identifier based on the index and content of a row

class xmu.containers.EMuGrid(rec: EMuRecord, path: str, fill_value: Any = None)[source]

Bases: MutableSequence

Reads and writes data in a grid

Changes to the grid are reflected in the original EMuRecord

Parameters:

rec (EMuRecord) – the EMu record the grid is from
path (str) – path to a field that is part of the grid
fill_value (Any) – value used when padding columns
pad (bool) – whether to pad the columns to the same length

group

names for all columns that are part of this grid, whether they appear in the current record or not

Type:: tuple

fill_value

value to use when padding the grid or deleting an item from an EMuRow object created from this grid

Type:: Any

columns

config

module-wide configuration parameters. Set automatically when an EMuConfig object is created.

Type:: EMuConfig

schema

info about a specific EMu configuration. Set automatically when an EMuSchema object is created.

Type:: EMuSchema

property columns: list[str]: List of columns in the grid that exist in the record

verify() → None[source]

Checks if any fields in the grid are missing from the record

Return type:: None
Raises:: ValueError – if fields are missing

insert(*args) → None[source]: S.insert(index, value) – insert value before index

add_columns(cols: list = None, fill_value: Any = None, omit_calculated: bool = False) → EMuGrid[source]

Adds missing columns to the grid

Parameters:

cols (list-like) – columns to add. If not given, adds all columns in the group attribute that do not already appear in the record.
fill_value (Any) – the value used to pad a column. Defaults to fill_value attribute of the instance if not given.
omit_calculated (bool) – whether to include calculated columns, for example, unit conversions. Calcualted columns must be defined in the config file.

Return type:

self

pad(fill_value: Any = None) → EMuGrid[source]

Pads all columns in the table to the same length

Parameters:: fill_value (Any) – the value used to pad a column. Defaults to fill_value attribute if not given.
Returns:: the instance of EMuGrid from which this method was called
Return type:: EMuGrid

filter(where: dict = None, field: str = None) → list[Any][source]

Filters the grid

Parameters:

where (dict) – the query as a dict. A row must match all criteria to be returned.
field (str) – a specific column to return. If empty, the whole row is returned.

Returns:

list of matching rows or values

Return type:

list[Any]

sort(key: int | str | Callable, reverse: bool = False)[source]

Sorts the grid by a single field

Parameters:

key (int | str | Callable) – the key or function to use to sort the grid
reverse (bool) – whether to sort the grid in reverse

Return type:

None

class xmu.containers.EMuRecord(rec: str | dict = None, module: str = None, field: str = None, dict_class: Callable = None, list_class: Callable = None)[source]

Bases: dict

Reads and writes data in an EMu record

Parameters:

rec (str | dict) – record as a mapping or iterable
module (str) – backend name of an EMu module
field (str) – name of an EMu field
dict_class (Callable) – class to use for dicts
list_class (Callable) – class to use for lists

module

backend name of an EMu module

Type:: str

field

name of an EMu field

Type:: str

dict_class

class to use for dicts. Defaults to DEFAULT_RECORD constant if not provided.

Type:: Callable

list_class

class to use for lists. Defaults to DEFAULT_COLUMN constant if not provided.

Type:: Callable

config

module-wide configuration parameters. Set automatically when an EMuConfig object is created.

Type:: EMuConfig

schema

info about a specific EMu configuration. Set automatically when an EMuSchema object is created.

Type:: EMuSchema

get(key: Hashable, default: Any = None) → Any[source]: Overrides the native dict.get method to map unrecognized terms

setdefault(key: Hashable, val: Any) → Any[source]: Overrides the native dict.setdefault method to use the subclass setter

update(*args, **kwargs) → None[source]: Overrides the native dict.update method to use the subclass setter

copy() → EMuRecord[source]: Overrides the native dict.copy method to return an object of this class

json(**kwargs) → str[source]

Converts record to JSON

Parameters:: kwargs – any kwarg accepted by json.dumps
Returns:: record as JSON string
Return type:: str

grid(field: str, **kwargs) → EMuGrid[source]

Returns the EMuGrid object containing the given field

Parameters:

field (str) – any field name that appears in a grid
kwargs – keyword agruments for EMuGrid

Returns:

the grid from the current record

Return type:

EMuGrid

to_xml(root: etree.Element | etree.SubElement = None, kind: str = None) → etree.Element[source]

Converts record to XML formatted for EMu

Normally called without specifying arguments.

Parameters:

root (lxml.etree.Element or lxml.etree.SubElement) – parent element in the XML tree
kind (str) – kind of XML file. One of “import”, “update”, or “emu”. If not given, assigns “update” if top-level records have irns and “import” if not.

Returns:

record as XML

Return type:

lxml.etree.Element or SubElement

class xmu.containers.EMuEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: JSONEncoder

Encodes objects using EMuRecord and EMuColumn

default(o: Any) → str[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

xmu.containers.DEFAULT_RECORD: alias of EMuRecord

xmu.containers.DEFAULT_COLUMN: alias of EMuColumn