ADR-027: Python Annotations

Status

Accepted

Context

Strong typing improves code quality, maintainability, and tooling support. Type annotations help catch errors early and provide better documentation for contributors.

Decision

Python code in this project is strongly typed. Contributors should use type annotations throughout the codebase. For example:

def __init__(
    self,
    *args,
    user_profile: Optional[UserProfile] = None,
    selected: bool = False,
    api_version: Optional[str] = None,
    manifest: Optional[SAMPluginCommon] = None,
    plugin_id: Optional[int] = None,
    plugin_meta: Optional[PluginMeta] = None,
    data: Union[dict[str, Any], str, None] = None,
    name: Union[str, None] = None,
    **kwargs,
):

To the extent that Python requirements are added to this project, any available corresponding stubs/annotation packages should be added in kind to smarter/requirements/in/local.in. Example:

django-stubs==5.2.2                 # Type annotations for Django
djangorestframework-stubs==3.16.0   # type annotations for djangorestframework
mypy_extensions==1.1.0              # Type annotations for Python

Alternatives Considered

Not using type annotations.
Relying solely on dynamic typing.

Consequences

Positive: - Improves code reliability and maintainability. - Enables better static analysis and tooling. - Reduces runtime errors due to type mismatches.
Negative: - Requires contributors to be familiar with Python type hints. - May require additional effort to maintain type stubs and annotations.