dmsp-ssm 1.0.0__tar.gz

dmsp_ssm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DMSP SSM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dmsp_ssm-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: dmsp-ssm
+Version: 1.0.0
+Summary: Python library for parsing DMSP SSM binary files.
+Author: DMSP SSM contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/scvarr/dmsp_ssm
+Project-URL: Repository, https://github.com/scvarr/dmsp_ssm
+Project-URL: Issues, https://github.com/scvarr/dmsp_ssm/issues
+Keywords: dmsp,ssm,satellite,magnetometer,xarray
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: xarray>=2024.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# dmsp-ssm
+
+`dmsp-ssm` is a Python library for reading, validating, and converting DMSP SSM binary data files.
+
+The package accepts single `.dat` files, gzip-compressed `.gz` files, and directories of supported files. It returns a `ParseResult` with parsed records and a validation report. The default output is an `xarray.Dataset`.
+
+## Installation
+
+```bash
+pip install dmsp-ssm
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from dmsp_ssm import Reader
+
+reader = Reader()
+result = reader.parse("path/to/file_or_directory")
+
+dataset = result.records
+report = result.report
+
+print(dataset)
+print(report.summary)
+```
+
+## Output Profiles
+
+Select an output profile with `ParseOptions`:
+
+```python
+from dmsp_ssm import ParseOptions, Reader
+
+reader = Reader()
+result = reader.parse(
+    "path/to/data",
+    options=ParseOptions(output_profile="xarray"),
+)
+```
+
+Supported profiles:
+
+- `xarray`: returns an `xarray.Dataset` with `record` and `second` dimensions.
+- `numpy`: returns a `dict[str, numpy.ndarray]`.
+- `table`: returns long-format trace rows as `list[dict[str, object]]`.
+
+## xarray Output
+
+The default `xarray` profile contains:
+
+- dimensions: `record`, `second`
+- coordinates: `record_time`, `second_index`
+- second-level variables: `time`, `bx`, `by`, `bz`, `valid`
+- record-level variables: `flight_number`, `year`, `day_of_year`, `minute_start_sec_of_day`, `latitude_deg`, `longitude_deg`, `altitude_km`
+
+Data variables include `units` attributes when units are defined by the internal format definition.
+
+Missing second-level measurements are detected by the `time == -1000.0` marker. For those positions, `time`, `bx`, `by`, and `bz` are normalized to `NaN`, and `valid` is set to `False`.
+
+## Validation Report
+
+`ParseResult.report` contains validation status, incidents, and summary counters:
+
+```python
+result = Reader().parse("path/to/data")
+
+print(result.report.status)
+print(result.report.outcome)
+print(result.report.summary)
+```
+
+To include compact missing-minute ranges:
+
+```python
+result = Reader().parse(
+    "path/to/data",
+    include_missing_minute_ranges=True,
+)
+```
+
+For directory inputs, the summary can also include per-file missing-minute diagnostics in `missing_minute_ranges_by_file`.
+
+## API Overview
+
+### Reader
+
+```python
+Reader(
+    error_policy="resync",
+    pre_parse_size_warning_threshold_bytes=256 * 1024 * 1024,
+)
+```
+
+Use `Reader.parse(path, ...)` to parse a file or directory.
+
+### ParseOptions
+
+```python
+ParseOptions(
+    recursive=True,
+    error_policy=None,
+    include_missing_minute_ranges=False,
+    output_profile="xarray",
+)
+```
+
+`output_profile` must be one of `xarray`, `numpy`, or `table`.
+
+### ParseResult
+
+`ParseResult.records` contains the selected output artifact.
+
+`ParseResult.report` contains validation diagnostics.
+
+`ParseResult.metadata` and `ParseResult.extensions` are reserved for optional metadata.
+
+## Supported Input
+
+- `.dat` files
+- `.gz` files containing DMSP SSM binary data
+- directories containing only one supported file type
+- recursive directory traversal when `recursive=True`
+
+Directories containing mixed `.dat` and `.gz` files are rejected.
+
+## License
+
+This project is licensed under the MIT License.

dmsp_ssm-1.0.0/README.md

