Skip to content

feat: export missing public API types for 1.0 surface - #45

Open
rcbevans wants to merge 2 commits into
mainfrom
feat/api-surface-1.0
Open

feat: export missing public API types for 1.0 surface#45
rcbevans wants to merge 2 commits into
mainfrom
feat/api-surface-1.0

Conversation

@rcbevans

Copy link
Copy Markdown
Contributor

Summary

Exports eight types that users and third-party backend implementers already need but had to import from deep internal paths:

  • Backend - the Protocol that storage backends implement
  • Clock, SystemClock - time abstraction and its production implementation
  • FakeClock - the test clock, now importable from the top level
  • JobRow, JobPage - the data structures returned by job listing queries
  • TaskQSettings, WorkerSettings - configuration types for the client and worker

Importing these from internal modules like taskq.backend._protocol or taskq.testing.clock would break on any future restructure. Adding them to __all__ makes them part of the stable public API surface for 1.0.

Test coverage

New tests/test_public_api_exports.py verifies:

  • Each new export is importable from taskq and present in __all__
  • Clock and Backend are @runtime_checkable Protocols
  • SystemClock is a frozen dataclass with no fields
  • FakeClock has now() and monotonic() methods
  • JobRow is a frozen dataclass with id, status, and actor fields
  • JobPage is a frozen dataclass with jobs and next_cursor fields
  • TaskQSettings has a callable load classmethod
  • WorkerSettings is a subclass of TaskQSettings
  • Every name in __all__ is actually importable (regression guard)
  • No duplicate entries in __all__
  • Capitalised entries in __all__ are sorted

Verification

  • ruff check - clean
  • pyright - clean
  • pytest tests/test_public_api_exports.py - all 16 tests pass

@rcbevans
rcbevans requested review from XBeg9, clinzy and kjw-azx July 29, 2026 04:28
@rcbevans rcbevans self-assigned this Jul 30, 2026
Add Backend, Clock, SystemClock, FakeClock, JobRow, JobPage,
TaskQSettings, and WorkerSettings to the top-level taskq __all__.
These are types users and third-party backend implementers already
need; importing them from deep internal paths would break on any
future restructure.

New test file pins importability, __all__ membership, and structural
shape (Protocol, dataclass, inheritance) for every new export, plus
a regression guard that every name in __all__ is actually importable.
@rcbevans
rcbevans force-pushed the feat/api-surface-1.0 branch from eac6ce2 to e41f49f Compare July 30, 2026 04:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant