{"action":"created","issue":{"url":"https://api.github.com/repos/python/mypy/issues/612","repository_url":"https://api.github.com/repos/python/mypy","labels_url":"https://api.github.com/repos/python/mypy/issues/612/labels{/name}","comments_url":"https://api.github.com/repos/python/mypy/issues/612/comments","events_url":"https://api.github.com/repos/python/mypy/issues/612/events","html_url":"https://github.com/python/mypy/issues/612","id":63365780,"number":612,"title":"Should we support type annotations in docstrings for Python 2 code?","user":{"login":"JukkaL","id":1107911,"avatar_url":"https://avatars.githubusercontent.com/u/1107911?v=3","gravatar_id":"","url":"https://api.github.com/users/JukkaL","html_url":"https://github.com/JukkaL","followers_url":"https://api.github.com/users/JukkaL/followers","following_url":"https://api.github.com/users/JukkaL/following{/other_user}","gists_url":"https://api.github.com/users/JukkaL/gists{/gist_id}","starred_url":"https://api.github.com/users/JukkaL/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JukkaL/subscriptions","organizations_url":"https://api.github.com/users/JukkaL/orgs","repos_url":"https://api.github.com/users/JukkaL/repos","events_url":"https://api.github.com/users/JukkaL/events{/privacy}","received_events_url":"https://api.github.com/users/JukkaL/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/python/mypy/labels/needs%20discussion","name":"needs discussion","color":"bfdadc"},{"url":"https://api.github.com/repos/python/mypy/labels/postponed","name":"postponed","color":"bfd4f2"}],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":11,"created_at":"2015-03-21T05:48:58Z","updated_at":"2016-06-03T01:19:05Z","closed_at":"2016-06-03T01:19:05Z","body":"We could support an alternative, docstring-based syntax for types in programs that need to be Python 2 compatible. The idea is from http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html\r\n\r\nExample:\r\n\r\n```python\r\ndef first_name(name):\r\n    \"\"\"Return the first name from a name with both a first and a last name.\r\n\r\n    Args:\r\n      name (str): The full name, such as 'John Smith'.\r\n\r\n    Returns:\r\n      str: The first name.\r\n    \"\"\"\r\n    return name.split()[0]\r\n```\r\n\r\nMypy would threat this as equivalent to this:\r\n\r\n```python\r\ndef first_name(name: str) -> str:\r\n    return name.split()[0]\r\n```\r\n\r\nA bunch of details would have to be fleshed out before implementing this. I'm adding this issue to get feedback on whether people would consider this useful. I've started seeing code using the above convention (though with slightly ad-hoc types).\r\n\r\nNote that we can support `# type:` annotations as an alternative. They could be pretty useful for small, internal functions that may not have a docstring at all. The docstring syntax would be pretty verbose if used for every function. Example:\r\n\r\n```python\r\ndef first_name(name):  # type: (str) -> str\r\n    return name.split()[0]\r\n```\r\n\r\nMaybe we should extend the docstring syntax to have optional shorter forms:\r\n\r\n```python\r\ndef join_name(first_name, last_name):\r\n    \"\"\"Join first and last name into a full name.\r\n\r\n    Args: first_name (str), last_name (str)\r\n    Returns: str\r\n    \"\"\"\r\n    return first_name + ' ' + last_name\r\n```\r\n\r\nAnother shorter form:\r\n\r\n```python\r\ndef join_name(first_name, last_name):\r\n    \"\"\"Join first and last name into a full name.\r\n\r\n    Args: \r\n      first_name (str)\r\n      last_name (str)\r\n    Returns: str\r\n    \"\"\"\r\n    return first_name + ' ' + last_name\r\n```\r\n\r\nAnother alternative for Python 2 code is to use the mypy codec that supports Python 3 type annotations in Python 2 code by automatically stripping them away. This has a few problems:\r\n\r\n1. The codec generally needs to be activated before it can be used, which is a minor pain, especially for entry point / main module(s).\r\n2. Tools such as IDEs and linters may get confused by it (but they could potentially be used in Python 3 mode, if the code is also Python 3 compatible).\r\n3. It slows down bytecode compilation or program startup. However, if we'd implement it in C, it could be very fast for CPython. But what about PyPy, Jython etc.?"},"comment":{"url":"https://api.github.com/repos/python/mypy/issues/comments/223467302","html_url":"https://github.com/python/mypy/issues/612#issuecomment-223467302","issue_url":"https://api.github.com/repos/python/mypy/issues/612","id":223467302,"user":{"login":"gvanrossum","id":2894642,"avatar_url":"https://avatars.githubusercontent.com/u/2894642?v=3","gravatar_id":"","url":"https://api.github.com/users/gvanrossum","html_url":"https://github.com/gvanrossum","followers_url":"https://api.github.com/users/gvanrossum/followers","following_url":"https://api.github.com/users/gvanrossum/following{/other_user}","gists_url":"https://api.github.com/users/gvanrossum/gists{/gist_id}","starred_url":"https://api.github.com/users/gvanrossum/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gvanrossum/subscriptions","organizations_url":"https://api.github.com/users/gvanrossum/orgs","repos_url":"https://api.github.com/users/gvanrossum/repos","events_url":"https://api.github.com/users/gvanrossum/events{/privacy}","received_events_url":"https://api.github.com/users/gvanrossum/received_events","type":"User","site_admin":false},"created_at":"2016-06-03T01:19:05Z","updated_at":"2016-06-03T01:19:05Z","body":"Yeah, we're not going to do this.\r\n\r\n- Types in docstrings are usually not checked so are often incorrect.\r\n- The docstring syntax for types is unnecessarily verbose.\r\n- We don't want to support multiple syntaxes forever.\r\n- There doesn't even seem to be agreement on how to write types in docstrings."}}
{"actor":{"display_login":"gvanrossum"}}