Add Typing to baseio, baserawio, and exampleio

[zm711]

Replaces #1229 because that now has merge conflicts.

I know this has been discussed #1123. Sam is against, others are typically for. This is just a draft to think about (& correct or reject), but I think adding type hints to some places exposed to the user would be beneficial. By putting the hints into the base it propagates to all ios to minimize other typing needing to be added, although developers can override the typing in their specific io.

I know that neo has complicated inputs, but I think type hints work best to give a suggested appropriate input (And as a nod to Sam I didn't add type hints for the returns yet).

[pep8speaks]

Hello @zm711! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2023-12-09 15:32:30 UTC

[zm711]

I'll fix formatting after I know whether this is supported or not.

[JoeZiminski]

I would add my support to such a PR. Typing is fantastic for catching bugs, in general improving robustness. Since I started using type hints last year they have caught a lot of potential bugs and saved me a lot of trouble!

[samuelgarcia]

Having the role of the old dinosaur is not so easy in a group but I am trying my best to maintain my public character.

[zm711]

Having the role of the old dinosaur is not so easy in a group but I am trying my best to maintain my public character.

@samuelgarcia never change. Your example error messages here and in probeinterface are always the highlight of my proofreading. (to be clear I mean in a great way :) )

[alejoe91]

@zm711 this looks good to me!

@samuelgarcia can we merge?

[zm711]

Thanks @alejoe91. I have a feeling when there is typing in the PR title @samuelgarcia has a filter for his alerts to jeter dans la poubelle.

[samuelgarcia]

@zm711 it is even worst. typing PR are triggering in me a brain state nearby freezing.
I always need to turn off the computer for at least one hour to recover totally.

[apdavison]

I am in favour of this PR, but some changes are needed for the type hints to be compatible with Python 3.8 and 3.9.

[zm711]

I am in favour of this PR, but some changes are needed for the type hints to be compatible with Python 3.8 and 3.9.

I think I addressed all of this in comments. But just to overall explain for future reference

I have added:

from __future__ import annotations

to the three files with typing, which allows us to use type hints from 3.9 and 3.10 in 3.8, 3.9, and 3.10 to keep things clean. This means we can:

• use | instead of needing Literal, but if Literal is preferred I can switch to that.
• use built-in types even in 3.8 list instead of List, dict instead of Dict

EDIT: one tiny other note is that the testing suite is currently running pytest on 3.9 (for NeoIOTest) so if | was going to break the code we should've seen that during the testing.

[apdavison]

so if | was going to break the code we should've seen that during the testing.

yes, that confused me, but since you've explained about from __future__ import annotations it all makes sense!

There's one remaining point I'm not sure about (numpy.dtype), but otherwise this looks good.

[zm711]

Officially the better typing would be:

import numpy.typing as npt

my_function(x, dtype: npt.DTypeLike = 'int32')

This indicates that something can be coerced into a numpy dtype. I currently have the dtype listed as the dtype constructor which is the constructor that takes an input and attempts to convert it to a numpy.dtype. So @apdavison you are correct that the current type is not strictly correct. Would you like me to change or do you think people will understand despite the mention of the constructor rather than the typing. I think the issue we will run into is that some old versions of numpy won't have the numpy typing module so it would be harder to support.

https://numpy.org/devdocs/reference/typing.html

[apdavison]

I think the issue we will run into is that some old versions of numpy won't have the numpy typing module so it would be harder to support

That's a good point. For now we're not doing strict type checking with mypy or whatever, so I agree let's leave it as is for now.

[zm711]

Also just for reference I checked and typing was added in 1.20 (but I think the DtypeLike was added in 1.21) so we would need to wait until our minimum numpy is that to be safe.