Python API Reference

This reference documents the stable public wrapper surface in tuix.core for v0.6 across 13 modular packages, matching the C header hierarchy and original `tuix_system_action` naming conventions.

Import Pattern

from tuix.core import (
    core,
    scene,
    object as objects,
    buffer,
    content_builder,
    command_buffer,
    compositor,
    event,
    input,
    renderer,
    sub_cycles,
    tuix,
    viewport,
)

Common Conventions

Scene names, builder names, labels, and titles accept bytes or str (bytes preferred for native C performance).
Character arguments accept single-byte bytes, UTF-8 strings, or integer codepoints.
Widget manipulation methods take `obj_ptr`. Resolve it once with `objects.get_object_by_uid(uid)` and reuse it.
Native setters return TUIX_RC_OK (0) on success and a negative TUIX_RC_* error code on failure. Snapshot getters return dict or None.
All native functions standardize on canonical `tuix_system_action` naming across both C and Python wrappers.

Coverage Map (13 Modular Packages)

Module Package	Documented Surface & Key Functions	Documentation Section
tuix.core.core	Engine lifecycle (`tuix_core_init`, `tuix_core_shutdown`), main loop (`tuix_core_loop_run`), mutex synchronization, frame stats, and mouse capture.	Public API -> Core & Probing
tuix.core.tuix	Terminal capability probing (`tuix_terminal_probe`), policies (`tuix_terminal_select_policy`), Unicode codepoint classification, and sound bridge.	Public API -> Core & Probing
tuix.core.scene	Scene allocation (`tuix_scene_init`), selection (`tuix_scene_select`), focus routing, modal overlays, transactions, and pixel compaction.	Public API -> Scenes API
tuix.core.buffer	Buffer tree hierarchy (`tuix_buffer_set_parent`), z-index, layout slots, grid placement, dirty marking, and screen metrics.	Public API -> Buffers API
tuix.core.content_builder	Standard builder registry (`tuix_builder_register_standard`), canonical builder constants, layout/grid constants, and unregistration.	Public API -> Builders
tuix.core.object	Object lifecycle allocation (`create_object`, `create_object_ex`, `get_object_by_uid`, `tuix_object_free_ptr`) and snapshot inspection.	Public API -> Objects API
tuix.core.input	Input listener thread (`tuix_input_start`, `tuix_input_stop`), snapshot queue retrieval (`tuix_input_get_snapshot`), and synthetic key injection.	Public API -> Input API
tuix.core.viewport	Virtual content dimensions (`tuix_object_get_viewport_content_size`), scroll offsets (`tuix_object_get_viewport_offset`), and insets.	Core Concepts -> Viewports & Virtual Space
tuix.core.command_buffer	Batched binary opcode execution (`tuix_command_buffer_execute`) and atomic frame-boundary commits (`tuix_batch_global_commit`).	Advanced -> Internal & Advanced APIs
tuix.core.compositor	Native compositing traversal (`tuix_compositor_compose_scene`), hitmap generation, traversal caching, and geometry resolution.	Advanced -> Internal & Advanced APIs
tuix.core.renderer	Direct ANSI streaming emission (`tuix_renderer_stream`), native buffer handles, binary patch rendering, and performance stats.	Advanced -> Internal & Advanced APIs
tuix.core.event	Thread-safe native-to-Python event queue flushing (`tuix_event_commit_python`) and dispatch bridge.	Advanced -> Internal & Advanced APIs
tuix.core.sub_cycles	Fine-grained sub-cycle registration (`tuix_sub_cycle_init`) and animation loops.	Advanced -> Internal & Advanced APIs

Typical Boot Sequence

from tuix.core import core, scene, object as objects, content_builder, input, tuix

# 1. Prepare terminal and probe environment
tuix.tuix_terminal_prepare()
tuix.tuix_terminal_probe()
tuix.tuix_terminal_select_policy()

# 2. Initialize native core engine and builders
core.tuix_core_init()
content_builder.tuix_builder_register_standard()

# 3. Create scene and start input listener
scene.tuix_scene_init(b'Main')
scene.tuix_scene_select(b'Main')
input.tuix_input_start()

# 4. Create UI widgets
uid = objects.create_object(content_builder.TEXT, b'Main', 0.5, 0.1, 0.1, 0.1)
obj = objects.get_object_by_uid(uid)
objects.tuix_text_set_text(obj, 'Ready')

# 5. Main loop
while running:
    core.tuix_core_loop_run()

# 6. Teardown
input.tuix_input_stop()
core.tuix_core_shutdown()
tuix.tuix_terminal_restore()