ace package

A package for converting ADMs from JSON and checking them, and converting ARIs between text URI and CBOR.

class ace.ARI

Bases: object

Base class for all forms of ARI.

class ace.AdmSet(cache_dir: Optional[str] = None)

Bases: object

An isolated set of managed ADM data. Each object of this class keeps a DB session open, so is not thread safe. But multiple instances of the same class can be created with the same underlying shared database.

Parameters:: cache_dir – A specific directory to keep the cache database in. If None, a user default cache path is used. If False, the cache is kept in-memory.

contains_namespace(namespace: str) → bool: Determine if a specific ADM normalized name is known. :return: True if the name s present.

db_session() → Session

Get the database session.

Returns:: The session object, which should not be used in a with context.

get_by_enum(enum: int) → AdmFile

Retreive a specific ADM by its integer enum.

Parameters:: enum – The value to filter on exactly.
Returns:: The ADM
Raises:: KeyError – If the enum is not present.

get_by_norm_name(name: str) → AdmFile

Retreive a specific ADM by its normalized name.

Parameters:: name – The value to filter on exactly.
Returns:: The ADM
Raises:: KeyError – If the name is not present.

get_child(adm: AdmFile, cls: type, norm_name: Optional[str] = None, enum: Optional[int] = None): Get one of the AdmObjMixin -derived child objects.

load_default_dirs() → int

Scan all default ADM store directories for new ADMs. This is based on the XDG_DATA_HOME and XDG_DATA_DIRS environment with the path segments /ace/adms appended.

Returns:: The total number of ADMs read.

load_from_data(buf: BinaryIO, del_dupe: bool = True) → AdmFile

Load an ADM definition from file content.

Parameters:

buf – The file-like object to read from.
del_dupe – Remove any pre-existing ADMs with the same norm_name.

Returns:

The associated AdmFile object if successful.

Raises:

Exception – if the load fails or if the file does not have a “name” metadata object.

load_from_dir(dir_path: str) → int

Scan a directory for JSON files and attempt to read them as ADM definitions.

Parameters:: dir – The directory path to scan.
Returns:: The number of ADMs read from that directory.

load_from_file(file_path: str, del_dupe: bool = True) → AdmFile

Load an ADM definition from a specific file. The ADM may be cached if an earlier load occurred on the same path.

Parameters:

file_path – The file path to read from. This path is normalized for cache use.
del_dupe – Remove any pre-existing ADMs with the same norm_name.

Returns:

The associated AdmFile object if successful.

Raises:

Exception – if the load fails or if the file does not have a “name” metadata object.

names() → Set[str]

Get all loaded ADM normalized names.

Returns:: A set of names.

class ace.Checker(db_sess)

Bases: object

A class which visits objects of the ORM and performs checks to create Issue objects.

Parameters:: db_sess – A database session to operate within.

check(src: Optional[AdmFile] = None)

Check a specific ADM for issues.

Parameters:: src – The ADM to check or None.
Returns:: A list of found Issue objects.

class ace.LiteralARI(type_enum: StructType, value: object)

Bases: ARI

A literal value in the form of an ARI.

check_type(): Validate the value against the type_enum of this object.

type_enum: StructType: ADM type of this value

value: object: Literal value

class ace.ReferenceARI(ident: Identity, params: Optional[List[Union[ARI, AC, EXPR, TNVC]]] = None)

Bases: ARI

The data content of an ARI.

ident: Identity: Identity of the referenced object

params: List[Union[ARI, AC, EXPR, TNVC]] = None: Optional paramerization, None is different than empty list

Submodules

CODEC for converting ADM to and from JSON form.

ace.adm_json.ATTRMAP = {<class 'ace.models.Mdat'>: ['name', 'enum', 'description', 'type', 'value'], <class 'ace.models.Const'>: ['name', 'enum', 'description', 'type', 'value'], <class 'ace.models.Ctrl'>: ['name', 'enum', 'description', 'parmspec'], <class 'ace.models.Edd'>: ['name', 'enum', 'description', 'parmspec', 'type'], <class 'ace.models.Mac'>: ['name', 'enum', 'description', 'parmspec', 'action'], <class 'ace.models.Oper'>: ['name', 'enum', 'description', 'result-type', 'in-type'], <class 'ace.models.Rptt'>: ['name', 'enum', 'description', 'parmspec', 'definition'], <class 'ace.models.Tblt'>: ['name', 'enum', 'description', 'columns'], <class 'ace.models.Var'>: ['name', 'enum', 'description', 'type', 'initializer']}: JSON object keys for each object class (by lower name)

