Poyo, a Lightweight YAML Parser

0.5.0 · active · verified Thu Apr 16

Poyo is a lightweight YAML parser for Python (current version 0.5.0). It focuses on parsing a chosen subset of the YAML format, primarily designed for configuration files like those used by cookiecutter. It explicitly does not support deserialization of arbitrary Python objects, YAML serialization, or JSON compatibility. The project is in maintenance mode with infrequent updates, with the last release in July 2019, but it remains functional for its intended scope.

Common errors

```
poyo.PoyoException: Error parsing YAML: Line ... Column ...: Expected a mapping or sequence start
```
cause Attempting to parse YAML that uses features outside of Poyo's supported subset (e.g., YAML tags, anchors/aliases, or malformed syntax).

fix Review the YAML content and simplify it to basic key-value pairs, lists, and scalars. If advanced YAML features are required, switch to a full-featured YAML parser like `PyYAML`.
```
KeyError: 'some_key' or AttributeError: 'NoneType' object has no attribute 'get'
```
cause A YAML `null` value (represented by `~` or `null`) was not parsed as Python's `None`, but as a string, or a key was expected but not found due to a parsing error in older versions.

fix This often occurs in older versions of poyo. Ensure you are using `poyo>=0.3.0` to correctly handle `null` values. Also, verify that your YAML structure matches the expected Python dictionary access path.
```
Error parsing YAML: Line ... Column ...: Could not parse scalar
```
cause This error can occur when Poyo encounters unexpected characters or structures, such as unquoted strings containing special characters or improper indentation, especially in older versions when list/comment handling was less robust.

fix Check for correct YAML indentation and ensure all strings with special characters or spaces are properly quoted. Consider upgrading to the latest Poyo version (`0.5.0`) as several parsing bugs were fixed in later releases.

Warnings

gotcha Poyo only supports a *subset* of the YAML specification. It does not support arbitrary Python object deserialization, YAML serialization, or compatibility with JSON. Attempting to use advanced YAML features (e.g., anchors, tags, complex mappings) will likely result in parsing errors.
Fix: Ensure your YAML adheres to the basic structure supported by Poyo (scalars, lists, dictionaries). For full YAML specification support, consider libraries like PyYAML.
gotcha The `~` character (YAML's representation for null) was not correctly recognized as `None` in Python before version 0.3.0, leading to unexpected string values.
Fix: Upgrade to `poyo>=0.3.0` to ensure `~` is correctly parsed as `None`.
gotcha Earlier versions had bugs with parsing list items that included comments or blank lines, leading to incorrect or incomplete data structures.
Fix: Upgrade to `poyo>=0.4.2` to resolve issues with lists containing comments and blank lines.
gotcha Multiline strings using the `>` or `|` block scalar indicators are only supported in version 0.5.0 and later.
Fix: Upgrade to `poyo>=0.5.0` to use multiline string features. For older versions, represent long strings as single-line quoted strings.

Install

pip install poyo Install latest version

Imports

parse_string
```
from poyo import parse_string
```
Main function to parse a YAML string into a Python dictionary.
PoyoException
```
from poyo import PoyoException
```
Custom exception raised for parsing errors.

Quickstart

Parses a simple YAML string using `parse_string` and demonstrates basic type conversion and multiline string handling, with error handling for parsing issues.

from poyo import parse_string, PoyoException

yaml_string = """
default_context:
    greeting: Hello
    is_enabled: true
    count: 123
    items:
        - apple
        - banana
        - null
long_description: >
    This is a multiline string.
    It demonstrates how to handle
    text blocks introduced in 0.5.0.
"""

try:
    config = parse_string(yaml_string)
    print(config)
    # Expected output similar to:
    # {
    #     'default_context': {
    #         'greeting': 'Hello',
    #         'is_enabled': True,
    #         'count': 123,
    #         'items': ['apple', 'banana', None]
    #     },
    #     'long_description': 'This is a multiline string. It demonstrates how to handle text blocks introduced in 0.5.0.'
    # }
except PoyoException as e:
    print(f"Error parsing YAML: {e}")

view raw JSON →