Skip to content

Provide explicit type hints and pydantic validation for robust usage #34

@lupppig

Description

@lupppig

Description:
Hi team! Thanks for building such an awesome library for the OpenPAYGO ecosystem.

Expected Behavior:
When using the OpenPAYGO library in modern Python backend applications (like FastAPI servers or typing-heavy codebases), developers expect:

  • Clear type definitions showing what arguments standard functions (like decode_token or MetricsRequestHandler) accept and return.
  • When processing JSON or dictionaries from devices, malformed data should raise explicit parsing/validation errors before reaching deep token logic.

Current Behavior:
Currently, functions like decode_token and MetricsRequestHandler rely on loose dictionaries and typeless signatures. Passing incorrect types or malformed historical data can trigger cryptic KeyError or ValueError, making debugging difficult.

Proposed Solution:
Add explicit Python typing (typing.Dict, typing.Optional, etc.) to method signatures across:

  • openpaygo/token_encode.py
  • openpaygo/token_decode.py
  • metrics_request.py / metrics_response.py

Additionally, leverage Pydantic models to automatically validate and parse input data, stripping invalid or unexpected fields.

Implementation Notes:

  • Created openpaygo/models.py with Pydantic models:

    • MetricsDataFormat
    • MetricsRequestData
    • MetricsHistoricalDataStep
  • Functions in metrics_request.py and metrics_response.py now cast dictionaries into Pydantic models.

  • Core files (token_shared.py, token_encode.py, token_decode.py) updated with type hints.

  • Integration tests run successfully with all 80 tests passing.

Benefits:

  • Improved type safety and clearer function signatures.
  • Automatic input/output validation reduces runtime errors.
  • Easier debugging and maintenance for developers.

Metadata

Metadata

Assignees

No one assigned

    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