YAMLStar Python Bindings
Python bindings for YAMLStar - a pure YAML 1.2 loader implemented in Clojure.
Features
- YAML 1.2 Spec Compliance: 100% compliant with YAML 1.2 core schema
- Pluggable YAML: Select parser and emitter implementations per call
- Fast Native Performance: Uses the native YAMLStar shared library
- Simple API: Load YAML documents with a single function call
- Multi-Document Support: Load multiple YAML documents from a single string
Installation
Prerequisites
First, build and install the shared library:
cd ../libyamlstar
make native
sudo make install PREFIX=/usr/local
Or install to user-local directory:
cd ../libyamlstar
make native
make install PREFIX=~/.local
Install Python Package
pip install .
For development:
pip install -e .
Quick Start
import yamlstar
# Create a YAMLStar instance
ys = yamlstar.YAMLStar()
# Load a simple YAML string
data = ys.load("key: value")
print(data) # {'key': 'value'}
# Select YAML parser and emitter plugins (see https://yamlstar.org/plugins/)
opts = yamlstar.Options()
opts.plugin(yamlstar.parser('go-yaml'))
opts.plugin(yamlstar.yaml_emitter('go-yaml'))
ys = yamlstar.YAMLStar(opts)
data = ys.load("key: value")
JSON Comments Parser
The JSON-comments parser is included in the native runtime. Select it through the parser option:
opts = yamlstar.Options().plugin(yamlstar.parser('json-comments'))
ys = yamlstar.YAMLStar(opts)
data = ys.load('''{
"a": true // comment
}''')
Other shared parser plugins can be discovered through Python package entry
points.
Setting YAMLSTAR_LIBRARY_PATH uses only the directories in that explicit
path.
Usage Examples
Basic Types
import yamlstar
ys = yamlstar.YAMLStar()
# Strings
ys.load("hello") # 'hello'
# Integers
ys.load("42") # 42
# Floats
ys.load("3.14") # 3.14
# Booleans
ys.load("true") # True
ys.load("false") # False
# Null
ys.load("null") # None
Collections
# Mappings (dictionaries)
data = ys.load("""
name: Alice
age: 30
city: Seattle
""")
# {'name': 'Alice', 'age': 30, 'city': 'Seattle'}
# Sequences (lists)
data = ys.load("""
- apple
- banana
- orange
""")
# ['apple', 'banana', 'orange']
# Flow style
data = ys.load("[a, b, c]")
# ['a', 'b', 'c']
Nested Structures
data = ys.load("""
person:
name: Alice
age: 30
hobbies:
- reading
- coding
- hiking
""")
# {
# 'person': {
# 'name': 'Alice',
# 'age': 30,
# 'hobbies': ['reading', 'coding', 'hiking']
# }
# }
Multi-Document YAML
# Load all documents from a multi-document YAML string
docs = ys.load_all("""---
name: Document 1
---
name: Document 2
---
name: Document 3
""")
# [
# {'name': 'Document 1'},
# {'name': 'Document 2'},
# {'name': 'Document 3'}
# ]
Type Coercion
YAMLStar follows YAML 1.2 core schema type inference:
data = ys.load("""
string: hello
integer: 42
float: 3.14
bool_true: true
bool_false: false
null_value: null
""")
# {
# 'string': 'hello',
# 'integer': 42,
# 'float': 3.14,
# 'bool_true': True,
# 'bool_false': False,
# 'null_value': None
# }
Error Handling
try:
data = ys.load("invalid: yaml: syntax")
except Exception as e:
print(f"Error loading YAML: {e}")
Version Information
# Get YAMLStar version
version = ys.version()
print(f"YAMLStar version: {version}")
API Reference
YAMLStar Class
__init__()
Create a new YAMLStar instance. Each instance maintains its own native-library lifecycle handle.
ys = yamlstar.YAMLStar()
load(yaml_input)
Load a single YAML document.
Parameters:
yaml_input(str): String containing YAML content
Returns:
- Python object representing the YAML document (dict, list, str, int, float, bool, or None)
Raises:
Exceptionif the YAML is malformed
Example:
data = ys.load("key: value")
load_all(yaml_input)
Load all YAML documents from a multi-document string.
Parameters:
yaml_input(str): String containing one or more YAML documents
Returns:
- List of Python objects, one per YAML document
Raises:
Exceptionif the YAML is malformed
Example:
docs = ys.load_all("---\ndoc1\n---\ndoc2")
version()
Get the YAMLStar version string.
Returns:
- str: Version string
Example:
version = ys.version()
Development
Running Tests
# Run all tests
make test
# Run only pytest tests
make test-pytest
# Run only FFI tests
make test-ffi
Building Distribution
# Build source distribution
make dist
# Build and install in development mode
make install
Requirements
- Python: 3.6 or higher
- libyamlstar: Shared library (installed separately)
- System: Linux or macOS
Library Search Path
The package searches for libyamlstar.so (or .dylib on macOS) in:
- Development path (relative to package)
- Directories in
LD_LIBRARY_PATHenvironment variable /usr/local/lib(default install location)~/.local/lib(user-local install location)
Comparison to PyYAML
| Feature | YAMLStar | PyYAML |
|---|---|---|
| YAML Version | 1.2 | 1.1 |
| Implementation | Pure Clojure | C + Python |
| Type Inference | YAML 1.2 core schema | YAML 1.1 + custom |
| Native Performance | Yes (Gloat/Glojure) | Yes (C extension) |
| Dependencies | libyamlstar.so | None |
License
MIT License - See License file
Credits
Created by Ingy döt Net, inventor of YAML.
YAMLStar is built on the YAML Reference Parser (pure Clojure implementation).
Links
- GitHub: https://github.com/yaml/yamlstar
- YAML Specification: https://yaml.org/spec/1.2/spec.html
Metadata
Release files for yamlstar 0.1.28
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| yamlstar-0.1.28.tar.gz | 12.4 kB | Without provenance | Details for yamlstar-0.1.28.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| yamlstar-0.1.28-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for yamlstar-0.1.28-py3-none-win_amd64.whl |
| yamlstar-0.1.28-py3-none-manylinux_2_31_x86_64.whl | Python 3 | none | Linux glibc 2.31+ x86-64 | Details for yamlstar-0.1.28-py3-none-manylinux_2_31_x86_64.whl |
| yamlstar-0.1.28-py3-none-macosx_15_0_x86_64.whl | Python 3 | none | macOS 15.0+ x86-64 | Details for yamlstar-0.1.28-py3-none-macosx_15_0_x86_64.whl |
| yamlstar-0.1.28-py3-none-macosx_14_0_arm64.whl | Python 3 | none | macOS 14.0+ ARM64 | Details for yamlstar-0.1.28-py3-none-macosx_14_0_arm64.whl |
Total release size: 46.8 MB
Release files / yamlstar-0.1.28.tar.gz
| Download URL | yamlstar-0.1.28.tar.gz |
|---|---|
| Size | 12.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d0a472cec9410fe3e4181cf258adbb727ca49709602bc0fc3e3060bf7266531e
|
|
BLAKE2b-256 checksum How to use checksums |
9da4cb92aa1a9a70e4bf883fe168169f21ce9203b992e9b4172ea0e84d1f2863
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / yamlstar-0.1.28-py3-none-win_amd64.whl
| Download URL | yamlstar-0.1.28-py3-none-win_amd64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
96a6a9e1e4f230f67c32c92466f603f7d8cb29313aae47bc8e9e9a0026eef881
|
|
BLAKE2b-256 checksum How to use checksums |
d097e1c64e1726dbcfdcd84e6df2561d3fe308d329bba44e5cfd66308669e68e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / yamlstar-0.1.28-py3-none-manylinux_2_31_x86_64.whl
| Download URL | yamlstar-0.1.28-py3-none-manylinux_2_31_x86_64.whl |
|---|---|
| Size | 14.1 MB |
| Tags | Linux glibc 2.31+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
e1fd962c85ea940977c851d1844e42f5347e4dde9408a5c487e7604f277244d1
|
|
BLAKE2b-256 checksum How to use checksums |
7fdc816f8e0fc2718832e14bd40b3c2c5526098dd17e5e316e4e417ccd9e75be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / yamlstar-0.1.28-py3-none-macosx_15_0_x86_64.whl
| Download URL | yamlstar-0.1.28-py3-none-macosx_15_0_x86_64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | Python 3 macOS 15.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
8eac8c6319cf6c7c89e2e916226002c6ee81664836e313b9e08c808868153b5a
|
|
BLAKE2b-256 checksum How to use checksums |
f56da438568f294bed32598378804160c411b76a68e718b9c653d714ab0eeaab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / yamlstar-0.1.28-py3-none-macosx_14_0_arm64.whl
| Download URL | yamlstar-0.1.28-py3-none-macosx_14_0_arm64.whl |
|---|---|
| Size | 12.1 MB |
| Tags | Python 3 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1f1ff26d59cc90085eb2817730a4e31ffe94bf50e10bf2b19a012c697783ffba
|
|
BLAKE2b-256 checksum How to use checksums |
83d35c4edfd9f81f8676cbe4926b247c4f74f811ddddfa2bff7f2a64f7572291
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for yamlstar 0.1.28
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.