add basedpyright.analysis.useTypingExtensions setting so that users don't accidentally make their project depend on typing_extensions

Author: DetachHead

docs/benefits-over-pyright/language-server-improvements.md

@@ -8,6 +8,19 @@ autocomplete suggestions for method overrides will automatically add the `@overr
 
 ![](./override-decorator-completions.gif)
 
+!!! info "for users targeting python <=3.11"
+
+    since the `@typing.override` decorator was introduced in python 3.12, this functionality is only enabled if either:
+
+    -   you are targeting python 3.12 or above (see [`pythonVersion`](../configuration/config-files.md/#environment-options))
+    -   you have enabled [`basedpyright.analysis.useTypingExtensions`](../configuration/language-server-settings.md#based-settings)
+
+!!! warning "important information for library developers"
+
+    using `typing_extensions` creates a runtime dependency on the [`typing_extensions`](https://pypi.org/project/typing-extensions/) pypi package, so you must declare it as a project dependency. this is why `basedpyright.analysis.useTypingExtensions` is disabled by default to prevent users from unknowingly adding a new dependency to their project.
+
+    such mistakes often go undetected until your package is released and causes a runtime error for your users because the module may be available in dev dependencies but not production dependencies. (we recommend using [tach](https://docs.gauge.sh/usage/commands#tach-check-external) to detect issues like these)
+
 ## improved diagnostic severity system
 
 in pyright, certain diagnostics such as unreachable and unused code are always reported as a hint and cannot be disabled even when the associated diagnostic rule is disabled (and in the case of unreachable code, [there is no diagnostic rule at all](./new-diagnostic-rules.md#reportunreachable)).

docs/configuration/language-server-settings.md

@@ -55,6 +55,8 @@ the following settings are exclusive to basedpyright
 
 ![](inlayHints.genericTypes.png)
 
+**basedpyright.analysis.useTypingExtensions** [boolean]: Whether to rely on imports from the `typing_extensions` module when targeting older versions of python that do not include certain typing features such as the `@override` decorator. Defaults to `false`. [more info](../benefits-over-pyright/language-server-improvements.md#autocomplete-improvements)
+
 ### discouraged settings
 
 these options can also be configured [using a config file](./config-files.md). it's recommended to use either a `pyproject.toml` or `pyrightconfig.json` file instead of the language server to configure type checking for the following reasons:

packages/pyright-internal/src/common/languageServerInterface.ts

@@ -50,6 +50,7 @@ export interface ServerSettings {
     taskListTokens?: TaskListToken[];
     functionSignatureDisplay?: SignatureDisplayType | undefined;
     inlayHints?: InlayHintSettings;
+    useTypingExtensions?: boolean;
 }
 
 export interface MessageAction {

packages/pyright-internal/src/languageServerBase.ts

@@ -371,6 +371,7 @@ export abstract class LanguageServerBase implements LanguageServerInterface, Dis
             workspace.disableTaggedHints = !!serverSettings.disableTaggedHints;
             workspace.disableOrganizeImports = !!serverSettings.disableOrganizeImports;
             workspace.inlayHints = serverSettings.inlayHints;
+            workspace.useTypingExtensions = serverSettings.useTypingExtensions ?? false;
         } finally {
             // Don't use workspace.isInitialized directly since it might have been
             // reset due to pending config change event.
@@ -970,6 +971,7 @@ export abstract class LanguageServerBase implements LanguageServerInterface, Dis
                     lazyEdit: false,
                     triggerCharacter: params?.context?.triggerCharacter,
                     checkDeprecatedWhenResolving: this.client.completionItemResolveSupportsTags,
+                    useTypingExtensions: workspace.useTypingExtensions,
                 },
                 token,
                 false
@@ -1001,6 +1003,7 @@ export abstract class LanguageServerBase implements LanguageServerInterface, Dis
                         snippet: this.client.completionSupportsSnippet,
                         lazyEdit: false,
                         checkDeprecatedWhenResolving: this.client.completionItemResolveSupportsTags,
+                        useTypingExtensions: workspace.useTypingExtensions,
                     },
                     token,
                     false

packages/pyright-internal/src/languageService/codeActionProvider.ts

@@ -81,6 +81,7 @@ export class CodeActionProvider {
                     // we don't care about deprecations here so make sure they don't get evaluated unnecessarily
                     // (we don't call resolveCompletionItem)
                     checkDeprecatedWhenResolving: true,
+                    useTypingExtensions: workspace.useTypingExtensions,
                 },
                 token,
                 true

packages/pyright-internal/src/languageService/completionProvider.ts

@@ -252,6 +252,7 @@ export interface CompletionOptions {
     readonly lazyEdit: boolean;
     readonly triggerCharacter?: string;
     readonly checkDeprecatedWhenResolving: boolean;
+    readonly useTypingExtensions: boolean;
 }
 
 interface RecentCompletionInfo {
@@ -518,17 +519,9 @@ export class CompletionProvider {
                             // this should always be true, but just in case
                             overrideDecorator?.category === TypeCategory.Function &&
                             // if targeting a python version that doesn't have typing.override, we don't want to insert the decorator unless
-                            // the user has actually installed the typing_extensions package
+                            // the user has explicitly enabled `basedpyright.analysis.useTypingExtensions`
                             (overrideDecorator.shared.moduleName !== 'typing_extensions' ||
-                                !!this.importResolver.resolveImport(
-                                    this.fileUri,
-                                    this.configOptions.findExecEnvironment(this.fileUri),
-                                    {
-                                        leadingDots: 0,
-                                        nameParts: ['typing_extensions'],
-                                        importedSymbols: undefined,
-                                    }
-                                ).nonStubImportResult?.resolvedUris.length) &&
+                                this.options.useTypingExtensions) &&
                             // check if the override decorator is already here
                             !decorators?.some((decorator) => {
                                 const type = this.evaluator.getTypeOfExpression(decorator.d.expr).type;

packages/pyright-internal/src/realLanguageServer.ts

@@ -117,6 +117,7 @@ export abstract class RealLanguageServer extends LanguageServerBase {
                 variableTypes: true,
                 genericTypes: false,
             },
+            useTypingExtensions: false,
         };
 
         try {
@@ -209,6 +210,9 @@ export abstract class RealLanguageServer extends LanguageServerBase {
                 if (inlayHintSection) {
                     serverSettings.inlayHints = { ...serverSettings.inlayHints, ...inlayHintSection };
                 }
+                if (pythonAnalysisSection.useTypingExtensions) {
+                    serverSettings.useTypingExtensions = pythonAnalysisSection.useTypingExtensions;
+                }
             } else {
                 serverSettings.autoSearchPaths = true;
             }

packages/pyright-internal/src/tests/chainedSourceFiles.test.ts

@@ -58,6 +58,7 @@ test('check chained files', () => {
             lazyEdit: false,
             snippet: false,
             checkDeprecatedWhenResolving: false,
+            useTypingExtensions: true,
         },
         CancellationToken.None,
         false
@@ -107,6 +108,7 @@ test('modify chained files', () => {
             lazyEdit: false,
             snippet: false,
             checkDeprecatedWhenResolving: false,
+            useTypingExtensions: true,
         },
         CancellationToken.None,
         false

packages/pyright-internal/src/workspaceFactory.ts

@@ -99,6 +99,7 @@ export interface Workspace extends WorkspaceFolder {
     isInitialized: InitStatus;
     searchPathsToWatch: Uri[];
     inlayHints?: InlayHintSettings | undefined;
+    useTypingExtensions: boolean;
 }
 
 export interface NormalWorkspace extends Workspace {
@@ -286,6 +287,7 @@ export class WorkspaceFactory {
             disableWorkspaceSymbol: false,
             isInitialized: createInitStatus(),
             searchPathsToWatch: [],
+            useTypingExtensions: false,
         };
 
         // Stick in our map

packages/vscode-pyright/package.json

@@ -1866,6 +1866,12 @@
                     "default": false,
                     "description": "Whether to show inlay hints on inferred generic types.",
                     "scope": "resource"
+                },
+                "basedpyright.analysis.useTypingExtensions": {
+                    "type": "boolean",
+                    "default": false,
+                    "markdownDescription": "Whether to rely on imports from the `typing_extensions` module when targeting older versions of python that do not include certain typing features such as the `@override` decorator.",
+                    "scope": "resource"
                 }
             }
         },