{"id":722,"library":"types-pyyaml","title":"Typing Stubs for PyYAML","description":"This package provides static type annotations (stubs) for the PyYAML library. PyYAML is a full-featured YAML parser and emitter for Python, enabling seamless interaction with YAML data for configurations and structured data. Types-PyYAML allows static type checkers like mypy and pyright to analyze code using PyYAML, improving code quality and catching potential type errors before runtime. This package is part of the typeshed project and aims to provide accurate annotations for PyYAML versions 6.0.*.","status":"active","version":"6.0.12.20250915","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","yaml","type-checking"],"install":[{"cmd":"pip install types-PyYAML","lang":"bash","label":"Install types-PyYAML"},{"cmd":"pip install PyYAML types-PyYAML mypy","lang":"bash","label":"Install PyYAML, its stubs, and mypy for type checking"}],"dependencies":[{"reason":"This package provides type stubs for PyYAML; PyYAML itself is required at runtime for any functionality.","package":"PyYAML","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"wrong":"import yaml","symbol":"yaml","correct":"import yaml-stubs"}],"quickstart":{"code":"import yaml\nfrom typing import Any\n\ndef process_config(config_str: str) -> dict[str, Any]:\n    data: dict[str, Any] = yaml.safe_load(config_str)\n    # Introduce a deliberate type error for demonstration\n    # 'name' is expected to be a string, but we assign a number\n    # mypy should flag this if types-PyYAML is correctly used.\n    if 'name' in data: # type: ignore[reportUntypedBaseMembers]\n        data['name'] = 123  # Intentionally wrong type for demo\n    return data\n\nconfig_data = \"\"\"\nname: Alice\nage: 30\n\"\"\"\n\n# This would normally be executed, but the focus is on static analysis\n# processed_data = process_config(config_data)\n# print(processed_data)\n\n# To run mypy and see the type error:\n# 1. pip install PyYAML types-PyYAML mypy\n# 2. Save this code as `app.py`\n# 3. Run: `mypy app.py`\n# Expected output should include a type error about data['name'] assignment.","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'6.0':82 'accur':77 'aim':74 'allow':42 'analyz':51 'annot':10,78 'catch':59 'check':88 'checker':45 'code':52,56 'configur':35 'data':33,38 'emitt':25 'enabl':28 'error':62 'featur':21 'full':20 'full-featur':19 'improv':55 'interact':30 'librari':15 'like':46 'mypi':47 'packag':6,66 'parser':23 'part':68 'potenti':60 'project':72 'provid':7,76 'pyright':49 'python':27 'pyyaml':4,14,16,41,54,80 'qualiti':57 'runtim':64 'seamless':29 'static':8,43 'structur':37 'stub':2,11,84 'type':1,9,40,44,61,83,87 'type-check':86 'types-pyyaml':39 'typesh':71 'use':53 'version':81 'yaml':22,32,85","created_at":"2026-03-28T17:12:08.537324+00:00","updated_at":"2026-04-16T23:43:41.492398+00:00","problems":{"verify_error":"File \"<string>\", line 1\n    import yaml-stubs\n               ^\nSyntaxError: invalid syntax"},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"6.0.12.20260815","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/PyYAML.md","pypi":"https://pypi.org/project/types-pyyaml/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-27","next_check":"2026-07-10","install_tag":"verified"}}