ModernLeft/athena-file
Watch
4
0
Fork
You've already forked athena-file
 0
Code Issues 2 Pull requests Packages 1 Activity Actions

Epic: 2026-07 fleet audit — release-worthiness and platform fit #33

New issue
Open
opened 2026-07-14 00:00:06 +00:00 by gravityfargo · 1 comment
gravityfargo commented 2026-07-14 00:00:06 +00:00
Owner
Copy link

Master tracking issue from the 2026-07-13 fleet audit (definition doc vs current state, v1.5.0 at audit time). This repo is the first rung of the bottom-up fix campaign: athena-file → athena-api → athena-frontend.

Release-worthiness (blocking a standalone release)

  • LICENSE is entirely absent — no file, no license/license-files in [project], no classifier. README.md:440 references a LICENSE that does not exist. Add AGPL-3.0.
  • Populate src/athena_file/__init__.py (currently 0 bytes) with the public re-exports and a package docstring. from athena_file import FileArchiver — the README's first example — raises ImportError today.
  • Add src/athena_file/py.typed — uv init --lib conformance; without it consumers' mypy (including athena-api's) discards all annotations.
  • README truth pass — examples reference attributes that don't exist: duplicate_groups/total_duplicates/wasted_space (actual: groups, duplicate_count, total_wasted_space), group.hash/group.size (actual: hash_value, total_size), report.verified_count/.missing_files/.corrupted_files (actual: valid_count, get_missing_files(), get_corrupted_files()), ArchiveConfig(max_retries=…) (actual: retry_attempts), storage_stats['files_per_shard'] (not a key). Every example must run.
  • Align Python version claims — README and CLAUDE.md say ≥3.13; pyproject.toml requires ≥3.14.
  • Release discipline — no git tags exist (1.5.0 untagged), no changelog, no commitizen config. Adopt the same commitizen setup as athena-api; tag the current release.

