Firebird-uuid Reference

firebird.uuid.ROOT_SPEC = 'https://raw.githubusercontent.com/FirebirdSQL/firebird-uuid/master/root.oid'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

URL for ROOT specification

firebird.uuid.IANA_ROOT_NAME = 'iso.org.dod.internet.private.enterprise'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

IANA name before Firebird namespace. Does not contain trailing dot.

firebird.uuid.oid_registry = OIDRegistry([])

A specialized registry for managing OIDNode objects, keyed by their UUID.

This class inherits from firebird.base.collections.Registry and provides methods specifically tailored for handling the Firebird OID hierarchy. It allows populating the registry from parsed specification data or TOML documents, retrieves nodes (including the designated root node), triggers the linking of nodes into a tree structure via build_tree, and enables serializing the registry content back into TOML format.

firebird.uuid.get_specification(url: str) → str

Fetches the text content of an OID specification from a URL.

Supports both HTTP(S) and local file:// URLs via a configured requests.Session.

Parameters:

url (str) – The URL (http, https, or file) of the OID specification YAML file.

Returns:

The YAML text content of the specification.

Raises:

• requests.exceptions.RequestException – If a network or file access error occurs.

• requests.exceptions.HTTPError – If an HTTP error response (e.g., 404) is received.

Return type:

str

firebird.uuid.get_specifications(root: str = 'https://raw.githubusercontent.com/FirebirdSQL/firebird-uuid/master/root.oid') → tuple[dict[str, str], dict[str, Exception]]

Recursively fetches all OID YAML specifications starting from a root URL.

Traverses the tree of specifications by following ‘node-spec’ URLs found in child definitions. It collects the raw YAML text of successfully fetched specifications and records any exceptions encountered during fetching or initial YAML parsing (needed to find child URLs).

This function performs only minimal validation necessary to navigate the tree.

Parameters:

root (str) – The URL of the root specification to start traversal from. Defaults to ROOT_SPEC.

Returns:

1. spec_map: dict[str, str] mapping URL to successfully fetched YAML content (string).

2. err_map: dict[str, Exception] mapping URL to the Exception encountered while trying to fetch or minimally parse that spec.

Return type:

A tuple containing two dictionaries

firebird.uuid.parse_specifications(specifications: dict[str, str]) → tuple[dict[str, dict], dict[str, Exception]]

Parses, validates, and normalizes multiple OID YAML specifications.

Takes a dictionary of raw YAML specification strings (typically from get_specifications), parses each string into a Python dictionary, validates its structure and content against the defined format, and normalizes keys (e.g., ‘node-spec’ to ‘node_spec’) using pythonize_spec.

Parameters:

specifications (dict[str, str]) – A dictionary mapping specification URLs (str) to their raw YAML content (str).

Returns:

1. data_map: dict[str, dict] mapping URL to the successfully parsed, validated, and key-normalized specification data (dictionary).

2. err_map: dict[str, Exception] mapping URL to the Exception encountered during YAML parsing or validation for that spec.

Return type:

A tuple containing two dictionaries

class firebird.uuid.OIDNodeType(value)

Bases: Enum

Enumeration of possible types for an OIDNode.

LEAF = 'leaf'

A terminal node in the hierarchy; it cannot have children defined in a separate specification file.

NODE = 'node'

An intermediate node that references another specification file (via node_spec) to define its children.

PRIVATE = 'private'

A node reserved for private use, similar to a LEAF in that it does not link to a separate specification file for children.

ROOT = 'root'

The top-level node in a specific OID specification file. Only one true root (from IANA) exists in the full conceptual tree.

class firebird.uuid.OIDNode(*, parent: OIDNode | None | Literal['None'] = None, oid: str | None = None, number: int | None = None, name: str | None = None, description: str | None = None, contact: str | None = None, email: str | None = None, site: str | None = None, parent_spec: str | None = None, node_spec: str | None = None, node_type: str | None = None)

