Type annotation considerations

@falexwolf wrote:

Wow, this looks great! One remark for future PRs: We’re migrating to a new documentation style using type annotations

I’m still not convinced that we should use type annotations for Scanpy toplevel functions. People use Scanpy in Jupyter Lab and notebooks and not in Pycharm. Hence, there is no gain in the annotations, by contrast, the function annotations simply look super complicated and it’s no longer feasible to grasp at first sight what’s going on. This also regards the output of the help in Jupyter Lab and Notebooks.

So, while I think that for AnnData and everything in the background, type annotations may make sense for a few developers (not for me, as I’m doing everything on remote servers using emacs), it doesn’t make sense for the Scanpy user.

Also, all the other big packages I work with all the time simply don’t have it (numpy, seaborn, pandas, tensorflow) and it makes it harder and lengthier for contributors to contribute if they need to go through it.

Finally, I’m still not happy about how the automatically generated docs from the type annotation look: which is from Clearly, the automatically generated line with Union[...] is just way too complicated for a human to make sense of. The mix of auto-generated types in the docs and the manual annotations also looks inhomogeneous.

So, please let’s stay away from having more type annotations and corresponding docstrings at this stage and let’s simply continue imitating what all the major packages are doing.

Also: regarding your comment about the use of ‘``’ vs. ‘' in the docs: again, I think it leads to an inhomogeneous appearance to have *two* types of markup for code-related things. I agree that the read-the-docs italicized default style for '’ might be supoptimal, and I’ll work on that if there is some time. But in general, I think there should be essentially one markup for code, as it’s done in the tensorflow docs and a couple of other examples.

Happy to also discuss offline, @flying-sheep 😉.

[flying-sheep]

sure! in short: alex said he didn’t like the switch to type annotations at all, citing a few gripes.

i went on to fix them at various places (fixes are now in) and argued against a few others. i convinced alex that we should (slowly and carefully) adapt type annotations.

the only thing that was missing is a consensus on how to best pretty-print typing.Union, because alex was not a fan of the name and clumsiness. I preferred a, b, or c, he just a, b, c. i explained why a, b, c is a bad convention, but alex insisted to go with it because (sadly) everyone is doing it.

from there on we went deeper into algebraic types and so on. without need really, as we already decided on what to do.

[flying-sheep]

Btw: IPython 7.2 is live and contains my signature rendering prettificattion… except that I made a mistake and it renders wrong. Anyway, I fix that in ipython/ipython#11525 and things should be pretty in IPython 7.2.1: