Add type annotations

[bradenmacdonald]

Attempting to use this library in a project that uses mypy (e.g. openedx-core) results in a mypy error because it doesn't seem to have any type annotations:

signals.py:6: error: Skipping analyzing "openedx_events.tooling": module is installed, but missing library stubs or py.typed marker  [import-untyped]
signals.py:6: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 247 source files)

To fix this:

1. Add type annotations, and
2. Add a py.typed marker so the annotations will get installed and used.

[bradenmacdonald]

There are many different ways this could be implemented. Here is just one example, that provides the best typing experience across the board and could be fully backwards-compatible, but requires transitioning the receivers to split up data and metadata as separate args instead of combining all the data+metadata fields into a single kwargs (the combined kwargs makes typing way more difficult, but could continue to be provided as well for some time to not break anything).

_T = TypeVar("_T")

class OpenEdxPublicSignal(Signal, Generic[_T]):
    def send_event(self, *, data: _T, send_robust: bool = True, time=None) -> list: ...

@attrs.define(frozen=True)
class XBlockCreatedEventData:
    xblock_info: XBlockData

XBLOCK_CREATED: OpenEdxPublicSignal[XBlockCreatedEventData] = OpenEdxPublicSignal(
    event_type="org.openedx.content_authoring.xblock.created.v1",
    data_cls=XBlockCreatedEventData,  # replaces the dict
)

Sending:

XBLOCK_CREATED.send_event(
    data=XBlockCreatedEventData(xblock_info=xblock_data),  # Fully typed
    time=now,
)

Receiving:

def on_xblock_created(
    sender,
    data: XBlockCreatedEventData,  # fully typed
    metadata: EventsMetadata,      # always the same, no per-signal variation
    **kwargs,
): ...

[bmtcril]

I have an old PR for this that I can resurrect. I'd like to tackle it in 2 stages:

1- Add type hints without changing any logic / data structures except internal APIs to fix type problems
2- Breaking refactor if the team would like to go for that. I think it would be a pretty heavy lift as (I think?) it would especially impact downstream Kafka event bus cases and require some slightly complicated versioning on that side

[bmtcril]

Ah right, I ran into upstream dependencies (opaque-keys, ccx-keys, and edx-django-utils) not being annotated and was hoping to do them first but we can work around it for now.

[bradenmacdonald]

Cool, thanks @bmtcril ! At least opaque-keys is now typed - I did that one a couple of years ago.