This project provides a way to retrieve information from
`typeshed <https://www.github.com/python/typeshed>`_ and from
`PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_ 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:

  .. code-block:: python

      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.12.0 (June 1, 2026)

- Update bundled typeshed
- Support for Python 3.12+ ``type`` alias statements

Version 2.11.0 (May 1, 2026)

- Update bundled typeshed

Version 2.10.0 (April 17, 2026)

- Update bundled typeshed
- Make tests pass with the typeshed in the PyPI tarball

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)

- Update bundled typeshed

Version 2.0.4 (March 10, 2022)

- Update bundled typeshed

Version 2.0.3 (February 2, 2022)

- Update bundled typeshed

Version 2.0.2 (January 28, 2022)

- Update bundled typeshed

Version 2.0.1 (January 14, 2022)

- Update bundled typeshed

Version 2.0.0 (December 22, 2021)

- Breaking change: Use `ast` instead of `typed_ast` for parsing

Version 1.2.3 (December 12, 2021)

- Update bundled typeshed
- Remove noisy warning if a name is imported multiple times
- Fix `get_all_stub_files()` in Python 3 for modules that also exist in Python 2

Version 1.2.2 (December 9, 2021)

- Further fix relative import resolution

Version 1.2.1 (December 9, 2021)

- Fix bug with resolution of relative imports
- Update bundled typeshed

Version 1.2.0 (December 6, 2021)

- Support overloaded methods
- Update bundled typeshed

Version 1.1.4 (December 6, 2021)

- Updated bundled typeshed

Version 1.1.3 (November 14, 2021)

- Update bundled typeshed
- Declare support for Python 3.10
- Fix undeclared dependency on ``mypy_extensions``

Version 1.1.2 (November 5, 2021)

- Update bundled typeshed

Version 1.1.1 (July 31, 2021)

- Update bundled typeshed
- Improve error message when encountering a duplicate name

Version 1.1.0 (June 24, 2021)

- Update bundled typeshed
- Handle missing `@python2` directory
- Allow comments in VERSIONS file

Version 1.0.2 (May 5, 2021)

- Handle version ranges in typeshed VERSIONS file
- Update bundled typeshed

Version 1.0.1 (April 24, 2021)

- Update bundled typeshed

Version 1.0.0 (April 11, 2021)

- Improve docstrings

Version 1.0.0rc1 (April 11, 2021)

- Support new typeshed layout
- Support PEP 561 packages
- Bundle typeshed directly instead of relying on mypy

Version 0.4 (December 2, 2019)

- Performance improvement
- Code quality improvements

Version 0.3 (November 23, 2019)

- Update location of typeshed for newer mypy versions

Version 0.2 (May 25, 2017)

- Support using a custom typeshed directory
- Add ``get_all_stub_files()``
- Handle ``from module import *``
- Bug fixes

Version 0.1 (May 4, 2017)

- Initial release