@@ -0,0 +1,135 @@
+# dmsp-ssm
+
+`dmsp-ssm` is a Python library for reading, validating, and converting DMSP SSM binary data files.
+
+The package accepts single `.dat` files, gzip-compressed `.gz` files, and directories of supported files. It returns a `ParseResult` with parsed records and a validation report. The default output is an `xarray.Dataset`.
+
+## Installation
+
+```bash
+pip install dmsp-ssm
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from dmsp_ssm import Reader
+
+reader = Reader()
+result = reader.parse("path/to/file_or_directory")
+
+dataset = result.records
+report = result.report
+
+print(dataset)
+print(report.summary)
+```
+
+## Output Profiles
+
+Select an output profile with `ParseOptions`:
+
+```python
+from dmsp_ssm import ParseOptions, Reader
+
+reader = Reader()
+result = reader.parse(
+    "path/to/data",
+    options=ParseOptions(output_profile="xarray"),
+)
+```
+
+Supported profiles:
+
+- `xarray`: returns an `xarray.Dataset` with `record` and `second` dimensions.
+- `numpy`: returns a `dict[str, numpy.ndarray]`.
+- `table`: returns long-format trace rows as `list[dict[str, object]]`.
+
+## xarray Output
+
+The default `xarray` profile contains:
+
+- dimensions: `record`, `second`
+- coordinates: `record_time`, `second_index`
+- second-level variables: `time`, `bx`, `by`, `bz`, `valid`
+- record-level variables: `flight_number`, `year`, `day_of_year`, `minute_start_sec_of_day`, `latitude_deg`, `longitude_deg`, `altitude_km`
+
+Data variables include `units` attributes when units are defined by the internal format definition.
+
+Missing second-level measurements are detected by the `time == -1000.0` marker. For those positions, `time`, `bx`, `by`, and `bz` are normalized to `NaN`, and `valid` is set to `False`.
+
+## Validation Report
+
+`ParseResult.report` contains validation status, incidents, and summary counters:
+
+```python
+result = Reader().parse("path/to/data")
+
+print(result.report.status)
+print(result.report.outcome)
+print(result.report.summary)
+```
+
+To include compact missing-minute ranges:
+
+```python
+result = Reader().parse(
+    "path/to/data",
+    include_missing_minute_ranges=True,
+)
+```
+
+For directory inputs, the summary can also include per-file missing-minute diagnostics in `missing_minute_ranges_by_file`.
+
+## API Overview
+
+### Reader
+
+```python
+Reader(
+    error_policy="resync",
+    pre_parse_size_warning_threshold_bytes=256 * 1024 * 1024,
+)
+```
+
+Use `Reader.parse(path, ...)` to parse a file or directory.
+
+### ParseOptions
+
+```python
+ParseOptions(
+    recursive=True,
+    error_policy=None,
+    include_missing_minute_ranges=False,
+    output_profile="xarray",
+)
+```
+
+`output_profile` must be one of `xarray`, `numpy`, or `table`.
+
+### ParseResult
+
+`ParseResult.records` contains the selected output artifact.
+
+`ParseResult.report` contains validation diagnostics.
+
+`ParseResult.metadata` and `ParseResult.extensions` are reserved for optional metadata.
+
+## Supported Input
+
+- `.dat` files
+- `.gz` files containing DMSP SSM binary data
+- directories containing only one supported file type
+- recursive directory traversal when `recursive=True`
+
+Directories containing mixed `.dat` and `.gz` files are rejected.
+
+## License
+
+This project is licensed under the MIT License.

