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 other formatters as needed, while render_mapping emits full YAML-style mappings.

render_variable

render_variable(variable, variable_type=None, *, prec=8)

Render a single Python value according to a detected or explicitly provided output type.

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

Behavior

• Detects an appropriate output type if none is provided
• Dispatches to the correct formatter (scalar, array, list, or mapping)
• Produces YAML-compatible text
• For array-like values, forwards numeric precision

Example

from data_schemer.render_data import render_variable

render_variable(300)

Output:

300

Arrays are rendered using aligned, readable formatting:

import numpy as np

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

[1, 2, 3]

render_array

render_array(array, *, style="clean", prec=8, indent=None)

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

This function accepts:

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

Parameters

• style: "clean" (bracketed YAML-style) or "bare" (rows only)
• prec: decimal precision for floating-point values
• indent: optional indentation (number of spaces)

Formatting rules

• Arrays are rendered using bracket notation in "clean" style
• 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

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(data, data_types=None, *, prec=8, array_style="clean")

Render a dictionary as a YAML-style mapping.

Behavior

• Keys are rendered in insertion order
• Values are rendered using render_variable
• Multi-line values are indented
• Arrays inherit precision and array style settings

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

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 and render_mapping 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 individual values
• 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.