class ace.adm_json.Decoder(db_sess=None)

Bases: object

The decoder portion of this CODEC.

decode(buf: BinaryIO) → AdmFile

Decode a single ADM from file.

Parameters:: buf – The buffer to read from.
Returns:: The decoded ORM root object.

from_json_obj(cls, json_obj)

Construct an ORM object from a decoded JSON object.

Parameters:

cls – The ORM class to instantiate.
json_obj – The decoded JSON to read from.

Returns:

The ORM object.

get_file_time(file_path: str)

Get a consistent file modified time.

Parameters:: file_path – The pathto the file to inspect.
Returns:: The modified time object.
Return type:: datetime.dateteime

class ace.adm_json.Encoder

Bases: object

The encoder portion of this CODEC.

encode(adm: AdmFile, buf: BinaryIO, indent=None)

Decode a single ADM from file.

Parameters:

adm – The ORM root object.
buf – The buffer to write into.
indent – The JSON indentation size or None.

to_json_ari(ari: ARI) → object

Construct an encoded JSON ARI from an ORM ARI.

Parameters:: ari – The ARI to encode.

:return the JSON-able object.

to_json_obj(obj) → object

Construct a encoded JSON object from an ORM object.

Parameters:: obj – The ORM object to read from.
Returns:: The JSON-able object.

ace.adm_json.SECNAMES = {<class 'ace.models.Mdat'>: 'Mdat', <class 'ace.models.Const'>: 'Const', <class 'ace.models.Ctrl'>: 'Ctrl', <class 'ace.models.Edd'>: 'Edd', <class 'ace.models.Mac'>: 'Mac', <class 'ace.models.Oper'>: 'Oper', <class 'ace.models.Rptt'>: 'Rptt', <class 'ace.models.Tblt'>: 'Tblt', <class 'ace.models.Var'>: 'Var'}: JSON key for each object type in the ADM

ace.adm_json.attr_to_member(name): Convert a JSON attribute name into a valid python instance variable name using underscores.

Manage a set of ADMs read in from some filesystem paths and kept in a cache database.

class ace.adm_set.AdmSet(cache_dir: Optional[str] = None)

Bases: object

An isolated set of managed ADM data. Each object of this class keeps a DB session open, so is not thread safe. But multiple instances of the same class can be created with the same underlying shared database.

Parameters:: cache_dir – A specific directory to keep the cache database in. If None, a user default cache path is used. If False, the cache is kept in-memory.

contains_namespace(namespace: str) → bool: Determine if a specific ADM normalized name is known. :return: True if the name s present.

db_session() → Session

Get the database session.

Returns:: The session object, which should not be used in a with context.

get_by_enum(enum: int) → AdmFile

Retreive a specific ADM by its integer enum.

Parameters:: enum – The value to filter on exactly.
Returns:: The ADM
Raises:: KeyError – If the enum is not present.

get_by_norm_name(name: str) → AdmFile

Retreive a specific ADM by its normalized name.

Parameters:: name – The value to filter on exactly.
Returns:: The ADM
Raises:: KeyError – If the name is not present.

get_child(adm: AdmFile, cls: type, norm_name: Optional[str] = None, enum: Optional[int] = None): Get one of the AdmObjMixin -derived child objects.

load_default_dirs() → int

Scan all default ADM store directories for new ADMs. This is based on the XDG_DATA_HOME and XDG_DATA_DIRS environment with the path segments /ace/adms appended.

Returns:: The total number of ADMs read.

load_from_data(buf: BinaryIO, del_dupe: bool = True) → AdmFile

Load an ADM definition from file content.

Parameters:

buf – The file-like object to read from.
del_dupe – Remove any pre-existing ADMs with the same norm_name.

Returns:

The associated AdmFile object if successful.

Raises:

