DOCSEARCHbyAlgolia
Submit Docs

typeshed

repository·main·Indexed 26 days ago

https://github.com/python/typeshed

Typeshed provides external type annotations for the Python standard library, builtins, and various third-party packages. It is used by static analysis tools like mypy and pyright for type checking, inference, and autocompletion. The project includes the _typeshed utility package for static analysis in stub files and provides tools for managing stub metadata, dependencies, and stubtest configurations.

Tokens
13.3K
Snippets
16
Records
139
Agent score
87%

What's inside typeshed

  1. Use the _typeshed package in stub files

    main

    The _typeshed package and its types are intended for use in stub (.pyi) files. These types do not exist at runtime. To avoid runtime errors when using these types in implementation (.py) files, you must wrap the import within a TYPE_CHECKING block.

    To use types in annotations, you can either use string literals (quoting the type) or enable from __future__ import annotations at the top of your file.

  2. Install third-party type stubs via pip

    main

    If you are using a type checker (like mypy, pyright, or PyCharm) and need type annotations for third-party libraries, you can install them from PyPI. These packages are typically named types-<package_name>. For example, to install stubs for html5lib and requests, use the following command:

    $ pip install types-html5lib types-requests

  3. Understand third-party stub package versioning

    main

    Third-party stub packages follow a specific versioning pattern: [runtime_version].[release_date].

    For example, a version like 1.2.0.20240309 indicates:

    • The stubs are targeted against package==1.2.*.
    • The stubs were released on March 9, 2024.

    When managing these dependencies, you can use one of three strategies:

    1. Match runtime bounds: Use the same version constraints for the stubs as you do for the package (e.g., types-requests>=2.30.0,<2.32). This ensures compatibility but carries a risk of breaking type checks if stubs change.
    2. Pin to a known good version: Use an exact version (e.g., types-requests==2.31.0.1) to prevent unexpected type-checking failures during dependency upgrades.
    3. Unpinned: Do not specify a version to automatically receive stub improvements, though this risks incompatibility if the runtime package undergoes a major version change.

  5. Use the `_typeshed` utility package

    main
    The _typeshed package is included as part of the standard library in typeshed. It contains utility types used within stub files. Note that these types are for static analysis only and are not available at runtime.

  6. Configure Mypy tests in metadata files

    main

    To configure Mypy tests for a distribution, use the [mypy-tests] section in your metadata file. You can define multiple module sections. Each section must include a module-name and a values sub-section containing the Mypy configuration keys and values.

    Example structure in a TOML metadata file:

    [mypy-tests.yaml]
module-name = "yaml"
[mypy-tests.yaml.values]
disallow_incomplete_defs = true
disallow_untyped_defs = true

  7. Understand API stability for _typeshed

    main

    While _typeshed can be used by packages outside of the typeshed repository, it offers limited API stability guarantees.

    • Stable items: Items explicitly marked as "stable" are guaranteed not to be removed or changed in an incompatible way for at least one year. Before any breaking change, the "stable" moniker will be removed and the type will be marked as deprecated.
    • Unmarked items: No stability guarantees are provided for types that are not explicitly marked as "stable".

  9. Use the build_py command in setuptools

    main

    The build_py command is used to build Python modules. It handles the copying of source files to the build directory and can optionally perform byte-compilation.

    Available Options

    Boolean Options

    These flags can be toggled on or off:

    • compile: Whether to byte-compile the modules.
    • optimize: Whether to optimize the byte-compilation.
    • force: (Implicitly available via negative_opt logic in the underlying command system).

    User Options

    The command supports the following configuration options:

    • build_lib: The directory where the built modules are installed.
    • py_modules: A list of Python modules to be built.
    • package: A specific package to build.
    • package_data: Data files associated with specific packages.
    • package_dir: Mapping of package names to directories.
    • packages: A list of packages to be built.
    • data_files: List of data files to be installed.

  12. Configure bdist distribution formats

    main

    The bdist command uses format_commands (or the alias format_command) to define available distribution formats. This is a dictionary mapping format names to tuples of strings. Note that ListCompat.append is deprecated; use dictionary operations instead.

    class ListCompat(dict[str, tuple[str, str]]):
    @deprecated("format_commands is now a dict. append is deprecated")
    def append(self, item: Unused) -> None: ...

# In bdist class:
format_commands: ClassVar[ListCompat]