Class Reference — gnss-product-management

Every class, dataclass, Protocol, NamedTuple, Enum, and Exception in the package, grouped by architectural layer.

---

Layer 0 — Configuration & Utilities

Layer 0 contains no standalone classes — only module-level helpers and bundled YAML data. Low-level network I/O is handled at Layer 3 by ConnectionPoolFactory (via fsspec). See Layer 6 — Utilities for the utility classes (_PassthroughDict, IGSAntexReferenceFrameType) and Layer 3 — Factories, Planners & Transport for ConnectionPool / ConnectionPoolFactory.

---

Layer 1 — Specifications (Data Models)

Immutable data models parsed from YAML. Everything here is a Pydantic BaseModel unless noted otherwise.

Parameters

Class	File	Base	Key Fields
DerivationMethod	specifications/parameters/parameter.py	str, Enum	ENUM, COMPUTED
Parameter	specifications/parameters/parameter.py	BaseModel	name, value, pattern, derivation, compute
ParameterCatalog	specifications/parameters/parameter.py	—	parameters: Dict[str, Parameter]

Formats

Class	File	Base	Key Fields
FormatFieldDef	specifications/format/spec.py	BaseModel	pattern, default, description
FormatVersionSpec	specifications/format/spec.py	BaseModel	description, notes, metadata, file_templates, compression
FormatSpec (raw)	specifications/format/spec.py	BaseModel	description, versions, compression
FormatSpecCollection	specifications/format/spec.py	BaseModel	formats: Dict[str, FormatSpec]
FormatSpec (resolved)	specifications/format/format_spec.py	BaseModel	name, version, variant, parameters, filename
FormatSpecCatalog	specifications/format/format_spec.py	BaseModel	formats: dict[str, VersionCatalog[FormatSpec]]
FormatCatalog	specifications/format/format_spec.py	Catalog	formats: dict[str, VersionCatalog[Product]]
FormatRegistry	specifications/format/spec.py	BaseModel	formats: Dict[str, FormatSpec] (reusable definitions)

Products

Class	File	Base	Key Fields
PathTemplate	specifications/products/product.py	BaseModel	pattern, value, description
Product	specifications/products/product.py	BaseModel	name, parameters: List[Parameter], filename: PathTemplate
VariantCatalog[T]	specifications/products/product.py	BaseModel, Generic[T]	variants: Dict[str, T]
VersionCatalog[T]	specifications/products/product.py	BaseModel, Generic[T]	versions: Dict[str, T]
ProductSpec	specifications/products/catalog.py	BaseModel	name, format, version, variant, parameters, filename
ProductSpecCatalog	specifications/products/catalog.py	BaseModel	products: dict[str, VersionCatalog[ProductSpec]]
ProductCatalog	specifications/products/catalog.py	Catalog	products: dict[str, VersionCatalog[Product]]

Remote Resources

Class	File	Base	Key Fields
Server	specifications/remote/resource.py	BaseModel	id, hostname, protocol, auth_required
ResourceProductSpec	specifications/remote/resource.py	BaseModel	id, server_id, product_name, product_version, parameters, directory
ResourceSpec	specifications/remote/resource.py	BaseModel	id, name, servers: List[Server], products: List[ResourceProductSpec]
SearchTarget	specifications/remote/resource.py	BaseModel	product: Product, server: Server, directory: PathTemplate
ResourceCatalog	specifications/remote/resource_catalog.py	Catalog	id, name, servers, queries: List[SearchTarget]

Local Resources

Class	File	Base	Key Fields
LocalCollection	specifications/local/local.py	BaseModel	directory, description, items
LocalResourceSpec	specifications/local/local.py	BaseModel	name, description, collections: List[LocalCollection]

Dependencies

Class	File	Base	Key Fields
SearchPreference	specifications/dependencies/dependencies.py	BaseModel	parameter, sorting, description
Dependency	specifications/dependencies/dependencies.py	BaseModel	spec, required, constraints: Dict[str, str]
DependencySpec	specifications/dependencies/dependencies.py	BaseModel	name, preferences, dependencies, package, task
ResolvedDependency	specifications/dependencies/dependencies.py	BaseModel	spec, required, status, local_path, remote_url
DependencyResolution	specifications/dependencies/dependencies.py	@dataclass	spec_name, resolved: List[ResolvedDependency]

Abstract Base

Class	File	Base	Key Fields
Catalog	specifications/catalog.py	BaseModel	Abstract build() classmethod — base for all resolved catalogs

Relationships

Catalog (abstract BaseModel)
 ├── FormatCatalog
 ├── ProductCatalog
 └── ResourceCatalog

Parameter ──used-by──► PathTemplate
Parameter ──used-by──► Product
Parameter ──used-by──► FormatSpec
Parameter ──used-by──► ResourceProductSpec

PathTemplate ──field-of──► Product
PathTemplate ──field-of──► SearchTarget (directory)

