Skip to content

TaskTonic API Reference

This document provides a technical overview of the core classes, methods, and framework directives available in the TaskTonic framework.

Framework Directives (Meta-Flags)

Configuration variables defined at the class level to alter the framework's internal handling of that class are referred to as Framework Directives or Tonic Meta-Flags. They must be defined directly under the class definition, not inside __init__.

1. Service & Topology Directives

These flags control how a Liquid/Tonic is instantiated and how it fits into the parent-child (base-infusion) hierarchy.

  • _tt_is_service (Type: bool | str)
    • Functionality: Marks the class as a Singleton Service. If set to True, it uses the class name (or explicitly passed name). If set to a str (e.g., "networking_selector_service"), it enforces that specific service name globally. Any subsequent instantiations of this class will return the already running instance from the Ledger.
  • _tt_base_liquid (Type: bool)
    • Functionality: If True, the Liquid will act as a root entity. It will not adopt the calling Tonic as its parent (base). This is extremely useful for detached background services.
  • _tt_force_name (Type: str)
    • Functionality: Forces instances of this class to always use the specified name, completely ignoring any name kwargs passed during __init__.

2. Lifecycle & Garbage Collection Directives

These flags dictate how Tonics and Catalysts behave when their tasks or dependencies are completed.

  • _tt_auto_finish_without_infusions (Type: bool)
    • Functionality: Determines whether a Catalyst or Tonic should automatically trigger its finish() sequence when all its active guest infusions (children/tasks) have completed. Set to False for persistent background servers.
  • _tt_non_critical_infusion (Type: bool)
    • Functionality: Marks a Tonic as a background or "daemon" task. If a Catalyst or parent Liquid only has _tt_non_critical_infusions remaining attached to it, the parent will shut down instead of staying alive for them.

3. Logging Directives

These flags override the default logging configuration inherited from the application formula or parent base.

  • _tt_force_log_mode (Type: ttLog enum | str)
    • Functionality: Hardcodes a specific logging verbosity level for the class (e.g., ttLog.QUIET or 'quiet'). It ensures the Tonic logs at this specific level regardless of global settings.
  • _tt_force_stealth_logging (Type: bool)
    • Functionality: A forceful override to completely silence the Liquid (ttLog.STEALTH), suppressing all lifecycle and sparkle logs. Used heavily by high-frequency internal classes (like ttTimer or SelectorService) to prevent console spam and memory overhead.

Base Architecture

ttLiquid

The foundational class. It manages identity, Ledger registration, lifecycle status, and parent/child (base/infusion) hierarchy.

Properties: * id (int): Unique identifier from the Ledger. * name (str): Human-readable name. * base (ttLiquid): The parent context that created this liquid. * infusions (list): Child liquids created by this instance. * life_cycle (ttLC): The current execution state.

Core Methods: * finish(): Initiates the static destruction sequence. Cascades to all infusions. * set_log_mode(log_mode): Dynamically changes the logging verbosity (e.g., ttLog.QUIET).

ttTonic

Inherits from ttLiquid. The active worker agent. It adds the Sparkle execution queue, State Machine, and logging capabilities.

State Machine Methods: * to_state(state, force_reenter=False): Requests a transition to a new state. * reenter_current_state(): Forces on_exit then on_enter for the current state. * get_active_state() / get_current_state_name(): Returns the string name of the current state.

Lifecycle Hooks (To be overridden): * ttse__on_start(self): Fired immediately after creation. * ttse__on_enter(self): Fired when entering any state. * ttse__on_exit(self): Fired when leaving any state. * ttse__on_finished(self): Fired during the shutdown sequence for cleanup.

Commands: * ttsc__finish(): Queues the command to gracefully shut down this Tonic and its children.

ttCatalyst

Inherits from ttTonic. The engine that owns a thread and a queue, processing Sparkles.

Core Methods: * start_sparkling(): Begins the main execution loop. Blocks if it is the Main Catalyst (id 0); otherwise spawns a background thread. * sparkle(): The actual continuous while loop that fetches and executes queue items.

ttFormula

The application entry point. Configures the environment and starts the Main Catalyst.

Methods (To be overridden): * creating_formula(): Return a tuple of configuration settings (e.g., logging rules, project name). * creating_main_catalyst(): Override to use a custom Main Catalyst (like ttPyside6Ui or ttDistiller). * creating_starting_tonics(): Instantiate your initial application Tonics here.

Central Utilities

ttLedger

A thread-safe singleton registry. * update_formula(formula, val=None): Injects settings into the global ttStore. * get_tonic_by_name(name): Retrieves a running Tonic instance. * get_service_by_name(service): Retrieves a running Singleton Service.

ttSparkleStack

Thread-local context manager tracking execution flow. * get_tonic(): Returns the Tonic currently executing a Sparkle. * get_stack(): Returns the current execution stack payload.

Timers (TaskTonic.ttTimer)

All timers are ttLiquid instances. They start immediately upon creation.

Common Methods: * .start(): Starts or resumes the timer. * .stop(): Halts the countdown. * .restart(): Stops, recalculates expiration, and starts again. * .change_timer(...): Modifies the duration without restarting. * .finish(): Destroys the timer.

Timer Classes: * ttTimerSingleShot(seconds, name, sparkle_back): Fires once. Useful for timeouts/watchdogs. * ttTimerRepeat(seconds, name, sparkle_back): Fires continuously at the set interval. * ttTimerPausing(seconds, name, sparkle_back, start_paused): Includes .pause() and .resume() methods. * ttTimerEveryYear, ttTimerEveryMonth, ttTimerEveryWeek, ttTimerEveryDay, ttTimerEveryHour, ttTimerEveryMinute: Absolute scheduled timers (e.g., ttTimerEveryWeek(day="sunday", hour=2)).

Data Store (ttStore and Item)

Store (Accessed via self.ledger.formula)

  • at(path) -> Item: Generates a cursor for a specific path.
  • get(path, default=None): Quick read.
  • set(path_or_data, value, notify=True): Write data (supports dict batching).
  • subscribe(path, callback, recursive=False, extract=None, trigger_now=False, ignore_source=None, owner=None): Binds a callback to data mutations.
  • unsubscribe(target): Removes a listener (usually pass self as the target).
  • group(source_id=None, notify=True): Context manager to batch writes.
  • source(source_id): Context manager to tag writes with an origin ID.

Item (Cursor)

  • .v: Property to read/write the value.
  • .parent: Returns cursor to parent container.
  • .list_root: Returns cursor to nearest array container (#).
  • set(data, value, notify=True): Write relative to cursor.
  • get(key, default=None): Read relative child.
  • append(prefix=None): Creates a new auto-incrementing child node.
  • children(prefix=None): Iterator of child Item nodes.
  • link_to(target_path, bubble_events=False): Creates a symlink alias to another store path.

Testing (ttDistiller)

Replaces ttCatalyst for synchronous testing and trace generation.

Core Methods: * sparkle(sparkle_count=None, timeout=None, till_state_in=None, till_sparkle_in=None, contract=None): Cranks the engine. Returns a status dictionary trace. * stat_print(statuses): Prints a formatted execution trace to the console.

Markdown Generator API: * md_create(title): Initializes the document. * md_add_txt(text): Appends custom text. * md_add_mermaid_flow(statuses): Generates an SVG-style sequence diagram. * md_add_trace_table(statuses): Generates a detailed step-by-step table. * md_get_output(): Returns the compiled Markdown string.