Bases: Distinct

Represents a single node within the Firebird OID hierarchy.

Each node encapsulates information such as its Object Identifier (OID), name, description, contact details, and type. It maintains links to its parent (using a weak reference) and holds a list of its direct children.

Nodes are uniquely identified by a UUID (uid) deterministically generated from their OID using uuid.uuid5 with the NAMESPACE_OID.

Parameters:

• parent (OIDNode | None | Literal[NONE_VALUE]) – The parent OIDNode. Stored as a weak reference. None for the absolute root node of the entire hierarchy.

• oid (str | None) – The full OID string for this node. If None, it’s constructed from parent.oid and number. One of oid or (parent and number) must be provided.

• number (int | None) – The node’s number relative to its parent. Used to construct the OID if oid is not given.

• name (str | None) – Node name (e.g., ‘firebird’).

• description (str | None) – Node description.

• contact (str | None) – Contact person/entity name.

• email (str | None) – Contact email address.

• site (str | None) – URL associated with the node owner/maintainer.

• parent_spec (str | None) – URL to the YAML specification of the parent node. If None, it’s derived from the parent object’s node_spec.

• node_spec (str | None) – URL to this node’s YAML specification file (if it’s a NODE type) or one of the keywords ‘leaf’ or ‘private’. Used to determine node_type if node_type argument is not provided.

• node_type (str | None) – Explicit node type (‘root’, ‘node’, ‘leaf’, ‘private’). If None, it’s inferred from node_spec (‘leaf’/’private’ keywords or defaults to ‘node’ if it looks like a URL/path).

Raises:

ValueError – If the OID cannot be determined (neither oid nor parent`+`number are sufficient).

classmethod from_spec(spec_url: str, data: dict[str, Any], parent: OIDNode | None = None) → OIDNode

Creates a new OIDNode and its direct children from parsed specification data.

Parameters:

• spec_url (str) – The URL from which the specification data was loaded. Used as the node_spec for the created node.

• data (dict[str, Any]) – Parsed and validated dictionary from an OID node specification document (typically after pythonize_spec). Expected keys: ‘node’ (dict for the main node), ‘children’ (list of dicts).

• parent (OIDNode | None) – The parent node for the node being created (if applicable).

Returns:

The newly created OIDNode instance representing the root of the specification defined in data, with its children list populated.

Return type:

OIDNode

as_toml_dict() → dict[str, Any]

Returns node data as a dictionary suitable for TOML serialization.

Parent is represented by its UUID string. Uses the original oid if provided directly, otherwise relies on the potentially calculated oid. Node type is represented by the original string (__node_type) if provided, otherwise potentially derived. node_spec for LEAF/PRIVATE is output as the type keyword (‘leaf’/’private’).

Returns:

A dictionary with string representations of complex types like UUIDs.

Return type:

dict[str, Any]

get_key() → UUID

Returns the node’s unique identifier (UUID).

Return type:

UUID

set_parent(parent: OIDNode | None) → None

Sets or updates the parent node and related attributes.

Establishes a weak reference to the new parent. If the node’s number is set, it recalculates the node’s oid based on the new parent’s OID. It also updates parent_spec from the new parent’s node_spec.

Important

This method ONLY updates the child (self). It does NOT modify the old or new parent’s children list. Tree modifications should be handled externally (e.g., by build_tree).

Parameters:

parent (OIDNode | None) – The new parent node, or None to detach the node.

Return type:

None

children: list[OIDNode]

Direct child nodes

contact: str | None

Name of node administrator/contact

description: str | None

Node description (human-readable)

email: str | None

E-mail address of node administrator/contact

property full_name: str

Returns the fully qualified node name, starting from the root.

Example: ‘iso.org.dod.internet.private.enterprise.firebird.subsytem’. Returns just the node’s name if it has no parent.

name: str | None

Node name (identifier part)

node_spec: str | None

URL to this node’s specification file (or None for LEAF/PRIVATE)

