Refactor static typing of the picamera2 module

[pantheraleo-7]

1. add comprehensive static typing of return types
2. add overloads for methods using dispatch_functions (as they can return two kind of types)
3. resolve the remaining type checker errors

follow-up of #1179

Before:

After:

(committed this in December, fell ill, forgot to put in a PR since haha)

looks like there will be merge conflicts with #1205, so creating a draft PR for now rebased onto HEAD.

[pantheraleo-7]

@davidplowman it'll be easier to review commit by commit

[davidplowman]

Hi again, great - thanks for doing more on this. I can look at this next week (bit late in the day right now!), let me know how you'd like to proceed. Is it worth running the CI tests already?

[pantheraleo-7]

Is it worth running the CI tests already?

yes

I can look at this next week (bit late in the day right now!)

no issues

[pantheraleo-7]

you can run tests now, I used 3.12 syntax earlier 😅

it should be now 3.9+ compatible

[pantheraleo-7]

Before:

After:

Now, we get Image or Job[Image] based on the arguments passed.

[davidplowman]

Hi, I think I've enabled the checks to run automatically for you now, hopefully that will make things a bit easier.

[davidplowman]

Hi, and thanks for doing all this. Is there anything more you think we might be able to turn on in the CI tests? Having got these improvements, I'm keen for us to hang on to them and not let in commits that might take things backwards again.

[pantheraleo-7]

as of this PR, I've eliminated* all type checker errors that were reported by pyright for the picamera2 and job modules. I see pyright workflow has been added in #1195, but it is not enforced. The rest of the codebase has many type errors, so what we can do is enforce them on just these two modules, for now, and then gradually add others as they get error-free in the future.

as for protecting the overloads and better return types that I've added, I don't see an elegant way to do this, but to add a test file and statically type it with the desired/expected type, and run pyright on it?

something like:
img: Image.Image = cam.capture_image()

we expect the return type to be a PIL image so we type it as such. if in future, somebody changes the overloads or the return type of capture_image to return something other than a PIL image, pyright would flag it. we can then decide if that change is an improvement or a regression (in this example, it's a regression obviously).

*could you check locally and confirm. I'm on a mac so I don't have access to libcamera.

[pantheraleo-7]

functions passed to Job must return (done, result). is there any restriction (runtime or just as a matter of policy) that result must be None when done is False?

as far as I'm reading the codebase, the result gets discarded when done is False? so it doesn't matter what type it is..

[davidplowman]

functions passed to Job must return (done, result). is there any restriction (runtime or just as a matter of policy) that result must be None when done is False?

as far as I'm reading the codebase, the result gets discarded when done is False? so it doesn't matter what type it is..

Hi, sorry I forgot to answer that. Yes, I think you're right, the result doesn't mean anything when done is False, so it can be whatever we want.

Anyway, I've merged this one now, thanks for all the work you've put into this!