orbitable 0.2.0__py3-none-any.whl

orbitable/__init__.py

@@ -0,0 +1,3 @@
+from orbitable.cli import main
+
+__all__ = ["main"]

orbitable/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

orbitable/cli.py

@@ -0,0 +1,216 @@
+import argparse
+import sys
+from pathlib import Path
+
+from loguru import logger
+from sqlalchemy.orm import sessionmaker
+
+from orbitable.config import load_config
+from orbitable.generator import generate
+from orbitable.ingest import ingest_file, ingest_sources
+from orbitable.model import Base
+
+
+def _setup_logging(level: str) -> None:
+    logger.remove()
+    logger.add(sys.stderr, level=level.upper())
+
+
+def _get_session(config):
+    engine = config.database.engine
+    Base.metadata.create_all(engine)
+    Session = sessionmaker(bind=engine)
+    return Session(), engine
+
+
+CONFIG_TEMPLATE = """\
+# Orbitable configuration
+# See: https://github.com/jolsten/orbitable
+
+# ----------------------------------------------
+# Database connection
+# ----------------------------------------------
+[database]
+# SQLAlchemy driver string. Examples:
+#   "sqlite"          - local SQLite file (default)
+#   "mysql+pymysql"   - MariaDB/MySQL via PyMySQL (install with: pip install orbitable[mysql])
+drivername = "sqlite"
+
+# For SQLite: path to the database file (relative or absolute)
+# For MariaDB/MySQL: the database name
+name = "orbitable.db"
+
+# Uncomment for MariaDB/MySQL:
+# host = "localhost"
+# port = 3306
+#
+# Credentials are loaded separately (never put passwords here).
+# Resolution order (highest priority first):
+#   1. Environment variables:  ORBITABLE_DATABASE__USERNAME / ORBITABLE_DATABASE__PASSWORD
+#   2. User secrets file:      ~/.config/orbitable.toml
+#   3. System secrets file:    set secrets_file below
+#
+# secrets_file = "/etc/orbitable/secrets.toml"
+
+# ----------------------------------------------
+# Ingest sources
+# ----------------------------------------------
+# Each [[ingest.sources]] entry defines a directory to scan for TLE/OMM files.
+# You can have multiple entries. File format is auto-detected by extension:
+#   .tle / .txt / .3le  ->  Two-Line Element format
+#   .json               ->  Space-Track OMM JSON
+#   .csv                ->  OMM CSV
+#   .xml                ->  OMM XML
+
+[[ingest.sources]]
+path = "./incoming"
+pattern = "*.tle"    # glob pattern for matching files
+
+# Add more sources as needed:
+# [[ingest.sources]]
+# path = "/data/spacetrack/daily"
+# pattern = "*.json"
+
+# ----------------------------------------------
+# Output generation
+# ----------------------------------------------
+[output]
+dir = "./output"     # directory where generated files are written
+
+# Which output formats to produce
+[output.formats]
+tle = true           # two-line element format (.tle files)
+omm = true           # OMM CSV format (.omm files)
+
+# Which output file types to generate
+[output.types]
+date_files = true    # one file per date: YYYYMMDD.{tle,omm}
+                     # contains the latest TLE per satellite for that date
+object_files = true  # one file per satellite: NORAD_ID.{tle,omm}
+                     # contains all TLEs for that satellite, ordered by epoch
+
+# ----------------------------------------------
+# Logging
+# ----------------------------------------------
+[logging]
+level = "INFO"       # DEBUG, INFO, WARNING, ERROR, CRITICAL
+"""
+
+SECRETS_TEMPLATE = """\
+# Orbitable user secrets
+# This file stores database credentials for your user account.
+# Keep this file private (chmod 600 on Linux/macOS).
+#
+# These values are overridden by environment variables:
+#   ORBITABLE_DATABASE__USERNAME
+#   ORBITABLE_DATABASE__PASSWORD
+
+username = ""
+password = ""
+"""
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    config_path = args.config
+    secrets_path = Path.home() / ".config" / "orbitable.toml"
+
+    created = []
+
+    if config_path.exists():
+        print(f"Config already exists: {config_path}")
+    else:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(CONFIG_TEMPLATE)
+        created.append(str(config_path))
+
+    if secrets_path.exists():
+        print(f"Secrets file already exists: {secrets_path}")
+    else:
+        secrets_path.parent.mkdir(parents=True, exist_ok=True)
+        secrets_path.write_text(SECRETS_TEMPLATE)
+        created.append(str(secrets_path))
+
+    if created:
+        print("Created:")
+        for path in created:
+            print(f"  {path}")
+        print("\nEdit these files to configure your database and credentials.")
+    elif not created:
+        print("Nothing to do -all files already exist.")
+
+
+def cmd_ingest(args: argparse.Namespace) -> None:
+    config = load_config(args.config)
+    _setup_logging(config.logging.level)
+
+    session, engine = _get_session(config)
+    try:
+        if args.files:
+            total = 0
+            for file in args.files:
+                count = ingest_file(session, Path(file))
+                total += count
+            logger.info(f"Ingested {total} new records from {len(args.files)} files")
+        else:
+            total = ingest_sources(session, config.ingest.sources)
+            logger.info(f"Ingested {total} new records from configured sources")
+    finally:
+        session.close()
+        engine.dispose()
+
+
+def cmd_generate(args: argparse.Namespace) -> None:
+    config = load_config(args.config)
+    _setup_logging(config.logging.level)
+
+    session, engine = _get_session(config)
+    try:
+        generate(session, config.output)
+    finally:
+        session.close()
+        engine.dispose()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="orbitable",
+        description="TLE database management tool",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=Path("config.toml"),
+        help="Path to config.toml (default: ./config.toml)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # init subcommand
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Scaffold config.toml and ~/.config/orbitable.toml",
+    )
+    init_parser.set_defaults(func=cmd_init)
+
+    # ingest subcommand
+    ingest_parser = subparsers.add_parser(
+        "ingest",
+        help="Ingest TLE/OMM files into the database",
+    )
+    ingest_parser.add_argument(
+        "files",
+        nargs="*",
+        help="Specific files to ingest (if omitted, scans configured source dirs)",
+    )
+    ingest_parser.set_defaults(func=cmd_ingest)
+
+    # generate subcommand
+    generate_parser = subparsers.add_parser(
+        "generate",
+        help="Generate output TLE/OMM files from the database",
+    )
+    generate_parser.set_defaults(func=cmd_generate)
+
+    args = parser.parse_args()
+    args.func(args)

