refactor: add type annotations and improve type safety

[KarimAziev]

This PR introduces significant improvements to type hinting as part of resolving issue #1192.

• The most important change was adding overloads to dispatch_functions, ensuring that it now correctly propagates return types.
• Refactored the Job class into a generic type.
• Added type annotations to core methods such as capture_array, capture_image, and create_video_configuration.
• Enhanced runtime safety by adding more assert statements.
• Fixed inconsistencies in the return types of private helper functions.
• Improved the pyright configuration: disabled the reportUnknownMemberType warning, resulting in fewer but more meaningful warnings being displayed.

While the PR mainly focuses on typing improvements with no logical changes, there's a minor fix in Job.cancel():

Before:

self._future.set_exception(CancelledError)

Now:

self._future.set_exception(CancelledError())

This change ensures that set_exception is always given an instance of CancelledError, aligning with concurrent.futures.Future's expectations. The previous version would have raised a TypeError: exceptions must be derived from BaseException when raised if it were ever encountered at runtime. This fix does not alter any behavior but ensures correctness.

P.S. I didn't plan for this to be so extensive, but... it turned into a rabbit hole.

[davidplowman]

Thanks for this PR. Looks like I need to install a newer version of typing-extensions than the Bookworm default. I'll do that and then re-open this so that it runs again.

[davidplowman]

That looks good, there's just one snag I've run into related to the line

from typing_extensions import Buffer

Because we ship Picamera2 installed in our regular OS images, it means that I can't use a version of typing_extensions that isn't in our Bookworm apt repo. The version currently there is 4.4.0. But for this line to work I think I need at least 4.8.0.

So the solutions are probably:

• Either update the Bookworm apt version to 4.8.0 (or newer)
• Or remove this line and the usage of the Buffer type later in the file.

I'll see whether it looks possible to update the Bookworm repo (does 4.8.0 sound OK to you?) and then post back.

Thanks again!

[KarimAziev]

Thanks for the feedback! I've removed it for now, so an updated version of typing-extensions is no longer needed.