The Target-Agnostic Core

Hashables

Theses classes are used for identifying types which have been bound and loaded to theirrepective module.

class Uid(qualified_name)

Bases: object

Unique identifier for a type name (binding). qualified name is a string of form

• <module>.<name> in which case the components are extracted accordingly

• <name> in which case module becomes __local__.

module: str

name: str

class Entry(qualified_name, value: str | None = None)

Bases: Uid

Extension class for Uid, associating an (usually) initialization value to a defined type.

value: str | None = None

Base Attributes

These AST objects are used to encode base attributes in type definitions, but are not types per-se.

class Endian(value)

Bases: Enum

Encode endianness

LITTLE = 'little'

BIG = 'big'

class IntBase(value: int, base: int)

Bases: object

Represents an integer in an arbitrary base. Its parser can read:

• binary numbers, e.g., 0b1100

• base 8 numbers, e.g., 0o1147

• base 16 numbers, e.g., 0x11FF

• base 10 numbers, e.g., 1100

• arbitrary base numbers from a tuple, e.g., (<value>, <base>)

value: int

base: int

class Range(low: IntBase, high: IntBase)

Bases: object

A range can be either a list with two elements, low and high limits, or a single value in which case the range is just that single value.

low: IntBase

high: IntBase

values()

Returns the range as a tuple of numbers.

size()

Calculates the number of elements contained in this range.

class Constant(constant: Endian | IntBase | Range)

Bases: object

Marks the contained value as being a constant.

constant: Endian | IntBase | Range

Core Data Types

These classes encode the target-agnostic type representations.

class TypeABC(type: str, readonly: bool, _info: dict | None)

Bases: object

Abstract base class for all type representations.

type: str

readonly: bool

derefer() → TypeABC

Returns ‘self’. Possibly overloaded by instances.

set_readonly(value: bool)

class Void(type: str, readonly: bool, _info: dict | None)

Bases: TypeABC

Void type.

select_types(of_class=None) → List[TypeABC]

Predicate selection function.

class Boolean(type: str, readonly: bool, _info: dict | None, bit_size: IntBase | None = None)

Bases: TypeABC

Boolean type.

bit_size: IntBase | None = None

select_types(of_class=None) → List[TypeABC]

Predicate selection function.

normalize_value(value) → bool | None

Tries to convert a value to a Python bool. Returns None if unsuccessful.

class Integer(type: str, readonly: bool, _info: dict | None, range: Range, endian: Endian | None = None, bit_size: IntBase | None = None)

Bases: TypeABC

Integer type. OBS: range attribute is mandatory.

range: Range

endian: Endian | None = None

bit_size: IntBase | None = None

select_types(of_class=None) → List[TypeABC]

Predicate selection function.

normalize_value(value) → int | None

Tries to convert a value to a Python int. Returns None if unsuccessful.

class Array(type: str, readonly: bool, _info: dict | None, range: Range, element_type: TypeABC, len_field: str | None = None)

Bases: TypeABC

Array type. OBS: range and element_type attributes are mandatory.

range: Range

element_type: TypeABC

len_field: str | None = None

select_types(of_class=None) → List[TypeABC]

Predicate selection function. Recurs into the contained type.

class Structure(type: str, readonly: bool, _info: dict | None, field: Dict[str, TypeABC])

Bases: TypeABC

A structure type is represented as a dictionary of other types.

field: Dict[str, TypeABC]

select_types(of_class=None) → List[TypeABC]

Predicate selection function. Recurs into all contained types.

class TypeRef(type: str, readonly: bool, _info: dict | None, ref: Uid, range_mod: Range | None = None, endian_mod: Endian | None = None, bit_size: IntBase | None = None)

Bases: TypeABC

Qualified reference to another (defined) type.

ref: Uid

range_mod: Range | None = None

endian_mod: Endian | None = None

bit_size: IntBase | None = None

derefer() → TypeABC

Overloads the base method. Recurs into the referenced type.

get_referred_type() → TypeABC

Retrieves the (previously loaded) referenced type from the current FtnDb singleton.

select_types(of_class=None) → List[TypeABC]

Predicate selection function. Recurs into the referenced type.

The Type Database Handler

class FtnDb(srcs={})

This is a singleton handler that takes care of loading and constructing the module dictionaries, populating them with FTN type definitions, and retrieving various information. Its constructor should be called exactly once at the beginning of the program.

Parameters:

srcs – dictionaries of modules with raw type definitions in AST format (e.g., JSON).

static instance()

Static access method.

static clear_instance()

Static destructor. Allows the subsequent creation of a new handler.

to_raw()

Returns the dictionaries of raw JSON/AST sources.

add_source(module: str, name: str, src: Dict) → None

Adds a user-provided raw source in the database.

parse(src) → TypeABC

Returns a base FTN type from a raw source expression without adding it to the database.

schema(base_type_name: str) → Schema

Returns the JSON schema used to parse a raw source expression into a base type.

get(what: Uid | str | TypeABC) → TypeABC

Returns a fully-built and loaded type definition. If not found it searches for its source module, deserializes using a corresponding base type schema and stores it in the database for future use.

make_entry(name: str | None = None, from_ftn: str | None = None, from_spec: Dict | None = None, value: str | None = None) → Entry

(Possibly constructs and) stores a FTN data type into the current database and returns an Entry object pointing to it.

Parameters:

• name – (mutually exclusive with from_ftn, from_spec) qualified name to previously loaded type (calls get() for good measure)

• from_ftn – (mutually exclusive with name, from_spec) string with binding or expression in the FTN language.

• from_spec – (mutually exclusive with name, from_ftn) string with binding or expression in raw format.

• value – initialization value.

dump(uid: Uid | str) → Dict

Serializes a previously loaded type.

loaded_types() → List[Uid]

Returns UIDs of all constructed and stored types

type_dependency_graph() → DiGraph

Builds a NetworkX graph representing the type dependencies of all constructed and stored types.