typeshed-client 2.7.0__tar.gz → 2.8.2__tar.gz

typeshed_client-2.8.2/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: typeshed_client
+Version: 2.8.2
+Summary: A library for accessing stubs in typeshed.
+Home-page: https://github.com/JelleZijlstra/typeshed_client
+Author: Jelle Zijlstra
+Author-email: jelle.zijlstra@gmail.com
+License: MIT
+Project-URL: Bug Tracker, https://github.com/JelleZijlstra/typeshed_client/issues
+Keywords: typeshed typing annotations
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: importlib_resources>=1.4.0
+Requires-Dist: typing-extensions>=4.5.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+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.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

typeshed_client-2.8.2/README.rst

@@ -0,0 +1,272 @@
+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.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

typeshed_client-2.8.2/pyproject.toml

@@ -0,0 +1,92 @@
+[tool.black]
+target-version = ['py39', 'py310', 'py311', 'py312', 'py313']
+include = '\.pyi?$'
+skip-magic-trailing-comma = true
+preview = true
+
+force-exclude = '''
+/(
+    \.git
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | typeshed_client/typeshed
+)/
+'''
+
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.mypy]
+strict_optional = true
+warn_no_return = true
+disallow_any_unimported = true
+
+# Across versions of mypy, the flags toggled by --strict vary.  To ensure
+# we have reproducible type check, we instead manually specify the flags
+warn_unused_configs = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+# warn_return_any = true
+warn_unreachable = true
+implicit_reexport = false
+strict_equality = true
+
+# Disallow any
+# disallow_any_explicit = true
+disallow_any_decorated = true
+
+exclude = [
+  "typeshed_client/typeshed",
+  "tests/site-packages",
+  "tests/typeshed",
+  "build/",
+  "thirdparty",
+  ".tox/",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+preview = true
+unsafe-fixes = true
+
+exclude = [
+  "typeshed_client/typeshed",
+  "tests/typeshed",
+  "build/",
+  ".tox/",
+]
+
+[tool.ruff.lint]
+select = [
+  "F",
+  "E",
+  "I",  # import sorting
+  "ANN",  # enforce type annotations
+  "C4",  # flake8-comprehensions
+  "B",  # bugbear
+  "SIM",  # simplify
+  "UP",  # pyupgrade
+  "PIE",
+  "PERF",
+  "RUF",  # Ruff's own rules
+]
+
+ignore = [
+  "SIM105",  # I don't like contextlib.suppress
+  "UP038",  # astral-sh/ruff#7871
+  "B901",  # returning from generators is fine
+]