pyflow-analysis 0.1.0__py3-none-any.whl

pyflow/analysis/typeinfo/generic_binder.py

@@ -0,0 +1,145 @@
+"""Bind type variables in generic classes to concrete type arguments.
+
+When a generic class is instantiated with type arguments (e.g.
+``List[int]``, ``MyDict[str, int]``), this module binds each
+:class:`TypeVarType` in the class's parameter list to the
+corresponding concrete :class:`ProperType`.
+
+The binding logic is adapted from Jedi's
+``jedi.inference.gradual.base`` (https://github.com/davidhalter/jedi).
+
+SPDX-FileCopyrightText: 2025 David Halter and contributors
+SPDX-FileCopyrightText: 2026 PyFlow Contributors
+SPDX-License-Identifier: MIT
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from pyflow.analysis.typeinfo.gradual_typing import substitute_type_vars
+
+if TYPE_CHECKING:
+    from pyflow.analysis.typeinfo.typesystem import ProperType, TypeVarType
+
+
+# ---------------------------------------------------------------------------
+# Generic binding
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class GenericBinding:
+    """Holds the result of binding type variables to concrete types.
+
+    Attributes:
+        mapping: A dictionary mapping type-variable names to concrete types.
+        type_vars: The original type-variable list (in declaration order).
+    """
+
+    mapping: dict[str, ProperType] = field(default_factory=dict)
+    type_vars: list[TypeVarType] = field(default_factory=list)
+
+    def apply(self, type_: ProperType) -> ProperType:
+        """Substitute all bound type variables in *type_* with concrete types.
+
+        Args:
+            type_: A type that may contain type variables from this binding.
+
+        Returns:
+            A new type with type variables replaced.
+        """
+        return substitute_type_vars(type_, self.mapping)
+
+    def is_bound(self, tv_name: str) -> bool:
+        """Check whether a type variable has been bound."""
+        return tv_name in self.mapping
+
+    def __bool__(self) -> bool:
+        return bool(self.mapping)
+
+    def __repr__(self) -> str:
+        return f"GenericBinding({self.mapping})"
+
+
+def bind_generics(
+    type_vars: list[TypeVarType],
+    concrete_args: list[ProperType],
+) -> GenericBinding:
+    """Bind a list of type variables to concrete type arguments.
+
+    Matches type variables to arguments positionally.  If there are fewer
+    concrete arguments than type variables, the trailing type variables
+    remain unbound.  If there are more concrete arguments, extras are
+    ignored.
+
+    Args:
+        type_vars: The type-variable parameters (e.g. from ``class Foo(Generic[T, U])``).
+        concrete_args: The concrete type arguments (e.g. from ``Foo[int, str]``).
+
+    Returns:
+        A :class:`GenericBinding` with the resolved mapping.
+
+    Examples:
+        >>> T = TypeVarType("T")
+        >>> U = TypeVarType("U")
+        >>> ti = TypeInfo(int)
+        >>> binding = bind_generics([T, U], [Instance(ti), Instance(ti)])
+        >>> binding.mapping
+        {'T': Instance(TypeInfo(int)), 'U': Instance(TypeInfo(int))}
+    """
+    mapping: dict[str, ProperType] = {}
+
+    for tv, arg in zip(type_vars, concrete_args):
+        mapping[tv.name] = arg
+
+    return GenericBinding(mapping=mapping, type_vars=list(type_vars))
+
+
+def bind_generics_from_pairs(
+    pairs: list[tuple[TypeVarType, ProperType]],
+) -> GenericBinding:
+    """Create a :class:`GenericBinding` from explicit (type_var, concrete_type) pairs.
+
+    This is useful when type variables are matched by name rather than
+    position (e.g. when matching base-class generics).
+
+    Args:
+        pairs: A list of ``(TypeVarType, ProperType)`` tuples.
+
+    Returns:
+        A :class:`GenericBinding` with the resolved mapping.
+    """
+    mapping: dict[str, ProperType] = {}
+    type_vars: list[TypeVarType] = []
+
+    for tv, arg in pairs:
+        mapping[tv.name] = arg
+        if tv not in type_vars:
+            type_vars.append(tv)
+
+    return GenericBinding(mapping=mapping, type_vars=type_vars)
+
+
+def merge_bindings(*bindings: GenericBinding) -> GenericBinding:
+    """Merge multiple :class:`GenericBinding` objects into one.
+
+    Later bindings override earlier ones for the same type-variable name.
+
+    Args:
+        *bindings: Zero or more bindings to merge.
+
+    Returns:
+        A new :class:`GenericBinding` combining all mappings.
+    """
+    mapping: dict[str, ProperType] = {}
+    type_vars: list[TypeVarType] = []
+
+    for b in bindings:
+        mapping.update(b.mapping)
+        for tv in b.type_vars:
+            if tv not in type_vars:
+                type_vars.append(tv)
+
+    return GenericBinding(mapping=mapping, type_vars=type_vars)

pyflow/analysis/typeinfo/gradual_typing.py

@@ -0,0 +1,255 @@
+"""PEP 484 gradual typing utilities for the PyFlow type system.
+
+Provides type-alias resolution and type-variable substitution for working
+with ``typing`` module constructs like ``List[int]``, ``Dict[str, int]``,
+``Optional[str]``, ``Union[int, str]``, and user-defined generics.
+
+The type-alias tables are adapted from Jedi's
+``jedi.inference.gradual.typing``
+(https://github.com/davidhalter/jedi).
+
+SPDX-FileCopyrightText: 2025 David Halter and contributors
+SPDX-FileCopyrightText: 2026 PyFlow Contributors
+SPDX-License-Identifier: MIT
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyflow.analysis.typeinfo.typesystem import (
+        ProperType,
+        TypeVarType,
+    )
+
+# ---------------------------------------------------------------------------
+# Type alias tables — PEP 484 typing → builtins mappings
+# ---------------------------------------------------------------------------
+
+TYPE_ALIAS_TYPES: dict[str, str] = {
+    "List": "builtins.list",
+    "Dict": "builtins.dict",
+    "Set": "builtins.set",
+    "FrozenSet": "builtins.frozenset",
+    "ChainMap": "collections.ChainMap",
+    "Counter": "collections.Counter",
+    "DefaultDict": "collections.defaultdict",
+    "Deque": "collections.deque",
+}
+
+PROXY_CLASS_TYPES: set[str] = {"Tuple", "Generic", "Protocol", "Callable", "Type"}
+
+PROXY_TYPES: set[str] = {"Optional", "Union", "ClassVar", "Annotated", "Final"}
+
+IGNORE_ANNOTATION_PARTS: set[str] = {"ClassVar", "Annotated", "Final"}
+
+# ---------------------------------------------------------------------------
+# Type alias resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_type_alias(name: str) -> str | None:
+    """Resolve a ``typing`` module alias to its concrete builtin/collections type.
+
+    Args:
+        name: A type name from the ``typing`` module (e.g. ``"List"``).
+
+    Returns:
+        The fully-qualified concrete type name, or ``None`` if *name*
+        is not a known alias.
+
+    Examples:
+        >>> resolve_type_alias("List")
+        'builtins.list'
+        >>> resolve_type_alias("Dict")
+        'builtins.dict'
+        >>> resolve_type_alias("str")
+        None
+    """
+    return TYPE_ALIAS_TYPES.get(name)
+
+
+def is_proxy_class(name: str) -> bool:
+    """Check whether *name* is a typing proxy class (Tuple, Generic, etc.)."""
+    return name in PROXY_CLASS_TYPES
+
+
+def is_proxy_type(name: str) -> bool:
+    """Check whether *name* is a typing proxy value (Optional, Union, etc.)."""
+    return name in PROXY_TYPES
+
+
+def should_ignore_annotation_part(name: str) -> bool:
+    """Check whether an annotation part should be ignored (ClassVar, Final, etc.)."""
+    return name in IGNORE_ANNOTATION_PARTS
+
+
+# ---------------------------------------------------------------------------
+# Type variable substitution
+# ---------------------------------------------------------------------------
+
+
+def substitute_type_vars(
+    type_: ProperType,
+    substitutions: dict[str, ProperType],
+) -> ProperType:
+    """Substitute type variables in *type_* with concrete types.
+
+    Recursively walks the type structure, replacing any :class:`TypeVarType`
+    whose name appears in *substitutions*.
+
+    Args:
+        type_: The type (possibly containing type variables) to substitute into.
+        substitutions: A mapping from type-variable name to concrete type.
+
+    Returns:
+        A new type with type variables replaced.  If no substitutions apply,
+        the original *type_* is returned unchanged.
+    """
+    from pyflow.analysis.typeinfo.typesystem import (
+        Instance,
+        TupleType,
+        TypeVarType,
+        UnionType,
+    )
+
+    if isinstance(type_, TypeVarType):
+        return substitutions.get(type_.name, type_)
+
+    if isinstance(type_, Instance) and type_.args:
+        new_args = tuple(
+            substitute_type_vars(a, substitutions) for a in type_.args
+        )
+        if new_args != type_.args:
+            return Instance(type_.type, new_args)
+        return type_
+
+    if isinstance(type_, TupleType) and type_.args:
+        new_args = tuple(
+            substitute_type_vars(a, substitutions) for a in type_.args
+        )
+        if new_args != type_.args:
+            return TupleType(new_args, unknown_size=type_.unknown_size)
+        return type_
+
+    if isinstance(type_, UnionType):
+        new_items = tuple(
+            substitute_type_vars(i, substitutions) for i in type_.items
+        )
+        if new_items != type_.items:
+            return UnionType(new_items)
+        return type_
+
+    return type_
+
+
+def collect_type_vars(type_: ProperType) -> list[TypeVarType]:
+    """Collect all :class:`TypeVarType` instances contained in *type_*.
+
+    Args:
+        type_: The type to scan.
+
+    Returns:
+        A list of distinct type variables, in depth-first order.
+    """
+    from pyflow.analysis.typeinfo.typesystem import (
+        Instance,
+        TupleType,
+        TypeVarType,
+        UnionType,
+    )
+
+    result: list[TypeVarType] = []
+
+    def _collect(t: ProperType) -> None:
+        if isinstance(t, TypeVarType):
+            if t not in result:
+                result.append(t)
+            return
+        if isinstance(t, Instance) and t.args:
+            for a in t.args:
+                _collect(a)
+        elif isinstance(t, TupleType) and t.args:
+            for a in t.args:
+                _collect(a)
+        elif isinstance(t, UnionType):
+            for i in t.items:
+                _collect(i)
+
+    _collect(type_)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Type-comment parsing (PEP 484 ``# type:`` comments)
+# ---------------------------------------------------------------------------
+
+
+def split_comment_param_declaration(decl_text: str) -> list[str]:
+    """Split a ``# type: (int, str) -> bool`` parameter declaration.
+
+    Handles nested generic brackets (e.g. ``Dict[str, int]`` is treated as
+    a single parameter).
+
+    Args:
+        decl_text: The parameter declaration text from a type comment.
+
+    Returns:
+        A list of type-name strings, one per parameter.
+
+    Examples:
+        >>> split_comment_param_declaration("int, str")
+        ['int', 'str']
+        >>> split_comment_param_declaration("Dict[str, int], bool")
+        ['Dict[str, int]', 'bool']
+    """
+    params: list[str] = []
+    depth = 0
+    current: list[str] = []
+
+    for ch in decl_text:
+        if ch == "[":
+            depth += 1
+            current.append(ch)
+        elif ch == "]":
+            depth -= 1
+            current.append(ch)
+        elif ch == "," and depth == 0:
+            params.append("".join(current).strip())
+            current = []
+        else:
+            current.append(ch)
+
+    if current:
+        stripped = "".join(current).strip()
+        if stripped:
+            params.append(stripped)
+
+    return params
+
+
+def parse_type_comment(comment: str) -> tuple[list[str], str | None]:
+    """Parse a PEP 484 type comment into parameter types and return type.
+
+    Supports the format::
+
+        # type: (int, str) -> bool
+        # type: (int, str, Dict[str, int]) -> Optional[str]
+
+    Args:
+        comment: The full type-comment string (including ``# type:`` prefix).
+
+    Returns:
+        A tuple of ``(param_types, return_type)`` where *param_types*
+        is a list of type-name strings and *return_type* is a string
+        or ``None``.
+    """
+    match = re.match(r"^#\s*type:\s*\(([^#]*)\)\s*->\s*([^#]*)", comment)
+    if not match:
+        return [], None
+
+    params_text = match.group(1)
+    return_text = match.group(2).strip()
+    return split_comment_param_declaration(params_text), return_text or None

pyflow/analysis/typeinfo/models.py

@@ -0,0 +1,43 @@
+"""Small public models for lightweight type-information queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pyflow.analysis.typeinfo.typesystem import Instance, ProperType
+
+
+@dataclass(frozen=True)
+class TypeFact:
+    """A single type fact for a symbol or member."""
+
+    name: str
+    typ: ProperType | None
+    raw_annotation: str | None
+    source: str
+    kind: str
+
+
+@dataclass(frozen=True)
+class FunctionTypeInfo:
+    """Callable type information."""
+
+    name: str
+    params: dict[str, ProperType | None]
+    returns: ProperType | None
+    raw_params: dict[str, str | None]
+    raw_returns: str | None
+    source: str
+
+
+@dataclass(frozen=True)
+class ClassTypeInfo:
+    """Class type information."""
+
+    name: str
+    typ: Instance
+    bases: tuple[ProperType, ...] = ()
+    raw_bases: tuple[str, ...] = ()
+    members: dict[str, TypeFact] = field(default_factory=dict)
+    methods: dict[str, FunctionTypeInfo] = field(default_factory=dict)
+    source: str = "source"