search

acquire-project / acquire-python

Acquire: a multi-camera video streaming software focusing on microscopy
Apache License 2.0
18 stars 9 forks source link

export names in __init__.pyi #171

Closed tlambert03 closed 8 months ago

tlambert03 commented 8 months ago

without explicitly exporting names in __init__.pyi, type checkers like mypy won't follow all the names and you won't get autocompletion and code highlighting. I know it's annoying to have to manually do this (and perhaps you will want to automate it if you're autogenerating your type stubs) ... but adding __all__ is important one way or the other

before this PR:

Screenshot 2024-03-04 at 7 27 06 PM Screenshot 2024-03-04 at 7 30 54 PM

after this PR:

Screenshot 2024-03-04 at 7 30 24 PM
tlambert03 commented 8 months ago

ooof.. looks like stubtest wants __all__ to be in __init__.py as well as __init__.pyi, making it even more annoying. so I added it here

tlambert03 commented 8 months ago

this actually goes much deeper. As I follow through the docs, I realize that a lot of the star imports from .acquire import * are indeed intended to be used publicly, so you get this sort of thing:

Screenshot 2024-03-04 at 7 48 24 PM

I don't want to sweep in and make any assumptions about the typing strategies here. @nclack, @aliddell, is this something you guys have thoughts on? I know it's annoying to keep static stubs up to date with native code, and it can make for a lot of duplicated stuff without having scripts to autogenerate and test them. is it something you already know about and have opinions on?

nclack commented 8 months ago

First, we should add type-checking to our examples!

Second, typing this stuff out made me think of a fix! Does #173 work for you @tlambert03?

Anyway, for posterity, here's some answers to questions:

I'm hoping that one day, we won't have to maintain the stubs by hand, but for now, it has to be manual. It's alright as long as we can catch it when it's wrong!

The problem looks to be with re-exporting the types from acquire.pyi. This typechecks (note the acquire.acquire parts):

import acquire

runtime = acquire.acquire.Runtime()
dm = runtime.device_manager()

for device in dm.devices():
    print(device)

props = runtime.get_configuration()
props.video[0].camera.identifier=dm.select(acquire.acquire.DeviceKind.Camera)

The stuff in __init__.py shouldn't really be part of the public API; it's all demo/example code. What we really want is the stuff in acquire.pyi.

tlambert03 commented 8 months ago

Does https://github.com/acquire-project/acquire-python/pull/173 work for you @tlambert03?

yeppers