2.7.3.1. pycsamt.airborne.registry#

Technology and native-format registries for airborne EM data.

The registry separates two concepts deliberately:

a technology describes scientific semantics (MobileMT, ZTEM, AFMAG);
a format describes a concrete native delivery that can be read/written.

The built-in technologies are registered immediately because their scientific contracts are stable. No native vendor format is registered until a genuine sample or authoritative format specification is available.

The two definition dataclasses (AirborneTechnologyDefinition, AirborneFormatDefinition) are lightweight value objects, so they inherit PyCSAMTObject rather than CoreObject or MTBase – the same choice already made for the analogous DataTypeDefinition in the sibling pycsamt.emtf registry. The bookkeeping itself (alias collisions, detector-then-extension matching) is not reimplemented here; it is delegated to NamedRegistry, which both this module and pycsamt.io.formats share.

Functions

`detect_airborne_format`(source)	Detect a registered native format using detectors, then extensions.
`detect_airborne_technology`(obj, *[, strict])	Return one canonical technology, or report/ignore mixed content.
`get_airborne_format`(name)	Return a native format definition by name or alias, or `None`.
`get_airborne_technology`(name)	Return a technology definition by canonical name or alias.
`identify_airborne_technologies`(obj)	Return canonical technologies explicitly or safely identified.
`list_airborne_formats`(*[, technology])	Return registered native formats, optionally for one technology.
`list_airborne_technologies`()	Return registered technologies in registration order.
`register_airborne_format`(definition, *[, ...])	Register a concrete native airborne file/delivery format.
`register_airborne_technology`(definition, *)	Register one scientific technology definition.

Classes

`AirborneFormatDefinition`(name, technology[, ...])	Describe one concrete native airborne delivery format.
`AirborneTechnologyDefinition`(name, label, family)	Describe one scientific airborne-EM technology contract.

Exceptions

`AirborneFormatDetectionError`	Raised when native airborne format detection is ambiguous.
`AirborneRegistryError`	Base exception for airborne technology/format registry errors.
`AirborneTechnologyAmbiguityError`	Raised when an object contains more than one airborne technology.

class pycsamt.airborne.registry.AirborneTechnologyDefinition(name, label, family, aliases=<factory>, primary_tf_names=<factory>, reference_required=False, infer_from_tf=False, description='')[source]

Bases: PyCSAMTObject

Describe one scientific airborne-EM technology contract.

A technology definition is intentionally free of file-format knowledge: it only records how to recognize the technology from an already-built AirborneEMDataset / EMTF object. A concrete native delivery is described separately by AirborneFormatDefinition.

Parameters:

name (str) – Canonical technology key, for example "mobilemt". Passed through normalize_key().
label (str) – Human-readable display name, for example "MobileMT".
family (str) – Broad measurement family shared by related technologies, for example "natural_field_airborne_em". Also normalized.
aliases (tuple of str, optional) – Alternate keys accepted for lookup, for example ("mobile_mt",).
primary_tf_names (tuple of str, optional) – Transfer-function names that are unique enough to this technology to justify inference; see infer_from_tf.
reference_required (bool, default False) – Whether a fixed ground reference station is scientifically required for this technology’s response. Used by assess_airborne_qc() to decide whether a missing reference-station is a QC issue.
infer_from_tf (bool, default False) – Whether identify_airborne_technologies() may infer this technology purely from a matching entry of primary_tf_names, when nothing else identifies it. Deliberately False for tipper-only technologies (ZTEM), because standard tipper T is not unique to one technology.
description (str, default "") – Short human-readable description.

Raises:

ValueError – If name, label, or family is empty after normalization/stripping.

name: str

label: str

family: str

aliases: tuple[str, ...]

primary_tf_names: tuple[str, ...]

reference_required: bool = False

infer_from_tf: bool = False

description: str = ''

class pycsamt.airborne.registry.AirborneFormatDefinition(name, technology, reader=None, writer=None, detector=None, extensions=<factory>, aliases=<factory>, description='')[source]

Bases: PyCSAMTObject

Describe one concrete native airborne delivery format.

A format definition binds one technology to a concrete on-disk (or stream) representation. It stays empty of reader/writer until a genuine sample or authoritative specification exists to validate against; see the module-level docstring and register_airborne_format().

Parameters:

name (str) – Canonical format key, unique across all technologies.
technology (str) – Owning technology key; must already be registered via register_airborne_technology() before this format is registered.
reader (callable, optional) – reader(source, **kwargs) -> AirborneEMDataset. None means the format is not yet readable.
writer (callable, optional) – writer(dataset, target, **kwargs) -> Any. None means the format is not yet writable.
detector (callable, optional) – detector(source) -> bool used for content-aware format detection, ahead of extension-based matching.
extensions (tuple of str, optional) – File extensions used as a detection hint when no detector matches; normalized to a leading dot and lowercased.
aliases (tuple of str, optional) – Alternate keys accepted for lookup.
description (str, default "") – Short human-readable description.

Raises:

ValueError – If name or technology is empty after normalization.

name: str

technology: str

