Skip to content

SPEC.md

Latest commit

 

History

History
84 lines (72 loc) · 4.5 KB

SPEC.md

File metadata and controls

84 lines (72 loc) · 4.5 KB
Raw

SPEC

§G

asdf-firefly CLI → inspect Roman WFI ASDF metadata, bounded previews, export Firefly-compatible FITS/table products. Inputs may be local ASDF paths or remote ASDF URIs incl HTTP(S), S3.

§C

  • docs-first project; docs ! match CLI behavior
  • Roman WFI target; generic ASDF only where supports Roman inspection/export
  • ASDF tree = navigable header; not flat FITS cards
  • large arrays/tables ⊥ load/print unless command explicitly requires
  • remote ASDF objects ⊥ whole download unless selected data/export requires or seekable stream unavailable
  • ASDF file context ! open while accessing lazy/memmap data
  • remote source context ! open while ASDF lazy data reachable
  • Firefly integration = export-and-open handoff until deeper API documented
  • persistent writes ! explicit output path; destructive overwrite ! --overwrite
  • temp Firefly products cleaned by default; retained on --keep-temp
  • command behavior deterministic & scriptable; prompts ⊥ initial CLI
  • initial CLI scaffold uses stdlib argparse
  • S3 support optional extra via fsspec + s3fs
  • Roman tagged-object support optional extra via asdf-astropy, gwcs, roman-datamodels
  • errors ! clear exit codes per README.md

§I

  • arg: FILE = local path | HTTP(S) URL | S3 URI
  • cmd: asdf-firefly info FILE → compact ASDF summary
  • cmd: asdf-firefly tree FILE → metadata tree; opts --depth, --arrays, --types, --find
  • cmd: asdf-firefly get FILE PATH → value summary; formats text|json|yaml
  • cmd: asdf-firefly validate FILE → ASDF validation; opts --strict, --format json
  • cmd: asdf-firefly tables FILE → table-like object list
  • cmd: asdf-firefly table show FILE PATH → bounded terminal preview
  • cmd: asdf-firefly table export FILE PATH OUTPUT → table file; formats ecsv|csv|fits|votable|parquet
  • cmd: asdf-firefly table open FILE PATH → temp table export + Firefly open
  • cmd: asdf-firefly images FILE → image-like array list
  • cmd: asdf-firefly image export FILE PATH OUTPUT → FITS export; opts --hdu, --include-wcs, --overwrite, --plane
  • cmd: asdf-firefly image open FILE PATH → temp FITS export + Firefly open
  • cmd: asdf-firefly fits-header FILE → embedded/synthesized FITS header view TBD
  • env: ASDF_FIREFLY_URL ? override Firefly URL
  • env: ASDF_FIREFLY_KEEP_TEMP ? override temp retention
  • cfg: ~/.config/asdf-firefly/config.toml → [firefly], [display], [export]
  • cfg: [remote] → S3 anon/cache opts TBD
  • extra: roman → Roman ASDF extension support

§V

V1: ∀ CLI read → ASDF opened via context manager. V2: array/table terminal output → summary/limit by default. V3: path syntax → slash-separated dict keys + list indexes. V4: missing path → exit code 4. V5: unsupported conversion → exit code 5 + reason. V6: Firefly open failure → exit code 6. V7: table export → normalize to astropy.table.Table or QTable before write. V8: image export → FITS output readable by Astropy. V9: 3D image export → --plane required initially. V10: metadata/WCS not representable in FITS → warning, not silent discard. V11: Firefly handoff → exported readable local product before launch/open. V12: optional dependency missing → clear action/error, not traceback. V13: docs changed with command behavior changes. V14: implementation status changes → IMPLEMENTATION_PLAN.md updated same change. V15: tests added with behavior changes once package scaffold exists. V16: metadata-only remote commands → no whole-object download when seekable source available. V17: S3 source without optional deps → clear install hint for asdf-firefly[remote]. V18: URI source resolver → preserve original URI in asdf.open(..., uri=...). V19: missing Roman ASDF extensions → warning OK; metadata inspection still works where raw fallback sufficient.

§T

id|status|task|cites T1|x|scaffold package, CLI entry point, test layout|V13,V14,V15,I.* T2|x|implement ASDF inspection commands|V1,V2,V3,V4,V13,I.info,I.tree,I.get,I.validate T3|.|implement object discovery commands|V2,V13,I.tables,I.images T4|.|implement table show/export/open|V2,V7,V11,V12,V13,I.table T5|.|implement image export/open|V2,V8,V9,V10,V11,V13,I.image T6|.|implement Firefly config/env/temp handling|V6,V11,V13,I.env,I.cfg T7|.|package/release workflow|V13,V14,I.* T8|.|resolve open decisions: Firefly open mechanism, fits-header scope, typed Roman object requirements|§C,§I,§V T9|x|implement source resolver for local, HTTP(S), S3 ASDF inputs|V1,V16,V17,V18,I.arg

§B

id|date|cause|fix