Parser Infrastructure

StructureRegistry

class aws.osml.io.StructureRegistry

Bases: object

Manages loading, caching, and lookup of structure definitions.

The registry discovers .ksy structure definition files from one or more search paths and makes them available by name. Built-in definitions for NITF headers, image subheaders, and common TREs are loaded automatically. You can extend the registry by adding custom search paths or registering definitions at runtime. Use get() to obtain a StructureDefinition for use with StructureAccessor or StructureWriter.

Example:

```python from aws.osml.io import StructureRegistry

registry = StructureRegistry() registry.add_search_path(“/path/to/my/structures”) definition = registry.get(“TRE_GEOLOB”) for name in registry.list():

print(name)

```

add_search_path(path)

Add a search path with higher priority than existing paths.

Parameters:

path (str) – Directory path to add to the search paths.

get(name)

Retrieve a structure definition by name.

Parameters:

name (str) – The structure name (e.g., "NITF_02.10_FileHeader", "TRE_GEOLOB").

Returns:

The StructureDefinition, or None if not found.

Return type:

StructureDefinition or None

list()

List all available structure definition names.

Returns:

Names that can be passed to get().

Return type:

list[str]

register(name, definition)

Register a definition at runtime with highest priority.

Runtime-registered definitions take priority over file-based definitions with the same name.

Parameters:
reload()

Reload all definitions from disk.

Clears the file cache and re-scans search paths. Definitions registered at runtime via register() are preserved.

Raises:

RuntimeError – If a search path cannot be read.

search_paths()

Return the current search paths.

Returns:

Directory paths being searched for .ksy files.

Return type:

list[str]

StructureDefinition

class aws.osml.io.StructureDefinition

Bases: object

A read-only structure definition parsed from a .ksy file.

Contains field names and layout information used by StructureAccessor and StructureWriter to read and write binary data. Obtain instances from StructureRegistry via StructureRegistry.get().

Example:

`python definition = registry.get("TRE_GEOLOB") print(definition.id, definition.field_names) `

field_names

Ordered list of field names defined in this structure.

id

The unique identifier for this structure (e.g., "TRE_GEOLOB").

title

Human-readable title from the definition, or None if not set.

StructureAccessor

class aws.osml.io.StructureAccessor(definition, data)

Bases: object

Provides lazy, dict-like read access to fields in binary data.

A StructureAccessor parses fields on demand according to a StructureDefinition, caching computed offsets for efficiency. Access fields with bracket notation (accessor["field_name"]), use dot-notation paths for nested fields ("parent.child"), check for conditional fields with has() or the in operator, and iterate over all accessible paths with fields(). Each field access returns a Value object.

Example:

```python from aws.osml.io import StructureAccessor

accessor = StructureAccessor(definition, data) value = accessor[“field_name”] if accessor.has(“optional_field”):

print(accessor[“optional_field”].as_str())

for path in accessor.fields():

print(path, accessor[path])

```

data

The underlying binary data buffer.

definition

The StructureDefinition used by this accessor.

fields()

List all accessible field paths.

Returns:

Field paths that can be passed to bracket notation.

Return type:

list[str]

has(path)

Check if a field exists and is accessible.

Returns False for conditional fields whose condition is not met.

Parameters:

path (str) – The field path to check.

Returns:

True if the field exists and is accessible.

Return type:

bool

raw_view(path)

Return the raw bytes for a field without interpretation.

Useful for passing binary data to external decoders.

Parameters:

path (str) – The field path.

Returns:

The raw bytes for the field.

Return type:

bytes

Raises:

  • KeyError – If the field does not exist.

  • RuntimeError – If the field is not contiguous in memory.

StructureWriter

class aws.osml.io.StructureWriter

Bases: object

Encodes values into binary data according to a StructureDefinition.

A StructureWriter serializes field values into the correct binary layout defined by a .ksy structure definition. Fields must be written in definition order. Call finish() to retrieve the final encoded bytes. Field values are set using bracket notation or the set() method, and accepted types include str, int, float, and bytes. For repeated fields, write elements sequentially with indexed paths (field_0, field_1, …).

Example:

```python from aws.osml.io import StructureWriter

writer = StructureWriter.new_streaming(definition) writer[“field1”] = “value1” writer[“field2”] = 42 data = writer.finish() ```

buffer()

Return the current buffer contents without validation.

Useful for debugging or inspecting partial writes.

Returns:

The current buffer contents.

Return type:

bytes

finish()

Finalize the writer and return the encoded bytes.

After calling finish(), the writer is consumed and cannot be used again.

Returns:

The encoded binary data.

Return type:

bytes

Raises:

  • ValueError – If required fields have not been written.

  • RuntimeError – If the writer has already been finalized.

Example:

`python writer = StructureWriter.new_fixed(definition) writer["FHDR"] = "NITF" writer["FVER"] = "02.10" data = writer.finish() `

is_set(path)

Check if a field has been written.

Parameters:

path (str) – The field path.

Returns:

True if the field has been written.

Return type:

bool

static new_streaming(definition)

Create a streaming writer.

Fields must be written in definition order.

Parameters:

definition (StructureDefinition) – The StructureDefinition to encode against.

Returns:

A new writer.

Return type:

StructureWriter

set(path, value)

Write a value to a field by path.

Parameters:

  • path (str) – The field path.

  • value – The value to write.

Value

class aws.osml.io.Value

Bases: object

Represents a parsed field value from binary structure data.

A Value is returned by StructureAccessor when you access a field. It holds the raw parsed content and provides type conversion methods — as_str(), as_int(), as_float(), and as_bytes() — for interpreting ASCII-encoded fields as native Python types. Most binary format fields (e.g. NITF header fields) are stored as fixed-width ASCII strings, so these converters handle trimming and numeric parsing automatically.

Example:

`python value = accessor["NROWS"] num_rows = value.as_int() print(value.as_str()) `

as_bytes()

Return the raw bytes of the value.

Returns:

The raw byte representation.

Return type:

bytes

as_float()

Parse the value as a floating-point number.

Blank or whitespace-only strings are parsed as 0.0.

Returns:

The parsed floating-point value.

Return type:

float

Raises:

TypeError – If the value cannot be converted to a float.

as_int()

Parse the value as a signed integer.

Blank or whitespace-only strings are parsed as 0.

Returns:

The parsed integer value.

Return type:

int

Raises:

TypeError – If the value cannot be converted to an integer.

as_str()

Return the value as a string, trimming trailing padding.

Returns:

The string value with trailing spaces removed.

Return type:

str

Raises:

TypeError – If the value cannot be converted to a string.