Prune the picmaker.picmaker BC shim exports

[rfrenchseti]

Background

src/picmaker/picmaker.py is a 101-line backward-compatibility shim that re-exports every public symbol from the leaf modules (cli, pipeline, io, enhance, geometry, color, pil_utils, _filters, instruments/*) plus:

• Sibling-package symbols (vicar.VicarError, vicar.VicarImage)
• Legacy class re-exports (ColorNames, ReadTiff16, WriteTiff16)
• Legacy instrument-dict aliases (GALILEO_SSI_DICT, GALILEO_SSI_NAMES, NH_MVIC_DICT, VOYAGER_ISS_DICT)
• Several private helpers (_percentile_lookup, _get_size_for_frame, _get_size_for_size, _resize_one_image, _one_pil_to_array)

The full identity-equality contract is verified by tests/test_api_compat.py. See CODEBASE_CRITIQUE.md §1 (Structure and layout, "Finding (Low) — src/picmaker/picmaker.py shim is intentional BC").

Goal

Audit which of these BC re-exports are actually consumed by downstream users (e.g., sibling SETI packages, internal scripts, ReadTheDocs traffic) vs. which are legacy carry-overs from the pre-PR-3 god-module era. Anything that has no real consumer can be removed in a major-version bump; anything that does have consumers should stay but get a DeprecationWarning emitted at import time so a downstream upgrade path exists.

Suggested approach

1. Inventory the exports. List every name in picmaker.picmaker.__all__ and dir(picmaker.picmaker) minus __*__.
2. Grep the SETI org for each. gh search code 'from picmaker.picmaker import <name>' org:SETI (and import picmaker.picmaker patterns) to find consumers outside this repo.
3. Classify each export:
   • Drop in the next major release — names with zero external consumers.
   • Keep + DeprecationWarning — names with consumers; emit at import time so users know to migrate to from picmaker import X.
   • Permanent BC — names like VicarError / VicarImage that are sibling-package re-exports for convenience (low cost).
4. Update tests/test_api_compat.py to remove the identity assertions for dropped names.
5. Document the migration in CHANGELOG / README under a "Breaking changes" header.

Acceptance criteria

• Audit complete; classification documented in the PR.
• Dropped names removed from picmaker.picmaker and tests/test_api_compat.py.
• Kept names emit DeprecationWarning at import time (with module-level warnings.warn once at first import).
• Permanent BC names keep working with no warning.
• Doc note added to RELEASING.md / CHANGELOG describing the policy and the next-major-release plan.

Related

• CODEBASE_CRITIQUE.md §1 — original finding.
• Priority 6 of CODEBASE_CRITIQUE.md ("Modernize tiff16.py and colornames.py") interacts here: ColorNames / ReadTiff16 / WriteTiff16 are among the BC names exposed.