orbitable/config.py

@@ -0,0 +1,118 @@
+import tomllib
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.engine import URL
+
+
+class Database(BaseModel):
+    drivername: str = "sqlite"
+    username: Optional[str] = None
+    password: Optional[str] = None
+    host: Optional[str] = None
+    port: Optional[int] = None
+    name: Optional[str] = ":memory:"
+    secrets_file: Optional[str] = None
+
+    @property
+    def url(self) -> URL:
+        return URL.create(
+            drivername=self.drivername,
+            username=self.username,
+            password=self.password,
+            host=self.host,
+            port=self.port,
+            database=self.name,
+        )
+
+    @property
+    def engine(self) -> Engine:
+        return create_engine(self.url)
+
+
+class IngestSource(BaseModel):
+    path: str
+    pattern: str = "*.tle"
+
+
+class IngestConfig(BaseModel):
+    sources: list[IngestSource] = []
+
+
+class OutputFormats(BaseModel):
+    tle: bool = True
+    omm: bool = True
+
+
+class OutputTypes(BaseModel):
+    date_files: bool = True
+    object_files: bool = True
+
+
+class OutputConfig(BaseModel):
+    dir: str = "./output"
+    formats: OutputFormats = OutputFormats()
+    types: OutputTypes = OutputTypes()
+
+
+class LoggingConfig(BaseModel):
+    level: str = "INFO"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="ORBITABLE_",
+        env_nested_delimiter="__",
+    )
+
+    database: Database = Database()
+    ingest: IngestConfig = IngestConfig()
+    output: OutputConfig = OutputConfig()
+    logging: LoggingConfig = LoggingConfig()
+
+
+def load_config(path: Path | None = None) -> Settings:
+    """Load settings from TOML file with layered credential resolution.
+
+    Resolution order (highest priority first):
+    1. Environment variables (ORBITABLE_DATABASE__USERNAME, etc.)
+    2. User secrets (~/.config/orbitable.toml)
+    3. System secrets file (database.secrets_file in config)
+    4. Values in config.toml
+    """
+    toml_data: dict = {}
+
+    if path is not None and path.exists():
+        with open(path, "rb") as f:
+            toml_data = tomllib.load(f)
+
+    # Load system secrets file if specified
+    db_data = toml_data.get("database", {})
+    secrets_file = db_data.get("secrets_file")
+    if secrets_file:
+        secrets_path = Path(secrets_file)
+        if secrets_path.exists():
+            with open(secrets_path, "rb") as f:
+                secrets = tomllib.load(f)
+            # Merge secrets into database config (secrets_file has lower priority
+            # than values already in db_data, which have lower priority than env vars)
+            for key in ("username", "password"):
+                if key in secrets and key not in db_data:
+                    db_data[key] = secrets[key]
+            toml_data["database"] = db_data
+
+    # Load user-local secrets (~/.config/orbitable.toml)
+    user_secrets_path = Path.home() / ".config" / "orbitable.toml"
+    if user_secrets_path.exists():
+        with open(user_secrets_path, "rb") as f:
+            user_secrets = tomllib.load(f)
+        for key in ("username", "password"):
+            if key in user_secrets and key not in db_data:
+                db_data[key] = user_secrets[key]
+        toml_data["database"] = db_data
+
+    # pydantic-settings handles env var overrides automatically
+    return Settings(**toml_data)

orbitable/generator.py

