# typeright: Generate Python Type Annotations
Insert PEP 484 type annotations into your python source code.
## Options
typeright currently supports 4 approaches (aka "fixers") for inserting
annotations, listed below.
Multiple fixers can be used in tandem: if an annotation exists, or is
newly added by a previous fixer, all subsequent fixers will skip the location.
The one exception to this is the docstring fixer, which will overwrite existing
annotations if they do not agree with the types found in the docstrings, if any.
In other words, when enabled, the docstrings are considered the source of truth for types.
The fixers are listed below in the order that they are called.
### Read types from a json file
```
json file options:
Read type info from a json file
--type-info FILE JSON input file
--max-line-drift N Maximum allowed line drift when inserting annotation (can be useful for custom codecs)
--uses-signature JSON input uses a signature format
-s, --only-simple Only annotate functions with trivial types
```
If you have a tool that is able to generate type information, you can output
it in a format compatible with typeright and it will insert them as annotations.
The most common case for this would be if you're using
[PyAnnotate](https://github.com/dropbox/pyannotate) to inspect types at
runtime (this project is itself a fork of PyAnnotate, focused solely on annotation
generation). Another scenario might be generating type info based on doxygen
xml files for a C extension, and adding these to stubs created by mypy's `stubgen`
tool.
### Generate types from a command
```
command options:
Generate type info by calling an external program
--command COMMAND, -c COMMAND
Command to generate JSON info for a call site
```
With this option, you can use the mypy daemon, `dmypy`, to generate annotations.
This tool will analyze your code to determine likely types for a function
based on the types of objects passed to it throughout your code.
To use this, first start the mypy daemon:
```
dmypy run
```
Next, invoke `typeright` and pass it the command to run:
```
typeright --command='dmypy suggest --json {filename}:{lineno}' path/
```
It will run the given command on any function in `path/` that does not have annotations.
I prefer to also pass `--no-any` to ensure high quality suggestions only.
### Convert types from docstrings
```
docstring options:
Generate type info by parsing docstrings
--doc-format {auto,google,numpy,off,rest}
Specify the docstring convention used within files to be converted ('auto' automatically determines the format by inspecting each docstring but it is faster and more reliable to specify this explicitly)
--doc-default-return-type TYPE
Default type to use for undocumented return values (defaults to 'Any'
```
Maintaining types in docstrings can be desirable for a few reasons:
- Your project has existing docstrings with types that are already mostly correct
- You find it easier to maintain and comprehend types specified alongside the
description of an argument
typeright can parse the three major docstring conventions to find type info: [numpy](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy), [google](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and [restructuredText](https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html#template-py-source-file)
Regardless of the docstring convention you choose, the types declared within your
docstrings should following the guidelines in [PEP 484](https://www.python.org/dev/peps/pep-0484/),
especially use of the [`typing`](https://docs.python.org/3/library/typing.html)
module, where necessary.
### Set all types to Any
One approach to typing an exiting project is to start by blanketing your code
with types, so that you can enable `mypy --disallow-untyped-defs`
straight out of the gate. This gets the boilerplate out of the way, and
"encourages" developers to add types to all new modules.
```
any options:
-a, --auto-any Annotate everything with 'Any'
```
### Output format options
There are options to control how to generate the type annotations:
```
output format options:
--annotation-style {auto,py2,py3}
Choose annotation style, py2 for Python 2 with comments, py3 for Python 3 with annotation syntax. The default will be determined by the version of the current python interpreter
--py2-comment-style {auto,multi,single}
Choose comment style, multi adds a comment per argument, single produces one type comment for all arguments, and auto chooses between the two styles based on the number of arguments and length of comments
```
### Other options
```
other options:
-p, --print-function Assume print is a function
-w, --write Write output files
-j N, --processes N Use N parallel processes (default no parallelism)
-v, --verbose More verbose output
-q, --quiet Don't show diffs
-o OUTPUT_DIR, --output-dir OUTPUT_DIR
Put output files in this directory instead of overwriting the input files
-W, --write-unchanged-files
Also write files even if no changes were required (useful with --output-dir); implies -w.
```
## Configuration
typeright will read defaults from a configuration file named `typeright.ini`,
or `setup.cfg` in the current directory.
For example:
```ini
[typeright]
files = typeright
command = dmypy suggest --json --no-any {filename}:{lineno}
docstring_format = numpy
write = true
```
## Installation
This should work for Python 2.7 as well as for Python 3.6 and higher.
```
pip install typeright
```
## Using as a pre-commit hook
We use [pre-commit](https://pre-commit.com/) to fixup code prior to committing
or pushing.
To set it up, `cd` to this repo and run:
```
pip install pre-commit
pre-commit install
```
To manually run pre-commit on staged files:
```
pre-commit run
```
To manually run pre-commit on all files:
```
pre-commit run -a
```
## Testing
To run the unit tests, use pytest:
```
pytest
```
## Acknowledgments
This project was forked from PyAnnotate, after some encouragement from
Guido van Rossum, because PyAnnotate is no longer being actively maintained.
Here are the original acknowledgments:
- Tony Grue
- Sergei Vorobev
- Jukka Lehtosalo
- Guido van Rossum
## Licence etc.
1. License: Apache 2.0.
2. Copyright attribution: Copyright (c) 2017 Dropbox, Inc, and Chad Dombrova 2020.
Raw data
{
"_id": null,
"home_page": "https://github.com/chadrik/typeright",
"name": "typeright",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"maintainer_email": "",
"keywords": "pep484,typing,annotations,mypy",
"author": "Chad Dombrova",
"author_email": "chadrik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/91/db/ddb0c324cbd4e1ff20590a8a8132e7b4aefa07595477062de84c5a7ae3b6/typeright-0.1.0.tar.gz",
"platform": null,
"description": "# typeright: Generate Python Type Annotations\n\nInsert PEP 484 type annotations into your python source code.\n\n## Options\n\ntyperight currently supports 4 approaches (aka \"fixers\") for inserting\nannotations, listed below.\n\nMultiple fixers can be used in tandem: if an annotation exists, or is\nnewly added by a previous fixer, all subsequent fixers will skip the location.\nThe one exception to this is the docstring fixer, which will overwrite existing\nannotations if they do not agree with the types found in the docstrings, if any.\nIn other words, when enabled, the docstrings are considered the source of truth for types.\n\nThe fixers are listed below in the order that they are called.\n\n### Read types from a json file\n\n```\njson file options:\n Read type info from a json file\n\n --type-info FILE JSON input file\n --max-line-drift N Maximum allowed line drift when inserting annotation (can be useful for custom codecs)\n --uses-signature JSON input uses a signature format\n -s, --only-simple Only annotate functions with trivial types\n```\n\nIf you have a tool that is able to generate type information, you can output\nit in a format compatible with typeright and it will insert them as annotations.\nThe most common case for this would be if you're using\n[PyAnnotate](https://github.com/dropbox/pyannotate) to inspect types at\nruntime (this project is itself a fork of PyAnnotate, focused solely on annotation\ngeneration). Another scenario might be generating type info based on doxygen\nxml files for a C extension, and adding these to stubs created by mypy's `stubgen`\ntool.\n\n### Generate types from a command\n\n```\ncommand options:\n Generate type info by calling an external program\n\n --command COMMAND, -c COMMAND\n Command to generate JSON info for a call site\n\n```\n\nWith this option, you can use the mypy daemon, `dmypy`, to generate annotations.\nThis tool will analyze your code to determine likely types for a function\nbased on the types of objects passed to it throughout your code.\n\nTo use this, first start the mypy daemon:\n\n```\ndmypy run\n```\n\nNext, invoke `typeright` and pass it the command to run:\n\n```\ntyperight --command='dmypy suggest --json {filename}:{lineno}' path/\n```\n\nIt will run the given command on any function in `path/` that does not have annotations.\nI prefer to also pass `--no-any` to ensure high quality suggestions only.\n\n### Convert types from docstrings\n\n```\ndocstring options:\n Generate type info by parsing docstrings\n\n --doc-format {auto,google,numpy,off,rest}\n Specify the docstring convention used within files to be converted ('auto' automatically determines the format by inspecting each docstring but it is faster and more reliable to specify this explicitly)\n --doc-default-return-type TYPE\n Default type to use for undocumented return values (defaults to 'Any'\n```\n\nMaintaining types in docstrings can be desirable for a few reasons:\n\n- Your project has existing docstrings with types that are already mostly correct\n- You find it easier to maintain and comprehend types specified alongside the\n description of an argument\n\ntyperight can parse the three major docstring conventions to find type info: [numpy](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy), [google](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and [restructuredText](https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html#template-py-source-file)\n\nRegardless of the docstring convention you choose, the types declared within your\ndocstrings should following the guidelines in [PEP 484](https://www.python.org/dev/peps/pep-0484/),\nespecially use of the [`typing`](https://docs.python.org/3/library/typing.html)\nmodule, where necessary.\n\n### Set all types to Any\n\nOne approach to typing an exiting project is to start by blanketing your code\nwith types, so that you can enable `mypy --disallow-untyped-defs`\nstraight out of the gate. This gets the boilerplate out of the way, and\n\"encourages\" developers to add types to all new modules.\n\n```\nany options:\n -a, --auto-any Annotate everything with 'Any'\n```\n\n### Output format options\n\nThere are options to control how to generate the type annotations:\n\n```\noutput format options:\n --annotation-style {auto,py2,py3}\n Choose annotation style, py2 for Python 2 with comments, py3 for Python 3 with annotation syntax. The default will be determined by the version of the current python interpreter\n --py2-comment-style {auto,multi,single}\n Choose comment style, multi adds a comment per argument, single produces one type comment for all arguments, and auto chooses between the two styles based on the number of arguments and length of comments\n```\n\n### Other options\n\n```\nother options:\n -p, --print-function Assume print is a function\n -w, --write Write output files\n -j N, --processes N Use N parallel processes (default no parallelism)\n -v, --verbose More verbose output\n -q, --quiet Don't show diffs\n -o OUTPUT_DIR, --output-dir OUTPUT_DIR\n Put output files in this directory instead of overwriting the input files\n -W, --write-unchanged-files\n Also write files even if no changes were required (useful with --output-dir); implies -w.\n```\n\n## Configuration\n\ntyperight will read defaults from a configuration file named `typeright.ini`,\nor `setup.cfg` in the current directory.\n\nFor example:\n\n```ini\n[typeright]\nfiles = typeright\n\ncommand = dmypy suggest --json --no-any {filename}:{lineno}\ndocstring_format = numpy\nwrite = true\n```\n\n## Installation\n\nThis should work for Python 2.7 as well as for Python 3.6 and higher.\n\n```\npip install typeright\n```\n\n## Using as a pre-commit hook\n\nWe use [pre-commit](https://pre-commit.com/) to fixup code prior to committing\nor pushing.\n\nTo set it up, `cd` to this repo and run:\n```\npip install pre-commit\npre-commit install\n```\n\nTo manually run pre-commit on staged files:\n\n```\npre-commit run\n```\n\nTo manually run pre-commit on all files:\n```\npre-commit run -a\n```\n\n## Testing\n\nTo run the unit tests, use pytest:\n\n```\npytest\n```\n\n## Acknowledgments\n\nThis project was forked from PyAnnotate, after some encouragement from\nGuido van Rossum, because PyAnnotate is no longer being actively maintained.\n\nHere are the original acknowledgments:\n\n- Tony Grue\n- Sergei Vorobev\n- Jukka Lehtosalo\n- Guido van Rossum\n\n## Licence etc.\n\n1. License: Apache 2.0.\n2. Copyright attribution: Copyright (c) 2017 Dropbox, Inc, and Chad Dombrova 2020.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Add type annotations to your source code",
"version": "0.1.0",
"split_keywords": [
"pep484",
"typing",
"annotations",
"mypy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c000f7ddca22487aba291632e7bde8373b5b044b923c16fc6fe0bc6217a28ea",
"md5": "964abcd0afcf7bae125a413385749e39",
"sha256": "84af073c4b6d4081ca5eb48c05f8e8e59d7747ad6224d85d6ac5527a9f1c1102"
},
"downloads": -1,
"filename": "typeright-0.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "964abcd0afcf7bae125a413385749e39",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"size": 69886,
"upload_time": "2023-04-03T22:15:55",
"upload_time_iso_8601": "2023-04-03T22:15:55.371465Z",
"url": "https://files.pythonhosted.org/packages/9c/00/0f7ddca22487aba291632e7bde8373b5b044b923c16fc6fe0bc6217a28ea/typeright-0.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91dbddb0c324cbd4e1ff20590a8a8132e7b4aefa07595477062de84c5a7ae3b6",
"md5": "4ba59b87ab72934df241f32d4105d73d",
"sha256": "58704c824060ba3c5e21c5b6fc54f971760aa8db4260cba8a9afa4588e8f47fe"
},
"downloads": -1,
"filename": "typeright-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4ba59b87ab72934df241f32d4105d73d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"size": 57007,
"upload_time": "2023-04-03T22:15:58",
"upload_time_iso_8601": "2023-04-03T22:15:58.250950Z",
"url": "https://files.pythonhosted.org/packages/91/db/ddb0c324cbd4e1ff20590a8a8132e7b4aefa07595477062de84c5a7ae3b6/typeright-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-03 22:15:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "chadrik",
"github_project": "typeright",
"lcname": "typeright"
}
JSON
