Skip to content

Protocol types for notify_callback and ops_alert_fn #63

@henry0816191

Description

@henry0816191

Problem

The notification and operational alerting callbacks throughout the codebase are untyped. Functions like notify_callback (used to deliver per-user watchlist matches and channel-wide announcements) and ops_alert_fn (used to surface operational errors to operators) are passed as bare Callable parameters without specifying their argument types, return types, or error-handling contracts. This means a caller can pass a function with the wrong signature and the error surfaces only at runtime -- the type checker and linters cannot catch the mismatch. The W24 eval's finding that 18 modules suppress mypy (in the sibling local-ci project) highlights the broader cost of skipping typed callback contracts in codebases that aspire to type coverage.

Acceptance Criteria

  • Define NotifyCallback and OpsAlertFn as typing.Protocol classes with explicit __call__ signatures (argument names, types, return type)
  • All callback parameters in bot.py, monitor.py, and any other modules are annotated with the new Protocol types
  • mypy (or pyright) passes on the modified modules with --strict or equivalent strictness for callback signatures
  • At least one test creates a deliberately mis-typed callback and confirms the type checker would flag it (documented in a comment or typed test fixture)
  • Existing test suite passes without regressions

Implementation Notes

Primary files to modify:

  • src/paperscout/bot.py -- notify_channel(), notify_user(), and any callback parameters
  • src/paperscout/monitor.py -- poll loop callback wiring, ops_alert_fn parameter
  • src/paperscout/models.py or new src/paperscout/protocols.py -- protocol definitions
  • pyproject.toml -- consider removing any ignore_errors overrides on modified modules

References

  • Eval finding: W24 horizon item (untyped callbacks cluster)
  • Related files: src/paperscout/bot.py, src/paperscout/monitor.py, src/paperscout/config.py, src/paperscout/models.py

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions