typeshed-client


Nametypeshed-client JSON
Version 2.7.0 PyPI version JSON
download
home_pagehttps://github.com/JelleZijlstra/typeshed_client
SummaryA library for accessing stubs in typeshed.
upload_time2024-07-16 17:01:17
maintainerNone
docs_urlNone
authorJelle Zijlstra
requires_python>=3.8
licenseMIT
keywords typeshed typing annotations
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            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: Optional[Path] = None,
  search_path: Optional[Sequence[Path]] = None, python_executable: Optional[str] = None,
  version: Optional[PythonVersion] = None, platform: str = sys.platform) -> SearchContext``:
  Returns a ``SearchContext``
- ``typeshed_client.get_stub_file(module_name: str, *,
  search_context: Optional[SearchContext] = None) -> Optional[Path]``: Returns
  the path to a module's stub in typeshed. For example,
  ``get_stub_file('typing', search_context=get_search_context(version=(2, 7)))`` may return
  ``Path('/path/to/typeshed/stdlib/@python2/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: Optional[SearchContext] = None) -> Optional[NameDict]`` 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: Union[ast3.AST, ImportedName, OverloadedName]
        child_nodes: Optional[NameDict] = 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, you need to 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.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

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/JelleZijlstra/typeshed_client",
    "name": "typeshed-client",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "typeshed typing annotations",
    "author": "Jelle Zijlstra",
    "author_email": "jelle.zijlstra@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/65/1e/f20e33447be772486acf028295cdd21437454a051adb602d52ddb5334f9e/typeshed_client-2.7.0.tar.gz",
    "platform": null,
    "description": "This project provides a way to retrieve information from\n`typeshed <https://www.github.com/python/typeshed>`_ and from\n`PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_ stub packages.\n\nExample use cases:\n\n- Find the path to the stub file for a particular module.\n- Find the names defined in a stub.\n- Find the AST node that defines a particular name in a stub.\n\nProjects for which ``typeshed_client`` could be useful include:\n\n- Static analyzers that want to access typeshed annotations.\n- Tools that check stubs for correctness.\n- Tools that use typeshed for runtime introspection.\n\nInstallation\n------------\n\n``typeshed_client`` works on all supported versions of Python. To install it, run\n``python3 -m pip install typeshed_client``.\n\nFinding stubs\n-------------\n\nThe `typeshed_client.finder` module provides functions for finding stub files\ngiven a module name.\n\nFunctions provided:\n\n- ``get_search_context(*, typeshed: Optional[Path] = None,\n  search_path: Optional[Sequence[Path]] = None, python_executable: Optional[str] = None,\n  version: Optional[PythonVersion] = None, platform: str = sys.platform) -> SearchContext``:\n  Returns a ``SearchContext``\n- ``typeshed_client.get_stub_file(module_name: str, *,\n  search_context: Optional[SearchContext] = None) -> Optional[Path]``: Returns\n  the path to a module's stub in typeshed. For example,\n  ``get_stub_file('typing', search_context=get_search_context(version=(2, 7)))`` may return\n  ``Path('/path/to/typeshed/stdlib/@python2/typing.pyi')``. If there is no stub for the\n  module, returns None.\n- ``typeshed_client.get_stub_ast`` has the same interface, but returns an AST\n  object (parsed using the standard library ``ast`` module).\n\nCollecting names from stubs\n---------------------------\n\n``typeshed_client.parser`` collects the names defined in a stub. It provides:\n\n- ``typeshed_client.get_stub_names(module_name: str, *,\n  search_context: Optional[SearchContext] = None) -> Optional[NameDict]`` collects the names\n  defined in a module, using the given Python version and platform. It\n  returns a ``NameDict``, a dictionary mapping object names defined in the module\n  to ``NameInfo`` records.\n- ``typeshed_client.NameInfo`` is a namedtuple defined as:\n\n  .. code-block:: python\n\n      class NameInfo(NamedTuple):\n        name: str\n        is_exported: bool\n        ast: Union[ast3.AST, ImportedName, OverloadedName]\n        child_nodes: Optional[NameDict] = None\n\n  ``name`` is the object's name. ``is_exported`` indicates whether the name is a\n  part of the stub's public interface. ``ast`` is the AST node defining the name,\n  or a different structure if the name is imported from another module or is\n  overloaded. For classes, ``child_nodes`` is a dictionary containing the names\n  defined within the class.\n\nResolving names to their definitions\n------------------------------------\n\nThe third component of this package, ``typeshed_client.resolver``, maps names to\ntheir definitions, even if those names are defined in other stubs.\n\nTo use the resolver, you need to instantiate the ``typeshed_client.Resolver``\nclass. For example, given a ``resolver = typeshed_client.Resolver()``, you can\ncall ``resolver.get_fully_qualified_name('collections.Set')`` to retrieve the\n``NameInfo`` containing the AST node defining ``collections.Set`` in typeshed.\n\nChangelog\n---------\n\nVersion 2.7.0 (July 16, 2024)\n\n- Update bundled typeshed\n\nVersion 2.6.0 (July 12, 2024)\n\n- Update bundled typeshed\n- Support ``try`` blocks in stubs\n- Declare support for Python 3.13\n- Handle situations where an entry on the module search path is not\n  accessible or does not exist\n- Fix warnings due to use of deprecated AST classes\n\nVersion 2.5.1 (February 25, 2024)\n\n- Fix packaging metadata that still incorrectly declared support for Python 3.7\n\nVersion 2.5.0 (February 25, 2024)\n\n- Update bundled typeshed\n- Drop support for Python 3.7\n- ``typeshed_client.finder.get_search_path()`` is now deprecated, as it is no longer useful\n\nVersion 2.4.0 (September 29, 2023)\n\n- Update bundled typeshed\n- Declare support for Python 3.12\n\nVersion 2.3.0 (April 30, 2023)\n\n- Update bundled typeshed\n- Support ``__all__.append`` and ``__all__.extend``\n\nVersion 2.2.0 (January 24, 2023)\n\n- Update bundled typeshed\n- Fix crash on stubs that use ``if MYPY``\n- Fix incorrect handling of ``import *`` in stubs\n- Drop support for Python 3.6 (thanks to Alex Waygood)\n\nVersion 2.1.0 (November 5, 2022)\n\n- Update bundled typeshed\n- Declare support for Python 3.11\n- Add ``typeshed_client.resolver.Module.get_dunder_all`` to get the contents of ``__all__``\n- Add support for ``__all__ +=`` syntax\n- Type check the code using mypy (thanks to Nicolas)\n\nVersion 2.0.5 (April 17, 2022)\n\n- Update bundled typeshed\n\nVersion 2.0.4 (March 10, 2022)\n\n- Update bundled typeshed\n\nVersion 2.0.3 (February 2, 2022)\n\n- Update bundled typeshed\n\nVersion 2.0.2 (January 28, 2022)\n\n- Update bundled typeshed\n\nVersion 2.0.1 (January 14, 2022)\n\n- Update bundled typeshed\n\nVersion 2.0.0 (December 22, 2021)\n\n- Breaking change: Use `ast` instead of `typed_ast` for parsing\n\nVersion 1.2.3 (December 12, 2021)\n\n- Update bundled typeshed\n- Remove noisy warning if a name is imported multiple times\n- Fix `get_all_stub_files()` in Python 3 for modules that also exist in Python 2\n\nVersion 1.2.2 (December 9, 2021)\n\n- Further fix relative import resolution\n\nVersion 1.2.1 (December 9, 2021)\n\n- Fix bug with resolution of relative imports\n- Update bundled typeshed\n\nVersion 1.2.0 (December 6, 2021)\n\n- Support overloaded methods\n- Update bundled typeshed\n\nVersion 1.1.4 (December 6, 2021)\n\n- Updated bundled typeshed\n\nVersion 1.1.3 (November 14, 2021)\n\n- Update bundled typeshed\n- Declare support for Python 3.10\n- Fix undeclared dependency on ``mypy_extensions``\n\nVersion 1.1.2 (November 5, 2021)\n\n- Update bundled typeshed\n\nVersion 1.1.1 (July 31, 2021)\n\n- Update bundled typeshed\n- Improve error message when encountering a duplicate name\n\nVersion 1.1.0 (June 24, 2021)\n\n- Update bundled typeshed\n- Handle missing `@python2` directory\n- Allow comments in VERSIONS file\n\nVersion 1.0.2 (May 5, 2021)\n\n- Handle version ranges in typeshed VERSIONS file\n- Update bundled typeshed\n\nVersion 1.0.1 (April 24, 2021)\n\n- Update bundled typeshed\n\nVersion 1.0.0 (April 11, 2021)\n\n- Improve docstrings\n\nVersion 1.0.0rc1 (April 11, 2021)\n\n- Support new typeshed layout\n- Support PEP 561 packages\n- Bundle typeshed directly instead of relying on mypy\n\nVersion 0.4 (December 2, 2019)\n\n- Performance improvement\n- Code quality improvements\n\nVersion 0.3 (November 23, 2019)\n\n- Update location of typeshed for newer mypy versions\n\nVersion 0.2 (May 25, 2017)\n\n- Support using a custom typeshed directory\n- Add ``get_all_stub_files()``\n- Handle ``from module import *``\n- Bug fixes\n\nVersion 0.1 (May 4, 2017)\n\n- Initial release\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A library for accessing stubs in typeshed.",
    "version": "2.7.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/JelleZijlstra/typeshed_client/issues",
        "Homepage": "https://github.com/JelleZijlstra/typeshed_client"
    },
    "split_keywords": [
        "typeshed",
        "typing",
        "annotations"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "fd394702c2901899c018189b9aa7eb75aa8eb54527aed71c3f285895190dc664",
                "md5": "527570e695b57c73f67c9ed9c6d323a1",
                "sha256": "97084e5abc58a76ace2c4618ecaebd625f2d19bbd85aa1b3fb86216bf174bbea"
            },
            "downloads": -1,
            "filename": "typeshed_client-2.7.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "527570e695b57c73f67c9ed9c6d323a1",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 624417,
            "upload_time": "2024-07-16T17:01:15",
            "upload_time_iso_8601": "2024-07-16T17:01:15.246600Z",
            "url": "https://files.pythonhosted.org/packages/fd/39/4702c2901899c018189b9aa7eb75aa8eb54527aed71c3f285895190dc664/typeshed_client-2.7.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "651ef20e33447be772486acf028295cdd21437454a051adb602d52ddb5334f9e",
                "md5": "e3c788f88969d03258329ac03805501a",
                "sha256": "e63df1e738588ad39f1226de042f4407ab6a99c456f0837063afd83b1415447c"
            },
            "downloads": -1,
            "filename": "typeshed_client-2.7.0.tar.gz",
            "has_sig": false,
            "md5_digest": "e3c788f88969d03258329ac03805501a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 433569,
            "upload_time": "2024-07-16T17:01:17",
            "upload_time_iso_8601": "2024-07-16T17:01:17.181783Z",
            "url": "https://files.pythonhosted.org/packages/65/1e/f20e33447be772486acf028295cdd21437454a051adb602d52ddb5334f9e/typeshed_client-2.7.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-07-16 17:01:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "JelleZijlstra",
    "github_project": "typeshed_client",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "typeshed-client"
}
        
Elapsed time: 1.13830s