typeshed-client

Warnings

• breaking Support for Python 3.8 was dropped in version 2.8.0. Ensure your environment uses Python 3.9 or newer.
  Fix: Upgrade your Python interpreter to version 3.9 or a later supported version.
• breaking Support for Python 3.7 was dropped in version 2.5.0. Ensure your environment uses Python 3.8 or newer for versions <2.8.0, and Python 3.9+ for >=2.8.0.
  Fix: Upgrade your Python interpreter to version 3.8 or later.
• breaking In version 1.2.3, the library switched from `typed_ast` to the standard library `ast` module for parsing. This could affect code directly interacting with the parser's internal structure if `typed_ast` specific features were relied upon.
  Fix: Update any code that directly interacts with the AST parsing to use `ast` module compatible structures and features.
• deprecated The function `typeshed_client.finder.get_search_path()` was deprecated in version 2.5.0 as it is no longer useful.
  Fix: Avoid using `get_search_path()`. Instead, configure the `search_path` directly when creating a `SearchContext` if custom paths are needed.
• gotcha Versions 2.8.0 and later explicitly set encoding to UTF-8 to fix crashes on Windows in some cases. Prior versions might encounter encoding issues on Windows when reading stub files.
  Fix: Upgrade to `typeshed-client` version 2.8.0 or newer to benefit from improved encoding handling on Windows.
• gotcha Starting with version 2.8.0, the library searches for names and imports in `.py` files in addition to `.pyi` files. While generally beneficial for typed packages, this change in behavior might subtly alter resolution outcomes if you relied on `.py` files being ignored. The `SearchContext` now has an `allow_py_files` argument (defaulting to `False` for `get_stub_file` and `get_stub_ast` without explicit context) to control this.
  Fix: If you experience unexpected resolution, explicitly set `allow_py_files=False` in your `SearchContext` or review your stub package structure.

Install

• pip install typeshed-client Install latest version

Imports

• get_stub_file

  from typeshed_client import get_stub_file

• get_stub_ast

  from typeshed_client import get_stub_ast

• SearchContext

  from typeshed_client.finder import SearchContext

Quickstart

This quickstart demonstrates how to find a stub file for a given module, retrieve its Abstract Syntax Tree (AST), and how to customize the stub search behavior using a `SearchContext`. It shows fetching stubs for 'typing' and attempts for 'math'.

from typeshed_client import get_stub_file, get_stub_ast
from typeshed_client.finder import SearchContext

# Find the stub file for a standard library module (e.g., 'typing')
typing_stub_path = get_stub_file('typing')
if typing_stub_path:
    print(f"Found 'typing' stub at: {typing_stub_path}")

    # Get the Abstract Syntax Tree (AST) for the stub
    typing_stub_ast = get_stub_ast('typing')
    if typing_stub_ast:
        print(f"AST for 'typing' module (first 3 nodes): {typing_stub_ast.body[:3]}")

# Example of using a custom SearchContext (e.g., allowing .py files in search)
# Note: allow_py_files was added in v2.8.0/v2.8.1/v2.8.2
custom_context = SearchContext(allow_py_files=True)
math_stub_path = get_stub_file('math', search_context=custom_context)
if math_stub_path:
    print(f"Found 'math' stub (with custom context) at: {math_stub_path}")
else:
    print("Could not find 'math' stub (this is normal if it's not in typeshed).")