microsoft/pyright
1
1
Fork 0
mirror of https://github.com/microsoft/pyright.git synced 2024-09-11 16:06:39 +03:00
Code Issues Projects Releases Wiki Activity

Updated documentation.

Browse Source
This commit is contained in:
Eric Traut 2019-03-20 21:31:15 -07:00
parent 2c8e4aed58
commit c8531cc9a9
5 changed files with 117 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -37,6 +37,7 @@ Pyright offers the following language service features:
## Documentation
* [Command-line Options](/docs/command-line.md)
* [Configuration](/docs/configuration.md)
* [Getting Started](/docs/getting-started.md)
## Limitations
@ -82,7 +83,6 @@ To install in VS Code, go to the extensions panel and choose "Install from VSIX.
Pyright is a work in progress. The following functionality is not yet finished. If you would like to contribute to any of these areas, contact the maintainers of the repo.
* More complete documentation - especially for configuration options
* Type inference for generators and async functions
* Support for type annotations within comments
* Address the many TODO comments in the code

6
docs/command-line.md
View File

@ -1,4 +1,4 @@
# Command-Line Options
# Pyright Command-Line Options
Pyright can be run as either a VS Code extension or as a node-based command-line tool. The command-line version allows for the following options:
@ -9,11 +9,11 @@ Pyright can be run as either a VS Code extension or as a node-based command-line
| -p,--project FILE OR DIRECTORY | Use the configuration file at this location |
| -t,--typeshed-path DIRECTORY | Use typeshed type stubs at this location (2) |
| -v,--venv-path DIRECTORY | Directory that contains virtual environments (3) |
| -w,--watch | Continue to run and watch for changes |
| -w,--watch | Continue to run and watch for changes (4) |
(1) This option is used to find imports if not using typeshed files or a configuration file with virtual environments.
(2) Pyright has built-in typeshed type stubs for Python stdlib functionality. To use a different version of typeshed type stubs, specify the directory with this option.
(3) This option is used in conjunction with configuration file, which can refer to different virtual environments by name. For more details, refer to the [configuration](/docs/configuration.md) documentation.
(4) When running in watch mode, pyright will reanalyze only those files that have been modified. These “deltas” are typically much faster than the initial analysis, which needs to analyze all files in the source tree.

99
docs/configuration.md
View File

