Merge pull request #9 from microbit-foundation/three-microbit-update

Update microbit branch from browser branch.
Minor test fix-ups after merge.

Author: microbit-matt-hillsdon

.eslintrc.json

@@ -62,7 +62,61 @@
                 "args": "none"
             }
         ],
-        "@typescript-eslint/no-use-before-define": 0
+        "@typescript-eslint/no-use-before-define": 0,
+        "@typescript-eslint/naming-convention": [
+            "error",
+            {
+                "selector": [
+                    "classProperty",
+                    "typeProperty",
+                    "parameterProperty",
+                    "classMethod",
+                    "typeMethod",
+                    "accessor"
+                ],
+                "modifiers": ["private"],
+                "leadingUnderscore": "require",
+                "format": ["camelCase"],
+                "filter": {
+                    "regex": "^(test_| )",
+                    "match": false
+                }
+            },
+            {
+                "selector": [
+                    "classProperty",
+                    "typeProperty",
+                    "parameterProperty",
+                    "classMethod",
+                    "typeMethod",
+                    "accessor"
+                ],
+                "modifiers": ["protected"],
+                "leadingUnderscore": "allow",
+                "format": ["camelCase"],
+                "filter": {
+                    "regex": "^(test_| )",
+                    "match": false
+                }
+            },
+            {
+                "selector": [
+                    "classProperty",
+                    "typeProperty",
+                    "parameterProperty",
+                    "classMethod",
+                    "typeMethod",
+                    "accessor"
+                ],
+                "modifiers": ["public"],
+                "leadingUnderscore": "forbid",
+                "format": ["camelCase"],
+                "filter": {
+                    "regex": "^(test_| )",
+                    "match": false
+                }
+            }
+        ]
     },
     "overrides": [
         {

.github/workflows/validation.yml

@@ -1,7 +1,7 @@
 name: 'Validation'
 
 env:
-  NODE_VERSION: '12' # Shipped with VS Code.
+  NODE_VERSION: '14' # Shipped with VS Code.
 
 on:
   push:
@@ -14,7 +14,7 @@ on:
 jobs:
   typecheck:
     if: github.repository == 'microsoft/pyright'
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     name: Typecheck
 
     steps:
@@ -41,7 +41,7 @@ jobs:
 
   style:
     if: github.repository == 'microsoft/pyright'
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     name: Style
 
     steps:
@@ -73,7 +73,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-10.15, windows-2019, ubuntu-18.04]
+        os: [macos-latest, windows-2019, ubuntu-latest]
 
     name: Test ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
@@ -108,7 +108,7 @@ jobs:
         working-directory: packages/pyright-internal
 
   build:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     name: Build
     needs: typecheck
 
@@ -139,7 +139,7 @@ jobs:
         working-directory: packages/vscode-pyright
 
   required:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     name: Required
     needs:
       - typecheck

.vscode/launch.json

@@ -76,6 +76,17 @@
             "disableOptimisticBPs": true,
             "program": "${workspaceFolder}/packages/pyright-internal/node_modules/jest/bin/jest"
         },
