API Reference

This section contains detailed API documentation for all ViewText modules.

viewtext.registry

viewtext.engine

Layout engine for building text grid layouts from configuration and context.

This module provides the LayoutEngine class that builds formatted text layouts by combining field registries, formatters, and layout configurations.

class viewtext.engine.LayoutEngine(field_registry: BaseFieldRegistry | None = None, layout_loader: LayoutLoader | None = None)

Bases: object

Engine for building text grid layouts from configuration and context data.

The LayoutEngine combines a field registry and formatter registry to build formatted text layouts according to TOML layout configurations.

Parameters:

field_registry (BaseFieldRegistry, optional) – Registry of field getter functions. If None, fields are retrieved directly from the context dictionary.

field_registry

The field registry for resolving field values

Type:

BaseFieldRegistry or None

formatter_registry

The formatter registry for formatting values

Type:

FormatterRegistry

Examples

>>> from viewtext import LayoutEngine, BaseFieldRegistry
>>> registry = BaseFieldRegistry()
>>> registry.register("temp", lambda ctx: ctx["temperature"])
>>> engine = LayoutEngine(field_registry=registry)
>>> layout = {
...     "lines": [
...         {"field": "temp", "index": 0, "formatter": "number",
...          "formatter_params": {"decimals": 1}}
...     ]
... }
>>> result = engine.build_line_str(layout, {"temperature": 23.456})
>>> result
['23.5']

__init__(field_registry: BaseFieldRegistry | None = None, layout_loader: LayoutLoader | None = None)

Initialize the layout engine.

Parameters:

• field_registry (BaseFieldRegistry, optional) – Registry of field getter functions

• layout_loader (LayoutLoader, optional) – Layout loader for resolving formatter presets

build_line_str(layout_config: dict[str, Any], context: dict[str, Any]) → list[str]

Build formatted text lines from layout configuration and context.

Parameters:

• layout_config (dict[str, Any]) – Layout configuration dictionary containing “lines” list

• context (dict[str, Any]) – Context dictionary containing data values

Returns:

List of formatted text lines

Return type:

list[str]

Examples

>>> engine = LayoutEngine()
>>> layout = {
...     "lines": [
...         {"field": "name", "index": 0},
...         {"field": "age", "index": 1}
...     ]
... }
>>> result = engine.build_line_str(layout, {"name": "John", "age": 30})
>>> result
['John', '30']

build_dict_str(layout_config: dict[str, Any], context: dict[str, Any]) → dict[str, str]

Build formatted dictionary from layout configuration and context.

Parameters:

• layout_config (dict[str, Any]) – Layout configuration dictionary containing “items” list

• context (dict[str, Any]) – Context dictionary containing data values

Returns:

Dictionary mapping keys to formatted values

Return type:

dict[str, str]

Examples

>>> engine = LayoutEngine()
>>> layout = {
...     "items": [
...         {"field": "temp", "key": "temperature",
...          "formatter": "number", "formatter_params": {"suffix": "°"}},
...         {"field": "price", "key": "cost", "formatter": "price"}
...     ]
... }
>>> result = engine.build_dict_str(layout, {"temp": 31, "price": 32})
>>> result
{'temperature': '31°', 'cost': '$32.00'}

viewtext.engine.get_layout_engine(field_registry: BaseFieldRegistry | None = None) → LayoutEngine

Get or create the global layout engine instance.

Parameters:

field_registry (BaseFieldRegistry, optional) – Registry to use when creating a new engine instance

Returns:

The global layout engine instance

Return type:

LayoutEngine

Raises:

ValueError – If no global engine exists and no field_registry is provided

Examples

>>> from viewtext import get_layout_engine, BaseFieldRegistry
>>> registry = BaseFieldRegistry()
>>> engine = get_layout_engine(field_registry=registry)

viewtext.formatters

Formatter registry for text output formatting.

This module provides the FormatterRegistry class with built-in formatters for text, numbers, prices, dates, relative times, and template strings.

class viewtext.formatters.FormatterRegistry

Bases: object

Registry for value formatting functions.

The formatter registry manages formatter functions that transform values into formatted strings. Includes built-in formatters for common use cases.

_formatters

Internal dictionary mapping formatter names to functions

Type:

dict[str, Callable]

Examples

>>> registry = FormatterRegistry()
>>> formatter = registry.get("price")
>>> formatter(123.45, symbol="$", decimals=2)
'$123.45'

__init__() → None

Initialize the formatter registry with built-in formatters.

register(name: str, formatter: Callable) → None

Register a formatter function.

Parameters:

• name (str) – The formatter name to register

• formatter (Callable) – A callable that takes a value and keyword arguments and returns a formatted string

Examples

>>> registry = FormatterRegistry()
>>> def custom_formatter(value, **kwargs):
...     return f"Custom: {value}"
>>> registry.register("custom", custom_formatter)

get(name: str) → Callable

Retrieve a registered formatter function.

Parameters:

name (str) – The formatter name to retrieve

Returns:

The formatter function

Return type:

Callable

Raises:

ValueError – If the formatter name is not registered

Examples

>>> registry = FormatterRegistry()
>>> formatter = registry.get("text")
>>> formatter("hello", prefix=">> ")
'>> hello'

viewtext.formatters.get_formatter_registry() → FormatterRegistry

Get the global formatter registry instance.

Returns:

The global formatter registry

Return type:

FormatterRegistry

Examples

>>> from viewtext import get_formatter_registry
>>> registry = get_formatter_registry()
>>> formatter = registry.get("price")

viewtext.loader

viewtext.validator

viewtext.registry_builder