node_type: OIDNodeType | None

Node type (enum member)

number: int | None

Node number (last component of OID) relative to parent

oid: str | None

OID string (may be calculated)

property parent: OIDNode | None

Returns the parent OIDNode object.

Returns None if this node has no parent or if the parent object has been garbage collected (due to the weak reference).

parent_spec: str | None

URL to parent node’s specification file

site: str | None

URL to node administrator/owner home page

uid: UUID

UUID (Universally Unique Identifier) derived from OID

class firebird.uuid.OIDRegistry(data: Mapping[Any, Distinct] | Sequence[Distinct] | Registry = None)

Bases: Registry

A specialized registry for managing OIDNode objects, keyed by their UUID.

This class inherits from firebird.base.collections.Registry and provides methods specifically tailored for handling the Firebird OID hierarchy. It allows populating the registry from parsed specification data or TOML documents, retrieves nodes (including the designated root node), triggers the linking of nodes into a tree structure via build_tree, and enables serializing the registry content back into TOML format.

Parameters:

data (Mapping[Any, Distinct] | Sequence[Distinct] | Registry)

as_toml() → str

Serializes the entire registry content into a TOML formatted string.

Iterates through all OIDNode objects currently held in the registry. For each node, it calls its as_toml_dict() method to get a TOML- compatible dictionary representation.

The final output is a single TOML string where the top level is a table (dictionary) mapping node UUID strings to their corresponding attribute dictionaries.

Returns:

A string containing the TOML representation of the registry’s nodes. An empty string if registry is empty.

Return type:

str

get_root() → OIDNode | None

Retrieves the root node of the OID hierarchy from the registry.

Searches the registered nodes for the unique node whose node_type attribute is OIDNodeType.ROOT.

Returns:

The root OIDNode object if found in the registry, otherwise None.

Return type:

OIDNode | None

update_from_specifications(specifications: dict[str, dict[str, Any]]) → None

Populates or updates the registry from parsed OID specification data.

Processes a dictionary where keys are specification URLs and values are the corresponding parsed/validated/pythonized specification data. For each specification, it instantiates OIDNode objects for both the main node defined in the spec (‘node’ key) and all its listed children (‘children’ key). All created nodes are added or updated in the registry using their UUIDs as keys.

After processing all specifications, it calls build_tree on the registry’s current contents to link the nodes into a hierarchical structure based on node_spec references and parent relationships.

Parameters:

specifications (dict[str, dict[str, Any]]) – A dictionary mapping specification URLs (str) to their corresponding parsed data (dict[str, Any]), as returned by parse_specifications.

Return type:

None

update_from_toml(toml_data: str) → None

Updates the registry by loading node data from a TOML document string.

Parses the TOML string, which is expected to contain a dictionary mapping node UUID strings to dictionaries of node attributes (as produced by the as_toml method).

Performs validation checks before loading:

• Ensures the TOML data either defines a root node (node_type=’root’ and no ‘parent’) or contains at least one node whose parent UUID already exists in the current registry.

• If a root node is defined in the TOML and a root node is already registered, verifies that their UUIDs match.

Nodes are then instantiated and added to the registry iteratively. A queue is used to handle dependencies: if a node’s parent hasn’t been loaded yet, the node is re-queued until its parent becomes available.

After all nodes from the TOML are successfully loaded and registered, build_tree is called on the registry’s contents to reconstruct the full node hierarchy.

Parameters:

toml_data (str) – A string containing the TOML document representation of the OID nodes to load.

Raises:

• Error – If validation fails (e.g., no linkable starting node, root UUID mismatch, unresolvable parent dependencies after attempting to load all nodes).

• toml.TOMLDecodeError – If the toml_data string is not valid TOML.

• uuid.ValueError – If a UUID string key or parent value in the TOML is malformed.

• KeyError – If essential keys like ‘node_type’ are missing in the TOML data for a node.

Return type:

None