+        {
+            "name": "Pyright jest selected test",
+            "type": "node",
+            "request": "launch",
+            "args": ["${fileBasenameNoExtension}", "--runInBand", "-t", "${selectedText}"],
+            "cwd": "${workspaceRoot}/packages/pyright-internal",
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen",
+            "disableOptimisticBPs": true,
+            "program": "${workspaceFolder}/packages/pyright-internal/node_modules/jest/bin/jest"
+        },
         {
             "name": "Pyright fourslash current file",
             "type": "node",

README.md

@@ -25,10 +25,12 @@ Pyright supports [configuration files](/docs/configuration.md) that provide gran
 * [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 637](https://www.python.org/dev/peps/pep-0637/) indexing with keyword arguments
 * [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
 * Type inference for function return values, instance variables, class variables, and globals
 * Type guards that understand conditional code flow constructs like if/else statements
 
@@ -61,40 +63,45 @@ For rich Python editing and debugging capabilities with Visual Studio Code, be s
 
 ## 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 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”.
 
 ### Vim
-For vim/neovim users, you can install [coc-pyright](https://github.com/fannheyward/coc-pyright), the Pyright extension for coc.nvim.
+Vim/neovim users can install [coc-pyright](https://github.com/fannheyward/coc-pyright), the Pyright extension for coc.nvim.
 
 Alternatively, [ALE](https://github.com/dense-analysis/ale) will automatically check your code with Pyright, without requiring any additional configuration.
 
 ### Sublime Text
-For sublime text users, you can install the [LSP-pyright](https://github.com/sublimelsp/LSP-pyright) plugin from [package control](https://packagecontrol.io/packages/LSP-pyright).
+Sublime text users can install the [LSP-pyright](https://github.com/sublimelsp/LSP-pyright) plugin from [package control](https://packagecontrol.io/packages/LSP-pyright).
 
 ### Emacs
-For emacs users, you can install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) that includes [lsp-pyright](https://github.com/emacs-lsp/lsp-pyright).
+Emacs users can install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) that includes [lsp-pyright](https://github.com/emacs-lsp/lsp-pyright).
 To activate the pyright extension follow the instructions in the [docs](https://emacs-lsp.github.io/lsp-pyright/).
 
 ### Command-line
-The latest version of the command-line tool can be installed with npm, which is part of node. If you don't have a recent version of node on your system, install that first from [nodejs.org](https://nodejs.org). 
+A [community-maintained](https://github.com/RobertCraigie/pyright-python) Python package by the name of “pyright” is available on pypi and conda-forge. This package will automatically install node (which Pyright requires) and keep Pyright up to date.
+
+`pip install pyright`
+
+or
+
+`conda install pyright`
+
+Once installed, you can run the tool from the command line as follows:
+`pyright <options>`
+
+
+Alternatively, you can install the command-line version of Pyright directly from npm, which is part of node. If you don't have a recent version of node on your system, install that first from [nodejs.org](https://nodejs.org). 
 
 To install pyright globally:
 `npm install -g pyright`
 
 On MacOS or Linux, sudo is required to install globally:
 `sudo npm install -g pyright`
 
-Once installed, you can run the tool from the command line as follows:
-`pyright <options>`
-
 To update to the latest version:
 `sudo npm update -g pyright`
 
 
-## Using Pyright with VS Code Python Extension
-Pyright’s type-checking functionality and language features are now incorporated into a VS Code extension called [Pylance](https://github.com/microsoft/pylance-release), the officially supported Python Language Server from Microsoft. Pylance is designed to work with the Python extension for VS Code. In addition to Pyright’s functionality, Pylance adds compatibility with several advanced features including IntelliCode for AI-assisted completions. If you are a VS Code user, we recommend that you uninstall Pyright and instead install Pylance. You will get all the benefits of Pyright and more! 
-
-
 ## Documentation
 * [Getting Started with Type Checking](/docs/getting-started.md)
 * [Type Concepts](/docs/type-concepts.md)
@@ -105,6 +112,7 @@ Pyright’s type-checking functionality and language features are now incorporat
 * [Comments](/docs/comments.md)
 * [Type Inference](/docs/type-inference.md)
 * [Import Resolution](/docs/import-resolution.md)
+* [Extending Builtins](/docs/builtins.md)
 * [Type Stubs](/docs/type-stubs.md)
 * [Types in Libraries](/docs/typed-libraries.md)
 * [Commands](/docs/commands.md)
@@ -114,12 +122,14 @@ Pyright’s type-checking functionality and language features are now incorporat
 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 is currently no plan to support older versions.
+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).
 
+If you would like to report a bug or request an enhancement, file a new issue in either the [pyright](https://github.com/microsoft/pyright/issues) or [pylance-release](https://github.com/microsoft/pylance-release/issues) issue tracker. In general, core type checking functionality is associated with Pyright while language service functionality is associated with Pylance, but the same contributors monitor both repos. For best results, provide the information requested in the issue template.
+
 
 ## FAQ
 **Q:** What is the difference between Pyright and [Pylance](https://github.com/microsoft/pylance-release)? 
@@ -128,12 +138,12 @@ Do you have questions about Pyright or Python type annotations in general? Post
 
 **Q:** What is the long-term plan for Pyright?
 
-**A:** Pyright is now 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 VSCode 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. The Pyright extension for VS Code is a reference implementation and is not guaranteed to be fully functional or maintained long-term.
 
 
 ## Contributing
 
-This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
+This project welcomes contributions and suggestions. For feature and complex bug fix contributions, it is recommended that you first discuss the proposed change with Pyright’s maintainers before submitting the pull request. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
 
 When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
 

build/lib/updateDeps.js

@@ -47,7 +47,7 @@ async function updatePackage(packageFile, transitive, reject = undefined) {
         reject: reject,
     });
 
-    if (!transitive && Object.keys(updateResult).length === 0) {
+    if (!transitive && Object.keys(/**@type {any}*/ (updateResult)).length === 0) {
         // If nothing changed and we aren't updating transitive deps, don't run npm install.
         return;
     }

build/updateDeps.js

@@ -14,6 +14,7 @@ async function main() {
         // These packages impact compatibility with VS Code and other users;
         // ensure they remained pinned exactly.
         '@types/vscode',
+        'vsce',
         'vscode-jsonrpc',
         'vscode-languageclient',
         'vscode-languageserver',

docs/build-debug.md

@@ -24,6 +24,12 @@ 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.
 
 
+## Running Pyright tests
+
+1. cd to the `packages/pyright-internal` directory
+2. Execute `npm run test`
+
+
 ## Debugging Pyright
 
 To debug pyright, open the root source directory within VS Code. Open the debug sub-panel and choose “Pyright CLI” from the debug target menu. Click on the green “run” icon or press F5 to build and launch the command-line version in the VS Code debugger.

docs/builtins.md

@@ -0,0 +1,8 @@
+# Extending Builtins
+
+The Python interpreter implicitly adds a set of symbols that are available within every module even though they are not explicitly imported. These so-called “built in” symbols include commonly-used types and functions such as “list”, “dict”, “int”, “float”, “min”, and “len”.
+
+Pyright gains knowledge of which types are included in “builtins” scope through the type stub file `builtins.pyi`. This stub file comes from the typeshed github repo and is bundled with pyright, along with type stubs that describe other stdlib modules.
+
+Some Python environments are customized to include additional builtins symbols. If you are using such an environment, you may want to tell Pyright about these additional symbols that are available at runtime. To do so, you can add a local type stub file called `__builtins__.pyi`. This file can be placed at the root of your project directory or at the root of the subdirectory specified in the `stubPath` setting (which is named `typings` by default).
+

docs/ci-integration.md

@@ -13,7 +13,8 @@ You can configure pyright to run as a git hook (e.g. prior to each check-in) by
         language: node
         pass_filenames: false
         types: [python]
-        additional_dependencies: ['[email protected]']
+        # Replace the version below with the latest pyright version
+        additional_dependencies: ['[email protected]']
 ```
 
 ### Running Pyright from a CI script

docs/command-line.md

@@ -15,12 +15,14 @@ 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          |
 | --pythonplatform `<PLATFORM>`           | Analyze for platform (Darwin, Linux, Windows)        |
 | --pythonversion `<VERSION>`             | Analyze for version (3.3, 3.4, etc.)                 |
+| --skipunannotated                       | Skip type analysis of unannotated functions?         |
 | --stats                                 | Print detailed performance stats                     |
 | -t, --typeshed-path `<DIRECTORY>`       | Use typeshed type stubs at this location (2)         |
 | -v, --venv-path `<DIRECTORY>`           | Directory that contains virtual environments (3)     |
 | --verbose                               | Emit verbose diagnostics                             |
 | --verifytypes `<IMPORT>`                | Verify completeness of types in py.typed package     |
 | --version                               | Print pyright version                                |
+| --warnings                              | Use exit code of 1 if warnings are reported          |
 | -w, --watch                             | Continue to run and watch for changes (4)            |
 
 (1) If specific files are specified on the command line, the pyrightconfig.json file is ignored.
@@ -61,7 +63,7 @@ If the “--outputjson” option is specified on the command line, diagnostics a
 }
 ```
 
-Each Diagnostic is formatted output in the following format:
+Each Diagnostic is output in the following format:
 
 ```javascript
 {
@@ -83,3 +85,5 @@ Each Diagnostic is formatted output in the following format:
 ```
 
 Diagnostic line and character numbers are zero-based.
+
+Not all diagnostics have an associated diagnostic rule. Diagnostic rules are used only for diagnostics that can be disabled or enabled. If a rule is associated with the diagnostic, it is included in the output. If it’s not, the rule field is omitted from the JSON output.

docs/comments.md

@@ -12,13 +12,19 @@ self._target = 3 # type: Union[int, str]
 ```
 
 ## File-level Type Controls
-Strict typing controls (where all supported type-checking switches generate errors) can be enabled for a file through the use of a special comment. Typically this comment is placed at or near the top of a code file on its own line.
+Strict type checking, where most supported type-checking switches generate errors, can be enabled for a file through the use of a special comment. Typically this comment is placed at or near the top of a code file on its own line.
 
 ```python
 # pyright: strict
 ```
 
-Individual configuration settings can also be overridden on a per-file basis and combined with “strict” typing. For example, if you want to enable all type checks except for “reportPrivateUsage”, you could add the following comment:
+Likewise, basic type checking can be enabled for a file.
+
+```python
+# pyright: basic
+```
+
+Individual configuration settings can also be overridden on a per-file basis and optionally combined with “strict” or “basic” type checking. For example, if you want to enable all type checks except for “reportPrivateUsage”, you could add the following comment:
 
 ```python
 # pyright: strict, reportPrivateUsage=false