Product ──field-of──► SearchTarget
Server  ──field-of──► SearchTarget

VersionCatalog[T] / VariantCatalog[T]
 └── wraps FormatSpec, ProductSpec, Product

FormatSpec ──resolved-into──► Product (via FormatCatalog.build)
ProductSpec ──resolved-into──► Product (via ProductCatalog.build)
ResourceSpec ──resolved-into──► ResourceCatalog (queries: List[SearchTarget])

SearchPreference ──used-by──► DependencySpec
Dependency ──used-by──► DependencySpec
ResolvedDependency ──used-by──► DependencyResolution

---

Layer 2 — Environments & Registry

Load YAML specs, build catalogs, and register local storage layouts.

Class	File	Base	Key Fields
_MatchEntry	environments/environment.py	NamedTuple	template_len, compiled_regex, product_name, format_name, version, variant, fixed_params
LoadedSpecs	environments/environment.py	BaseModel	Holds raw spec models before catalog build
ProductRegistry	environments/environment.py	—	Central registry: loads YAML → builds FormatCatalog, ProductCatalog, ParameterCatalog, ResourceCatalog objects; satisfies SourcePlanner Protocol for remote queries
RegisteredLocalResource	environments/workspace.py	BaseModel	name, base_dir, spec: LocalResourceSpec, server: Server
WorkSpace	environments/workspace.py	—	Registry of local storage directories and layout specs

Relationships

ProductRegistry  (implements SourcePlanner Protocol — remote resources)
 ├── owns FormatCatalog
 ├── owns ProductCatalog
 ├── owns ParameterCatalog
 └── owns ResourceCatalog[] (built from ResourceSpec files)

WorkSpace  (implements SourcePlanner Protocol — local resources)
 └── owns RegisteredLocalResource[]
      ├── references LocalResourceSpec
      └── references Server

---

Layer 3 — Factories, Planners & Transport

Query construction, remote search, download, ranking, and dependency resolution.

Protocols

Class	File	Base	Description
SourcePlanner	factories/source_planner.py	Protocol	Common interface: resource_ids, source_product(), sink_product(), register()

Connection Management

Class	File	Base	Key Fields
ConnectionPool	factories/connection_pool.py	—	hostname, protocol, max_connections, _pool, _semaphore
ConnectionPoolFactory	factories/connection_pool.py	—	_pools: Dict[str, ConnectionPool]

Search Planners

Class	File	Base	Key Fields
SearchPlanner	factories/search_planner.py	—	_product_registry: ProductRegistry, _workspace: WorkSpace

SearchPlanner delegates remote lookups to ProductRegistry and local lookups to WorkSpace — both satisfy the SourcePlanner Protocol (resource_ids, source_product(), sink_product()).

Transport

Class	File	Base	Key Fields
WormHole	factories/remote_transport.py	—	_connection_pool_factory: ConnectionPoolFactory, _env: ProductRegistry

Dependency Resolution

Dependency resolution is handled by ResolvePipeline (see Pipelines below). There is no separate DependencyResolver class.

Models & Exceptions

Class	File	Base	Key Fields
FoundResource	factories/models.py	BaseModel	product, source, uri, center, quality, parameters, _query (private)
Resolution	factories/models.py	BaseModel	task, paths: List[Path], lockfile
DiscoveryEntry	factories/models.py	BaseModel	product, center, quality, source, uri
DiscoveryReport	factories/models.py	BaseModel	entries: List[DiscoveryEntry]
MissingProductError	factories/models.py	Exception	missing: List[str], task: str

Pipelines

Class	File	Base	Key Fields
DownloadPipeline	factories/pipelines/download.py	—	_planner: SearchPlanner, _transport: WormHole
LockfileWriter	factories/pipelines/lockfile_writer.py	—	_manager: LockfileManager, _package: str
ResolvePipeline	factories/pipelines/resolve.py	—	_query: ProductQuery, _downloader: DownloadPipeline

Ranking (module-level functions, no classes)

Function	File	Signature
sort_by_protocol	factories/ranking.py	(targets: List[SearchTarget]) -> List[SearchTarget]
sort_by_preferences	factories/ranking.py	(targets, preferences) -> List[SearchTarget]

Relationships

SourcePlanner (Protocol)
 ├── ProductRegistry  implements SourcePlanner (remote resources)
 └── WorkSpace        implements SourcePlanner (local resources)

SearchPlanner
 ├── uses ProductRegistry (_product_registry) — remote resource_ids / source_product
 └── uses WorkSpace (_workspace)              — local resource_ids / source_product

WormHole
 ├── owns ConnectionPoolFactory
 ├── reads SearchTarget[]  → search()       → SearchTarget[] (expanded)
 └── reads SearchTarget    → download_one() → Path

DownloadPipeline
 ├── owns SearchPlanner
 ├── owns WormHole
 ├── reads FoundResource._query → WormHole.download_one()
 └── produces Path