Exception – if the load fails or if the file does not have a “name” metadata object.

load_from_dir(dir_path: str) → int

Scan a directory for JSON files and attempt to read them as ADM definitions.

Parameters:: dir – The directory path to scan.
Returns:: The number of ADMs read from that directory.

load_from_file(file_path: str, del_dupe: bool = True) → AdmFile

Load an ADM definition from a specific file. The ADM may be cached if an earlier load occurred on the same path.

Parameters:

file_path – The file path to read from. This path is normalized for cache use.
del_dupe – Remove any pre-existing ADMs with the same norm_name.

Returns:

The associated AdmFile object if successful.

Raises:

Exception – if the load fails or if the file does not have a “name” metadata object.

names() → Set[str]

Get all loaded ADM normalized names.

Returns:: A set of names.

The logical data model for an ARI and associated AMP data. This is distinct from the ORM in models used for ADM introspection.

class ace.ari.AC(items: ~typing.List[~typing.Union[~ace.ari.ARI, ~ace.ari.AC, ~ace.ari.EXPR]] = <factory>)

Bases: object

An ARI Collection (AC).

items: List[Union[ARI, AC, EXPR]]

class ace.ari.ARI

Bases: object

Base class for all forms of ARI.

class ace.ari.EXPR(type_enum: ~ace.ari.StructType, items: ~typing.List[~ace.ari.ARI] = <factory>)

Bases: object

An Expression (EXPR).

items: List[ARI]

type_enum: StructType: ADM type of the result value

class ace.ari.Identity(namespace: Optional[Union[str, int]] = None, type_enum: Optional[StructType] = None, name: Optional[Union[bytes, int]] = None, issuer: Optional[bytes] = None, tag: Optional[bytes] = None)

Bases: object

The identity of a reference ARI as a unique name-set.

issuer: Optional[bytes] = None

name: Optional[Union[bytes, int]] = None: Name with the type removed

namespace: Optional[Union[str, int]] = None: The None value indicates the absense of a URI path component

strip_name(): If present, strip parameters off of the name portion.

tag: Optional[bytes] = None

type_enum: Optional[StructType] = None: ADM type of the referenced object

ace.ari.LITERAL_TYPES = {StructType.UNK, StructType.BOOL, StructType.BYTE, StructType.STR, StructType.INT, StructType.UINT, StructType.VAST, StructType.UVAST, StructType.REAL32, StructType.REAL64, StructType.TV, StructType.TS, StructType.BSTR}: All literal struct types

class ace.ari.LiteralARI(type_enum: StructType, value: object)

Bases: ARI

A literal value in the form of an ARI.

check_type(): Validate the value against the type_enum of this object.

type_enum: StructType: ADM type of this value

value: object: Literal value

class ace.ari.ReferenceARI(ident: Identity, params: Optional[List[Union[ARI, AC, EXPR, TNVC]]] = None)

Bases: ARI

The data content of an ARI.

ident: Identity: Identity of the referenced object

params: List[Union[ARI, AC, EXPR, TNVC]] = None: Optional paramerization, None is different than empty list

class ace.ari.StructType(value)

Bases: IntEnum

The enumeration of ADM data types from Section 5.4 of ADM draft.

AC = 37

ARI = 36

BOOL = 16

BSTR = 39

BYTE = 17

CONST = 0

CTRL = 1

EDD = 2

EXPR = 38

INT = 19

LIT = 3

MAC = 4

MDAT = -1

OPER = 5

REAL32 = 23

REAL64 = 24

RPTT = 7

SBR = 8

STR = 18

TBLT = 10

TBR = 11

TNVC = 35

TS = 33

TV = 32

UINT = 20

UNK = -25

UVAST = 22

VAR = 12

VAST = 21

class ace.ari.TNVC(items: ~typing.List[~typing.Union[~ace.ari.ARI, ~ace.ari.AC, ~ace.ari.EXPR]] = <factory>)

Bases: object

A pseudo-class based on ADM requirements, but not representable as text ARI. In text form this is really an AC and gets converted by nickname handling.

items: List[Union[ARI, AC, EXPR]]

CODEC for converting ARI to and from CBOR form.

class ace.ari_cbor.AriFlag(value)

Bases: IntFlag

