orbit-formats 0.1.0__tar.gz

orbit_formats-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Golden / reference fixtures under tests/data are compared byte-for-byte by the
+# round-trip tests. Git's line-ending normalisation (autocrlf on Windows checks out LF as
+# CRLF) would otherwise rewrite them and break those byte-exact assertions, so treat the
+# fixtures as binary — checked out verbatim, identical on every platform.
+tests/data/** -text

orbit_formats-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default reviewer for everything in this repo.
+*   @djankov

orbit_formats-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,59 @@
+name: Bug
+description: Report a defect in orbit-formats.
+title: "<short summary>"
+labels: ["type:bug"]
+body:
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: Observed behavior. Include error messages and tracebacks verbatim.
+    validations:
+      required: true
+  - type: textarea
+    id: what_expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: >-
+        Smallest snippet that triggers the bug — the Python (or CLI) call and, if a
+        file fails to parse or convert, the smallest sample file that reproduces it.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: orbit_formats_version
+    attributes:
+      label: orbit-formats version
+      placeholder: "e.g. 0.1.0, or git sha"
+    validations:
+      required: true
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - Windows
+        - macOS
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Relevant output — tracebacks, warnings, pytest output.
+      render: shell

orbit_formats-0.1.0/.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,25 @@
+name: Chore
+description: Tooling, infra, hygiene, or other non-feature work.
+title: "<short summary>"
+labels: ["type:chore"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What
+      description: What needs to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why
+      description: Why now. What's blocked or painful without it.
+    validations:
+      required: true
+  - type: textarea
+    id: done
+    attributes:
+      label: Definition of done
+      value: |
+        - [ ]

orbit_formats-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/orgs/astro-tools/discussions
+    about: Open a discussion for usage questions, ideas, or general chat.

orbit_formats-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,41 @@
+name: Feature
+description: Propose a new capability or a non-trivial change.
+title: "<short summary>"
+labels: ["type:feature"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing what this feature is.
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why this matters. What can't users do today that they should be able to do?
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: >-
+        Concrete, testable checkboxes. An outside reviewer should be able to read these
+        and tell whether the feature is done.
+      value: |
+        - [ ]
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: out_of_scope
+    attributes:
+      label: Out of scope / non-goals
+      description: What this issue deliberately does not cover. Helps keep scope honest.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Design notes, links to charter sections, references to prior art, open questions.

orbit_formats-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,34 @@
+<!--
+Thanks for contributing to orbit-formats. Keep PRs small and scoped to one issue.
+-->
+
+## Summary
+
+<!-- One or two sentences: what this PR changes and why. -->
+
+Closes #
+
+## Changes
+
+<!-- Short bullet list of the substantive changes. Omit trivia (formatting, imports). -->
+
+-
+
+## Tested with
+
+<!-- Tick what you ran locally. CI will re-run on Ubuntu, Windows, and macOS. -->
+
+- [ ] `pytest`
+- [ ] `ruff check`
+- [ ] `ruff format --check`
+- [ ] `mypy`
+
+## Breaking changes
+
+<!-- "None" if none. Otherwise: what breaks, who is affected, migration notes. -->
+
+None.
+
+## Notes for reviewers
+
+<!-- Optional. Things to look at first, known rough edges, questions for the reviewer. -->

orbit_formats-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      # 3 OSes × 3 Python minors = 9 cells. orbit-formats is pure Python with no
+      # native or GMAT dependency, so the matrix is the platform/interpreter spread,
+      # nothing more.
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install project
+        run: uv sync --all-groups
+
+      - name: Run pytest
+        run: uv run pytest --cov --cov-report=term-missing
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    name: typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mypy
+
+  # Smoke-check that `pip install orbit-formats` (no extras, no dev group) imports
+  # cleanly. Catches an extras-only dependency leaking into the default install path.
+  minimal-install:
+    name: minimal install smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install .
+      - run: python -c "import orbit_formats"
+
+  # Cross-validate the OEM writer against the ccsds-ndm oracle. ccsds-ndm is GPL-3.0, so
+  # it is never a runtime, extra, or dev dependency, never in uv.lock, and never shipped:
+  # it is installed transiently here with `uv run --with` and used only by this job's
+  # tests (which `importorskip` it, so they skip everywhere else). This keeps the whole
+  # distributed/locked project GPL-free while still validating against a reference impl.
+  oracle:
+    name: oracle cross-validation (ccsds-ndm)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run --with ccsds-ndm pytest tests/test_ccsds_oem_oracle.py -v
+
+  # Validate CITATION.cff against the Citation File Format v1.2.0 schema. cffconvert
+  # is installed standalone because it is a CI-only schema check, not part of the dev
+  # or runtime dependency graph.
+  citation:
+    name: citation file (cffconvert)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install cffconvert==2.0.0
+      - run: cffconvert --validate -i CITATION.cff

orbit_formats-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mkdocs build --strict
+
+  deploy:
+    name: deploy
+    needs: build
+    if: |
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: uv run mkdocs gh-deploy --force --no-history

orbit_formats-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/orbit-formats
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    name: github release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            dist/*

orbit_formats-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.whl
+
+# Environments
+.venv/
+venv/
+env/
+.env
+
+# uv
+.uv-cache/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+.cache/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+.DS_Store

orbit_formats-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

orbit_formats-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to orbit-formats are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+First release. orbit-formats reads TLE, CCSDS OEM (KVN), and GMAT report files into a
+single canonical representation, writes CCSDS OEM, and round-trips OEM losslessly —
+emitting an explicit, structured warning whenever a conversion cannot preserve
+information, never a silent drop.
+
+### Added
+
+- Canonical representation: a federated, typed dataclass family — `StateVector`,
+  `Ephemeris`, and `MeanElementSet` — unified by a shared `Metadata` spine (reference
+  frame, time scale, central body, object id, units, provenance). State-series types
+  project to a gmat-run-identical DataFrame (`Epoch, X, Y, Z, VX, VY, VZ`, with the spine
+  on `DataFrame.attrs`) that downstream consumers can adopt without reshaping.
+- Two-layer model: a faithful per-format fidelity layer beneath the canonical metamodel,
+  linked by an optional `source_native` handle, so a same-format round-trip stays
+  byte-identical (with `retain_source=True`) or content-lossless.
+- Readers: TLE / 3LE (sgp4-backed mean elements, TEME / UTC), CCSDS OEM (in-house KVN
+  parser — multi-segment, with covariance and acceleration preserved on the fidelity
+  model), and GMAT report (whitespace-aligned tables into an ephemeris or state).
+- Writer: CCSDS OEM (KVN), with byte-identical, content-lossless, and synthesised paths.
+- Public API — `read`, `write`, `convert`, and `detect_format` — with
+  content-signature-first format auto-detection and an explicit `format=` override.
+- Conversion graph: Cartesian ↔ Keplerian elements and time-scale conversion across UTC /
+  TAI / TT / TDB / GPS / UT1; conversions route through each format's preferred canonical
+  form.
+- Lossy-conversion framework: structured, catchable warnings (`DroppedFieldWarning`,
+  `PrecisionLossWarning`, `ModelApproximationWarning`, `MissingFieldWarning`) that name
+  exactly what a conversion drops.
+- Frame-rotation boundary: reference frames are tagged and preserved; a conversion that
+  would require rotating between distinct frames is refused rather than approximated.
+- `orbit-formats convert` command-line interface for one-shot file-to-file conversion.
+- Documentation site — the canonical-representation reference, a per-format reference, the
+  lossy-conversion semantics, and the conversion-capability matrix — and a typed
+  (`py.typed`), MIT-licensed package published to PyPI.
+
+[Unreleased]: https://github.com/astro-tools/orbit-formats/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/astro-tools/orbit-formats/releases/tag/v0.1.0

orbit_formats-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use orbit-formats in academic work, please cite it using the metadata below."
+title: orbit-formats
+abstract: >-
+  orbit-formats is a permissively-licensed Python library for reading, writing, and
+  losslessly converting between orbital state-vector and ephemeris file formats — TLE,
+  the CCSDS Navigation Data Message family, SP3, SPICE SPK, STK ephemeris, and GMAT
+  report. It reads each format into a single canonical in-memory representation and
+  emits an explicit, structured warning whenever a conversion cannot preserve
+  information.
+type: software
+authors:
+  - given-names: Dimitrije
+    family-names: Jankovic
+version: 0.1.0
+date-released: "2026-05-30"
+license: MIT
+repository-code: "https://github.com/astro-tools/orbit-formats"
+url: "https://github.com/astro-tools/orbit-formats"
+keywords:
+  - astrodynamics
+  - orbital-mechanics
+  - ephemeris
+  - ccsds
+  - tle
+  - space

orbit_formats-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to orbit-formats
+
+Thanks for your interest. This page is the one place to learn the workflow.
+
+## Getting set up
+
+```bash
+git clone https://github.com/astro-tools/orbit-formats.git
+cd orbit-formats
+uv sync --all-groups
+```
+
+This installs the package, its runtime dependencies, and the dev and docs groups.
+
+## Branches and PRs
+
+- One issue per branch. Branch names use a short prefix for type:
+  - `feat/<slug>` — new capability, tied to a `type:feature` issue.
+  - `fix/<slug>` — bug fix, tied to a `type:bug` issue.
+  - `chore/<slug>` — infra / tooling / hygiene.
+  - `docs/<slug>` — docs-only change.
+- Open a PR against `main`. Put `Closes #<N>` in the PR description so the issue
+  auto-closes on merge and the project board advances the card to Done.
+- Squash-merge is the only merge method. The PR title becomes the squash commit
+  subject — write it as a complete imperative sentence.
+
+## Local checks before pushing
+
+```bash
+uv run pytest               # tests
+uv run ruff check           # lint
+uv run ruff format --check  # formatting
+uv run mypy                 # types
+```
+
+CI re-runs all four on Ubuntu, Windows, and macOS, across Python 3.10, 3.11, and 3.12.
+
+## Commit messages
+
+Keep them short and imperative. One subject line, optional body.
+
+Do not include AI or tool attribution trailers in commits, PR titles, PR descriptions,
+or comments — see the repo-level convention.
+
+## Scope discipline
+
+orbit-formats is an I/O and conversion library: it reads, writes, and converts orbital
+state and ephemeris formats, and warns whenever a conversion cannot preserve
+information. It is deliberately not a propagator, an integrator, or a general
+frame-transformation engine. Before opening a feature issue, check the charter and the
+existing issues to make sure the work belongs here.
+
+## Questions
+
+Open a [discussion](https://github.com/orgs/astro-tools/discussions) rather than an
+issue for open-ended questions, usage help, or brainstorming. The astro-tools org runs
+a single shared discussions space — there is no per-repo discussions board.

orbit_formats-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 astro-tools
+
+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.