LockfileWriter
 ├── owns LockfileManager
 ├── reads DependencyResolution
 └── produces Path (lockfile)

ResolvePipeline
 ├── owns ProductQuery  (_query)
 ├── owns DownloadPipeline
 ├── calls ranking.sort_by_protocol / sort_by_preferences (via ProductQuery)
 ├── reads DependencySpec
 └── produces (DependencyResolution, Path)

---

Layer 4 — Client API

High-level entry points consumed by application code.

Class	File	Base	Key Fields
GNSSClient	client/gnss_client.py	—	_env: ProductRegistry, _qf: SearchPlanner, _fetcher: WormHole
ProductQuery	client/product_query.py	—	_fetcher: WormHole, _qf: SearchPlanner, _product, _date, _parameters, _source_ids, _preferences

Search results are returned as FoundResource objects (see Layer 3 — Models & Exceptions).

Relationships

GNSSClient
 ├── owns ProductRegistry
 ├── owns SearchPlanner
 ├── owns WormHole
 ├── creates ProductQuery (fluent builder)
 ├── delegates to ResolvePipeline (dependency resolution)
 └── produces FoundResource[], DependencyResolution

ProductQuery (fluent builder)
 ├── uses WormHole
 ├── uses SearchPlanner
 └── produces FoundResource[]

---

Layer 5 — Lockfile Management

Persist reproducible product manifests as JSON sidecar files.

Class	File	Base	Key Fields
LockProductAlternative	lockfile/models.py	BaseModel	url
LockProduct	lockfile/models.py	BaseModel	name, timestamp, url, hash, size, sink, alternatives
DependencyLockFile	lockfile/models.py	BaseModel	date, package, task, version, products: List[LockProduct]
HashMismatchMode	lockfile/operations.py	Enum	WARN, STRICT
LockfileManager	lockfile/manager.py	—	_dir: Path — facade for load/save/build operations

Relationships

DependencyLockFile
 └── contains LockProduct[]
      └── contains LockProductAlternative[]

LockfileManager
 ├── reads/writes DependencyLockFile
 ├── uses LockProduct
 └── uses HashMismatchMode (via operations)

---

Layer 6 — Utilities

Class	File	Base	Description
_PassthroughDict	utilities/helpers.py	dict	Returns '{key}' for missing keys (used in template formatting)
IGSAntexReferenceFrameType	utilities/metadata_funcs.py	Enum	IGS ANTEX reference frame identifiers (IGS05, IGS08, …)

---

Module-Level Singletons

Name	File	Type	Description
DefaultProductEnvironment	defaults/__init__.py	ProductRegistry	Pre-configured registry built from bundled YAML
DefaultWorkSpace	defaults/__init__.py	WorkSpace	Pre-configured workspace built from bundled YAML

---

Full Dependency Graph (simplified)

┌─────────────────────────────────────────────────────────────────┐
│  Client API                                                     │
│  GNSSClient ──► ProductQuery ──► FoundResource[]                │
└──────┬──────────────────────────────────────────────────────────┘
       │ uses
┌──────▼──────────────────────────────────────────────────────────┐
│  Pipelines                                                      │
│  ResolvePipeline ──► ProductQuery ──► DownloadPipeline          │
│                  └──► LockfileWriter                            │
└──────┬──────────────────────────────────────────────────────────┘
       │ uses
┌──────▼──────────────────────────────────────────────────────────┐
│  Factories                                                      │
│  SearchPlanner ──► ProductRegistry (remote, via SourcePlanner)  │
│                └──► WorkSpace (local, via SourcePlanner)        │
│  WormHole ──► ConnectionPoolFactory ──► ConnectionPool          │
│  ranking.sort_by_protocol / sort_by_preferences                 │
└──────┬──────────────────────────────────────────────────────────┘
       │ uses
┌──────▼──────────────────────────────────────────────────────────┐
│  Environments                                                   │
│  ProductRegistry ──► builds catalogs from specs                 │
│  WorkSpace ──► RegisteredLocalResource[]                        │
└──────┬──────────────────────────────────────────────────────────┘
       │ uses
┌──────▼──────────────────────────────────────────────────────────┐
│  Specifications (BaseModel data layer)                          │
│  Parameter, PathTemplate, Product, Server, SearchTarget         │
│  FormatCatalog, ProductCatalog, ResourceCatalog                 │
│  DependencySpec, DependencyResolution, SearchPreference         │
│  LocalResourceSpec, LocalCollection                             │
└──────┬──────────────────────────────────────────────────────────┘
       │ uses
┌──────▼──────────────────────────────────────────────────────────┐
│  Utilities / Configuration (Layer 0)                            │
│  as_path(), hash_file(), decompress_gzip(), bundled YAMLs       │
└─────────────────────────────────────────────────────────────────┘

  Lockfile Management (cross-cutting)
  LockfileManager ──► DependencyLockFile ──► LockProduct