@@ -0,0 +1,148 @@
+import pathlib
+
+from loguru import logger
+from sgp4.api import Satrec
+from sgp4.exporter import export_omm
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from orbitable.config import OutputConfig
+from orbitable.model import TLE
+from orbitable.reader import TLETuple, write_omm_csv, write_tle
+
+
+def _reconstruct_satrec(tle: TLE) -> Satrec:
+    """Reconstruct a Satrec object from stored TLE lines."""
+    return Satrec.twoline2rv(tle.line1, tle.line2)
+
+
+def _safe_export_omm(sat: Satrec, name: str) -> dict | None:
+    """Export OMM dict from Satrec, returning None if export fails."""
+    try:
+        return export_omm(sat, name)
+    except (ValueError, AttributeError):
+        return None
+
+
+def _get_object_name(tle: TLE) -> str:
+    """Get object name from OmmMetadata if available, else fall back to object_id."""
+    if tle.omm_metadata and tle.omm_metadata.object_name:
+        return tle.omm_metadata.object_name
+    return tle.object_id
+
+
+def generate_date_files(
+    session: Session, output_dir: pathlib.Path, config: OutputConfig
+) -> None:
+    """Generate one file per date with the latest TLE per object."""
+    # Get distinct dates (UTC date truncation of epoch)
+    date_query = select(func.date(TLE.epoch).label("d")).distinct()
+    dates = session.execute(date_query).scalars().all()
+
+    logger.info(f"Generating date files for {len(dates)} dates")
+
+    for date_str in dates:
+        if date_str is None:
+            continue
+
+        # Subquery: max epoch per norad_cat_id on this date
+        subq = (
+            select(
+                TLE.norad_cat_id,
+                func.max(TLE.epoch).label("max_epoch"),
+            )
+            .where(func.date(TLE.epoch) == date_str)
+            .group_by(TLE.norad_cat_id)
+            .subquery()
+        )
+
+        # Join back to get full TLE rows
+        stmt = (
+            select(TLE)
+            .join(
+                subq,
+                (TLE.norad_cat_id == subq.c.norad_cat_id)
+                & (TLE.epoch == subq.c.max_epoch),
+            )
+            .order_by(TLE.norad_cat_id)
+        )
+        tles = session.execute(stmt).scalars().all()
+
+        if not tles:
+            continue
+
+        filename_date = date_str.replace("-", "")
+
+        # TLE output
+        if config.formats.tle:
+            tle_path = output_dir / f"{filename_date}.tle"
+            tle_tuples: list[TLETuple] = [(t.line1, t.line2) for t in tles]
+            write_tle(tle_path, tle_tuples)
+
+        # OMM output
+        if config.formats.omm:
+            omm_path = output_dir / f"{filename_date}.omm"
+            omm_records = []
+            for tle in tles:
+                sat = _reconstruct_satrec(tle)
+                name = _get_object_name(tle)
+                record = _safe_export_omm(sat, name)
+                if record is not None:
+                    omm_records.append(record)
+            write_omm_csv(omm_path, omm_records)
+
+
+def generate_object_files(
+    session: Session, output_dir: pathlib.Path, config: OutputConfig
+) -> None:
+    """Generate one file per satellite with all its TLEs."""
+    # Get distinct NORAD IDs
+    norad_ids = (
+        session.execute(select(TLE.norad_cat_id).distinct().order_by(TLE.norad_cat_id))
+        .scalars()
+        .all()
+    )
+
+    logger.info(f"Generating object files for {len(norad_ids)} satellites")
+
+    for norad_id in norad_ids:
+        if norad_id is None:
+            continue
+
+        stmt = select(TLE).where(TLE.norad_cat_id == norad_id).order_by(TLE.epoch)
+        tles = session.execute(stmt).scalars().all()
+
+        if not tles:
+            continue
+
+        # TLE output
+        if config.formats.tle:
+            tle_path = output_dir / f"{norad_id}.tle"
+            tle_tuples: list[TLETuple] = [(t.line1, t.line2) for t in tles]
+            write_tle(tle_path, tle_tuples)
+
+        # OMM output
+        if config.formats.omm:
+            omm_path = output_dir / f"{norad_id}.omm"
+            omm_records = []
+            for tle in tles:
+                sat = _reconstruct_satrec(tle)
+                name = _get_object_name(tle)
+                record = _safe_export_omm(sat, name)
+                if record is not None:
+                    omm_records.append(record)
+            write_omm_csv(omm_path, omm_records)
+
+
+def generate(session: Session, config: OutputConfig) -> None:
+    """Generate all configured output files."""
+    output_dir = pathlib.Path(config.dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if config.types.date_files:
+        generate_date_files(session, output_dir, config)
+
+    if config.types.object_files:
+        generate_object_files(session, output_dir, config)
+
+    logger.info(f"Output generation complete → {output_dir}")

orbitable/ingest.py

@@ -0,0 +1,211 @@
+import pathlib
+from typing import Sequence
+
+from loguru import logger
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from orbitable.config import IngestSource
+from orbitable.model import OmmMetadata, TLE, utcnow
+from orbitable.reader import (
+    TLETuple,
+    detect_format,
+    read_omm_csv,
+    read_omm_json,
+    read_omm_xml,
+    read_tle,
+)
+
+CHUNK_SIZE = 5000
+
+
+def _bulk_insert_tles(session: Session, records: list[dict]) -> int:
+    """Bulk insert TLE records with dialect-aware dedup.
+
+    Returns count of newly inserted rows.
+    """
+    if not records:
+        return 0
+
+    dialect = session.bind.dialect.name  # type: ignore[union-attr]
+    table = TLE.__table__
+    total_inserted = 0
+
+    for i in range(0, len(records), CHUNK_SIZE):
+        chunk = records[i : i + CHUNK_SIZE]
+
+        if dialect == "sqlite":
+            from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+
+            stmt = sqlite_insert(table).on_conflict_do_nothing(  # type: ignore[arg-type]
+                index_elements=["line1", "line2"]
+            )
+        elif dialect in ("mysql", "mariadb"):
+            from sqlalchemy import insert
+
+            stmt = insert(table).prefix_with("IGNORE")  # type: ignore[arg-type]
+        else:
+            from sqlalchemy import insert
+
+            stmt = insert(table).prefix_with("IGNORE")  # type: ignore[arg-type]
+
+        result = session.execute(stmt, chunk)
+        total_inserted += result.rowcount
+        session.commit()
+
+    return total_inserted
+
+
+def ingest_tles(session: Session, tles: Sequence[TLETuple]) -> int:
+    """Ingest TLE tuples into the database.
+
+    Skips malformed records and duplicates. Returns count of newly inserted rows.
+    """
+    records = []
+    for line1, line2 in tles:
+        try:
+            tle = TLE.from_twoline(line1, line2)
+            now = utcnow()
+            record = _tle_to_record(tle, now)
+            records.append(record)
+        except Exception:
+            logger.warning(f"Skipping malformed TLE: {line1[:20]}...")
+
+    return _bulk_insert_tles(session, records)
+
+
+def _tle_to_record(tle: TLE, now=None) -> dict:
+    """Convert a TLE ORM object to a dict for Core-level INSERT."""
+    if now is None:
+        now = utcnow()
+    record = {
+        col.name: getattr(tle, col.name)
+        for col in TLE.__table__.columns
+        if col.name != "id"
+    }
+    record["created"] = now
+    record["modified"] = now
+    return record
+
+
+def ingest_omm(session: Session, omm_records: list[dict]) -> int:
+    """Ingest OMM records into the database.
+
+    Extracts TLE_LINE1/TLE_LINE2 from each record, inserts into TLE table,
+    then populates OmmMetadata for newly inserted rows.
+    Returns count of newly inserted TLE rows.
+    """
+    # Build TLE records from OMM data
+    tle_records = []
+    omm_by_lines: dict[tuple[str, str], dict] = {}
+
+    for omm in omm_records:
+        line1 = omm.get("TLE_LINE1", "").strip()
+        line2 = omm.get("TLE_LINE2", "").strip()
+        if not line1 or not line2:
+            logger.warning(
+                f"OMM record missing TLE lines: {omm.get('OBJECT_NAME', 'unknown')}"
+            )
+            continue
+
+        try:
+            tle = TLE.from_twoline(line1, line2)
+            record = _tle_to_record(tle)
+            tle_records.append(record)
+            omm_by_lines[(line1, line2)] = omm
+        except Exception:
+            logger.warning(
+                f"Skipping malformed OMM record: {omm.get('OBJECT_NAME', 'unknown')}"
+            )
+
+    # Bulk insert TLE rows
+    inserted = _bulk_insert_tles(session, tle_records)
+
+    if not omm_by_lines:
+        return inserted
+
+    # FK resolution: SELECT back by (line1, line2) to get IDs
+    line_pairs = list(omm_by_lines.keys())
+    for i in range(0, len(line_pairs), CHUNK_SIZE):
+        chunk = line_pairs[i : i + CHUNK_SIZE]
+        # Query TLE rows that match our line pairs and don't have metadata yet
+        stmt = (
+            select(TLE.id, TLE.line1, TLE.line2)
+            .where(
+                TLE.line1.in_([lp[0] for lp in chunk]),
+                TLE.line2.in_([lp[1] for lp in chunk]),
+            )
+            .outerjoin(OmmMetadata, TLE.id == OmmMetadata.tle_id)
+            .where(OmmMetadata.id.is_(None))
+        )
+        rows = session.execute(stmt).all()
+
+        metadata_records = []
+        for tle_id, line1, line2 in rows:
+            omm = omm_by_lines.get((line1, line2))
+            if omm is None:
+                continue
+            metadata_records.append(
+                OmmMetadata(
+                    tle_id=tle_id,
+                    object_name=omm.get("OBJECT_NAME"),
+                    object_type=omm.get("OBJECT_TYPE"),
+                    country_code=omm.get("COUNTRY_CODE"),
+                    rcs_size=omm.get("RCS_SIZE"),
+                    launch_date=omm.get("LAUNCH_DATE"),
+                    site=omm.get("SITE"),
+                    decay_date=omm.get("DECAY_DATE"),
+                    originator=omm.get("ORIGINATOR"),
+                    gp_id=int(omm["GP_ID"]) if omm.get("GP_ID") else None,
+                )
+            )
+
+        if metadata_records:
+            session.add_all(metadata_records)
+            session.commit()
+
+    return inserted
+
+
+def ingest_file(session: Session, path: pathlib.Path) -> int:
+    """Detect format and ingest a single file. Returns count of newly inserted rows."""
+    fmt = detect_format(path)
+    logger.info(f"Ingesting {path} (format: {fmt})")
+
+    if fmt == "tle":
+        tles = read_tle(path)
+        return ingest_tles(session, tles)
+    elif fmt == "omm_json":
+        records = read_omm_json(path)
+        return ingest_omm(session, records)
+    elif fmt == "omm_csv":
+        records = read_omm_csv(path)
+        return ingest_omm(session, records)
+    elif fmt == "omm_xml":
+        records = read_omm_xml(path)
+        return ingest_omm(session, records)
+    else:
+        logger.warning(f"Unknown format for {path}, skipping")
+        return 0
+
+
+def ingest_sources(session: Session, sources: list[IngestSource]) -> int:
+    """Scan configured source directories and ingest all matching files."""
+    total = 0
+    for source in sources:
+        source_path = pathlib.Path(source.path)
+        if not source_path.is_dir():
+            logger.warning(f"Source directory does not exist: {source_path}")
+            continue
+
+        files = sorted(source_path.glob(source.pattern))
+        logger.info(
+            f"Found {len(files)} files in {source_path} matching {source.pattern}"
+        )
+
+        for file in files:
+            count = ingest_file(session, file)
+            logger.info(f"  {file.name}: {count} new records")
+            total += count
+
+    return total

orbitable/model.py

@@ -0,0 +1,181 @@
+import datetime
+from math import degrees, pi, sqrt
+from typing import Optional
+
+from sgp4.alpha5 import to_alpha5
+from sgp4.api import Satrec
+from sgp4.conveniences import sat_epoch_datetime
+from sqlalchemy import DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+def object_id(sat: Satrec) -> str:
+    val = sat.intldesg
+    if len(val) < 2:
+        return val
+    else:
+        return ("20" if int(val[0:2]) < 57 else "19") + val
+
+
+def period(sat: Satrec) -> float:
+    """Calculate orbital period [min]"""
+    a_km = sat.a * sat.radiusearthkm
+    return 2 * pi * sqrt(a_km**3 / sat.mu)
+
+
+def mean_motion(sat: Satrec) -> float:
+    """Mean Motion [revs/day]"""
+    return sat.no_kozai * 60 * 24 / (2 * pi)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def utcnow():
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+class Mixin:
+    id: Mapped[int] = mapped_column(
+        primary_key=True,
+        autoincrement=True,
+        index=True,
+        unique=True,
+    )
+    created: Mapped[datetime.datetime] = mapped_column(
+        default=utcnow,
+        index=True,
+    )
+    modified: Mapped[datetime.datetime] = mapped_column(
+        default=utcnow,
+        onupdate=utcnow,
+        index=True,
+    )
+
+
+class TLE(Base, Mixin):
+    __tablename__ = "tle"
+
+    __table_args__ = (UniqueConstraint("line1", "line2"),)
+
+    line1: Mapped[str] = mapped_column(String(70), index=True)
+    line2: Mapped[str] = mapped_column(String(70), index=True)
+
+    object_id: Mapped[str] = mapped_column(String(15))
+    """International Designator"""
+    norad_cat_id: Mapped[Optional[int]] = mapped_column(index=True)
+    """NORAD Catalog Number ("Satellite Number")"""
+    classification: Mapped[str] = mapped_column(String(1))
+    """Classification Type"""
+
+    # Element Set
+    epoch: Mapped[datetime.datetime] = mapped_column(DateTime, index=True)
+    """Epoch of Mean Keplerian elements (mandatory)"""
+    mean_motion: Mapped[Optional[float]] = mapped_column(index=True)
+    """Keplerian Mean Motion [rev/day]"""
+    eccentricity: Mapped[float] = mapped_column(index=True)
+    """Eccentricity"""
+    inclination: Mapped[float] = mapped_column(index=True)
+    """Inclination [deg]"""
+    ra_of_asc_node: Mapped[float] = mapped_column(index=True)
+    """Right Ascension of Ascending Node [deg]"""
+    arg_of_pericenter: Mapped[float] = mapped_column(index=True)
+    """Argument of Pericenter [deg]"""
+    mean_anomaly: Mapped[float] = mapped_column(index=True)
+    """Mean Anomaly [deg]"""
+
+    # Other TLE Details
+    ephemeris_type: Mapped[int]
+    """Element Set Type"""
+    element_set_no: Mapped[int]
+    """Element Set Number (for this satellite)
+    Normally incremented sequentially, but my be out of sync.
+    """
+    rev_at_epoch: Mapped[Optional[int]]
+    """Revolution Number"""
+    bstar: Mapped[Optional[float]]
+    """Drag-like ballistic coefficient"""
+    mean_motion_dot: Mapped[Optional[float]]
+    """First Time Derivative of Mean Motion (i.e., a drag term)"""
+    mean_motion_ddot: Mapped[Optional[float]]
+    """Second Time Derivative of Mean Motion (i.e., a drag term)"""
+
+    # Derived Values
+    semimajor_axis: Mapped[Optional[float]]
+    """Semi-major Axis [km]"""
+    period: Mapped[Optional[float]]
+    """Orbital Period [min]"""
+    apoapsis_alt: Mapped[Optional[float]]
+    """Apoapsis Altitude [km]"""
+    periapsis_alt: Mapped[Optional[float]]
+    """Periapsis Altitude [km]"""
+
+    omm_metadata: Mapped[Optional["OmmMetadata"]] = relationship(
+        back_populates="tle", uselist=False, lazy="select"
+    )
+
+    def __repr__(self) -> str:
+        n = to_alpha5(self.norad_cat_id)
+        t = self.epoch.isoformat(sep="T", timespec="seconds")
+        e = self.element_set_no
+        return f"TLE(norad_cat_id={n!r}, epoch={t!r}, element_set_no={e})"
+
+    @classmethod
+    def from_twoline(cls, *lines: str) -> "TLE":
+        if len(lines) == 2:
+            line1, line2 = lines
+        elif len(lines) == 3:
+            _, line1, line2 = lines
+        else:
+            msg = "Must provide an iterable of length 2 or 3"
+            raise ValueError(msg)
+
+        sat = Satrec.twoline2rv(line1, line2)
+        fields = _fields_from_satrec(sat)
+
+        return cls(line1=line1, line2=line2, **fields)
+
+
+def _fields_from_satrec(sat: Satrec) -> dict:
+    """Extract orbital element fields from a populated Satrec object."""
+    epoch = sat_epoch_datetime(sat)
+    return dict(
+        object_id=object_id(sat),
+        norad_cat_id=sat.satnum,
+        classification=sat.classification,
+        epoch=epoch,
+        mean_motion=mean_motion(sat),
+        eccentricity=sat.ecco,
+        inclination=degrees(sat.inclo),
+        ra_of_asc_node=degrees(sat.nodeo),
+        arg_of_pericenter=degrees(sat.argpo),
+        mean_anomaly=degrees(sat.mo),
+        ephemeris_type=sat.ephtype,
+        element_set_no=sat.elnum,
+        rev_at_epoch=sat.revnum,
+        bstar=sat.bstar,
+        mean_motion_dot=sat.ndot,
+        mean_motion_ddot=sat.nddot,
+        semimajor_axis=sat.a * sat.radiusearthkm,
+        period=period(sat),
+        apoapsis_alt=sat.alta * sat.radiusearthkm,
+        periapsis_alt=sat.altp * sat.radiusearthkm,
+    )
+
+
+class OmmMetadata(Base, Mixin):
+    __tablename__ = "omm_metadata"
+
+    tle_id: Mapped[int] = mapped_column(ForeignKey("tle.id"), unique=True, index=True)
+    tle: Mapped["TLE"] = relationship(back_populates="omm_metadata")
+
+    object_name: Mapped[Optional[str]] = mapped_column(String(100))
+    object_type: Mapped[Optional[str]] = mapped_column(String(20))
+    country_code: Mapped[Optional[str]] = mapped_column(String(10))
+    rcs_size: Mapped[Optional[str]] = mapped_column(String(10))
+    launch_date: Mapped[Optional[str]] = mapped_column(String(10))
+    site: Mapped[Optional[str]] = mapped_column(String(20))
+    decay_date: Mapped[Optional[str]] = mapped_column(String(10))
+    originator: Mapped[Optional[str]] = mapped_column(String(20))
+    gp_id: Mapped[Optional[int]] = mapped_column()

orbitable/reader.py

@@ -0,0 +1,204 @@
+import concurrent.futures
+import csv
+import datetime
+import json
+import os
+import pathlib
+from typing import Callable, Iterable, TypeVar, Union
+
+from sgp4 import omm as sgp4_omm
+
+PathLike = Union[str, os.PathLike, pathlib.Path]
+TLETuple = tuple[str, str]
+
+T = TypeVar("T")
+
+GroupByKey = TypeVar("GroupByKey")
+
+
+def group_by(
+    tles: list[TLETuple], key: Callable[[TLETuple], GroupByKey]
+) -> dict[GroupByKey, list[TLETuple]]:
+    """Groups input TLEs by values from a callable key."""
+    results: dict[GroupByKey, list[TLETuple]] = {}
+    for tle in tles:
+        group = key(tle)
+        if group not in results:
+            results[group] = []
+        results[group].append(tle)
+    return results
+
+
+def unique(tles: list[T]) -> list[T]:
+    """Returns input as a list list ensuring unique entries."""
+    return list(dict.fromkeys(tles).keys())
+
+
+def tle_epoch(tle: TLETuple) -> float:
+    """Get the epoch (float) from a TLE, adjusted for Y2K."""
+    epoch = float(tle[0][18:32].replace(" ", "0"))
+    epoch += 1900_000 if epoch // 1000 >= 57 else 2000_000
+    return epoch
+
+
+def tle_date(tle: TLETuple) -> str:
+    """Get the date (as str) from a TLE."""
+    epoch = tle_epoch(tle)
+    year, doy = divmod(epoch, 1000)
+    doy = doy // 1
+    dt = datetime.datetime(int(year), 1, 1) + datetime.timedelta(days=int(doy - 1))
+    return dt.strftime("%Y%m%d")
+
+
+def tle_satnum(tle: TLETuple) -> str:
+    """Extract the (Alpha-5) Satnum from a TLE."""
+    return tle[0][2:7].replace(" ", "0")
+
+
+def read_tle(
+    file: PathLike,
+) -> list[TLETuple]:
+    """Read a single TLE file."""
+    results: list[TLETuple] = []
+    with open(file, "r") as f:
+        line1: str | None = None
+        for raw in f:
+            line = raw.rstrip()
+            if not line:
+                continue
+            if line[0] == "1":
+                line1 = line
+            elif line[0] == "2" and line1 is not None:
+                results.append((line1, line))
+                line1 = None
+    return results
+
+
+def read_tles(files: Iterable[PathLike]) -> list[TLETuple]:
+    """Read multiple TLE files."""
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        futures = [executor.submit(read_tle, file) for file in files]
+        tles = []
+        for future in futures:
+            results = future.result()
+            tles.extend(results)
+    return tles
+
+
+def write_tle(
+    file_path: PathLike,
+    tles: Iterable[TLETuple],
+    *,
+    sort: bool = False,
+    deduplicate: bool = False,
+) -> None:
+    if deduplicate:
+        tles = unique(list(tles))
+
+    if sort:
+        tles = sorted(tles, key=tle_epoch)
+        tles = sorted(tles, key=tle_satnum)
+
+    with open(file_path, "w") as f:
+        for line1, line2 in tles:
+            print(line1, file=f)
+            print(line2, file=f)
+
+
+def write_tles(
+    files: dict[pathlib.Path, Iterable[TLETuple]],
+    *,
+    deduplicate: bool = True,
+    sort: bool = False,
+) -> None:
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        futures: dict[concurrent.futures.Future, pathlib.Path] = {
+            executor.submit(
+                write_tle, file, tles, deduplicate=deduplicate, sort=sort
+            ): file
+            for file, tles in files.items()
+        }
+
+        for future in futures:
+            future.result()
+
+
+# --- OMM Format Support ---
+
+
+def read_omm_json(file: PathLike) -> list[dict]:
+    """Read Space-Track JSON format OMM data.
+
+    Handles both single-object (bare dict) and array forms.
+    """
+    with open(file, "r") as f:
+        data = json.load(f)
+    if isinstance(data, dict):
+        return [data]
+    return data
+
+
+def read_omm_csv(file: PathLike) -> list[dict]:
+    """Read OMM CSV format using sgp4's parser."""
+    with open(file, "r") as f:
+        return list(sgp4_omm.parse_csv(f))
+
+
+def read_omm_xml(file: PathLike) -> list[dict]:
+    """Read OMM XML format using sgp4's parser."""
+    with open(file, "rb") as f:
+        return list(sgp4_omm.parse_xml(f))
+
+
+# Standard OMM CSV field order (matches Space-Track output)
+OMM_CSV_FIELDS = [
+    "OBJECT_NAME",
+    "OBJECT_ID",
+    "EPOCH",
+    "MEAN_MOTION",
+    "ECCENTRICITY",
+    "INCLINATION",
+    "RA_OF_ASC_NODE",
+    "ARG_OF_PERICENTER",
+    "MEAN_ANOMALY",
+    "EPHEMERIS_TYPE",
+    "CLASSIFICATION_TYPE",
+    "NORAD_CAT_ID",
+    "ELEMENT_SET_NO",
+    "REV_AT_EPOCH",
+    "BSTAR",
+    "MEAN_MOTION_DOT",
+    "MEAN_MOTION_DDOT",
+]
+
+
+def write_omm_csv(
+    file_path: PathLike,
+    records: list[dict],
+) -> None:
+    """Write OMM records as CSV."""
+    if not records:
+        return
+    fieldnames = OMM_CSV_FIELDS
+    with open(file_path, "w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames, extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(records)
+
+
+def detect_format(file: PathLike) -> str:
+    """Detect file format by extension.
+
+    Returns one of: "tle", "omm_json", "omm_csv", "omm_xml"
+    """
+    ext = pathlib.Path(file).suffix.lower()
+    if ext in (".tle", ".txt", ".3le"):
+        return "tle"
+    elif ext == ".json":
+        return "omm_json"
+    elif ext == ".csv":
+        return "omm_csv"
+    elif ext == ".xml":
+        return "omm_xml"
+    else:
+        return "tle"  # default to TLE format

orbitable-0.2.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: orbitable
+Version: 0.2.0
+Summary: Orbital element database management tool
+Author-email: Jonathan Olsten <jolsten@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: sgp4>=2.24
+Requires-Dist: sqlalchemy>=2.0.40
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Description-Content-Type: text/markdown
+
+# Orbitable
+
+Orbital element database manager. Ingests TLE (Two-Line Element) and OMM (Orbit Mean-Elements Message) files into a database and generates organized output files by date and satellite.
+
+## Installation
+
+```bash
+pip install orbitable
+
+# For MariaDB/MySQL support:
+pip install orbitable[mysql]
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add orbitable
+```
+
+## Quick Start
+
+### 1. Scaffold configuration
+
+```bash
+orbitable init
+```
+
+This creates two files:
+
+- `./config.toml` -- main configuration (database, ingest sources, output settings)
+- `~/.config/orbitable.toml` -- user-local database credentials
+
+Use `-c` to specify a different config path:
+
+```bash
+orbitable -c /etc/orbitable/config.toml init
+```
+
+### 2. Configure
+
+Edit `config.toml` to set your database and ingest sources. The generated file is fully commented -- see below for a summary.
+
+**SQLite (default):**
+
+```toml
+[database]
+drivername = "sqlite"
+name = "orbitable.db"
+```
+
+**MariaDB/MySQL:**
+
+```toml
+[database]
+drivername = "mysql+pymysql"
+host = "localhost"
+port = 3306
+name = "orbitable"
+secrets_file = "/etc/orbitable/secrets.toml"
+```
+
+Then add your credentials to `~/.config/orbitable.toml`:
+
+```toml
+username = "myuser"
+password = "mypassword"
+```
+
+### 3. Ingest TLE/OMM files
+
+Scan configured source directories:
+
+```bash
+orbitable ingest
+```
+
+Or ingest specific files:
+
+```bash
+orbitable ingest /path/to/20260327.tle /path/to/20260327.json
+```
+
+File format is auto-detected by extension:
+
+| Extension          | Format              |
+| ------------------ | ------------------- |
+| `.tle`, `.txt`, `.3le` | Two-Line Element |
+| `.json`            | Space-Track OMM JSON |
+| `.csv`             | OMM CSV              |
+| `.xml`             | OMM XML              |
+
+Ingestion is idempotent -- duplicate records are silently skipped.
+
+### 4. Generate output files
+
+```bash
+orbitable generate
+```
+
+This produces files in the configured output directory:
+
+- **Date files** (`YYYYMMDD.tle` / `YYYYMMDD.omm`) -- one TLE per satellite for each date (latest epoch that day)
+- **Object files** (`25544.tle` / `25544.omm`) -- all TLEs for a single satellite, ordered by epoch
+
+## Automating with Cron
+
+Orbitable is designed to run via cron rather than as a long-running service. Both `ingest` and `generate` are idempotent and safe to re-run.
+
+**Ingest and generate every 4 hours:**
+
+```cron
+0 */4 * * * orbitable -c /etc/orbitable/config.toml ingest && orbitable -c /etc/orbitable/config.toml generate
+```
+
+**Ingest hourly, generate once daily at 03:00 UTC:**
+
+```cron
+0 * * * * orbitable -c /etc/orbitable/config.toml ingest
+0 3 * * * orbitable -c /etc/orbitable/config.toml generate
+```
+
+**With logging to a file:**
+
+```cron
+0 */4 * * * orbitable -c /etc/orbitable/config.toml ingest >> /var/log/orbitable.log 2>&1 && orbitable -c /etc/orbitable/config.toml generate >> /var/log/orbitable.log 2>&1
+```
+
+## Credential Resolution
+
+Database credentials are resolved in priority order:
+
+1. **Environment variables** -- `ORBITABLE_DATABASE__USERNAME` / `ORBITABLE_DATABASE__PASSWORD`
+2. **User secrets file** -- `~/.config/orbitable.toml`
+3. **System secrets file** -- path set via `secrets_file` in `config.toml`
+4. **config.toml values** -- not recommended for credentials
+
+For cron jobs, either use the user secrets file or export environment variables in the crontab:
+
+```cron
+ORBITABLE_DATABASE__USERNAME=myuser
+ORBITABLE_DATABASE__PASSWORD=mypassword
+0 */4 * * * orbitable -c /etc/orbitable/config.toml ingest && orbitable -c /etc/orbitable/config.toml generate
+```
+
+## CLI Reference
+
+```
+orbitable [-c CONFIG] COMMAND
+
+Commands:
+  init       Scaffold config.toml and ~/.config/orbitable.toml
+  ingest     Ingest TLE/OMM files into the database
+  generate   Generate output TLE/OMM files from the database
+
+Options:
+  -c, --config PATH   Path to config.toml (default: ./config.toml)
+```
+
+## Configuration Reference
+
+### `[database]`
+
+| Field          | Default      | Description                                |
+| -------------- | ------------ | ------------------------------------------ |
+| `drivername`   | `"sqlite"`   | SQLAlchemy driver (`sqlite`, `mysql+pymysql`) |
+| `name`         | `":memory:"` | Database name or file path                 |
+| `host`         |              | Database host                              |
+| `port`         |              | Database port                              |
+| `username`     |              | Database username (prefer secrets file)    |
+| `password`     |              | Database password (prefer secrets file)    |
+| `secrets_file` |              | Path to a TOML file with username/password |
+
+### `[[ingest.sources]]`
+
+| Field     | Default   | Description                        |
+| --------- | --------- | ---------------------------------- |
+| `path`    |           | Directory to scan for files        |
+| `pattern` | `"*.tle"` | Glob pattern for matching files    |
+
+### `[output]`
+
+| Field   | Default      | Description                     |
+| ------- | ------------ | ------------------------------- |
+| `dir`   | `"./output"` | Output directory                |
+
+### `[output.formats]`
+
+| Field | Default | Description                 |
+| ----- | ------- | --------------------------- |
+| `tle` | `true`  | Generate .tle output files  |
+| `omm` | `true`  | Generate .omm (CSV) output  |
+
+### `[output.types]`
+
+| Field          | Default | Description                                        |
+| -------------- | ------- | -------------------------------------------------- |
+| `date_files`   | `true`  | YYYYMMDD files with latest TLE per satellite       |
+| `object_files` | `true`  | Per-satellite files with all TLEs ordered by epoch  |
+
+### `[logging]`
+
+| Field   | Default  | Description                                    |
+| ------- | -------- | ---------------------------------------------- |
+| `level` | `"INFO"` | Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL |

orbitable-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+orbitable/__init__.py,sha256=YhnTJ1eJoEVD95gMKIAELlWuK3FeoHjIDyl428vpNE4,51
+orbitable/_version.py,sha256=s9U3X54Pdr-Jlh9GP6LBaa_VRos7qs_wtrVefUHHNIA,520
+orbitable/cli.py,sha256=Qoc_96gvVEgN9LDt2YW7HYNHlYnJLOqZBZ3hRyMA2YA,6494
+orbitable/config.py,sha256=Gx6QhQC9KQKnb31FNSmwJM7GsD93We_N1nwZtAXhKQI,3463
+orbitable/generator.py,sha256=JaKaVvC7xGrgMd88FlCbOR8UGoeyQJ97UcE28WraATs,4735
+orbitable/ingest.py,sha256=I-Ig3Azq-GukoLGif7ks7a652Ih9EnGa2iWTl-xkfa0,6729
+orbitable/model.py,sha256=XfteoYgDDmeK4wGZocVOSSgo7xzw2ya8FUQYbDNAWNY,6037
+orbitable/reader.py,sha256=KFTznIM9euet0f4urmeo6rBL5FXQ0hKWFaf1GuOvnR0,5248
+orbitable-0.2.0.dist-info/METADATA,sha256=ttDAhE1r3CaTILiDwxcvKf1MP7Y3ipJ-ZzmawGYB9ps,6356
+orbitable-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+orbitable-0.2.0.dist-info/entry_points.txt,sha256=VuRn13lX9clQ2ILIQTHCX1CZyMlsPlPE639Yqks4wsg,45
+orbitable-0.2.0.dist-info/RECORD,,

orbitable-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

orbitable-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orbitable = orbitable:main