typeshed-client

library2.13.0pypypi✓ verified 23d ago

typeshed-client is a Python library (version 2.9.0) for programmatically accessing type stubs from typeshed and PEP 561 stub packages. It allows tools to find stub files, discover names defined in stubs, and retrieve AST nodes for definitions. The library frequently updates its bundled typeshed to stay current with the official type stub repository.

type-stubs

pip install typeshed-client

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESHED-CLIENT

typeshed-client

type-stubspythonv2.13.0

Install

1.7s avg

Import

102ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.13.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.108s · 23.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.096s · 24MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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).")

typeshed-client --version

Debug

Known issues

breakingSupport 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.

affects: >=2.8.0

breakingSupport 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.

affects: >=2.5.0

breakingIn 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.

affects: >=1.2.3

deprecatedThe 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.

affects: >=2.5.0

gotchaVersions 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.

affects: <2.8.0

gotchaStarting 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.

affects: >=2.8.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'typeshed_client'

The `typeshed-client` package is not installed in the current Python environment, or the import name `typeshed_client` is misspelled.

fix

pip install typeshed-client

AttributeError: module 'typeshed_client' has no attribute 'get_stub_names'

The function `get_stub_names` is located within the `finder` submodule, not directly under the main `typeshed_client` module.

fix

from typeshed_client import finder
finder.get_stub_names('builtins')

TypeError: 'int' object is not iterable

The `version` argument to functions like `get_stub_names` or `get_stub_ast` expects a tuple of two integers (e.g., `(3, 9)`), but a single integer or other non-iterable type was provided.

fix

from typeshed_client import finder
finder.get_stub_names('builtins', version=(3, 9))

TypeError: module_name must be a string

The `module_name` argument for functions like `get_stub_names` or `get_stub_ast` was not provided as a string.

fix

from typeshed_client import finder
finder.get_stub_names('os')

Upgrade

Version history

2.13.0latest on PyPI · released Aug 3, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.9 or newer.

Agent activity

45 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/JelleZijlstra/typeshed_client ↗

packagehttps://pypi.org/project/typeshed-client/ ↗