@zzzen/pyright-internal 1.1.254 → 1.1.255

package/src/analyzer/staticExpressions.ts

@@ -0,0 +1,308 @@
+/*
+ * staticExpressions.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ * Author: Eric Traut
+ *
+ * Collection of static methods that operate on expressions
+ * (parse node trees).
+ */
+
+import { ExecutionEnvironment, PythonPlatform } from '../common/configOptions';
+import { ArgumentCategory, ExpressionNode, NameNode, NumberNode, ParseNodeType, TupleNode } from '../parser/parseNodes';
+import { KeywordType, OperatorType } from '../parser/tokenizerTypes';
+
+// Returns undefined if the expression cannot be evaluated
+// statically as a bool value or true/false if it can.
+export function evaluateStaticBoolExpression(
+    node: ExpressionNode,
+    execEnv: ExecutionEnvironment,
+    definedConstants: Map<string, boolean | string>,
+    typingImportAliases?: string[],
+    sysImportAliases?: string[]
+): boolean | undefined {
+    if (node.nodeType === ParseNodeType.AssignmentExpression) {
+        return evaluateStaticBoolExpression(
+            node.rightExpression,
+            execEnv,
+            definedConstants,
+            typingImportAliases,
+            sysImportAliases
+        );
+    }
+
+    if (node.nodeType === ParseNodeType.UnaryOperation) {
+        if (node.operator === OperatorType.Not) {
+            const value = evaluateStaticBoolLikeExpression(
+                node.expression,
+                execEnv,
+                definedConstants,
+                typingImportAliases,
+                sysImportAliases
+            );
+            if (value !== undefined) {
+                return !value;
+            }
+        }
+    } else if (node.nodeType === ParseNodeType.BinaryOperation) {
+        // Is it an OR or AND expression?
+        if (node.operator === OperatorType.Or || node.operator === OperatorType.And) {
+            const leftValue = evaluateStaticBoolExpression(
+                node.leftExpression,
+                execEnv,
+                definedConstants,
+                typingImportAliases,
+                sysImportAliases
+            );
+            const rightValue = evaluateStaticBoolExpression(
+                node.rightExpression,
+                execEnv,
+                definedConstants,
+                typingImportAliases,
+                sysImportAliases
+            );
+
+            if (leftValue === undefined || rightValue === undefined) {
+                return undefined;
+            }
+
+            if (node.operator === OperatorType.Or) {
+                return leftValue || rightValue;
+            } else {
+                return leftValue && rightValue;
+            }
+        }
+
+        if (
+            _isSysVersionInfoExpression(node.leftExpression, sysImportAliases) &&
+            node.rightExpression.nodeType === ParseNodeType.Tuple
+        ) {
+            // Handle the special case of "sys.version_info >= (3, x)"
+            const comparisonVersion = _convertTupleToVersion(node.rightExpression);
+            return _evaluateNumericBinaryOperation(node.operator, execEnv.pythonVersion, comparisonVersion);
+        } else if (
+            node.leftExpression.nodeType === ParseNodeType.Index &&
+            _isSysVersionInfoExpression(node.leftExpression.baseExpression, sysImportAliases) &&
+            node.leftExpression.items.length === 1 &&
+            !node.leftExpression.trailingComma &&
+            !node.leftExpression.items[0].name &&
+            node.leftExpression.items[0].argumentCategory === ArgumentCategory.Simple &&
+            node.leftExpression.items[0].valueExpression.nodeType === ParseNodeType.Number &&
+            !node.leftExpression.items[0].valueExpression.isImaginary &&
+            node.leftExpression.items[0].valueExpression.value === 0 &&
+            node.rightExpression.nodeType === ParseNodeType.Number
+        ) {
+            // Handle the special case of "sys.version_info[0] >= X"
+            return _evaluateNumericBinaryOperation(
+                node.operator,
+                Math.floor(execEnv.pythonVersion / 256),
+                node.rightExpression.value
+            );
+        } else if (
+            _isSysPlatformInfoExpression(node.leftExpression, sysImportAliases) &&
+            node.rightExpression.nodeType === ParseNodeType.StringList
+        ) {
+            // Handle the special case of "sys.platform != 'X'"
+            const comparisonPlatform = node.rightExpression.strings.map((s) => s.value).join('');
+            const expectedPlatformName = _getExpectedPlatformNameFromPlatform(execEnv);
+            return _evaluateStringBinaryOperation(node.operator, expectedPlatformName, comparisonPlatform);
+        } else if (
+            _isOsNameInfoExpression(node.leftExpression) &&
+            node.rightExpression.nodeType === ParseNodeType.StringList
+        ) {
+            // Handle the special case of "os.name == 'X'"
+            const comparisonOsName = node.rightExpression.strings.map((s) => s.value).join('');
+            const expectedOsName = _getExpectedOsNameFromPlatform(execEnv);
+            if (expectedOsName !== undefined) {
+                return _evaluateStringBinaryOperation(node.operator, expectedOsName, comparisonOsName);
+            }
+        } else {
+            // Handle the special case of <definedConstant> == 'X' or <definedConstant> != 'X'.
+            if (
+                node.leftExpression.nodeType === ParseNodeType.Name &&
+                node.rightExpression.nodeType === ParseNodeType.StringList
+            ) {
+                const constantValue = definedConstants.get(node.leftExpression.value);
+                if (constantValue !== undefined && typeof constantValue === 'string') {
+                    const comparisonStringName = node.rightExpression.strings.map((s) => s.value).join('');
+                    return _evaluateStringBinaryOperation(node.operator, constantValue, comparisonStringName);
+                }
+            }
+        }
+    } else if (node.nodeType === ParseNodeType.Constant) {
+        if (node.constType === KeywordType.True) {
+            return true;
+        } else if (node.constType === KeywordType.False) {
+            return false;
+        }
+    } else if (node.nodeType === ParseNodeType.Name) {
+        if (node.value === 'TYPE_CHECKING') {
+            return true;
+        }
+
+        const constant = definedConstants.get(node.value);
+        if (constant !== undefined) {
+            return !!constant;
+        }
+    } else if (
+        typingImportAliases &&
+        node.nodeType === ParseNodeType.MemberAccess &&
+        node.memberName.value === 'TYPE_CHECKING' &&
+        node.leftExpression.nodeType === ParseNodeType.Name &&
+        typingImportAliases.some((alias) => alias === (node.leftExpression as NameNode).value)
+    ) {
+        return true;
+    }
+
+    return undefined;
+}
+
+// Similar to evaluateStaticBoolExpression except that it handles
+// other non-bool values that are statically falsy or truthy
+// (like "None").
+export function evaluateStaticBoolLikeExpression(
+    node: ExpressionNode,
+    execEnv: ExecutionEnvironment,
+    definedConstants: Map<string, boolean | string>,
+    typingImportAliases?: string[],
+    sysImportAliases?: string[]
+): boolean | undefined {
+    if (node.nodeType === ParseNodeType.Constant) {
+        if (node.constType === KeywordType.None) {
+            return false;
+        }
+    }
+
+    return evaluateStaticBoolExpression(node, execEnv, definedConstants, typingImportAliases, sysImportAliases);
+}
+
+function _convertTupleToVersion(node: TupleNode): number | undefined {
+    let comparisonVersion: number | undefined;
+    // Ignore patch versions.
+    if (node.expressions.length >= 2) {
+        if (
+            node.expressions[0].nodeType === ParseNodeType.Number &&
+            !node.expressions[0].isImaginary &&
+            node.expressions[1].nodeType === ParseNodeType.Number &&
+            !node.expressions[1].isImaginary
+        ) {
+            const majorVersion = node.expressions[0];
+            const minorVersion = node.expressions[1];
+            if (typeof majorVersion.value === 'number' && typeof minorVersion.value === 'number') {
+                comparisonVersion = majorVersion.value * 256 + minorVersion.value;
+            }
+        }
+    } else if (node.expressions.length === 1) {
+        const majorVersion = node.expressions[0] as NumberNode;
+        if (typeof majorVersion.value === 'number') {
+            comparisonVersion = majorVersion.value * 256;
+        }
+    }
+
+    return comparisonVersion;
+}
+
+function _evaluateNumericBinaryOperation(
+    operatorType: OperatorType,
+    leftValue: number | bigint | undefined,
+    rightValue: number | bigint | undefined
+): any | undefined {
+    if (leftValue !== undefined && rightValue !== undefined) {
+        leftValue = BigInt(leftValue);
+        rightValue = BigInt(rightValue);
+
+        if (operatorType === OperatorType.LessThan) {
+            return leftValue < rightValue;
+        } else if (operatorType === OperatorType.LessThanOrEqual) {
+            return leftValue <= rightValue;
+        } else if (operatorType === OperatorType.GreaterThan) {
+            return leftValue > rightValue;
+        } else if (operatorType === OperatorType.GreaterThanOrEqual) {
+            return leftValue >= rightValue;
+        } else if (operatorType === OperatorType.Equals) {
+            return leftValue === rightValue;
+        } else if (operatorType === OperatorType.NotEquals) {
+            return leftValue !== rightValue;
+        }
+    }
+
+    return undefined;
+}
+
+function _evaluateStringBinaryOperation(
+    operatorType: OperatorType,
+    leftValue: string | undefined,
+    rightValue: string | undefined
+): any | undefined {
+    if (leftValue !== undefined && rightValue !== undefined) {
+        if (operatorType === OperatorType.Equals) {
+            return leftValue === rightValue;
+        } else if (operatorType === OperatorType.NotEquals) {
+            return leftValue !== rightValue;
+        }
+    }
+
+    return undefined;
+}
+
+function _isSysVersionInfoExpression(node: ExpressionNode, sysImportAliases: string[] = ['sys']): boolean {
+    if (node.nodeType === ParseNodeType.MemberAccess) {
+        if (node.leftExpression.nodeType === ParseNodeType.Name && node.memberName.value === 'version_info') {
+            if (sysImportAliases.some((alias) => alias === (node.leftExpression as NameNode).value)) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+function _isSysPlatformInfoExpression(node: ExpressionNode, sysImportAliases: string[] = ['sys']): boolean {
+    if (node.nodeType === ParseNodeType.MemberAccess) {
+        if (node.leftExpression.nodeType === ParseNodeType.Name && node.memberName.value === 'platform') {
+            if (sysImportAliases.some((alias) => alias === (node.leftExpression as NameNode).value)) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+function _isOsNameInfoExpression(node: ExpressionNode): boolean {
+    if (node.nodeType === ParseNodeType.MemberAccess) {
+        if (
+            node.leftExpression.nodeType === ParseNodeType.Name &&
+            node.leftExpression.value === 'os' &&
+            node.memberName.value === 'name'
+        ) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+function _getExpectedPlatformNameFromPlatform(execEnv: ExecutionEnvironment): string | undefined {
+    if (execEnv.pythonPlatform === PythonPlatform.Darwin) {
+        return 'darwin';
+    } else if (execEnv.pythonPlatform === PythonPlatform.Windows) {
+        return 'win32';
+    } else if (execEnv.pythonPlatform === PythonPlatform.Linux) {
+        return 'linux';
+    }
+
+    return undefined;
+}
+
+function _getExpectedOsNameFromPlatform(execEnv: ExecutionEnvironment): string | undefined {
+    if (execEnv.pythonPlatform === PythonPlatform.Darwin) {
+        return 'posix';
+    } else if (execEnv.pythonPlatform === PythonPlatform.Windows) {
+        return 'nt';
+    } else if (execEnv.pythonPlatform === PythonPlatform.Linux) {
+        return 'posix';
+    }
+
+    return undefined;
+}

package/src/analyzer/symbol.ts

@@ -0,0 +1,249 @@
+/*
+ * symbol.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ * Author: Eric Traut
+ *
+ * Represents an association between a name and the type
+ * (or multiple types) that the symbol is associated with
+ * in the program.
+ */
+
+import { Declaration, DeclarationType } from './declaration';
+import { areDeclarationsSame, hasTypeForDeclaration } from './declarationUtils';
+import { Type } from './types';
+
+export const enum SymbolFlags {
+    None = 0,
+
+    // Indicates that the symbol is unbound at the start of
+    // execution. Some symbols are initialized by the module
+    // loader, so they are bound even before the first statement
+    // in the module is executed.
+    InitiallyUnbound = 1 << 0,
+
+    // Indicates that the symbol is not visible from other files.
+    // Used for module-level symbols.
+    ExternallyHidden = 1 << 1,
+
+    // Indicates that the symbol is a class member of a class.
+    ClassMember = 1 << 2,
+
+    // Indicates that the symbol is an instance member of a class.
+    InstanceMember = 1 << 3,
+
+    // Indicates that the symbol is considered "private" to the
+    // class or module and should not be accessed outside or overridden.
+    PrivateMember = 1 << 5,
+
+    // Indicates that the symbol is not considered for protocol
+    // matching. This applies to some built-in symbols like __class__.
+    IgnoredForProtocolMatch = 1 << 6,
+
+    // Indicates that the symbol is a ClassVar, so it cannot be
+    // set when accessed through a class instance.
+    ClassVar = 1 << 7,
+
+    // Indicates that the symbol is in __all__.
+    InDunderAll = 1 << 8,
+
+    // Indicates that the symbol is a private import in a py.typed module.
+    PrivatePyTypedImport = 1 << 9,
+
+    // Indicates that the symbol is an InitVar as specified in PEP 557.
+    InitVar = 1 << 10,
+}
+
+let nextSymbolId = 1;
+function getUniqueSymbolId() {
+    return nextSymbolId++;
+}
+
+// Symbol ID that indicates that there is no specific symbol.
+export const indeterminateSymbolId = 0;
+
+export class Symbol {
+    // Information about the node that declared the value -
+    // i.e. where the editor will take the user if "show definition"
+    // is selected. Multiple declarations can exist for variables,
+    // properties, and functions (in the case of @overload).
+    private _declarations?: Declaration[];
+
+    // Flags that provide information about the symbol.
+    private _flags: SymbolFlags;
+
+    // Unique numeric ID for each symbol allocated.
+    readonly id: number;
+
+    // Symbols that are completely synthesized (i.e. have no
+    // corresponding declarations in the program) can have
+    // a specified type.
+    private _synthesizedType?: Type;
+
+    constructor(flags: SymbolFlags) {
+        this.id = getUniqueSymbolId();
+        this._flags = flags;
+    }
+
+    static createWithType(flags: SymbolFlags, type: Type) {
+        const newSymbol = new Symbol(flags);
+        newSymbol._synthesizedType = type;
+        return newSymbol;
+    }
+
+    isInitiallyUnbound() {
+        return !!(this._flags & SymbolFlags.InitiallyUnbound);
+    }
+
+    setIsExternallyHidden() {
+        this._flags |= SymbolFlags.ExternallyHidden;
+    }
+
+    isExternallyHidden() {
+        return !!(this._flags & SymbolFlags.ExternallyHidden);
+    }
+
+    setIsIgnoredForProtocolMatch() {
+        this._flags |= SymbolFlags.IgnoredForProtocolMatch;
+    }
+
+    isIgnoredForProtocolMatch() {
+        return !!(this._flags & SymbolFlags.IgnoredForProtocolMatch);
+    }
+
+    setIsClassMember() {
+        this._flags |= SymbolFlags.ClassMember;
+    }
+
+    isClassMember() {
+        return !!(this._flags & SymbolFlags.ClassMember);
+    }
+
+    setIsInstanceMember() {
+        this._flags |= SymbolFlags.InstanceMember;
+    }
+
+    isInstanceMember() {
+        return !!(this._flags & SymbolFlags.InstanceMember);
+    }
+
+    setIsClassVar() {
+        this._flags |= SymbolFlags.ClassVar;
+    }
+
+    isClassVar() {
+        return !!(this._flags & SymbolFlags.ClassVar);
+    }
+
+    setIsInitVar() {
+        this._flags |= SymbolFlags.InitVar;
+    }
+
+    isInitVar() {
+        return !!(this._flags & SymbolFlags.InitVar);
+    }
+
+    setIsInDunderAll() {
+        this._flags |= SymbolFlags.InDunderAll;
+    }
+
+    isInDunderAll() {
+        return !!(this._flags & SymbolFlags.InDunderAll);
+    }
+
+    setIsPrivateMember() {
+        this._flags |= SymbolFlags.PrivateMember;
+    }
+
+    isPrivateMember() {
+        return !!(this._flags & SymbolFlags.PrivateMember);
+    }
+
+    setPrivatePyTypedImport() {
+        this._flags |= SymbolFlags.PrivatePyTypedImport;
+    }
+
+    isPrivatePyTypedImport() {
+        return !!(this._flags & SymbolFlags.PrivatePyTypedImport);
+    }
+
+    addDeclaration(declaration: Declaration) {
+        if (this._declarations) {
+            // See if this node was already identified as a declaration. If so,
+            // replace it. Otherwise, add it as a new declaration to the end of
+            // the list.
+            const declIndex = this._declarations.findIndex((decl) => areDeclarationsSame(decl, declaration));
+            if (declIndex < 0) {
+                this._declarations.push(declaration);
+
+                // If there is more than one declaration for a symbol, we will
+                // assume it is not a type alias.
+                this._declarations.forEach((decl) => {
+                    if (decl.type === DeclarationType.Variable && decl.typeAliasName) {
+                        delete decl.typeAliasName;
+                    }
+                });
+            } else {
+                // If the new declaration has a defined type, it should replace
+                // the existing one.
+                const curDecl = this._declarations[declIndex];
+                if (hasTypeForDeclaration(declaration)) {
+                    this._declarations[declIndex] = declaration;
+                    if (curDecl.type === DeclarationType.Variable && declaration.type === DeclarationType.Variable) {
+                        if (!declaration.inferredTypeSource && curDecl.inferredTypeSource) {
+                            declaration.inferredTypeSource = curDecl.inferredTypeSource;
+                        }
+                    }
+                } else if (declaration.type === DeclarationType.Variable) {
+                    // If it's marked "final" or "type alias", this should be reflected
+                    // in the existing declaration. Likewise, if the existing declaration
+                    // doesn't have a type source, add it.
+                    if (curDecl.type === DeclarationType.Variable) {
+                        if (declaration.isFinal) {
+                            curDecl.isFinal = true;
+                        }
+
+                        if (declaration.typeAliasAnnotation) {
+                            curDecl.typeAliasAnnotation = declaration.typeAliasAnnotation;
+                            curDecl.typeAliasName = declaration.typeAliasName;
+                        }
+
+                        if (!curDecl.inferredTypeSource && declaration.inferredTypeSource) {
+                            curDecl.inferredTypeSource = declaration.inferredTypeSource;
+                        }
+                    }
+                }
+            }
+        } else {
+            this._declarations = [declaration];
+        }
+    }
+
+    hasDeclarations() {
+        return this._declarations ? this._declarations.length > 0 : false;
+    }
+
+    getDeclarations() {
+        return this._declarations ? this._declarations : [];
+    }
+
+    hasTypedDeclarations() {
+        // We'll treat an synthesized type as an implicit declaration.
+        if (this._synthesizedType) {
+            return true;
+        }
+
+        return this.getDeclarations().some((decl) => hasTypeForDeclaration(decl));
+    }
+
+    getTypedDeclarations() {
+        return this.getDeclarations().filter((decl) => hasTypeForDeclaration(decl));
+    }
+
+    getSynthesizedType() {
+        return this._synthesizedType;
+    }
+}
+
+// Maps names to symbol information.
+export type SymbolTable = Map<string, Symbol>;

package/src/analyzer/symbolNameUtils.ts

@@ -0,0 +1,50 @@
+/*
+ * symbolNameUtils.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ * Author: Eric Traut
+ *
+ * Static methods that apply to symbols or symbol names.
+ */
+
+const _constantRegEx = /^[A-Z0-9_]+$/;
+const _underscoreOnlyRegEx = /^[_]+$/;
+const _camelCaseRegEx = /^_{0,2}[A-Z][A-Za-z0-9_]+$/;
+
+// Private symbol names start with a double underscore.
+export function isPrivateName(name: string) {
+    return name.length > 2 && name.startsWith('__') && !name.endsWith('__');
+}
+
+// Protected symbol names start with a single underscore.
+export function isProtectedName(name: string) {
+    return name.length > 1 && name.startsWith('_') && !name.startsWith('__');
+}
+
+export function isPrivateOrProtectedName(name: string) {
+    return isPrivateName(name) || isProtectedName(name);
+}
+
+// "Dunder" names start and end with two underscores.
+export function isDunderName(name: string) {
+    return name.length > 4 && name.startsWith('__') && name.endsWith('__');
+}
+
+// "Single Dunder" names start and end with single underscores.
+export function isSingleDunderName(name: string) {
+    return name.length > 2 && name.startsWith('_') && name.endsWith('_');
+}
+
+// Constants are all-caps with possible numbers and underscores.
+export function isConstantName(name: string) {
+    return !!name.match(_constantRegEx) && !name.match(_underscoreOnlyRegEx);
+}
+
+// Type aliases are CamelCase with possible numbers and underscores.
+export function isTypeAliasName(name: string) {
+    return !!name.match(_camelCaseRegEx);
+}
+
+export function isPublicConstantOrTypeAlias(name: string) {
+    return !isPrivateOrProtectedName(name) && (isConstantName(name) || isTypeAliasName(name));
+}

package/src/analyzer/symbolUtils.ts

@@ -0,0 +1,49 @@
+/*
+ * symbolUtils.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ * Author: Eric Traut
+ *
+ * Collection of functions that operate on Symbol objects.
+ */
+
+import { Declaration, DeclarationType } from './declaration';
+import { isFinalVariableDeclaration } from './declarationUtils';
+import { Symbol } from './symbol';
+
+export function getLastTypedDeclaredForSymbol(symbol: Symbol): Declaration | undefined {
+    const typedDecls = symbol.getTypedDeclarations();
+
+    if (typedDecls.length > 0) {
+        return typedDecls[typedDecls.length - 1];
+    }
+
+    return undefined;
+}
+
+// Within TypedDict classes, member variables are not accessible as
+// normal attributes. Instead, they are accessed through index operations.
+export function isTypedDictMemberAccessedThroughIndex(symbol: Symbol): boolean {
+    const typedDecls = symbol.getTypedDeclarations();
+
+    if (typedDecls.length > 0) {
+        const lastDecl = typedDecls[typedDecls.length - 1];
+        if (lastDecl.type === DeclarationType.Variable) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+export function isFinalVariable(symbol: Symbol): boolean {
+    return symbol.getDeclarations().some((decl) => isFinalVariableDeclaration(decl));
+}
+
+export function isRequiredTypedDictVariable(symbol: Symbol) {
+    return symbol.getDeclarations().some((decl) => decl.type === DeclarationType.Variable && !!decl.isRequired);
+}
+
+export function isNotRequiredTypedDictVariable(symbol: Symbol) {
+    return symbol.getDeclarations().some((decl) => decl.type === DeclarationType.Variable && !!decl.isNotRequired);
+}