{"id":3305,"library":"typeshed-client","title":"typeshed-client","description":"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.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/JelleZijlstra/typeshed_client","tags":["typing","type checking","typeshed","stubs","static analysis"],"install":[{"cmd":"pip install typeshed-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"symbol":"get_stub_file","correct":"from typeshed_client import get_stub_file"},{"symbol":"get_stub_ast","correct":"from typeshed_client import get_stub_ast"},{"symbol":"SearchContext","correct":"from typeshed_client.finder import SearchContext"}],"quickstart":{"code":"from typeshed_client import get_stub_file, get_stub_ast\nfrom typeshed_client.finder import SearchContext\n\n# Find the stub file for a standard library module (e.g., 'typing')\ntyping_stub_path = get_stub_file('typing')\nif typing_stub_path:\n    print(f\"Found 'typing' stub at: {typing_stub_path}\")\n\n    # Get the Abstract Syntax Tree (AST) for the stub\n    typing_stub_ast = get_stub_ast('typing')\n    if typing_stub_ast:\n        print(f\"AST for 'typing' module (first 3 nodes): {typing_stub_ast.body[:3]}\")\n\n# Example of using a custom SearchContext (e.g., allowing .py files in search)\n# Note: allow_py_files was added in v2.8.0/v2.8.1/v2.8.2\ncustom_context = SearchContext(allow_py_files=True)\nmath_stub_path = get_stub_file('math', search_context=custom_context)\nif math_stub_path:\n    print(f\"Found 'math' stub (with custom context) at: {math_stub_path}\")\nelse:\n    print(\"Could not find 'math' stub (this is normal if it's not in typeshed).\")","lang":"python","description":"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'."},"warnings":[{"fix":"Upgrade your Python interpreter to version 3.9 or a later supported version.","message":"Support for Python 3.8 was dropped in version 2.8.0. Ensure your environment uses Python 3.9 or newer.","severity":"breaking","affected_versions":">=2.8.0"},{"fix":"Upgrade your Python interpreter to version 3.8 or later.","message":"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.","severity":"breaking","affected_versions":">=2.5.0"},{"fix":"Update any code that directly interacts with the AST parsing to use `ast` module compatible structures and features.","message":"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.","severity":"breaking","affected_versions":">=1.2.3"},{"fix":"Avoid using `get_search_path()`. Instead, configure the `search_path` directly when creating a `SearchContext` if custom paths are needed.","message":"The function `typeshed_client.finder.get_search_path()` was deprecated in version 2.5.0 as it is no longer useful.","severity":"deprecated","affected_versions":">=2.5.0"},{"fix":"Upgrade to `typeshed-client` version 2.8.0 or newer to benefit from improved encoding handling on Windows.","message":"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.","severity":"gotcha","affected_versions":"<2.8.0"},{"fix":"If you experience unexpected resolution, explicitly set `allow_py_files=False` in your `SearchContext` or review your stub package structure.","message":"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.","severity":"gotcha","affected_versions":">=2.8.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}