Typing Stubs for PyYAML

Warnings

• breaking Updates to type stubs, even without changes to your runtime code, can introduce new type-checking errors. This is because typeshed aims to improve the accuracy of type annotations, which might expose previously unflagged type inconsistencies in your codebase.
  Fix: Consider pinning your `types-PyYAML` version in your `requirements.txt` (e.g., `types-PyYAML==6.0.12.20250915`) and regularly testing updates. You can also temporarily ignore specific errors using `type: ignore` comments if a stub change is overly strict or controversial, while contributing fixes to typeshed.
• gotcha When attempting to use the C-accelerated `CLoader` or `CDumper` from PyYAML with a fallback to pure Python `Loader`/`Dumper`, type checkers like mypy can report `Incompatible import` errors. This happens because `CLoader` and `Loader` are distinct types, even though they often serve a similar purpose.
  Fix: If strict type checking is desired, you may need to use `typing.cast` or `type: ignore` to suppress these specific errors. Alternatively, structure your code to use a single `Loader`/`Dumper` definition to avoid type checker confusion, or refactor to reduce direct exposure of the `Loader` type.
• gotcha PyYAML (and thus its stubs) is based on the older YAML 1.1 specification. This can lead to unexpected implicit type conversions (e.g., 'yes', 'no' become booleans; '010' becomes an octal integer; `59:59` interpreted as seconds) compared to the stricter YAML 1.2 specification common in other parsers. The stubs accurately reflect these 1.1 behaviors.
  Fix: Be aware of YAML 1.1's implicit typing rules when writing or consuming YAML files with PyYAML. For stricter YAML 1.2 compliance, consider alternative libraries like `ruamel.yaml` if the `types-PyYAML` stubs' accuracy for PyYAML's behavior is undesirable for your use case.
• gotcha The versioning of `types-PyYAML` is independent of `PyYAML` itself, though the stubs target specific `PyYAML` versions (e.g., `types-PyYAML 6.0.x.YYYYMMDD` targets `PyYAML==6.0.*`). This means updating one does not automatically update the other, and an older stub version might not fully cover a newer PyYAML, or vice versa.
  Fix: It is recommended to explicitly install both `PyYAML` and `types-PyYAML` and to regularly update both, while ensuring their compatibility. Typeshed recommends either using the same version bounds for stubs as for the package or pinning the stubs to a known good version.

Install

• pip install types-PyYAML Install types-PyYAML
• pip install PyYAML types-PyYAML mypy Install PyYAML, its stubs, and mypy for type checking

Imports

• yaml

  import yaml

  Types-PyYAML provides type hints for the 'yaml' module imported from the PyYAML library. It does not introduce its own runtime symbols.
• load, dump

  from yaml import load, dump

  Common imports for PyYAML functionality, now with type checking enabled by types-PyYAML.

Quickstart

This quickstart demonstrates how `types-PyYAML` enables static type checking for `PyYAML` code using `mypy`. After installing `PyYAML`, `types-PyYAML`, and `mypy`, save the code to `app.py` and run `mypy app.py`. Mypy will detect the deliberate type error where an integer is assigned to a key expected to hold a string, thanks to the type information provided by `types-PyYAML`.

import yaml
from typing import Any

def process_config(config_str: str) -> dict[str, Any]:
    data: dict[str, Any] = yaml.safe_load(config_str)
    # Introduce a deliberate type error for demonstration
    # 'name' is expected to be a string, but we assign a number
    # mypy should flag this if types-PyYAML is correctly used.
    if 'name' in data: # type: ignore[reportUntypedBaseMembers]
        data['name'] = 123  # Intentionally wrong type for demo
    return data

config_data = """
name: Alice
age: 30
"""

# This would normally be executed, but the focus is on static analysis
# processed_data = process_config(config_data)
# print(processed_data)

# To run mypy and see the type error:
# 1. pip install PyYAML types-PyYAML mypy
# 2. Save this code as `app.py`
# 3. Run: `mypy app.py`
# Expected output should include a type error about data['name'] assignment.