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.

map(func: Callable[[ARI], ARI]) → ARI

Call a mapping on this ARI (after each child ARI if present).

Parameters:: func – The callable visitor for each type object.

visit(visitor: Callable[[ARI], None]) → None

Call a visitor on this ARI and each child ARI.

The base type calls the visitor on itself, so only composing types need to override this function.

Parameters:: visitor – The callable visitor for each type object.

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.

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) → AdmModule

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) → AdmModule

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: AdmModule, 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) → AdmModule

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 AdmModule object if successful.

Raises:

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

load_from_dirs(dir_paths: List[str]) → int

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

Parameters:: dir_paths – The directory paths to scan.
Returns:: The number of ADMs read from that directory.

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

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 AdmModule 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[AdmModule] = 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(value: object = undefined, type_id: Optional[StructType] = None)

Bases: ARI

A literal value in the form of an ARI.

map(func: Callable[[ARI], ARI]) → ARI

Call a mapping on this ARI (after each child ARI if present).

Parameters:: func – The callable visitor for each type object.

type_id: Optional[StructType] = None: ADM type of this value

value: object = undefined: Literal value specific to type_id

visit(visitor: Callable[[ARI], None]) → None

Call a visitor on this ARI and each child ARI.

The base type calls the visitor on itself, so only composing types need to override this function.

Parameters:: visitor – The callable visitor for each type object.

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

Bases: ARI

The data content of an ARI.

ident: Identity: Identity of the referenced object

map(func: Callable[[ARI], ARI]) → ARI

Call a mapping on this ARI (after each child ARI if present).

Parameters:: func – The callable visitor for each type object.

params: Optional[Union[List[ARI], Dict[LiteralARI, ARI]]] = None: Optional paramerization, None is different than empty list

visit(visitor: Callable[[ARI], None]) → None

Call a visitor on this ARI and each child ARI.

The base type calls the visitor on itself, so only composing types need to override this function.

Parameters:: visitor – The callable visitor for each type object.

class ace.StructType(value)

Bases: IntEnum

The enumeration of ARI value types from Section 10.3 of ARI draft.

AC = 17

AM = 18

ARITYPE = 16

BOOL = 1

BYTE = 2

BYTESTR = 11

CBOR = 15

CONST = -2

CTRL = -3

EDD = -4

EXECSET = 20

IDENT = -1

INT = 4

LABEL = 14

LITERAL = 255

NULL = 0

OBJECT = -256

OPER = -6

REAL32 = 8

REAL64 = 9

RPTSET = 21

SBR = -8

TBL = 19

TBR = -10

TD = 13

TEXTSTR = 10

TP = 12

TYPEDEF = -12

UINT = 5

UVAST = 7

VAR = -11

VAST = 6

Subpackages

Submodules

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.

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) → AdmModule

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) → AdmModule

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: AdmModule, 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) → AdmModule

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 AdmModule object if successful.

Raises:

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

load_from_dirs(dir_paths: List[str]) → int

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

Parameters:: dir_paths – The directory paths to scan.
Returns:: The number of ADMs read from that directory.

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

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 AdmModule 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.adm_set.DbRepository(db_sess, file_entries: Optional[List[DirEntry]] = None)

Bases: Repository

get_module_from_handle(handle)

Return the raw module text from the repository

Returns (ref, in_format, text) if found, or None if not found. ref is a string which is used to identify the source of

the text for the user. used in error messages

in_format is one of ‘yang’ or ‘yin’ or None. text is the raw text data

Raises ReadError

get_modules_and_revisions(_ctx)

Return a list of all modules and their revisons

Returns a tuple (modulename, revision, handle), where `handle’ is used in the call to get_module_from_handle() to retrieve the module.

CODEC for converting ADM to and from YANG form.

class ace.adm_yang.Decoder(repos: Repository)

Bases: object

The decoder portion of this CODEC.

decode(buf: TextIO) → AdmModule

Decode a single ADM from file.

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

from_stmt(cls, stmt: Statement) → AdmObjMixin

Construct an ORM object from a decoded YANG statement.

Parameters:

cls – The ORM class to instantiate.
stmt – The decoded YANG 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_yang.EmptyRepos

Bases: Repository

get_modules_and_revisions(ctx)

Return a list of all modules and their revisons

Returns a tuple (modulename, revision, handle), where `handle’ is used in the call to get_module_from_handle() to retrieve the module.