Platform fit (athena-api consumes this library)

  • Document the sharded-JSON engine as NOT used by Athena (DB is the platform's source of truth). Today README/CLAUDE.md present it as the primary storage, and it is hard-wired: FileArchiver constructs it unconditionally; FileVerifier/DeduplicationEngine require it as a constructor arg.
  • Storage-independent FileVerifier path — accept an iterable of (path, expected-hash) so a DB-backed consumer can run fixity sweeps without the JSON catalog. Unblocks the api's fixity-sweep endpoint (see the athena-api master epic).

Documentation

  • pdoc support (Nathan-authored, deliberately) — pdoc config + build tooling; site lands on a subdomain of athena-archive.org.
  • Docstring gaps for pdoc — main.py and plugins/factory.py lack module docstrings; FileWorker.exif_data undocumented; move() docstring malformed ("verivies", Args/Returns mismatch).

Hygiene

  • Remove .coverage, coverage.xml, .env, dist/ from the working tree / ignore them.
  • Fix conftest.py:13 TestFileData NamedTuple pytest-collection warning.
  • Move dev-loop pytest addopts (--last-failed --maxfail=1 -vv) out of the project-wide [tool.pytest.ini_options] defaults — they distort CI runs.

Deferred (derivatives design session, not this epic)

Thumbnail tiers beyond fixed boxes, IIIF level-0 static tiles, dedicated AV posters (currently a single scaled frame at t=1.0s), multi-page PDF previews.

Audit baseline: 247 tests passing, 12 deselected. Internals (hashing, verification, batch, dedup, plugins) are sound; this epic is the library's public face and platform fit.

Master tracking issue from the 2026-07-13 fleet audit (definition doc vs current state, v1.5.0 at audit time). This repo is the first rung of the bottom-up fix campaign: athena-file → athena-api → athena-frontend. ## Release-worthiness (blocking a standalone release) - [ ] **LICENSE is entirely absent** — no file, no `license`/`license-files` in `[project]`, no classifier. `README.md:440` references a LICENSE that does not exist. Add AGPL-3.0. - [ ] **Populate `src/athena_file/__init__.py`** (currently 0 bytes) with the public re-exports and a package docstring. `from athena_file import FileArchiver` — the README's first example — raises ImportError today. - [ ] **Add `src/athena_file/py.typed`** — `uv init --lib` conformance; without it consumers' mypy (including athena-api's) discards all annotations. - [ ] **README truth pass** — examples reference attributes that don't exist: `duplicate_groups`/`total_duplicates`/`wasted_space` (actual: `groups`, `duplicate_count`, `total_wasted_space`), `group.hash`/`group.size` (actual: `hash_value`, `total_size`), `report.verified_count`/`.missing_files`/`.corrupted_files` (actual: `valid_count`, `get_missing_files()`, `get_corrupted_files()`), `ArchiveConfig(max_retries=…)` (actual: `retry_attempts`), `storage_stats['files_per_shard']` (not a key). Every example must run. - [ ] **Align Python version claims** — README and CLAUDE.md say ≥3.13; `pyproject.toml` requires ≥3.14. - [ ] **Release discipline** — no git tags exist (1.5.0 untagged), no changelog, no commitizen config. Adopt the same commitizen setup as athena-api; tag the current release. ## Platform fit (athena-api consumes this library) - [ ] **Document the sharded-JSON engine as NOT used by Athena** (DB is the platform's source of truth). Today README/CLAUDE.md present it as the primary storage, and it is hard-wired: `FileArchiver` constructs it unconditionally; `FileVerifier`/`DeduplicationEngine` require it as a constructor arg. - [ ] **Storage-independent FileVerifier path** — accept an iterable of (path, expected-hash) so a DB-backed consumer can run fixity sweeps without the JSON catalog. Unblocks the api's fixity-sweep endpoint (see the athena-api master epic). ## Documentation - [ ] **pdoc support** (Nathan-authored, deliberately) — pdoc config + build tooling; site lands on a subdomain of athena-archive.org. - [ ] **Docstring gaps for pdoc** — `main.py` and `plugins/factory.py` lack module docstrings; `FileWorker.exif_data` undocumented; `move()` docstring malformed ("verivies", Args/Returns mismatch). ## Hygiene - [ ] Remove `.coverage`, `coverage.xml`, `.env`, `dist/` from the working tree / ignore them. - [ ] Fix `conftest.py:13` `TestFileData` NamedTuple pytest-collection warning. - [ ] Move dev-loop pytest addopts (`--last-failed --maxfail=1 -vv`) out of the project-wide `[tool.pytest.ini_options]` defaults — they distort CI runs. ## Deferred (derivatives design session, not this epic) Thumbnail tiers beyond fixed boxes, IIIF level-0 static tiles, dedicated AV posters (currently a single scaled frame at t=1.0s), multi-page PDF previews. --- Audit baseline: 247 tests passing, 12 deselected. Internals (hashing, verification, batch, dedup, plugins) are sound; this epic is the library's public face and platform fit.
gravityfargo commented 2026-07-14 01:10:34 +00:00
Author
Owner
Copy link

Status 2026-07-13

Landed

  • CI test image pinned to athena-archive-ci:0.1.0 (workflow + Dockerfile.test)
  • Renovate updates applied manually: uv lock --upgrade (9 packages incl. mypy 2.3, ruff 0.15.21, pytest 9.1.1), actions/checkout v7, actions/cache v6 — action refs now plain version tags, no commit hashes
  • AGPL-3.0 LICENSE at repo root; pyproject.toml declares AGPL-3.0-or-later + license-files (closed #32)
  • README Python-version claim removed — pyproject requires-python is authoritative
  • prettier dropped from make format (Python-only repo, ruff covers it)
  • pdoc scaffolded: dev dependency, make docs (static site to docs/, gitignored) and make docs-serve (live preview), numpy docformat

Remaining for release-worthiness

  • Author API docstrings (self-written, in progress) — pdoc site content follows from these
  • Document the CIFS/forceuid utime gotcha in the FileWorker.move docstring (#27)
  • Slim README to install/quick-start once architecture content lives in docstrings/pdoc
  • Enable ruff D (pydocstyle, numpy convention) after the docstring pass
  • Decide hosting for the generated pdoc site

Full test suite green throughout (247 passed, coverage 93%).

## Status 2026-07-13 ### Landed - [x] CI test image pinned to `athena-archive-ci:0.1.0` (workflow + Dockerfile.test) - [x] Renovate updates applied manually: `uv lock --upgrade` (9 packages incl. mypy 2.3, ruff 0.15.21, pytest 9.1.1), actions/checkout v7, actions/cache v6 — action refs now plain version tags, no commit hashes - [x] AGPL-3.0 `LICENSE` at repo root; `pyproject.toml` declares `AGPL-3.0-or-later` + `license-files` (closed #32) - [x] README Python-version claim removed — pyproject `requires-python` is authoritative - [x] `prettier` dropped from `make format` (Python-only repo, ruff covers it) - [x] pdoc scaffolded: dev dependency, `make docs` (static site to `docs/`, gitignored) and `make docs-serve` (live preview), numpy docformat ### Remaining for release-worthiness - [ ] Author API docstrings (self-written, in progress) — pdoc site content follows from these - [ ] Document the CIFS/forceuid utime gotcha in the `FileWorker.move` docstring (#27) - [ ] Slim README to install/quick-start once architecture content lives in docstrings/pdoc - [ ] Enable ruff `D` (pydocstyle, numpy convention) after the docstring pass - [ ] Decide hosting for the generated pdoc site Full test suite green throughout (247 passed, coverage 93%).
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
fix/renovate-config-location
1.6.1
1.6.0
Labels
Clear labels   
bug
Something is not working

  
duplicate
This issue or pull request already exists

  
enhancement
New feature

  
help wanted
Need some help

  
invalid
Something is wrong

  
question
More information is needed

  
wontfix
This won't be fixed

No labels
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ModernLeft/athena-file#33
No description provided.