PyYAML-ft (Free-Threading)

8.0.0 · active · verified Thu Apr 09

PyYAML-ft is a fork of the popular PyYAML library, providing a full-featured YAML parser and emitter for Python. Its primary purpose is to add support for free-threading builds of CPython, specifically targeting Python 3.13 and newer, where the Global Interpreter Lock (GIL) is absent. This addresses thread-safety issues that are more easily triggered in free-threaded environments and ensures ABI compatibility. The library is currently at version 8.0.0 and maintains an active release cadence in sync with free-threading Python developments.

Warnings

breaking The primary module name has changed from `yaml` to `yaml_ft` starting with v8.0.0. Direct `import yaml` will fail if only `pyyaml-ft` is installed.
Fix: Update imports to `import yaml_ft` or use `try: import yaml_ft as yaml except ModuleNotFoundError: import yaml` for compatibility with projects supporting both PyYAML and PyYAML-ft.
breaking Custom constructors, representers, and resolvers (`add_constructor`, `add_representer`, `add_implicit_resolver`, `add_path_resolver`) now use thread-local registries. These must be explicitly re-registered in each new thread if used in multithreaded applications.
Fix: Ensure that any custom YAML types or resolvers are registered within each thread's initialization function or before processing YAML in that thread.
gotcha PyYAML-ft is primarily designed for Python 3.13 and newer, especially free-threaded builds. While it might install on older Python versions, its free-threading benefits are specific to Python 3.13+ environments.
Fix: Ensure your project's `requires_python` is set to `>=3.13` and consider conditional installation based on `python_version` if supporting a wider range of Python versions.
gotcha Using `yaml.load()` (or `yaml_ft.load()`) with untrusted input can lead to arbitrary code execution, as it can deserialize arbitrary Python objects. This is a well-known security vulnerability in PyYAML and applies to PyYAML-ft.
Fix: Always use `yaml_ft.safe_load()` when loading YAML from untrusted or external sources to restrict object construction to safe types.

Install

pip install pyyaml-ft Install pyyaml-ft

Imports

yaml_ft
```
import yaml_ft
```
As of v8.0.0, the module was renamed from 'yaml' to 'yaml_ft' to allow coexistence with upstream PyYAML.
safe_load, safe_dump
```
from yaml_ft import safe_load, safe_dump
```
It is generally safer to use `safe_load` and `safe_dump` to prevent arbitrary code execution from untrusted YAML sources.

Quickstart

This quickstart demonstrates how to load and dump YAML data using `pyyaml-ft`. It includes a conditional import for compatibility and uses `safe_load`/`safe_dump` for secure processing of YAML data.

import io

try:
    import yaml_ft as yaml
except ModuleNotFoundError:
    # Fallback or for environments where pyyaml-ft isn't the primary YAML lib
    import yaml 

# Sample YAML data
yaml_data = """
name: Alice
age: 30
occupations:
  - Software Engineer
  - Technical Writer
is_active: true
"""

# Load YAML data
data = yaml.safe_load(yaml_data)
print("Loaded Data:", data)

# Modify data
data['age'] = 31
data['occupations'].append('Open Source Contributor')

# Dump data to YAML string
output_stream = io.StringIO()
yaml.safe_dump(data, output_stream, default_flow_style=False)
print("\nDumped YAML:")
print(output_stream.getvalue())

print(f"\nSuccessfully used {yaml.__name__} for YAML operations.")

view raw JSON →