Autobahn WebSocket Protocol - Improve typing

[bblommers]

Description

Adds typehints to autobahn/twisted/websocket.py and autobahn/websocket/protocol. I realize that's only a small section of the codebase, those just contain the classes that I use the most 🙂

Some style choices that I made:

• X | Y notation (instead of the Optional[X] that is used as well in this codebase)
• Lowercase dict[..] and tuple[..], as that is the preferred way for Python >= 3.10 (instead of typing.Dict[..] and typing.Tuple[..])
• Removed the :style.. from the docstrings, if the type is now available as a typehint, just because it seems superfluous to specify the type twice

Checklist

• I have referenced relevant issue numbers above
• I have performed a self-review of my code and it follows
  the style guidelines of this project
• I have added new or used existing tests that prove my fix
  is effective or that my feature works
• I have added necessary documentation (if appropriate) and
  updated the changelog
• I have added an AI assistance disclosure file (required!)
  in this PR

[bblommers]

With the changes in autobahn/wamp, this check now passes

[bblommers]

Minor typo to get the CI to pass

[oberstet]

thanks a lot for contributing!

in fact, this is funny/surprising, since adding/improving type hints is something I became interested in myself just recently, coming from a different angle (SLSA L4 / WASM).

this broader context and resulting "style guide" as related to type hints is now documented in #1839

I've added specific references to your PR, and I'd be very curious about your comments, remarks and general feedback!

please don't get this wrong, I am not asking for "full type hints everywhere" for this PR.

the GitHub issue is just for giving the "outer scope / aggregate issue" as an anchor - eg I noticed you did add an audit file to this PR already (very good, thanks a lot!), but that does not yet refer a GitHub issue - because there wasn't one (which is important for the audit file as this properly relates "issue to PR to CI/CD to merge-to-master" and allows developers and users to figure out how these related also retrospectively)

[bblommers]

Great minds think alike @oberstet!

I've pushed a new commit with some improvements, as pointed out in the guide:

1. Add from future import annotations to all modified files
2. Replace all Optional[X] with X | None
3. Remove unused typing imports (Optional, Union, Dict, Tuple)

Missing:

• Add missing parameter types (especially payload: bytes)
• Run ruff check --select ANN,UP and fix violations

There are still a ton of types missing, even in this small subsection - and I'm not familiar enough with the codebase/functionality to determine the correct types for them. That's why I left some as-is.

General remarks / feedback

As someone who went through the same process of 'cleaning' a codebase both in terms of style and typehints, I have some advice, if I can:

1. Tackle it piece by piece.
   a) ruff can be very useful, both to find improvements (ruff check) and sometimes to fix them automatically (ruff check --fix).
   b) At the same time - I found it a very useful to also apply these changes to one file/module at the time. Tackling everything is a great way to introduce new bugs/typos (speaking from experience 🙂 )
2. The style guide looks great! Very comprehensive and clear. However: automated checks will always be easier to follow for developers, so adding any ruff commands to just check-typing would be very helpful for contributors

Speaking of: running ruff check --select UP seems to be mostly f-strings violations, which could be fixed automatically using ruff check --fix. I would be happy to add that as part of this PR - but I would recommend running that against the entire codebase in a separate PR for that. It makes reviewing a lot easier!

[oberstet]

Thanks so much @bblommers — merging this now! 🎉

Really appreciated how quickly you aligned with the style guide after I filed #1839. The from __future__ import annotations addition and the Optional → X | None migration are exactly what we needed. Clean work.

On your feedback:

1. Piece by piece — 100% agree. That's the plan for [FEATURE] Constrain codebase to statically typed and region-based lifetimes Python subset #1839. Your PR sets a great pattern for what "typed subset" looks like in practice.
2. Adding ruff to just check-typing — great suggestion, I'll add ruff check --select ANN,UP to the recipe. Makes it much easier for contributors to validate locally before pushing.
3. f-strings cleanup in separate PR — yes please! If you're up for it, a focused ruff check --fix --select UP across the codebase would be very welcome. Keeping it separate makes review much easier, as you noted.

Remaining typing work (untyped payload params, more modules) is now tracked in #1839 — no pressure, but if you're interested in picking up more files, you'd be very welcome to. The high-priority ones are wamp/protocol.py and wamp/component.py.

Thanks again for the contribution and the thoughtful process feedback!