Ctrl + k

or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/typeshed-client@2.8.x

docs

index.md
tile.json

tessl/pypi-typeshed-client

tessl install tessl/pypi-typeshed-client@2.8.4

A library for accessing stubs in typeshed.

index.mddocs/

Typeshed Client

A comprehensive Python library for retrieving and analyzing type stub information from typeshed (Python's repository of type stubs for the standard library and third-party packages) and PEP 561 stub packages. It enables developers to programmatically find stub file paths for specific modules, collect and parse names defined in stubs with their AST representations, and resolve fully qualified names to their definitions across multiple stub files.

Package Information

  • Package Name: typeshed_client
  • Package Type: pypi
  • Language: Python
  • Installation: pip install typeshed_client
  • Supported Python Versions: 3.9+
  • Thread Safety: Module-level functions are thread-safe; Resolver instances should not be shared across threads
  • Mutability: SearchContext is immutable (NamedTuple); Resolver maintains internal mutable caches

Core Imports

import typeshed_client

Common imports for finding stubs:

from typeshed_client import (
    get_stub_file,
    get_stub_ast,
    get_stub_names,
    get_search_context,
    SearchContext,
)

For name resolution:

from typeshed_client import Resolver

For working with parsed names:

from typeshed_client import (
    NameInfo,
    NameDict,
    ImportedName,
    OverloadedName,
)

Additional useful imports:

from typeshed_client import (
    ModulePath,
    PythonVersion,
    ResolvedName,
    ImportedInfo,
    Module,
)

For exception handling:

from typeshed_client.parser import InvalidStub

For advanced operations:

from typeshed_client.finder import (
    find_typeshed,
    parse_stub_file,
    safe_exists,
    safe_is_dir,
    safe_is_file,
)
from typeshed_client.parser import (
    parse_ast,
    get_import_star_names,
    get_dunder_all_from_info,
)

Quick Reference

Key Functions

FunctionPurposeReturns None?
get_stub_file(module_name)Find path to stub fileYes, if not found
get_stub_ast(module_name)Get parsed AST of stubYes, if not found
get_stub_names(module_name)Get all names in stubYes, if not found
get_search_context(...)Create configurationNever
Resolver()Create name resolverNever

Core Types

TypeDescription
SearchContextConfiguration for stub finding
NameDictdict[str, NameInfo] mapping names to info
NameInfoInformation about a name (AST, export status)
ImportedNameRepresents imported name
OverloadedNameFunction with multiple overloads
ResolvedNameUnion[ModulePath, ImportedInfo, NameInfo, None]

Basic Usage

from typeshed_client import get_stub_file, get_stub_names, Resolver

# Find the path to a module's stub file
stub_path = get_stub_file('typing')
if stub_path:
    print(f"Found: {stub_path}")

# Get all names defined in a module
names = get_stub_names('collections')
if names:
    exported = [name for name, info in names.items() if info.is_exported]
    print(f"Exported names: {exported[:5]}")

# Resolve a fully qualified name to its definition
resolver = Resolver()
result = resolver.get_fully_qualified_name('collections.OrderedDict')
if result:
    print(f"Resolved: {type(result).__name__}")

Architecture

The library consists of three main components:

  1. Finder Module: Locates stub files following PEP 561 resolution order

    • Searches typeshed, stub packages, and inline stubs
    • Supports version-specific and platform-specific stubs

  2. Parser Module: Parses stub ASTs into structured name dictionaries

    • Handles exports, imports, and overloads
    • Evaluates conditional definitions based on version/platform

  3. Resolver Module: Resolves names across module boundaries

    • Follows imports and re-exports
    • Maintains internal caches for performance

Core Capabilities

Finding Stub Files

Locate stub files for Python modules with support for typeshed, PEP 561 stub packages, and inline stubs.

def get_stub_file(module_name: str, *, search_context: Optional[SearchContext] = None) -> Optional[Path]: ...
def get_stub_ast(module_name: str, *, search_context: Optional[SearchContext] = None) -> Optional[ast.Module]: ...
def get_all_stub_files(search_context: Optional[SearchContext] = None) -> Iterable[tuple[str, Path]]: ...

→ Detailed API Reference

Parsing Stubs

Parse stub files into structured dictionaries mapping names to AST nodes with export information.

def get_stub_names(module_name: str, *, search_context: Optional[SearchContext] = None) -> Optional[NameDict]: ...
def parse_ast(ast: ast.AST, search_context: SearchContext, module_name: ModulePath, *, is_init: bool = False) -> NameDict: ...

→ Detailed API Reference

Resolving Names

Resolve fully qualified names across module boundaries, following imports to find original definitions.

class Resolver:
    def __init__(self, search_context: Optional[SearchContext] = None) -> None: ...
    def get_fully_qualified_name(self, name: str) -> ResolvedName: ...
    def get_name(self, module_name: ModulePath, name: str) -> ResolvedName: ...
    def get_module(self, module_name: ModulePath) -> Module: ...

→ Detailed API Reference

Search Context Configuration

Configure stub finding behavior with custom typeshed paths, search paths, Python versions, and platform settings.

def get_search_context(
    *,
    typeshed: Optional[Path] = None,
    search_path: Optional[Sequence[Path]] = None,
    version: Optional[PythonVersion] = None,
    platform: str = sys.platform,
    raise_on_warnings: bool = False,
    allow_py_files: bool = False
) -> SearchContext: ...

→ Detailed API Reference

Key Patterns

Pattern: Check for None Returns

Always check functions that return Optional types:

# CORRECT
stub_path = get_stub_file('module')
if stub_path is None:
    print("Module not found")
else:
    print(f"Found: {stub_path}")

# INCORRECT - may crash
stub_path = get_stub_file('module')
with open(stub_path) as f:  # TypeError if None
    content = f.read()

Pattern: Type Check ResolvedName

Use isinstance() to determine resolved name type:

result = resolver.get_fully_qualified_name('collections.OrderedDict')

if result is None:
    print("Not found")
elif isinstance(result, ModulePath):
    print("It's a module")
elif isinstance(result, ImportedInfo):
    print(f"Imported from {'.'.join(result.source_module)}")
elif isinstance(result, NameInfo):
    print("Defined directly")

Pattern: Reuse Resolver Instances

Cache resolvers for performance:

# CORRECT - reuse resolver
resolver = Resolver()
for name in ['typing.List', 'typing.Dict', 'typing.Set']:
    result = resolver.get_fully_qualified_name(name)

# INCORRECT - creates new resolver each time
for name in ['typing.List', 'typing.Dict', 'typing.Set']:
    resolver = Resolver()  # Wasteful
    result = resolver.get_fully_qualified_name(name)

Pattern: Version-Specific Analysis

Compare stubs across Python versions:

from typeshed_client import get_search_context, get_stub_names

versions = [(3, 9), (3, 10), (3, 11)]
for version in versions:
    ctx = get_search_context(version=version)
    names = get_stub_names('typing', search_context=ctx)
    if names:
        print(f"Python {version}: {len(names)} names")

Common Data Structures

NameInfo

Information about a name defined in a stub:

class NameInfo(NamedTuple):
    name: str
    is_exported: bool
    ast: Union[ast.AST, ImportedName, OverloadedName]
    child_nodes: Optional[NameDict] = None
  • name: The object's name (unqualified)
  • is_exported: Whether publicly exported (True if not starting with _ or in __all__)
  • ast: AST node, ImportedName, or OverloadedName
  • child_nodes: For classes, nested names (methods/attributes)

ImportedName

Represents a name imported from another module:

class ImportedName(NamedTuple):
    module_name: ModulePath
    name: Optional[str] = None

SearchContext

Configuration for stub operations:

class SearchContext(NamedTuple):
    typeshed: Path
    search_path: Sequence[Path]
    version: PythonVersion
    platform: str
    raise_on_warnings: bool = False
    allow_py_files: bool = False

Error Handling

InvalidStub Exception

Raised for parsing errors or warnings (when raise_on_warnings=True):

class InvalidStub(Exception):
    def __init__(self, message: str, file_path: Optional[Path] = None) -> None: ...

Usage:

from typeshed_client.parser import InvalidStub

ctx = get_search_context(raise_on_warnings=True)
try:
    names = get_stub_names('module', search_context=ctx)
except InvalidStub as e:
    print(f"Parsing error: {e}")

Best Practices

  1. Always check for None: Functions like get_stub_file() return None when module not found
  2. Reuse SearchContext: Create once, reuse across operations for consistency
  3. Cache Resolver instances: Maintains internal caches for performance
  4. Use type guards: Check isinstance() for union types like ResolvedName
  5. Handle version differences: Test with different SearchContext configurations
  6. Check Module.exists: Always verify before accessing module.names
  7. Use safe file operations: Prefer safe_exists(), safe_is_file() over direct path operations
  8. Handle exceptions: Wrap operations in try-except when using raise_on_warnings=True

Documentation Structure

Guides

Step-by-step instructions for common tasks:

Examples

Real-world scenarios and use cases:

API Reference

Detailed specifications and comprehensive documentation:

Performance Notes

  • Caching: Resolver instances cache parsed modules and resolved names
  • Thread Safety: Module-level functions are thread-safe; don't share Resolver across threads
  • Memory: Parsed ASTs stored in memory when cached
  • Stub Lookup: O(n) where n is number of directories in search path
  • Name Resolution: O(1) after first resolution (cached)

Version

__version__: str  # Current version: "2.8.2"