class ace.adm_yang.Encoder

Bases: object

The encoder portion of this CODEC.

encode(adm: AdmModule, buf: TextIO) → None

Decode a single ADM from file.

Parameters:

adm – The ORM root object.
buf – The buffer to write into.

to_stmt(obj: AdmObjMixin, module) → Statement

Construct a YANG statement from an ORM object.

Parameters:: obj – The ORM object to read from.
Returns:: The pyang object.

ace.adm_yang.SELFDIR = '/home/runner/work/dtnma-ace/dtnma-ace/src/ace': Directory containing this file

ace.adm_yang.range_from_text(text: str) → Interval: Parse a YANG “range” statement argument.

ace.adm_yang.range_to_text(ranges: Interval) → str: Construct a YANG “range” statement argument.

ace.adm_yang.search_all_exp(stmt, kywd): Search-one within uses-expanded substatements.

ace.adm_yang.search_one_exp(stmt, kywd): Search-one within uses-expanded substatements.

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.ARI

Bases: object

Base class for all forms of ARI.

map(func: Callable[[ARI], ARI]) → ARI

Call a mapping on this ARI (after each child ARI if present).

Parameters:: func – The callable visitor for each type object.

visit(visitor: Callable[[ARI], None]) → None

Call a visitor on this ARI and each child ARI.

The base type calls the visitor on itself, so only composing types need to override this function.

Parameters:: visitor – The callable visitor for each type object.

ace.ari.DTN_EPOCH = datetime.datetime(2000, 1, 1, 0, 0): Reference for absolute time points

class ace.ari.ExecutionSet(nonce: LiteralARI, targets: List[ARI])

Bases: object

Internal representation of Execution-Set data.

nonce: LiteralARI: Optional nonce value

targets: List[ARI]: The targets to execute

ace.ari.FALSE = LiteralARI(value=False, type_id=<StructType.BOOL: 1>): The false value of the AMM

class ace.ari.Identity(ns_id: Optional[Union[str, int]] = None, ns_rev: Optional[str] = None, type_id: Optional[StructType] = None, obj_id: Optional[Union[str, int]] = None)

Bases: object

The identity of an object reference as a unique identifer-set.

ns_id: Optional[Union[str, int]] = None: The None value indicates a module-relative path.

ns_rev: Optional[str] = None: For the text-form ARI a specific module revision date.

obj_id: Optional[Union[str, int]] = None: Name with the type removed

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

class ace.ari.LiteralARI(value: object = undefined, type_id: Optional[StructType] = None)

Bases: ARI

A literal value in the form of an ARI.

map(func: Callable[[ARI], ARI]) → ARI

Call a mapping on this ARI (after each child ARI if present).

Parameters:: func – The callable visitor for each type object.

type_id: Optional[StructType] = None: ADM type of this value

value: object = undefined: Literal value specific to type_id

visit(visitor: Callable[[ARI], None]) → None

Call a visitor on this ARI and each child ARI.

The base type calls the visitor on itself, so only composing types need to override this function.

Parameters:: visitor – The callable visitor for each type object.

ace.ari.NULL = LiteralARI(value=None, type_id=<StructType.NULL: 0>): The null value of the AMM

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

Bases: ARI

The data content of an ARI.

ident: Identity: Identity of the referenced object

map(func: Callable[[ARI], ARI]) → ARI

Call a mapping on this ARI (after each child ARI if present).

Parameters:: func – The callable visitor for each type object.

params: Optional[Union[List[ARI], Dict[LiteralARI, ARI]]] = None: Optional paramerization, None is different than empty list

visit(visitor: Callable[[ARI], None]) → None

Call a visitor on this ARI and each child ARI.

The base type calls the visitor on itself, so only composing types need to override this function.

Parameters:: visitor – The callable visitor for each type object.

class ace.ari.Report(rel_time: timedelta, source: ARI, items: List[ARI])

Bases: object

Internal representation of Report data.

items: List[ARI]: Items of the report.

rel_time: timedelta: Time of the report relative to the parent :ivar:`ReportSet.ref_time` value.

