| Name | autotyping JSON |
| Version |
24.9.0
JSON |
| download |
| home_page | None |
| Summary | A tool for autoadding simple type annotations. |
| upload_time | 2024-09-23 12:33:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
annotations
typing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
When I refactor code I often find myself tediously adding type
annotations that are obvious from context: functions that don't
return anything, boolean flags, etcetera. That's where autotyping
comes in: it automatically adds those types and inserts the right
annotations.
# Usage
Autotyping can be called directly from the CLI, be used as a [pre-commit hook](#pre-commit-hook) or run via the [`libcst` interface](#LibCST) as a codemod.
Here's how to use it from the CLI:
- `pip install autotyping`
- `python -m autotyping /path/to/my/code`
By default it does nothing; you have to add flags to make it do
more transformations. The following are supported:
- Annotating return types:
- `--none-return`: add a `-> None` return type to functions without any
return, yield, or raise in their body
- `--scalar-return`: add a return annotation to functions that only return
literal bool, str, bytes, int, or float objects.
- Annotating parameter types:
- `--bool-param`: add a `: bool` annotation to any function
parameter with a default of `True` or `False`
- `--int-param`, `--float-param`, `--str-param`, `--bytes-param`: add
an annotation to any parameter for which the default is a literal int,
float, str, or bytes object
- `--annotate-optional foo:bar.Baz`: for any parameter of the form
`foo=None`, add `Baz`, imported from `bar`, as the type. For example,
use `--annotate-optional uid:my_types.Uid` to annotate any `uid` in your
codebase with a `None` default as `Optional[my_types.Uid]`.
- `--annotate-named-param foo:bar.Baz`: annotate any parameter with no
default that is named `foo` with `bar.Baz`. For example, use
`--annotate-named-param uid:my_types.Uid` to annotate any `uid`
parameter in your codebase with no default as `my_types.Uid`.
- `--guess-common-names`: infer certain parameter types from their names
based on common patterns in open-source Python code. For example, infer
that a `verbose` parameter is of type `bool`.
- Annotating magical methods:
- `--annotate-magics`: add type annotation to certain magic methods.
Currently this does the following:
- `__str__` returns `str`
- `__repr__` returns `str`
- `__len__` returns `int`
- `__length_hint__` returns `int`
- `__init__` returns `None`
- `__del__` returns `None`
- `__bool__` returns `bool`
- `__bytes__` returns `bytes`
- `__format__` returns `str`
- `__contains__` returns `bool`
- `__complex__` returns `complex`
- `__int__` returns `int`
- `__float__` returns `float`
- `__index__` returns `int`
- `__exit__`: the three parameters are `Optional[Type[BaseException]]`,
`Optional[BaseException]`, and `Optional[TracebackType]`
- `__aexit__`: same as `__exit__`
- `--annotate-imprecise-magics`: add imprecise type annotations for
some additional magic methods. Currently this adds `typing.Iterator`
return annotations to `__iter__`, `__await__`, and `__reversed__`.
These annotations should have a generic parameter to indicate what
you're iterating over, but that's too hard for autotyping to figure
out.
- External integrations
- `--pyanalyze-report`: takes types suggested by
[pyanalyze](https://github.com/quora/pyanalyze)'s `suggested_parameter_type`
and `suggested_return_type` codes and applies them. You can generate these
with a command like:
`pyanalyze --json-output failures.json -e suggested_return_type -e suggested_parameter_type -v .`
- `--only-without-imports`: only apply pyanalyze suggestions that do not require
new imports. This is useful because suggestions that require imports may need
more manual work.
There are two shortcut flags to enable multiple transformations at once:
- `--safe` enables changes that should always be safe. This includes
`--none-return`, `--scalar-return`, and `--annotate-magics`.
- `--aggressive` enables riskier changes that are more likely to produce
new type checker errors. It includes all of `--safe` as well as `--bool-param`,
`--int-param`, `--float-param`, `--str-param`, `--bytes-param`, and
`--annotate-imprecise-magics`.
# LibCST
Autotyping is built as a LibCST codemod; see the
[LibCST documentation](https://libcst.readthedocs.io/en/latest/codemods_tutorial.html)
for more information on how to use codemods.
If you wish to run things through the `libcst.tool` interface, you can do this like so:
- Make sure you have a `.libcst.codemod.yaml` with `'autotyping'` in the `modules` list.
For an example, see the `.libcst.codemod.yaml` in this repo.
- Run `python -m libcst.tool codemod autotyping.AutotypeCommand /path/to/my/code`
# pre-commit hook
Pre-commit hooks are scripts that runs automatically before a commit is made,
which makes them really handy for checking and enforcing code-formatting
(or in this case, typing)
1. To add `autotyping` as a [pre-commit](https://pre-commit.com/) hook,
you will first need to install pre-commit if you haven't already:
```
pip install pre-commit
```
2. After that, create or update the `.pre-commit-config.yaml` file at the root
of your repository and add in:
```yaml
- repos:
- repo: https://github.com/JelleZijlstra/autotyping
rev: 24.9.0
hooks:
- id: autotyping
stages: [commit]
types: [python]
args: [--safe] # or alternatively, --aggressive, or any of the other flags mentioned above
```
3. Finally, run the following command to install the pre-commit hook
in your repository:
```
pre-commit install
```
Now whenever you commit changes, autotyping will automatically add
type annotations to your code!
# Limitations
Autotyping is intended to be a simple tool that uses heuristics to find
annotations that would be tedious to add by hand. The heuristics may fail,
and after you run autotyping you should run a type checker to verify that
the types it added are correct.
Known limitations:
- autotyping does not model code flow through a function, so it may miss
implicit `None` returns
# Changelog
## 24.9.0 (September 23, 2024)
- Add pre-commit support. (Thanks to Akshit Tyagi and Matthew Akram.)
- Add missing dependency. (Thanks to Stefane Fermigier.)
## 24.3.0 (March 25, 2024)
- Add simpler ways to invoke autotyping. Now, it is possible to simply use
`python3 -m autotyping` to invoke the tool. (Thanks to Shantanu Jain.)
- Drop support for Python 3.7; add support for Python 3.12. (Thanks to Hugo
van Kemenade.)
- Infer return types for some more magic methods. (Thanks to Dhruv Manilawala.)
## 23.3.0 (March 3, 2023)
- Fix crash on certain argument names like `iterables` (contributed by
Marco Gorelli)
## 23.2.0 (February 3, 2023)
- Add `--guess-common-names` (contributed by John Litborn)
- Fix the `--safe` and `--aggressive` flags so they don't take
ignored arguments
- `--length-hint` should return `int` (contributed by Nikita Sobolev)
- Fix bug in import adding (contributed by Shantanu)
## 22.9.0 (September 5, 2022)
- Add `--safe` and `--aggressive`
- Add `--pyanalyze-report`
- Do not add `None` return types to methods marked with `@abstractmethod` and
to methods in stub files
- Improve type inference:
- `"string" % ...` is always `str`
- `b"bytes" % ...` is always `bytes`
- An `and` or `or` operator where left and right sides are of the same type
returns that type
- `is`, `is not`, `in`, and `not in` always return `bool`
## 21.12.0 (December 21, 2021)
- Initial PyPI release
Raw data
{
"_id": null,
"home_page": null,
"name": "autotyping",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "annotations, typing",
"author": null,
"author_email": "Jelle Zijlstra <jelle.zijlstra@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1e/d6/da57f5c54009f3a2436e25aab1f156a241e61d96be6456050be11d5350a8/autotyping-24.9.0.tar.gz",
"platform": null,
"description": "When I refactor code I often find myself tediously adding type\nannotations that are obvious from context: functions that don't\nreturn anything, boolean flags, etcetera. That's where autotyping\ncomes in: it automatically adds those types and inserts the right\nannotations.\n\n# Usage\n\nAutotyping can be called directly from the CLI, be used as a [pre-commit hook](#pre-commit-hook) or run via the [`libcst` interface](#LibCST) as a codemod.\nHere's how to use it from the CLI:\n\n- `pip install autotyping`\n- `python -m autotyping /path/to/my/code`\n\nBy default it does nothing; you have to add flags to make it do\nmore transformations. The following are supported:\n\n- Annotating return types:\n - `--none-return`: add a `-> None` return type to functions without any\n return, yield, or raise in their body\n - `--scalar-return`: add a return annotation to functions that only return\n literal bool, str, bytes, int, or float objects.\n- Annotating parameter types:\n - `--bool-param`: add a `: bool` annotation to any function\n parameter with a default of `True` or `False`\n - `--int-param`, `--float-param`, `--str-param`, `--bytes-param`: add\n an annotation to any parameter for which the default is a literal int,\n float, str, or bytes object\n - `--annotate-optional foo:bar.Baz`: for any parameter of the form\n `foo=None`, add `Baz`, imported from `bar`, as the type. For example,\n use `--annotate-optional uid:my_types.Uid` to annotate any `uid` in your\n codebase with a `None` default as `Optional[my_types.Uid]`.\n - `--annotate-named-param foo:bar.Baz`: annotate any parameter with no\n default that is named `foo` with `bar.Baz`. For example, use\n `--annotate-named-param uid:my_types.Uid` to annotate any `uid`\n parameter in your codebase with no default as `my_types.Uid`.\n - `--guess-common-names`: infer certain parameter types from their names\n based on common patterns in open-source Python code. For example, infer\n that a `verbose` parameter is of type `bool`.\n- Annotating magical methods:\n - `--annotate-magics`: add type annotation to certain magic methods.\n Currently this does the following:\n - `__str__` returns `str`\n - `__repr__` returns `str`\n - `__len__` returns `int`\n - `__length_hint__` returns `int`\n - `__init__` returns `None`\n - `__del__` returns `None`\n - `__bool__` returns `bool`\n - `__bytes__` returns `bytes`\n - `__format__` returns `str`\n - `__contains__` returns `bool`\n - `__complex__` returns `complex`\n - `__int__` returns `int`\n - `__float__` returns `float`\n - `__index__` returns `int`\n - `__exit__`: the three parameters are `Optional[Type[BaseException]]`,\n `Optional[BaseException]`, and `Optional[TracebackType]`\n - `__aexit__`: same as `__exit__`\n - `--annotate-imprecise-magics`: add imprecise type annotations for\n some additional magic methods. Currently this adds `typing.Iterator`\n return annotations to `__iter__`, `__await__`, and `__reversed__`.\n These annotations should have a generic parameter to indicate what\n you're iterating over, but that's too hard for autotyping to figure\n out.\n- External integrations\n - `--pyanalyze-report`: takes types suggested by\n [pyanalyze](https://github.com/quora/pyanalyze)'s `suggested_parameter_type`\n and `suggested_return_type` codes and applies them. You can generate these\n with a command like:\n `pyanalyze --json-output failures.json -e suggested_return_type -e suggested_parameter_type -v .`\n - `--only-without-imports`: only apply pyanalyze suggestions that do not require\n new imports. This is useful because suggestions that require imports may need\n more manual work.\n\nThere are two shortcut flags to enable multiple transformations at once:\n\n- `--safe` enables changes that should always be safe. This includes\n `--none-return`, `--scalar-return`, and `--annotate-magics`.\n- `--aggressive` enables riskier changes that are more likely to produce\n new type checker errors. It includes all of `--safe` as well as `--bool-param`,\n `--int-param`, `--float-param`, `--str-param`, `--bytes-param`, and\n `--annotate-imprecise-magics`.\n\n# LibCST\n\nAutotyping is built as a LibCST codemod; see the\n[LibCST documentation](https://libcst.readthedocs.io/en/latest/codemods_tutorial.html)\nfor more information on how to use codemods.\n\nIf you wish to run things through the `libcst.tool` interface, you can do this like so:\n- Make sure you have a `.libcst.codemod.yaml` with `'autotyping'` in the `modules` list.\n For an example, see the `.libcst.codemod.yaml` in this repo.\n- Run `python -m libcst.tool codemod autotyping.AutotypeCommand /path/to/my/code`\n\n\n# pre-commit hook\n\nPre-commit hooks are scripts that runs automatically before a commit is made,\nwhich makes them really handy for checking and enforcing code-formatting \n(or in this case, typing)\n\n1. To add `autotyping` as a [pre-commit](https://pre-commit.com/) hook, \nyou will first need to install pre-commit if you haven't already:\n```\npip install pre-commit\n```\n\n2. After that, create or update the `.pre-commit-config.yaml` file at the root\nof your repository and add in:\n\n```yaml\n- repos:\n - repo: https://github.com/JelleZijlstra/autotyping\n rev: 24.9.0\n hooks:\n - id: autotyping\n stages: [commit]\n types: [python]\n args: [--safe] # or alternatively, --aggressive, or any of the other flags mentioned above \n```\n\n3. Finally, run the following command to install the pre-commit hook\nin your repository:\n\n```\npre-commit install\n```\n\nNow whenever you commit changes, autotyping will automatically add\ntype annotations to your code!\n\n\n# Limitations\n\nAutotyping is intended to be a simple tool that uses heuristics to find\nannotations that would be tedious to add by hand. The heuristics may fail,\nand after you run autotyping you should run a type checker to verify that\nthe types it added are correct.\n\nKnown limitations:\n\n- autotyping does not model code flow through a function, so it may miss\n implicit `None` returns\n\n# Changelog\n\n## 24.9.0 (September 23, 2024)\n\n- Add pre-commit support. (Thanks to Akshit Tyagi and Matthew Akram.)\n- Add missing dependency. (Thanks to Stefane Fermigier.)\n\n## 24.3.0 (March 25, 2024)\n\n- Add simpler ways to invoke autotyping. Now, it is possible to simply use\n `python3 -m autotyping` to invoke the tool. (Thanks to Shantanu Jain.)\n- Drop support for Python 3.7; add support for Python 3.12. (Thanks to Hugo\n van Kemenade.)\n- Infer return types for some more magic methods. (Thanks to Dhruv Manilawala.)\n\n## 23.3.0 (March 3, 2023)\n\n- Fix crash on certain argument names like `iterables` (contributed by\n Marco Gorelli)\n\n## 23.2.0 (February 3, 2023)\n\n- Add `--guess-common-names` (contributed by John Litborn)\n- Fix the `--safe` and `--aggressive` flags so they don't take\n ignored arguments\n- `--length-hint` should return `int` (contributed by Nikita Sobolev)\n- Fix bug in import adding (contributed by Shantanu)\n\n## 22.9.0 (September 5, 2022)\n\n- Add `--safe` and `--aggressive`\n- Add `--pyanalyze-report`\n- Do not add `None` return types to methods marked with `@abstractmethod` and\n to methods in stub files\n- Improve type inference:\n - `\"string\" % ...` is always `str`\n - `b\"bytes\" % ...` is always `bytes`\n - An `and` or `or` operator where left and right sides are of the same type\n returns that type\n - `is`, `is not`, `in`, and `not in` always return `bool`\n\n## 21.12.0 (December 21, 2021)\n\n- Initial PyPI release\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool for autoadding simple type annotations.",
"version": "24.9.0",
"project_urls": {
"Bug Tracker": "https://github.com/JelleZijlstra/autotyping/issues",
"Homepage": "https://github.com/JelleZijlstra/autotyping"
},
"split_keywords": [
"annotations",
" typing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "baf27d40e2913c27634ebf4a3e8a77061a3ed1432ccd0b8590787985e4da8e46",
"md5": "85ea732b3a6e6e991afa060291441620",
"sha256": "9c16b0bcab310a2dfe5228bb01c4d1dd5499e7bf67fc6b7915c35267c665b498"
},
"downloads": -1,
"filename": "autotyping-24.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85ea732b3a6e6e991afa060291441620",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12920,
"upload_time": "2024-09-23T12:33:49",
"upload_time_iso_8601": "2024-09-23T12:33:49.957820Z",
"url": "https://files.pythonhosted.org/packages/ba/f2/7d40e2913c27634ebf4a3e8a77061a3ed1432ccd0b8590787985e4da8e46/autotyping-24.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1ed6da57f5c54009f3a2436e25aab1f156a241e61d96be6456050be11d5350a8",
"md5": "7e454cf2a0288e62c1f7369e1f89ec19",
"sha256": "d7e9787aca0f69b089431581f703c53210d2cf39e792e2106759d04034c1251b"
},
"downloads": -1,
"filename": "autotyping-24.9.0.tar.gz",
"has_sig": false,
"md5_digest": "7e454cf2a0288e62c1f7369e1f89ec19",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17116,
"upload_time": "2024-09-23T12:33:51",
"upload_time_iso_8601": "2024-09-23T12:33:51.417746Z",
"url": "https://files.pythonhosted.org/packages/1e/d6/da57f5c54009f3a2436e25aab1f156a241e61d96be6456050be11d5350a8/autotyping-24.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 12:33:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JelleZijlstra",
"github_project": "autotyping",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "autotyping"
}
