From 526d907defabe4485c6ef8924c3d270953288e59 Mon Sep 17 00:00:00 2001 From: Eric Traut Date: Sun, 26 Feb 2023 10:54:20 -0700 Subject: [PATCH] Slimmed down the README to remove information that most pyright users probably don't care about. Features of pyright were moved to a separate "features.md" document. --- README.md | 68 ++----------------------------- docs/features.md | 64 +++++++++++++++++++++++++++++ packages/vscode-pyright/README.md | 2 +- 3 files changed, 69 insertions(+), 65 deletions(-) create mode 100644 docs/features.md diff --git a/README.md b/README.md index 874d9ed2e..67d226225 100644 --- a/README.md +++ b/README.md @@ -2,73 +2,15 @@ # Static type checker for Python -### Speed -Pyright is a fast type checker meant for large Python source bases. It can run in a “watch” mode and performs fast incremental updates when files are modified. - -### Configurability -Pyright supports [configuration files](/docs/configuration.md) that provide granular control over settings. Different “execution environments” can be associated with subdirectories within a source base. Each environment can specify different module search paths, python language versions, and platform targets. - -### Type Checking Features -* [PEP 484](https://www.python.org/dev/peps/pep-0484/) type hints including generics -* [PEP 487](https://www.python.org/dev/peps/pep-0487/) simpler customization of class creation -* [PEP 526](https://www.python.org/dev/peps/pep-0526/) syntax for variable annotations -* [PEP 544](https://www.python.org/dev/peps/pep-0544/) structural subtyping -* [PEP 561](https://www.python.org/dev/peps/pep-0561/) distributing and packaging type information -* [PEP 563](https://www.python.org/dev/peps/pep-0563/) postponed evaluation of annotations -* [PEP 570](https://www.python.org/dev/peps/pep-0570/) position-only parameters -* [PEP 585](https://www.python.org/dev/peps/pep-0585/) type hinting generics in standard collections -* [PEP 586](https://www.python.org/dev/peps/pep-0586/) literal types -* [PEP 589](https://www.python.org/dev/peps/pep-0589/) typed dictionaries -* [PEP 591](https://www.python.org/dev/peps/pep-0591/) final qualifier -* [PEP 593](https://www.python.org/dev/peps/pep-0593/) flexible variable annotations -* [PEP 604](https://www.python.org/dev/peps/pep-0604/) complementary syntax for unions -* [PEP 612](https://www.python.org/dev/peps/pep-0612/) parameter specification variables -* [PEP 613](https://www.python.org/dev/peps/pep-0613/) explicit type aliases -* [PEP 635](https://www.python.org/dev/peps/pep-0635/) structural pattern matching -* [PEP 646](https://www.python.org/dev/peps/pep-0646/) variadic generics -* [PEP 647](https://www.python.org/dev/peps/pep-0647/) user-defined type guards -* [PEP 655](https://www.python.org/dev/peps/pep-0655/) required typed dictionary items -* [PEP 673](https://www.python.org/dev/peps/pep-0673/) Self type -* [PEP 675](https://www.python.org/dev/peps/pep-0675/) arbitrary literal strings -* [PEP 681](https://www.python.org/dev/peps/pep-0681/) dataclass transform -* [PEP 692](https://www.python.org/dev/peps/pep-0692/) TypedDict for kwargs typing -* [PEP 695](https://www.python.org/dev/peps/pep-0695/) (draft) Type parameter syntax -* [PEP 696](https://www.python.org/dev/peps/pep-0696/) (draft) Type defaults for TypeVarLikes -* [PEP 698](https://www.python.org/dev/peps/pep-0698/) Override decorator for static typing -* [PEP 702](https://www.python.org/dev/peps/pep-0702/) (draft) Marking deprecations -* Type inference for function return values, instance variables, class variables, and globals -* Type guards that understand conditional code flow constructs like if/else statements - -### VS Code Integration -Pyright ships as both a command-line tool and a VS Code extension that provides many powerful features that help improve programming efficiency. - -### VS Code Language Features -The VS Code extension supports many time-saving language features including: - -* Intelligent type completion of keywords, symbols, and import names appears when editing -* Import statements are automatically inserted when necessary for type completions -* Signature completion tips help when filling in arguments for a call -* Hover over symbols to provide type information and doc strings -* Find Definitions to quickly go to the location of a symbol’s definition -* Find References to find all references to a symbol within a code base -* Rename Symbol to rename all references to a symbol within a code base -* Find Symbols within the current document or within the entire workspace -* View call hierarchy information — calls made within a function and places where a function is called -* Organize Imports command for automatically ordering imports according to PEP8 rules -* Type stub generation for third-party libraries - -### Built-in Type Stubs -Pyright includes a recent copy of the stdlib type stubs from [Typeshed](https://github.com/python/typeshed). It can be configured to use another (perhaps more recent or modified) copy of the Typeshed type stubs. Of course, it also works with custom type stub files that are part of your project. +Pyright is a full-featured, standards-based static type checker for Python. It is designed for high performance and can be used with large Python source bases. ### Command-line Tool or Visual Studio Code Extension Pyright includes both a [command-line tool](/docs/command-line.md) and an [extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-pyright.pyright) that implements the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). -For rich Python editing and debugging capabilities with Visual Studio Code, be sure to also install the official [Microsoft Python extension for Visual Studio Code](https://marketplace.visualstudio.com/itemdetails?itemName=ms-python.python) as Pyright only provides syntax and type checking. - ## Installation ### VS Code Extension -For most VS Code users, we recommend using the Pylance extension rather than Pyright. Pylance incorporates the Pyright type checker but features additional capabilities such as IntelliCode and semantic token highlighting. You can install the latest-published version of the Pylance VS Code extension directly from VS Code. Simply open the extensions panel and search for “Pylance”. +For most VS Code users, we recommend using the Pylance extension rather than Pyright. Pylance incorporates the Pyright type checker but features additional capabilities such as semantic token highlighting and symbol indexing. You can install the latest-published version of the Pylance VS Code extension directly from VS Code. Simply open the extensions panel and search for “Pylance”. ### Vim Vim/neovim users can install [coc-pyright](https://github.com/fannheyward/coc-pyright), the Pyright extension for coc.nvim. @@ -107,6 +49,7 @@ To update to the latest version: ## Documentation +* [Pyright Features](/docs/features.md) * [Getting Started with Type Checking](/docs/getting-started.md) * [Type Concepts](/docs/type-concepts.md) * [Continuous Integration (CI)](/docs/ci-integration.md) @@ -126,9 +69,6 @@ To update to the latest version: For additional information about Python static typing, refer to this community-maintained [Python Type School](https://github.com/python/typing/discussions). -## Limitations -Pyright provides support for Python 3.0 and newer. There are no plans to support older versions. - ## Community Do you have questions about Pyright or Python type annotations in general? Post your questions in [the discussion section](https://github.com/microsoft/pyright/discussions). @@ -143,7 +83,7 @@ If you would like to report a bug or request an enhancement, file a new issue in **Q:** What is the long-term plan for Pyright? -**A:** Pyright is an officially-supported Microsoft type checker for Python. It will continue to be developed and maintained as an open-source project under its original MIT license terms. The Pyright extension for VS Code is a reference implementation and is not guaranteed to be fully functional or maintained long-term. +**A:** Pyright is an officially-supported Microsoft type checker for Python. It will continue to be developed and maintained as an open-source project under its original MIT license terms. ## Contributing diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 000000000..0963bad3e --- /dev/null +++ b/docs/features.md @@ -0,0 +1,64 @@ +# Pyright Features + +### Speed +Pyright is a fast type checker meant for large Python source bases. It can run in a “watch” mode and performs fast incremental updates when files are modified. + +### Configurability +Pyright supports [configuration files](/docs/configuration.md) that provide granular control over settings. Different “execution environments” can be associated with subdirectories within a source base. Each environment can specify different module search paths, python language versions, and platform targets. + +### Type Checking Features +* [PEP 484](https://www.python.org/dev/peps/pep-0484/) type hints including generics +* [PEP 487](https://www.python.org/dev/peps/pep-0487/) simpler customization of class creation +* [PEP 526](https://www.python.org/dev/peps/pep-0526/) syntax for variable annotations +* [PEP 544](https://www.python.org/dev/peps/pep-0544/) structural subtyping +* [PEP 561](https://www.python.org/dev/peps/pep-0561/) distributing and packaging type information +* [PEP 563](https://www.python.org/dev/peps/pep-0563/) postponed evaluation of annotations +* [PEP 570](https://www.python.org/dev/peps/pep-0570/) position-only parameters +* [PEP 585](https://www.python.org/dev/peps/pep-0585/) type hinting generics in standard collections +* [PEP 586](https://www.python.org/dev/peps/pep-0586/) literal types +* [PEP 589](https://www.python.org/dev/peps/pep-0589/) typed dictionaries +* [PEP 591](https://www.python.org/dev/peps/pep-0591/) final qualifier +* [PEP 593](https://www.python.org/dev/peps/pep-0593/) flexible variable annotations +* [PEP 604](https://www.python.org/dev/peps/pep-0604/) complementary syntax for unions +* [PEP 612](https://www.python.org/dev/peps/pep-0612/) parameter specification variables +* [PEP 613](https://www.python.org/dev/peps/pep-0613/) explicit type aliases +* [PEP 635](https://www.python.org/dev/peps/pep-0635/) structural pattern matching +* [PEP 646](https://www.python.org/dev/peps/pep-0646/) variadic generics +* [PEP 647](https://www.python.org/dev/peps/pep-0647/) user-defined type guards +* [PEP 655](https://www.python.org/dev/peps/pep-0655/) required typed dictionary items +* [PEP 673](https://www.python.org/dev/peps/pep-0673/) Self type +* [PEP 675](https://www.python.org/dev/peps/pep-0675/) arbitrary literal strings +* [PEP 681](https://www.python.org/dev/peps/pep-0681/) dataclass transform +* [PEP 692](https://www.python.org/dev/peps/pep-0692/) TypedDict for kwargs typing +* [PEP 695](https://www.python.org/dev/peps/pep-0695/) (draft) Type parameter syntax +* [PEP 696](https://www.python.org/dev/peps/pep-0696/) (draft) Type defaults for TypeVarLikes +* [PEP 698](https://www.python.org/dev/peps/pep-0698/) Override decorator for static typing +* [PEP 702](https://www.python.org/dev/peps/pep-0702/) (draft) Marking deprecations +* Type inference for function return values, instance variables, class variables, and globals +* Type guards that understand conditional code flow constructs like if/else statements + +### VS Code Integration +Pyright ships as both a command-line tool and a VS Code extension that provides many powerful features that help improve programming efficiency. + +### VS Code Language Features +The VS Code extension supports many time-saving language features including: + +* Intelligent type completion of keywords, symbols, and import names appears when editing +* Import statements are automatically inserted when necessary for type completions +* Signature completion tips help when filling in arguments for a call +* Hover over symbols to provide type information and doc strings +* Find Definitions to quickly go to the location of a symbol’s definition +* Find References to find all references to a symbol within a code base +* Rename Symbol to rename all references to a symbol within a code base +* Find Symbols within the current document or within the entire workspace +* View call hierarchy information — calls made within a function and places where a function is called +* Organize Imports command for automatically ordering imports according to PEP8 rules +* Type stub generation for third-party libraries + +### Built-in Type Stubs +Pyright includes a recent copy of the stdlib type stubs from [Typeshed](https://github.com/python/typeshed). It can be configured to use another (perhaps more recent or modified) copy of the Typeshed type stubs. Of course, it also works with custom type stub files that are part of your project. + +## Limitations +Pyright provides support for Python 3.0 and newer. There are no plans to support older versions. + + diff --git a/packages/vscode-pyright/README.md b/packages/vscode-pyright/README.md index 8f18dfefb..747c0adc5 100644 --- a/packages/vscode-pyright/README.md +++ b/packages/vscode-pyright/README.md @@ -2,7 +2,7 @@ ### Speed -Pyright is a fast type checker meant for large Python source bases. It can run in a "watch" mode and performs fast incremental updates when files are modified. +Pyright is a full-featured, standards-based static type checker for Python. It is designed for high performance and can be used with large Python source bases. ### Configurability