python

This directory contains the Python-specific implementation for the Talon voice coding system. It translates high-level programming voice actions into syntax-accurate Python code, managing everything from basic keywords and formatting to complex typing conventions, docstrings, and syntax trees.

Core Architecture and Actions

The backend engine of the Python programming integration is defined in python.py. This file performs several critical roles to bootstrap and support Python editing:

• Context Scope: It scopes all contained rules and lists specifically to Python files using the code.language: python match rule.
• Operator Mapping: It overrides the default operator behaviors using the Operators configuration class. This translates spoken commands for math, comparison, assignment, and bitwise operations into their precise Python string representations (for example, mapping bitwise operators like & or Python-specific math operators like floor division // and exponentiation **).
• Structure Code Formatting: It overrides the generic programming actions defined in Talon's global library. For example:
  • code_private_function inserts a private Python method with a leading underscore (e.g., def _my_method():).
  • code_public_function inserts a public Python method (e.g., def my_method():).
  • Boolean, nullability (None), and type annotation insertions are set up to match idiomatic Python styles.
• Exception Lists: It dynamically generates a dictionary mapping lowercase spoken variations of standard built-in Python exceptions (e.g., ZeroDivisionError, ImportError, UnicodeDecodeError) to their CamelCase class names.

Advanced Generic Type Parsing

python.py implements custom capturing logic to facilitate modern Python type hinting. By declaring the <user.python_generic_type> capture, the system parses spoken syntax to construct complex nested Python type hints. This enables the dictation of definitions like: * "list of string" $\rightarrow$ list[str] * "list of string or integer" $\rightarrow$ list[str | int] * "tuple of optional of integer done string" $\rightarrow$ tuple[Optional[int], str]

Spoken Commands and Syntax Insertion

The structural glue mapping user speech to text layouts is declared in python.talon.

• Global Settings: It configures formatting styles, establishing SNAKE_CASE as the default formatter for functions and variables.
• Tag Activation: It activates relevant modular programming tags (like user.code_operators_math, user.code_functions_common, and user.code_comment_documentation) so that generic voice programming patterns function contextually in Python.
• Python-Specific Phrases: It binds direct spoken phrases to Python blocks:
  • state try $\rightarrow$ try:\n
  • state past $\rightarrow$ pass
  • self taught $\rightarrow$ self.
  • raise and except commands are integrated with the dynamic list of standard exceptions generated in python.py.
• Docstring Documentation: It enables Sphinx/reStructuredText-compliant docstring fields (such as :param:, :type:, :rtype:) through specialized spoken commands.

Dictionary and Keyword Lists

To feed the generic Talon rules with Python vocabulary, the directory defines several .talon-list files. These lists map natural speech patterns to language-specific syntaxes, keeping the core parser clean and modular.

• code_keyword.talon-list: Defines spoken triggers for most Python statement keywords and control flow operators, such as async, await, class, elif, lambda, match, and yield.
• code_keyword_unprefixed.talon-list: Holds keywords that can safely be spoken without a "state" prefix (such as continue or finally).
• code_type.talon-list: Maps standard Python types and typing module annotations (such as Callable, Iterable, NoReturn, and UnionAny).
• code_common_function.talon-list: Registers Python built-in functions like len, print, range, and type conversions like int or str.
• code_common_method.talon-list: Registers standard object methods commonly used across lists, strings, and dictionaries, such as append, join, split, strip, and values.