Problem
src/sixsentences/py.typed is present, so the wheel tells type checkers its
annotations are authoritative. src/sixsentences/__init__.py then exports:
__all__ = ["__version__"]
Everything a caller actually uses — querylang.parser.parse_query,
querylang.translate.translations, corpus.store, pipeline.dedup,
reporting.prisma, coverage.estimator — is reached by importing a submodule
directly. So the package promises typed, stable surfaces and simultaneously
declares that none of them are surface.
The practical consequence: there is no answer to "what can change in a patch
release". Every module path a user imported is either supported or it is not,
and right now nobody has said which. CHANGELOG.md states the project follows
semantic versioning, which only means something once there is a defined public
API to version.
What to decide
- Which names are the supported API. Likely the query language, the corpus
builder and search, the dedup and snowball pipelines, ranking, coverage, the
PRISMA renderers, and the data import and analysis entry points — but that is
a decision, not a list to copy.
- Whether they are re-exported from
sixsentences directly, or whether the
submodule paths themselves are the contract.
- What is explicitly internal, and therefore free to change without notice —
the _-prefixed helpers are already clear, the rest is not.
- Where this is written down. A short "Public API" section in the README, or a
docs page, that the release checklist can point at.
Why now
The package is published as a wheel with checksums and provenance, and the
release checklist gates on version agreement across five files. That machinery
exists to make releases trustworthy. A consumer still cannot tell which import
will survive the next one.
Acceptance criteria
Problem
src/sixsentences/py.typedis present, so the wheel tells type checkers itsannotations are authoritative.
src/sixsentences/__init__.pythen exports:Everything a caller actually uses —
querylang.parser.parse_query,querylang.translate.translations,corpus.store,pipeline.dedup,reporting.prisma,coverage.estimator— is reached by importing a submoduledirectly. So the package promises typed, stable surfaces and simultaneously
declares that none of them are surface.
The practical consequence: there is no answer to "what can change in a patch
release". Every module path a user imported is either supported or it is not,
and right now nobody has said which.
CHANGELOG.mdstates the project followssemantic versioning, which only means something once there is a defined public
API to version.
What to decide
builder and search, the dedup and snowball pipelines, ranking, coverage, the
PRISMA renderers, and the data import and analysis entry points — but that is
a decision, not a list to copy.
sixsentencesdirectly, or whether thesubmodule paths themselves are the contract.
the
_-prefixed helpers are already clear, the rest is not.docs page, that the release checklist can point at.
Why now
The package is published as a wheel with checksums and provenance, and the
release checklist gates on version agreement across five files. That machinery
exists to make releases trustworthy. A consumer still cannot tell which import
will survive the next one.
Acceptance criteria
internal means
__all__and the documentation agreecannot rot
CHANGELOG.mdpoints at it