Flags at the front of an ARI.

HAS_ISS = 32

HAS_NN = 128

HAS_PARAMS = 64

HAS_TAG = 16

class ace.ari_cbor.Decoder

Bases: object

The decoder portion of this CODEC.

decode(buf: BinaryIO) → ARI

Decode an ARI from CBOR bytestring.

Parameters:: buf – The buffer to read from.
Returns:: The decoded ARI.

class ace.ari_cbor.Encoder

Bases: object

The encoder portion of this CODEC.

encode(obj: ARI, buf: BinaryIO)

Encode an ARI into CBOR bytestring.

Parameters:

obj – The ARI object to encode.
buf – The buffer to write into.

exception ace.ari_cbor.ParseError

Bases: RuntimeError

Indicate an error in ARI parsing.

class ace.ari_cbor.TnvcFlag(value)

Bases: IntFlag

Flgas at the front of a TNVC.

MIXED = 8

NAME = 2

TYPE = 4

VALUE = 1

Utilities to convert to CBOR diagnostic notation.

ace.cborutil.from_hexstr(text: str) → bytes

Convert hexstr text into byte string.

Parameters:: text – The hexstring.
Returns:: Decoded bytes.

ace.cborutil.to_diag(val) → str: Convert a Python object to CBOR diagnostic notation.

ace.cborutil.to_hexstr(data: bytes) → str

Convert a byte string into hexstr text.

Parameters:: data – The byte string.
Returns:: Encoded text.

ORM models for the ADM and its contents.

class ace.models.AC(**kwargs)

Bases: Base

An ARI Collection (AC). Used by macros to define the action, used by reports to define the contents.

There is no explicit relationship to the object which contains this type.

id

items

class ace.models.ARI(**kwargs)

Bases: Base

A single non-literal ARI

ap: Optional parameters

id

list: Relationship to the AC

list_id: Optional containing AC

nm: Name

ns: Namespace

position: ordinal of this parameter in an AC (if part of an AC)

class ace.models.AdmFile(**kwargs)

Bases: Base

The ADM file itself and its source (filesystem) metadata

abs_file_path: Fully resolved path from which the ADM was loaded

adm_ns: non normalized namespace

const

ctrl

edd

enum: Enumeration for this ADM

id: Unique ID of the row

last_modified: Modified Time from the source file

mac

mdat

norm_name: Normalized ADM name (for searching)

norm_namespace: Normalized ADM namespace (for searching)

oper

rptt

tblt

uses

var

class ace.models.AdmObjMixin

Bases: object

Common attributes of an ADM-defined object.

description = Column(None, String(), table=None): Arbitrary optional text

enum = Column(None, Integer(), table=None): Enumeration for this ADM

name = Column(None, String(), table=None, nullable=False): Unique name (within a section)

norm_name = Column(None, String(), table=None): Normalized object name (for searching)

class ace.models.AdmUses(**kwargs)

Bases: Base

Each “uses” of an ADM

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

id

namespace: Original exact text

norm_namespace: Normalized text for searching

position: ordinal of this item in the list

class ace.models.AriAP(**kwargs)

Bases: Base

Defining each parameter used by an ARI

ari: Relationship to the parent Oper

ari_id: ID of the Oper for which this is a parameter

id

position: ordinal of this parameter in an ARI list

type

value

ace.models.CURRENT_SCHEMA_VERSION = 12: Value of SchemaVersion.version_num

class ace.models.Const(**kwargs)

Bases: Base, AdmObjMixin

Constant value (CONST)

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

type

value

class ace.models.Ctrl(**kwargs)

Bases: Base, AdmObjMixin

Control

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

parmspec

parmspec_id: Parameters of this object

class ace.models.Edd(**kwargs)

Bases: Base, AdmObjMixin

Externally Defined Data (EDD)

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

parmspec

parmspec_id: Parameters of this object

type

class ace.models.Expr(**kwargs)

Bases: Base

Expression (EXPR)

id

postfix: Relationship to the AC

postfix_id: The AC defining the postfix expression

type: Result type of the expression

class ace.models.Mac(**kwargs)

Bases: Base, AdmObjMixin

Macro (MAC) - an ordered collection of Controls or of other Macros

