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

A few updates to the docs.

Browse Source
This commit is contained in:
Eric Traut 2019-03-20 21:37:56 -07:00
parent c8531cc9a9
commit 24bc2ad86e
3 changed files with 17 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -56,15 +56,15 @@ A: The Microsoft Python Language Server is a [language server protocol (LSP)](ht
To build the project:
1. Install [nodejs](https://nodejs.org/en/)
2. Open terminal window in main directory of cloned source
3. Execute "npm install" to download dependencies
4. Execute "npm run build"
3. Execute `npm install` to download dependencies
4. Execute `npm run build`
To build the VS Code extension package:
Same as above, plus
1. Execute "npm run package"
1. Execute `npm run package`
The resulting package (pyright-X.Y.Z.vsix) can be found in the client directory.
To install in VS Code, go to the extensions panel and choose "Install from VSIX..." from the menu, then select the package.
To install in VS Code, go to the extensions panel and choose “Install from VSIX...” from the menu, then select the package.
## Code Structure

20
docs/configuration.md
View File

@ -6,29 +6,29 @@ Pyright offers flexible configuration options specified in a JSON-formatted text
**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.
**exclude** [array of paths, optional]: Paths of directories that should not be included. These override the includes directories, allowing specific subdirectories to be ignored. Note that files in the exclude paths may still be included in the analysis if they are referenced (imported) by source files that are not excluded.
**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.
**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.
**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.
**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.
**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.
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'.
**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.
@ -42,11 +42,11 @@ The following settings can be specified for each 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.
**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.
**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.
**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

6
docs/getting-started.md
View File

@ -4,9 +4,9 @@ A static type checker like pyright can add incremental value to your source code
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.
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".
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.