Skip to main content

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:

  • Exception if 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:

  • Exception if 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:

  1. Development path (relative to package)
  2. Directories in LD_LIBRARY_PATH environment variable
  3. /usr/local/lib (default install location)
  4. ~/.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).

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)

Source distribution for yamlstar 0.1.28
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)

Table of built distributions (wheels) for yamlstar 0.1.28
File Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page