add function and variable annotations. #637
Replies: 5 comments 3 replies
-
Thanks so much for this post. I really love these discussions. Let's go step-by-step:
Type specifications in docstrings are important mostly for users of the functions (that is, programmers importing these functions for their applications). Indeed, we have not revisited all functions to homogenize type specifications. This can be improved. Some functions work with both
You are right. In these cases, we should update the docstring to
In my personal opinion, the first for sure. This is a very deep conversation, a topic full of controversy, and many things need to be explained to make that decision. Python is a dynamic-typed language. Therefore, it relies entirely on polymorphism. That's the power of Python. And that's a conscient decision. You gain tons of flexibility while developing, but you lose speed because the compiler needs to identify the types line by line. Python was designed that way. On the other hand, you have to test your Python programs entirely on runtime. There are no compiler checks here. That's why our test cases are so heavy (and could be much more). That's why libraries like Hypothesis were developed, and test-driven development in Python is so necessary. You can also do program-by-contract in Python. I have worked that way. The PROS: you may identify bugs faster. CONS: yet another layer to maintain. Most libraries out there addressing P-b-C are unfunctionally slow. The best is to use a decorator with assert statements. It's the least overhead. Below is an example: def type_check(ordered_types, named_types):
def decorator(func):
def wrapper(*args, **kwargs):
for arg, type_ in zip(args, ordered_types):
assert isinstance(arg, type_)
for arg, type_ in zip(kwargs.values(), named_types):
assert isinstance(arg, type_)
return func(*args, **kwargs)
return wrapper
return decorator
@type_check((str, float), (int, ))
def func1(a, b, *, c=0): # the '*' is mandatory
print(a, b, c)
func1('a', 1.0, c=3)
func1('a', 1.0, c='a') # assertion error Surely it can be expanded. You can also use
I have no idea. Let's discuss the use of type hints instead. First, consider that haddock3 is a fast-developing code. Therefore, "enforcing" types at this moment might be adding unnecessary stress on the developers. Think about the
When I was the lead developer of haddock3, I usually opposed adding dependencies to the project. Sometimes I was too strict, but I continue having the same opinion. For a project like HADDOCK3, adding these dependencies to the run time adds a burden. But if the dependency is on the developer environment, that's okay (see our
If it is a dependency, I would say yes.
I always prefer to use In conclusion: What I wrote here is mostly my personal view on using type hints. I don't see any benefit on type-hints that docstrings won't provide. Now, should you contribute with type-hints to haddock3? Currently, I am no longer the lead developer of haddock3. I keep contributing to the project actively as an external collaborator, though. Implementing type-hints adds another layer of maintenance, which is not required for the science being developed or for the correct behavior of the software. I think it depends a lot on who is maintaining the software and the time available. However, I would appreciate it so much if you could contribute to the correct documentation of type specifications or improve polymorphism behavior wherever it is beneficial. That's my opinion. The idea of type-hints is not totally bad. But I think hinters should parse information from well-established docstring formats, like the numpy-doc, instead of requiring yet another layer of maintenance. My comments here were very bold. This topic is full of controversy. I wrote here my personal opinion. Cheers, |
Beta Was this translation helpful? Give feedback.
-
This point of view is apropos. I'd like to push a request of type-annotation-added version anyway,just as another flavor.Maybe I can find some bugs by type checks too. |
Beta Was this translation helpful? Give feedback.
-
I found this discussion by accident. Although I'm not really connected to this project, maybe I can share some experiences you might find interesting. 😊 I'm the maintainer of python-semver and I had the same considerations. This is what I learned and observed:
There are certainly pros and cons. Everybody is free to decide if this is worth the effort. I don't have any insights for this project, so I can't give any recommendations for or against it. For a more elaborate analysis, see https://realpython.com/lessons/pros-and-cons-type-hints/. From my own experiences working with maintaining python-semver, I solved the type hints vs. docstring issue with this approach:
Here is the example how this looks: https://python-semver.readthedocs.io/en/latest/api.html#module-semver.version For my project it worked out and the additional effort was and is still manageable. The types are not only checked, but also documented. I like this approach. 😉 For others, the situation might be different. Thanks for reading. |
Beta Was this translation helpful? Give feedback.
-
I think this is a great suggestion.Auto-generated documents including type-hints can make the api references more explict for programmers. |
Beta Was this translation helpful? Give feedback.
-
Hi @tomschr Very nice reply. You placed the stake right in the middle 😉. Indeed, both tendencies have their reasons, and I like how you approached type hints in your project. I did not know about the existence of Very nice discussion. Thanks to both of you 👏 |
Beta Was this translation helpful? Give feedback.
-
Hello there!
I have added some tentative function annotations into haddock's python code for better type-hints and auto-completion supports from IDEs.
Before I continue to check them carefully,I'd like to seek your opinions on some questions:
Many functions have type specifications in their doc-strings.Their type specifications may be narrow.
For example,most functions' implementations accept
str
andPath
both but they are justPath
in some doc-strings;some functions accept
Iterator
orSequence
but they arelist
in doc-strings.Which one is better?Annotating functions in a minimum generic way to be compatible with code implementations, or same as the doc-string in a "Programming by Contract" way?
I add some Literal types and Typedicts definations to narrow possibities.Some are unlikely to change in the short term but others may be too hardcode,say:
As there are many funtions converting yaml,toml files or accepting **keywords,narrowing their parameters help type-hints in current codes,but maybe too strict.I perfer
Any
type in this case.What's your suggestions?There are some useful types in
typing
module of python 3.10+,saySelf
,ParamSpec
,andConcatenate
.Python use
typing_extensions
module to support backport.I'd like to import typing_extensions but it's not belong to python standard libriary.Is it neccesory to add
typing_extensions
into requirements?Not related to this topic,but I found that there are many statements are:
I prefer
for key in d
andlist(d)
because they are conciser.d.keys()
is more explict.Are there any other benefits I don't know?Beta Was this translation helpful? Give feedback.
All reactions