add Python type hints #359
Conversation
| @@ -33,6 +33,29 @@ Building and/or using Python 2 is probably discouraged even more than, say, usin | |||
| * A popular way to learn Python is by doing it the hard way at http://learnpythonthehardway.org/ | |||
| * Using [`pylint`](https://www.pylint.org) and [`yapf`](https://github.com/google/yapf) while learning Python is an easy way to get familiar with best practices and commonly used coding styles | |||
|
|
|||
| ### Type hints | |||
There was a problem hiding this comment.
This section would fit better between "code style" and "testing". In the code style chapter various tools for static code analysis are presented, and type hints are typically also used for static code analysis.
| Other important libraries like Matplotlib have very complex functions that take in many possible types of arguments, leading to overly complex variable types. | ||
| Such huge types clutter your code tremendously, so they are not typically encouraged. |
There was a problem hiding this comment.
| Other important libraries like Matplotlib have very complex functions that take in many possible types of arguments, leading to overly complex variable types. | |
| Such huge types clutter your code tremendously, so they are not typically encouraged. |
I would leave this out. There is some discussion possible about the design choices of matplotlib and that is not the aim of our guide. How about saying that type hints are not practical if e.g. the researchers you are developing the code with are not comfortable with using them because they are too technical?
| @@ -338,3 +362,4 @@ We recommend `flask`. | |||
| * For run-time configuration via command-line options, the built-in [`argparse`](https://docs.python.org/library/argparse.html) module usually suffices. | |||
| * A more complete solution is [`ConfigArgParse`](https://github.com/bw2/ConfigArgParse). This (almost) drop-in replacement for `argparse` allows you to not only specify configuration options via command-line options, but also via (ini or yaml) configuration files and via environment variables. | |||
| * Other popular libraries are [`click`](https://click.palletsprojects.com) and [`fire`](https://google.github.io/python-fire/). | |||
| * [Typer](https://typer.tiangolo.com): make a CLI app by using type hints with runtime effects. Very low on boilerplate for simple cases, but also allows for more complex cases. Uses `click` internally. | |||
There was a problem hiding this comment.
| * [Typer](https://typer.tiangolo.com): make a CLI app by using type hints with runtime effects. Very low on boilerplate for simple cases, but also allows for more complex cases. Uses `click` internally. | |
| * [Typer](https://typer.tiangolo.com): make a command-line application by using type hints with runtime effects. Very low on boilerplate for simple cases, but also allows for more complex cases. Uses `click` internally. |
To keep the text easy to understand for less technical people
|
|
||
| We recommend using type hints, where possible and _practical_. | ||
| Type hints are still being actively developed; not everything one would like to be able to express in a compact way can yet be achieved. | ||
| This is why, for instance, NumPy arrays and ML library "tensor" types still (in 2024) have awkward type hinting. |
There was a problem hiding this comment.
Could you be more specific about what "ML library" you mean? And also write out the abbreviation, please
| See [this guide](https://realpython.com/python-type-checking/) to learn more about type hints. | ||
|
|
||
| Some tools to know about that make use of type hints: | ||
| - [Mypy](https://mypy.readthedocs.io/en/stable/index.html): tool that checks whether your code uses types correctly. |
There was a problem hiding this comment.
Make this a bit broader by mentioning (or linking to a page with) alternatives? e.g. https://www.infoworld.com/article/2260170/4-python-type-checkers-to-keep-your-code-clean.html
|
@stefsmeets We talked today about |
|
I think it makes sense, I find attrs to be much more approachable than pydantic. The attrs docs have a really nice section on comparing the different tools: https://www.attrs.org/en/stable/why.html |
|
Briefly browsing PROTEUS' use of attrs, it seems like a nice lightweight tool for value validation. I'm not sure how (or even if) Pydantic handles this, but certainly seems useful. I don't think it should go under this PR, though, it's a topic independent of type hints. |
|
Whoops, missed your comment @stefsmeets before posting mine just now. Agree, it looks nice and lightweight. Lets make a separate issue. |
Added a subsection on type hints, following the discussion in #310. Also added a few cool libraries, e.g. FastAPI that was mentioned by Bouwe in #54 and Typer from the same author.
Fixes #310.
Checklist
SIGNIFICANT changes / additions, e.g. new chapters
ALL contributions
python3 -m http.server 4000and confirmed they work correctly.docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.toml, at least for the files I changed.CITATION.cfffile.