reader: Callable[[...], Any] | None = None

writer: Callable[[...], Any] | None = None

detector: Callable[[Any], bool] | None = None

extensions: tuple[str, ...]

aliases: tuple[str, ...]

description: str = ''

property readable: bool[source]: Whether a native reader has been registered.

property writable: bool[source]: Whether a native writer has been registered.

exception pycsamt.airborne.registry.AirborneRegistryError[source]

Bases: ValueError

Base exception for airborne technology/format registry errors.

exception pycsamt.airborne.registry.AirborneTechnologyAmbiguityError[source]

Bases: AirborneRegistryError

Raised when an object contains more than one airborne technology.

exception pycsamt.airborne.registry.AirborneFormatDetectionError[source]

Bases: AirborneRegistryError

Raised when native airborne format detection is ambiguous.

pycsamt.airborne.registry.register_airborne_technology(definition, *, replace=False)[source]

Register one scientific technology definition.

Parameters:

definition (AirborneTechnologyDefinition) – Technology contract to register.
replace (bool, default False) – Whether to overwrite an existing registration under the same canonical name, forwarded to register().

Returns:

The same definition instance, for convenient chaining.

Return type:

AirborneTechnologyDefinition

Raises:

TypeError – If definition is not an AirborneTechnologyDefinition.
AirborneRegistryError – If the canonical name or an alias is already registered and replace is False.

pycsamt.airborne.registry.get_airborne_technology(name)[source]

Return a technology definition by canonical name or alias.

Returns None rather than raising when name is unregistered, since callers such as _technology_from_text() use this for best-effort inference over untrusted attrs/subtype values.

Parameters:: name (str)
Return type:: AirborneTechnologyDefinition | None

pycsamt.airborne.registry.list_airborne_technologies()[source]

Return registered technologies in registration order.

Return type:: tuple[AirborneTechnologyDefinition, …]

pycsamt.airborne.registry.identify_airborne_technologies(obj)[source]

Return canonical technologies explicitly or safely identified.

Parameters:: obj (AirborneEMDataset, AirborneEMLine, AirborneEMRecord, or EMTF) – Object to inspect; see _collect_object_technologies() for exactly what is walked and in what priority.
Returns:: Zero or more canonical technology names, in registration order. Zero means obj carries no explicit or safely inferable technology tag; more than one means obj genuinely mixes technologies (see detect_airborne_technology() to turn that into an error instead).
Return type:: tuple of str

Notes

Only response types that are unique to one technology are inferred from transfer-function names. Standard tipper T and interstation TI are intentionally not enough by themselves to identify ZTEM or AirMt.

pycsamt.airborne.registry.detect_airborne_technology(obj, *, strict=True)[source]

Return one canonical technology, or report/ignore mixed content.

Parameters:

obj (AirborneEMDataset, AirborneEMLine, AirborneEMRecord, or EMTF) – Object to inspect; forwarded to identify_airborne_technologies().
strict (bool, default True) – Whether more than one identified technology is an error (True) or is reported as None (False).

Returns:

The single identified technology; None if none was identified, or if more than one was identified and strict is False.

Return type:

str or None

Raises:

AirborneTechnologyAmbiguityError – If more than one technology is identified and strict is True.

pycsamt.airborne.registry.register_airborne_format(definition, *, replace=False)[source]

Register a concrete native airborne file/delivery format.

Parameters:

definition (AirborneFormatDefinition) – Format to register. Its technology must already be registered via register_airborne_technology().
replace (bool, default False) – Whether to overwrite an existing registration under the same canonical name instead of raising.

Returns:

The registered definition. This may be a new instance with technology rewritten to the owning definition’s canonical name when definition was constructed with an alias.

Return type:

AirborneFormatDefinition

Raises:

TypeError – If definition is not an AirborneFormatDefinition.
AirborneRegistryError – If definition.technology is not a registered technology, or if the canonical name/an alias collides and replace is False.

pycsamt.airborne.registry.get_airborne_format(name)[source]

Return a native format definition by name or alias, or None.

Parameters:: name (str)
Return type:: AirborneFormatDefinition | None

pycsamt.airborne.registry.list_airborne_formats(*, technology=None)[source]

Return registered native formats, optionally for one technology.

Parameters:: technology (str, optional) – Canonical name or alias to filter by. None returns every registered format across all technologies.
Returns:: Matching formats in registration order.
Return type:: tuple of AirborneFormatDefinition
Raises:: AirborneRegistryError – If technology is supplied and is not registered.

pycsamt.airborne.registry.detect_airborne_format(source)[source]

Detect a registered native format using detectors, then extensions.

Parameters:: source (Any) – Candidate to identify, typically a path or an open stream. Passed to each registered detector, and to _extension_of() when no detector matches.
Returns:: The canonical format name, or None if nothing matched.
Return type:: str or None
Raises:: AirborneFormatDetectionError – If more than one registered format matches source, whether by detector or by extension.

Notes

Detectors have priority. Extensions are only hints and are used when they map to exactly one registered format. No built-in vendor formats are registered merely from published system descriptions.