Skip to content

engine: the package ships py.typed but declares no public API #141

Description

@L4XB

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

  1. 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.
  2. Whether they are re-exported from sixsentences directly, or whether the
    submodule paths themselves are the contract.
  3. What is explicitly internal, and therefore free to change without notice —
    the _-prefixed helpers are already clear, the rest is not.
  4. 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

  • The supported API is listed, in one place, with a statement of what
    internal means
  • __all__ and the documentation agree
  • A test asserts every publicly listed name is importable, so the list
    cannot rot
  • The versioning promise in CHANGELOG.md points at it

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:apiPublic Python and serialization contractstype:rfcDesign proposal requiring agreement before implementation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions