typeshed-client · Python Simple Repository Browser

Project Links

Meta

Author: Jelle Zijlstra

Requires Python: >=3.9

Classifiers

Development Status

3 - Alpha

Environment

Console

Intended Audience

Developers

License

OSI Approved :: MIT License

Operating System

OS Independent

Programming Language

Python
Python :: 3.9
Python :: 3.10
Python :: 3.11
Python :: 3.12
Python :: 3.13
Python :: 3.14

Topic

Software Development

This project provides a way to retrieve information from typeshed and from PEP 561 stub packages.

Example use cases:

Find the path to the stub file for a particular module.
Find the names defined in a stub.
Find the AST node that defines a particular name in a stub.

Projects for which typeshed_client could be useful include:

Static analyzers that want to access typeshed annotations.
Tools that check stubs for correctness.
Tools that use typeshed for runtime introspection.

Installation

typeshed_client works on all supported versions of Python. To install it, run python3 -m pip install typeshed_client.

Finding stubs

The typeshed_client.finder module provides functions for finding stub files given a module name.

Functions provided:

get_search_context(*, typeshed: Path | None = None, search_path: Sequence[Path] | None = None, python_executable: str | None = None, version: PythonVersion | None = None, platform: str = sys.platform, raise_on_warnings: bool = False, allow_py_files: bool = False) -> SearchContext: Returns a SearchContext, which can be used with most other functions to customize stub finding behavior. All arguments are optional and the rest of the package will use a SearchContext created with the default values if no explicit context is provided. The arguments are:
- typeshed: The path to the typeshed directory. If not provided, the package will use the bundled version of typeshed.
- search_path: A list of directories to search for stubs. If not provided, sys.path will be used.
- python_executable: The path to the Python executable to be used for determining search_path.
- version: Version of Python (as a pair, e.g., (3, 13)) to be used for interpreting sys.version_info checks in stubs.
- platform: The platform to be used for interpreting sys.platform checks in stubs. The default is sys.platform, the platform where the library is invoked.
- raise_on_warnings: If True, raise an exception if the parser encounters something it does not understand.
- allow_py_files: If True, allow searching for .py files in addition to .pyi files. This is useful for typed packages that contain both stub files and regular Python files. The default is False.
typeshed_client.get_stub_file(module_name: str, *, search_context: SearchContext | None = None) -> Path | None: Returns the path to a module’s stub file. For example, get_stub_file('typing') may return Path('/path/to/typeshed/stdlib/typing.pyi'). If there is no stub for the module, returns None.
typeshed_client.get_stub_ast has the same interface, but returns an AST object (parsed using the standard library ast module).

Collecting names from stubs

typeshed_client.parser collects the names defined in a stub. It provides:

typeshed_client.get_stub_names(module_name: str, *, search_context: SearchContext | None = None) -> NameDict | None collects the names defined in a module, using the given Python version and platform. It returns a NameDict, a dictionary mapping object names defined in the module to NameInfo records.
typeshed_client.NameInfo is a namedtuple defined as:
```
class NameInfo(NamedTuple):
  name: str
  is_exported: bool
  ast: ast.AST | ImportedName | OverloadedName
  child_nodes: NameDict | None = None
```
name is the object’s name. is_exported indicates whether the name is a part of the stub’s public interface. ast is the AST node defining the name, or a different structure if the name is imported from another module or is overloaded. For classes, child_nodes is a dictionary containing the names defined within the class.

Resolving names to their definitions

The third component of this package, typeshed_client.resolver, maps names to their definitions, even if those names are defined in other stubs.

To use the resolver, instantiate the typeshed_client.Resolver class. For example, given a resolver = typeshed_client.Resolver(), you can call resolver.get_fully_qualified_name('collections.Set') to retrieve the NameInfo containing the AST node defining collections.Set in typeshed.

Changelog

Version 2.9.0 (March 1, 2026)

Update bundled typeshed
Add new public function evaluate_expression_truthiness
Support single-file stub packages
Support namespace packages

Version 2.8.2 (July 15, 2025)

Fix package publishing pipeline

Version 2.8.1 (July 15, 2025)

Fix package publishing pipeline

Version 2.8.0 (July 15, 2025)

Update bundled typeshed
Drop support for Python 3.8 and add preliminary support for Python 3.14
Search for names and imports in .py files in addition to .pyi files
Allow more redefinitions in stub files. OverloadedName objects can now contain ImportedName objects.
Explicitly set encoding to UTF-8, fixing crashes on Windows in some cases.

Version 2.7.0 (July 16, 2024)

Update bundled typeshed

Version 2.6.0 (July 12, 2024)

Update bundled typeshed
Support try blocks in stubs
Declare support for Python 3.13
Handle situations where an entry on the module search path is not accessible or does not exist
Fix warnings due to use of deprecated AST classes

Version 2.5.1 (February 25, 2024)

Fix packaging metadata that still incorrectly declared support for Python 3.7

Version 2.5.0 (February 25, 2024)

Update bundled typeshed
Drop support for Python 3.7
typeshed_client.finder.get_search_path() is now deprecated, as it is no longer useful

Version 2.4.0 (September 29, 2023)

Update bundled typeshed
Declare support for Python 3.12

Version 2.3.0 (April 30, 2023)

Update bundled typeshed
Support __all__.append and __all__.extend

Version 2.2.0 (January 24, 2023)

Update bundled typeshed
Fix crash on stubs that use if MYPY
Fix incorrect handling of import * in stubs
Drop support for Python 3.6 (thanks to Alex Waygood)

Version 2.1.0 (November 5, 2022)

Update bundled typeshed
Declare support for Python 3.11
Add typeshed_client.resolver.Module.get_dunder_all to get the contents of __all__
Add support for __all__ += syntax
Type check the code using mypy (thanks to Nicolas)

Version 2.0.5 (April 17, 2022)