Adding type annotations to Python API (an offer, not a request!)

Hi @mwouts ! I hope all is well 😄

I was using jupytext’s Python API for the first time in a long time and was wishing that there were type annotations to provide me with better auto-completion and guidance. I would be happy to add these if you are interested!

Would you be interested in me adding type annotations to these functions? It would roughly look like:

• Adding annotations to the objects exposed via jupytext.__all__
• Adding two CI jobs for running mypy and pyright, respectively, on example code to ensure that the annotations correct and sufficiently narrow
• The addition of an empty py.typed file within the jupytext/ dir, included as package data for jupytext. This would be in accordance with PEP 561 for distributing type information for Python packages.

This would likely add typing_extensions as an explicit dependency, so that I can include Literal types to document the valid fmt options. typing_extensions itself is already quite ubiquitous (it is practically part of std-lib, but with more frequent updates), so this would likely have a negligible impact on users.

Some benefits are that users will:

• Have enhanced auto-complete information when working with the Python package, both when specifying inputs to jupytext functions and when working with outputs
• In most IDEs, they will see “red squiggles” in real time when they have made a mistake when working with functions (e.g. perhaps they used write instead of writes)

[mwouts]

Thanks @rsokl for the detailed information. I see that typing_extensions is already a dependency of markdown-it-py, which is itself a dependency of jupytext, so indeed please use it and go ahead! Thanks!

[rsokl]

I spent some time with this and realized that some of the critical arguments exposed via the API, such as fmt, are far more complex than I had expected (e.g., I didn’t realize that users could pass dictionaries for fmt[^1]). I have concerns that this effort will become much more expansive than I had initially advertised, and that it would require buy-in from developers (i.e., they would need to update annoations as new features are added to jupytext).

This is all doable, but I think it would amount to a much more significant effort and it would almost certainly entail refactors of some of jupytext’s internals… given that jupytext has been carrying along just fine without these, I think it isn’t worth it.

Sorry for the noise here!

[^1]: For example… python class JupytextFormat(TypedDict): extension: Literal[ ".auto" ".ipynb", ".md", ".markdown", ".Rmd", ".py", ".coco", ".R", ".r", ".jl", ".cpp", ".ss", ".clj", ".scm", ".sh", ".ps1", ".q", ".m", ".wolfram", ".pro", ".js", ".ts", ".scala", ".rs", ".robot", ".resource", ".cs", ".fsx", ".fs", ".sos", ".java", ".groovy", ".sage", ".ml", ".hs", ".tcl", ".mac", ".gp", ".qmd", ".myst", ".mystnb", ".mnb", ] format_name: NotRequired[ Literal[ "markdown", "rmarkdown", "light", "nomarker", "light", "percent", "hydrogen", "spin", "sphinx", "pandoc", "quarto", "myst", ] ] suffix: NotRequired[str] prefix: NotRequired[str]