dmsp_ssm-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dmsp-ssm"
+version = "1.0.0"
+description = "Python library for parsing DMSP SSM binary files."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    {name = "DMSP SSM contributors"},
+]
+keywords = ["dmsp", "ssm", "satellite", "magnetometer", "xarray"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.26",
+    "xarray>=2024.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.2",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/scvarr/dmsp_ssm"
+Repository = "https://github.com/scvarr/dmsp_ssm"
+Issues = "https://github.com/scvarr/dmsp_ssm/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "unit: fast unit and contract tests",
+    "integration: file-based integration tests",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

dmsp_ssm-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dmsp_ssm-1.0.0/src/dmsp_ssm/__init__.py

@@ -0,0 +1,17 @@
+"""Публичная поверхность API библиотеки dmsp_ssm.
+
+Поддерживаемые пользовательские точки входа:
+- `Reader`
+- `ParseOptions`
+- `ParseResult`
+
+Остальные модули и сущности, включая `dmsp_ssm._internal.*`,
+являются деталями реализации и не входят в публичный контракт.
+"""
+
+from dmsp_ssm.parse_options import ParseOptions
+from dmsp_ssm.parse_result import ParseResult
+from dmsp_ssm.reader import Reader
+
+__all__ = ["Reader", "ParseOptions", "ParseResult"]
+__version__ = "1.0.0"

dmsp_ssm-1.0.0/src/dmsp_ssm/_internal/assembler/__init__.py

@@ -0,0 +1 @@
+"""Внутренний пакет компоновки результата."""

dmsp_ssm-1.0.0/src/dmsp_ssm/_internal/assembler/artifact_accumulator.py

@@ -0,0 +1,81 @@
+"""Накопление артефактов результата по выбранному профилю вывода."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from dmsp_ssm._internal.assembler.contracts import (
+    ArtifactBundle,
+    OUTPUT_PROFILE_ARTIFACT_REQUIREMENTS
+)
+
+from ..builder.numpy_builder import NumpyBuilder
+from ..builder.table_builder import TableBuilder
+from ..builder.xarray_builder import XArrayBuilder
+from ..decoder.decoder import Decoder
+from ..pipeline.decoded_record import DecodedRecord
+from ..pipeline.field_trace import FieldTrace
+from ..pipeline.raw_record import RawRecord
+from ..validator.contracts import ValidationResult
+
+ReaderOutputProfile = Literal["raw", "decoded", "xarray", "numpy", "table"]
+
+
+def accumulate_artifact_bundle(
+        *,
+        profile: ReaderOutputProfile,
+        raw_records: list[RawRecord],
+        field_traces: list[FieldTrace] | None,
+        report: ValidationResult,
+        decoder: Decoder,
+        builder: XArrayBuilder,
+        numpy_builder: NumpyBuilder,
+        table_builder: TableBuilder | None = None,
+) -> ArtifactBundle:
+    """Собрать `ArtifactBundle` из артефактов, требуемых выбранным профилем."""
+
+    requirements = OUTPUT_PROFILE_ARTIFACT_REQUIREMENTS.get(profile)
+    if requirements is None:
+        raise ValueError(f"Неподдерживаемый внутренний профиль вывода: {profile}")
+
+    bundle = ArtifactBundle(
+        report=report,
+        field_traces=field_traces,
+    )
+    required_artifacts = requirements.required_artifacts
+
+    decoded_records: list[DecodedRecord] | None = None
+
+    if "raw_records" in required_artifacts:
+        bundle.raw_records = raw_records
+
+    if (
+            "decoded_records" in required_artifacts
+            or "dataset" in required_artifacts
+            or "numpy_records" in required_artifacts
+    ):
+        decoded_records = [decoder.decode(record) for record in raw_records]
+
+    if "decoded_records" in required_artifacts:
+        bundle.decoded_records = decoded_records
+
+    if "dataset" in required_artifacts:
+        bundle.dataset = builder.build(decoded_records or [])
+
+    if "numpy_records" in required_artifacts:
+        bundle.numpy_records = numpy_builder.build(decoded_records or [])
+
+    if "table_records" in required_artifacts:
+        if table_builder is None:
+            raise ValueError(
+                "Для internal profile 'table' требуется table_builder."
+            )
+        if decoded_records is None:
+            decoded_records = [decoder.decode(record) for record in raw_records]
+        bundle.decoded_records = decoded_records
+        bundle.table_records = table_builder.build(
+            field_traces=field_traces or [],
+            decoded_records=decoded_records,
+        )
+
+    return bundle

dmsp_ssm-1.0.0/src/dmsp_ssm/_internal/assembler/contracts.py

@@ -0,0 +1,88 @@
+"""Внутренние контрактные границы слоя финальной сборки результата.
+
+Assembler-слой расположен после подготовки выходного артефакта и отвечает за
+преобразование `ArtifactBundle` в фасадный `ParseResult`.
+
+Слой не выполняет чтение, валидацию, разбор, декодирование или построение
+выходных структур данных. Он получает уже подготовленные артефакты для
+публичных профилей `xarray`, `numpy` и `table`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+import numpy as np
+import xarray as xr
+
+from ..pipeline.decoded_record import DecodedRecord
+from ..pipeline.field_trace import FieldTrace
+from ..pipeline.raw_record import RawRecord
+from dmsp_ssm.parse_result import ParseResult
+from ..validator.contracts import ValidationResult
+
+OutputProfile = Literal["raw", "decoded", "xarray", "numpy", "table"]
+
+
+@dataclass(slots=True, frozen=True)
+class ProfileArtifactRequirements:
+    """Описание артефактов, необходимых для выбранного профиля вывода.
+
+    Используется внутренним accumulation-слоем, чтобы подготовить только те данные,
+    которые требуются для сборки результата выбранного профиля.
+    """
+
+    required_artifacts: frozenset[str]
+
+
+OUTPUT_PROFILE_ARTIFACT_REQUIREMENTS: dict[
+    OutputProfile,
+    ProfileArtifactRequirements,
+] = {
+    "raw": ProfileArtifactRequirements(
+        required_artifacts=frozenset({"raw_records"})
+    ),
+    "decoded": ProfileArtifactRequirements(
+        required_artifacts=frozenset({"decoded_records"})
+    ),
+    "xarray": ProfileArtifactRequirements(
+        required_artifacts=frozenset({"dataset"})
+    ),
+    "numpy": ProfileArtifactRequirements(
+        required_artifacts=frozenset({"numpy_records"})
+    ),
+    "table": ProfileArtifactRequirements(
+        required_artifacts=frozenset({"table_records"})
+    ),
+}
+
+
+@dataclass(slots=True)
+class ArtifactBundle:
+    """Внутренний контейнер артефактов между use-case и assembler-слоем.
+
+    `ArtifactBundle` переносит диагностический отчет, подготовленный результат
+    выбранного профиля и дополнительные служебные данные. Контейнер не является
+    публичным API и не задает потоковый протокол обработки.
+
+    Необязательные поля отсутствуют, если соответствующий артефакт не требуется
+    для выбранного профиля вывода.
+    """
+
+    report: ValidationResult
+    raw_records: list[RawRecord] | None = None
+    decoded_records: list[DecodedRecord] | None = None
+    dataset: xr.Dataset | None = None
+    numpy_records: dict[str, np.ndarray] | None = None
+    table_records: list[dict[str, object]] | None = None
+    field_traces: list[FieldTrace] | None = None
+    metadata: dict[str, object] | None = None
+    extensions: dict[str, object] | None = None
+
+
+class SupportsParseResultAssembler(Protocol):
+    """Контракт assembler-компонента для сборки фасадного `ParseResult`."""
+
+    def assemble(self, bundle: ArtifactBundle) -> ParseResult:
+        """Собрать фасадный результат без чтения, декодирования и построения артефактов."""

dmsp_ssm-1.0.0/src/dmsp_ssm/_internal/assembler/in_memory.py

@@ -0,0 +1,35 @@
+"""Assembler итогового `ParseResult` с результатом в памяти."""
+
+from __future__ import annotations
+
+from .contracts import ArtifactBundle
+from dmsp_ssm.parse_result import ParseResult
+
+
+class InMemoryParseResultAssembler:
+    """Assembler, формирующий `ParseResult` из готового `ArtifactBundle`.
+
+    Компонент не выполняет чтение, валидацию, разбор, декодирование или построение
+    выходных структур данных. Он выбирает подготовленный результат профиля и
+    помещает его в `ParseResult.records`.
+    """
+
+    @staticmethod
+    def assemble(bundle: ArtifactBundle) -> ParseResult:
+        """Собрать `ParseResult` в памяти для поддержанных артефактов результата."""
+        records = bundle.dataset
+        if records is None:
+            records = bundle.numpy_records
+        if records is None:
+            records = bundle.table_records
+        if records is None:
+            raise ValueError(
+                "Для in-memory assembler требуется dataset, numpy_records или table_records в artifact bundle."
+            )
+
+        return ParseResult(
+            records=records,
+            report=bundle.report,
+            metadata=bundle.metadata,
+            extensions=bundle.extensions,
+        )

dmsp_ssm-1.0.0/src/dmsp_ssm/_internal/builder/__init__.py

@@ -0,0 +1 @@
+"""Внутренний пакет сборки выходных профилей."""

dmsp_ssm-1.0.0/src/dmsp_ssm/_internal/builder/contracts.py

@@ -0,0 +1,18 @@
+"""Внутренние контракты builder-слоя."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..pipeline.decoded_record import DecodedRecord
+
+
+class BuilderArtifact(Protocol):
+    """Маркерный контракт результата builder-компонента."""
+
+
+class SupportsDecodedRecordBuilder(Protocol):
+    """Контракт builder-компонента, работающего с декодированными записями."""
+
+    def build(self, records: list[DecodedRecord]) -> BuilderArtifact:
+        """Построить выходной артефакт из декодированных записей."""