Rendering data

DataSchemer includes small, focused utilities for rendering Python data into readable, YAML-compatible text. These tools are intended for human-facing output: command-line tools, reports, and snippets that users may want to copy directly into configuration files.

The rendering utilities live in render_data.py.

They are not a full serialization system. Instead, they provide:

• stable, predictable formatting
• readable alignment for numeric data
• minimal YAML-compatible syntax
• no implicit I/O or file handling

Design goals

The rendering layer is intentionally conservative.

It aims to:

• produce output that is easy to read in a terminal
• remain valid YAML when pasted into a file
• avoid introducing YAML features that obscure structure
• keep formatting decisions explicit and reproducible

For full serialization, schema validation, or round-tripping, standard YAML libraries should be used instead.

Overview of the API

The public rendering API consists of three main functions:

• render_variable
• render_array
• render_mapping

These functions are designed to compose cleanly: render_variable dispatches to render_array or render_mapping as needed.

render_variable

render_variable(name, value, *, indent=0)

Render a single named variable and its value as YAML-style text.

This is the primary entry point used by DataSchemer command-line tools when emitting results.

Behavior

• Prepends the variable name followed by :
• Delegates rendering of the value based on its type
• Applies indentation consistently
• Produces YAML-compatible output

Example

from data_schemer.render_data import render_variable

render_variable("temperature", 300)

Output:

temperature: 300

Arrays and mappings are rendered on subsequent lines with indentation:

import numpy as np

render_variable("vector", np.array([1, 2, 3]))

vector:
  [ 1, 2, 3 ]

render_array

render_array(array, *, indent=0)

Render a one- or two-dimensional array as aligned, readable text.

This function accepts:

• NumPy arrays
• nested Python lists
• array-like objects convertible to NumPy

Formatting rules

• Arrays are rendered using bracket notation ([ ... ])
• Rows are aligned vertically for readability
• Floating-point values are trimmed of insignificant zeros
• Negative zero is suppressed (-0.0 → 0)
• Output is valid YAML (inline sequences)

Example: vector

import numpy as np
from data_schemer.render_data import render_array

render_array(np.array([0.5, 0.0, 1.0]))

[ 0.5, 0, 1 ]

Example: matrix

matrix = np.array([
  [0.5, 0.5, 0.5],
  [0.0, 0.0, 0.0],
  [0.5, 0.0, 0.0],
])

render_array(matrix, indent=2)

  [[ 0.5, 0.5, 0.5 ],
   [ 0  , 0  , 0   ],
   [ 0.5, 0  , 0   ]]

The formatting prioritizes visual alignment over compactness.

render_mapping

render_mapping(mapping, *, indent=0)

Render a mapping (typically a dictionary) as a YAML-style block.

Behavior

• Keys are rendered in insertion order
• Each key is rendered using render_variable
• Nested mappings increase indentation
• Values may be scalars, arrays, or other mappings

Example

from data_schemer.render_data import render_mapping
import numpy as np

data = {
  "positions": np.array([
    [0.5, 0.5, 0.5],
    [0.0, 0.0, 0.0],
  ]),
  "lattice_constant": 3.905,
}

print(render_mapping(data))

Output:

positions:
  [[ 0.5, 0.5, 0.5 ],
   [ 0  , 0  , 0   ]]
lattice_constant: 3.905

YAML compatibility

The output produced by the rendering utilities is:

• syntactically valid YAML
• intentionally minimal
• free of tags, anchors, or advanced YAML constructs

This makes it suitable for:

• copy-paste into configuration files
• inclusion in documentation
• inspection in terminal output

However, the rendering layer does not guarantee round-tripping back to the original Python object.

When to use render_data

Use the rendering utilities when you want:

• human-readable numeric output
• stable formatting for CLI tools
• YAML-compatible snippets without full serialization
• consistent array formatting across tools

Do not use them when you need:

• schema enforcement
• automatic file writing
• full YAML feature support
• guaranteed round-trip fidelity

Relationship to SchemaCommandLine

In schema-driven workflows, these functions are typically invoked indirectly.

SchemaCommandLine uses render_variable to emit results in a consistent, user-facing format, ensuring that command output is both readable and reusable.

Summary

The rendering layer is intentionally small:

• render_variable handles named output
• render_array handles numeric structure
• render_mapping handles hierarchical data

Together, they provide a predictable bridge between Python data structures and human-readable, YAML-compatible text.