Skip to content

talon

The directory provides a mock implementation of the Talon Voice API. When running unit tests or static analysis tools outside of the active Talon Voice application runner—such as in a continuous integration (CI) pipeline or a local command-line terminal—the native, closed-source talon APIs are not accessible.

These stub files prevent ModuleNotFoundError crashes and allow developers to validate the logic of their community scripts in isolation.

Key Components

Core API Stubs

The __init__.py file acts as the primary mock entry point for the talon package. It mimics core Talon infrastructure:

  • Actions Management: Implements the Actions and RegisteredActionsAccessor classes to mimic Talon's action dispatching system. It comes with built-in mock definitions for basic actions like key, insert, sleep, and edit.selected_text. It supports registering custom test actions via register_test_action and resetting them between runs with reset_test_actions.
  • Modules and Contexts: Provides dummy implementations of the Module and Context classes. The Module.action_class decorator automatically registers class methods into the mock actions system under the user namespace using Python's inspect library.
  • UI and Resources: Stubs out UI frameworks (ImgUI, UI), configuration storage (Settings, Registry), and resource handling (Resource redirects file requests to standard Python files; App defaults the system platform to "mac" during test runs).
  • Environment Indicator: Exposes a test_mode = True flag, which allows user-space scripts to detect that they are running within a test suite and adapt their behavior accordingly.

Grammar Stubbing

The grammar.py file provides empty stub classes for Talon's speech-parsing engine:

  • Phrase and vm.Phrase: These classes are stubbed as empty structures. This allows user code containing type annotations or runtime checks like isinstance(input, Phrase) to run smoothly and return False during testing without throwing reference errors.

Experimental API Stubs

The experimental subdirectory mimics the talon.experimental package:

  • It provides mock placeholders for advanced UI elements like TextArea, Span, DarkThemeLabels, and LightThemeLabels.
  • Setting these components to safe defaults (such as None) allows scripts relying on experimental UI layouts to be imported and parsed in non-GUI testing environments without causing initialization crashes.

How the Stubs Work Together

When a test runner (like pytest) executes a test suite, it prepends the stub directory to the Python import path (sys.path). When a script runs import talon or from talon import Context, Module, actions, Python loads these mock definitions instead of searching for the real, closed-source Talon runtime.

During execution:

  1. Module and Context definitions are evaluated, capturing settings, lists, and action registrations.
  2. Custom user action classes are registered directly into the mock Actions registry via Python decorators in the Module mock.
  3. Tests can mock specific actions dynamically and assert that user-defined commands trigger the correct internal mock behaviors.