Quickstart Guide

This guide will help you get started with ViewText quickly.

Installation

ViewText is available as a standalone PyPI package called viewtext:

pip install viewtext

Basic Concepts

ViewText works with three main components:

  1. Field Mappings: Define how fields map to context data (can be in TOML or Python)

  2. Layout Configuration: TOML files that define how fields map to grid positions

  3. Layout Engine: Builds formatted text output from layouts and context data

Simple Example

Step 1: Create Field Mappings

Create a file named fields.toml:

[fields.temperature]
context_key = "temp"

[fields.humidity]
context_key = "humidity"

[fields.location]
context_key = "city"
default = "Unknown"

Step 2: Create a Layout Configuration

Create a file named layouts.toml:

[layouts.weather]
name = "Weather Display"

[[layouts.weather.lines]]
field = "location"
index = 0
formatter = "text_uppercase"

[[layouts.weather.lines]]
field = "temperature"
index = 1
formatter = "number"

[layouts.weather.lines.formatter_params]
suffix = "°F"
decimals = 1

[[layouts.weather.lines]]
field = "humidity"
index = 2
formatter = "number"

[layouts.weather.lines.formatter_params]
suffix = "%"
decimals = 0

Step 3: Build the Layout

from viewtext import LayoutEngine, LayoutLoader

# Load the layout and field mappings
loader = LayoutLoader("layouts.toml", fields_path="fields.toml")
config = loader.load()
layout = loader.get_layout("weather")

# Create the engine with field mappings from config
engine = LayoutEngine(field_mappings=config.fields)

# Build the output
context = {
    "temp": 72.5,
    "humidity": 65,
    "city": "San Francisco"
}

lines = engine.build_line_str(layout, context)

# Print the result
for line in lines:
    print(line)

Output:

SAN FRANCISCO
72.5°F
65%

Computed Fields

You can perform calculations on your data directly in TOML configuration:

[fields.temperature_f]
operation = "celsius_to_fahrenheit"
sources = ["temp_c"]
default = 0.0

[fields.total_price]
operation = "multiply"
sources = ["price", "quantity"]
default = 0.0

[fields.average_score]
operation = "average"
sources = ["score1", "score2", "score3"]

Available Operations

  • Temperature: celsius_to_fahrenheit, fahrenheit_to_celsius

  • Arithmetic: multiply, divide, add, subtract

  • Aggregates: average, min, max

  • Transforms: abs, round, linear_transform

Example with Layout

# fields.toml
[fields.temp_f]
operation = "celsius_to_fahrenheit"
sources = ["temp_c"]
default = 32.0

# layouts.toml
[layouts.weather]
name = "Weather"

[[layouts.weather.lines]]
field = "temp_f"
index = 0
formatter = "number"

[layouts.weather.lines.formatter_params]
decimals = 1
suffix = "°F"

from viewtext import LayoutEngine, LayoutLoader, RegistryBuilder

loader = LayoutLoader("layouts.toml", fields_path="fields.toml")
layout = loader.get_layout("weather")

registry = RegistryBuilder.build_from_config(loader=loader)
engine = LayoutEngine(field_registry=registry)

lines = engine.build_line_str(layout, {"temp_c": 25})
print(lines[0])

Output: 77.0°F

See examples/computed_fields.toml and examples/README_computed_fields.md for more examples.

Using Built-in Formatters

ViewText includes several built-in formatters:

Text Formatters

# text - Basic text with prefix/suffix
# text_uppercase - Uppercase text

Number Formatters

# number - Format numbers with decimals and separators
# price - Format prices with currency symbols

Date/Time Formatters

# datetime - Format timestamps and datetime objects
# relative_time - Format as relative time (e.g., "5m ago")

Using Python Field Registry (Advanced)

For more complex field logic, you can use Python’s BaseFieldRegistry instead of TOML:

from viewtext import BaseFieldRegistry

registry = BaseFieldRegistry()

# Register custom field getters with complex logic
registry.register("temperature", lambda ctx: ctx["temp"])
registry.register("status", lambda ctx: "Hot" if ctx["temp"] > 80 else "Cool")

# Use the registry with the engine
engine = LayoutEngine(field_registry=registry)

See the User Guide for more details on when to use each approach.

Next Steps