source: ARI: Source of the report, either a RPTT or CTRL.

class ace.ari.ReportSet(nonce: Optional[Union[bytes, int]], ref_time: datetime, reports: List[Report])

Bases: object

Internal representation of Report-Set data.

nonce: Optional[Union[bytes, int]]: Optional nonce value

ref_time: datetime: The reference time for all contained Report relative-times.

reports: List[Report]: The contained Reports

class ace.ari.StructType(value)

Bases: IntEnum

The enumeration of ARI value types from Section 10.3 of ARI draft.

AC = 17

AM = 18

ARITYPE = 16

BOOL = 1

BYTE = 2

BYTESTR = 11

CBOR = 15

CONST = -2

CTRL = -3

EDD = -4

EXECSET = 20

IDENT = -1

INT = 4

LABEL = 14

LITERAL = 255

NULL = 0

OBJECT = -256

OPER = -6

REAL32 = 8

REAL64 = 9

RPTSET = 21

SBR = -8

TBL = 19

TBR = -10

TD = 13

TEXTSTR = 10

TP = 12

TYPEDEF = -12

UINT = 5

UVAST = 7

VAR = -11

VAST = 6

ace.ari.TRUE = LiteralARI(value=True, type_id=<StructType.BOOL: 1>): The true value of the AMM

class ace.ari.Table(shape: tuple)

Bases: ndarray

Wrapper class to overload some numpy behavior.

static from_rows(rows: List[List]) → Table

Construct and initialize a table from a list of rows.

Parameters:: rows – A row-major list of lists.
Returns:: A new Table object.

ace.ari.UNDEFINED = LiteralARI(value=undefined, type_id=None): The undefined value of the AMM

ace.ari.as_bool(val: ARI) → bool

ace.ari.is_null(val: ARI) → bool

Logic to compare against the NULL value.

Parameters:: val – The value to check.
Returns:: True if equivalent to NULL.

ace.ari.is_undefined(val: ARI) → bool

Logic to compare against the UNDEFINED value.

Parameters:: val – The value to check.
Returns:: True if equivalent to UNDEFINED.

CODEC for converting ARI to and from CBOR form.

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(ari: ARI, buf: BinaryIO)

Encode an ARI into CBOR bytestring.

Parameters:

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

exception ace.ari_cbor.ParseError

Bases: RuntimeError

Indicate an error in ARI parsing.

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.

Dereference objects and types from a model.

class ace.lookup.ActualParameterSet(gparams: Union[List[ARI], Dict[ARI, ARI]], fparams: List[FormalParameter])

Bases: object

An actual parameter set normalized from given parameters based on formal parameters.

Parameters:

gparams – The given parameters from a :cls:`ReferenceARI` value.
fparams – The formal parameters from an ADM.

class ace.lookup.FormalParameter(name: str, index: int, typeobj: SemType, default: Optional[ARI] = None)

Bases: object

A single formal parameter obtained from a :cls:`models.ParamMixin` object within an ADM context.

default: Optional[ARI] = None: Default value.

index: int: The list index (ordinal) of the parameter.

name: str: The unique name of the parameter.

typeobj: SemType: The fully recursively resolved type of the parameter.

ace.lookup.ORM_TYPE = {StructType.TYPEDEF: <class 'ace.models.Typedef'>, StructType.VAR: <class 'ace.models.Var'>, StructType.OPER: <class 'ace.models.Oper'>, StructType.EDD: <class 'ace.models.Edd'>, StructType.CTRL: <class 'ace.models.Ctrl'>, StructType.CONST: <class 'ace.models.Const'>, StructType.IDENT: <class 'ace.models.Ident'>}: Map from reference type-ID to ADM model type.

exception ace.lookup.ParameterError

Bases: RuntimeError

Exception when parameter handling fails.

class ace.lookup.RelativeResolver(ns_id: Union[int, str])

Bases: object

Resolve module-relative ARIs

class ace.lookup.TypeResolver

Bases: object

A caching recursive type resolver.

resolve(typeobj: SemType, adm: AdmModule) → SemType

Bind references to external BaseType objects from type names. This function is not reentrant.