@ -1 +1,100 @@
# Pyright Configuration
Pyright offers flexible configuration options specified in a JSON-formatted text configuration. By default, the file is called "pyrightconfig.json" and is located within the root directory of your project. Relative paths specified within the config file are relative to the config file’s location.
## Master Pyright Config Options
**include** [array of paths, optional]: Paths of directories that should be included. If no paths are specified, pyright defaults to the directory that contains the config file.
**exclude** [array of paths, optional]: Paths of directories that should not be included. These override the includes directories, allowing specific subdirectories to be ignored.
**typeshedPath** [path, optional]: Path to a directory that contains typeshed type stub files. Pyright ships with an internal copy of some typeshed type stubs (those that cover the Python stdlib packages). If you want to use a full copy of the typeshed type stubs (including those for third-party packages), you can clone the [typeshed github repo](https://github.com/python/typeshed) to a local directory and reference the location with this path.
**typingsPath** [path, optional]: Path to a directory that contains custom type stubs. Each package's type stub file(s) are expected to be in its own subdirectory.
**pythonPath** [path, optional]: Path to the Python execution environment. This is used to resolve third-party modules when there is no "venvPath" specified in the config file.
**venvPath** [path, optional]: Path to a directory containing one or more subdirectories, each of which contains a virtual environment. Each execution environment (see below for details) can refer to a different virtual environment. This optional overrides the "pythonPath" option described above.
**venv** [string, optional]: Used in conjunction with the venvPath, specifies the virtual environment to use. Individual execution environments may override this setting.
**pythonVersion** [string, optional]: Specifies the verison of Python that will be used to execute the source code. The version should be specified as a string in the format "M.m" where M is the major version and m is the minor (e.g. ```"3.0"``` or ```"3.6"```). If a version is provided, pyright will generate errors if the source code makes use of language features that are not supported in that version. It will also tailor its use of type stub files, which conditionalize type definitions based on the version.
**pythonPlatform** [string, optional]: Specifies the target platform that will be used to execute the source code. Should be one of ```"Windows"```, ```"Darwin"``` or ```"Linux"```. If specified, pyright will tailor its use of type stub files, which conditionalize type definitions based on the platform.
**executionEnvironments** [array of objects, optional]: Specifies a list of execution environments (see below). Execution environments are searched from start to finish by comparing the path of a source file with the root path specified in the execution environment.
## Type Check Diagnostics Settings
The following settings control pyright's diagnostic output (warnings or errors). Unless otherwise specified, each diagnostic setting can specify a boolean value (```false``` indicating that no error is generated and ```true``` indicating that an error is generated). Alternatively, a string value of ```"none"```, ```"warn"```, or ```"error"``` can be used to specify the diagnostic level.
**reportTypeshedErrors** [boolean or string, optional]: Generate or suppress diagnostics for typeshed type stub files. In general, these type stub files should be "clean" and generate no errors. The default value for this setting is 'none'.
**reportMissingImports** [boolean or string, optional]: Generate or suppress diagnostics for imports that have no corresponding type stub file (either a typeshed file or a custom type stub). The default value for this setting is 'none', although pyright can do a much better job of static type checking if type stub files are provided for all imports.
## Execution Environment Options
Pyright allows multiple “execution environments” to be defined for different portions of your source tree. For example, a subtree may be designed to run with a different PYTHON_PATH or a different version of the python interpeter than the rest of the source base.
The following settings can be specified for each execution environment.
**root** [string, required]: Root path for the code that will execute within this execution environment.
**extraPaths** [array of strings, optional]: Additional search paths (in addition to the root path) that will be used when searching for packages. At runtime, these will be specified in the PYTHON_PATH environment variable.
**venv** [string, optional]: The virtual environment to use for this execution environment. If not specified, the global "venv" setting is used instead.
**pythonVersion** [string, optional]: The version of Python used for this execution environment. If not specified, the global "pythonVersion" setting is used instead.
**pythonPlatform** [string, optional]: Specifies the target platform that will be used for this execution environment. If not specified, the global "pythonPlatform" setting is used instead.
## Sample Config File
The following is an example of a pyright config file:
```json
{
"include": [
"src"
],
"exclude": [
"src/experimental",
"src/web/node_modules",
"src/typestubs"
],
"typingsPath": "src/typestubs",
"reportTypeshedErrors": false,
"reportMissingImports": true,
"pythonVersion": "3.6",
"pythonPlatform": "Linux",
"executionEnvironments": [
{
"root": "src/web",
"pythonVersion": "3.5",
"pythonPlatform": "Windows",
"extraPaths": [
"src/service_libs"
]
},
{
"root": "src/sdk",
"pythonVersion": "3.0",
"extraPaths": [
"src/backend"
]
},
{
"root": "src/tests",
"extraPaths": [
"src/tests/e2e",
"src/sdk"
]
},
{
"root": "src"
}
]
}
```

12
docs/getting-started.md Normal file
View File

@ -0,0 +1,12 @@
## Getting Started with Pyright
A static type checker like pyright can add incremental value to your source code as more type information is provided.
Here is a typical progression:
1. Install pyright (either the VS Code extension or command-line tool).
2. Write a minimal pyrightconfig.json that defines the "projectRoot" and (optionally) "include" and "exclude" entries. Place the config file in your project’s top-level directory and commit it to your repo.
3. Run pyright over your source base with the default settings. Fix any errors and warnings that it emits.
4. Enable the "reportMissingImports" setting in the config file and add (minimal) type stub files for the imported files. You may wish to create a "typestubs" directory within your code base -- a common location for all of your custom type stub files. You may be able to find preexisting type stub files for some of your imports within the typeshed repo (in the [third-party directory](https://github.com/python/typeshed/tree/master/third_party)).
5. Check in your custom type stub files and configure pyright to run as part of your continuous integration environment to keep the project "type clean".
6. Incrementally add type annotations to your code files. The annotations that provide most value are on function input parameters, instance variables, and return parameters (in that order). Note that annotation of variables (instance, class and local) requires Python 3.6 or newer.

3
server/src/analyzer/expressionUtils.ts
View File

@ -39,7 +39,8 @@ export class ExpressionUtils {
// Handle the special case of "sys.platform != 'X'"
let comparisonPlatform = node.rightExpression.getValue();
if (execEnv.pythonPlatform !== undefined) {
return this._evaluateStringBinaryOperation(node.operator, execEnv.pythonPlatform, comparisonPlatform);
return this._evaluateStringBinaryOperation(node.operator,
execEnv.pythonPlatform, comparisonPlatform);
}
}
}