action: Relationship to the AC object

action_id: Reference to the EXPR action of this macro

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

parmspec

parmspec_id: Parameters of this object

class ace.models.Mdat(**kwargs)

Bases: Base, AdmObjMixin

Metadata about the ADM

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

type: Not really used

value: The metadata value text

class ace.models.Oper(**kwargs)

Bases: Base, AdmObjMixin

Operator (Oper) used in EXPR postfix

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

in_type

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

result_type

class ace.models.OperParm(**kwargs)

Bases: Base

Defining each parameter used by an Oper

id

oper: Relationship to the parent Oper

oper_id: ID of the Oper for which this is a parameter

position: ordinal of this parameter in an Oper

type

class ace.models.Rptt(**kwargs)

Bases: Base, AdmObjMixin

Report Template (RPTT)

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

definition

definition_id: Items present in the report

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

parmspec

parmspec_id: Parameters of this object

class ace.models.SchemaVersion(**kwargs)

Bases: Base

Identify the version of a DB.

version_num

class ace.models.Tblt(**kwargs)

Bases: Base, AdmObjMixin

Table Template (TBLT)

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

columns

columns_id: Columns present in the table

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

class ace.models.TypeNameItem(**kwargs)

Bases: Base

Each item within a TypeNameList

id

list

list_id: Containing list

name

position: ordinal of this parameter in a TypeNameList

type

class ace.models.TypeNameList(**kwargs)

Bases: Base

A list of typed, named items (e.g. parameters or columns)

id

items

class ace.models.Var(**kwargs)

Bases: Base, AdmObjMixin

Variable value (VAR)

admfile: Relationship to the AdmFile

admfile_id: ID of the file from which this came

description: Arbitrary optional text

enum: Enumeration for this ADM

id: Unique ID of the row

initializer

initializer_id

name: Unique name (within a section)

norm_name: Normalized object name (for searching)

type

Perform conversion to and from nickname content in ARIs.

class ace.nickname.AdmObjType(value)

Bases: IntEnum

An enumeration.

CONST = 0

CTRL = 1

EDD = 2

MAC = 3

MDAT = 10

OPER = 4

RPTT = 5

SBR = 6

TBLT = 7

TBR = 8

VAR = 9

class ace.nickname.Converter(mode: Mode, adms: AdmSet, must_nickname: bool = False)

Bases: object

This class traverses an ARI and converts all contents to or from nickname data based on an AdmSet database.

Parameters:

mode – The conversion mode.
adms – The AdmSet to look up nicknames.
must_nickname – If true, the conversion will fail if no nickname

is available.

class ace.nickname.Mode(value)

Bases: Enum

The Converter conversion direction

FROM_NN = 2: Interpret nickname enums

TO_NN = 1: Obtain nickname enums

ace.nickname.ORM_TYPE = {StructType.MDAT: <class 'ace.models.Mdat'>, StructType.CONST: <class 'ace.models.Const'>, StructType.CTRL: <class 'ace.models.Ctrl'>, StructType.EDD: <class 'ace.models.Edd'>, StructType.MAC: <class 'ace.models.Mac'>, StructType.OPER: <class 'ace.models.Oper'>, StructType.RPTT: <class 'ace.models.Rptt'>, StructType.TBLT: <class 'ace.models.Tblt'>, StructType.VAR: <class 'ace.models.Var'>}: ORM relationship attribute for each ARI reference type

Algorithms that rely on the ACE data models.

ace.util.find_ident(db_sess: sqlalchemy.orm.Session, ident: ace.ari.Ident)

Search for a specific referenced object.

Parameters:: ident – The object identity to search for.
Returns:: The found object or None.

ace.util.get_ident(obj: ace.models.ARI) → ace.ari.Ident

Extract an Ident object from an ADM’s ARI.

Parameters:: obj – The ORM object from an ADM.
Returns:: The object identity.

ace.util.is_printable(name: bytes) → bool

ace.util.normalize_ident(text: str) → str

Normalize an identity component (namespace or name) to make lookup in the database consistent and output in tools like CAmp consistent.

Parameters:: text – The text to normalize.
Returns:: Normalized text.

ace package

Subpackages

Submodules