Parameters:: typeobj – The original unbound type object (and any children).
Returns:: The :ivar:`typeobj` with all type references bound.
Raises:: TypeResolverError – If any required types are missing.

exception ace.lookup.TypeResolverError(msg: str, badtypes: List): Bases: RuntimeError

ace.lookup.dereference(ref: ReferenceARI, db_sess: Session) → Optional[AdmObjMixin]: Dereference a single object reference.

ace.lookup.find_adm(ns_id, db_sess: Session) → Optional[AdmModule]: Dereference an ADM module.

ORM models for the ADM and its contents.

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

Bases: Base, CommonMixin

Each “import” of an ADM

description

id

module

module_id

name

position

prefix

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

Bases: Base

The ADM itself with relations to its attributes and objects

const

ctrl

edd

enum

feature

id: Unique ID of the row

ident

imports

latest_revision

metadata_id

metadata_list

name

norm_name

oper

revisions

source

source_id

typedef

var

class ace.models.AdmObjMixin

Bases: CommonMixin

Common attributes of an ADM-defined object.

enum = Column(None, Integer(), table=None)

if_feature_expr = Column(None, PickleType(), table=None): Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

name = Column(None, String(), table=None, nullable=False)

norm_name = Column(None, String(), table=None)

position = Column(None, Integer(), table=None)

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

Bases: Base, CommonMixin

Each “revision” of an ADM

description

id

module

module_id

name

position

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

Bases: Base

The original ADM file content and metadata from a successful load.

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

file_text: Cached full file content.

id: Unique ID of the row

last_modified: Modified Time from the source file

module: Derived ADM module content

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

class ace.models.CommonMixin

Bases: object

Common module substatements.

description = Column(None, String(), table=None)

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

Bases: Base, AdmObjMixin, ParamMixin, TypeUseMixin

Constant value (CONST)

description

enum

id

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

init_ari: Resolved and decoded ARI for ivar:init_value.

init_value: The initial and constant value as text ARI

module

module_id

name

norm_name

parameters

parameters_id

position

typeobj: An object derived from the :cls:`SemType` class.

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

Bases: Base, AdmObjMixin, ParamMixin

Control

description

enum

id

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

module

module_id

name

norm_name

parameters

parameters_id

position

result: Optional result descriptor.

result_id

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

Bases: Base, AdmObjMixin, ParamMixin, TypeUseMixin

Externally Defined Data (EDD)

description

enum

id

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

module

module_id

name

norm_name

parameters

parameters_id

position

typeobj: An object derived from the :cls:`SemType` class.

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

Bases: Base, CommonMixin

Feature definition, which is a module-only object not an AMM object.

description

id

module

module_id

name

position

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

Bases: Base, AdmObjMixin, ParamMixin

Identity object (named, derived object)

bases

description

enum

id: Unique ID of the row

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

module: Relationship to the AdmModule

module_id: ID of the file from which this came

name

norm_name

parameters

parameters_id

position

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

Bases: Base

Each Identity base reference

base_ari: Resolved and decoded ARI

base_text: The object from which the parent Ident is derived as text ARI

id: Unique ID of the row

ident: Relationship to the AdmModule

ident_id: ID of the file from which this came

position: ordinal of this item in a TypeNameList

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

Bases: Base

A single item of module, object, or substatement metadata.

arg

id

list

list_id

name

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

Bases: Base

A list of named metadata items.

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

id

items

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

Bases: Base, AdmObjMixin, ParamMixin

Operator (Oper) used in EXPR postfix

description

enum

id

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

module

module_id

name

norm_name

operands

operands_id

parameters

parameters_id

position

result

result_id

class ace.models.ParamMixin

Bases: object

Attributes for formal parameters of an object.

parameters = <_RelationshipDeclared at 0x7f7dd8031e40; no key>

parameters_id = Column(None, Integer(), ForeignKey('typename_list.id'), table=None)

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

Bases: Base

Identify the version of a DB.

version_num

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

Bases: Base, TypeUseMixin

Each item within a TypeNameList

default_ari: Resolved and decoded ARI for default_value.

default_value: Optional default value for parameter as text ARI.

description: Arbitrary optional text

id

list

list_id

name: Unique name for the item, the type comes from TypeUseMixin

position: ordinal of this item in a TypeNameList

