Provide typing

[tmoulignier]

Hello,

Is it possible to provide typing in classes properties and functions? for example:

def get( idstr):
becomes:

from .registry.ig import ig
def get( idstr:str ) -> ig:

That way, people using IDE can crawl from a function to another, and have auto-completion working.

The documentation also does not display properly in markdown (in VScode at least) as we would require two line break (or add an \n at the end of the line).

Thanks

[chmarti1]

Thanks for the heads-up. It's helpful to see issues people are having in their favorite IDEs. I'm going to flag this as a future feature, but it will probably be a very long time before it receives attention. There are two reasons for this:

1. I wrote the PYroMat core package about 10 years ago in Python 2. It is stable, heavily tested, and the effort required to rewrite the functional interface to track with IDE trends is difficult to justify.
2. Python's in-line help is not really intended to comply with markdown - it is intended to display correctly on a terminal PEP 257.

Spoiler: I don't use VS, so this is valuable news to me.

I think there's a really valuable insight here. We should really prioritize experimenting with the PYroMat interface in lots of different development environments to see how the UI holds up. Thanks for your comment!

[tmoulignier]

Technically, any IDE with auto-completion will benefit from it. The typing of functions is only intended for this purpose and doesn't impact the code, so it should be transparent to your code performance/results, see the note here:
https://docs.python.org/3/library/typing.html

But good to see you might look into it, it might serve your module ergonomy

[chmarti1]

You're definitely right that one of PYroMat's design intents is to be convenient from the command line. I'll definitely look at what it would take to do. Re-reading my comment before, I realize I should be more clear... because PYroMat is inherently type flexible (accepting floats, nested lists, and numpy.ndarray), the typing system will require thought to make sure it is done well.

[jranalli]

Possible point for future conversation, this may couple with improving the efficiency of the published docs process. I recently used sphinx for the first time for one of my other projects and it can do some heavy lifting on generating an API reference built from the docstrings, which can very easily be hosted on readthedocs. For a better example than the one I built, see here. You can build jupyter/ipynb files into HTML examples and all kinds of cool stuff.

@chmarti1 I don't think it would be a lot of effort to port the LaTeX user guide to the ReStructuredText format that sphinx uses and produce really nice pages out of it. If I have a chance, I will see what building the bare bones version out of existing PyroMat docstrings looks like and you could consider whether you'd like to consider at least for a direct API reference.

[tmoulignier]

You're definitely right that one of PYroMat's design intents is to be convenient from the command line. I'll definitely look at what it would take to do. Re-reading my comment before, I realize I should be more clear... because PYroMat is inherently type flexible (accepting floats, nested lists, and numpy.ndarray), the typing system will require thought to make sure it is done well.

For multiple typing, you may want to look into this: https://docs.python.org/3/library/typing.html#typing.Union

note it is a bit python version dependant, i don't think it will work on python 2 or even early python 3