diff --git a/README.md b/README.md index e8dbaeed9..536e2d685 100644 --- a/README.md +++ b/README.md @@ -1,284 +1,30 @@ -[![CI](https://github.com/google/pytype/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/google/pytype/actions/workflows/ci.yml?query=branch%3Amain) -[![PyPI - Wheel](https://img.shields.io/pypi/wheel/pytype)](https://pypi.org/project/pytype/#files) - -# pytype - πŸ¦†βœ” - -Pytype checks and infers types for your Python code - without requiring type -annotations. Pytype can: - -* Lint plain Python code, flagging common mistakes such as misspelled attribute -names, incorrect function calls, and [much more][error-classes], even across -file boundaries. -* Enforce user-provided [type annotations][pep-484]. While annotations are -optional for pytype, it will check and apply them where present. -* Generate type annotations in standalone files ("[pyi files][pyi-stub-files]"), -which can be merged back into the Python source with a provided -[merge-pyi][merge-pyi] tool. - -Pytype is a static analyzer; it does not execute the code it runs on. - -Thousands of projects at Google rely on pytype to keep their Python code -well-typed and error-free. - -For more information, check out the [user guide][user-guide], [FAQ][faq], or -[supported features][supported-features]. - -## How is pytype different from other type checkers? - -1. Pytype uses **inference** instead of gradual typing. This means it will -infer types on code even when the code has no type hints on it. So it can -detect issues with code like this, which other type checkers would miss: - - ```python - def f(): - return "PyCon" - def g(): - return f() + 2019 - - # pytype: line 4, in g: unsupported operand type(s) for +: 'str' - # and 'int' [unsupported-operands] - ``` - -1. Pytype is **lenient** instead of strict. That means it allows all -operations that succeed at runtime and don't contradict annotations. For -instance, this code will pass as safe in pytype, but fail in other type -checkers, which assign types to variables as soon as they are initialized: - - ```python - from typing import List - def get_list() -> List[str]: - lst = ["PyCon"] - lst.append(2019) - return [str(x) for x in lst] - - # mypy: line 4: error: Argument 1 to "append" of "list" has - # incompatible type "int"; expected "str" - ``` - -Also see the corresponding [FAQ entry][faq-diff]. - -## Quickstart - -To quickly get started with type-checking a file or directory, run the -following, replacing `file_or_directory` with your input: - -```shell -pip install pytype -pytype file_or_directory -``` - -To set up pytype on an entire package, add the following to a `pyproject.toml` -file in the directory immediately above the package, replacing `package_name` -with the package name: - -```toml -[tool.pytype] -inputs = ['package_name'] -``` - -Now you can run the no-argument command `pytype` to type-check the package. It's -also easy to add pytype to your automated testing; see this -[example][importlab-github-actions] of a GitHub project that runs pytype on GitHub Actions. - -Finally, pytype generates files of inferred type information, located by default -in `.pytype/pyi`. You can use this information to type-annotate the -corresponding source file: - -```shell -merge-pyi -i .py .pytype/pyi/.pyi -``` - -## Requirements - -You need a Python 3.8-3.12 interpreter to run pytype, as well as an -interpreter in `$PATH` for the Python version of the code you're analyzing -(supported: 3.8-3.12). - -Platform support: - -* Pytype is currently developed and tested on Linux\*, which is the main supported - platform. -* Installation on MacOSX requires OSX 10.7 or higher and Xcode v8 or higher**. -* Windows is currently not supported unless you use [WSL][wsl]. - -\* -On Alpine Linux, installation may fail due to issues with upstream -dependencies. See the details of [this issue][scikit-build-issue] for a -possible fix. -
-\*\* -If the ninja dependency fails to install, make sure cmake is installed. See -[this issue][ninja-build-issue] for details. - - -## Installing - -Pytype can be installed via pip. Note that the installation requires `wheel` -and `setuptools`. (If you're working in a virtualenv, these two packages should -already be present.) - -```shell -pip install pytype -``` - -Or from the source code [on GitHub][github]. - -```shell -git clone --recurse-submodules https://github.com/google/pytype.git -cd pytype -pip install . -``` - -Instead of using `--recurse-submodules`, you could also have run - -```shell -git submodule init -git submodule update -``` - -in the `pytype` directory. To edit the code and have your edits tracked live, -replace the pip install command with: - -```shell -pip install -e . -``` - -### Installing on WSL - -Follow the steps above, but make sure you have the correct libraries first: - -```shell -sudo apt install build-essential python3-dev libpython3-dev -``` - -## Usage - -``` -usage: pytype [options] input [input ...] - -positional arguments: - input file or directory to process -``` - -Common options: - -* `-V, --python-version`: Python version (major.minor) of the target code. - Defaults to the version that pytype is running under. -* `-o, --output`: The directory into which all pytype output goes, including - generated .pyi files. Defaults to `.pytype`. -* `-d, --disable`. Comma or space-separated list of error names to ignore. - Detailed explanations of pytype's error names are in - [this doc][error-classes]. Defaults to empty. - -For a full list of options, run `pytype --help`. - -In addition to the above, you can direct pytype to use a custom typeshed -installation instead of its own bundled copy by setting `$TYPESHED_HOME`. - -### Config File - -For convenience, you can save your pytype configuration in a file. The config -file can be a TOML-style file with a `[tool.pytype]` section (preferred) or an -INI-style file with a `[pytype]` section. If an explicit config file is not -supplied, pytype will look for a pytype section in the first `pyproject.toml` or -`setup.cfg` file found by walking upwards from the current working directory. - -Start off by generating a sample config file: - -```shell -$ pytype --generate-config pytype.toml -``` - -Now customize the file based on your local setup, keeping only the sections you -need. Directories may be relative to the location of the config file, which is -useful if you want to check in the config file as part of your project. - -For example, suppose you have the following directory structure and want to -analyze package `~/repo1/foo`, which depends on package `~/repo2/bar`: - -``` -~/ -β”œβ”€β”€ repo1 -β”‚ └── foo -β”‚ β”œβ”€β”€ __init__.py -β”‚ └── file_to_check.py -└── repo2 - └── bar - β”œβ”€β”€ __init__.py - └── dependency.py -``` - -Here is the filled-in config file, which instructs pytype to type-check -`~/repo1/foo` as Python 3.9 code, look for packages in `~/repo1` and `~/repo2`, -and ignore attribute errors. Notice that the path to a package does not include -the package itself. - -```toml -$ cat ~/repo1/pytype.toml - -# NOTE: All relative paths are relative to the location of this file. - -[tool.pytype] - -# Space-separated list of files or directories to process. -inputs = [ - 'foo', -] - -# Python version (major.minor) of the target code. -python_version = '3.9' - -# Paths to source code directories, separated by ':'. -pythonpath = .:~/repo2 - -# Space-separated list of error names to ignore. -disable = [ - 'attribute-error', -] -``` - -We could've discovered that `~/repo2` needed to be added to the pythonpath by -running pytype's broken dependency checker: - -``` -$ pytype --config=~/repo1/pytype.toml ~/repo1/foo/*.py --unresolved - -Unresolved dependencies: - bar.dependency -``` - -### Subtools - -Pytype ships with a few scripts in addition to `pytype` itself: - -* `annotate-ast`, an in-progress type annotator for ASTs. -* [`merge-pyi`][merge-pyi], for merging type information from a .pyi file into a -Python file. -* `pytd-tool`, a parser for .pyi files. -* `pytype-single`, a debugging tool for pytype developers, which analyzes a -single Python file assuming that .pyi files have already been generated for all -of its dependencies. -* `pyxref`, a cross-references generator. - -## License - -[Apache 2.0][license] - -## Disclaimer - -This is not an official Google product. - -[error-classes]: docs/errors.md -[faq]: docs/faq.md -[faq-diff]: docs/faq.md#how-is-pytype-different-from-other-type-checkers -[github]: https://github.com/google/pytype/ -[importlab-github-actions]: https://github.com/google/importlab/blob/main/.github/workflows/ci.yml -[license]: https://github.com/google/pytype/blob/main/LICENSE -[merge-pyi]: https://github.com/google/pytype/tree/main/pytype/tools/merge_pyi -[ninja-build-issue]: https://github.com/google/pytype/issues/957 -[pep-484]: https://www.python.org/dev/peps/pep-0484 -[pyi-stub-files]: docs/user_guide.md#pyi-stub-files -[scikit-build-issue]: https://github.com/scikit-build/ninja-python-distributions/issues/27 -[supported-features]: docs/support.md -[user-guide]: docs/user_guide.md -[wsl]: https://docs.microsoft.com/en-us/windows/wsl/faq +# An update on pytype + +**TL;DR**: The last supported Python version for Pytype will be 3.12. We are +still very actively interested in the space of Python type checking, but +shifting our investments towards new ideas and different frameworks. + +Pytype's development began in 2012 to meet Google developers' demand for +compile-time checking. Pytype started with using type inference and interface +files, and then switched to inline annotations (while retaining the inference +engine) after the acceptance of PEP 484. Later, pytype's team collaborated with +Guido and mypy to create typeshed, a central repository for type annotations. + +While pytype has been effective, its bytecode-based design has presented +challenges in implementing new features (e.g. faster adoption of new typing +PEPs) due to bytecode’s inherent instability and propensity to change. +Consequently, we intend to focus our investments on exploring new typing +approaches that are better suited for Google’s Python user base and make +Python 3.12 the last supported version for pytype. + +We encourage folks to investigate the mature and excellent alternative solutions +for Python typing going forward. We would like to note that the Python typing +ecosystem is very robust now, offering a wider array of mature solutions (see +[FAQ](https://github.com/google/pytype/issues/1925)). + +The creation and development of pytype was a collaborative effort, and we would +like to thank all contributors to pytype, especially the four main contributors: +Rebecca Chen, Martin DeMello, Teddy Sudol, and initial lead Matthias Kramm. +We particularly recognize Rebecca Chen for her decade-long commitment to pytype +and her significant contributions to Python's type system as a long-standing +member of the typing council.