typeobj: An object derived from the :cls:`SemType` class.

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

Bases: Base

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

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

id

items

class ace.models.TypeUseMixin

Bases: object

Common attributes for containing a typing instance.

typeobj = Column(None, PickleType(), table=None): An object derived from the :cls:`SemType` class.

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

Bases: Base, AdmObjMixin, TypeUseMixin

Type definition (named semantic type)

description

enum

id

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

module

module_id

name

norm_name

position

typeobj: An object derived from the :cls:`SemType` class.

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

Bases: Base, AdmObjMixin, TypeUseMixin

Variable value (VAR)

description

enum

id

if_feature_expr: Feature-matching parsed expression. See pyang.syntax.parse_if_feature_expr().

init_ari: Resolved and decoded ARI for ivar:init_value.

init_value: The initial value as text ARI

module

module_id

name

norm_name

position

typeobj: An object derived from the :cls:`SemType` class.

Perform conversion to and from nickname content in ARIs.

class ace.nickname.Converter(mode: Mode, db_sess: Session, 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.
db_sess – 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

TO_NN = 1

class ace.type_constraint.CborCddl(text: str)

Bases: Constraint

CDDL pattern for embedded CBOR item.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

text: str: CDDL expression.

class ace.type_constraint.IdentRefBase(base_text: str, base_ari: ReferenceARI, base_ident: Optional[Ident] = None)

Bases: Constraint

Limit the base of Ident object references.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

base_ari: ReferenceARI: The base object reference.

base_ident: Ident = None: ADM object lookup session

base_text: str: Original required base text.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

class ace.type_constraint.IntegerBits(positions: Dict[int, str], mask: int)

Bases: Constraint

Label enumerated values and bit positions.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

mask: int: Mask for all named bits.

positions: Dict[int, str]: Named bit positions.

class ace.type_constraint.IntegerEnums(values: Dict[int, str])

Bases: Constraint

Named enumerated values.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

values: Dict[int, str]: Named values.

class ace.type_constraint.NumericRange(ranges: Interval)

Bases: Constraint

Limit the range of numeric values.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

ranges: Interval: The Interval representing valid ranges.

class ace.type_constraint.StringLength(ranges: Interval)

Bases: Constraint

Limit the length of string values. For textstr this is a count of characters, for bytestr this is a count of bytes.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

ranges: Interval: The Interval representing valid lengths.

class ace.type_constraint.TextPattern(pattern: str)

Bases: Constraint

Limit the content of text string values.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

pattern: str: The regular expression pattern.

Implementation of semantic typing logic for ADMs and ARI processing.

ace.typing.ANY = {'literal': AnyType(type_id=<StructType.LITERAL: 255>), 'object': AnyType(type_id=<StructType.OBJECT: -256>)}: Special reserved types and behavior.

class ace.typing.AnyType(type_id: StructType)

Bases: BuiltInType

Special non-union aggregation built-in types.

VALUE_CLS = {StructType.OBJECT: <class 'ace.ari.ReferenceARI'>, StructType.LITERAL: <class 'ace.ari.LiteralARI'>}: Required value type for target time type.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

ace.typing.BUILTINS = {'ac': ContainerType(type_id=<StructType.AC: 17>), 'am': ContainerType(type_id=<StructType.AM: 18>), 'aritype': StringType(type_id=<StructType.ARITYPE: 16>), 'bool': BoolType(type_id=<StructType.BOOL: 1>), 'byte': NumericType(type_id=<StructType.BYTE: 2>), 'bytestr': StringType(type_id=<StructType.BYTESTR: 11>), 'cbor': StringType(type_id=<StructType.CBOR: 15>), 'const': ObjRefType(type_id=<StructType.CONST: -2>), 'ctrl': ObjRefType(type_id=<StructType.CTRL: -3>), 'edd': ObjRefType(type_id=<StructType.EDD: -4>), 'ident': ObjRefType(type_id=<StructType.IDENT: -1>), 'int': NumericType(type_id=<StructType.INT: 4>), 'label': StringType(type_id=<StructType.LABEL: 14>), 'literal': AnyType(type_id=<StructType.LITERAL: 255>), 'null': NullType(type_id=<StructType.NULL: 0>), 'object': AnyType(type_id=<StructType.OBJECT: -256>), 'oper': ObjRefType(type_id=<StructType.OPER: -6>), 'real32': NumericType(type_id=<StructType.REAL32: 8>), 'real64': NumericType(type_id=<StructType.REAL64: 9>), 'sbr': ObjRefType(type_id=<StructType.SBR: -8>), 'tbl': ContainerType(type_id=<StructType.TBL: 19>), 'tbr': ObjRefType(type_id=<StructType.TBR: -10>), 'td': TimeType(type_id=<StructType.TD: 13>), 'textstr': StringType(type_id=<StructType.TEXTSTR: 10>), 'tp': TimeType(type_id=<StructType.TP: 12>), 'typedef': ObjRefType(type_id=<StructType.TYPEDEF: -12>), 'uint': NumericType(type_id=<StructType.UINT: 5>), 'uvast': NumericType(type_id=<StructType.UVAST: 7>), 'var': ObjRefType(type_id=<StructType.VAR: -11>), 'vast': NumericType(type_id=<StructType.VAST: 6>)}: All builtin types by name.

ace.typing.BUILTINS_BY_ENUM = {StructType.OBJECT: AnyType(type_id=<StructType.OBJECT: -256>), StructType.TYPEDEF: ObjRefType(type_id=<StructType.TYPEDEF: -12>), StructType.VAR: ObjRefType(type_id=<StructType.VAR: -11>), StructType.TBR: ObjRefType(type_id=<StructType.TBR: -10>), StructType.SBR: ObjRefType(type_id=<StructType.SBR: -8>), StructType.OPER: ObjRefType(type_id=<StructType.OPER: -6>), StructType.EDD: ObjRefType(type_id=<StructType.EDD: -4>), StructType.CTRL: ObjRefType(type_id=<StructType.CTRL: -3>), StructType.CONST: ObjRefType(type_id=<StructType.CONST: -2>), StructType.IDENT: ObjRefType(type_id=<StructType.IDENT: -1>), StructType.NULL: NullType(type_id=<StructType.NULL: 0>), StructType.BOOL: BoolType(type_id=<StructType.BOOL: 1>), StructType.BYTE: NumericType(type_id=<StructType.BYTE: 2>), StructType.INT: NumericType(type_id=<StructType.INT: 4>), StructType.UINT: NumericType(type_id=<StructType.UINT: 5>), StructType.VAST: NumericType(type_id=<StructType.VAST: 6>), StructType.UVAST: NumericType(type_id=<StructType.UVAST: 7>), StructType.REAL32: NumericType(type_id=<StructType.REAL32: 8>), StructType.REAL64: NumericType(type_id=<StructType.REAL64: 9>), StructType.TEXTSTR: StringType(type_id=<StructType.TEXTSTR: 10>), StructType.BYTESTR: StringType(type_id=<StructType.BYTESTR: 11>), StructType.TP: TimeType(type_id=<StructType.TP: 12>), StructType.TD: TimeType(type_id=<StructType.TD: 13>), StructType.LABEL: StringType(type_id=<StructType.LABEL: 14>), StructType.CBOR: StringType(type_id=<StructType.CBOR: 15>), StructType.ARITYPE: StringType(type_id=<StructType.ARITYPE: 16>), StructType.AC: ContainerType(type_id=<StructType.AC: 17>), StructType.AM: ContainerType(type_id=<StructType.AM: 18>), StructType.TBL: ContainerType(type_id=<StructType.TBL: 19>), StructType.LITERAL: AnyType(type_id=<StructType.LITERAL: 255>)}: Builtin types by enumeration.

class ace.typing.BaseType

Bases: object

Base interface class for all type-defining classes.

all_constraints() → Set[Constraint]: Extract the set of all constraints on this type. This will not cross into container type contents.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

simplify(obj: ARI) → ARI

Perform type simplification to avoid duplicate literal typing.

The base type returns itself.

Parameters:: obj – The input ARI.
Returns:: The converted ARI.

class ace.typing.BoolType

Bases: BuiltInType

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

class ace.typing.BuiltInType(type_id: StructType)

Bases: BaseType

Behavior related to built-in types.

Parameters:: type_id – The :cls:`StructType` value related to the instance.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

class ace.typing.Constraint

Bases: object

Base class for all type constraints.

applicable() → Set[StructType]: Determine for which built-in types this constraint is applicable.

is_valid(obj: ARI) → bool: Determine if a specific AMM value meets this constraint.

class ace.typing.ContainerType(type_id: StructType)

Bases: BuiltInType

ARI containers.

VALUE_CLS = {StructType.AC: <class 'list'>, StructType.AM: <class 'dict'>, StructType.TBL: <class 'numpy.ndarray'>}: Required value type for target time type.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

class ace.typing.DiverseList(parts: List[BaseType])

Bases: SemType

A list with non-uniform-typed items.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

parts: List[BaseType]: Type for each item or sequence.

ace.typing.LITERALS = {'ac': ContainerType(type_id=<StructType.AC: 17>), 'am': ContainerType(type_id=<StructType.AM: 18>), 'aritype': StringType(type_id=<StructType.ARITYPE: 16>), 'bool': BoolType(type_id=<StructType.BOOL: 1>), 'byte': NumericType(type_id=<StructType.BYTE: 2>), 'bytestr': StringType(type_id=<StructType.BYTESTR: 11>), 'cbor': StringType(type_id=<StructType.CBOR: 15>), 'int': NumericType(type_id=<StructType.INT: 4>), 'label': StringType(type_id=<StructType.LABEL: 14>), 'null': NullType(type_id=<StructType.NULL: 0>), 'real32': NumericType(type_id=<StructType.REAL32: 8>), 'real64': NumericType(type_id=<StructType.REAL64: 9>), 'tbl': ContainerType(type_id=<StructType.TBL: 19>), 'td': TimeType(type_id=<StructType.TD: 13>), 'textstr': StringType(type_id=<StructType.TEXTSTR: 10>), 'tp': TimeType(type_id=<StructType.TP: 12>), 'uint': NumericType(type_id=<StructType.UINT: 5>), 'uvast': NumericType(type_id=<StructType.UVAST: 7>), 'vast': NumericType(type_id=<StructType.VAST: 6>)}: Literal types, including ARI containers.

class ace.typing.NullType

Bases: BuiltInType

The null type is trivial and will convert all values into null except for the undefined value.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

class ace.typing.NumericType(type_id, dom_min, dom_max)

Bases: BuiltInType

VALUE_CLS = {StructType.BYTE: <class 'int'>, StructType.INT: <class 'int'>, StructType.UINT: <class 'int'>, StructType.VAST: <class 'int'>, StructType.UVAST: <class 'int'>, StructType.REAL32: <class 'float'>, StructType.REAL64: <class 'float'>}

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

ace.typing.OBJREFS = {'const': ObjRefType(type_id=<StructType.CONST: -2>), 'ctrl': ObjRefType(type_id=<StructType.CTRL: -3>), 'edd': ObjRefType(type_id=<StructType.EDD: -4>), 'ident': ObjRefType(type_id=<StructType.IDENT: -1>), 'oper': ObjRefType(type_id=<StructType.OPER: -6>), 'sbr': ObjRefType(type_id=<StructType.SBR: -8>), 'tbr': ObjRefType(type_id=<StructType.TBR: -10>), 'typedef': ObjRefType(type_id=<StructType.TYPEDEF: -12>), 'var': ObjRefType(type_id=<StructType.VAR: -11>)}: Object reference types.

class ace.typing.ObjRefType(type_id=None)

Bases: BuiltInType

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

class ace.typing.SemType

Bases: BaseType

Base class for all semantic type structures.

class ace.typing.Sequence(base: BaseType, min_elements: Optional[int] = None, max_elements: Optional[int] = None)

Bases: SemType

A sequence within a :cls:`DiverseList` or for a greedy last parameter/operand.

The value itself is handled as a List[ARI], not an ARI

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

base: BaseType: Type restriction within the sequence.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

max_elements: Optional[int] = None: Upper limit on the size of the sequence.

min_elements: Optional[int] = None: Lower limit on the size of the sequence.

take(remain: List[ARI]) → List[ARI]

Match as many given parameters from a list as allowed.

Parameters:: remain – A mutable list to remove matching items from.
Returns:: The matched items.
Raises:: ValueError – If the operation cannot be performed.

class ace.typing.StringType(type_id: StructType)

Bases: BuiltInType

VALUE_CLS = {StructType.TEXTSTR: <class 'str'>, StructType.BYTESTR: <class 'bytes'>, StructType.LABEL: <class 'str'>, StructType.CBOR: <class 'bytes'>, StructType.ARITYPE: (<class 'str'>, <class 'int'>)}: Required value type for target string type.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

class ace.typing.TableColumn(name: str, base: BaseType)

Bases: object

Each column of a TableTemplate object.

base: BaseType: Type for this column.

name: str: Unique name of this column.

class ace.typing.TableTemplate(columns: ~typing.List[~ace.typing.TableColumn] = <factory>, key: ~typing.Optional[str] = None, unique: ~typing.List[~typing.List[str]] = <factory>, min_elements: ~typing.Optional[int] = None, max_elements: ~typing.Optional[int] = None)

Bases: SemType

A template for specific table (TBL) structure.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

columns: List[TableColumn]: Column definitions, with significant order.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

key: Optional[str] = None: Name of the key column.

max_elements: Optional[int] = None: Upper limit on the number of rows.

min_elements: Optional[int] = None: Lower limit on the number of rows.

unique: List[List[str]]: Names of unique column tuples.

class ace.typing.TimeType(type_id: StructType)

Bases: BuiltInType

Times as offsets from absolute or relative epochs.

VALUE_CLS = {StructType.TP: (<class 'datetime.datetime'>, <class 'int'>, <class 'float'>), StructType.TD: (<class 'datetime.timedelta'>, <class 'int'>, <class 'float'>)}: Required value type for target time type.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → ARI

class ace.typing.TypeUnion(types: ~typing.List[~ace.typing.SemType] = <factory>)

Bases: SemType

A union of other types.

all_constraints() → Set[Constraint]: Extract the set of all constraints on this type. This will not cross into container type contents.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

types: List[SemType]: The underlying types, with significant order.

class ace.typing.TypeUse(type_text: ~typing.Optional[str] = None, type_ari: ~typing.Optional[~ace.ari.ARI] = None, base: ~typing.Optional[~ace.typing.BaseType] = None, units: ~typing.Optional[str] = None, constraints: ~typing.List[~ace.typing.Constraint] = <factory>)

Bases: SemType

Use of and optional restriction on an other type.

all_constraints() → Set[Constraint]: Extract the set of all constraints on this type. This will not cross into container type contents.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

base: Optional[BaseType] = None: The bound type being used.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

constraints: List[Constraint]: Optional value constraints on this use.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

type_ari: ARI = None: Absolute ARI for the :ivar:`base` type to bind to.

type_text: str = None: Original text name of the type being used.

units: Optional[str] = None: Optional unit name for this use.

class ace.typing.UniformList(base: BaseType, min_elements: Optional[int] = None, max_elements: Optional[int] = None)

Bases: SemType

A list with uniform-typed items.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

base: BaseType: Type for all items.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

max_elements: Optional[int] = None: Upper limit on the size of the list.

min_elements: Optional[int] = None: Lower limit on the size of the list.

class ace.typing.UniformMap(kbase: Optional[BaseType] = None, vbase: Optional[BaseType] = None)

Bases: SemType

A map with uniform-typed items.

all_type_ids() → Set[StructType]: Extract the set of ARI types available for this type. This will not cross into container type contents.

children() → List[BaseType]

Get the set of child types under this type object.

The base type returns an empty list.

Returns:: Any child type objects.

convert(obj: ARI) → ARI

Force a literal conversion to this target type.

Parameters:

obj – The input ARI.

Returns:

The converted ARI.

Raises:

TypeError – if something is wrong with the input type.
ValueError – if something is wrong with the input value.

get(obj: ARI) → Optional[ARI]

kbase: Optional[BaseType] = None: Type for all keys.

vbase: Optional[BaseType] = None: Type for all values.

ace.typing.type_walk(root: BaseType) → Iterator

Walk all type objects in a tree, ignoring duplicates in cases of circular references.

Parameters:: root – The starting type to walk.
Returns:: an iterator over all unique type objects.

Algorithms that rely on the ACE data models.

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.