Comment or docstring?

[gvanrossum]

The current proposal has this in a docstring. Perhaps it would be better off in a comment? IDEs tend to read the source code, so they have access to comments as well as docstrings, and the README currently appears to make runtime behavior a non-goal.

[mristin]

Just my 2 cents: it makes sense to have these name-to-types integrated into the automatically generated documentation such as sphinx. As a user of a library, I'd be happy to be able to access that information.

[guettli]

@mristin I have never used automatically generated documentation. I am unsure. If the name2type mapping is in the docstring, then it is visible. This means your goal is reached without any work. This speaks for docstrings.

[guettli]

@gvanrossum do you have contact to PyCharm developers (I mean the people who develop PyCharm)? I am very interested in their feedback. Because that's where I would like to see the name2mapping in action.

[mristin]

@guettli exactly, if it's written in the docstring, it is automatically visible in the documentation.

It makes sense to use sphinx syntax in order to get nice formatting (:...: directives, e.g. see http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures)

[ksamuel]

Just my 2 cents: it makes sense to have these name-to-types integrated into the automatically generated documentation such as sphinx. As a user of a library, I'd be happy to be able to access that information

Yes, but having it in a comment doesn't prevent this. You can write a plugin to that extend. After all, there is a plugin for sphinx that ignore types in the docstring, and inject type from type annotations already.

I wish we allowed typing in the docstrings since the beginning, I really do. It would have made millions of code lines in the world using sphinx automatically typed hinted without work.

But this idea has been rejected unfortunately, and we can either use annotations, or type comments.

Now, if this idea ever gets implemented and use docstrings, we will end up a really weird place where all the types cannot be in a docstring, except for this particular feature that MUST be in a docstring.

For congruence, we need to put it in a comment.

[guettli]

@ksamuel sooner or later Python 2.x will die. If you use a modern Python 3.x, is it feasible to use type comments? Is there a case where annotations are not enough, and you need type comments?

[ksamuel]

Variable annotations are comment-only if you have less than Python3.6. You may also want to use annotations for something else (ex: the begins lib), and use comments for type hinting. At last, you may use type comments to avoid having executable code running just to add type hints. Before 3.7, we don't have delayed executation of type annotations, and so you pay the performance price. Also, think about the documentations, tutorials, repos, etc, that will feature the comments. It will be here for years to come anyway. E.G: let's say I have an open source project that is compatible with python 2 and 3. I write all my type hints in comments. Now I drop Python 2 support. I'm not going to rewrite all my comments. I will keep them. It's too much work, and doesn't add any value to my clients. Le 26/10/2018 à 11:47, Thomas Güttler a écrit :

…

@ksamuel <https://github.com/ksamuel> sooner or later Python 2.x will die. If you use a modern Python 3.x, is it feasible to use type comments? Is there a case where annotations are not enough, and you need type comments? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANivvoSwnlXN3XlVQet6CY-zElZx9MHks5uotolgaJpZM4X7Rsl>.

[dstanek]

I like the idea of using the docstring much better. A few years ago I created dstanek/typist to use type information from docstrings. It's worked out nicely since the information is usable in our generated docs too.

[ksamuel]

I do too. I'd love to type my hints in the docstrings. But Guido said no for type hints in docstrings (python/mypy#612 (comment) and python/mypy#1840 (comment)). Now either we have type hints in docstrings and put this new features in docstrings. Or we don't, and put the new feature in comments. Doing a bit of each is very much against the zen of Python. I'm all for changing the status quo, and allow type hints in docstrings. But it seems harder to convince the mypy team to implement this change (it's a way bigger debate, and a LOT of work) than to make the decision to use comments in a project that has yet to be created. Whichever solution you choose, please do not allow to have a mixed world of comments only one one side, and docstrings only on the other side. We have had several situations like this in Python (e.g: setup.cfg / setup.py / pytoml or __init__.py / namespace) and I have been witnessing people paying debts for years because of those. We need something clear. No guesses. No doubts. No if/else in the docs and tutorials.

[guettli]

@ksamuel why should I (or someone else) convince the mypy team?

... please do not allow to have a mixed world ...

Yes, me too. I try to avoid OR in docs and APIs. Every new comer is clueless and unsure again and again. I would like to avoid this.

[ksamuel]

Only if you want to use docstrings. If you use docstrings but don't change the status quo on type hints in doc strings, we will have a a mixed world, giving that mypy is the reference and most used implementation of type checking tooling.

[guettli]

@ksamuel about mypy: Up to now the list of name2type mapping goals is small: Better type-hints in IDEs. But maybe mypy support would be nice.

I the mypy developers what they think here: python/mypy#5841

[mristin]

@guettli I'd suggest name2type aims for both IDE and mypy support. As soon as you have to deal with a larger code base and a larger team/organization, I find it super useful when conventions can be enforced automatically.

I don't know if I'm leaning too much out of the window, but it might be interesting to go even beyond type checks: for example, you could use patterns for hungarian notation and enforce constraints on the type at verification time or at runtime (e.g., prefix p_.* could imply that the number is always positive).

I found the following blog post interesting: https://www.joelonsoftware.com/2005/05/11/making-wrong-code-look-wrong/
but always doubted that such an approach is viable without automatic enforcement.

[gvanrossum]

@gvanrossum do you have contact to PyCharm developers (I mean the people who develop PyCharm)? I am very interested in their feedback. Because that's where I would like to see the name2mapping in action.

Try @vlasovskikh

[vlasovskikh]

@guettli Personally I prefer comments, since they don't interfere with module documentation. From the implementation perspective, module docstrings are easier, since PyCharm already indexes them and you'll be able to access the docstrings from ancestor __init__.py files quickly. As for module-level comments, it is possible to add a custom indexer for these mappings. The type inference logic could be implemented as a plugin for PyCharm that adds a custom type provider to our type inference.

[guettli]

@vlasovskikh thank you for your feedback. By the way I updated the README and added an argument against name2type mapping. I would like to know what you think about this:

It is not needed since stats are enough. Example: If you code base contains a variable name "request" 100 times, and in 70 times the variable type is an instance of "django.http.HttpRequest" (detected by usual type-annotation), then it is redundant to specify this explicit in a file. The IDE (or code quality checking tool) could gather this information by looking at the stats.

[guettli]

Just for the records. I asked in the PyCharm issue tracker, but received no reply up to now:
https://youtrack.jetbrains.com/issue/PY-32490

[guettli]

I received feedback from PyCharm:

At the moment, we don't plan to support the proposal you've mentioned. It could be implemented as a third-party plugin for PyCharm

Source: https://youtrack.jetbrains.com/issue/PY-32490#focus=streamItem-27-3142017-0-0

Since my proposal won't reach my goal (integration in PyCharm) my motivation is gone.

Thank you all who participated in this idea and gave feedback.

I think it was useful to discuss this, even if it was not successful.

Have a nice time, enjoy live, au revoir.

I leave this open for now, and will close this in a month.