AutoCorrect2 Hotstrings

Description	Generate typo-based AutoHotkey hotstrings and validate them against AutoCorrect2
Author(s)	Or Fadida
Repository	https://github.com/orfadida2000/autocorrect2-hotstring-generation
Copyright	Copyright © 2026 Or Fadida

AutoCorrect2 Hotstring Generation

This project generates plausible keyboard-typo hotstrings, removes ambiguous generated mappings, checks the remaining candidates against AutoCorrect2, and can append accepted definitions to a dedicated generated AutoHotkey include file.

The project deliberately separates four concerns:

• hotstring.core — generic AutoHotkey hotstring models, trigger conversion, option resolution, and conflict semantics;
• hotstring.typo_generation — typo generation and internal ambiguity filtering;
• hotstring.autocorrect2 — AutoCorrect2-specific source loading, candidate rendering, integration checks, and generated-file writing;
• hotstring.cli — command-line parsing, external-input resolution, runtime command construction, and pipeline dispatch.

Project-level orchestration, reporting, and generic file I/O remain at the hotstring package root. The hotstring.__main__ module provides the python -m hotstring entry point and delegates command-line execution to hotstring.cli.application.main.

The processing stages can be used independently. Typo generation does not depend on AutoCorrect2, and AutoCorrect2 checking can operate on manually constructed candidates.

The three workflows are also available through the typo-generation, autocorrect2-check, and full-pipeline subcommands.

See also: Command-line interface for command syntax and shared runtime configuration.

License: This project is licensed under the MIT License.

Project Background

Purpose

AutoCorrect2 Hotstrings is a supporting project for AutoCorrect2. Its purpose is to generate plausible keyboard-typo hotstrings, evaluate whether those hotstrings are safe to use, and prepare accepted corrections for integration with an existing AutoCorrect2 setup.

The project focuses on a problem that becomes increasingly important as an autocorrect library grows: a generated correction must not merely look plausible. Its trigger also needs to behave safely alongside other generated hotstrings and the hotstrings that already exist in AutoCorrect2.

At a high level, the workflow is:

Workflow Diagram

flowchart TD
    A["Target words"] --> B["Generate plausible<br>keyboard typos"]
    B --> C["Remove internally<br>ambiguous mappings"]
    C --> D["Create AutoCorrect2<br>candidates"]
    D --> E["Check against existing<br>AutoCorrect2 hotstrings"]
    E --> F["Keep accepted<br>candidates"]
    F --> G["Optionally write<br>hotstrings and reports"]

The project is therefore not an autocorrect runtime of its own. AutoHotkey and AutoCorrect2 remain responsible for recognizing and executing hotstrings. This project provides generation, analysis, validation, and integration tooling around that existing system.

AutoHotkey and hotstrings

AutoHotkey is a Windows automation and scripting language. One of its core text-automation features is the hotstring.

A hotstring watches typed input for a trigger and reacts when that trigger is recognized. A simple hotstring can replace one piece of text with another, while an execute hotstring can invoke arbitrary AutoHotkey code.

In its simplest form, an autocorrect hotstring maps a misspelled trigger to an intended word.

This makes hotstrings a natural foundation for a continuously running autocorrect system. AutoHotkey also provides options that change how triggers are recognized, including case sensitivity, whether an ending character is required, and whether matching is allowed inside words.

Those recognition rules matter to this project because two hotstrings can interfere even when their trigger strings are not identical. Conflict detection therefore needs to model the relevant AutoHotkey hotstring semantics rather than performing only simple string equality checks.

The original AutoCorrect.ahk

The lineage begins with AutoCorrect.ahk, initially released by Jim Biancolo on September 24, 2006.

The original script implemented autocorrection in AutoHotkey using lists of common misspellings. Its own introduction emphasized an important limitation: an autocorrect system should focus on corrections that are sufficiently unambiguous rather than attempting to silently correct every possible misspelling.

That distinction remains useful today. An incorrect automatic correction can be worse than leaving a questionable word untouched, because the replacement may look valid and no longer be caught by a conventional spellchecker.

The script was expanded over time with additional misspellings and correction rules, helping establish the AutoHotkey hotstring-based autocorrect approach from which later projects evolved.

AutoCorrect2

AutoCorrect2 is a modern AutoHotkey v2 project built on that lineage.

It began as a version of the earlier AutoCorrect.ahk, but has evolved into a suite of interrelated AutoHotkey v2 scripts and tools for using, creating, managing, analyzing, and improving autocorrect hotstrings.

That broader tooling is important: maintaining a large autocorrect collection is not just a matter of adding more typo/replacement pairs. It also involves examining trigger behavior, refining entries, managing generated content, and avoiding corrections that would interfere with valid typing or with other hotstrings.

AutoCorrect2 provides the runtime environment and surrounding tools in which the hotstrings produced by this project are intended to operate.

Where this project fits

The relationship can be summarized as:

Relationship Diagram

flowchart TD
    A["AutoHotkey"] -->|"runtime for"| B["AutoCorrect.ahk"]
    A -->|"runtime for"| C["AutoCorrect2"]
    B -->|"predecessor of"| C
    D["AutoCorrect2 Hotstrings<br>(this project)"] -->|"supports"| C

This project operates at the generation and analysis layer.

Given target words, it can generate typo candidates that mimic plausible keyboard mistakes. Those candidates are then filtered before integration:

• ambiguous generated mappings can be removed;
• generated hotstrings can be checked against one another;
• candidates can be checked against existing AutoCorrect2 hotstrings;
• AutoHotkey recognition rules relevant to conflicts can be taken into account;
• accepted entries can be rendered in AutoCorrect2-compatible form;
• reports can explain which candidates were accepted or rejected.

The intent is not to maximize the number of generated corrections. The intent is to produce a set of useful candidates while reducing unsafe or ambiguous automatic behavior.

Design principle

A generated typo is only useful if correcting it automatically is reasonably safe.

That principle influences the architecture of the project. Generation and conflict analysis are deliberately separate concerns: producing a plausible typo does not automatically mean that the corresponding hotstring should be added.

The project therefore treats generation as the beginning of the pipeline, not the final decision.

Further reading

• AutoHotkey
• AutoHotkey v2 hotstrings
• AutoCorrect2 on GitHub
• Original AutoCorrect.ahk source mirror

Getting started

Install

The project uses uv and is configured as a non-package project. A normal sync installs the runtime dependency plus the default dev and docs groups:

uv sync

Configure AutoCorrect2

The project does not contain a machine-specific AutoCorrect2 path. Commands which read AutoCorrect2 resolve the project directory in this order:

1. --autocorrect2-project-dir;
2. the AUTOCORRECT2_PROJECT_DIR process environment variable;
3. a dotenv file selected with --env-file;
4. .env at the repository root.

For normal local use, copy the committed example and edit the value:

Copy-Item .env.example .env

AUTOCORRECT2_PROJECT_DIR=H:/Projects/AutoCorrect2

The local .env is ignored by Git. A relative path in a dotenv file is resolved relative to that file. Relative command-line and process-environment paths are resolved relative to the current working directory.

Add a one-time #Include for Core/GeneratedHotstrings.ahk in the same active AutoCorrect2 hotstring context as the main autocorrection library. The generated file remains project-owned and is scanned on later runs when it exists.

Run a workflow

The command-line interface mirrors the three public pipeline functions:

uv run python -m hotstring --help

For example, run the complete workflow with a UTF-8 file containing one source word per non-empty line:

uv run python -m hotstring full-pipeline `
    --words-file .\words.txt `
    --single-attempts 100 `
    --multi-attempts 100 `
    --multi-min-length 5 `
    --report .\hotstring-generation-report.txt

Those sampling values are examples rather than application defaults. The CLI requires them so every run states its sampling policy explicitly. Use --write-accepted to opt into modifying Core/GeneratedHotstrings.ahk; without it, AutoCorrect2-aware workflows only read and report.

Add -v before the workflow name for progress messages, or -vv for debugging details:

uv run python -m hotstring -v full-pipeline --help

Build the documentation

uv run mkdocs serve

The MkDocs configuration uses these committed stylesheet files under docs/assets/stylesheets/:

• catppuccin-latte.css
• catppuccin-mocha.css
• dracula.css
• extra.css

Command-line usage

The hotstring.__main__ module provides the python -m hotstring entry point and delegates command-line execution to main() which exposes the project's three public workflows as subcommands.

Subcommand	Workflow
typo-generation	Generate typo mappings and remove internally ambiguous mappings
autocorrect2-check	Check supplied candidates against existing AutoCorrect2 hotstrings
full-pipeline	Generate typo candidates and check the survivors against AutoCorrect2

Display the top-level help or the help for one subcommand with:

uv run python -m hotstring --help
uv run python -m hotstring typo-generation --help
uv run python -m hotstring autocorrect2-check --help
uv run python -m hotstring full-pipeline --help

Logging verbosity

-v and --verbose are repeatable top-level options:

Invocation	Logging level
no verbosity option	Normal command summaries and concise errors
-v	Informational logging
-vv	Debug logging, including a traceback for an unexpected runtime failure

The verbosity option belongs to the top-level parser, so it must appear before the subcommand:

uv run python -m hotstring -v typo-generation ...
uv run python -m hotstring -vv full-pipeline ...

Repeating -v more than twice continues to use debug logging.

Typo generation

typo-generation requires exactly one source of words:

• repeat --word WORD to supply words directly; or
• use --words-file PATH for a UTF-8 file containing one word per line.

Blank lines are ignored, and duplicate words are removed while preserving their first occurrence.

The command creates the project's default ordered TypoGenerationTask sequence from these required arguments:

Argument	Meaning
--single-attempts COUNT	Attempts per eligible word for each forced single-error task
--multi-attempts COUNT	Attempts per eligible word for the mixed two-error task
--multi-min-length LENGTH	Minimum word length for the mixed two-error task

Optional generation arguments are:

Argument	Meaning
--language LANGUAGE	MULTYPO language identifier; defaults to english
--excluding-set / --no-excluding-set	Enable or disable MULTYPO's language excluding set; enabled by default
--keyboard-weights HORIZONTAL VERTICAL	Relative keyboard-neighbor weights; defaults to 9 1
--workers COUNT	Process-pool size; omit it to use the execution layer's default
--report PATH	Write a typo-generation report

For example:

uv run python -m hotstring typo-generation `
    --words-file .\words.txt `
    --single-attempts 100 `
    --multi-attempts 100 `
    --multi-min-length 5 `
    --workers 4 `
    --report .\reports\typo-generation.txt

This subcommand does not load or modify an AutoCorrect2 project.

AutoCorrect2 project directory

The autocorrect2-check and full-pipeline subcommands resolve the local AutoCorrect2 project directory in this order:

1. --project-dir PATH;
2. the process environment variable AUTOCORRECT2_PROJECT_DIR;
3. the dotenv file selected by --env-file PATH;
4. .env at the project root.

Resolution stops at the first configured source. A lower-priority dotenv file is therefore not opened or validated after a command-line or process-environment value has been selected.

A project-root .env file can contain:

AUTOCORRECT2_PROJECT_DIR=H:/Projects/AutoCorrect2

An explicit dotenv file uses the same key:

uv run python -m hotstring autocorrect2-check `
    --env-file .\config\autocorrect2.env `
    --candidate "teh" "the" "B0X"

A relative value read from a dotenv file is resolved relative to that file's directory. A relative --project-dir value or process-environment value is resolved relative to the current working directory.

See AutoCorrect2 configuration for the required source-file layout and generated-file policy.

AutoCorrect2 conflict checking

autocorrect2-check accepts manually supplied AutoCorrect2CandidateHotstring objects without running typo generation.

Supply candidates directly by repeating --candidate with three values:

--candidate TRIGGER REPLACEMENT OPTIONS

For example:

uv run python -m hotstring autocorrect2-check `
    --candidate "teh" "the" "B0X" `
    --candidate "adn" "and" "B0X" `
    --project-dir "H:\Projects\AutoCorrect2" `
    --report .\reports\autocorrect2-check.txt

Alternatively, --candidates-file PATH accepts a UTF-8 JSON file containing a top-level array. Every object must contain exactly the string fields trigger, replacement, and options:

[
  {
    "trigger": "teh",
    "replacement": "the",
    "options": "B0X"
  },
  {
    "trigger": "adn",
    "replacement": "and",
    "options": "B0X"
  }
]

Use the file with:

uv run python -m hotstring autocorrect2-check `
    --candidates-file .\candidates.json

--candidate and --candidates-file are mutually exclusive.

Full pipeline

full-pipeline composes typo generation and AutoCorrect2 conflict checking. It accepts the same word and generation arguments as typo-generation, then converts the surviving mappings into generated B0X candidates before running the AutoCorrect2 check.

For example:

uv run python -m hotstring full-pipeline `
    --words-file .\words.txt `
    --single-attempts 100 `
    --multi-attempts 100 `
    --multi-min-length 5 `
    --workers 4 `
    --report .\reports\full-pipeline.txt

The project directory can come from any of the four configuration sources described above. full-pipeline does not accept --candidate or --candidates-file, because it creates candidates from the typo-generation result.

Reports and generated output

All three subcommands accept --report PATH. Parent directories are created by the reporting layer when required.

AutoCorrect2-aware commands are read-only by default. Supply --write-accepted to append accepted candidates to Core/GeneratedHotstrings.ahk:

uv run python -m hotstring full-pipeline `
    --words-file .\words.txt `
    --single-attempts 100 `
    --multi-attempts 100 `
    --multi-min-length 5 `
    --write-accepted

Writing manually supplied candidates remains subject to the writer's explicit generated-option contract.

Exit statuses

Status	Meaning
0	The selected workflow completed successfully
1	Pipeline execution failed
2	Command-line syntax or resolved runtime configuration was invalid
130	Execution was interrupted from the terminal

Project structure

Project Structure

autocorrect2-hotstring-generation/
├── docs/
│   ├── index.md
│   ├── api/
│   │   ├── index.md
│   │   ├── cli/
│   │   │   ├── index.md
│   │   │   ├── application.md
│   │   │   ├── commands.md
│   │   │   ├── parser.md
│   │   │   └── runtime.md
│   │   ├── core/
│   │   │   ├── index.md
│   │   │   ├── conflicts.md
│   │   │   ├── constants.md
│   │   │   ├── models.md
│   │   │   ├── options.md
│   │   │   └── trigger.md
│   │   ├── autocorrect2/
│   │   │   ├── index.md
│   │   │   ├── source_loading/
│   │   │   │   ├── index.md
│   │   │   │   ├── cache.md
│   │   │   │   ├── loader.md
│   │   │   │   └── parser.md
│   │   │   ├── constants.md
│   │   │   ├── integration.md
│   │   │   ├── models.md
│   │   │   └── writer.md
│   │   ├── typo-generation/
│   │   │   ├── index.md
│   │   │   ├── aggregation.md
│   │   │   ├── execution.md
│   │   │   ├── generation.md
│   │   │   └── models.md
│   │   ├── constants.md
│   │   ├── file-io.md
│   │   ├── pipeline.md
│   │   └── report.md
│   ├── assets/
│   │   ├── icons/
│   │   │   ├── ACicon.ico
│   │   │   └── autocorrect2-spellcheck.svg
│   │   ├── scripts/
│   │   │   └── header-title-link.js
│   │   └── stylesheets/
│   │       ├── dracula.css
│   │       └── extra.css
│   ├── concepts/
│   │   ├── index.md
│   │   ├── autocorrect2.md
│   │   ├── conflict-detection.md
│   │   ├── hotstrings.md
│   │   └── typo-generation.md
│   ├── configuration/
│   │   ├── index.md
│   │   ├── autocorrect2.md
│   │   └── typo-generation.md
│   ├── workflows/
│   │   ├── index.md
│   │   ├── autocorrect2-check.md
│   │   ├── full-pipeline.md
│   │   ├── reporting.md
│   │   └── typo-generation.md
│   ├── command-line.md
│   ├── getting-started.md
│   ├── license.md
│   ├── project-background.md
│   └── project-structure.md
├── hotstring/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli/
│   │   ├── __init__.py
│   │   ├── application.py
│   │   ├── commands.py
│   │   ├── parser.py
│   │   └── runtime.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── conflicts.py
│   │   ├── constants.py
│   │   ├── models.py
│   │   ├── options.py
│   │   └── trigger.py
│   ├── autocorrect2/
│   │   ├── __init__.py
│   │   ├── source_loading/
│   │   │   ├── __init__.py
│   │   │   ├── cache.py
│   │   │   ├── loader.py
│   │   │   └── parser.py
│   │   ├── constants.py
│   │   ├── integration.py
│   │   ├── models.py
│   │   └── writer.py
│   ├── typo_generation/
│   │   ├── __init__.py
│   │   ├── aggregation.py
│   │   ├── execution.py
│   │   ├── generation.py
│   │   └── models.py
│   ├── constants.py
│   ├── file_io.py
│   ├── pipeline.py
│   └── report.py
├── .env.example
├── .gitignore
├── LICENSE
├── mkdocs.yml
├── pyproject.toml
├── README.md
└── uv.lock

Generic AutoHotkey hotstring behavior lives under hotstring/core/. AutoCorrect2-specific knowledge is isolated under hotstring/autocorrect2/, with source loading further separated into its own subpackage. Typo generation remains independent under hotstring/typo_generation/.

The hotstring.cli subpackage forms the command-line application layer:

• parser.py defines command-line syntax;
• runtime.py resolves external input and constructs runtime command objects;
• commands.py dispatches those objects to the public pipelines;
• application.py owns logging, process-level errors, and exit statuses;
• __init__.py re-exports main.

The hotstring.__main__ module provides the python -m hotstring entry point and delegates command-line execution to hotstring.cli.application.main. Other top-level hotstring modules remain responsible for project-level orchestration and infrastructure rather than the generic hotstring domain model.

Concepts

Concepts

The project separates generic AutoHotkey semantics, typo sampling, AutoCorrect2 integration, and orchestration.

The main conceptual boundaries are:

• declared vs resolved hotstring options;
• generic hotstrings vs semantic correction candidates;
• generic candidates vs AutoCorrect2-specific candidates;
• typo generation vs AutoCorrect2 conflict checking;
• report construction vs filesystem output.

These boundaries allow either processing stage to run independently and keep context-dependent AutoHotkey defaults out of the parser itself.

Hotstrings and options

Trigger representations

The generic hotstring model keeps trigger meaning separate from AutoHotkey source spelling.

Each initialized Hotstring stores two trigger representations:

• semantic_trigger — the actual characters AutoHotkey should recognize;
• ahk_trigger — the deterministic, minimally escaped spelling used when rendering AHK source.

The constructor argument trigger is an InitVar, so it is not retained as a third ambiguous representation after initialization.

By default, Hotstring and candidate classes interpret constructor trigger as semantic text. ExistingHotstring receives trigger text extracted from an AHK source file, so it shadows the class policy TRIGGER_INPUT_IS_AHK_SOURCE = True. The base Hotstring.__post_init__() still owns the same resolution algorithm for every subclass:

flowchart LR
    A["Constructor trigger"] -->|"apply class policy"| B["semantic_trigger"]
    B -->|"encode canonically"| C["ahk_trigger"]

When CHECK_TRIGGER_ROUND_TRIP is enabled, initialization also verifies the conversion invariant:

ahk_to_semantic_trigger(ahk_trigger) == semantic_trigger

This is an internal consistency check. A failure indicates a bug in the conversion contract rather than invalid user input.

Trigger conversion and canonicalization

semantic_to_ahk_trigger() produces one deterministic, minimally escaped AHK representation.

ahk_to_semantic_trigger() performs the reverse semantic conversion: it interprets an AHK source spelling and returns the trigger characters that spelling represents. It may therefore accept multiple valid source spellings that have the same semantic result.

During canonical encoding, characters which always require source escaping, such as a literal backtick or supported control characters, are escaped unconditionally. Colons and semicolons are escaped only when their source context requires it:

• : is escaped only as needed to prevent an unescaped :: sequence inside the trigger or against the declaration delimiter;
• ; is escaped only when a literal source space immediately precedes it and it would otherwise begin a comment.

Consequently, multiple valid source spellings can decode to the same semantic trigger. For example:

foo:bar
foo`:bar

both decode to:

foo:bar

and re-encode canonically as the minimally escaped form:

foo:bar

The helpers are therefore intentionally asymmetric with respect to source spelling. The supported semantic round trip is:

ahk_to_semantic_trigger(semantic_to_ahk_trigger(value)) == value

for every semantic trigger accepted by the encoder. Re-encoding arbitrary AHK source is allowed to canonicalize optional or unnecessary escapes.

Case-insensitive matching key

Conflict detection operates on semantic trigger text, never on escaped AHK source spelling. Each hotstring therefore caches a derived case_insensitive_semantic_trigger_key.

On Windows the key is produced with the Microsoft CRT under an explicit C locale to follow AutoHotkey's case-insensitive comparison basis as closely as possible. On non-Windows systems, str.lower() is used as a deterministic fallback. The key is runtime-derived state and is not persisted in the source cache.

Hotstring rendering

Hotstring.render(content=None) renders the canonical option declaration and ahk_trigger, never the constructor input.

content means everything emitted after the declaration's second ::. It is therefore intentionally broader than an inline replacement RHS: depending on AutoHotkey syntax and options, it may be replacement text, executable content, or multiline block content.

The generic Hotstring.to_ahk_string_literal() helper separately handles AHK double-quoted string syntax. It escapes literal backticks and quotes plus all supported AHK control escapes (r, n, b, t, v, a, and f). Trigger encoding and quoted-string encoding remain separate because their syntax rules are different.

Declared option state

HotstringOptions represents what is explicitly declared on one hotstring. Every omitted option uses the shared sentinel:

InheritedState.INHERIT

This is distinct from the actual semantic value of the option. For example, CaseMode contains only real case modes, while inheritance is represented by InheritedState rather than by a synthetic CaseMode.INHERIT member.

Two-state settings use the SettingState members SettingState.ENABLED and SettingState.DISABLED. The * option is exposed semantically as ending_character_optional, so its mapping is direct:

Declaration	Semantic state
*	SettingState.ENABLED
*0	SettingState.DISABLED
omitted	InheritedState.INHERIT

declaration() serializes the parsed semantic state back to one canonical option string. Repeated or contradictory source options therefore collapse to the last effective value rather than being reproduced verbatim.

Resolved option state

ResolvedHotstringOptions is a separate dataclass rather than a subclass of HotstringOptions. Its fields contain only concrete values; none are typed with InheritedState.

ResolvedHotstringOptions.from_options() constructs a resolved object from:

1. one parsed HotstringOptions declaration; and
2. the fully resolved defaults applicable at that declaration position.

Explicit values override those defaults. InheritedState.INHERIT leaves the corresponding default unchanged. This makes resolution context-sensitive without making HotstringOptions itself aware of file position, #Hotstring, or other sources of defaults.

Send mode

The declared SendMode enum represents the three actual hotstring send-mode choices:

INPUT
PLAY
EVENT

The declaration mapping is:

Hotstring option	Declared value
SI	SendMode.INPUT
SP	SendMode.PLAY
SE	SendMode.EVENT
omitted	InheritedState.INHERIT

Input mode has two distinct effective fallback behaviors, so the resolved model uses a separate four-state ResolvedSendMode enum:

class ResolvedSendMode(Enum):
    INPUT_WITH_PLAY_FALLBACK = auto()
    INPUT_WITH_EVENT_FALLBACK = auto()
    PLAY = auto()
    EVENT = auto()

ResolvedHotstringOptions.send_mode is therefore typed as ResolvedSendMode.

The important mappings are:

Effective source	Resolved value
explicit SI	ResolvedSendMode.INPUT_WITH_PLAY_FALLBACK
AutoHotkey built-in default	ResolvedSendMode.INPUT_WITH_EVENT_FALLBACK
SP	ResolvedSendMode.PLAY
SE	ResolvedSendMode.EVENT

InheritedState.INHERIT does not inherently mean INPUT_WITH_EVENT_FALLBACK. It means to use the currently applicable hotstring default. If inheritance eventually reaches AutoHotkey's untouched built-in default, the resulting resolved value is ResolvedSendMode.INPUT_WITH_EVENT_FALLBACK. If an applicable default has already selected SI, SP, or SE, the inherited value resolves according to that default instead.

Candidate hierarchy

The generic model hierarchy is:

Candidate hotstring class hierarchy

classDiagram
    direction TB

    Hotstring <|-- CandidateHotstring
    CandidateHotstring <|-- AutoCorrect2CandidateHotstring

    class CandidateHotstring {
        <<abstract>>
    }

CandidateHotstring stores the semantic replacement and requires a concrete subclass to derive the AutoHotkey content corresponding to that replacement. The public Hotstring.render() contract remains inherited unchanged, so the hierarchy does not narrow the method signature.

AutoCorrect2CandidateHotstring supplies the AutoCorrect2-specific mapping: the replacement is converted to a complete escaped AutoHotkey string literal and wrapped in f(...).

Typo generation

Each source item is treated as exactly one word. For every configured typo distribution and every source word, MULTYPO is sampled generation_attempts_per_word times.

MULTYPO itself receives typo_rate=1.0 for each attempt because every sampling attempt is intended to corrupt the supplied word. The project therefore does not expose the old custom typo_rate argument that previously scaled the number of iterations.

The low-level generator uses insert_typos() directly rather than the sentence-oriented insert_typos_in_text() wrapper. Sentence tokenization and NLTK resources are therefore unnecessary for this workflow.

Raw samples are aggregated by noisy form. A noisy form that maps to exactly one target word becomes a candidate; one that maps to multiple target words is recorded as an internal clash and removed before AutoCorrect2 processing.

Conflict detection

Conflict checking operates on semantic trigger text and effective hotstring matching semantics, not on AHK source spelling or on whether a particular option token happened to be present in the source.

Before matching, a parsed HotstringOptions declaration is converted to a ResolvedHotstringOptions using the defaults that apply at that declaration position. Conflict detection then reads only the resolved recognition fields it needs.

Matching directions

Conflict checking examines both directions:

1. whether an existing hotstring can activate while a candidate is typed;
2. whether the candidate can activate while an existing trigger is typed.

Every occurrence is considered, including overlapping occurrences. The implementation uses repeated str.find() searches advancing by one character, so a trigger such as ana is found at both valid positions in banana.

Recognition options

The checker supports all combinations of the recognition-related hotstring options currently modeled by the project:

• * / *0 — whether an ending character is optional;
• ? / ?0 — whether an alphanumeric predecessor is permitted;
• C, C0, and C1 — effective case matching.

Options unrelated to trigger recognition, such as backspacing, execution, priority, send mode, replacement mode, key delay, or recognizer reset, do not affect conflict recognition.

Boundaries

A matching occurrence has a valid left boundary when one of these is true:

• the occurrence starts at the beginning of the containing trigger;
• the preceding character is non-alphanumeric;
• the tested hotstring permits an alphanumeric predecessor through ?.

The right boundary is valid when one of these is true:

• the tested hotstring does not require an ending character (* is enabled);
• the occurrence reaches the end of the containing trigger, because a later typed ending character can still activate it;
• the following character is in the effective ending-character set.

An ending character may itself appear anywhere inside a hotstring trigger. That is valid AutoHotkey input; the character matters to conflict logic only when it serves as the character immediately following a shorter matched occurrence.

Case matching

If both compared hotstrings are case-sensitive, occurrence and same-trigger checks use their exact semantic_trigger strings.

If either hotstring is case-insensitive, a shared typed casing can exist when their AutoHotkey-compatible case-insensitive semantic keys match. The cached case_insensitive_semantic_trigger_key is derived once from each semantic trigger and reused throughout matching.

On Windows the key uses the Microsoft CRT C-locale lowercase basis. The non-Windows fallback uses str.lower() and includes a defensive slice-based path if lowercasing changes string length.

AutoCorrect2 integration

The AutoCorrect2 layer owns only behavior that is specific to the external AutoCorrect2 project.

Source loading

Existing declarations are loaded through the nested hotstring.autocorrect2.source_loading package:

• parser extracts static hotstring declarations from decoded source text;
• cache persists source fingerprints and minimal extracted state;
• loader coordinates the configured required and optional source files.

The parser is escape-aware. It scans trigger source character by character so escaped colons and backticks cannot be mistaken for the trigger's closing :: delimiter.

Parsed trigger text is supplied to ExistingHotstring in AHK source form. The generic model then derives semantic_trigger, canonical ahk_trigger, parsed options, and the case-insensitive semantic comparison key.

The persistent source cache stores canonical AHK trigger text and canonical option declarations, not semantic or comparison-key state. SHA-256 of the exact source bytes is authoritative for content identity; size and modification time are metadata only. Cached semantic state is rebuilt by the current model every time an entry is restored.

Candidate rendering and output

Approved generated candidates are represented by AutoCorrect2CandidateHotstring. Its concrete replacement-to-content mapping wraps a safely escaped AutoHotkey string literal in AutoCorrect2's f(...) helper.

Generated candidates are not inserted into upstream-maintained AutoCorrectHotstrings.ahk. They are appended to Core/GeneratedHotstrings.ahk, which AutoCorrect2 includes once through a manually added #Include directive.

The writer enforces the generated-file B0X contract. Generic conflict detection is deliberately independent of that output policy and supports other recognition-option combinations.

Keeping generated content separate allows later conflict checks to inspect previously generated entries without modifying upstream-maintained files.

Workflows

Workflows

Three public workflows are available through both Python APIs and matching CLI subcommands:

1. standalone typo generation through run_typo_generation() and typo-generation respectively;
2. standalone AutoCorrect2 conflict checking through run_autocorrect2_check() and autocorrect2-check respectively;
3. the composed workflow through run_full_pipeline() and full-pipeline respectively.

The full workflow reuses the first two rather than duplicating their logic. Typo generation remains independent of AutoCorrect2; the adaptation from a noisy-word mapping to AutoCorrect2CandidateHotstring belongs to the composed pipeline.

See also: Command-line interface for command syntax and shared runtime configuration.

Full pipeline

run_full_pipeline() composes run_typo_generation() with run_autocorrect2_check() and returns a FullPipelineResult:

Full Pipeline Workflow

flowchart TD
    A["Source words and<br>generation settings"] --> B["Generate typo<br>mappings"]
    B --> C["TypoGenerationResult"]
    C -->|"candidate mappings"| D["Create B0X<br>AutoCorrect2 candidates"]
    D --> E["Check against<br>AutoCorrect2"]
    E --> F["AutoCorrect2CheckResult"]
    C --> G["FullPipelineResult"]
    F --> G

The adaptation step converts each surviving noisy-to-target mapping into an AutoCorrect2CandidateHotstring using the fixed generated option set B0X. Typo generation itself has no dependency on HotstringOptions or AutoCorrect2.

The full pipeline disables stage-specific report writing while composing the two stages and creates one combined report at the end when requested.

Command-line usage

Run the composed workflow with full-pipeline:

uv run python -m hotstring full-pipeline `
    --words-file .\words.txt `
    --single-attempts 100 `
    --multi-attempts 100 `
    --multi-min-length 5 `
    --workers 4 `
    --report .\reports\full-pipeline.txt

The AutoCorrect2 project directory is resolved from --project-dir, the process environment, an explicit dotenv file, or the project-root .env.

The command remains read-only unless --write-accepted is supplied. It does not accept manually supplied candidates because it creates B0X candidates from the typo-generation result.

See also: Command-line interface for all shared options.

Typo generation

This standalone workflow generates and filters typo mappings without loading AutoCorrect2 data.

run_typo_generation() accepts source words, an ordered sequence of TypoGenerationTask objects, a TypoGenerationConfig, and an optional n_workers value.

Typo Generation Workflow

flowchart TD
    A["Source words"] --> D["Execute typo-generation<br>tasks"]
    B["Generation tasks"] --> D
    C["Configuration<br>and worker count"] --> D
    D --> E["Raw MULTYPO samples"]
    E --> F["Aggregate and classify<br>generated mappings"]
    F --> G["TypoGenerationResult"]

TypoGenerationResult.candidates maps each unambiguous noisy form to exactly one target word. clashes contains noisy forms that mapped to multiple target words and are therefore removed before any AutoCorrect2 processing.

This workflow has no dependency on AutoCorrect2 hotstring models or option policies.

Command-line usage

Run standalone typo generation with typo-generation:

uv run python -m hotstring typo-generation `
    --words-file .\words.txt `
    --single-attempts 100 `
    --multi-attempts 100 `
    --multi-min-length 5 `
    --workers 4 `
    --report .\reports\typo-generation.txt

The command accepts either repeated --word arguments or one --words-file, but not both. It does not load or modify AutoCorrect2.

See also: Command-line interface for all generation options.

AutoCorrect2 conflict checking

Use this workflow when candidate hotstrings already exist and need to be checked against the active hotstrings in a configured AutoCorrect2 project.

run_autocorrect2_check() accepts a sequence of AutoCorrect2CandidateHotstring objects:

Conflict Checking Workflow

flowchart TD
    A["Supplied candidates"] --> D["Resolve options and<br>assess conflicts"]
    B["Configured AutoCorrect2<br>source files"] --> C["Load existing<br>hotstrings"]
    C --> D
    D --> E["AutoCorrect2CheckResult"]

Typo generation is not involved. The returned AutoCorrect2CheckResult partitions the supplied candidates into accepted and rejected groups.

Each supplied candidate retains its semantic replacement and derives the AutoCorrect2-compatible AutoHotkey content used when it is rendered.

The pipeline can optionally append accepted candidates to the generated include file. The AutoCorrect2 writer owns the generated-file location and output policy, while generic filesystem operations remain in hotstring.file_io.

Command-line usage

Supply candidates directly by repeating --candidate:

uv run python -m hotstring autocorrect2-check `
    --candidate "teh" "the" "B0X" `
    --candidate "adn" "and" "B0X" `
    --project-dir "H:\Projects\AutoCorrect2" `
    --report .\reports\autocorrect2-check.txt

Each occurrence receives the semantic trigger, semantic replacement, and hotstring option string.

Alternatively, use --candidates-file with a UTF-8 JSON array:

[
  {
    "trigger": "teh",
    "replacement": "the",
    "options": "B0X"
  },
  {
    "trigger": "adn",
    "replacement": "and",
    "options": "B0X"
  }
]

uv run python -m hotstring autocorrect2-check `
    --candidates-file .\candidates.json

--candidate and --candidates-file are mutually exclusive. The command is read-only unless --write-accepted is supplied.

See also: Command-line interface for project-directory resolution and all command options.

Reporting

Report builders return list[str] and never write files themselves:

• create_typo_generation_report()
• create_autocorrect2_report()
• create_full_pipeline_report()

The full report reuses the two stage-specific report bodies. Run-level framing belongs to build_report_document(), which can add metadata that should appear only once around the combined body.

Only the pipeline layer decides when a report is written and delegates the filesystem operation to hotstring.file_io.

Configuration

Configuration

Configuration is divided between AutoCorrect2 integration and typo-generation behavior. These concerns are independent: standalone typo generation does not require an AutoCorrect2 project directory.

AutoCorrect2 integration

AutoCorrect2 configuration explains how the local AutoCorrect2 project directory is resolved, including command-line, environment-variable, and dotenv sources. It also describes generated output and the explicit --write-accepted requirement.

Typo generation

Typo-generation configuration describes the generation settings represented by TypoGenerationConfig, the ordered TypoGenerationTask sequence, and execution settings such as the worker count.

See also: Command-line interface for command syntax and all command options.

Typo-generation configuration

TypoGenerationConfig contains settings shared by every task in one generation run:

• language;
• use_excluding_set;
• horizontal_vs_vertical.

Individual sampling policies are represented by TypoGenerationTask. Each task defines:

• its typo-operation distribution;
• its typo rate;
• its generation attempts per eligible word;
• its minimum eligible word length.

Default CLI task set

The CLI uses create_default_typo_generation_tasks() to construct the ordered default task sequence:

• one forced single-error task for each supported operation distribution;
• one mixed two-error task.

The required CLI arguments are:

Argument	Runtime setting
--single-attempts COUNT	Attempts per word for each forced single-error task
--multi-attempts COUNT	Attempts per word for the mixed two-error task
--multi-min-length LENGTH	Minimum word length for the mixed two-error task

Shared generator settings use:

Argument	Runtime setting
--language LANGUAGE	TypoGenerationConfig.language
--excluding-set / --no-excluding-set	TypoGenerationConfig.use_excluding_set
--keyboard-weights HORIZONTAL VERTICAL	TypoGenerationConfig.horizontal_vs_vertical

Execution setting

--workers COUNT becomes the pipeline's n_workers argument. Worker count is not part of TypoGenerationConfig because it changes how the requested work is executed, not the requested generation semantics.

AutoCorrect2 configuration

Project directory

The project does not contain a hard-coded local AutoCorrect2 path. The CLI resolves the directory in this order:

1. --project-dir PATH;
2. the process environment variable AUTOCORRECT2_PROJECT_DIR;
3. the dotenv file selected by --env-file PATH;
4. .env at the project root.

Resolution stops at the first configured source. Relative values from a dotenv file are resolved relative to that file's directory. Relative command-line and process-environment values are resolved relative to the current working directory.

A dotenv file uses:

AUTOCORRECT2_PROJECT_DIR=H:/Projects/AutoCorrect2

Required sources

The selected AutoCorrect2 project directory must contain:

• Core/AutoCorrectHotstrings.ahk
• Core/PersonalHotstrings.ahk
• Includes/DateTool.ahk

Core/GeneratedHotstrings.ahk is optional on the first run and is scanned once it exists.

Generated output

AutoCorrect2-aware commands are read-only by default. --write-accepted enables appending accepted candidates to Core/GeneratedHotstrings.ahk.

Candidates supplied manually to autocorrect2-check must satisfy the writer's explicit generated-option contract before they can be written. The full pipeline creates generated candidates with the required B0X options.

Matching defaults

HotstringOptions does not bake AutoHotkey defaults into omitted fields. Omitted values remain the INHERIT member of InheritedState until a ResolvedHotstringOptions is created with the defaults that apply at that source position.

Resolution combines the parsed declaration with the fully resolved defaults applicable at that source position:

Resolution Diagram

flowchart TD
    A["HotstringOptions<br>declaration"] --> C["Resolve inherited<br>fields"]
    B["Applicable<br>resolved defaults"] --> C
    C --> D["ResolvedHotstringOptions<br>effective state"]

Until positional directive analysis is implemented, the AutoCorrect2 pipeline can resolve declarations against the configured built-in/default option object.

The conflict checker currently assumes the configured ending-character set and uses only the resolved recognition-related fields required for matching.

API Reference

API reference

The API reference mirrors the Python package hierarchy and is rendered directly from source docstrings with mkdocstrings.

• hotstring.core contains generic AutoHotkey hotstring behavior.
• hotstring.autocorrect2 contains AutoCorrect2-specific integration, including the nested source_loading subpackage.
• hotstring.typo_generation contains typo-generation functionality.
• hotstring.cli contains command-line parsing, runtime configuration, and pipeline dispatch.
• Top-level hotstring modules such as pipeline, report, and file_io are documented directly under this API section.

The conceptual and workflow documentation should be used for architectural context; these pages focus on concrete Python symbols and signatures.

Core

Core API

hotstring.core contains the generic AutoHotkey hotstring domain model and recognition logic. It does not depend on AutoCorrect2 integration or typo generation.

The subpackage contains:

• semantic/AHK trigger conversion and case-insensitive keys;
• hotstring and candidate domain models;
• option parsing and effective option resolution;
• conflict detection;
• generic AutoHotkey defaults and constants.

Core models

This module contains the generic Hotstring model, the abstract CandidateHotstring specialization, and ExistingHotstring for declarations loaded from AHK source.

Hotstring uses a class-level trigger-input policy rather than subclass resolver methods. ExistingHotstring shadows that policy so the shared base initialization logic knows its constructor trigger is AHK source text.

models

Define generic AutoHotkey hotstring domain models.

CHECK_TRIGGER_ROUND_TRIP module-attribute

CHECK_TRIGGER_ROUND_TRIP: Final[bool] = True

Whether hotstring initialization verifies the trigger conversion invariant.

Hotstring dataclass

Represent the generic declaration portion of an AutoHotkey v2 hotstring.

trigger and options_input are constructor-only values. By default, trigger is interpreted as semantic trigger text. Subclasses whose constructor receives AHK source-form trigger text can override the TRIGGER_INPUT_IS_AHK_SOURCE class policy without replacing the shared trigger-resolution algorithm.

Parameters:

Name	Type	Description	Default
trigger	InitVar[str]	Constructor trigger input. For Hotstring and candidate classes, this is semantic trigger text. Subclasses may declare that the same constructor argument is AHK source text by overriding TRIGGER_INPUT_IS_AHK_SOURCE.	required
options_input	InitVar[str | HotstringOptions]	Parsed hotstring options or a raw option declaration string.	required

Attributes:

Name	Type	Description
TRIGGER_INPUT_IS_AHK_SOURCE	bool	Whether the constructor's trigger argument is interpreted as AutoHotkey source text rather than as a semantic trigger. If False, trigger is treated as the literal semantic text that the hotstring should recognize. If True, trigger is treated as AutoHotkey source text and is decoded before the semantic and canonical AutoHotkey trigger representations are derived. Subclasses may override this class attribute to define the expected representation of their constructor trigger input.
semantic_trigger	str	Semantic trigger text containing the actual characters AutoHotkey should recognize.
ahk_trigger	str	Canonical, minimally escaped trigger source spelling used inside an AHK hotstring declaration.
options	HotstringOptions	Parsed per-hotstring options. This is always a HotstringOptions instance after initialization, regardless of the constructor input type.
case_insensitive_semantic_trigger_key	str	Cached comparison key derived from semantic_trigger and used for AutoHotkey-compatible case-insensitive conflict detection. This is derived runtime state rather than another trigger representation.

Source code in hotstring\core\models.py

@dataclass(frozen=True, slots=True)
class Hotstring:
    """Represent the generic declaration portion of an AutoHotkey v2 hotstring.

    `trigger` and `options_input` are constructor-only values. By default,
    `trigger` is interpreted as semantic trigger text. Subclasses whose
    constructor receives AHK source-form trigger text can override the
    `TRIGGER_INPUT_IS_AHK_SOURCE` class policy without replacing the shared
    trigger-resolution algorithm.

    Args:
        trigger:
            Constructor trigger input. For `Hotstring` and candidate classes,
            this is semantic trigger text. Subclasses may declare that the same
            constructor argument is AHK source text by overriding
            `TRIGGER_INPUT_IS_AHK_SOURCE`.
        options_input:
            Parsed hotstring options or a raw option declaration string.

    Attributes:
        TRIGGER_INPUT_IS_AHK_SOURCE:
            Whether the constructor's `trigger` argument is interpreted as
            AutoHotkey source text rather than as a semantic trigger.

            If `False`, `trigger` is treated as the literal semantic text that
            the hotstring should recognize. If `True`, `trigger` is treated as
            AutoHotkey source text and is decoded before the semantic and
            canonical AutoHotkey trigger representations are derived.

            Subclasses may override this class attribute to define the expected
            representation of their constructor trigger input.
        semantic_trigger:
            Semantic trigger text containing the actual characters AutoHotkey
            should recognize.
        ahk_trigger:
            Canonical, minimally escaped trigger source spelling used inside an
            AHK hotstring declaration.
        options:
            Parsed per-hotstring options. This is always a
            [`HotstringOptions`][hotstring.core.options.HotstringOptions]
            instance after initialization, regardless of the constructor input
            type.
        case_insensitive_semantic_trigger_key:
            Cached comparison key derived from `semantic_trigger` and used for
            AutoHotkey-compatible case-insensitive conflict detection. This is
            derived runtime state rather than another trigger representation.
    """

    TRIGGER_INPUT_IS_AHK_SOURCE: ClassVar[bool] = False

    trigger: InitVar[str]
    options_input: InitVar[str | HotstringOptions]

    semantic_trigger: str = field(init=False)
    ahk_trigger: str = field(init=False)
    options: HotstringOptions = field(init=False)
    case_insensitive_semantic_trigger_key: str = field(
        init=False,
        repr=False,
        compare=False,
    )

    def __post_init__(
        self,
        trigger: str,
        options_input: str | HotstringOptions,
    ) -> None:
        """Resolve constructor inputs and establish immutable hotstring state.

        Trigger initialization follows one shared algorithm for the full
        hierarchy:

        1. interpret the constructor trigger according to
           `TRIGGER_INPUT_IS_AHK_SOURCE`;
        2. derive the semantic trigger;
        3. derive the canonical AHK trigger from the semantic trigger;
        4. optionally verify that decoding the canonical AHK trigger reproduces
           the same semantic trigger.

        Args:
            trigger:
                Constructor trigger input supplied through the `InitVar`.
            options_input:
                Raw or already parsed option input supplied through the
                `InitVar`.

        Raises:
            TypeError:
                If the trigger or options input has an invalid type.
            ValueError:
                If the resolved semantic trigger is empty or cannot be
                represented safely in canonical AHK source form, or if the
                option string is invalid.
            AssertionError:
                If `CHECK_TRIGGER_ROUND_TRIP` is enabled and the canonical AHK
                trigger does not decode back to the derived semantic trigger.
        """
        if not isinstance(trigger, str):
            raise TypeError(
                f"Hotstring trigger input must be a string, not {type(trigger).__name__}"
            )

        semantic_trigger = (
            ahk_to_semantic_trigger(trigger) if self.TRIGGER_INPUT_IS_AHK_SOURCE else trigger
        )
        if not semantic_trigger:
            raise ValueError("Hotstring semantic trigger cannot be empty.")

        ahk_trigger = semantic_to_ahk_trigger(semantic_trigger)

        if CHECK_TRIGGER_ROUND_TRIP:
            round_trip_trigger = ahk_to_semantic_trigger(ahk_trigger)
            if round_trip_trigger != semantic_trigger:
                raise AssertionError(
                    "Canonical AHK trigger does not round-trip to the semantic trigger."
                )

        if isinstance(options_input, str):
            options = HotstringOptions(options_input)
        elif isinstance(options_input, HotstringOptions):
            options = options_input
        else:
            raise TypeError(
                "Hotstring options input must be a string or HotstringOptions "
                f"instance, not {type(options_input).__name__}"
            )

        object.__setattr__(self, "semantic_trigger", semantic_trigger)
        object.__setattr__(self, "ahk_trigger", ahk_trigger)
        object.__setattr__(self, "options", options)
        object.__setattr__(
            self,
            "case_insensitive_semantic_trigger_key",
            make_case_insensitive_trigger_key(semantic_trigger),
        )

    @staticmethod
    def to_ahk_string_literal(value: str) -> str:
        """Convert text to an AutoHotkey v2 double-quoted string literal.

        This helper is intentionally separate from hotstring-trigger source
        encoding. A quoted AHK expression string and a hotstring trigger
        declaration have different escaping rules.

        Literal backticks, double quotes, and every supported AutoHotkey control
        escape are encoded. Unsupported ASCII control characters are rejected
        rather than emitted invisibly into generated source.

        Args:
            value:
                Text to encode as an AutoHotkey string literal.

        Returns:
            Complete double-quoted AHK string literal.

        Raises:
            TypeError:
                If `value` is not a string.
            ValueError:
                If `value` contains an unsupported ASCII control character.
        """
        if not isinstance(value, str):
            raise TypeError(
                f"AHK string literal value must be a string, not {type(value).__name__}"
            )

        supported_control_characters = {
            "\r",
            "\n",
            "\b",
            "\t",
            "\v",
            "\a",
            "\f",
        }
        unsupported = [
            character
            for character in value
            if (ord(character) < 32 and character not in supported_control_characters)
            or ord(character) == 127
        ]
        if unsupported:
            codepoints = ", ".join(f"U+{ord(character):04X}" for character in unsupported)
            raise ValueError(
                f"AHK string literal contains unsupported control characters: {codepoints}"
            )

        escaped = (
            value.replace("`", "``")
            .replace('"', '`"')
            .replace("\r", "`r")
            .replace("\n", "`n")
            .replace("\b", "`b")
            .replace("\t", "`t")
            .replace("\v", "`v")
            .replace("\a", "`a")
            .replace("\f", "`f")
        )
        return f'"{escaped}"'

    def render(self, content: str | None = None) -> str:
        """Render the hotstring declaration with optional trailing content.

        Rendering always uses the canonical `ahk_trigger` representation,
        never the constructor input or semantic trigger. This guarantees that
        triggers containing context-sensitive colons or semicolons, literal
        backticks, or supported control characters are emitted safely and
        consistently.

        `content` means everything emitted after the declaration's second
        `::`. It can therefore represent replacement text, executable inline
        content, or a multiline hotstring function body. If `content` is
        omitted, subclasses may provide their own default through
        [`_default_content()`][hotstring.core.models.Hotstring._default_content].

        Args:
            content:
                Optional content to emit after the second `::`.

        Returns:
            Complete hotstring source text.

        Raises:
            TypeError:
                If the supplied or subclass-provided content is neither a
                string nor `None`.
        """
        if content is None:
            content = self._default_content()

        if content is not None and not isinstance(content, str):
            raise TypeError(
                f"Hotstring content must be a string or None, not {type(content).__name__}"
            )

        declaration = f":{self.options.declaration()}:{self.ahk_trigger}::"
        return declaration if content is None else declaration + content

    def _default_content(self) -> str | None:
        """Return subclass-provided content used by `render()` when omitted.

        Returns:
            Default content, or `None` when the generic hotstring has none.
        """
        return None

__post_init__

__post_init__(
    trigger: str, options_input: str | HotstringOptions
) -> None

Resolve constructor inputs and establish immutable hotstring state.

Trigger initialization follows one shared algorithm for the full hierarchy:

1. interpret the constructor trigger according to TRIGGER_INPUT_IS_AHK_SOURCE;
2. derive the semantic trigger;
3. derive the canonical AHK trigger from the semantic trigger;
4. optionally verify that decoding the canonical AHK trigger reproduces the same semantic trigger.

Parameters:

Name	Type	Description	Default
trigger	str	Constructor trigger input supplied through the InitVar.	required
options_input	str | HotstringOptions	Raw or already parsed option input supplied through the InitVar.	required

Raises:

Type	Description
TypeError	If the trigger or options input has an invalid type.
ValueError	If the resolved semantic trigger is empty or cannot be represented safely in canonical AHK source form, or if the option string is invalid.
AssertionError	If CHECK_TRIGGER_ROUND_TRIP is enabled and the canonical AHK trigger does not decode back to the derived semantic trigger.

Source code in hotstring\core\models.py

def __post_init__(
    self,
    trigger: str,
    options_input: str | HotstringOptions,
) -> None:
    """Resolve constructor inputs and establish immutable hotstring state.

    Trigger initialization follows one shared algorithm for the full
    hierarchy:

    1. interpret the constructor trigger according to
       `TRIGGER_INPUT_IS_AHK_SOURCE`;
    2. derive the semantic trigger;
    3. derive the canonical AHK trigger from the semantic trigger;
    4. optionally verify that decoding the canonical AHK trigger reproduces
       the same semantic trigger.

    Args:
        trigger:
            Constructor trigger input supplied through the `InitVar`.
        options_input:
            Raw or already parsed option input supplied through the
            `InitVar`.

    Raises:
        TypeError:
            If the trigger or options input has an invalid type.
        ValueError:
            If the resolved semantic trigger is empty or cannot be
            represented safely in canonical AHK source form, or if the
            option string is invalid.
        AssertionError:
            If `CHECK_TRIGGER_ROUND_TRIP` is enabled and the canonical AHK
            trigger does not decode back to the derived semantic trigger.
    """
    if not isinstance(trigger, str):
        raise TypeError(
            f"Hotstring trigger input must be a string, not {type(trigger).__name__}"
        )

    semantic_trigger = (
        ahk_to_semantic_trigger(trigger) if self.TRIGGER_INPUT_IS_AHK_SOURCE else trigger
    )
    if not semantic_trigger:
        raise ValueError("Hotstring semantic trigger cannot be empty.")

    ahk_trigger = semantic_to_ahk_trigger(semantic_trigger)

    if CHECK_TRIGGER_ROUND_TRIP:
        round_trip_trigger = ahk_to_semantic_trigger(ahk_trigger)
        if round_trip_trigger != semantic_trigger:
            raise AssertionError(
                "Canonical AHK trigger does not round-trip to the semantic trigger."
            )

    if isinstance(options_input, str):
        options = HotstringOptions(options_input)
    elif isinstance(options_input, HotstringOptions):
        options = options_input
    else:
        raise TypeError(
            "Hotstring options input must be a string or HotstringOptions "
            f"instance, not {type(options_input).__name__}"
        )

    object.__setattr__(self, "semantic_trigger", semantic_trigger)
    object.__setattr__(self, "ahk_trigger", ahk_trigger)
    object.__setattr__(self, "options", options)
    object.__setattr__(
        self,
        "case_insensitive_semantic_trigger_key",
        make_case_insensitive_trigger_key(semantic_trigger),
    )

to_ahk_string_literal staticmethod

to_ahk_string_literal(value: str) -> str

Convert text to an AutoHotkey v2 double-quoted string literal.

This helper is intentionally separate from hotstring-trigger source encoding. A quoted AHK expression string and a hotstring trigger declaration have different escaping rules.

Literal backticks, double quotes, and every supported AutoHotkey control escape are encoded. Unsupported ASCII control characters are rejected rather than emitted invisibly into generated source.

Parameters:

Name	Type	Description	Default
value	str	Text to encode as an AutoHotkey string literal.	required

Returns:

Type	Description
str	Complete double-quoted AHK string literal.

Raises:

Type	Description
TypeError	If value is not a string.
ValueError	If value contains an unsupported ASCII control character.

Source code in hotstring\core\models.py

@staticmethod
def to_ahk_string_literal(value: str) -> str:
    """Convert text to an AutoHotkey v2 double-quoted string literal.

    This helper is intentionally separate from hotstring-trigger source
    encoding. A quoted AHK expression string and a hotstring trigger
    declaration have different escaping rules.

    Literal backticks, double quotes, and every supported AutoHotkey control
    escape are encoded. Unsupported ASCII control characters are rejected
    rather than emitted invisibly into generated source.

    Args:
        value:
            Text to encode as an AutoHotkey string literal.

    Returns:
        Complete double-quoted AHK string literal.

    Raises:
        TypeError:
            If `value` is not a string.
        ValueError:
            If `value` contains an unsupported ASCII control character.
    """
    if not isinstance(value, str):
        raise TypeError(
            f"AHK string literal value must be a string, not {type(value).__name__}"
        )

    supported_control_characters = {
        "\r",
        "\n",
        "\b",
        "\t",
        "\v",
        "\a",
        "\f",
    }
    unsupported = [
        character
        for character in value
        if (ord(character) < 32 and character not in supported_control_characters)
        or ord(character) == 127
    ]
    if unsupported:
        codepoints = ", ".join(f"U+{ord(character):04X}" for character in unsupported)
        raise ValueError(
            f"AHK string literal contains unsupported control characters: {codepoints}"
        )

    escaped = (
        value.replace("`", "``")
        .replace('"', '`"')
        .replace("\r", "`r")
        .replace("\n", "`n")
        .replace("\b", "`b")
        .replace("\t", "`t")
        .replace("\v", "`v")
        .replace("\a", "`a")
        .replace("\f", "`f")
    )
    return f'"{escaped}"'

render

render(content: str | None = None) -> str

Render the hotstring declaration with optional trailing content.

Rendering always uses the canonical ahk_trigger representation, never the constructor input or semantic trigger. This guarantees that triggers containing context-sensitive colons or semicolons, literal backticks, or supported control characters are emitted safely and consistently.

content means everything emitted after the declaration's second ::. It can therefore represent replacement text, executable inline content, or a multiline hotstring function body. If content is omitted, subclasses may provide their own default through _default_content().

Parameters:

Name	Type	Description	Default
content	str | None	Optional content to emit after the second ::.	None

Returns:

Type	Description
str	Complete hotstring source text.

Raises:

Type	Description
TypeError	If the supplied or subclass-provided content is neither a string nor None.

Source code in hotstring\core\models.py

def render(self, content: str | None = None) -> str:
    """Render the hotstring declaration with optional trailing content.

    Rendering always uses the canonical `ahk_trigger` representation,
    never the constructor input or semantic trigger. This guarantees that
    triggers containing context-sensitive colons or semicolons, literal
    backticks, or supported control characters are emitted safely and
    consistently.

    `content` means everything emitted after the declaration's second
    `::`. It can therefore represent replacement text, executable inline
    content, or a multiline hotstring function body. If `content` is
    omitted, subclasses may provide their own default through
    [`_default_content()`][hotstring.core.models.Hotstring._default_content].

    Args:
        content:
            Optional content to emit after the second `::`.

    Returns:
        Complete hotstring source text.

    Raises:
        TypeError:
            If the supplied or subclass-provided content is neither a
            string nor `None`.
    """
    if content is None:
        content = self._default_content()

    if content is not None and not isinstance(content, str):
        raise TypeError(
            f"Hotstring content must be a string or None, not {type(content).__name__}"
        )

    declaration = f":{self.options.declaration()}:{self.ahk_trigger}::"
    return declaration if content is None else declaration + content

_default_content

_default_content() -> str | None

Return subclass-provided content used by render() when omitted.

Returns:

Type	Description
str | None	Default content, or None when the generic hotstring has none.

Source code in hotstring\core\models.py

def _default_content(self) -> str | None:
    """Return subclass-provided content used by `render()` when omitted.

    Returns:
        Default content, or `None` when the generic hotstring has none.
    """
    return None

CandidateHotstring dataclass

Bases: Hotstring, ABC

Represent an abstract proposed hotstring correction.

Candidate constructor trigger input is semantic text, so this class keeps the inherited TRIGGER_INPUT_IS_AHK_SOURCE = False policy. Concrete subclasses define how the semantic replacement is converted into AutoHotkey content. The computed content is cached once during initialization.

Parameters:

Name	Type	Description	Default
trigger	InitVar[str]	Semantic trigger text proposed for the candidate.	required
options_input	InitVar[str | HotstringOptions]	Raw or already parsed hotstring options.	required
replacement	str	Intended semantic replacement text.	required

Attributes:

Name	Type	Description
replacement	str	Intended semantic replacement text.
content	str	Derived AutoHotkey content computed by the concrete subclass.

Source code in hotstring\core\models.py

@dataclass(frozen=True, slots=True)
class CandidateHotstring(Hotstring, ABC):
    """Represent an abstract proposed hotstring correction.

    Candidate constructor trigger input is semantic text, so this class keeps
    the inherited `TRIGGER_INPUT_IS_AHK_SOURCE = False` policy. Concrete
    subclasses define how the semantic `replacement` is converted into
    AutoHotkey content. The computed content is cached once during
    initialization.

    Args:
        trigger:
            Semantic trigger text proposed for the candidate.
        options_input:
            Raw or already parsed hotstring options.
        replacement:
            Intended semantic replacement text.

    Attributes:
        replacement:
            Intended semantic replacement text.
        content:
            Derived AutoHotkey content computed by the concrete subclass.
    """

    replacement: str
    content: str = field(init=False)

    def __post_init__(
        self,
        trigger: str,
        options_input: str | HotstringOptions,
    ) -> None:
        """Validate the candidate and derive its AutoHotkey content.

        Args:
            trigger:
                Semantic trigger constructor input.
            options_input:
                Raw or parsed option constructor input.

        Raises:
            TypeError:
                If `replacement` is not a string or `compute_content()` does
                not return a string.
            ValueError:
                If base hotstring initialization rejects an input.
            AssertionError:
                If an enabled base trigger invariant check fails.
        """
        Hotstring.__post_init__(self, trigger, options_input)

        if not isinstance(self.replacement, str):
            raise TypeError(
                f"Candidate replacement must be a string, not {type(self.replacement).__name__}"
            )

        content = self.compute_content(self.replacement)
        if not isinstance(content, str):
            raise TypeError(
                f"Candidate compute_content() must return a string, not {type(content).__name__}"
            )
        object.__setattr__(self, "content", content)

    @abstractmethod
    def compute_content(self, replacement: str) -> str:
        """Convert semantic replacement text into concrete AHK content.

        Args:
            replacement:
                Stored candidate replacement.

        Returns:
            Content suitable for the concrete candidate type.
        """
        raise NotImplementedError

    def _default_content(self) -> str:
        """Return the candidate's precomputed content for default rendering.

        Returns:
            Precomputed candidate content.
        """
        return self.content

__post_init__

__post_init__(
    trigger: str, options_input: str | HotstringOptions
) -> None

Validate the candidate and derive its AutoHotkey content.

Parameters:

Name	Type	Description	Default
trigger	str	Semantic trigger constructor input.	required
options_input	str | HotstringOptions	Raw or parsed option constructor input.	required

Raises:

Type	Description
TypeError	If replacement is not a string or compute_content() does not return a string.
ValueError	If base hotstring initialization rejects an input.
AssertionError	If an enabled base trigger invariant check fails.

Source code in hotstring\core\models.py

def __post_init__(
    self,
    trigger: str,
    options_input: str | HotstringOptions,
) -> None:
    """Validate the candidate and derive its AutoHotkey content.

    Args:
        trigger:
            Semantic trigger constructor input.
        options_input:
            Raw or parsed option constructor input.

    Raises:
        TypeError:
            If `replacement` is not a string or `compute_content()` does
            not return a string.
        ValueError:
            If base hotstring initialization rejects an input.
        AssertionError:
            If an enabled base trigger invariant check fails.
    """
    Hotstring.__post_init__(self, trigger, options_input)

    if not isinstance(self.replacement, str):
        raise TypeError(
            f"Candidate replacement must be a string, not {type(self.replacement).__name__}"
        )

    content = self.compute_content(self.replacement)
    if not isinstance(content, str):
        raise TypeError(
            f"Candidate compute_content() must return a string, not {type(content).__name__}"
        )
    object.__setattr__(self, "content", content)

compute_content abstractmethod

compute_content(replacement: str) -> str

Convert semantic replacement text into concrete AHK content.

Parameters:

Name	Type	Description	Default
replacement	str	Stored candidate replacement.	required

Returns:

Type	Description
str	Content suitable for the concrete candidate type.

Source code in hotstring\core\models.py

@abstractmethod
def compute_content(self, replacement: str) -> str:
    """Convert semantic replacement text into concrete AHK content.

    Args:
        replacement:
            Stored candidate replacement.

    Returns:
        Content suitable for the concrete candidate type.
    """
    raise NotImplementedError

_default_content

_default_content() -> str

Return the candidate's precomputed content for default rendering.

Returns:

Type	Description
str	Precomputed candidate content.

Source code in hotstring\core\models.py

def _default_content(self) -> str:
    """Return the candidate's precomputed content for default rendering.

    Returns:
        Precomputed candidate content.
    """
    return self.content

ExistingHotstring dataclass

Bases: Hotstring

Represent an existing hotstring discovered in an AHK source file.

Unlike the generic and candidate models, trigger passed to this class is interpreted as AHK source-form trigger text. The class expresses that difference only by shadowing TRIGGER_INPUT_IS_AHK_SOURCE; the base __post_init__() still owns the complete resolution algorithm. Existing source is decoded to semantic form and re-encoded to the project's canonical minimally escaped AHK form, so equivalent source spellings produce identical stored trigger state.

Parameters:

Name	Type	Description	Default
trigger	InitVar[str]	Trigger source spelling extracted from the AHK declaration.	required
options_input	InitVar[str | HotstringOptions]	Raw or parsed hotstring options.	required
source	Path	Source path from which the declaration was extracted.	required

Attributes:

Name	Type	Description
source	Path	Source path from which the declaration was extracted.

Source code in hotstring\core\models.py

@dataclass(frozen=True, slots=True)
class ExistingHotstring(Hotstring):
    """Represent an existing hotstring discovered in an AHK source file.

    Unlike the generic and candidate models, `trigger` passed to this class is
    interpreted as AHK source-form trigger text. The class expresses that
    difference only by shadowing `TRIGGER_INPUT_IS_AHK_SOURCE`; the base
    `__post_init__()` still owns the complete resolution algorithm. Existing
    source is decoded to semantic form and re-encoded to the project's
    canonical minimally escaped AHK form, so equivalent source spellings
    produce identical stored trigger state.

    Args:
        trigger:
            Trigger source spelling extracted from the AHK declaration.
        options_input:
            Raw or parsed hotstring options.
        source:
            Source path from which the declaration was extracted.

    Attributes:
        source:
            Source path from which the declaration was extracted.
    """

    TRIGGER_INPUT_IS_AHK_SOURCE: ClassVar[bool] = True

    source: Path

    def __post_init__(
        self,
        trigger: str,
        options_input: str | HotstringOptions,
    ) -> None:
        """Resolve the AHK trigger input and validate the source field.

        Args:
            trigger:
                AHK source-form trigger constructor input.
            options_input:
                Raw or parsed option constructor input.

        Raises:
            TypeError:
                If `source` is not a [`Path`][pathlib.Path].
            ValueError:
                If the trigger or option input is invalid.
            AssertionError:
                If an enabled base trigger invariant check fails.
        """
        Hotstring.__post_init__(self, trigger, options_input)

        if not isinstance(self.source, Path):
            raise TypeError(
                f"Existing hotstring source must be a Path, not {type(self.source).__name__}"
            )

__post_init__

__post_init__(
    trigger: str, options_input: str | HotstringOptions
) -> None

Resolve the AHK trigger input and validate the source field.

Parameters:

Name	Type	Description	Default
trigger	str	AHK source-form trigger constructor input.	required
options_input	str | HotstringOptions	Raw or parsed option constructor input.	required

Raises:

Type	Description
TypeError	If source is not a Path.
ValueError	If the trigger or option input is invalid.
AssertionError	If an enabled base trigger invariant check fails.

Source code in hotstring\core\models.py

def __post_init__(
    self,
    trigger: str,
    options_input: str | HotstringOptions,
) -> None:
    """Resolve the AHK trigger input and validate the source field.

    Args:
        trigger:
            AHK source-form trigger constructor input.
        options_input:
            Raw or parsed option constructor input.

    Raises:
        TypeError:
            If `source` is not a [`Path`][pathlib.Path].
        ValueError:
            If the trigger or option input is invalid.
        AssertionError:
            If an enabled base trigger invariant check fails.
    """
    Hotstring.__post_init__(self, trigger, options_input)

    if not isinstance(self.source, Path):
        raise TypeError(
            f"Existing hotstring source must be a Path, not {type(self.source).__name__}"
        )

Trigger representations

This module owns conversion between semantic trigger text and deterministic, minimally escaped AutoHotkey source spelling, plus the reusable case-insensitive comparison key derived from semantic text.

The semantic-to-AHK and AHK-to-semantic helpers are intentionally asymmetric with respect to source spelling: multiple valid AHK spellings can normalize to one canonical source representation.

trigger

Normalize AutoHotkey hotstring trigger source and matching representations.

The project keeps two distinct trigger representations:

• a semantic trigger, containing the actual characters AutoHotkey should recognize;
• an AHK trigger, containing a deterministic, minimally escaped source spelling suitable for use inside a hotstring declaration.

The conversion helpers in this module are the single source of truth for moving between those representations. The conversion is intentionally asymmetric with respect to source spelling: multiple valid AHK spellings may decode to the same semantic trigger, while semantic-to-AHK conversion always emits one canonical minimally escaped spelling.

Case-insensitive matching also lives here because it must operate on semantic trigger text rather than escaped AHK source spelling.

_SEMANTIC_TO_AHK_ESCAPE module-attribute

_SEMANTIC_TO_AHK_ESCAPE: Final[dict[str, str]] = {
    "`": "``",
    "\n": "`n",
    "\r": "`r",
    "\x08": "`b",
    "\t": "`t",
    "\x0b": "`v",
    "\x07": "`a",
    "\x0c": "`f",
}

AHK source escapes for semantic characters that always require escaping.

_AHK_ESCAPE_TO_SEMANTIC module-attribute

_AHK_ESCAPE_TO_SEMANTIC: Final[dict[str, str]] = {
    "`": "`",
    "n": "\n",
    "r": "\r",
    "b": "\x08",
    "t": "\t",
    "s": " ",
    "v": "\x0b",
    "a": "\x07",
    "f": "\x0c",
    ":": ":",
    ";": ";",
}

Known AHK escape suffixes and the semantic characters they represent.

semantic_to_ahk_trigger

semantic_to_ahk_trigger(trigger: str) -> str

Convert a semantic hotstring trigger to canonical AutoHotkey source text.

The semantic trigger contains the actual characters that AutoHotkey should recognize. This function converts that value into a minimally escaped, deterministic representation suitable for use as the trigger portion of an AutoHotkey hotstring declaration.

Conversion is performed in two stages.

First, characters which always require AutoHotkey escaping are converted according to _SEMANTIC_TO_AHK_ESCAPE. All other ordinary characters are preserved unchanged.

Second, characters whose escaping requirements depend on their surrounding AutoHotkey source are handled:

• A semicolon is escaped only when immediately preceded by a literal space, because in that position it would otherwise begin an AutoHotkey comment. Semantic tab characters do not require special handling here because they were already converted to `t during the first stage.

• Colons are escaped only where necessary to prevent an unescaped :: sequence from appearing in the trigger or between the trigger and the hotstring declaration delimiter. A temporary trailing colon represents the first colon of that delimiter while the trigger is processed. Consecutive colons are then scanned from right to left, alternating between literal and escaped forms. The temporary colon is removed before returning the result.

This produces a canonical representation without unnecessarily escaping colons or semicolons.

The supported round-trip invariant is:

ahk_to_semantic_trigger(semantic_to_ahk_trigger(value)) == value

for every semantic trigger accepted by this function. The reverse source round trip is intentionally not required because AutoHotkey can accept multiple equivalent source spellings.

Parameters:

Name	Type	Description	Default
trigger	str	The semantic hotstring trigger containing the actual characters that should be recognized.	required

Returns:

Type	Description
str	The trigger encoded for use in an AutoHotkey hotstring declaration.

Raises:

Type	Description
TypeError	If trigger is not a string.
ValueError	If trigger is empty or contains an unsupported ASCII control character which has no explicitly supported AutoHotkey escape representation.

Examples:

An ordinary colon does not require escaping:

foo:bar -> foo:bar

A trailing colon must be escaped because the hotstring declaration's closing :: immediately follows it:

foo: -> foo`:

Consecutive colons are escaped only as needed to prevent an unescaped :: sequence:

foo::bar -> foo`::bar

A semicolon following a space must be escaped:

foo ;bar -> foo `;bar

A semicolon without a preceding space remains literal:

foo;bar -> foo;bar

Source code in hotstring\core\trigger.py

def semantic_to_ahk_trigger(trigger: str) -> str:
    """Convert a semantic hotstring trigger to canonical AutoHotkey source text.

    The semantic trigger contains the actual characters that AutoHotkey should
    recognize. This function converts that value into a minimally escaped,
    deterministic representation suitable for use as the trigger portion of an
    AutoHotkey hotstring declaration.

    Conversion is performed in two stages.

    First, characters which always require AutoHotkey escaping are converted
    according to `_SEMANTIC_TO_AHK_ESCAPE`. All other ordinary characters are
    preserved unchanged.

    Second, characters whose escaping requirements depend on their surrounding
    AutoHotkey source are handled:

    - A semicolon is escaped only when immediately preceded by a literal space,
      because in that position it would otherwise begin an AutoHotkey comment.
      Semantic tab characters do not require special handling here because they
      were already converted to `` `t `` during the first stage.

    - Colons are escaped only where necessary to prevent an unescaped ``::``
      sequence from appearing in the trigger or between the trigger and the
      hotstring declaration delimiter. A temporary trailing colon represents
      the first colon of that delimiter while the trigger is processed.
      Consecutive colons are then scanned from right to left, alternating
      between literal and escaped forms. The temporary colon is removed before
      returning the result.

    This produces a canonical representation without unnecessarily escaping
    colons or semicolons.

    The supported round-trip invariant is:

    ```python
    ahk_to_semantic_trigger(semantic_to_ahk_trigger(value)) == value
    ```

    for every semantic trigger accepted by this function. The reverse source
    round trip is intentionally not required because AutoHotkey can accept
    multiple equivalent source spellings.

    Args:
        trigger:
            The semantic hotstring trigger containing the actual characters
            that should be recognized.

    Returns:
        The trigger encoded for use in an AutoHotkey hotstring declaration.

    Raises:
        TypeError:
            If `trigger` is not a string.
        ValueError:
            If `trigger` is empty or contains an unsupported ASCII control
            character which has no explicitly supported AutoHotkey escape
            representation.

    Examples:
        An ordinary colon does not require escaping:

        ```text
        foo:bar -> foo:bar
        ```

        A trailing colon must be escaped because the hotstring declaration's
        closing ``::`` immediately follows it:

        ```text
        foo: -> foo`:
        ```

        Consecutive colons are escaped only as needed to prevent an unescaped
        ``::`` sequence:

        ```text
        foo::bar -> foo`::bar
        ```

        A semicolon following a space must be escaped:

        ```text
        foo ;bar -> foo `;bar
        ```

        A semicolon without a preceding space remains literal:

        ```text
        foo;bar -> foo;bar
        ```
    """
    if not isinstance(trigger, str):
        raise TypeError(
            f"Semantic hotstring trigger must be a string, not {type(trigger).__name__}"
        )
    if not trigger:
        raise ValueError("Semantic hotstring trigger cannot be empty.")

    encoded_parts: list[str] = []

    def escape_contextual_characters() -> str:
        """Apply context-dependent colon and semicolon escaping.

        `encoded_parts` contains the trigger after all unconditional escapes
        have already been applied. A temporary colon is appended to represent
        the first colon of the hotstring declaration's closing ``::``
        delimiter. Processing from right to left then makes the colon escaping
        rule identical for internal and trailing colon runs.

        Returns:
            Fully encoded canonical AutoHotkey trigger text.
        """
        encoded_parts.append(":")

        reversed_parts: list[str] = []
        escape_colon = False

        for index in range(len(encoded_parts) - 1, -1, -1):
            part = encoded_parts[index]

            if part == ":":
                reversed_parts.append("`:" if escape_colon else ":")
                escape_colon = not escape_colon
                continue

            escape_colon = False

            if (
                part == ";"
                and index > 0
                and encoded_parts[index - 1] == " "
            ):
                reversed_parts.append("`;")
            else:
                reversed_parts.append(part)

        encoded_trigger = "".join(reversed(reversed_parts))

        # The temporary delimiter colon is always the final literal character.
        return encoded_trigger[:-1]

    for character in trigger:
        escaped = _SEMANTIC_TO_AHK_ESCAPE.get(character)
        if escaped is not None:
            encoded_parts.append(escaped)
            continue

        codepoint = ord(character)
        if codepoint < 32 or codepoint == 127:
            raise ValueError(
                "Semantic hotstring trigger contains an unsupported control "
                f"character U+{codepoint:04X}."
            )

        encoded_parts.append(character)

    return escape_contextual_characters()

ahk_to_semantic_trigger

ahk_to_semantic_trigger(trigger: str) -> str

Convert an AutoHotkey source trigger to its semantic trigger text.

The input is the trigger portion exactly as represented in AutoHotkey source syntax. Escape sequences are decoded so the returned string contains the actual characters AutoHotkey recognizes as the hotstring trigger.

The function scans the source from left to right. Ordinary characters are copied unchanged. When an AutoHotkey escape character (`) is encountered, it is consumed together with the character immediately following it.

Recognized AutoHotkey escape sequences are converted to their corresponding semantic characters according to _AHK_ESCAPE_TO_SEMANTIC. This includes control-character escapes such as `n and `t, as well as source escapes such as , : ``, and ``; ``.

AutoHotkey's `s escape is also decoded to a literal space, even though semantic_to_ahk_trigger() does not emit `s when producing its canonical source representation.

If the escaped character does not have a special entry in _AHK_ESCAPE_TO_SEMANTIC, the escape character itself is discarded and the following character is preserved literally. This allows valid unnecessary escaping in existing AutoHotkey source to normalize to the same semantic trigger.

Because multiple valid AutoHotkey source spellings can represent the same semantic trigger, this conversion is intentionally not the exact inverse of semantic_to_ahk_trigger() with respect to source spelling. Instead, the important round-trip invariant is:

ahk_to_semantic_trigger(semantic_to_ahk_trigger(value)) == value

Converting existing AutoHotkey source to semantic form and then back to source form may therefore change its spelling by canonicalizing unnecessary or optional escapes.

Parameters:

Name	Type	Description	Default
trigger	str	The trigger text as written in an AutoHotkey hotstring declaration, excluding the surrounding option and :: delimiters.	required

Returns:

Type	Description
str	The semantic trigger containing the actual characters recognized by
str	AutoHotkey.

Raises:

Type	Description
TypeError	If trigger is not a string.
ValueError	If trigger is empty or ends with an unmatched AutoHotkey escape character.

Examples:

Ordinary characters require no decoding:

foo.bar -> foo.bar

An escaped colon becomes a literal semantic colon:

foo`:bar -> foo:bar

An unescaped isolated colon has the same semantic meaning:

foo:bar -> foo:bar

An escaped semicolon becomes a literal semicolon:

foo `;bar -> foo ;bar

AutoHotkey control-character escapes are converted to the actual semantic character. For example, `t becomes a tab:

foo`tbar -> foo<TAB>bar

The AutoHotkey space escape is accepted and normalized to an ordinary semantic space:

foo`sbar -> foo bar

A doubled backtick represents one semantic backtick:

foo``bar -> foo`bar

Different valid source spellings can therefore produce the same semantic value:

foo:bar  -> foo:bar
foo`:bar -> foo:bar

Source code in hotstring\core\trigger.py

def ahk_to_semantic_trigger(trigger: str) -> str:
    """Convert an AutoHotkey source trigger to its semantic trigger text.

    The input is the trigger portion exactly as represented in AutoHotkey
    source syntax. Escape sequences are decoded so the returned string contains
    the actual characters AutoHotkey recognizes as the hotstring trigger.

    The function scans the source from left to right. Ordinary characters are
    copied unchanged. When an AutoHotkey escape character (`` ` ``) is
    encountered, it is consumed together with the character immediately
    following it.

    Recognized AutoHotkey escape sequences are converted to their corresponding
    semantic characters according to `_AHK_ESCAPE_TO_SEMANTIC`. This includes
    control-character escapes such as `` `n `` and `` `t ``, as well as source
    escapes such as `` `` ``, `` `: ``, and `` `; ``.

    AutoHotkey's `` `s `` escape is also decoded to a literal space, even
    though `semantic_to_ahk_trigger()` does not emit `` `s `` when producing
    its canonical source representation.

    If the escaped character does not have a special entry in
    `_AHK_ESCAPE_TO_SEMANTIC`, the escape character itself is discarded and
    the following character is preserved literally. This allows valid
    unnecessary escaping in existing AutoHotkey source to normalize to the
    same semantic trigger.

    Because multiple valid AutoHotkey source spellings can represent the same
    semantic trigger, this conversion is intentionally not the exact inverse
    of `semantic_to_ahk_trigger()` with respect to source spelling. Instead,
    the important round-trip invariant is:

    ```python
    ahk_to_semantic_trigger(semantic_to_ahk_trigger(value)) == value
    ```

    Converting existing AutoHotkey source to semantic form and then back to
    source form may therefore change its spelling by canonicalizing unnecessary
    or optional escapes.

    Args:
        trigger:
            The trigger text as written in an AutoHotkey hotstring declaration,
            excluding the surrounding option and ``::`` delimiters.

    Returns:
        The semantic trigger containing the actual characters recognized by
        AutoHotkey.

    Raises:
        TypeError:
            If `trigger` is not a string.
        ValueError:
            If `trigger` is empty or ends with an unmatched AutoHotkey escape
            character.

    Examples:
        Ordinary characters require no decoding:

        ```text
        foo.bar -> foo.bar
        ```

        An escaped colon becomes a literal semantic colon:

        ```text
        foo`:bar -> foo:bar
        ```

        An unescaped isolated colon has the same semantic meaning:

        ```text
        foo:bar -> foo:bar
        ```

        An escaped semicolon becomes a literal semicolon:

        ```text
        foo `;bar -> foo ;bar
        ```

        AutoHotkey control-character escapes are converted to the actual
        semantic character. For example, `` `t `` becomes a tab:

        ```text
        foo`tbar -> foo<TAB>bar
        ```

        The AutoHotkey space escape is accepted and normalized to an ordinary
        semantic space:

        ```text
        foo`sbar -> foo bar
        ```

        A doubled backtick represents one semantic backtick:

        ```text
        foo``bar -> foo`bar
        ```

        Different valid source spellings can therefore produce the same
        semantic value:

        ```text
        foo:bar  -> foo:bar
        foo`:bar -> foo:bar
        ```
    """
    if not isinstance(trigger, str):
        raise TypeError(
            f"AHK hotstring trigger must be a string, not {type(trigger).__name__}"
        )
    if not trigger:
        raise ValueError("AHK hotstring trigger cannot be empty.")

    decoded_parts: list[str] = []
    index = 0

    while index < len(trigger):
        character = trigger[index]

        if character != "`":
            decoded_parts.append(character)
            index += 1
            continue

        if index + 1 >= len(trigger):
            raise ValueError(
                "AutoHotkey hotstring trigger ends with an unmatched escape character."
            )

        escaped_character = trigger[index + 1]
        decoded_parts.append(
            _AHK_ESCAPE_TO_SEMANTIC.get(
                escaped_character,
                escaped_character,
            )
        )
        index += 2

    return "".join(decoded_parts)

_python_case_insensitive_key

_python_case_insensitive_key(value: str) -> str

Return the non-Windows fallback case-insensitive comparison key.

Parameters:

Name	Type	Description	Default
value	str	Semantic trigger text.	required

Returns:

Type	Description
str	Python lowercase representation used when the Microsoft CRT is not
str	available.

Source code in hotstring\core\trigger.py

def _python_case_insensitive_key(value: str) -> str:
    """Return the non-Windows fallback case-insensitive comparison key.

    Args:
        value:
            Semantic trigger text.

    Returns:
        Python lowercase representation used when the Microsoft CRT is not
        available.
    """
    return value.lower()

_windows_case_insensitive_key

_windows_case_insensitive_key(value: str) -> str

Return a Microsoft CRT C-locale lowercase comparison key.

AutoHotkey's Unicode build compares case-insensitive hotstring text through the Microsoft CRT _wcsicmp family. Lowering each semantic trigger once with _wcslwr_l under an explicit C locale gives a reusable key with the same lowercase basis while avoiding repeated FFI comparisons during conflict detection.

Parameters:

Name	Type	Description	Default
value	str	Semantic trigger text.	required

Returns:

Type	Description
str	Lowercased trigger key produced by the Microsoft CRT.

Source code in hotstring\core\trigger.py

def _windows_case_insensitive_key(value: str) -> str:
    """Return a Microsoft CRT C-locale lowercase comparison key.

    AutoHotkey's Unicode build compares case-insensitive hotstring text
    through the Microsoft CRT ``_wcsicmp`` family. Lowering each semantic
    trigger once with ``_wcslwr_l`` under an explicit ``C`` locale gives a
    reusable key with the same lowercase basis while avoiding repeated FFI
    comparisons during conflict detection.

    Args:
        value:
            Semantic trigger text.

    Returns:
        Lowercased trigger key produced by the Microsoft CRT.
    """
    buffer = ctypes.create_unicode_buffer(value)
    _WCSLWR_L(buffer, _C_LOCALE)
    return buffer.value

make_case_insensitive_trigger_key

make_case_insensitive_trigger_key(trigger: str) -> str

Create the reusable case-insensitive matching key for a semantic trigger.

On Windows the key is produced with the Microsoft CRT _wcslwr_l function under an explicit C locale so comparisons reproduce AutoHotkey's CRT-based case-insensitive behavior as closely as possible. On non-Windows systems, where AutoHotkey itself does not run, Python's str.lower() is used as a deterministic fallback.

Parameters:

Name	Type	Description	Default
trigger	str	Semantic hotstring trigger text.	required

Returns:

Type	Description
str	Case-insensitive comparison key.

Raises:

Type	Description
TypeError	If trigger is not a string.

Source code in hotstring\core\trigger.py

def make_case_insensitive_trigger_key(trigger: str) -> str:
    """Create the reusable case-insensitive matching key for a semantic trigger.

    On Windows the key is produced with the Microsoft CRT ``_wcslwr_l``
    function under an explicit ``C`` locale so comparisons reproduce
    AutoHotkey's CRT-based case-insensitive behavior as closely as possible.
    On non-Windows systems, where AutoHotkey itself does not run, Python's
    `str.lower()` is used as a deterministic fallback.

    Args:
        trigger:
            Semantic hotstring trigger text.

    Returns:
        Case-insensitive comparison key.

    Raises:
        TypeError:
            If `trigger` is not a string.
    """
    if not isinstance(trigger, str):
        raise TypeError(
            f"Semantic hotstring trigger must be a string, not {type(trigger).__name__}"
        )

    return _PLATFORM_CASE_INSENSITIVE_KEY(trigger)

Hotstring options

This module contains the declared option model, inheritance sentinel, semantic enums, and fully resolved option model.

The declared send mode uses SendMode (INPUT, PLAY, and EVENT). Fully resolved options use the separate ResolvedSendMode enum so Input's Play and Event fallback behaviors remain explicit without complicating the field type.

options

Parse, normalize, and resolve AutoHotkey v2 hotstring option strings.

HotstringOptions is the single source of truth for interpreting per-hotstring option strings in this project. Omitted inheritable options are represented by the enum member INHERIT of InheritedState. ResolvedHotstringOptions represents the corresponding fully resolved semantic state.

InheritedState

Bases: Enum

Represent an option value inherited from the applicable defaults.

Attributes:

Name	Type	Description
INHERIT		The option is not explicitly set and should inherit from the applicable default.

Source code in hotstring\core\options.py

class InheritedState(Enum):
    """Represent an option value inherited from the applicable defaults.

    Attributes:
        INHERIT:
            The option is not explicitly set and should inherit from the
            applicable default.
    """

    INHERIT = auto()

SettingState

Bases: Enum

Represent the explicit state of a two-state option.

Attributes:

Name	Type	Description
ENABLED		The option behavior is explicitly enabled.
DISABLED		The option behavior is explicitly disabled.

Source code in hotstring\core\options.py

class SettingState(Enum):
    """Represent the explicit state of a two-state option.

    Attributes:
        ENABLED:
            The option behavior is explicitly enabled.
        DISABLED:
            The option behavior is explicitly disabled.
    """

    ENABLED = auto()
    DISABLED = auto()

CaseMode

Bases: Enum

Represent AutoHotkey hotstring case-matching behavior.

Attributes:

Name	Type	Description
SENSITIVE		Match the trigger case-sensitively.
INSENSITIVE_CONFORMING		Match case-insensitively and allow replacement case conformation.
INSENSITIVE_FIXED		Match case-insensitively without replacement case conformation.

Source code in hotstring\core\options.py

class CaseMode(Enum):
    """Represent AutoHotkey hotstring case-matching behavior.

    Attributes:
        SENSITIVE:
            Match the trigger case-sensitively.
        INSENSITIVE_CONFORMING:
            Match case-insensitively and allow replacement case conformation.
        INSENSITIVE_FIXED:
            Match case-insensitively without replacement case conformation.
    """

    SENSITIVE = auto()
    INSENSITIVE_CONFORMING = auto()
    INSENSITIVE_FIXED = auto()

ReplacementMode

Bases: Enum

Represent AutoHotkey replacement-text interpretation behavior.

Attributes:

Name	Type	Description
NORMAL		Use normal replacement processing.
RAW		Use raw replacement processing.
TEXT		Use text-mode replacement processing.

Source code in hotstring\core\options.py

class ReplacementMode(Enum):
    """Represent AutoHotkey replacement-text interpretation behavior.

    Attributes:
        NORMAL:
            Use normal replacement processing.
        RAW:
            Use raw replacement processing.
        TEXT:
            Use text-mode replacement processing.
    """

    NORMAL = auto()
    RAW = auto()
    TEXT = auto()

SendMode

Bases: Enum

Represent the explicitly selected hotstring send mode.

Attributes:

Name	Type	Description
INPUT		Explicitly select SendInput.
PLAY		Explicitly select SendPlay.
EVENT		Explicitly select SendEvent.

Source code in hotstring\core\options.py

class SendMode(Enum):
    """Represent the explicitly selected hotstring send mode.

    Attributes:
        INPUT:
            Explicitly select SendInput.
        PLAY:
            Explicitly select SendPlay.
        EVENT:
            Explicitly select SendEvent.
    """

    INPUT = auto()
    PLAY = auto()
    EVENT = auto()

ResolvedSendMode

Bases: Enum

Represent the fully resolved hotstring send behavior.

Attributes:

Name	Type	Description
INPUT_WITH_PLAY_FALLBACK		Explicit SI: use SendInput with SendPlay fallback.
INPUT_WITH_EVENT_FALLBACK		Built-in default: use SendInput with SendEvent fallback.
PLAY		Use SendPlay.
EVENT		Use SendEvent.

Source code in hotstring\core\options.py

class ResolvedSendMode(Enum):
    """Represent the fully resolved hotstring send behavior.

    Attributes:
        INPUT_WITH_PLAY_FALLBACK:
            Explicit `SI`: use SendInput with SendPlay fallback.
        INPUT_WITH_EVENT_FALLBACK:
            Built-in default: use SendInput with SendEvent fallback.
        PLAY:
            Use SendPlay.
        EVENT:
            Use SendEvent.
    """

    INPUT_WITH_PLAY_FALLBACK = auto()
    INPUT_WITH_EVENT_FALLBACK = auto()
    PLAY = auto()
    EVENT = auto()

HotstringOptions dataclass

Represent a validated per-hotstring AutoHotkey option declaration.

The original option string is retained in options. Every omitted option is represented by the singleton InheritedState.INHERIT, preserving the distinction between an inherited value and an explicitly selected value.

Attributes:

Name	Type	Description
options	str	Original validated option string with surrounding horizontal whitespace removed.
ending_character_optional	SettingState | InheritedState	Whether the hotstring may activate without an ending character, or InheritedState.INHERIT if not explicitly set.
trigger_inside_word	SettingState | InheritedState	Explicit inside-word matching state, or InheritedState.INHERIT.
automatic_backspacing	SettingState | InheritedState	Explicit automatic-backspacing state, or InheritedState.INHERIT.
case_mode	CaseMode | InheritedState	Explicit case-matching mode, or InheritedState.INHERIT.
key_delay	int | InheritedState	Explicit key delay, or InheritedState.INHERIT.
omit_ending_character	SettingState | InheritedState	Explicit ending-character omission state, or InheritedState.INHERIT.
priority	int | InheritedState	Explicit priority, or InheritedState.INHERIT.
replacement_mode	ReplacementMode | InheritedState	Explicit replacement-processing mode, or InheritedState.INHERIT.
suspend_exempt	SettingState | InheritedState	Explicit suspension-exemption state, or InheritedState.INHERIT.
send_mode	SendMode | InheritedState	Explicit send mode, or InheritedState.INHERIT.
execute	SettingState | InheritedState	Explicit execute state, or InheritedState.INHERIT.
reset_recognizer	SettingState | InheritedState	Explicit recognizer-reset state, or InheritedState.INHERIT.

Source code in hotstring\core\options.py

@dataclass(slots=True, frozen=True)
class HotstringOptions:
    """Represent a validated per-hotstring AutoHotkey option declaration.

    The original option string is retained in `options`. Every omitted option
    is represented by the singleton `InheritedState.INHERIT`, preserving the
    distinction between an inherited value and an explicitly selected value.

    Attributes:
        options:
            Original validated option string with surrounding horizontal
            whitespace removed.
        ending_character_optional:
            Whether the hotstring may activate without an ending character,
            or `InheritedState.INHERIT` if not explicitly set.
        trigger_inside_word:
            Explicit inside-word matching state, or `InheritedState.INHERIT`.
        automatic_backspacing:
            Explicit automatic-backspacing state, or `InheritedState.INHERIT`.
        case_mode:
            Explicit case-matching mode, or `InheritedState.INHERIT`.
        key_delay:
            Explicit key delay, or `InheritedState.INHERIT`.
        omit_ending_character:
            Explicit ending-character omission state, or `InheritedState.INHERIT`.
        priority:
            Explicit priority, or `InheritedState.INHERIT`.
        replacement_mode:
            Explicit replacement-processing mode, or `InheritedState.INHERIT`.
        suspend_exempt:
            Explicit suspension-exemption state, or `InheritedState.INHERIT`.
        send_mode:
            Explicit send mode, or `InheritedState.INHERIT`.
        execute:
            Explicit execute state, or `InheritedState.INHERIT`.
        reset_recognizer:
            Explicit recognizer-reset state, or `InheritedState.INHERIT`.
    """

    options: str = field(init=True, compare=False)

    ending_character_optional: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "*", SettingState.DISABLED: "*0"},
            "str_to_value": {"*": SettingState.ENABLED, "*0": SettingState.DISABLED},
        },
    )
    trigger_inside_word: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "?", SettingState.DISABLED: "?0"},
            "str_to_value": {"?": SettingState.ENABLED, "?0": SettingState.DISABLED},
        },
    )
    automatic_backspacing: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "B", SettingState.DISABLED: "B0"},
            "str_to_value": {"B": SettingState.ENABLED, "B0": SettingState.DISABLED},
        },
    )
    case_mode: CaseMode | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {
                CaseMode.SENSITIVE: "C",
                CaseMode.INSENSITIVE_CONFORMING: "C0",
                CaseMode.INSENSITIVE_FIXED: "C1",
            },
            "str_to_value": {
                "C": CaseMode.SENSITIVE,
                "C0": CaseMode.INSENSITIVE_CONFORMING,
                "C1": CaseMode.INSENSITIVE_FIXED,
            },
        },
    )
    key_delay: int | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={"value_to_str": {}, "str_to_value": {}},
    )
    omit_ending_character: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "O", SettingState.DISABLED: "O0"},
            "str_to_value": {"O": SettingState.ENABLED, "O0": SettingState.DISABLED},
        },
    )
    priority: int | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={"value_to_str": {}, "str_to_value": {}},
    )
    replacement_mode: ReplacementMode | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {
                ReplacementMode.NORMAL: "R0",
                ReplacementMode.RAW: "R",
                ReplacementMode.TEXT: "T",
            },
            "str_to_value": {
                "R0": ReplacementMode.NORMAL,
                "T0": ReplacementMode.NORMAL,
                "R": ReplacementMode.RAW,
                "T": ReplacementMode.TEXT,
            },
        },
    )
    suspend_exempt: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "S", SettingState.DISABLED: "S0"},
            "str_to_value": {"S": SettingState.ENABLED, "S0": SettingState.DISABLED},
        },
    )
    send_mode: SendMode | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {
                SendMode.INPUT: "SI",
                SendMode.PLAY: "SP",
                SendMode.EVENT: "SE",
            },
            "str_to_value": {
                "SI": SendMode.INPUT,
                "SP": SendMode.PLAY,
                "SE": SendMode.EVENT,
            },
        },
    )
    execute: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "X", SettingState.DISABLED: "X0"},
            "str_to_value": {"X": SettingState.ENABLED, "X0": SettingState.DISABLED},
        },
    )
    reset_recognizer: SettingState | InheritedState = field(
        init=False,
        default=InheritedState.INHERIT,
        metadata={
            "value_to_str": {SettingState.ENABLED: "Z", SettingState.DISABLED: "Z0"},
            "str_to_value": {"Z": SettingState.ENABLED, "Z0": SettingState.DISABLED},
        },
    )

    def __post_init__(self) -> None:
        """Validate and parse the supplied option string.

        Raises:
            TypeError:
                If `options` is not a string.
            ValueError:
                If the string contains an unsupported option or an invalid
                numeric value.
        """
        if not isinstance(self.options, str):
            raise TypeError(
                f"Hotstring options must be a string, not {type(self.options).__name__}"
            )

        object.__setattr__(self, "options", self.options.strip(" \t"))

        field_name_to_info = {field_info.name: field_info for field_info in fields(self)}
        options = self.options
        position = 0

        while position < len(options):
            match = _OPTION_PATTERN.match(options, position)
            if match is None:
                raise ValueError(
                    f"Invalid hotstring option at position {position}: {options[position:]!r}"
                )

            option = match.group(1).upper()

            if option.startswith("K"):
                key_delay = int(option[1:])
                if not -1 <= key_delay <= _INT32_MAX:
                    raise ValueError(
                        f"Hotstring key delay must be between -1 and {_INT32_MAX}: {option!r}"
                    )
                object.__setattr__(self, "key_delay", key_delay)

            elif option.startswith("P"):
                priority = int(option[1:])
                if not _INT32_MIN <= priority <= _INT32_MAX:
                    raise ValueError(
                        f"Hotstring priority is outside the signed 32-bit range: {option!r}"
                    )
                object.__setattr__(self, "priority", priority)

            else:
                field_name = _NON_NUMERIC_OPTION_FIELD_NAME.get(option)
                if field_name is None:
                    raise AssertionError(f"Unhandled hotstring option: {option!r}")

                field_info = field_name_to_info[field_name]
                str_to_value = field_info.metadata.get("str_to_value", {})
                value = str_to_value.get(option)
                if value is None:
                    raise RuntimeError(
                        f"Failed to map hotstring option {option!r} to a value for "
                        f"field {field_name!r}; this should never happen."
                    )
                object.__setattr__(self, field_name, value)

            position = match.end()

    def declaration(self) -> str:
        """Return a canonical option string for the parsed semantic state.

        Returns:
            Canonical option text in dataclass field order. Inherited options
            are omitted.
        """
        options_str = ""

        for field_info in fields(self):
            name = field_info.name
            if name == "options":
                continue

            value = getattr(self, name)
            if value is InheritedState.INHERIT:
                continue

            if name == "key_delay":
                option_str = f"K{value}"
            elif name == "priority":
                option_str = f"P{value}"
            else:
                value_to_str = field_info.metadata.get("value_to_str", {})
                option_str = value_to_str.get(value)
                if option_str is None:
                    raise RuntimeError(
                        f"Failed to map value {value!r} of field {name!r} to a string; "
                        "this should never happen."
                    )

            options_str += option_str

        return options_str

__post_init__

__post_init__() -> None

Validate and parse the supplied option string.

Raises:

Type	Description
TypeError	If options is not a string.
ValueError	If the string contains an unsupported option or an invalid numeric value.

Source code in hotstring\core\options.py

def __post_init__(self) -> None:
    """Validate and parse the supplied option string.

    Raises:
        TypeError:
            If `options` is not a string.
        ValueError:
            If the string contains an unsupported option or an invalid
            numeric value.
    """
    if not isinstance(self.options, str):
        raise TypeError(
            f"Hotstring options must be a string, not {type(self.options).__name__}"
        )

    object.__setattr__(self, "options", self.options.strip(" \t"))

    field_name_to_info = {field_info.name: field_info for field_info in fields(self)}
    options = self.options
    position = 0

    while position < len(options):
        match = _OPTION_PATTERN.match(options, position)
        if match is None:
            raise ValueError(
                f"Invalid hotstring option at position {position}: {options[position:]!r}"
            )

        option = match.group(1).upper()

        if option.startswith("K"):
            key_delay = int(option[1:])
            if not -1 <= key_delay <= _INT32_MAX:
                raise ValueError(
                    f"Hotstring key delay must be between -1 and {_INT32_MAX}: {option!r}"
                )
            object.__setattr__(self, "key_delay", key_delay)

        elif option.startswith("P"):
            priority = int(option[1:])
            if not _INT32_MIN <= priority <= _INT32_MAX:
                raise ValueError(
                    f"Hotstring priority is outside the signed 32-bit range: {option!r}"
                )
            object.__setattr__(self, "priority", priority)

        else:
            field_name = _NON_NUMERIC_OPTION_FIELD_NAME.get(option)
            if field_name is None:
                raise AssertionError(f"Unhandled hotstring option: {option!r}")

            field_info = field_name_to_info[field_name]
            str_to_value = field_info.metadata.get("str_to_value", {})
            value = str_to_value.get(option)
            if value is None:
                raise RuntimeError(
                    f"Failed to map hotstring option {option!r} to a value for "
                    f"field {field_name!r}; this should never happen."
                )
            object.__setattr__(self, field_name, value)

        position = match.end()

declaration

declaration() -> str

Return a canonical option string for the parsed semantic state.

Returns:

Type	Description
str	Canonical option text in dataclass field order. Inherited options
str	are omitted.

Source code in hotstring\core\options.py

def declaration(self) -> str:
    """Return a canonical option string for the parsed semantic state.

    Returns:
        Canonical option text in dataclass field order. Inherited options
        are omitted.
    """
    options_str = ""

    for field_info in fields(self):
        name = field_info.name
        if name == "options":
            continue

        value = getattr(self, name)
        if value is InheritedState.INHERIT:
            continue

        if name == "key_delay":
            option_str = f"K{value}"
        elif name == "priority":
            option_str = f"P{value}"
        else:
            value_to_str = field_info.metadata.get("value_to_str", {})
            option_str = value_to_str.get(value)
            if option_str is None:
                raise RuntimeError(
                    f"Failed to map value {value!r} of field {name!r} to a string; "
                    "this should never happen."
                )

        options_str += option_str

    return options_str

ResolvedHotstringOptions dataclass

Represent a fully resolved AutoHotkey hotstring option state.

Unlike HotstringOptions, every field contains a concrete semantic value. InheritedState is therefore absent from every field annotation.

Attributes:

Name	Type	Description
ending_character_optional	SettingState	Whether the hotstring may activate without an ending character.
trigger_inside_word	SettingState	Whether the trigger may begin after an alphanumeric character.
automatic_backspacing	SettingState	Whether AutoHotkey automatically erases the typed trigger.
case_mode	CaseMode	Effective case-matching mode.
key_delay	int	Effective hotstring key delay.
omit_ending_character	SettingState	Whether an ending character is omitted from replacement output.
priority	int	Effective hotstring thread priority.
replacement_mode	ReplacementMode	Effective replacement-text processing mode.
suspend_exempt	SettingState	Whether the hotstring is exempt from suspension.
send_mode	ResolvedSendMode	Effective replacement send mode.
execute	SettingState	Whether inline content is executed rather than used as literal replacement text.
reset_recognizer	SettingState	Whether the recognizer resets after activation.

Source code in hotstring\core\options.py

@dataclass(slots=True, frozen=True, kw_only=True)
class ResolvedHotstringOptions:
    """Represent a fully resolved AutoHotkey hotstring option state.

    Unlike [`HotstringOptions`][hotstring.core.options.HotstringOptions], every
    field contains a concrete semantic value. `InheritedState` is therefore
    absent from every field annotation.

    Attributes:
        ending_character_optional:
            Whether the hotstring may activate without an ending character.
        trigger_inside_word:
            Whether the trigger may begin after an alphanumeric character.
        automatic_backspacing:
            Whether AutoHotkey automatically erases the typed trigger.
        case_mode:
            Effective case-matching mode.
        key_delay:
            Effective hotstring key delay.
        omit_ending_character:
            Whether an ending character is omitted from replacement output.
        priority:
            Effective hotstring thread priority.
        replacement_mode:
            Effective replacement-text processing mode.
        suspend_exempt:
            Whether the hotstring is exempt from suspension.
        send_mode:
            Effective replacement send mode.
        execute:
            Whether inline content is executed rather than used as literal
            replacement text.
        reset_recognizer:
            Whether the recognizer resets after activation.
    """

    ending_character_optional: SettingState
    trigger_inside_word: SettingState
    automatic_backspacing: SettingState
    case_mode: CaseMode
    key_delay: int
    omit_ending_character: SettingState
    priority: int
    replacement_mode: ReplacementMode
    suspend_exempt: SettingState
    send_mode: ResolvedSendMode
    execute: SettingState
    reset_recognizer: SettingState

    def __post_init__(self) -> None:
        """Validate the resolved option state.

        Raises:
            TypeError:
                If any field has an invalid type.
            ValueError:
                If any numeric field is outside its accepted range.
        """
        binary_field_names = (
            "ending_character_optional",
            "trigger_inside_word",
            "automatic_backspacing",
            "omit_ending_character",
            "suspend_exempt",
            "execute",
            "reset_recognizer",
        )

        if not isinstance(self.case_mode, CaseMode):
            raise TypeError(
                f"case_mode must be a CaseMode member, got {type(self.case_mode).__name__}"
            )
        if isinstance(self.key_delay, bool) or not isinstance(self.key_delay, int):
            raise TypeError(f"key_delay must be an int, got {type(self.key_delay).__name__}")
        if not -1 <= self.key_delay <= _INT32_MAX:
            raise ValueError(f"key_delay must be between -1 and {_INT32_MAX}, got {self.key_delay}")
        if isinstance(self.priority, bool) or not isinstance(self.priority, int):
            raise TypeError(f"priority must be an int, got {type(self.priority).__name__}")
        if not _INT32_MIN <= self.priority <= _INT32_MAX:
            raise ValueError(
                f"priority must not be outside the signed 32-bit range, got {self.priority}"
            )
        if not isinstance(self.replacement_mode, ReplacementMode):
            raise TypeError(
                "replacement_mode must be a ReplacementMode member, got "
                f"{type(self.replacement_mode).__name__}"
            )
        if not isinstance(self.send_mode, ResolvedSendMode):
            raise TypeError(
                f"send_mode must be a ResolvedSendMode member, got {type(self.send_mode).__name__}"
            )

        for field_name in binary_field_names:
            value = getattr(self, field_name)
            if not isinstance(value, SettingState):
                raise TypeError(
                    f"{field_name} must be a SettingState member, got {type(value).__name__}"
                )

    @classmethod
    def from_options(
        cls,
        options: HotstringOptions,
        *,
        defaults: ResolvedHotstringOptions,
    ) -> Self:
        """Resolve one parsed declaration against concrete applicable defaults.

        Each explicitly set value in `options` overrides the corresponding
        value in `defaults`; each `InheritedState.INHERIT` value leaves the
        applicable default unchanged.

        Explicit `SI` is resolved to SendInput with SendPlay fallback, while
        an inherited built-in default can remain SendInput with SendEvent
        fallback. This preserves AutoHotkey's distinction between those cases.

        Args:
            options:
                Parsed per-hotstring declaration to resolve.
            defaults:
                Fully resolved defaults applicable to the declaration.

        Returns:
            New fully resolved option state.

        Raises:
            TypeError:
                If either argument has an invalid type.
            RuntimeError:
                If the parsed and resolved option models stop exposing the
                same option field names.
        """
        if not isinstance(options, HotstringOptions):
            raise TypeError(
                f"options must be a HotstringOptions instance, got {type(options).__name__}"
            )
        if not isinstance(defaults, cls):
            raise TypeError(
                f"defaults must be a {cls.__name__} instance, got {type(defaults).__name__}"
            )

        parsed_field_names = {
            field_info.name for field_info in fields(options) if field_info.name != "options"
        }
        resolved_field_names = {field_info.name for field_info in fields(cls)}
        if parsed_field_names != resolved_field_names:
            raise RuntimeError(
                "HotstringOptions and ResolvedHotstringOptions option fields are inconsistent."
            )

        overrides: dict[str, object] = {}
        for name in resolved_field_names:
            value = getattr(options, name)
            if value is InheritedState.INHERIT:
                continue

            if name == "send_mode":
                if value is SendMode.INPUT:
                    overrides[name] = ResolvedSendMode.INPUT_WITH_PLAY_FALLBACK
                elif value is SendMode.PLAY:
                    overrides[name] = ResolvedSendMode.PLAY
                elif value is SendMode.EVENT:
                    overrides[name] = ResolvedSendMode.EVENT
                else:
                    raise RuntimeError(f"Unhandled explicit send mode: {value!r}")
            else:
                overrides[name] = value

        return cast(Self, replace(defaults, **overrides))

__post_init__

__post_init__() -> None

Validate the resolved option state.

Raises:

Type	Description
TypeError	If any field has an invalid type.
ValueError	If any numeric field is outside its accepted range.

Source code in hotstring\core\options.py

def __post_init__(self) -> None:
    """Validate the resolved option state.

    Raises:
        TypeError:
            If any field has an invalid type.
        ValueError:
            If any numeric field is outside its accepted range.
    """
    binary_field_names = (
        "ending_character_optional",
        "trigger_inside_word",
        "automatic_backspacing",
        "omit_ending_character",
        "suspend_exempt",
        "execute",
        "reset_recognizer",
    )

    if not isinstance(self.case_mode, CaseMode):
        raise TypeError(
            f"case_mode must be a CaseMode member, got {type(self.case_mode).__name__}"
        )
    if isinstance(self.key_delay, bool) or not isinstance(self.key_delay, int):
        raise TypeError(f"key_delay must be an int, got {type(self.key_delay).__name__}")
    if not -1 <= self.key_delay <= _INT32_MAX:
        raise ValueError(f"key_delay must be between -1 and {_INT32_MAX}, got {self.key_delay}")
    if isinstance(self.priority, bool) or not isinstance(self.priority, int):
        raise TypeError(f"priority must be an int, got {type(self.priority).__name__}")
    if not _INT32_MIN <= self.priority <= _INT32_MAX:
        raise ValueError(
            f"priority must not be outside the signed 32-bit range, got {self.priority}"
        )
    if not isinstance(self.replacement_mode, ReplacementMode):
        raise TypeError(
            "replacement_mode must be a ReplacementMode member, got "
            f"{type(self.replacement_mode).__name__}"
        )
    if not isinstance(self.send_mode, ResolvedSendMode):
        raise TypeError(
            f"send_mode must be a ResolvedSendMode member, got {type(self.send_mode).__name__}"
        )

    for field_name in binary_field_names:
        value = getattr(self, field_name)
        if not isinstance(value, SettingState):
            raise TypeError(
                f"{field_name} must be a SettingState member, got {type(value).__name__}"
            )

from_options classmethod

from_options(
    options: HotstringOptions,
    *,
    defaults: ResolvedHotstringOptions,
) -> Self

Resolve one parsed declaration against concrete applicable defaults.

Each explicitly set value in options overrides the corresponding value in defaults; each InheritedState.INHERIT value leaves the applicable default unchanged.

Explicit SI is resolved to SendInput with SendPlay fallback, while an inherited built-in default can remain SendInput with SendEvent fallback. This preserves AutoHotkey's distinction between those cases.

Parameters:

Name	Type	Description	Default
options	HotstringOptions	Parsed per-hotstring declaration to resolve.	required
defaults	ResolvedHotstringOptions	Fully resolved defaults applicable to the declaration.	required

Returns:

Type	Description
Self	New fully resolved option state.

Raises:

Type	Description
TypeError	If either argument has an invalid type.
RuntimeError	If the parsed and resolved option models stop exposing the same option field names.

Source code in hotstring\core\options.py

@classmethod
def from_options(
    cls,
    options: HotstringOptions,
    *,
    defaults: ResolvedHotstringOptions,
) -> Self:
    """Resolve one parsed declaration against concrete applicable defaults.

    Each explicitly set value in `options` overrides the corresponding
    value in `defaults`; each `InheritedState.INHERIT` value leaves the
    applicable default unchanged.

    Explicit `SI` is resolved to SendInput with SendPlay fallback, while
    an inherited built-in default can remain SendInput with SendEvent
    fallback. This preserves AutoHotkey's distinction between those cases.

    Args:
        options:
            Parsed per-hotstring declaration to resolve.
        defaults:
            Fully resolved defaults applicable to the declaration.

    Returns:
        New fully resolved option state.

    Raises:
        TypeError:
            If either argument has an invalid type.
        RuntimeError:
            If the parsed and resolved option models stop exposing the
            same option field names.
    """
    if not isinstance(options, HotstringOptions):
        raise TypeError(
            f"options must be a HotstringOptions instance, got {type(options).__name__}"
        )
    if not isinstance(defaults, cls):
        raise TypeError(
            f"defaults must be a {cls.__name__} instance, got {type(defaults).__name__}"
        )

    parsed_field_names = {
        field_info.name for field_info in fields(options) if field_info.name != "options"
    }
    resolved_field_names = {field_info.name for field_info in fields(cls)}
    if parsed_field_names != resolved_field_names:
        raise RuntimeError(
            "HotstringOptions and ResolvedHotstringOptions option fields are inconsistent."
        )

    overrides: dict[str, object] = {}
    for name in resolved_field_names:
        value = getattr(options, name)
        if value is InheritedState.INHERIT:
            continue

        if name == "send_mode":
            if value is SendMode.INPUT:
                overrides[name] = ResolvedSendMode.INPUT_WITH_PLAY_FALLBACK
            elif value is SendMode.PLAY:
                overrides[name] = ResolvedSendMode.PLAY
            elif value is SendMode.EVENT:
                overrides[name] = ResolvedSendMode.EVENT
            else:
                raise RuntimeError(f"Unhandled explicit send mode: {value!r}")
        else:
            overrides[name] = value

    return cast(Self, replace(defaults, **overrides))

Conflict detection

conflicts

Detect trigger-recognition conflicts between candidate and existing hotstrings.

Conflict detection models the three trigger-recognition dimensions relevant to whether two hotstrings can activate on overlapping typed text:

• case sensitivity (C / C0 / C1);
• whether an alphanumeric predecessor is permitted (? / ?0);
• whether an ending character is required (* / *0).

Other hotstring options affect replacement or execution behavior rather than trigger recognition and therefore do not restrict conflict checking.

ConflictKind

Bases: Enum

Classify why two hotstrings conflict.

Attributes:

Name	Type	Description
SAME_TRIGGER		Candidate and existing definitions can recognize the same complete trigger text.
EXISTING_FIRES_DURING_CANDIDATE		The existing definition can become eligible while a valid typed form of the candidate trigger is being entered.
CANDIDATE_FIRES_DURING_EXISTING		The candidate can become eligible while a valid typed form of the existing trigger is being entered.

Source code in hotstring\core\conflicts.py

class ConflictKind(Enum):
    """Classify why two hotstrings conflict.

    Attributes:
        SAME_TRIGGER:
            Candidate and existing definitions can recognize the same complete
            trigger text.
        EXISTING_FIRES_DURING_CANDIDATE:
            The existing definition can become eligible while a valid typed
            form of the candidate trigger is being entered.
        CANDIDATE_FIRES_DURING_EXISTING:
            The candidate can become eligible while a valid typed form of the
            existing trigger is being entered.
    """

    SAME_TRIGGER = "same trigger"
    EXISTING_FIRES_DURING_CANDIDATE = (
        "existing hotstring can activate while candidate is typed"
    )
    CANDIDATE_FIRES_DURING_EXISTING = (
        "candidate can activate while existing hotstring is typed"
    )

HotstringConflict dataclass

Describe one conflict between a candidate and an existing definition.

Attributes:

Name	Type	Description
candidate	CandidateHotstring	Candidate involved in the conflict.
existing	ExistingHotstring	Existing definition involved in the conflict.
kind	ConflictKind	Conflict classification.
reason	str	Human-readable explanation of the matching overlap.

Source code in hotstring\core\conflicts.py

@dataclass(frozen=True, slots=True)
class HotstringConflict:
    """Describe one conflict between a candidate and an existing definition.

    Attributes:
        candidate:
            Candidate involved in the conflict.
        existing:
            Existing definition involved in the conflict.
        kind:
            Conflict classification.
        reason:
            Human-readable explanation of the matching overlap.
    """

    candidate: CandidateHotstring
    existing: ExistingHotstring
    kind: ConflictKind
    reason: str

CandidateAssessment dataclass

Represent all conflicts discovered for one candidate.

Attributes:

Name	Type	Description
candidate	CandidateHotstring	Candidate that was checked.
conflicts	tuple[HotstringConflict, ...]	All conflicting existing hotstrings.

Source code in hotstring\core\conflicts.py

@dataclass(frozen=True, slots=True)
class CandidateAssessment:
    """Represent all conflicts discovered for one candidate.

    Attributes:
        candidate:
            Candidate that was checked.
        conflicts:
            All conflicting existing hotstrings.
    """

    candidate: CandidateHotstring
    conflicts: tuple[HotstringConflict, ...]

    @property
    def is_accepted(self) -> bool:
        """Return whether the candidate has no detected conflicts.

        Returns:
            Whether the candidate is conflict-free.
        """
        return not self.conflicts

is_accepted property

is_accepted: bool

Return whether the candidate has no detected conflicts.

Returns:

Type	Description
bool	Whether the candidate is conflict-free.

_TriggerOverlap dataclass

Describe a trigger occurrence satisfying both recognition boundaries.

Attributes:

Name	Type	Description
start	int	Inclusive start index inside the containing semantic trigger.
end	int	Exclusive end index inside the containing semantic trigger.
left_reason	str	Explanation of the valid left boundary.
right_reason	str	Explanation of the valid right boundary.

Source code in hotstring\core\conflicts.py

@dataclass(frozen=True, slots=True)
class _TriggerOverlap:
    """Describe a trigger occurrence satisfying both recognition boundaries.

    Attributes:
        start:
            Inclusive start index inside the containing semantic trigger.
        end:
            Exclusive end index inside the containing semantic trigger.
        left_reason:
            Explanation of the valid left boundary.
        right_reason:
            Explanation of the valid right boundary.
    """

    start: int
    end: int
    left_reason: str
    right_reason: str

    @property
    def reason(self) -> str:
        """Return the combined boundary explanation.

        Returns:
            Human-readable explanation of both boundaries.
        """
        return f"{self.left_reason}; {self.right_reason}"

reason property

reason: str

Return the combined boundary explanation.

Returns:

Type	Description
str	Human-readable explanation of both boundaries.

find_conflict

find_conflict(
    candidate: CandidateHotstring,
    existing: ExistingHotstring,
    *,
    ending_chars: frozenset[str] = DEFAULT_ENDING_CHARS,
    option_defaults: ResolvedHotstringOptions = DEFAULT_HOTSTRING_OPTIONS,
) -> HotstringConflict | None

Check one candidate against one existing hotstring.

All combinations of case sensitivity, inside-word recognition, and ending-character requirements are supported for both definitions.

Parameters:

Name	Type	Description	Default
candidate	CandidateHotstring	Candidate to check.	required
existing	ExistingHotstring	Existing definition to compare against.	required
ending_chars	frozenset[str]	Effective AutoHotkey ending-character set.	DEFAULT_ENDING_CHARS
option_defaults	ResolvedHotstringOptions	Fully resolved defaults applicable to inherited hotstring options.	DEFAULT_HOTSTRING_OPTIONS

Returns:

Type	Description
HotstringConflict | None	Detected conflict, or None when the pair does not conflict.

Source code in hotstring\core\conflicts.py

def find_conflict(
    candidate: CandidateHotstring,
    existing: ExistingHotstring,
    *,
    ending_chars: frozenset[str] = DEFAULT_ENDING_CHARS,
    option_defaults: ResolvedHotstringOptions = DEFAULT_HOTSTRING_OPTIONS,
) -> HotstringConflict | None:
    """Check one candidate against one existing hotstring.

    All combinations of case sensitivity, inside-word recognition, and
    ending-character requirements are supported for both definitions.

    Args:
        candidate:
            Candidate to check.
        existing:
            Existing definition to compare against.
        ending_chars:
            Effective AutoHotkey ending-character set.
        option_defaults:
            Fully resolved defaults applicable to inherited hotstring options.

    Returns:
        Detected conflict, or `None` when the pair does not conflict.
    """
    candidate_options = ResolvedHotstringOptions.from_options(
        candidate.options,
        defaults=option_defaults,
    )
    existing_options = ResolvedHotstringOptions.from_options(
        existing.options,
        defaults=option_defaults,
    )

    return _find_candidate_conflict(
        candidate,
        candidate_options,
        existing,
        existing_options,
        ending_chars=ending_chars,
    )

assess_candidate

assess_candidate(
    candidate: CandidateHotstring,
    existing_hotstrings: Sequence[ExistingHotstring],
    *,
    ending_chars: frozenset[str] = DEFAULT_ENDING_CHARS,
    option_defaults: ResolvedHotstringOptions = DEFAULT_HOTSTRING_OPTIONS,
) -> CandidateAssessment

Check one candidate against all existing definitions.

Parameters:

Name	Type	Description	Default
candidate	CandidateHotstring	Candidate to evaluate.	required
existing_hotstrings	Sequence[ExistingHotstring]	Existing definitions to compare against.	required
ending_chars	frozenset[str]	Effective AutoHotkey ending-character set.	DEFAULT_ENDING_CHARS
option_defaults	ResolvedHotstringOptions	Fully resolved defaults applicable to inherited hotstring options.	DEFAULT_HOTSTRING_OPTIONS

Returns:

Type	Description
CandidateAssessment	Complete candidate assessment.

Source code in hotstring\core\conflicts.py

def assess_candidate(
    candidate: CandidateHotstring,
    existing_hotstrings: Sequence[ExistingHotstring],
    *,
    ending_chars: frozenset[str] = DEFAULT_ENDING_CHARS,
    option_defaults: ResolvedHotstringOptions = DEFAULT_HOTSTRING_OPTIONS,
) -> CandidateAssessment:
    """Check one candidate against all existing definitions.

    Args:
        candidate:
            Candidate to evaluate.
        existing_hotstrings:
            Existing definitions to compare against.
        ending_chars:
            Effective AutoHotkey ending-character set.
        option_defaults:
            Fully resolved defaults applicable to inherited hotstring options.

    Returns:
        Complete candidate assessment.
    """
    candidate_options = ResolvedHotstringOptions.from_options(
        candidate.options,
        defaults=option_defaults,
    )

    conflicts: list[HotstringConflict] = []
    for existing in existing_hotstrings:
        existing_options = ResolvedHotstringOptions.from_options(
            existing.options,
            defaults=option_defaults,
        )
        conflict = _find_candidate_conflict(
            candidate,
            candidate_options,
            existing,
            existing_options,
            ending_chars=ending_chars,
        )
        if conflict is not None:
            conflicts.append(conflict)

    return CandidateAssessment(candidate=candidate, conflicts=tuple(conflicts))

assess_candidates

assess_candidates(
    candidates: Sequence[CandidateHotstring],
    existing_hotstrings: Sequence[ExistingHotstring],
    *,
    ending_chars: frozenset[str] = DEFAULT_ENDING_CHARS,
    option_defaults: ResolvedHotstringOptions = DEFAULT_HOTSTRING_OPTIONS,
) -> tuple[CandidateAssessment, ...]

Check multiple candidates against all existing definitions.

Candidate-to-candidate checking is intentionally not performed here; typo-generation aggregation handles internal candidate ambiguity before the full pipeline reaches this stage.

Parameters:

Name	Type	Description	Default
candidates	Sequence[CandidateHotstring]	Candidates to evaluate.	required
existing_hotstrings	Sequence[ExistingHotstring]	Existing definitions to compare against.	required
ending_chars	frozenset[str]	Effective ending-character set.	DEFAULT_ENDING_CHARS
option_defaults	ResolvedHotstringOptions	Fully resolved defaults applicable to inherited hotstring options.	DEFAULT_HOTSTRING_OPTIONS

Returns:

Type	Description
tuple[CandidateAssessment, ...]	Candidate assessments in input order.

Source code in hotstring\core\conflicts.py

def assess_candidates(
    candidates: Sequence[CandidateHotstring],
    existing_hotstrings: Sequence[ExistingHotstring],
    *,
    ending_chars: frozenset[str] = DEFAULT_ENDING_CHARS,
    option_defaults: ResolvedHotstringOptions = DEFAULT_HOTSTRING_OPTIONS,
) -> tuple[CandidateAssessment, ...]:
    """Check multiple candidates against all existing definitions.

    Candidate-to-candidate checking is intentionally not performed here;
    typo-generation aggregation handles internal candidate ambiguity before
    the full pipeline reaches this stage.

    Args:
        candidates:
            Candidates to evaluate.
        existing_hotstrings:
            Existing definitions to compare against.
        ending_chars:
            Effective ending-character set.
        option_defaults:
            Fully resolved defaults applicable to inherited hotstring options.

    Returns:
        Candidate assessments in input order.
    """
    return tuple(
        assess_candidate(
            candidate,
            existing_hotstrings,
            ending_chars=ending_chars,
            option_defaults=option_defaults,
        )
        for candidate in candidates
    )

_find_candidate_conflict

_find_candidate_conflict(
    candidate: CandidateHotstring,
    candidate_options: ResolvedHotstringOptions,
    existing: ExistingHotstring,
    existing_options: ResolvedHotstringOptions,
    *,
    ending_chars: frozenset[str],
) -> HotstringConflict | None

Check one existing definition against one candidate.

Parameters:

Name	Type	Description	Default
candidate	CandidateHotstring	Candidate definition.	required
candidate_options	ResolvedHotstringOptions	Fully resolved candidate options.	required
existing	ExistingHotstring	Existing definition.	required
existing_options	ResolvedHotstringOptions	Fully resolved existing options.	required
ending_chars	frozenset[str]	Effective ending-character set.	required

Returns:

Type	Description
HotstringConflict | None	Detected conflict, or None.

Source code in hotstring\core\conflicts.py

def _find_candidate_conflict(
    candidate: CandidateHotstring,
    candidate_options: ResolvedHotstringOptions,
    existing: ExistingHotstring,
    existing_options: ResolvedHotstringOptions,
    *,
    ending_chars: frozenset[str],
) -> HotstringConflict | None:
    """Check one existing definition against one candidate.

    Args:
        candidate:
            Candidate definition.
        candidate_options:
            Fully resolved candidate options.
        existing:
            Existing definition.
        existing_options:
            Fully resolved existing options.
        ending_chars:
            Effective ending-character set.

    Returns:
        Detected conflict, or `None`.
    """
    candidate_case_sensitive = candidate_options.case_mode is CaseMode.SENSITIVE
    existing_case_sensitive = existing_options.case_mode is CaseMode.SENSITIVE

    if _same_trigger_can_match(
        candidate,
        candidate_case_sensitive=candidate_case_sensitive,
        existing=existing,
        existing_case_sensitive=existing_case_sensitive,
    ):
        return HotstringConflict(
            candidate=candidate,
            existing=existing,
            kind=ConflictKind.SAME_TRIGGER,
            reason=(
                "The candidate and existing hotstring can recognize the same "
                "complete trigger text."
            ),
        )

    existing_overlap = next(
        _iter_trigger_overlaps(
            trigger=existing,
            container=candidate,
            allow_alphanumeric_predecessor=(
                existing_options.trigger_inside_word is SettingState.ENABLED
            ),
            require_ending_character=(
                existing_options.ending_character_optional is SettingState.DISABLED
            ),
            trigger_case_sensitive=existing_case_sensitive,
            container_case_sensitive=candidate_case_sensitive,
            ending_chars=ending_chars,
        ),
        None,
    )
    if existing_overlap is not None:
        return HotstringConflict(
            candidate=candidate,
            existing=existing,
            kind=ConflictKind.EXISTING_FIRES_DURING_CANDIDATE,
            reason=(
                "The existing hotstring can activate while the candidate is "
                f"being typed: {existing_overlap.reason}."
            ),
        )

    candidate_overlap = next(
        _iter_trigger_overlaps(
            trigger=candidate,
            container=existing,
            allow_alphanumeric_predecessor=(
                candidate_options.trigger_inside_word is SettingState.ENABLED
            ),
            require_ending_character=(
                candidate_options.ending_character_optional is SettingState.DISABLED
            ),
            trigger_case_sensitive=candidate_case_sensitive,
            container_case_sensitive=existing_case_sensitive,
            ending_chars=ending_chars,
        ),
        None,
    )
    if candidate_overlap is not None:
        return HotstringConflict(
            candidate=candidate,
            existing=existing,
            kind=ConflictKind.CANDIDATE_FIRES_DURING_EXISTING,
            reason=(
                "The candidate can activate while the existing hotstring is "
                f"being typed: {candidate_overlap.reason}."
            ),
        )

    return None

_same_trigger_can_match

_same_trigger_can_match(
    candidate: Hotstring,
    *,
    candidate_case_sensitive: bool,
    existing: Hotstring,
    existing_case_sensitive: bool,
) -> bool

Return whether two complete trigger definitions share a typed form.

If both hotstrings are case-sensitive, their semantic triggers must match exactly. If either definition is case-insensitive, a shared casing exists whenever their AutoHotkey-compatible case-insensitive keys are equal.

Parameters:

Name	Type	Description	Default
candidate	Hotstring	First hotstring.	required
candidate_case_sensitive	bool	Whether the first hotstring requires exact case.	required
existing	Hotstring	Second hotstring.	required
existing_case_sensitive	bool	Whether the second hotstring requires exact case.	required

Returns:

Type	Description
bool	Whether the two complete trigger definitions can recognize the same
bool	typed text.

Source code in hotstring\core\conflicts.py

def _same_trigger_can_match(
    candidate: Hotstring,
    *,
    candidate_case_sensitive: bool,
    existing: Hotstring,
    existing_case_sensitive: bool,
) -> bool:
    """Return whether two complete trigger definitions share a typed form.

    If both hotstrings are case-sensitive, their semantic triggers must match
    exactly. If either definition is case-insensitive, a shared casing exists
    whenever their AutoHotkey-compatible case-insensitive keys are equal.

    Args:
        candidate:
            First hotstring.
        candidate_case_sensitive:
            Whether the first hotstring requires exact case.
        existing:
            Second hotstring.
        existing_case_sensitive:
            Whether the second hotstring requires exact case.

    Returns:
        Whether the two complete trigger definitions can recognize the same
        typed text.
    """
    if candidate_case_sensitive and existing_case_sensitive:
        return candidate.semantic_trigger == existing.semantic_trigger

    return (
        candidate.case_insensitive_semantic_trigger_key
        == existing.case_insensitive_semantic_trigger_key
    )

_iter_trigger_overlaps

_iter_trigger_overlaps(
    *,
    trigger: Hotstring,
    container: Hotstring,
    allow_alphanumeric_predecessor: bool,
    require_ending_character: bool,
    trigger_case_sensitive: bool,
    container_case_sensitive: bool,
    ending_chars: frozenset[str],
) -> Iterator[_TriggerOverlap]

Yield occurrences satisfying trigger recognition and both boundaries.

trigger is the hotstring whose ability to activate is being tested. container is the other hotstring whose trigger is being typed.

Case handling must consider both definitions. If both are case-sensitive, only the exact source-defined casing of the container is a valid typed form. If either is case-insensitive, a shared casing can exist for an occurrence whenever the corresponding case-insensitive keys match.

Parameters:

Name	Type	Description	Default
trigger	Hotstring	Hotstring whose activation is being tested.	required
container	Hotstring	Other hotstring whose semantic trigger is being typed around it.	required
allow_alphanumeric_predecessor	bool	Whether the tested hotstring permits an alphanumeric predecessor.	required
require_ending_character	bool	Whether the tested hotstring requires an ending character.	required
trigger_case_sensitive	bool	Whether the tested hotstring requires exact trigger casing.	required
container_case_sensitive	bool	Whether the containing hotstring requires exact trigger casing.	required
ending_chars	frozenset[str]	Effective ending-character set.	required

Yields:

Type	Description
_TriggerOverlap	Every boundary-valid occurrence.

Source code in hotstring\core\conflicts.py

def _iter_trigger_overlaps(
    *,
    trigger: Hotstring,
    container: Hotstring,
    allow_alphanumeric_predecessor: bool,
    require_ending_character: bool,
    trigger_case_sensitive: bool,
    container_case_sensitive: bool,
    ending_chars: frozenset[str],
) -> Iterator[_TriggerOverlap]:
    """Yield occurrences satisfying trigger recognition and both boundaries.

    `trigger` is the hotstring whose ability to activate is being tested.
    `container` is the other hotstring whose trigger is being typed.

    Case handling must consider *both* definitions. If both are case-sensitive,
    only the exact source-defined casing of the container is a valid typed
    form. If either is case-insensitive, a shared casing can exist for an
    occurrence whenever the corresponding case-insensitive keys match.

    Args:
        trigger:
            Hotstring whose activation is being tested.
        container:
            Other hotstring whose semantic trigger is being typed around it.
        allow_alphanumeric_predecessor:
            Whether the tested hotstring permits an alphanumeric predecessor.
        require_ending_character:
            Whether the tested hotstring requires an ending character.
        trigger_case_sensitive:
            Whether the tested hotstring requires exact trigger casing.
        container_case_sensitive:
            Whether the containing hotstring requires exact trigger casing.
        ending_chars:
            Effective ending-character set.

    Yields:
        Every boundary-valid occurrence.
    """
    if len(trigger.semantic_trigger) > len(container.semantic_trigger):
        return

    require_exact_case = trigger_case_sensitive and container_case_sensitive

    for start in _iter_hotstring_occurrence_starts(
        trigger=trigger,
        container=container,
        require_exact_case=require_exact_case,
    ):
        end = start + len(trigger.semantic_trigger)

        left_reason = _left_boundary_reason(
            container=container.semantic_trigger,
            start=start,
            allow_alphanumeric_predecessor=allow_alphanumeric_predecessor,
        )
        if left_reason is None:
            continue

        right_reason = _right_boundary_reason(
            container=container.semantic_trigger,
            end=end,
            require_ending_character=require_ending_character,
            ending_chars=ending_chars,
        )
        if right_reason is None:
            continue

        yield _TriggerOverlap(
            start=start,
            end=end,
            left_reason=left_reason,
            right_reason=right_reason,
        )

_iter_hotstring_occurrence_starts

_iter_hotstring_occurrence_starts(
    *,
    trigger: Hotstring,
    container: Hotstring,
    require_exact_case: bool,
) -> Iterator[int]

Yield semantic occurrence starts under the required case semantics.

The normal Windows path searches the already cached semantic or case-insensitive trigger strings directly. A defensive fallback preserves original semantic indices if a non-Windows str.lower() transformation changes Unicode string length.

Parameters:

Name	Type	Description	Default
trigger	Hotstring	Hotstring whose semantic trigger is being located.	required
container	Hotstring	Hotstring whose semantic trigger is being searched.	required
require_exact_case	bool	Whether both definitions require exact casing.	required

Yields:

Type	Description
int	Start index of each occurrence in container.semantic_trigger.

Source code in hotstring\core\conflicts.py

def _iter_hotstring_occurrence_starts(
    *,
    trigger: Hotstring,
    container: Hotstring,
    require_exact_case: bool,
) -> Iterator[int]:
    """Yield semantic occurrence starts under the required case semantics.

    The normal Windows path searches the already cached semantic or
    case-insensitive trigger strings directly. A defensive fallback preserves
    original semantic indices if a non-Windows `str.lower()` transformation
    changes Unicode string length.

    Args:
        trigger:
            Hotstring whose semantic trigger is being located.
        container:
            Hotstring whose semantic trigger is being searched.
        require_exact_case:
            Whether both definitions require exact casing.

    Yields:
        Start index of each occurrence in `container.semantic_trigger`.
    """
    if require_exact_case:
        yield from _iter_occurrence_starts(
            trigger=trigger.semantic_trigger,
            container=container.semantic_trigger,
        )
        return

    trigger_key = trigger.case_insensitive_semantic_trigger_key
    container_key = container.case_insensitive_semantic_trigger_key

    if (
        len(trigger_key) == len(trigger.semantic_trigger)
        and len(container_key) == len(container.semantic_trigger)
    ):
        yield from _iter_occurrence_starts(
            trigger=trigger_key,
            container=container_key,
        )
        return

    trigger_length = len(trigger.semantic_trigger)
    for start in range(len(container.semantic_trigger) - trigger_length + 1):
        segment = container.semantic_trigger[start : start + trigger_length]
        if make_case_insensitive_trigger_key(segment) == trigger_key:
            yield start

_iter_occurrence_starts

_iter_occurrence_starts(
    *, trigger: str, container: str
) -> Iterator[int]

Yield every exact string occurrence start, including overlaps.

Repeated str.find() is used instead of a regex lookahead. Advancing the next search by one character, rather than by the matched trigger length, preserves overlapping occurrences such as both ana matches in banana.

Parameters:

Name	Type	Description	Default
trigger	str	Exact string to locate.	required
container	str	String in which to locate it.	required

Yields:

Type	Description
int	Start index of each occurrence.

Source code in hotstring\core\conflicts.py

def _iter_occurrence_starts(*, trigger: str, container: str) -> Iterator[int]:
    """Yield every exact string occurrence start, including overlaps.

    Repeated `str.find()` is used instead of a regex lookahead. Advancing the
    next search by one character, rather than by the matched trigger length,
    preserves overlapping occurrences such as both `ana` matches in
    `banana`.

    Args:
        trigger:
            Exact string to locate.
        container:
            String in which to locate it.

    Yields:
        Start index of each occurrence.
    """
    start = container.find(trigger)
    while start != -1:
        yield start
        start = container.find(trigger, start + 1)

_left_boundary_reason

_left_boundary_reason(
    *,
    container: str,
    start: int,
    allow_alphanumeric_predecessor: bool,
) -> str | None

Evaluate the left boundary of one occurrence.

Parameters:

Name	Type	Description	Default
container	str	Semantic trigger containing the occurrence.	required
start	int	Occurrence start index.	required
allow_alphanumeric_predecessor	bool	Whether an alphanumeric predecessor is allowed.	required

Returns:

Type	Description
str | None	Explanation of a valid boundary, or None when invalid.

Source code in hotstring\core\conflicts.py

def _left_boundary_reason(
    *, container: str, start: int, allow_alphanumeric_predecessor: bool
) -> str | None:
    """Evaluate the left boundary of one occurrence.

    Args:
        container:
            Semantic trigger containing the occurrence.
        start:
            Occurrence start index.
        allow_alphanumeric_predecessor:
            Whether an alphanumeric predecessor is allowed.

    Returns:
        Explanation of a valid boundary, or `None` when invalid.
    """
    if start == 0:
        return "the occurrence starts at the beginning"

    preceding_char = container[start - 1]
    if not preceding_char.isalnum():
        return f"the preceding character {preceding_char!r} is non-alphanumeric"
    if allow_alphanumeric_predecessor:
        return (
            f"the preceding character {preceding_char!r} is alphanumeric, "
            "but the hotstring permits an alphanumeric predecessor"
        )
    return None

_right_boundary_reason

_right_boundary_reason(
    *,
    container: str,
    end: int,
    require_ending_character: bool,
    ending_chars: frozenset[str],
) -> str | None

Evaluate the right boundary of one occurrence.

Parameters:

Name	Type	Description	Default
container	str	Semantic trigger containing the occurrence.	required
end	int	Exclusive occurrence end index.	required
require_ending_character	bool	Whether activation requires an ending character.	required
ending_chars	frozenset[str]	Effective ending-character set.	required

Returns:

Type	Description
str | None	Explanation of a valid boundary, or None when invalid.

Source code in hotstring\core\conflicts.py

def _right_boundary_reason(
    *,
    container: str,
    end: int,
    require_ending_character: bool,
    ending_chars: frozenset[str],
) -> str | None:
    """Evaluate the right boundary of one occurrence.

    Args:
        container:
            Semantic trigger containing the occurrence.
        end:
            Exclusive occurrence end index.
        require_ending_character:
            Whether activation requires an ending character.
        ending_chars:
            Effective ending-character set.

    Returns:
        Explanation of a valid boundary, or `None` when invalid.
    """
    if not require_ending_character:
        return "the hotstring does not require an ending character"
    if end == len(container):
        return (
            "the occurrence reaches the end of the containing trigger, so a "
            "subsequently typed ending character can activate it"
        )

    following_char = container[end]
    if following_char in ending_chars:
        return f"the following character {following_char!r} is an ending character"
    return None

Core constants

constants

Define generic project constants for AutoHotkey hotstring semantics.

DEFAULT_ENDING_CHARS module-attribute

DEFAULT_ENDING_CHARS: Final[frozenset[str]] = frozenset(
    "-()[]{}':;\"/\\,.?!\n \t"
)

AutoHotkey v2's built-in hotstring ending-character set.

DEFAULT_HOTSTRING_OPTIONS module-attribute

DEFAULT_HOTSTRING_OPTIONS: Final[
    ResolvedHotstringOptions
] = ResolvedHotstringOptions(
    ending_character_optional=SettingState.DISABLED,
    trigger_inside_word=SettingState.DISABLED,
    automatic_backspacing=SettingState.ENABLED,
    case_mode=CaseMode.INSENSITIVE_CONFORMING,
    key_delay=0,
    omit_ending_character=SettingState.DISABLED,
    priority=0,
    replacement_mode=ReplacementMode.NORMAL,
    suspend_exempt=SettingState.DISABLED,
    send_mode=ResolvedSendMode.INPUT_WITH_EVENT_FALLBACK,
    execute=SettingState.DISABLED,
    reset_recognizer=SettingState.DISABLED,
)

AutoHotkey's built-in fully resolved hotstring option defaults.

Pipelines

pipeline

Expose the three independent project execution pipelines.

The full workflow is deliberately implemented as composition of the typo- generation-only and AutoCorrect2-only workflows. Neither subsystem depends on the other, which keeps generation policy separate from AutoHotkey source inspection and conflict detection.

GENERATED_CANDIDATE_OPTIONS module-attribute

GENERATED_CANDIDATE_OPTIONS: Final[HotstringOptions] = (
    HotstringOptions("B0X")
)

Options assigned when the full pipeline converts typo mappings to hotstrings.

FullPipelineResult dataclass

Represent the two results produced by the composed full pipeline.

Attributes:

Name	Type	Description
typo_generation	TypoGenerationResult	Result of typo generation and internal ambiguity filtering.
autocorrect2	AutoCorrect2CheckResult	Result of checking the surviving candidates against AutoCorrect2.

Source code in hotstring\pipeline.py

@dataclass(frozen=True, slots=True)
class FullPipelineResult:
    """Represent the two results produced by the composed full pipeline.

    Attributes:
        typo_generation:
            Result of typo generation and internal ambiguity filtering.
        autocorrect2:
            Result of checking the surviving candidates against AutoCorrect2.
    """

    typo_generation: TypoGenerationResult
    autocorrect2: AutoCorrect2CheckResult

run_typo_generation

run_typo_generation(
    word_list: Sequence[str],
    tasks: Sequence[TypoGenerationTask],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None = None,
    report_path: Path | None = None,
    logger: Logger | None = None,
) -> TypoGenerationResult

Run typo generation and internal ambiguity filtering only.

Parameters:

Name	Type	Description	Default
word_list	Sequence[str]	Source words to corrupt.	required
tasks	Sequence[TypoGenerationTask]	Ordered typo-generation tasks to execute.	required
config	TypoGenerationConfig	Shared MULTYPO generator configuration.	required
n_workers	int | None	Optional process-pool size. None uses the executor default when parallel execution is selected.	None
report_path	Path | None	Optional destination for a typo-generation-only report.	None
logger	Logger | None	Optional orchestration logger forwarded to the execution layer.	None

Returns:

Type	Description
TypoGenerationResult	Aggregated typo-generation result containing valid mappings and
TypoGenerationResult	internally ambiguous noisy forms.

Raises:

Type	Description
TypeError	If task/execution inputs have invalid types.
ValueError	If no generation tasks are supplied or a generation setting is invalid.
RuntimeError	If a parallel generation task fails.
OSError	If a requested report cannot be written.

Source code in hotstring\pipeline.py

def run_typo_generation(
    word_list: Sequence[str],
    tasks: Sequence[TypoGenerationTask],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None = None,
    report_path: Path | None = None,
    logger: logging.Logger | None = None,
) -> TypoGenerationResult:
    """Run typo generation and internal ambiguity filtering only.

    Args:
        word_list:
            Source words to corrupt.
        tasks:
            Ordered typo-generation tasks to execute.
        config:
            Shared MULTYPO generator configuration.
        n_workers:
            Optional process-pool size. `None` uses the executor default when
            parallel execution is selected.
        report_path:
            Optional destination for a typo-generation-only report.
        logger:
            Optional orchestration logger forwarded to the execution layer.

    Returns:
        Aggregated typo-generation result containing valid mappings and
        internally ambiguous noisy forms.

    Raises:
        TypeError:
            If task/execution inputs have invalid types.
        ValueError:
            If no generation tasks are supplied or a generation setting is
            invalid.
        RuntimeError:
            If a parallel generation task fails.
        OSError:
            If a requested report cannot be written.
    """
    words = list(word_list)
    task_tuple = tuple(tasks)
    samples = execute_typo_generation_tasks(
        words,
        task_tuple,
        config,
        n_workers=n_workers,
        logger=logger,
    )
    result = aggregate_typo_samples(
        samples,
        config=config,
        tasks=task_tuple,
        source_word_count=len(words),
    )

    if report_path is not None:
        _write_report(
            report_path,
            "TYPO GENERATION REPORT",
            create_typo_generation_report(result),
        )

    return result

run_autocorrect2_check

run_autocorrect2_check(
    candidates: Sequence[AutoCorrect2CandidateHotstring],
    *,
    project_dir: Path,
    report_path: Path | None = None,
    write_accepted: bool = False,
) -> AutoCorrect2CheckResult

Check manually supplied candidates against active AutoCorrect2 hotstrings.

Trigger conflict detection supports every combination of the recognition options currently modeled by the project: ending-character-free matching (*), inside-word matching (?), and case-sensitive matching (C). No candidate is rejected merely for using one of those semantics.

Parameters:

Name	Type	Description	Default
candidates	Sequence[AutoCorrect2CandidateHotstring]	AutoCorrect2 candidates supplied directly by the caller.	required
project_dir	Path	AutoCorrect2 project directory containing the configured source files.	required
report_path	Path | None	Optional destination for an AutoCorrect2-only report.	None
write_accepted	bool	Append accepted candidates to the generated include file when True.	False

Returns:

Type	Description
AutoCorrect2CheckResult	Conflict-check result partitioning candidates into accepted and
AutoCorrect2CheckResult	rejected groups.

Raises:

Type	Description
FileNotFoundError	If a required AutoCorrect2 source file is missing.
UnicodeDecodeError	If a source requiring parsing is not valid UTF-8 text.
ValueError	If source data is invalid or writing is requested for a candidate that violates the writer's explicit B0X contract.
OSError	If authoritative sources, reports, or generated files cannot be read or written.

Source code in hotstring\pipeline.py

def run_autocorrect2_check(
    candidates: Sequence[AutoCorrect2CandidateHotstring],
    *,
    project_dir: Path,
    report_path: Path | None = None,
    write_accepted: bool = False,
) -> AutoCorrect2CheckResult:
    """Check manually supplied candidates against active AutoCorrect2 hotstrings.

    Trigger conflict detection supports every combination of the recognition
    options currently modeled by the project: ending-character-free matching
    (`*`), inside-word matching (`?`), and case-sensitive matching (`C`). No
    candidate is rejected merely for using one of those semantics.

    Args:
        candidates:
            AutoCorrect2 candidates supplied directly by the caller.
        project_dir:
            AutoCorrect2 project directory containing the configured source
            files.
        report_path:
            Optional destination for an AutoCorrect2-only report.
        write_accepted:
            Append accepted candidates to the generated include file when
            `True`.

    Returns:
        Conflict-check result partitioning candidates into accepted and
        rejected groups.

    Raises:
        FileNotFoundError:
            If a required AutoCorrect2 source file is missing.
        UnicodeDecodeError:
            If a source requiring parsing is not valid UTF-8 text.
        ValueError:
            If source data is invalid or writing is requested for a candidate
            that violates the writer's explicit `B0X` contract.
        OSError:
            If authoritative sources, reports, or generated files cannot be
            read or written.
    """
    candidate_tuple = tuple(candidates)
    existing_hotstrings = load_existing_hotstrings(project_dir)
    assessments = assess_candidates(candidate_tuple, existing_hotstrings)

    accepted: list[AutoCorrect2CandidateHotstring] = []
    rejected = []
    for candidate, assessment in zip(candidate_tuple, assessments, strict=True):
        if assessment.is_accepted:
            accepted.append(candidate)
        else:
            rejected.append(assessment)

    result = AutoCorrect2CheckResult(
        accepted=tuple(accepted),
        rejected=tuple(rejected),
    )

    if write_accepted:
        append_candidates(result.accepted, project_dir=project_dir)

    if report_path is not None:
        _write_report(
            report_path,
            "AUTOCORRECT2 CONFLICT CHECK REPORT",
            create_autocorrect2_report(result),
        )

    return result

run_full_pipeline

run_full_pipeline(
    word_list: Sequence[str],
    tasks: Sequence[TypoGenerationTask],
    config: TypoGenerationConfig,
    *,
    project_dir: Path,
    n_workers: int | None = None,
    report_path: Path | None = None,
    write_accepted: bool = False,
    logger: Logger | None = None,
) -> FullPipelineResult

Run typo generation followed by AutoCorrect2 conflict checking.

The function composes the two independent stage pipelines without asking either stage to emit its own report. Surviving typo mappings are converted to AutoCorrect2CandidateHotstring objects with the project's fixed generated B0X option set.

Parameters:

Name	Type	Description	Default
word_list	Sequence[str]	Source words to corrupt.	required
tasks	Sequence[TypoGenerationTask]	Ordered typo-generation tasks to execute.	required
config	TypoGenerationConfig	Shared MULTYPO generator configuration.	required
project_dir	Path	AutoCorrect2 project directory.	required
n_workers	int | None	Optional process-pool size.	None
report_path	Path | None	Optional destination for the combined report.	None
write_accepted	bool	Append final accepted candidates to the generated include file.	False
logger	Logger | None	Optional typo-generation orchestration logger.	None

Returns:

Type	Description
FullPipelineResult	Combined result containing both stage results.

Raises:

Type	Description
TypeError	If generation or source-loading inputs have invalid types.
ValueError	If generation/source data is invalid or a writable candidate violates the generated-file contract.
FileNotFoundError	If a required AutoCorrect2 source file is missing.
UnicodeDecodeError	If an authoritative source requiring parsing is not valid UTF-8.
RuntimeError	If a parallel generation task fails.
OSError	If source, report, or generated files cannot be read or written.

Source code in hotstring\pipeline.py

def run_full_pipeline(
    word_list: Sequence[str],
    tasks: Sequence[TypoGenerationTask],
    config: TypoGenerationConfig,
    *,
    project_dir: Path,
    n_workers: int | None = None,
    report_path: Path | None = None,
    write_accepted: bool = False,
    logger: logging.Logger | None = None,
) -> FullPipelineResult:
    """Run typo generation followed by AutoCorrect2 conflict checking.

    The function composes the two independent stage pipelines without asking
    either stage to emit its own report. Surviving typo mappings are converted
    to [`AutoCorrect2CandidateHotstring`]
    [hotstring.autocorrect2.models.AutoCorrect2CandidateHotstring] objects with
    the project's fixed generated `B0X` option set.

    Args:
        word_list:
            Source words to corrupt.
        tasks:
            Ordered typo-generation tasks to execute.
        config:
            Shared MULTYPO generator configuration.
        project_dir:
            AutoCorrect2 project directory.
        n_workers:
            Optional process-pool size.
        report_path:
            Optional destination for the combined report.
        write_accepted:
            Append final accepted candidates to the generated include file.
        logger:
            Optional typo-generation orchestration logger.

    Returns:
        Combined result containing both stage results.

    Raises:
        TypeError:
            If generation or source-loading inputs have invalid types.
        ValueError:
            If generation/source data is invalid or a writable candidate
            violates the generated-file contract.
        FileNotFoundError:
            If a required AutoCorrect2 source file is missing.
        UnicodeDecodeError:
            If an authoritative source requiring parsing is not valid UTF-8.
        RuntimeError:
            If a parallel generation task fails.
        OSError:
            If source, report, or generated files cannot be read or written.
    """
    typo_result = run_typo_generation(
        word_list,
        tasks,
        config,
        n_workers=n_workers,
        report_path=None,
        logger=logger,
    )

    candidates = tuple(
        AutoCorrect2CandidateHotstring(
            trigger=noisy_word,
            options_input=GENERATED_CANDIDATE_OPTIONS,
            replacement=target_word,
        )
        for noisy_word, target_word in typo_result.candidates.items()
    )

    autocorrect2_result = run_autocorrect2_check(
        candidates,
        project_dir=project_dir,
        report_path=None,
        write_accepted=write_accepted,
    )
    result = FullPipelineResult(
        typo_generation=typo_result,
        autocorrect2=autocorrect2_result,
    )

    if report_path is not None:
        _write_report(
            report_path,
            "AUTOHOTKEY HOTSTRING GENERATION REPORT",
            create_full_pipeline_report(typo_result, autocorrect2_result),
        )

    return result

_write_report

_write_report(
    path: Path, title: str, body_lines: Sequence[str]
) -> None

Build and write one complete report document.

Parameters:

Name	Type	Description	Default
path	Path	Destination report file.	required
title	str	Top-level report title.	required
body_lines	Sequence[str]	Pipeline-specific report body lines.	required

Raises:

Type	Description
ValueError	If the report title is empty.
OSError	If the report cannot be written.

Source code in hotstring\pipeline.py

def _write_report(path: Path, title: str, body_lines: Sequence[str]) -> None:
    """Build and write one complete report document.

    Args:
        path:
            Destination report file.
        title:
            Top-level report title.
        body_lines:
            Pipeline-specific report body lines.

    Raises:
        ValueError:
            If the report title is empty.
        OSError:
            If the report cannot be written.
    """
    document_lines = build_report_document(title, body_lines)
    write_text(path, "\n".join(document_lines) + "\n")

CLI

Command-line interface API

hotstring.cli contains the application layer for the project's command-line interface. It converts command-line input into validated runtime objects and dispatches those objects to the public pipeline APIs.

The subpackage does not implement typo generation, conflict detection, source loading, or generated-file writing. Those responsibilities remain in their respective domain and pipeline modules.

The subpackage contains:

• Application, which defines the CLI entry point, logging setup, process-level error handling, and exit statuses;
• Parser, which defines the top-level parser, the three subcommands, and their arguments;
• Runtime configuration, which loads external inputs, resolves the AutoCorrect2 project directory, constructs typo-generation tasks, and creates immutable command objects;
• Command execution, which dispatches validated command objects to the corresponding pipeline functions and prints terminal summaries.

The package root re-exports main(), allowing the repository-level main.py entry point to import it with:

from hotstring.cli import main

Application

application

Define the command-line application's process boundary.

This module coordinates argument parsing, runtime configuration, logging, and command execution. Domain work remains in hotstring.pipeline, while parser and input-resolution details live in sibling CLI modules.

main

main(argv: Sequence[str] | None = None) -> int

Run the command-line interface.

Parameters:

Name	Type	Description	Default
argv	Sequence[str] | None	Optional argument sequence excluding the executable name. None reads arguments from sys.argv, matching normal command-line use.	None

Returns:

Type	Description
int	Process exit status: zero for success, one for a runtime failure, or
int	130 when execution is interrupted. Invalid command-line input is
int	reported by argparse with status two.

Source code in hotstring\cli\application.py

def main(argv: Sequence[str] | None = None) -> int:
    """Run the command-line interface.

    Args:
        argv:
            Optional argument sequence excluding the executable name. `None`
            reads arguments from `sys.argv`, matching normal command-line use.

    Returns:
        Process exit status: zero for success, one for a runtime failure, or
        130 when execution is interrupted. Invalid command-line input is
        reported by `argparse` with status two.
    """
    parser = create_argument_parser()
    namespace = parser.parse_args(argv)
    _configure_logging(namespace.verbosity)

    try:
        command = create_command_config(namespace)
    except CliConfigurationError as exc:
        parser.error(str(exc))

    try:
        return execute_command(command, logger=_LOGGER)
    except KeyboardInterrupt:
        print(f"{parser.prog}: interrupted", file=sys.stderr)
        return 130
    except Exception as exc:  # noqa: BLE001 - this is the process boundary.
        if _LOGGER.isEnabledFor(logging.DEBUG):
            _LOGGER.exception("Command execution failed")
        else:
            print(f"{parser.prog}: error: {exc}", file=sys.stderr)
        return 1

_configure_logging

_configure_logging(verbosity: int) -> None

Configure application logging for the requested verbosity.

Logging is left untouched at the default verbosity so library consumers and multiprocessing workers do not inherit an unnecessary root handler.

Parameters:

Name	Type	Description	Default
verbosity	int	Number of -v occurrences supplied to the top-level parser.	required

Source code in hotstring\cli\application.py

def _configure_logging(verbosity: int) -> None:
    """Configure application logging for the requested verbosity.

    Logging is left untouched at the default verbosity so library consumers
    and multiprocessing workers do not inherit an unnecessary root handler.

    Args:
        verbosity:
            Number of `-v` occurrences supplied to the top-level parser.
    """
    if verbosity <= 0:
        return

    level = logging.INFO if verbosity == 1 else logging.DEBUG
    logging.basicConfig(
        level=level,
        format="%(levelname)s %(name)s: %(message)s",
    )

Parser

parser

Construct the command-line parser and its three subcommands.

Parser construction is intentionally separate from runtime resolution. This module describes syntax and performs scalar validation; create_command_config() resolves files, environment configuration, and domain objects after parsing succeeds.

create_argument_parser

create_argument_parser() -> ArgumentParser

Create the complete top-level argument parser.

The parser exposes three independent workflows: typo generation, AutoCorrect2 conflict checking, and their composed full pipeline. Shared options are added by private helpers so their spelling and validation stay consistent across subcommands.

Returns:

Type	Description
ArgumentParser	Configured parser ready to parse a command-line argument sequence.

Source code in hotstring\cli\parser.py

def create_argument_parser() -> argparse.ArgumentParser:
    """Create the complete top-level argument parser.

    The parser exposes three independent workflows: typo generation,
    AutoCorrect2 conflict checking, and their composed full pipeline. Shared
    options are added by private helpers so their spelling and validation stay
    consistent across subcommands.

    Returns:
        Configured parser ready to parse a command-line argument sequence.
    """
    parser = argparse.ArgumentParser(description=_PROGRAM_DESCRIPTION)
    parser.add_argument(
        "-v",
        "--verbose",
        dest="verbosity",
        action="count",
        default=0,
        help="increase logging detail; repeat for debug output",
    )

    subparsers = parser.add_subparsers(
        dest="command",
        metavar="COMMAND",
        required=True,
    )

    typo_generation = subparsers.add_parser(
        "typo-generation",
        help="generate and internally validate typo mappings",
        description="Generate typo mappings without inspecting AutoCorrect2.",
    )
    _add_word_source_arguments(typo_generation)
    _add_generation_arguments(typo_generation)
    _add_report_argument(typo_generation)

    autocorrect2_check = subparsers.add_parser(
        "autocorrect2-check",
        help="check supplied candidates against AutoCorrect2",
        description=(
            "Check explicitly supplied candidate hotstrings without running typo generation."
        ),
    )
    _add_candidate_source_arguments(autocorrect2_check)
    _add_autocorrect2_arguments(autocorrect2_check)
    _add_report_argument(autocorrect2_check)

    full_pipeline = subparsers.add_parser(
        "full-pipeline",
        help="generate typos and check them against AutoCorrect2",
        description=(
            "Generate typo candidates, remove internal ambiguity, and check "
            "the survivors against AutoCorrect2."
        ),
    )
    _add_word_source_arguments(full_pipeline)
    _add_generation_arguments(full_pipeline)
    _add_autocorrect2_arguments(full_pipeline)
    _add_report_argument(full_pipeline)

    return parser

_add_word_source_arguments

_add_word_source_arguments(parser: ArgumentParser) -> None

Add the mutually exclusive source-word inputs.

Parameters:

Name	Type	Description	Default
parser	ArgumentParser	Subparser receiving the arguments.	required

Source code in hotstring\cli\parser.py

def _add_word_source_arguments(parser: argparse.ArgumentParser) -> None:
    """Add the mutually exclusive source-word inputs.

    Args:
        parser:
            Subparser receiving the arguments.
    """
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument(
        "--word",
        action="append",
        metavar="WORD",
        help="source word to process; repeat to supply multiple words",
    )
    group.add_argument(
        "--words-file",
        type=Path,
        metavar="PATH",
        help="UTF-8 text file containing one source word per line",
    )

_add_candidate_source_arguments

_add_candidate_source_arguments(
    parser: ArgumentParser,
) -> None

Add the mutually exclusive candidate inputs.

Parameters:

Name	Type	Description	Default
parser	ArgumentParser	Subparser receiving the arguments.	required

Source code in hotstring\cli\parser.py

def _add_candidate_source_arguments(parser: argparse.ArgumentParser) -> None:
    """Add the mutually exclusive candidate inputs.

    Args:
        parser:
            Subparser receiving the arguments.
    """
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument(
        "--candidate",
        action="append",
        nargs=3,
        metavar=("TRIGGER", "REPLACEMENT", "OPTIONS"),
        help=(
            "candidate semantic trigger, replacement, and AHK option string; "
            "repeat to supply multiple candidates"
        ),
    )
    group.add_argument(
        "--candidates-file",
        type=Path,
        metavar="PATH",
        help="UTF-8 JSON file containing candidate objects",
    )

_add_generation_arguments

_add_generation_arguments(parser: ArgumentParser) -> None

Add settings shared by typo-generating commands.

Parameters:

Name	Type	Description	Default
parser	ArgumentParser	Subparser receiving the arguments.	required

Source code in hotstring\cli\parser.py

def _add_generation_arguments(parser: argparse.ArgumentParser) -> None:
    """Add settings shared by typo-generating commands.

    Args:
        parser:
            Subparser receiving the arguments.
    """
    parser.add_argument(
        "--single-attempts",
        dest="single_error_attempts_per_word",
        type=_positive_integer,
        required=True,
        metavar="COUNT",
        help="attempts per word for each forced single-error task",
    )
    parser.add_argument(
        "--multi-attempts",
        dest="multi_error_attempts_per_word",
        type=_positive_integer,
        required=True,
        metavar="COUNT",
        help="attempts per word for the mixed two-error task",
    )
    parser.add_argument(
        "--multi-min-length",
        dest="multi_error_minimum_word_length",
        type=_minimum_two_integer,
        required=True,
        metavar="LENGTH",
        help="minimum word length eligible for the mixed two-error task",
    )
    parser.add_argument(
        "--language",
        type=_nonempty_text,
        default="english",
        metavar="LANGUAGE",
        help="MULTYPO language identifier (default: %(default)s)",
    )
    parser.add_argument(
        "--excluding-set",
        action=argparse.BooleanOptionalAction,
        default=True,
        help="enable or disable MULTYPO's language excluding set",
    )
    parser.add_argument(
        "--keyboard-weights",
        dest="keyboard_neighbor_weights",
        type=_positive_number,
        nargs=2,
        default=(9.0, 1.0),
        metavar=("HORIZONTAL", "VERTICAL"),
        help="relative keyboard-neighbor weights (default: 9 1)",
    )
    parser.add_argument(
        "--workers",
        type=_positive_integer,
        metavar="COUNT",
        help="process-pool size; omit to let the executor choose",
    )

_add_autocorrect2_arguments

_add_autocorrect2_arguments(parser: ArgumentParser) -> None

Add settings shared by AutoCorrect2-aware commands.

Parameters:

Name	Type	Description	Default
parser	ArgumentParser	Subparser receiving the arguments.	required

Source code in hotstring\cli\parser.py

def _add_autocorrect2_arguments(parser: argparse.ArgumentParser) -> None:
    """Add settings shared by AutoCorrect2-aware commands.

    Args:
        parser:
            Subparser receiving the arguments.
    """
    parser.add_argument(
        "--project-dir",
        dest="autocorrect2_project_dir",
        type=Path,
        metavar="PATH",
        help=(
            "AutoCorrect2 project directory; takes precedence over environment "
            "and .env configuration"
        ),
    )
    parser.add_argument(
        "--env-file",
        type=Path,
        metavar="PATH",
        help=(
            f"dotenv file containing {AUTOCORRECT2_PROJECT_DIR_ENV}; used after "
            "the process environment (default fallback: project-root .env)"
        ),
    )
    parser.add_argument(
        "--write-accepted",
        action="store_true",
        help="append accepted candidates to AutoCorrect2's generated include",
    )

_add_report_argument

_add_report_argument(parser: ArgumentParser) -> None

Add the optional report destination.

Parameters:

Name	Type	Description	Default
parser	ArgumentParser	Subparser receiving the argument.	required

Source code in hotstring\cli\parser.py

def _add_report_argument(parser: argparse.ArgumentParser) -> None:
    """Add the optional report destination.

    Args:
        parser:
            Subparser receiving the argument.
    """
    parser.add_argument(
        "--report",
        type=Path,
        metavar="PATH",
        help="write the workflow report to this path",
    )

_positive_integer

_positive_integer(value: str) -> int

Parse a strictly positive integer for argparse.

Parameters:

Name	Type	Description	Default
value	str	Raw argument text.	required

Returns:

Type	Description
int	Parsed positive integer.

Raises:

Type	Description
ArgumentTypeError	If the value is not an integer greater than zero.

Source code in hotstring\cli\parser.py

def _positive_integer(value: str) -> int:
    """Parse a strictly positive integer for `argparse`.

    Args:
        value:
            Raw argument text.

    Returns:
        Parsed positive integer.

    Raises:
        argparse.ArgumentTypeError:
            If the value is not an integer greater than zero.
    """
    try:
        parsed = int(value)
    except ValueError as exc:
        raise argparse.ArgumentTypeError("must be an integer") from exc
    if parsed <= 0:
        raise argparse.ArgumentTypeError("must be greater than zero")
    return parsed

_minimum_two_integer

_minimum_two_integer(value: str) -> int

Parse an integer greater than or equal to two.

Parameters:

Name	Type	Description	Default
value	str	Raw argument text.	required

Returns:

Type	Description
int	Parsed integer.

Raises:

Type	Description
ArgumentTypeError	If the value is not an integer of at least two.

Source code in hotstring\cli\parser.py

def _minimum_two_integer(value: str) -> int:
    """Parse an integer greater than or equal to two.

    Args:
        value:
            Raw argument text.

    Returns:
        Parsed integer.

    Raises:
        argparse.ArgumentTypeError:
            If the value is not an integer of at least two.
    """
    parsed = _positive_integer(value)
    if parsed < 2:
        raise argparse.ArgumentTypeError("must be at least 2")
    return parsed

_positive_number

_positive_number(value: str) -> float

Parse a strictly positive floating-point value.

Parameters:

Name	Type	Description	Default
value	str	Raw argument text.	required

Returns:

Type	Description
float	Parsed positive number.

Raises:

Type	Description
ArgumentTypeError	If the value is not finite and greater than zero.

Source code in hotstring\cli\parser.py

def _positive_number(value: str) -> float:
    """Parse a strictly positive floating-point value.

    Args:
        value:
            Raw argument text.

    Returns:
        Parsed positive number.

    Raises:
        argparse.ArgumentTypeError:
            If the value is not finite and greater than zero.
    """
    try:
        parsed = float(value)
    except ValueError as exc:
        raise argparse.ArgumentTypeError("must be a number") from exc
    if parsed <= 0 or not parsed < float("inf"):
        raise argparse.ArgumentTypeError("must be a finite number greater than zero")
    return parsed

_nonempty_text

_nonempty_text(value: str) -> str

Reject an empty or whitespace-only text argument.

Parameters:

Name	Type	Description	Default
value	str	Raw argument text.	required

Returns:

Type	Description
str	Trimmed text.

Raises:

Type	Description
ArgumentTypeError	If the value contains no non-whitespace characters.

Source code in hotstring\cli\parser.py

def _nonempty_text(value: str) -> str:
    """Reject an empty or whitespace-only text argument.

    Args:
        value:
            Raw argument text.

    Returns:
        Trimmed text.

    Raises:
        argparse.ArgumentTypeError:
            If the value contains no non-whitespace characters.
    """
    parsed = value.strip()
    if not parsed:
        raise argparse.ArgumentTypeError("must not be empty")
    return parsed

Runtime configuration

runtime

Resolve parsed CLI input into immutable runtime command objects.

This module owns the application-specific boundary between argparse values and the project's domain APIs. It loads word and candidate files, constructs TypoGenerationTask objects, resolves the AutoCorrect2 project directory, and validates paths before a pipeline starts.

AUTOCORRECT2_PROJECT_DIR_ENV module-attribute

AUTOCORRECT2_PROJECT_DIR_ENV: Final[str] = (
    "AUTOCORRECT2_PROJECT_DIR"
)

Environment variable containing the local AutoCorrect2 project path.

DEFAULT_ENV_FILE module-attribute

DEFAULT_ENV_FILE: Final[Path] = PROJECT_ROOT / '.env'

Project-local dotenv file consulted as the final configuration source.

CommandConfig

CommandConfig = (
    TypoGenerationCommand
    | AutoCorrect2CheckCommand
    | FullPipelineCommand
)

Union of all command objects accepted by the execution layer.

CliConfigurationError

Bases: ValueError

Indicate invalid runtime configuration supplied through the CLI.

Source code in hotstring\cli\runtime.py

class CliConfigurationError(ValueError):
    """Indicate invalid runtime configuration supplied through the CLI."""

GenerationRuntimeConfig dataclass

Store resolved inputs shared by typo-generating workflows.

Attributes:

Name	Type	Description
words	tuple[str, ...]	Ordered, de-duplicated source words.
tasks	tuple[TypoGenerationTask, ...]	Ordered typo-generation tasks derived from CLI settings.
config	TypoGenerationConfig	Shared MULTYPO generator configuration.
n_workers	int | None	Optional process-pool size.

Source code in hotstring\cli\runtime.py

@dataclass(frozen=True, slots=True)
class GenerationRuntimeConfig:
    """Store resolved inputs shared by typo-generating workflows.

    Attributes:
        words:
            Ordered, de-duplicated source words.
        tasks:
            Ordered typo-generation tasks derived from CLI settings.
        config:
            Shared MULTYPO generator configuration.
        n_workers:
            Optional process-pool size.
    """

    words: tuple[str, ...]
    tasks: tuple[TypoGenerationTask, ...]
    config: TypoGenerationConfig
    n_workers: int | None

AutoCorrect2RuntimeConfig dataclass

Store resolved inputs shared by AutoCorrect2-aware workflows.

Attributes:

Name	Type	Description
project_dir	Path	Validated AutoCorrect2 project directory.
write_accepted	bool	Whether accepted candidates may be appended to the generated include file.

Source code in hotstring\cli\runtime.py

@dataclass(frozen=True, slots=True)
class AutoCorrect2RuntimeConfig:
    """Store resolved inputs shared by AutoCorrect2-aware workflows.

    Attributes:
        project_dir:
            Validated AutoCorrect2 project directory.
        write_accepted:
            Whether accepted candidates may be appended to the generated
            include file.
    """

    project_dir: Path
    write_accepted: bool

TypoGenerationCommand dataclass

Represent one standalone typo-generation invocation.

Attributes:

Name	Type	Description
generation	GenerationRuntimeConfig	Resolved typo-generation inputs.
report_path	Path | None	Optional report destination.

Source code in hotstring\cli\runtime.py

@dataclass(frozen=True, slots=True)
class TypoGenerationCommand:
    """Represent one standalone typo-generation invocation.

    Attributes:
        generation:
            Resolved typo-generation inputs.
        report_path:
            Optional report destination.
    """

    generation: GenerationRuntimeConfig
    report_path: Path | None

AutoCorrect2CheckCommand dataclass

Represent one standalone AutoCorrect2 conflict-check invocation.

Attributes:

Name	Type	Description
candidates	tuple[AutoCorrect2CandidateHotstring, ...]	Candidate hotstrings supplied directly by the user.
autocorrect2	AutoCorrect2RuntimeConfig	Resolved AutoCorrect2 integration settings.
report_path	Path | None	Optional report destination.

Source code in hotstring\cli\runtime.py

@dataclass(frozen=True, slots=True)
class AutoCorrect2CheckCommand:
    """Represent one standalone AutoCorrect2 conflict-check invocation.

    Attributes:
        candidates:
            Candidate hotstrings supplied directly by the user.
        autocorrect2:
            Resolved AutoCorrect2 integration settings.
        report_path:
            Optional report destination.
    """

    candidates: tuple[AutoCorrect2CandidateHotstring, ...]
    autocorrect2: AutoCorrect2RuntimeConfig
    report_path: Path | None

FullPipelineCommand dataclass

Represent one composed generation-and-check invocation.

Attributes:

Name	Type	Description
generation	GenerationRuntimeConfig	Resolved typo-generation inputs.
autocorrect2	AutoCorrect2RuntimeConfig	Resolved AutoCorrect2 integration settings.
report_path	Path | None	Optional combined report destination.

Source code in hotstring\cli\runtime.py

@dataclass(frozen=True, slots=True)
class FullPipelineCommand:
    """Represent one composed generation-and-check invocation.

    Attributes:
        generation:
            Resolved typo-generation inputs.
        autocorrect2:
            Resolved AutoCorrect2 integration settings.
        report_path:
            Optional combined report destination.
    """

    generation: GenerationRuntimeConfig
    autocorrect2: AutoCorrect2RuntimeConfig
    report_path: Path | None

create_command_config

create_command_config(
    namespace: Namespace,
) -> CommandConfig

Convert parsed arguments into one validated command object.

Parameters:

Name	Type	Description	Default
namespace	Namespace	Namespace returned by create_argument_parser().	required

Returns:

Type	Description
CommandConfig	Immutable configuration for the selected workflow.

Raises:

Type	Description
CliConfigurationError	If a file, path, environment value, candidate, or domain setting is invalid.

Source code in hotstring\cli\runtime.py

def create_command_config(namespace: argparse.Namespace) -> CommandConfig:
    """Convert parsed arguments into one validated command object.

    Args:
        namespace:
            Namespace returned by
            [`create_argument_parser()`][hotstring.cli.parser.create_argument_parser].

    Returns:
        Immutable configuration for the selected workflow.

    Raises:
        CliConfigurationError:
            If a file, path, environment value, candidate, or domain setting
            is invalid.
    """
    try:
        report_path = _optional_cli_path(namespace.report)

        if namespace.command == "typo-generation":
            return TypoGenerationCommand(
                generation=_create_generation_config(namespace),
                report_path=report_path,
            )
        if namespace.command == "autocorrect2-check":
            return AutoCorrect2CheckCommand(
                candidates=_load_candidates(namespace),
                autocorrect2=_create_autocorrect2_config(namespace),
                report_path=report_path,
            )
        if namespace.command == "full-pipeline":
            return FullPipelineCommand(
                generation=_create_generation_config(namespace),
                autocorrect2=_create_autocorrect2_config(namespace),
                report_path=report_path,
            )
    except CliConfigurationError:
        raise
    except (OSError, TypeError, ValueError) as exc:
        raise CliConfigurationError(str(exc)) from exc

    raise CliConfigurationError(f"Unsupported command: {namespace.command!r}")

_create_generation_config

_create_generation_config(
    namespace: Namespace,
) -> GenerationRuntimeConfig

Build the shared typo-generation runtime configuration.

Parameters:

Name	Type	Description	Default
namespace	Namespace	Parsed command arguments.	required

Returns:

Type	Description
GenerationRuntimeConfig	Resolved generation configuration.

Source code in hotstring\cli\runtime.py

def _create_generation_config(namespace: argparse.Namespace) -> GenerationRuntimeConfig:
    """Build the shared typo-generation runtime configuration.

    Args:
        namespace:
            Parsed command arguments.

    Returns:
        Resolved generation configuration.
    """
    weights = tuple(float(value) for value in namespace.keyboard_neighbor_weights)
    config = TypoGenerationConfig(
        language=namespace.language,
        use_excluding_set=namespace.excluding_set,
        horizontal_vs_vertical=(weights[0], weights[1]),
    )
    tasks = create_default_typo_generation_tasks(
        single_error_attempts_per_word=namespace.single_error_attempts_per_word,
        multi_error_attempts_per_word=namespace.multi_error_attempts_per_word,
        multi_error_minimum_word_length=namespace.multi_error_minimum_word_length,
    )
    return GenerationRuntimeConfig(
        words=_load_words(namespace),
        tasks=tasks,
        config=config,
        n_workers=namespace.workers,
    )

_create_autocorrect2_config

_create_autocorrect2_config(
    namespace: Namespace,
) -> AutoCorrect2RuntimeConfig

Build the shared AutoCorrect2 runtime configuration.

Parameters:

Name	Type	Description	Default
namespace	Namespace	Parsed command arguments.	required

Returns:

Type	Description
AutoCorrect2RuntimeConfig	Resolved AutoCorrect2 configuration.

Source code in hotstring\cli\runtime.py

def _create_autocorrect2_config(
    namespace: argparse.Namespace,
) -> AutoCorrect2RuntimeConfig:
    """Build the shared AutoCorrect2 runtime configuration.

    Args:
        namespace:
            Parsed command arguments.

    Returns:
        Resolved AutoCorrect2 configuration.
    """
    project_dir = _resolve_autocorrect2_project_dir(
        direct_path=namespace.autocorrect2_project_dir,
        explicit_env_file=namespace.env_file,
    )
    return AutoCorrect2RuntimeConfig(
        project_dir=project_dir,
        write_accepted=namespace.write_accepted,
    )

_load_words

_load_words(namespace: Namespace) -> tuple[str, ...]

Load, normalize, and de-duplicate source words.

Parameters:

Name	Type	Description	Default
namespace	Namespace	Parsed command arguments.	required

Returns:

Type	Description
tuple[str, ...]	Ordered source-word tuple.

Raises:

Type	Description
CliConfigurationError	If the word source is unreadable or contains no usable words.

Source code in hotstring\cli\runtime.py

def _load_words(namespace: argparse.Namespace) -> tuple[str, ...]:
    """Load, normalize, and de-duplicate source words.

    Args:
        namespace:
            Parsed command arguments.

    Returns:
        Ordered source-word tuple.

    Raises:
        CliConfigurationError:
            If the word source is unreadable or contains no usable words.
    """
    if namespace.word is not None:
        raw_words = namespace.word
        source_description = "--word"
    else:
        path = _require_input_file(namespace.words_file, label="word-list file")
        try:
            raw_words = path.read_text(encoding="utf-8").splitlines()
        except (OSError, UnicodeError) as exc:
            raise CliConfigurationError(f"Could not read word-list file {path}: {exc}") from exc
        source_description = str(path)

    words = _unique_nonempty_text(raw_words)
    if not words:
        raise CliConfigurationError(
            f"The word source {source_description} contains no non-empty words."
        )
    return words

_load_candidates

_load_candidates(
    namespace: Namespace,
) -> tuple[AutoCorrect2CandidateHotstring, ...]

Load and validate directly supplied candidate hotstrings.

Parameters:

Name	Type	Description	Default
namespace	Namespace	Parsed command arguments.	required

Returns:

Type	Description
tuple[AutoCorrect2CandidateHotstring, ...]	Candidate tuple in source order.

Raises:

Type	Description
CliConfigurationError	If candidate data is missing, malformed, or invalid.

Source code in hotstring\cli\runtime.py

def _load_candidates(
    namespace: argparse.Namespace,
) -> tuple[AutoCorrect2CandidateHotstring, ...]:
    """Load and validate directly supplied candidate hotstrings.

    Args:
        namespace:
            Parsed command arguments.

    Returns:
        Candidate tuple in source order.

    Raises:
        CliConfigurationError:
            If candidate data is missing, malformed, or invalid.
    """
    if namespace.candidate is not None:
        records: Sequence[object] = namespace.candidate
    else:
        path = _require_input_file(namespace.candidates_file, label="candidate JSON file")
        try:
            document = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
            raise CliConfigurationError(
                f"Could not read candidate JSON file {path}: {exc}"
            ) from exc
        if not isinstance(document, list):
            raise CliConfigurationError(
                f"Candidate JSON file {path} must contain a top-level array."
            )
        records = document

    if not records:
        raise CliConfigurationError("At least one candidate must be supplied.")

    candidates: list[AutoCorrect2CandidateHotstring] = []
    for index, record in enumerate(records, start=1):
        try:
            trigger, replacement, options = _candidate_fields(record)
            candidates.append(
                AutoCorrect2CandidateHotstring(
                    trigger=trigger,
                    replacement=replacement,
                    options_input=options,
                )
            )
        except (TypeError, ValueError) as exc:
            raise CliConfigurationError(f"Candidate {index} is invalid: {exc}") from exc
    return tuple(candidates)

_candidate_fields

_candidate_fields(record: object) -> tuple[str, str, str]

Extract the three candidate fields from CLI or JSON input.

Parameters:

Name	Type	Description	Default
record	object	Three-value CLI sequence or JSON object.	required

Returns:

Type	Description
tuple[str, str, str]	Semantic trigger, semantic replacement, and option declaration.

Raises:

Type	Description
TypeError	If the record shape or a field type is invalid.
ValueError	If a JSON object has missing or unexpected fields.

Source code in hotstring\cli\runtime.py

def _candidate_fields(record: object) -> tuple[str, str, str]:
    """Extract the three candidate fields from CLI or JSON input.

    Args:
        record:
            Three-value CLI sequence or JSON object.

    Returns:
        Semantic trigger, semantic replacement, and option declaration.

    Raises:
        TypeError:
            If the record shape or a field type is invalid.
        ValueError:
            If a JSON object has missing or unexpected fields.
    """
    if isinstance(record, Mapping):
        keys = set(record)
        missing = _CANDIDATE_FIELDS - keys
        unexpected = keys - _CANDIDATE_FIELDS
        if missing:
            raise ValueError(f"missing fields: {', '.join(sorted(missing))}")
        if unexpected:
            raise ValueError(f"unexpected fields: {', '.join(sorted(unexpected))}")
        trigger, replacement, options = (
            record["trigger"],
            record["replacement"],
            record["options"],
        )
    elif isinstance(record, Sequence) and not isinstance(record, (str, bytes)):
        if len(record) != 3:
            raise ValueError("expected exactly three values")
        trigger, replacement, options = record
    else:
        raise TypeError("expected an object with trigger, replacement, and options fields")

    if (
        not isinstance(trigger, str)
        or not isinstance(replacement, str)
        or not isinstance(options, str)
    ):
        raise TypeError("trigger, replacement, and options must all be strings")
    return trigger, replacement, options

_resolve_autocorrect2_project_dir

_resolve_autocorrect2_project_dir(
    *,
    direct_path: Path | None,
    explicit_env_file: Path | None,
) -> Path

Resolve the AutoCorrect2 project path by documented precedence.

Resolution stops at the first configured source:

1. --project-dir;
2. the process environment;
3. an explicitly selected --env-file;
4. the project-root .env file.

Lower-priority sources are not opened or validated after a higher-priority value is found.

Parameters:

Name	Type	Description	Default
direct_path	Path | None	Optional path supplied directly on the command line.	required
explicit_env_file	Path | None	Optional dotenv file selected on the command line.	required

Returns:

Type	Description
Path	Validated absolute AutoCorrect2 project path.

Raises:

Type	Description
CliConfigurationError	If no source supplies a usable path or the selected project is invalid.

Source code in hotstring\cli\runtime.py

def _resolve_autocorrect2_project_dir(
    *,
    direct_path: Path | None,
    explicit_env_file: Path | None,
) -> Path:
    """Resolve the AutoCorrect2 project path by documented precedence.

    Resolution stops at the first configured source:

    1. `--project-dir`;
    2. the process environment;
    3. an explicitly selected `--env-file`;
    4. the project-root `.env` file.

    Lower-priority sources are not opened or validated after a higher-priority
    value is found.

    Args:
        direct_path:
            Optional path supplied directly on the command line.
        explicit_env_file:
            Optional dotenv file selected on the command line.

    Returns:
        Validated absolute AutoCorrect2 project path.

    Raises:
        CliConfigurationError:
            If no source supplies a usable path or the selected project is
            invalid.
    """
    if direct_path is not None:
        return _validate_autocorrect2_project_dir(_absolute_path(direct_path))

    process_value = os.environ.get(AUTOCORRECT2_PROJECT_DIR_ENV)
    if process_value is not None:
        if not process_value.strip():
            raise CliConfigurationError(f"{AUTOCORRECT2_PROJECT_DIR_ENV} is set but empty.")
        return _validate_autocorrect2_project_dir(_absolute_path(Path(process_value.strip())))

    if explicit_env_file is not None:
        env_file = _require_input_file(explicit_env_file, label="dotenv file")
        return _project_dir_from_dotenv(env_file)

    if DEFAULT_ENV_FILE.is_file():
        return _project_dir_from_dotenv(DEFAULT_ENV_FILE)

    raise CliConfigurationError(
        "AutoCorrect2 project directory is not configured. Supply --project-dir, "
        f"set {AUTOCORRECT2_PROJECT_DIR_ENV}, pass --env-file, or create "
        f"{DEFAULT_ENV_FILE}."
    )

_project_dir_from_dotenv

_project_dir_from_dotenv(env_file: Path) -> Path

Read and validate the AutoCorrect2 path from one dotenv file.

Relative values are interpreted from the dotenv file's directory, making project-local configuration independent of the caller's working directory.

Parameters:

Name	Type	Description	Default
env_file	Path	Existing dotenv file to read.	required

Returns:

Type	Description
Path	Validated absolute AutoCorrect2 project path.

Raises:

Type	Description
CliConfigurationError	If the variable is absent, empty, or resolves to an invalid project directory.

Source code in hotstring\cli\runtime.py

def _project_dir_from_dotenv(env_file: Path) -> Path:
    """Read and validate the AutoCorrect2 path from one dotenv file.

    Relative values are interpreted from the dotenv file's directory, making
    project-local configuration independent of the caller's working directory.

    Args:
        env_file:
            Existing dotenv file to read.

    Returns:
        Validated absolute AutoCorrect2 project path.

    Raises:
        CliConfigurationError:
            If the variable is absent, empty, or resolves to an invalid
            project directory.
    """
    try:
        values = dotenv_values(env_file)
    except OSError as exc:
        raise CliConfigurationError(f"Could not read dotenv file {env_file}: {exc}") from exc

    raw_value = values.get(AUTOCORRECT2_PROJECT_DIR_ENV)
    if raw_value is None or not raw_value.strip():
        raise CliConfigurationError(
            f"Dotenv file {env_file} does not define a non-empty {AUTOCORRECT2_PROJECT_DIR_ENV}."
        )

    path = Path(raw_value.strip()).expanduser()
    if not path.is_absolute():
        path = env_file.parent / path
    return _validate_autocorrect2_project_dir(path.resolve(strict=False))

_validate_autocorrect2_project_dir

_validate_autocorrect2_project_dir(path: Path) -> Path

Validate the selected AutoCorrect2 project directory.

Parameters:

Name	Type	Description	Default
path	Path	Absolute candidate directory.	required

Returns:

Type	Description
Path	The validated path.

Raises:

Type	Description
CliConfigurationError	If the directory or a required hotstring source is missing.

Source code in hotstring\cli\runtime.py

def _validate_autocorrect2_project_dir(path: Path) -> Path:
    """Validate the selected AutoCorrect2 project directory.

    Args:
        path:
            Absolute candidate directory.

    Returns:
        The validated path.

    Raises:
        CliConfigurationError:
            If the directory or a required hotstring source is missing.
    """
    if not path.is_dir():
        raise CliConfigurationError(f"AutoCorrect2 project directory does not exist: {path}")

    missing = [
        relative_path
        for relative_path in REQUIRED_HOTSTRING_SOURCE_RELATIVE_PATHS
        if not (path / relative_path).is_file()
    ]
    if missing:
        rendered = ", ".join(str(relative_path) for relative_path in missing)
        raise CliConfigurationError(
            f"AutoCorrect2 project directory {path} is missing required files: {rendered}"
        )
    return path

_require_input_file

_require_input_file(path: Path, *, label: str) -> Path

Resolve a CLI path and require an existing regular file.

Parameters:

Name	Type	Description	Default
path	Path	Path supplied on the command line.	required
label	str	Human-readable input name used in an error message.	required

Returns:

Type	Description
Path	Absolute file path.

Raises:

Type	Description
CliConfigurationError	If the path is not an existing regular file.

Source code in hotstring\cli\runtime.py

def _require_input_file(path: Path, *, label: str) -> Path:
    """Resolve a CLI path and require an existing regular file.

    Args:
        path:
            Path supplied on the command line.
        label:
            Human-readable input name used in an error message.

    Returns:
        Absolute file path.

    Raises:
        CliConfigurationError:
            If the path is not an existing regular file.
    """
    absolute = _absolute_path(path)
    if not absolute.is_file():
        raise CliConfigurationError(f"The {label} does not exist: {absolute}")
    return absolute

_optional_cli_path

_optional_cli_path(path: Path | None) -> Path | None

Resolve an optional CLI path against the current directory.

Parameters:

Name	Type	Description	Default
path	Path | None	Optional path supplied on the command line.	required

Returns:

Type	Description
Path | None	Absolute path, or None when no path was supplied.

Source code in hotstring\cli\runtime.py

def _optional_cli_path(path: Path | None) -> Path | None:
    """Resolve an optional CLI path against the current directory.

    Args:
        path:
            Optional path supplied on the command line.

    Returns:
        Absolute path, or `None` when no path was supplied.
    """
    return None if path is None else _absolute_path(path)

_absolute_path

_absolute_path(path: Path) -> Path

Return an expanded absolute path without requiring it to exist.

Parameters:

Name	Type	Description	Default
path	Path	Path to normalize.	required

Returns:

Type	Description
Path	Expanded absolute path.

Source code in hotstring\cli\runtime.py

def _absolute_path(path: Path) -> Path:
    """Return an expanded absolute path without requiring it to exist.

    Args:
        path:
            Path to normalize.

    Returns:
        Expanded absolute path.
    """
    return path.expanduser().resolve(strict=False)

_unique_nonempty_text

_unique_nonempty_text(
    values: Iterable[str],
) -> tuple[str, ...]

Normalize text values and remove duplicates while preserving order.

Parameters:

Name	Type	Description	Default
values	Iterable[str]	Text values to normalize.	required

Returns:

Type	Description
tuple[str, ...]	Ordered tuple of unique, non-empty stripped values.

Source code in hotstring\cli\runtime.py

def _unique_nonempty_text(values: Iterable[str]) -> tuple[str, ...]:
    """Normalize text values and remove duplicates while preserving order.

    Args:
        values:
            Text values to normalize.

    Returns:
        Ordered tuple of unique, non-empty stripped values.
    """
    return tuple(dict.fromkeys(value.strip() for value in values if value.strip()))

Command execution

commands

Dispatch validated CLI commands to the public pipeline APIs.

The runtime layer resolves all user input before this module is called. Each handler therefore performs only workflow dispatch and concise terminal reporting; report generation and optional writes remain owned by hotstring.pipeline.

execute_command

execute_command(
    command: CommandConfig,
    *,
    logger: Logger | None = None,
    output: TextIO | None = None,
) -> int

Execute one validated command and print its summary.

Parameters:

Name	Type	Description	Default
command	CommandConfig	Runtime command created by create_command_config().	required
logger	Logger | None	Optional orchestration logger forwarded to typo-generation pipelines.	None
output	TextIO | None	Optional output stream. None uses the current sys.stdout.	None

Returns:

Type	Description
int	Zero after successful pipeline execution.

Source code in hotstring\cli\commands.py

def execute_command(
    command: CommandConfig,
    *,
    logger: logging.Logger | None = None,
    output: TextIO | None = None,
) -> int:
    """Execute one validated command and print its summary.

    Args:
        command:
            Runtime command created by
            [`create_command_config()`][hotstring.cli.runtime.create_command_config].
        logger:
            Optional orchestration logger forwarded to typo-generation
            pipelines.
        output:
            Optional output stream. `None` uses the current `sys.stdout`.

    Returns:
        Zero after successful pipeline execution.
    """
    stream = sys.stdout if output is None else output

    if isinstance(command, TypoGenerationCommand):
        generation = command.generation
        result = run_typo_generation(
            generation.words,
            generation.tasks,
            generation.config,
            n_workers=generation.n_workers,
            report_path=command.report_path,
            logger=logger,
        )
        _print_typo_summary(result, output=stream)
        _print_report_path(command.report_path, output=stream)
        return 0

    if isinstance(command, AutoCorrect2CheckCommand):
        autocorrect2 = command.autocorrect2
        result = run_autocorrect2_check(
            command.candidates,
            project_dir=autocorrect2.project_dir,
            report_path=command.report_path,
            write_accepted=autocorrect2.write_accepted,
        )
        _print_autocorrect2_summary(result, output=stream)
        _print_write_destination(
            write_accepted=autocorrect2.write_accepted,
            project_dir=autocorrect2.project_dir,
            output=stream,
        )
        _print_report_path(command.report_path, output=stream)
        return 0

    if isinstance(command, FullPipelineCommand):
        generation = command.generation
        autocorrect2 = command.autocorrect2
        result = run_full_pipeline(
            generation.words,
            generation.tasks,
            generation.config,
            n_workers=generation.n_workers,
            project_dir=autocorrect2.project_dir,
            report_path=command.report_path,
            write_accepted=autocorrect2.write_accepted,
            logger=logger,
        )
        _print_typo_summary(result.typo_generation, output=stream)
        _print_autocorrect2_summary(result.autocorrect2, output=stream)
        _print_write_destination(
            write_accepted=autocorrect2.write_accepted,
            project_dir=autocorrect2.project_dir,
            output=stream,
        )
        _print_report_path(command.report_path, output=stream)
        return 0

    assert_never(command)

_print_typo_summary

_print_typo_summary(
    result: TypoGenerationResult, *, output: TextIO
) -> None

Print the stable summary fields of a typo-generation result.

Parameters:

Name	Type	Description	Default
result	TypoGenerationResult	Typo-generation result returned by the pipeline.	required
output	TextIO	Destination stream.	required

Source code in hotstring\cli\commands.py

def _print_typo_summary(result: TypoGenerationResult, *, output: TextIO) -> None:
    """Print the stable summary fields of a typo-generation result.

    Args:
        result:
            Typo-generation result returned by the pipeline.
        output:
            Destination stream.
    """
    print("Typo generation complete.", file=output)
    print(f"  Source words: {result.source_word_count}", file=output)
    print(f"  Raw samples: {result.generated_sample_count}", file=output)
    print(f"  Candidates: {len(result.candidates)}", file=output)
    print(f"  Internal clashes: {len(result.clashes)}", file=output)

_print_autocorrect2_summary

_print_autocorrect2_summary(
    result: AutoCorrect2CheckResult, *, output: TextIO
) -> None

Print the stable summary fields of an AutoCorrect2 check result.

Parameters:

Name	Type	Description	Default
result	AutoCorrect2CheckResult	AutoCorrect2 result returned by the pipeline.	required
output	TextIO	Destination stream.	required

Source code in hotstring\cli\commands.py

def _print_autocorrect2_summary(
    result: AutoCorrect2CheckResult,
    *,
    output: TextIO,
) -> None:
    """Print the stable summary fields of an AutoCorrect2 check result.

    Args:
        result:
            AutoCorrect2 result returned by the pipeline.
        output:
            Destination stream.
    """
    print("AutoCorrect2 check complete.", file=output)
    print(f"  Candidates checked: {result.candidate_count}", file=output)
    print(f"  Accepted: {len(result.accepted)}", file=output)
    print(f"  Rejected: {len(result.rejected)}", file=output)

_print_write_destination

_print_write_destination(
    *,
    write_accepted: bool,
    project_dir: Path,
    output: TextIO,
) -> None

Print the generated-file destination when writing was enabled.

Parameters:

Name	Type	Description	Default
write_accepted	bool	Whether the selected command enabled writing.	required
project_dir	Path	AutoCorrect2 project directory.	required
output	TextIO	Destination stream.	required

Source code in hotstring\cli\commands.py

def _print_write_destination(
    *,
    write_accepted: bool,
    project_dir: Path,
    output: TextIO,
) -> None:
    """Print the generated-file destination when writing was enabled.

    Args:
        write_accepted:
            Whether the selected command enabled writing.
        project_dir:
            AutoCorrect2 project directory.
        output:
            Destination stream.
    """
    if write_accepted:
        print(
            f"  Generated include: {project_dir / GENERATED_HOTSTRINGS_RELATIVE_PATH}",
            file=output,
        )

_print_report_path

_print_report_path(
    report_path: Path | None, *, output: TextIO
) -> None

Print the report destination when one was requested.

Parameters:

Name	Type	Description	Default
report_path	Path | None	Optional report destination.	required
output	TextIO	Destination stream.	required

Source code in hotstring\cli\commands.py

def _print_report_path(report_path: Path | None, *, output: TextIO) -> None:
    """Print the report destination when one was requested.

    Args:
        report_path:
            Optional report destination.
        output:
            Destination stream.
    """
    if report_path is not None:
        print(f"  Report: {report_path}", file=output)

Reports

report

Build composable line-oriented reports for all supported pipelines.

Section builders deliberately omit run-level metadata such as dates or timestamps. This allows the full pipeline to reuse the typo-generation and AutoCorrect2 report bodies without duplicating document metadata.

create_typo_generation_report

create_typo_generation_report(
    result: TypoGenerationResult,
) -> list[str]

Create the typo-generation report body.

Parameters:

Name	Type	Description	Default
result	TypoGenerationResult	Aggregated typo-generation result.	required

Returns:

Type	Description
list[str]	Report body as individual text lines.

Source code in hotstring\report.py

def create_typo_generation_report(result: TypoGenerationResult) -> list[str]:
    """Create the typo-generation report body.

    Args:
        result:
            Aggregated typo-generation result.

    Returns:
        Report body as individual text lines.
    """
    horizontal_weight, vertical_weight = result.config.horizontal_vs_vertical
    lines = [
        "TYPO GENERATION",
        "-" * 80,
        f"Source words: {result.source_word_count}",
        f"Generation tasks: {len(result.tasks)}",
        f"Language: {result.config.language}",
        f"Use excluding set: {result.config.use_excluding_set}",
        f"Horizontal/vertical keyboard weights: {horizontal_weight}/{vertical_weight}",
        f"Successful raw samples: {result.generated_sample_count}",
        f"Unique noisy words: {result.unique_noisy_word_count}",
        f"Valid candidates: {len(result.candidates)}",
        f"Internal clashes: {len(result.clashes)}",
        "",
        "TASKS",
        "-" * 80,
    ]

    for index, task in enumerate(result.tasks, start=1):
        lines.extend(
            (
                f"Task {index}",
                f"  Distribution: {task.distribution.distribution}",
                f"  Typo rate: {task.typo_rate}",
                f"  Generation attempts per word: {task.generation_attempts_per_word}",
                f"  Minimum word length: {task.minimum_word_length}",
            )
        )

    lines.extend(("", "VALID TYPO CANDIDATES", "-" * 80))
    if result.candidates:
        lines.extend(f"{noisy!r} -> {target!r}" for noisy, target in result.candidates.items())
    else:
        lines.append("None")

    lines.extend(("", "INTERNAL CLASHES", "-" * 80))
    if result.clashes:
        for noisy_word, targets in result.clashes.items():
            lines.append(f"{noisy_word!r}")
            lines.extend(f"  -> {target!r}" for target in targets)
    else:
        lines.append("None")
    return lines

create_autocorrect2_report

create_autocorrect2_report(
    result: AutoCorrect2CheckResult,
) -> list[str]

Create the AutoCorrect2 conflict-check report body.

Candidate names are displayed with their semantic trigger, while an existing conflict's rendered source line uses its canonical AHK trigger.

Parameters:

Name	Type	Description	Default
result	AutoCorrect2CheckResult	AutoCorrect2 candidate-check result.	required

Returns:

Type	Description
list[str]	Report body as individual text lines.

Source code in hotstring\report.py

def create_autocorrect2_report(result: AutoCorrect2CheckResult) -> list[str]:
    """Create the AutoCorrect2 conflict-check report body.

    Candidate names are displayed with their semantic trigger, while an
    existing conflict's rendered source line uses its canonical AHK trigger.

    Args:
        result:
            AutoCorrect2 candidate-check result.

    Returns:
        Report body as individual text lines.
    """
    lines = [
        "AUTOCORRECT2 CONFLICT CHECK",
        "-" * 80,
        f"Candidates checked: {result.candidate_count}",
        f"Accepted candidates: {len(result.accepted)}",
        f"Rejected candidates: {len(result.rejected)}",
        "",
        "ACCEPTED",
        "-" * 80,
    ]

    if result.accepted:
        lines.extend(
            f"{candidate.semantic_trigger!r} -> {candidate.replacement!r}"
            for candidate in result.accepted
        )
    else:
        lines.append("None")

    lines.extend(("", "REJECTED", "-" * 80))
    if not result.rejected:
        lines.append("None")
        return lines

    for assessment in result.rejected:
        candidate = assessment.candidate
        lines.append(f"{candidate.semantic_trigger!r} -> {candidate.replacement!r}")
        for conflict in assessment.conflicts:
            lines.extend(
                (
                    f"  Existing: {conflict.existing.render()}",
                    f"  Source:   {conflict.existing.source}",
                    f"  Type:     {conflict.kind.value}",
                    f"  Reason:   {conflict.reason}",
                    "",
                )
            )
    return lines

create_full_pipeline_report

create_full_pipeline_report(
    typo_result: TypoGenerationResult,
    autocorrect2_result: AutoCorrect2CheckResult,
) -> list[str]

Create a full report by composing both stage-specific report bodies.

Source code in hotstring\report.py

def create_full_pipeline_report(
    typo_result: TypoGenerationResult,
    autocorrect2_result: AutoCorrect2CheckResult,
) -> list[str]:
    """Create a full report by composing both stage-specific report bodies."""
    lines = create_typo_generation_report(typo_result)
    lines.extend(("", "=" * 80, ""))
    lines.extend(create_autocorrect2_report(autocorrect2_result))
    lines.extend(
        (
            "",
            "FINAL SUMMARY",
            "-" * 80,
            f"Internal typo clashes removed: {len(typo_result.clashes)}",
            f"AutoCorrect2 conflicts removed: {len(autocorrect2_result.rejected)}",
            f"Final accepted hotstrings: {len(autocorrect2_result.accepted)}",
        )
    )
    return lines

build_report_document

build_report_document(
    title: str, body_lines: Sequence[str]
) -> list[str]

Wrap a report body with run-level document framing.

Source code in hotstring\report.py

def build_report_document(title: str, body_lines: Sequence[str]) -> list[str]:
    """Wrap a report body with run-level document framing."""
    if not title:
        raise ValueError("Report title cannot be empty.")
    return [title, "=" * 80, "", *body_lines]

File I/O

file_io

Provide small generic text-file I/O helpers.

read_text

read_text(path: Path, *, encoding: str = 'utf-8') -> str

Read a text file.

Parameters:

Name	Type	Description	Default
path	Path	File to read.	required
encoding	str	Text encoding.	'utf-8'

Returns:

Type	Description
str	File contents.

Raises:

Type	Description
OSError	If the file cannot be read.

Source code in hotstring\file_io.py

def read_text(path: Path, *, encoding: str = "utf-8") -> str:
    """Read a text file.

    Args:
        path:
            File to read.
        encoding:
            Text encoding.

    Returns:
        File contents.

    Raises:
        OSError:
            If the file cannot be read.
    """
    return path.read_text(encoding=encoding)

write_text

write_text(
    path: Path,
    text: str,
    *,
    append: bool = False,
    encoding: str = "utf-8",
    create_parents: bool = True,
) -> None

Write or append text to a file.

Parameters:

Name	Type	Description	Default
path	Path	Destination file.	required
text	str	Text to write.	required
append	bool	Append instead of replacing the current contents.	False
encoding	str	Text encoding.	'utf-8'
create_parents	bool	Create missing parent directories before writing.	True

Raises:

Type	Description
OSError	If the destination cannot be written.

Source code in hotstring\file_io.py

def write_text(
    path: Path,
    text: str,
    *,
    append: bool = False,
    encoding: str = "utf-8",
    create_parents: bool = True,
) -> None:
    """Write or append text to a file.

    Args:
        path:
            Destination file.
        text:
            Text to write.
        append:
            Append instead of replacing the current contents.
        encoding:
            Text encoding.
        create_parents:
            Create missing parent directories before writing.

    Raises:
        OSError:
            If the destination cannot be written.
    """
    if create_parents:
        path.parent.mkdir(parents=True, exist_ok=True)

    mode = "a" if append else "w"
    with path.open(mode, encoding=encoding, newline="") as stream:
        stream.write(text)

Constants

constants

TOP_PACKAGE_DIR module-attribute

TOP_PACKAGE_DIR: Final[Path] = Path(__file__).parent

Top-level package directory of this source project.

PROJECT_ROOT module-attribute

PROJECT_ROOT: Final[Path] = TOP_PACKAGE_DIR.parent

Root directory of this source project.

Typo generation

Typo generation API

hotstring.typo_generation contains typo-generation models, generation logic, execution strategies, and aggregation helpers.

Typo-generation models

models

Define task, configuration, and result models for typo generation.

REPLACE_ONLY_TYPO_DISTRIBUTION module-attribute

REPLACE_ONLY_TYPO_DISTRIBUTION = TypoWeightDistribution(
    replace=1.0
)

Distribution that selects only replacement errors.

TRANSPOSE_ONLY_TYPO_DISTRIBUTION module-attribute

TRANSPOSE_ONLY_TYPO_DISTRIBUTION = TypoWeightDistribution(
    transpose=1.0
)

Distribution that selects only transposition errors.

DELETE_ONLY_TYPO_DISTRIBUTION module-attribute

DELETE_ONLY_TYPO_DISTRIBUTION = TypoWeightDistribution(
    delete=1.0
)

Distribution that selects only deletion errors.

INSERT_ONLY_TYPO_DISTRIBUTION module-attribute

INSERT_ONLY_TYPO_DISTRIBUTION = TypoWeightDistribution(
    insert=1.0
)

Distribution that selects only insertion errors.

DEFAULT_SINGLE_ERROR_TYPO_DISTRIBUTIONS module-attribute

DEFAULT_SINGLE_ERROR_TYPO_DISTRIBUTIONS: tuple[
    TypoWeightDistribution, ...
] = (
    REPLACE_ONLY_TYPO_DISTRIBUTION,
    TRANSPOSE_ONLY_TYPO_DISTRIBUTION,
    DELETE_ONLY_TYPO_DISTRIBUTION,
    INSERT_ONLY_TYPO_DISTRIBUTION,
)

Default single-error distributions, one for each supported operation type.

DEFAULT_MIXED_ERROR_TYPO_DISTRIBUTION module-attribute

DEFAULT_MIXED_ERROR_TYPO_DISTRIBUTION = (
    TypoWeightDistribution(
        replace=0.28,
        transpose=0.28,
        delete=0.28,
        insert=0.15,
    )
)

Mixed distribution mirroring MULTYPO's built-in operation weights.

TypoWeightDistribution dataclass

Represent the weight mapping of the MULTYPO typo operations.

Values are non-negative weights. MULTYPO normalizes the supplied mapping, so they do not need to sum to one.

Attributes:

Name	Type	Description
replace	float	Replacement-operation weight.
transpose	float	Transposition-operation weight.
delete	float	Deletion-operation weight.
insert	float	Insertion-operation weight.

Source code in hotstring\typo_generation\models.py

@dataclass(frozen=True, slots=True)
class TypoWeightDistribution:
    """Represent the weight mapping of the MULTYPO typo operations.

    Values are non-negative weights. MULTYPO normalizes the supplied mapping,
    so they do not need to sum to one.

    Attributes:
        replace:
            Replacement-operation weight.
        transpose:
            Transposition-operation weight.
        delete:
            Deletion-operation weight.
        insert:
            Insertion-operation weight.
    """

    replace: float = 0.0
    transpose: float = 0.0
    delete: float = 0.0
    insert: float = 0.0

    def __post_init__(self) -> None:
        """Validate typo-distribution weights.

        Raises:
            TypeError:
                If a weight is not a real number or is a boolean.
            ValueError:
                If a weight is negative or all weights are zero.
        """
        values = (self.replace, self.transpose, self.delete, self.insert)
        for value in values:
            if isinstance(value, bool) or not isinstance(value, Real):
                raise TypeError("Typo distribution weights must be real numbers.")
            if value < 0:
                raise ValueError("Typo distribution weights cannot be negative.")

        if not any(value > 0 for value in values):
            raise ValueError("At least one typo distribution weight must be positive.")

    @property
    def distribution(self) -> dict[str, float]:
        """Return the mapping expected by `MultiTypoGenerator`.

        Returns:
            Typo-operation weight mapping.
        """
        return {
            "replace": float(self.replace),
            "transpose": float(self.transpose),
            "delete": float(self.delete),
            "insert": float(self.insert),
        }

distribution property

distribution: dict[str, float]

Return the mapping expected by MultiTypoGenerator.

Returns:

Type	Description
dict[str, float]	Typo-operation weight mapping.

__post_init__

__post_init__() -> None

Validate typo-distribution weights.

Raises:

Type	Description
TypeError	If a weight is not a real number or is a boolean.
ValueError	If a weight is negative or all weights are zero.

Source code in hotstring\typo_generation\models.py

def __post_init__(self) -> None:
    """Validate typo-distribution weights.

    Raises:
        TypeError:
            If a weight is not a real number or is a boolean.
        ValueError:
            If a weight is negative or all weights are zero.
    """
    values = (self.replace, self.transpose, self.delete, self.insert)
    for value in values:
        if isinstance(value, bool) or not isinstance(value, Real):
            raise TypeError("Typo distribution weights must be real numbers.")
        if value < 0:
            raise ValueError("Typo distribution weights cannot be negative.")

    if not any(value > 0 for value in values):
        raise ValueError("At least one typo distribution weight must be positive.")

TypoGenerationTask dataclass

Describe one independently executable typo-generation task.

Attributes:

Name	Type	Description
distribution	TypoWeightDistribution	Typo-operation distribution used by the task.
typo_rate	float	MULTYPO typo rate passed directly to insert_typos.
generation_attempts_per_word	int	Number of independent samples requested for each eligible word.
minimum_word_length	int	Minimum source-word length eligible for this task.

Source code in hotstring\typo_generation\models.py

@dataclass(frozen=True, slots=True, kw_only=True)
class TypoGenerationTask:
    """Describe one independently executable typo-generation task.

    Attributes:
        distribution:
            Typo-operation distribution used by the task.
        typo_rate:
            MULTYPO typo rate passed directly to `insert_typos`.
        generation_attempts_per_word:
            Number of independent samples requested for each eligible word.
        minimum_word_length:
            Minimum source-word length eligible for this task.
    """

    distribution: TypoWeightDistribution
    typo_rate: float
    generation_attempts_per_word: int
    minimum_word_length: int

    def __post_init__(self) -> None:
        """Validate the task definition.

        Raises:
            TypeError:
                If a field has an invalid type.
            ValueError:
                If the typo rate, attempt count, or minimum length is invalid.
        """
        if not isinstance(self.distribution, TypoWeightDistribution):
            raise TypeError(
                "distribution must be a TypoWeightDistribution instance, "
                f"not {type(self.distribution).__name__}."
            )
        if isinstance(self.typo_rate, bool) or not isinstance(self.typo_rate, Real):
            raise TypeError("typo_rate must be a real number.")
        if self.typo_rate <= 0:
            raise ValueError("typo_rate must be greater than zero.")
        if isinstance(self.generation_attempts_per_word, bool) or not isinstance(
            self.generation_attempts_per_word, int
        ):
            raise TypeError("generation_attempts_per_word must be an integer.")
        if self.generation_attempts_per_word <= 0:
            raise ValueError("generation_attempts_per_word must be greater than zero.")
        if isinstance(self.minimum_word_length, bool) or not isinstance(
            self.minimum_word_length, int
        ):
            raise TypeError("minimum_word_length must be an integer.")
        if self.minimum_word_length < 2:
            raise ValueError("minimum_word_length must be at least 2.")

__post_init__

__post_init__() -> None

Validate the task definition.

Raises:

Type	Description
TypeError	If a field has an invalid type.
ValueError	If the typo rate, attempt count, or minimum length is invalid.

Source code in hotstring\typo_generation\models.py

def __post_init__(self) -> None:
    """Validate the task definition.

    Raises:
        TypeError:
            If a field has an invalid type.
        ValueError:
            If the typo rate, attempt count, or minimum length is invalid.
    """
    if not isinstance(self.distribution, TypoWeightDistribution):
        raise TypeError(
            "distribution must be a TypoWeightDistribution instance, "
            f"not {type(self.distribution).__name__}."
        )
    if isinstance(self.typo_rate, bool) or not isinstance(self.typo_rate, Real):
        raise TypeError("typo_rate must be a real number.")
    if self.typo_rate <= 0:
        raise ValueError("typo_rate must be greater than zero.")
    if isinstance(self.generation_attempts_per_word, bool) or not isinstance(
        self.generation_attempts_per_word, int
    ):
        raise TypeError("generation_attempts_per_word must be an integer.")
    if self.generation_attempts_per_word <= 0:
        raise ValueError("generation_attempts_per_word must be greater than zero.")
    if isinstance(self.minimum_word_length, bool) or not isinstance(
        self.minimum_word_length, int
    ):
        raise TypeError("minimum_word_length must be an integer.")
    if self.minimum_word_length < 2:
        raise ValueError("minimum_word_length must be at least 2.")

TypoGenerationConfig dataclass

Configure generator settings shared by every task in one run.

Attributes:

Name	Type	Description
language	str	MULTYPO language identifier.
use_excluding_set	bool	Whether MULTYPO's language excluding set is enabled.
horizontal_vs_vertical	tuple[float, float]	Relative horizontal and vertical keyboard-neighbor weights.

Source code in hotstring\typo_generation\models.py

@dataclass(frozen=True, slots=True, kw_only=True)
class TypoGenerationConfig:
    """Configure generator settings shared by every task in one run.

    Attributes:
        language:
            MULTYPO language identifier.
        use_excluding_set:
            Whether MULTYPO's language excluding set is enabled.
        horizontal_vs_vertical:
            Relative horizontal and vertical keyboard-neighbor weights.
    """

    language: str = "english"
    use_excluding_set: bool = True
    horizontal_vs_vertical: tuple[float, float] = (9.0, 1.0)

    def __post_init__(self) -> None:
        """Validate shared typo-generation configuration."""
        if not isinstance(self.language, str):
            raise TypeError("language must be a string.")
        if not self.language:
            raise ValueError("language cannot be empty.")
        if not isinstance(self.use_excluding_set, bool):
            raise TypeError("use_excluding_set must be a boolean.")
        if not isinstance(self.horizontal_vs_vertical, tuple):
            raise TypeError("horizontal_vs_vertical must be a tuple.")
        if len(self.horizontal_vs_vertical) != 2:
            raise ValueError("horizontal_vs_vertical must contain exactly two weights.")
        for weight in self.horizontal_vs_vertical:
            if isinstance(weight, bool) or not isinstance(weight, Real):
                raise TypeError("Keyboard-neighbor weights must be real numbers.")
            if weight <= 0:
                raise ValueError("Keyboard-neighbor weights must be positive.")

__post_init__

__post_init__() -> None

Validate shared typo-generation configuration.

Source code in hotstring\typo_generation\models.py

def __post_init__(self) -> None:
    """Validate shared typo-generation configuration."""
    if not isinstance(self.language, str):
        raise TypeError("language must be a string.")
    if not self.language:
        raise ValueError("language cannot be empty.")
    if not isinstance(self.use_excluding_set, bool):
        raise TypeError("use_excluding_set must be a boolean.")
    if not isinstance(self.horizontal_vs_vertical, tuple):
        raise TypeError("horizontal_vs_vertical must be a tuple.")
    if len(self.horizontal_vs_vertical) != 2:
        raise ValueError("horizontal_vs_vertical must contain exactly two weights.")
    for weight in self.horizontal_vs_vertical:
        if isinstance(weight, bool) or not isinstance(weight, Real):
            raise TypeError("Keyboard-neighbor weights must be real numbers.")
        if weight <= 0:
            raise ValueError("Keyboard-neighbor weights must be positive.")

RawTypoSample dataclass

Represent one successful noisy-word sample.

Attributes:

Name	Type	Description
noisy_word	str	Generated typo candidate.
target_word	str	Correct source word the typo should map back to.

Source code in hotstring\typo_generation\models.py

@dataclass(frozen=True, slots=True)
class RawTypoSample:
    """Represent one successful noisy-word sample.

    Attributes:
        noisy_word:
            Generated typo candidate.
        target_word:
            Correct source word the typo should map back to.
    """

    noisy_word: str
    target_word: str

TypoGenerationResult dataclass

Represent aggregated output of the typo-generation stage.

Attributes:

Name	Type	Description
config	TypoGenerationConfig	Shared generator configuration used for generation.
tasks	tuple[TypoGenerationTask, ...]	Ordered generation tasks that were executed.
source_word_count	int	Number of source words supplied before per-task length filtering.
generated_sample_count	int	Number of successful raw samples before deduplication.
candidates	dict[str, str]	Unique noisy-word to target-word mappings.
clashes	dict[str, tuple[str, ...]]	Noisy words that mapped to more than one target word.

Source code in hotstring\typo_generation\models.py

@dataclass(frozen=True, slots=True)
class TypoGenerationResult:
    """Represent aggregated output of the typo-generation stage.

    Attributes:
        config:
            Shared generator configuration used for generation.
        tasks:
            Ordered generation tasks that were executed.
        source_word_count:
            Number of source words supplied before per-task length filtering.
        generated_sample_count:
            Number of successful raw samples before deduplication.
        candidates:
            Unique noisy-word to target-word mappings.
        clashes:
            Noisy words that mapped to more than one target word.
    """

    config: TypoGenerationConfig
    tasks: tuple[TypoGenerationTask, ...]
    source_word_count: int
    generated_sample_count: int
    candidates: dict[str, str]
    clashes: dict[str, tuple[str, ...]]

    @property
    def unique_noisy_word_count(self) -> int:
        """Return the number of unique noisy forms after aggregation.

        Returns:
            Candidate count plus internal clash count.
        """
        return len(self.candidates) + len(self.clashes)

unique_noisy_word_count property

unique_noisy_word_count: int

Return the number of unique noisy forms after aggregation.

Returns:

Type	Description
int	Candidate count plus internal clash count.

create_default_typo_generation_tasks

create_default_typo_generation_tasks(
    *,
    single_error_attempts_per_word: int,
    multi_error_attempts_per_word: int,
    multi_error_minimum_word_length: int,
) -> tuple[TypoGenerationTask, ...]

Create the project's default single- and two-error task set.

Parameters:

Name	Type	Description	Default
single_error_attempts_per_word	int	Sampling attempts per eligible word for each forced single-error task.	required
multi_error_attempts_per_word	int	Sampling attempts per eligible word for the mixed two-error task.	required
multi_error_minimum_word_length	int	Minimum word length for the mixed two-error task.	required

Returns:

Type	Description
tuple[TypoGenerationTask, ...]	Ordered default task tuple.

Source code in hotstring\typo_generation\models.py

def create_default_typo_generation_tasks(
    *,
    single_error_attempts_per_word: int,
    multi_error_attempts_per_word: int,
    multi_error_minimum_word_length: int,
) -> tuple[TypoGenerationTask, ...]:
    """Create the project's default single- and two-error task set.

    Args:
        single_error_attempts_per_word:
            Sampling attempts per eligible word for each forced single-error task.
        multi_error_attempts_per_word:
            Sampling attempts per eligible word for the mixed two-error task.
        multi_error_minimum_word_length:
            Minimum word length for the mixed two-error task.

    Returns:
        Ordered default task tuple.
    """
    single_error_tasks = tuple(
        TypoGenerationTask(
            distribution=distribution,
            typo_rate=1.0,
            generation_attempts_per_word=single_error_attempts_per_word,
            minimum_word_length=2,
        )
        for distribution in DEFAULT_SINGLE_ERROR_TYPO_DISTRIBUTIONS
    )
    multi_error_task = TypoGenerationTask(
        distribution=DEFAULT_MIXED_ERROR_TYPO_DISTRIBUTION,
        typo_rate=2.0,
        generation_attempts_per_word=multi_error_attempts_per_word,
        minimum_word_length=multi_error_minimum_word_length,
    )
    return (*single_error_tasks, multi_error_task)

Typo generation

generation

Perform low-level typo sampling for one generation task with MULTYPO.

generate_typos_for_task

generate_typos_for_task(
    word_list: Sequence[str],
    task: TypoGenerationTask,
    config: TypoGenerationConfig,
    *,
    logger: Logger | None = None,
) -> list[RawTypoSample]

Generate noisy samples for all words eligible for one task.

Parameters:

Name	Type	Description	Default
word_list	Sequence[str]	Shared source words to consider.	required
task	TypoGenerationTask	Task-specific distribution and sampling settings.	required
config	TypoGenerationConfig	Shared MULTYPO generator configuration.	required
logger	Logger | None	Optional logger for progress and diagnostics.	None

Returns:

Type	Description
list[RawTypoSample]	Successful raw typo samples.

Source code in hotstring\typo_generation\generation.py

def generate_typos_for_task(
    word_list: Sequence[str],
    task: TypoGenerationTask,
    config: TypoGenerationConfig,
    *,
    logger: logging.Logger | None = None,
) -> list[RawTypoSample]:
    """Generate noisy samples for all words eligible for one task.

    Args:
        word_list:
            Shared source words to consider.
        task:
            Task-specific distribution and sampling settings.
        config:
            Shared MULTYPO generator configuration.
        logger:
            Optional logger for progress and diagnostics.

    Returns:
        Successful raw typo samples.
    """
    generator = _create_generator(task, config)
    normalized_words = tuple(_normalize_source_word(word) for word in word_list)
    eligible_words = tuple(
        word for word in normalized_words if len(word) >= task.minimum_word_length
    )

    if logger is not None:
        logger.info(
            "Generating typo samples for %d/%d eligible words with typo_rate=%s, "
            "attempts_per_word=%d, distribution=%s",
            len(eligible_words),
            len(normalized_words),
            task.typo_rate,
            task.generation_attempts_per_word,
            task.distribution.distribution,
        )

    generated: list[RawTypoSample] = []
    for target_word in eligible_words:
        for _ in range(task.generation_attempts_per_word):
            noisy_word = generator.insert_typos(
                target_word,
                typo_rate=float(task.typo_rate),
            ).lower()
            if noisy_word == target_word:
                continue
            generated.append(RawTypoSample(noisy_word=noisy_word, target_word=target_word))

    return generated

_create_generator

_create_generator(
    task: TypoGenerationTask, config: TypoGenerationConfig
) -> MultiTypoGenerator

Create a configured MULTYPO generator for one task.

Source code in hotstring\typo_generation\generation.py

def _create_generator(
    task: TypoGenerationTask,
    config: TypoGenerationConfig,
) -> MultiTypoGenerator:
    """Create a configured MULTYPO generator for one task."""
    return MultiTypoGenerator(
        language=config.language,
        use_excluding_set=config.use_excluding_set,
        typo_distribution=task.distribution.distribution,
        horizontal_vs_vertical=config.horizontal_vs_vertical,
    )

_normalize_source_word

_normalize_source_word(source_word: str) -> str

Validate and normalize one source word to lowercase.

Source code in hotstring\typo_generation\generation.py

def _normalize_source_word(source_word: str) -> str:
    """Validate and normalize one source word to lowercase."""
    if not isinstance(source_word, str):
        raise TypeError(f"Source words must be strings, not {type(source_word).__name__}.")
    if not source_word:
        raise ValueError("Source words cannot be empty.")
    if any(character.isspace() for character in source_word):
        raise ValueError(
            f"Source word must contain exactly one word and no whitespace: {source_word!r}"
        )
    return source_word.lower()

Typo execution

execution

Execute typo-generation tasks serially or with a spawned process pool.

execute_typo_generation_tasks

execute_typo_generation_tasks(
    word_list: Sequence[str],
    tasks: Sequence[TypoGenerationTask],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None = None,
    logger: Logger | None = None,
) -> list[RawTypoSample]

Execute all typo-generation tasks and collect their raw samples.

Parameters:

Name	Type	Description	Default
word_list	Sequence[str]	Shared source words considered by every task.	required
tasks	Sequence[TypoGenerationTask]	Ordered typo-generation tasks to execute.	required
config	TypoGenerationConfig	Shared generator configuration.	required
n_workers	int | None	Requested process-pool size, or None for the executor default.	None
logger	Logger | None	Optional orchestration logger.	None

Returns:

Type	Description
list[RawTypoSample]	Concatenated raw samples in input task order.

Raises:

Type	Description
TypeError	If n_workers or a task has an invalid type.
ValueError	If no tasks are supplied or n_workers is not positive.
RuntimeError	If a parallel generation task fails.

Source code in hotstring\typo_generation\execution.py

def execute_typo_generation_tasks(
    word_list: Sequence[str],
    tasks: Sequence[TypoGenerationTask],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None = None,
    logger: logging.Logger | None = None,
) -> list[RawTypoSample]:
    """Execute all typo-generation tasks and collect their raw samples.

    Args:
        word_list:
            Shared source words considered by every task.
        tasks:
            Ordered typo-generation tasks to execute.
        config:
            Shared generator configuration.
        n_workers:
            Requested process-pool size, or `None` for the executor default.
        logger:
            Optional orchestration logger.

    Returns:
        Concatenated raw samples in input task order.

    Raises:
        TypeError:
            If `n_workers` or a task has an invalid type.
        ValueError:
            If no tasks are supplied or `n_workers` is not positive.
        RuntimeError:
            If a parallel generation task fails.
    """
    _validate_worker_count(n_workers)
    task_tuple = _normalize_tasks(tasks)
    words = list(word_list)

    if n_workers is None:
        effective_n_workers = None
    else:
        available_cpus = (
            os.process_cpu_count() if hasattr(os, "process_cpu_count") else os.cpu_count()
        ) or 1
        max_allowed_workers = available_cpus
        if sys.platform == "win32":
            max_allowed_workers = min(max_allowed_workers, _MAX_WINDOWS_PROCESS_POOL_WORKERS)
        effective_n_workers = min(n_workers, len(task_tuple), max_allowed_workers)

    if len(task_tuple) == 1 or effective_n_workers == 1:
        return _execute_tasks_serial(words, task_tuple, config, logger=logger)

    return _execute_tasks_parallel(
        words,
        task_tuple,
        config,
        n_workers=effective_n_workers,
        logger=logger,
    )

_execute_tasks_serial

_execute_tasks_serial(
    word_list: list[str],
    tasks: tuple[TypoGenerationTask, ...],
    config: TypoGenerationConfig,
    *,
    logger: Logger | None,
) -> list[RawTypoSample]

Execute every task in the current process.

Source code in hotstring\typo_generation\execution.py

def _execute_tasks_serial(
    word_list: list[str],
    tasks: tuple[TypoGenerationTask, ...],
    config: TypoGenerationConfig,
    *,
    logger: logging.Logger | None,
) -> list[RawTypoSample]:
    """Execute every task in the current process."""
    samples: list[RawTypoSample] = []
    for task in tasks:
        samples.extend(generate_typos_for_task(word_list, task, config, logger=logger))
    return samples

_execute_tasks_parallel

_execute_tasks_parallel(
    word_list: list[str],
    tasks: tuple[TypoGenerationTask, ...],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None,
    logger: Logger | None,
) -> list[RawTypoSample]

Execute tasks with a spawned process pool.

Source code in hotstring\typo_generation\execution.py

def _execute_tasks_parallel(
    word_list: list[str],
    tasks: tuple[TypoGenerationTask, ...],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None,
    logger: logging.Logger | None,
) -> list[RawTypoSample]:
    """Execute tasks with a spawned process pool."""
    mp_context = mp.get_context("spawn")
    root_logger = logging.getLogger()
    root_handlers = tuple(
        handler for handler in root_logger.handlers if not isinstance(handler, logging.NullHandler)
    )
    manager_logger_name = logger.name if logger is not None else "typo_generation"

    if not root_handlers:
        return _multi_worker_typo_generation(
            word_list,
            tasks,
            config,
            n_workers=n_workers,
            mp_context=mp_context,
            proxy_queue=None,
            root_level=root_logger.level,
            manager_logger_name=manager_logger_name,
        )

    with mp_context.Manager() as manager:
        proxy_queue = manager.Queue(-1)
        listener = QueueListener(proxy_queue, *root_handlers, respect_handler_level=True)
        listener.start()
        try:
            return _multi_worker_typo_generation(
                word_list,
                tasks,
                config,
                n_workers=n_workers,
                mp_context=mp_context,
                proxy_queue=proxy_queue,
                root_level=root_logger.level,
                manager_logger_name=manager_logger_name,
            )
        finally:
            listener.stop()

_multi_worker_typo_generation

_multi_worker_typo_generation(
    word_list: list[str],
    tasks: tuple[TypoGenerationTask, ...],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None,
    mp_context: BaseContext,
    proxy_queue: Any | None,
    root_level: int,
    manager_logger_name: str,
) -> list[RawTypoSample]

Submit every generation task to a process pool and collect results.

Source code in hotstring\typo_generation\execution.py

def _multi_worker_typo_generation(
    word_list: list[str],
    tasks: tuple[TypoGenerationTask, ...],
    config: TypoGenerationConfig,
    *,
    n_workers: int | None,
    mp_context: BaseContext,
    proxy_queue: Any | None,
    root_level: int,
    manager_logger_name: str,
) -> list[RawTypoSample]:
    """Submit every generation task to a process pool and collect results."""
    results_by_index: dict[int, list[RawTypoSample]] = {}

    with ProcessPoolExecutor(
        max_workers=n_workers,
        mp_context=mp_context,
        initializer=_initialize_worker,
        initargs=(root_level, proxy_queue, manager_logger_name),
    ) as executor:
        future_to_task: dict[Future[list[RawTypoSample]], tuple[int, TypoGenerationTask]] = {
            executor.submit(_generate_task_in_worker, word_list, task, config): (index, task)
            for index, task in enumerate(tasks)
        }

        for future in as_completed(future_to_task):
            index, task = future_to_task[future]
            try:
                results_by_index[index] = future.result()
            except Exception as error:
                raise RuntimeError(
                    f"Failed to execute typo-generation task at index {index}: {task!r}"
                ) from error

    return [sample for index in range(len(tasks)) for sample in results_by_index[index]]

_worker_logger_initialization

_worker_logger_initialization(
    root_level: int,
    proxy_queue: Any | None,
    manager_logger_name: str | None,
) -> None

Initialize logging inside one spawned worker process.

Source code in hotstring\typo_generation\execution.py

def _worker_logger_initialization(
    root_level: int,
    proxy_queue: Any | None,
    manager_logger_name: str | None,
) -> None:
    """Initialize logging inside one spawned worker process."""
    global _WORKER_LOGGER

    root_logger = logging.getLogger()
    root_logger.handlers.clear()
    root_logger.setLevel(root_level)
    if proxy_queue is not None:
        root_logger.addHandler(QueueHandler(proxy_queue))

    base_name = f"worker_{os.getpid()}"
    worker_name = base_name if not manager_logger_name else f"{manager_logger_name}.{base_name}"
    _WORKER_LOGGER = logging.getLogger(worker_name)

_initialize_worker

_initialize_worker(
    root_level: int,
    proxy_queue: Any | None = None,
    manager_logger_name: str | None = None,
) -> None

Initialize process-global state inside a spawned worker process.

Source code in hotstring\typo_generation\execution.py

def _initialize_worker(
    root_level: int,
    proxy_queue: Any | None = None,
    manager_logger_name: str | None = None,
) -> None:
    """Initialize process-global state inside a spawned worker process."""
    _worker_logger_initialization(root_level, proxy_queue, manager_logger_name)

_generate_task_in_worker

_generate_task_in_worker(
    word_list: list[str],
    task: TypoGenerationTask,
    config: TypoGenerationConfig,
) -> list[RawTypoSample]

Execute one task inside a process-pool worker.

Source code in hotstring\typo_generation\execution.py

def _generate_task_in_worker(
    word_list: list[str],
    task: TypoGenerationTask,
    config: TypoGenerationConfig,
) -> list[RawTypoSample]:
    """Execute one task inside a process-pool worker."""
    return generate_typos_for_task(word_list, task, config, logger=_WORKER_LOGGER)

_normalize_tasks

_normalize_tasks(
    tasks: Sequence[TypoGenerationTask],
) -> tuple[TypoGenerationTask, ...]

Validate and freeze the task sequence for one execution run.

Source code in hotstring\typo_generation\execution.py

def _normalize_tasks(tasks: Sequence[TypoGenerationTask]) -> tuple[TypoGenerationTask, ...]:
    """Validate and freeze the task sequence for one execution run."""
    task_tuple = tuple(tasks)
    if not task_tuple:
        raise ValueError("At least one typo-generation task must be provided.")
    for index, task in enumerate(task_tuple):
        if not isinstance(task, TypoGenerationTask):
            raise TypeError(
                f"tasks[{index}] must be a TypoGenerationTask, not {type(task).__name__}."
            )
    return task_tuple

_validate_worker_count

_validate_worker_count(n_workers: int | None) -> None

Validate an optional process-pool worker count.

Source code in hotstring\typo_generation\execution.py

def _validate_worker_count(n_workers: int | None) -> None:
    """Validate an optional process-pool worker count."""
    if n_workers is None:
        return
    if isinstance(n_workers, bool) or not isinstance(n_workers, int):
        raise TypeError("n_workers must be an integer or None.")
    if n_workers <= 0:
        raise ValueError("n_workers must be greater than zero.")

Typo aggregation

aggregation

Aggregate raw typo samples and remove internally ambiguous candidates.

aggregate_typo_samples

aggregate_typo_samples(
    samples: Sequence[RawTypoSample],
    *,
    config: TypoGenerationConfig,
    tasks: Sequence[TypoGenerationTask],
    source_word_count: int,
) -> TypoGenerationResult

Deduplicate raw samples and separate valid candidates from clashes.

Source code in hotstring\typo_generation\aggregation.py

def aggregate_typo_samples(
    samples: Sequence[RawTypoSample],
    *,
    config: TypoGenerationConfig,
    tasks: Sequence[TypoGenerationTask],
    source_word_count: int,
) -> TypoGenerationResult:
    """Deduplicate raw samples and separate valid candidates from clashes."""
    if isinstance(source_word_count, bool) or not isinstance(source_word_count, int):
        raise TypeError("source_word_count must be an integer.")
    if source_word_count < 0:
        raise ValueError("source_word_count cannot be negative.")

    task_tuple = tuple(tasks)
    if not task_tuple:
        raise ValueError("At least one typo-generation task must be provided.")

    targets_by_noisy: dict[str, set[str]] = defaultdict(set)
    for sample in samples:
        targets_by_noisy[sample.noisy_word].add(sample.target_word)

    candidates: dict[str, str] = {}
    clashes: dict[str, tuple[str, ...]] = {}
    for noisy_word in sorted(targets_by_noisy):
        targets = targets_by_noisy[noisy_word]
        if len(targets) == 1:
            candidates[noisy_word] = next(iter(targets))
        else:
            clashes[noisy_word] = tuple(sorted(targets))

    return TypoGenerationResult(
        config=config,
        tasks=task_tuple,
        source_word_count=source_word_count,
        generated_sample_count=len(samples),
        candidates=candidates,
        clashes=clashes,
    )

AutoCorrect2

AutoCorrect2 API

hotstring.autocorrect2 contains the AutoCorrect2-specific integration layer. It builds on the generic hotstring functionality in hotstring.core.

Source discovery, parsing, caching, and loading are grouped under the source_loading subpackage.

AutoCorrect2 models

This module contains the concrete AutoCorrect2CandidateHotstring model.

models

Define AutoCorrect2-specific hotstring and result models.

AutoCorrect2CandidateHotstring dataclass

Bases: CandidateHotstring

Represent a candidate rendered using AutoCorrect2's f() helper.

The inherited constructor trigger input is semantic trigger text. The semantic replacement is converted to a safe AutoHotkey string literal and passed as the single argument to f().

Source code in hotstring\autocorrect2\models.py

@dataclass(frozen=True, slots=True)
class AutoCorrect2CandidateHotstring(CandidateHotstring):
    """Represent a candidate rendered using AutoCorrect2's `f()` helper.

    The inherited constructor `trigger` input is semantic trigger text. The
    semantic replacement is converted to a safe AutoHotkey string literal and
    passed as the single argument to `f()`.
    """

    def compute_content(self, replacement: str) -> str:
        """Compute AutoCorrect2 executable content for a replacement.

        Args:
            replacement:
                Intended replacement text.

        Returns:
            AutoHotkey expression calling `f()` with the replacement.
        """
        return f"f({self.to_ahk_string_literal(replacement)})"

compute_content

compute_content(replacement: str) -> str

Compute AutoCorrect2 executable content for a replacement.

Parameters:

Name	Type	Description	Default
replacement	str	Intended replacement text.	required

Returns:

Type	Description
str	AutoHotkey expression calling f() with the replacement.

Source code in hotstring\autocorrect2\models.py

def compute_content(self, replacement: str) -> str:
    """Compute AutoCorrect2 executable content for a replacement.

    Args:
        replacement:
            Intended replacement text.

    Returns:
        AutoHotkey expression calling `f()` with the replacement.
    """
    return f"f({self.to_ahk_string_literal(replacement)})"

AutoCorrect2CheckResult dataclass

Represent the result of checking candidates against AutoCorrect2.

Attributes:

Name	Type	Description
accepted	tuple[AutoCorrect2CandidateHotstring, ...]	Candidates with no detected conflict.
rejected	tuple[CandidateAssessment, ...]	Assessments for candidates with one or more conflicts.

Source code in hotstring\autocorrect2\models.py

@dataclass(frozen=True, slots=True)
class AutoCorrect2CheckResult:
    """Represent the result of checking candidates against AutoCorrect2.

    Attributes:
        accepted:
            Candidates with no detected conflict.
        rejected:
            Assessments for candidates with one or more conflicts.
    """

    accepted: tuple[AutoCorrect2CandidateHotstring, ...]
    rejected: tuple[CandidateAssessment, ...]

    @property
    def candidate_count(self) -> int:
        """Return the total number of candidates checked.

        Returns:
            Number of accepted plus rejected candidates.
        """
        return len(self.accepted) + len(self.rejected)

candidate_count property

candidate_count: int

Return the total number of candidates checked.

Returns:

Type	Description
int	Number of accepted plus rejected candidates.

Source loading

Source loading API

hotstring.autocorrect2.source_loading contains the components responsible for loading existing AutoCorrect2 hotstrings from source files.

The subpackage separates source parsing, cache management, and the higher-level loading workflow into dedicated modules.

Source parser

parser

Parse static AutoCorrect2 hotstring declarations from source text.

The parser treats trigger source spelling as AutoHotkey syntax rather than as plain text. In particular, an escaped colon (`:) is part of the trigger and must not be mistaken for the closing :: delimiter. Parsed trigger text is passed to ExistingHotstring in AHK source form; the model then derives semantic and canonical source forms.

LOGGER module-attribute

LOGGER: Final[Logger] = logging.getLogger(__name__)

Module logger used for parser diagnostics.

HOTSTRING_PREFIX_PATTERN module-attribute

HOTSTRING_PREFIX_PATTERN: Final[Pattern[str]] = re.compile(
    "^[ \\t]*:([^\\r\\n:]*):"
)

Pattern capturing a static declaration's indentation and option prefix.

extract_hotstrings

extract_hotstrings(
    content: str, *, source: str | Path
) -> list[ExistingHotstring]

Extract static hotstring declarations from decoded AutoCorrect2 text.

The function performs no filesystem I/O. Each source line is checked for a leading :options: prefix. The trigger is then scanned character by character so escaped characters cannot terminate it accidentally.

Parameters:

Name	Type	Description	Default
content	str	Decoded AutoCorrect2 source text.	required
source	str | Path	Source identifier stored on each extracted definition.	required

Returns:

Type	Description
list[ExistingHotstring]	Existing hotstrings in declaration order.

Raises:

Type	Description
TypeError	If the supplied source data has an invalid type.
ValueError	If a recognized declaration contains invalid options or invalid AHK trigger escaping.

Source code in hotstring\autocorrect2\source_loading\parser.py

def extract_hotstrings(content: str, *, source: str | Path) -> list[ExistingHotstring]:
    """Extract static hotstring declarations from decoded AutoCorrect2 text.

    The function performs no filesystem I/O. Each source line is checked for a
    leading ``:options:`` prefix. The trigger is then scanned character by
    character so escaped characters cannot terminate it accidentally.

    Args:
        content:
            Decoded AutoCorrect2 source text.
        source:
            Source identifier stored on each extracted definition.

    Returns:
        Existing hotstrings in declaration order.

    Raises:
        TypeError:
            If the supplied source data has an invalid type.
        ValueError:
            If a recognized declaration contains invalid options or invalid
            AHK trigger escaping.
    """
    if not isinstance(content, str):
        raise TypeError(
            f"Hotstring source content must be a string, got {type(content).__name__}"
        )
    if not isinstance(source, (str, Path)):
        raise TypeError(
            "Hotstring source identifier must be a string or Path, "
            f"got {type(source).__name__}"
        )

    source_path = Path(source)
    LOGGER.debug("Parsing static hotstrings from source %s.", source_path)

    hotstrings: list[ExistingHotstring] = []
    for line in content.splitlines():
        prefix_match = HOTSTRING_PREFIX_PATTERN.match(line)
        if prefix_match is None:
            continue

        trigger_start = prefix_match.end()
        trigger_end = _find_trigger_delimiter(line, start=trigger_start)
        if trigger_end is None:
            continue

        hotstrings.append(
            ExistingHotstring(
                trigger=line[trigger_start:trigger_end],
                options_input=prefix_match.group(1),
                source=source_path,
            )
        )

    LOGGER.debug(
        "Parsed %d static hotstring(s) from source %s.",
        len(hotstrings),
        source_path,
    )
    return hotstrings

_find_trigger_delimiter

_find_trigger_delimiter(
    line: str, *, start: int
) -> int | None

Locate the first unescaped :: trigger delimiter on one source line.

A backtick escapes the next source character, so a colon immediately after a backtick cannot begin the delimiter. Two consecutive backticks represent one literal backtick; scanning the pair as one escaped unit naturally lets a following :: terminate the trigger.

An unescaped semicolon preceded by horizontal whitespace begins an AutoHotkey comment. If such a comment starts before a closing delimiter, the line does not contain a complete static hotstring declaration.

Parameters:

Name	Type	Description	Default
line	str	One source line without its newline terminator.	required
start	int	Index immediately after the :options: prefix.	required

Returns:

Type	Description
int | None	Index of the first colon in the closing delimiter, or None when no
int | None	valid delimiter occurs before the end of the source line.

Source code in hotstring\autocorrect2\source_loading\parser.py

def _find_trigger_delimiter(line: str, *, start: int) -> int | None:
    """Locate the first unescaped ``::`` trigger delimiter on one source line.

    A backtick escapes the next source character, so a colon immediately after
    a backtick cannot begin the delimiter. Two consecutive backticks represent
    one literal backtick; scanning the pair as one escaped unit naturally lets
    a following ``::`` terminate the trigger.

    An unescaped semicolon preceded by horizontal whitespace begins an
    AutoHotkey comment. If such a comment starts before a closing delimiter,
    the line does not contain a complete static hotstring declaration.

    Args:
        line:
            One source line without its newline terminator.
        start:
            Index immediately after the ``:options:`` prefix.

    Returns:
        Index of the first colon in the closing delimiter, or `None` when no
        valid delimiter occurs before the end of the source line.
    """
    index = start

    while index < len(line):
        character = line[index]

        if character == "`":
            if index + 1 >= len(line):
                return None
            index += 2
            continue

        if (
            character == ";"
            and index > 0
            and line[index - 1] in {" ", "\t"}
        ):
            return None

        if character == ":" and index + 1 < len(line) and line[index + 1] == ":":
            return index

        index += 1

    return None

Source cache

cache

Persist AutoCorrect2 source fingerprints and extracted hotstrings.

The cache is an optimization only. SHA-256 of the exact source bytes is the authoritative content identity; filesystem size and modification time are stored as useful metadata but are never trusted as proof that a same-sized source is unchanged.

Cached hotstrings persist only source-derived state: canonical AHK trigger spelling and canonical option text. Semantic trigger text and the case-insensitive semantic comparison key are reconstructed by the domain model on every load so they always reflect the current trigger-normalization implementation.

LOGGER module-attribute

LOGGER: Final[Logger] = logging.getLogger(__name__)

Module logger used for cache diagnostics.

CACHE_SCHEMA_VERSION module-attribute

CACHE_SCHEMA_VERSION: Final[int] = 2

Persistent-cache compatibility version, including parser semantics.

DEFAULT_SOURCE_CACHE_PATH module-attribute

DEFAULT_SOURCE_CACHE_PATH: Final[Path] = (
    PROJECT_ROOT
    / ".cache"
    / "autocorrect2-source-cache.json"
)

Deterministic project-local path used for the persistent source cache.

CachedHotstring dataclass

Represent the minimal persisted form of one extracted hotstring.

Attributes:

Name	Type	Description
trigger	str	Canonical AHK source-form trigger text.
options	str	Canonical hotstring option declaration.

Source code in hotstring\autocorrect2\source_loading\cache.py

@dataclass(frozen=True, slots=True)
class CachedHotstring:
    """Represent the minimal persisted form of one extracted hotstring.

    Attributes:
        trigger:
            Canonical AHK source-form trigger text.
        options:
            Canonical hotstring option declaration.
    """

    trigger: str
    options: str

SourceCacheEntry dataclass

Represent cached state for one AutoCorrect2 source file.

Attributes:

Name	Type	Description
modification_time_ns	int	Source modification time recorded when the entry was refreshed.
size	int	Source size recorded when the entry was refreshed.
sha256	str	SHA-256 digest of the exact source bytes.
hotstrings	tuple[CachedHotstring, ...]	Extracted hotstrings stored in declaration order.

Source code in hotstring\autocorrect2\source_loading\cache.py

@dataclass(frozen=True, slots=True)
class SourceCacheEntry:
    """Represent cached state for one AutoCorrect2 source file.

    Attributes:
        modification_time_ns:
            Source modification time recorded when the entry was refreshed.
        size:
            Source size recorded when the entry was refreshed.
        sha256:
            SHA-256 digest of the exact source bytes.
        hotstrings:
            Extracted hotstrings stored in declaration order.
    """

    modification_time_ns: int
    size: int
    sha256: str
    hotstrings: tuple[CachedHotstring, ...]

SourceCache dataclass

Represent the complete persistent AutoCorrect2 source cache.

Attributes:

Name	Type	Description
project_dir	str	Canonical AutoCorrect2 project directory associated with the cache. This prevents accidental reuse for a different checkout at another path; machine identity is deliberately not part of cache validity.
files	dict[str, SourceCacheEntry]	Cache entries keyed by source path relative to the AutoCorrect2 project root.

Source code in hotstring\autocorrect2\source_loading\cache.py

@dataclass(slots=True)
class SourceCache:
    """Represent the complete persistent AutoCorrect2 source cache.

    Attributes:
        project_dir:
            Canonical AutoCorrect2 project directory associated with the
            cache. This prevents accidental reuse for a different checkout at
            another path; machine identity is deliberately not part of cache
            validity.
        files:
            Cache entries keyed by source path relative to the AutoCorrect2
            project root.
    """

    project_dir: str
    files: dict[str, SourceCacheEntry] = field(default_factory=dict)

canonical_project_dir

canonical_project_dir(project_dir: Path) -> str

Return the canonical project-directory value stored in the cache.

Parameters:

Name	Type	Description	Default
project_dir	Path	AutoCorrect2 project directory.	required

Returns:

Type	Description
str	Absolute normalized project-directory string.

Raises:

Type	Description
TypeError	If the supplied project directory is not a path.
OSError	If path resolution fails.

Source code in hotstring\autocorrect2\source_loading\cache.py

def canonical_project_dir(project_dir: Path) -> str:
    """Return the canonical project-directory value stored in the cache.

    Args:
        project_dir:
            AutoCorrect2 project directory.

    Returns:
        Absolute normalized project-directory string.

    Raises:
        TypeError:
            If the supplied project directory is not a path.
        OSError:
            If path resolution fails.
    """
    if not isinstance(project_dir, Path):
        raise TypeError(
            f"AutoCorrect2 project directory must be a Path, not {type(project_dir).__name__}"
        )
    return str(project_dir.resolve())

source_cache_key

source_cache_key(source: Path) -> str

Return the stable JSON key for a configured source path.

Parameters:

Name	Type	Description	Default
source	Path	Source path relative to the AutoCorrect2 project root.	required

Returns:

Type	Description
str	POSIX-style relative path suitable for use as a JSON object key.

Raises:

Type	Description
TypeError	If the supplied source is not a path.

Source code in hotstring\autocorrect2\source_loading\cache.py

def source_cache_key(source: Path) -> str:
    """Return the stable JSON key for a configured source path.

    Args:
        source:
            Source path relative to the AutoCorrect2 project root.

    Returns:
        POSIX-style relative path suitable for use as a JSON object key.

    Raises:
        TypeError:
            If the supplied source is not a path.
    """
    if not isinstance(source, Path):
        raise TypeError(f"Source cache key must be a Path, not {type(source).__name__}")
    return source.as_posix()

compute_content_hash

compute_content_hash(content: bytes) -> str

Compute the SHA-256 digest used as authoritative content identity.

Parameters:

Name	Type	Description	Default
content	bytes	Exact source-file bytes.	required

Returns:

Type	Description
str	Lowercase hexadecimal SHA-256 digest.

Raises:

Type	Description
TypeError	If the supplied content is not bytes.

Source code in hotstring\autocorrect2\source_loading\cache.py

def compute_content_hash(content: bytes) -> str:
    """Compute the SHA-256 digest used as authoritative content identity.

    Args:
        content:
            Exact source-file bytes.

    Returns:
        Lowercase hexadecimal SHA-256 digest.

    Raises:
        TypeError:
            If the supplied content is not bytes.
    """
    if not isinstance(content, bytes):
        raise TypeError(f"Source content for hashing must be bytes, not {type(content).__name__}")

    digest = hashlib.sha256(content).hexdigest()
    LOGGER.debug("Computed SHA-256 digest for %d source byte(s).", len(content))
    return digest

create_source_cache_entry

create_source_cache_entry(
    hotstrings: Sequence[ExistingHotstring],
    *,
    modification_time_ns: int,
    size: int,
    sha256: str,
) -> SourceCacheEntry

Create a cache entry from parsed hotstrings and source state.

Cached triggers use each model's canonical ahk_trigger field, not its semantic trigger. Restoring the entry therefore feeds exactly the input representation expected by ExistingHotstring.

Parameters:

Name	Type	Description	Default
hotstrings	Sequence[ExistingHotstring]	Parsed hotstrings in declaration order.	required
modification_time_ns	int	Current source modification time.	required
size	int	Current source size.	required
sha256	str	SHA-256 digest of the exact source bytes.	required

Returns:

Type	Description
SourceCacheEntry	Cache entry ready for persistence.

Raises:

Type	Description
TypeError	If source metadata or a hotstring has an invalid type.
ValueError	If source metadata or the digest is invalid.

Source code in hotstring\autocorrect2\source_loading\cache.py

def create_source_cache_entry(
    hotstrings: Sequence[ExistingHotstring],
    *,
    modification_time_ns: int,
    size: int,
    sha256: str,
) -> SourceCacheEntry:
    """Create a cache entry from parsed hotstrings and source state.

    Cached triggers use each model's canonical `ahk_trigger` field, not its
    semantic trigger. Restoring the entry therefore feeds exactly the input
    representation expected by `ExistingHotstring`.

    Args:
        hotstrings:
            Parsed hotstrings in declaration order.
        modification_time_ns:
            Current source modification time.
        size:
            Current source size.
        sha256:
            SHA-256 digest of the exact source bytes.

    Returns:
        Cache entry ready for persistence.

    Raises:
        TypeError:
            If source metadata or a hotstring has an invalid type.
        ValueError:
            If source metadata or the digest is invalid.
    """
    _validate_metadata(modification_time_ns, size, sha256)

    cached_hotstrings: list[CachedHotstring] = []
    for hotstring in hotstrings:
        if not isinstance(hotstring, ExistingHotstring):
            raise TypeError(
                "Cached hotstrings must contain ExistingHotstring instances, "
                f"not {type(hotstring).__name__}"
            )

        cached_hotstrings.append(
            CachedHotstring(
                trigger=hotstring.ahk_trigger,
                options=hotstring.options.declaration(),
            )
        )

    return SourceCacheEntry(
        modification_time_ns=modification_time_ns,
        size=size,
        sha256=sha256,
        hotstrings=tuple(cached_hotstrings),
    )

restore_hotstrings

restore_hotstrings(
    entry: SourceCacheEntry, *, source: Path
) -> list[ExistingHotstring]

Reconstruct domain hotstrings from one persisted cache entry.

The cached trigger is intentionally fed back to ExistingHotstring as AHK source-form constructor input. Its semantic trigger, canonical source representation, parsed options, and case-insensitive semantic key are therefore rebuilt using the current code.

Parameters:

Name	Type	Description	Default
entry	SourceCacheEntry	Cached source entry to reconstruct.	required
source	Path	Source identifier assigned to each reconstructed hotstring.	required

Returns:

Type	Description
list[ExistingHotstring]	Existing hotstrings in their cached declaration order.

Raises:

Type	Description
TypeError	If the cache entry or source identifier has an invalid type.
ValueError	If cached hotstring data is invalid under the current model.

Source code in hotstring\autocorrect2\source_loading\cache.py

def restore_hotstrings(
    entry: SourceCacheEntry,
    *,
    source: Path,
) -> list[ExistingHotstring]:
    """Reconstruct domain hotstrings from one persisted cache entry.

    The cached trigger is intentionally fed back to `ExistingHotstring` as
    AHK source-form constructor input. Its semantic trigger, canonical source
    representation, parsed options, and case-insensitive semantic key are therefore
    rebuilt using the current code.

    Args:
        entry:
            Cached source entry to reconstruct.
        source:
            Source identifier assigned to each reconstructed hotstring.

    Returns:
        Existing hotstrings in their cached declaration order.

    Raises:
        TypeError:
            If the cache entry or source identifier has an invalid type.
        ValueError:
            If cached hotstring data is invalid under the current model.
    """
    if not isinstance(entry, SourceCacheEntry):
        raise TypeError(f"Source cache entry must be SourceCacheEntry, not {type(entry).__name__}")
    if not isinstance(source, Path):
        raise TypeError(f"Hotstring source identifier must be a Path, not {type(source).__name__}")

    hotstrings = [
        ExistingHotstring(
            trigger=hotstring.trigger,
            options_input=hotstring.options,
            source=source,
        )
        for hotstring in entry.hotstrings
    ]

    LOGGER.debug(
        "Reconstructed %d hotstring(s) from cached source %s.",
        len(hotstrings),
        source,
    )
    return hotstrings

load_source_cache

load_source_cache(
    cache_path: Path, *, project_dir: Path
) -> SourceCache

Load the persistent source cache or return an empty compatible cache.

Missing, unreadable, malformed, incompatible, or project-mismatched cache files are treated as disposable optimization state. In those cases an empty cache associated with the requested AutoCorrect2 project is returned.

Parameters:

Name	Type	Description	Default
cache_path	Path	JSON cache file to load.	required
project_dir	Path	AutoCorrect2 project directory expected by the caller.	required

Returns:

Type	Description
SourceCache	Loaded compatible cache, or a new empty cache when persisted state
SourceCache	cannot be reused.

Raises:

Type	Description
TypeError	If a path argument has an invalid type.
OSError	If canonicalizing the project directory fails.

Source code in hotstring\autocorrect2\source_loading\cache.py

def load_source_cache(cache_path: Path, *, project_dir: Path) -> SourceCache:
    """Load the persistent source cache or return an empty compatible cache.

    Missing, unreadable, malformed, incompatible, or project-mismatched cache
    files are treated as disposable optimization state. In those cases an
    empty cache associated with the requested AutoCorrect2 project is returned.

    Args:
        cache_path:
            JSON cache file to load.
        project_dir:
            AutoCorrect2 project directory expected by the caller.

    Returns:
        Loaded compatible cache, or a new empty cache when persisted state
        cannot be reused.

    Raises:
        TypeError:
            If a path argument has an invalid type.
        OSError:
            If canonicalizing the project directory fails.
    """
    if not isinstance(cache_path, Path):
        raise TypeError(f"Cache path must be a Path, not {type(cache_path).__name__}")

    expected_project_dir = canonical_project_dir(project_dir)

    try:
        raw_data: object = json.loads(cache_path.read_text(encoding="utf-8"))
    except FileNotFoundError:
        LOGGER.debug("Source cache does not exist at %s; starting empty.", cache_path)
        return SourceCache(project_dir=expected_project_dir)
    except (OSError, UnicodeError, json.JSONDecodeError):
        LOGGER.debug(
            "Source cache at %s could not be loaded; starting empty.",
            cache_path,
            exc_info=True,
        )
        return SourceCache(project_dir=expected_project_dir)

    if not isinstance(raw_data, dict):
        LOGGER.debug("Source cache at %s is not a JSON object; starting empty.", cache_path)
        return SourceCache(project_dir=expected_project_dir)

    data = cast(dict[str, object], raw_data)
    if data.get("schema_version") != CACHE_SCHEMA_VERSION:
        LOGGER.debug(
            "Source cache schema at %s is incompatible; expected %d and found %r.",
            cache_path,
            CACHE_SCHEMA_VERSION,
            data.get("schema_version"),
        )
        return SourceCache(project_dir=expected_project_dir)

    cached_project_dir = data.get("project_dir")
    if cached_project_dir != expected_project_dir:
        LOGGER.debug(
            "Source cache project mismatch at %s; cached=%r current=%r. Starting empty.",
            cache_path,
            cached_project_dir,
            expected_project_dir,
        )
        return SourceCache(project_dir=expected_project_dir)

    raw_files = data.get("files")
    if not isinstance(raw_files, dict):
        LOGGER.debug("Source cache files section at %s is invalid; starting empty.", cache_path)
        return SourceCache(project_dir=expected_project_dir)

    files: dict[str, SourceCacheEntry] = {}
    for source_key, raw_entry in raw_files.items():
        if not isinstance(source_key, str):
            LOGGER.debug("Ignoring source-cache entry with a non-string key: %r.", source_key)
            continue

        entry = _parse_source_cache_entry(raw_entry)
        if entry is None:
            LOGGER.debug("Ignoring malformed source-cache entry for %s.", source_key)
            continue
        files[source_key] = entry

    LOGGER.debug(
        "Loaded %d source-cache %s from %s.",
        len(files),
        "entry" if len(files) == 1 else "entries",
        cache_path,
    )
    return SourceCache(project_dir=expected_project_dir, files=files)

save_source_cache

save_source_cache(
    cache: SourceCache, cache_path: Path
) -> None

Persist the source cache atomically as UTF-8 JSON.

Each cached hotstring contains exactly trigger and options. The trigger value is the canonical AHK source representation. Source paths are stored once as keys in the surrounding files object.

Parameters:

Name	Type	Description	Default
cache	SourceCache	Source cache to persist.	required
cache_path	Path	Destination JSON file.	required

Raises:

Type	Description
TypeError	If an argument has an invalid type.
OSError	If the cache directory or cache file cannot be written or replaced.

Source code in hotstring\autocorrect2\source_loading\cache.py

def save_source_cache(cache: SourceCache, cache_path: Path) -> None:
    """Persist the source cache atomically as UTF-8 JSON.

    Each cached hotstring contains exactly `trigger` and `options`. The trigger
    value is the canonical AHK source representation. Source paths are stored
    once as keys in the surrounding `files` object.

    Args:
        cache:
            Source cache to persist.
        cache_path:
            Destination JSON file.

    Raises:
        TypeError:
            If an argument has an invalid type.
        OSError:
            If the cache directory or cache file cannot be written or replaced.
    """
    if not isinstance(cache, SourceCache):
        raise TypeError(f"Cache must be SourceCache, not {type(cache).__name__}")
    if not isinstance(cache_path, Path):
        raise TypeError(f"Cache path must be a Path, not {type(cache_path).__name__}")

    cache_path.parent.mkdir(parents=True, exist_ok=True)
    payload = (
        json.dumps(
            _serialize_source_cache(cache),
            ensure_ascii=False,
            indent=2,
        )
        + "\n"
    )

    temporary_path: Path | None = None
    try:
        with tempfile.NamedTemporaryFile(
            mode="w",
            encoding="utf-8",
            newline="\n",
            prefix=f".{cache_path.name}.",
            suffix=".tmp",
            dir=cache_path.parent,
            delete=False,
        ) as temporary_file:
            temporary_file.write(payload)
            temporary_path = Path(temporary_file.name)

        os.replace(temporary_path, cache_path)
    except Exception:
        if temporary_path is not None:
            temporary_path.unlink(missing_ok=True)
        raise

    LOGGER.debug(
        "Persisted %d source-cache entr%s to %s.",
        len(cache.files),
        "y" if len(cache.files) == 1 else "ies",
        cache_path,
    )

_parse_source_cache_entry

_parse_source_cache_entry(
    raw_entry: object,
) -> SourceCacheEntry | None

Parse one untrusted JSON cache entry.

Parameters:

Name	Type	Description	Default
raw_entry	object	Decoded JSON value representing a source entry.	required

Returns:

Type	Description
SourceCacheEntry | None	Validated cache entry, or None when the value is malformed.

Source code in hotstring\autocorrect2\source_loading\cache.py

def _parse_source_cache_entry(raw_entry: object) -> SourceCacheEntry | None:
    """Parse one untrusted JSON cache entry.

    Args:
        raw_entry:
            Decoded JSON value representing a source entry.

    Returns:
        Validated cache entry, or `None` when the value is malformed.
    """
    if not isinstance(raw_entry, dict):
        return None

    entry_data = cast(dict[str, object], raw_entry)
    modification_time_ns = entry_data.get("mtime_ns")
    size = entry_data.get("size")
    sha256 = entry_data.get("sha256")
    raw_hotstrings = entry_data.get("hotstrings")

    if not _metadata_is_valid(modification_time_ns, size, sha256):
        return None
    if not isinstance(raw_hotstrings, list):
        return None

    hotstrings: list[CachedHotstring] = []
    for raw_hotstring in raw_hotstrings:
        cached_hotstring = _parse_cached_hotstring(raw_hotstring)
        if cached_hotstring is None:
            return None
        hotstrings.append(cached_hotstring)

    return SourceCacheEntry(
        modification_time_ns=cast(int, modification_time_ns),
        size=cast(int, size),
        sha256=cast(str, sha256),
        hotstrings=tuple(hotstrings),
    )

_parse_cached_hotstring

_parse_cached_hotstring(
    raw_hotstring: object,
) -> CachedHotstring | None

Parse one minimal hotstring record from decoded JSON.

Parameters:

Name	Type	Description	Default
raw_hotstring	object	Decoded JSON value representing one cached hotstring.	required

Returns:

Type	Description
CachedHotstring | None	Parsed cached hotstring, or None when malformed.

Source code in hotstring\autocorrect2\source_loading\cache.py

def _parse_cached_hotstring(raw_hotstring: object) -> CachedHotstring | None:
    """Parse one minimal hotstring record from decoded JSON.

    Args:
        raw_hotstring:
            Decoded JSON value representing one cached hotstring.

    Returns:
        Parsed cached hotstring, or `None` when malformed.
    """
    if not isinstance(raw_hotstring, dict):
        return None

    hotstring_data = cast(dict[str, object], raw_hotstring)
    if set(hotstring_data) != {"trigger", "options"}:
        return None

    trigger = hotstring_data.get("trigger")
    options = hotstring_data.get("options")
    if not isinstance(trigger, str) or not isinstance(options, str):
        return None

    return CachedHotstring(trigger=trigger, options=options)

_serialize_source_cache

_serialize_source_cache(
    cache: SourceCache,
) -> dict[str, object]

Convert the in-memory source cache to JSON-compatible values.

Parameters:

Name	Type	Description	Default
cache	SourceCache	Source cache to serialize.	required

Returns:

Type	Description
dict[str, object]	JSON-compatible cache document.

Source code in hotstring\autocorrect2\source_loading\cache.py

def _serialize_source_cache(cache: SourceCache) -> dict[str, object]:
    """Convert the in-memory source cache to JSON-compatible values.

    Args:
        cache:
            Source cache to serialize.

    Returns:
        JSON-compatible cache document.
    """
    files: dict[str, object] = {}
    for source_key, entry in sorted(cache.files.items()):
        files[source_key] = {
            "mtime_ns": entry.modification_time_ns,
            "size": entry.size,
            "sha256": entry.sha256,
            "hotstrings": [
                {
                    "trigger": hotstring.trigger,
                    "options": hotstring.options,
                }
                for hotstring in entry.hotstrings
            ],
        }

    return {
        "schema_version": CACHE_SCHEMA_VERSION,
        "project_dir": cache.project_dir,
        "files": files,
    }

_validate_metadata

_validate_metadata(
    modification_time_ns: int, size: int, sha256: str
) -> None

Validate metadata used to construct a source-cache entry.

Parameters:

Name	Type	Description	Default
modification_time_ns	int	Source modification time.	required
size	int	Source size.	required
sha256	str	Source SHA-256 digest.	required

Raises:

Type	Description
TypeError	If a metadata value has an invalid type.
ValueError	If a metadata value is outside its valid domain.

Source code in hotstring\autocorrect2\source_loading\cache.py

def _validate_metadata(modification_time_ns: int, size: int, sha256: str) -> None:
    """Validate metadata used to construct a source-cache entry.

    Args:
        modification_time_ns:
            Source modification time.
        size:
            Source size.
        sha256:
            Source SHA-256 digest.

    Raises:
        TypeError:
            If a metadata value has an invalid type.
        ValueError:
            If a metadata value is outside its valid domain.
    """
    if isinstance(modification_time_ns, bool) or not isinstance(modification_time_ns, int):
        raise TypeError("Source modification time must be an integer.")
    if isinstance(size, bool) or not isinstance(size, int):
        raise TypeError("Source size must be an integer.")
    if not isinstance(sha256, str):
        raise TypeError("Source SHA-256 digest must be a string.")

    if modification_time_ns < 0:
        raise ValueError("Source modification time cannot be negative.")
    if size < 0:
        raise ValueError("Source size cannot be negative.")
    if not _sha256_is_valid(sha256):
        raise ValueError("Source SHA-256 digest must be 64 hexadecimal characters.")

_metadata_is_valid

_metadata_is_valid(
    modification_time_ns: object,
    size: object,
    sha256: object,
) -> bool

Return whether decoded source metadata has the expected shape.

Parameters:

Name	Type	Description	Default
modification_time_ns	object	Decoded modification-time value.	required
size	object	Decoded file-size value.	required
sha256	object	Decoded digest value.	required

Returns:

Type	Description
bool	Whether all metadata values are valid.

Source code in hotstring\autocorrect2\source_loading\cache.py

def _metadata_is_valid(
    modification_time_ns: object,
    size: object,
    sha256: object,
) -> bool:
    """Return whether decoded source metadata has the expected shape.

    Args:
        modification_time_ns:
            Decoded modification-time value.
        size:
            Decoded file-size value.
        sha256:
            Decoded digest value.

    Returns:
        Whether all metadata values are valid.
    """
    return (
        isinstance(modification_time_ns, int)
        and not isinstance(modification_time_ns, bool)
        and modification_time_ns >= 0
        and isinstance(size, int)
        and not isinstance(size, bool)
        and size >= 0
        and isinstance(sha256, str)
        and _sha256_is_valid(sha256)
    )

_sha256_is_valid

_sha256_is_valid(value: str) -> bool

Return whether a string is a lowercase-or-uppercase SHA-256 hex digest.

Parameters:

Name	Type	Description	Default
value	str	Candidate digest string.	required

Returns:

Type	Description
bool	Whether the value contains exactly 64 hexadecimal characters.

Source code in hotstring\autocorrect2\source_loading\cache.py

def _sha256_is_valid(value: str) -> bool:
    """Return whether a string is a lowercase-or-uppercase SHA-256 hex digest.

    Args:
        value:
            Candidate digest string.

    Returns:
        Whether the value contains exactly 64 hexadecimal characters.
    """
    return len(value) == 64 and all(character in string.hexdigits for character in value)

Source loader

loader

Load configured AutoCorrect2 hotstring sources through a persistent cache.

LOGGER module-attribute

LOGGER: Final[Logger] = logging.getLogger(__name__)

Module logger used for source-loading diagnostics.

load_existing_hotstrings

load_existing_hotstrings(
    project_dir: Path,
    *,
    required_source_paths: Sequence[
        Path
    ] = REQUIRED_HOTSTRING_SOURCE_RELATIVE_PATHS,
    optional_source_paths: Sequence[
        Path
    ] = OPTIONAL_HOTSTRING_SOURCE_RELATIVE_PATHS,
    cache_path: Path | None = DEFAULT_SOURCE_CACHE_PATH,
) -> list[ExistingHotstring]

Load all configured active static AutoCorrect2 hotstrings.

Required sources must exist. Optional sources, including the project-owned generated include file, are scanned only when present. When caching is enabled, SHA-256 is the authoritative content identity. File size and modification time are retained as useful metadata and positive change signals, but matching metadata never suppresses hash verification.

Cache failures are treated as optimization failures rather than source-load failures. The function falls back to parsing authoritative AutoCorrect2 source files when persisted cache data cannot be used.

Parameters:

Name	Type	Description	Default
project_dir	Path	AutoCorrect2 project directory.	required
required_source_paths	Sequence[Path]	Relative source paths that must exist.	REQUIRED_HOTSTRING_SOURCE_RELATIVE_PATHS
optional_source_paths	Sequence[Path]	Relative source paths scanned when present.	OPTIONAL_HOTSTRING_SOURCE_RELATIVE_PATHS
cache_path	Path | None	Persistent JSON cache path, or None to disable caching.	DEFAULT_SOURCE_CACHE_PATH

Returns:

Type	Description
list[ExistingHotstring]	Existing hotstrings in source-file and declaration order.

Raises:

Type	Description
TypeError	If a path argument has an invalid type.
FileNotFoundError	If a required source does not exist.
UnicodeDecodeError	If a changed source is not valid UTF-8 text.
ValueError	If a parsed hotstring declaration is invalid.
OSError	If an authoritative source cannot be inspected or read.

Source code in hotstring\autocorrect2\source_loading\loader.py

def load_existing_hotstrings(
    project_dir: Path,
    *,
    required_source_paths: Sequence[Path] = REQUIRED_HOTSTRING_SOURCE_RELATIVE_PATHS,
    optional_source_paths: Sequence[Path] = OPTIONAL_HOTSTRING_SOURCE_RELATIVE_PATHS,
    cache_path: Path | None = DEFAULT_SOURCE_CACHE_PATH,
) -> list[ExistingHotstring]:
    """Load all configured active static AutoCorrect2 hotstrings.

    Required sources must exist. Optional sources, including the project-owned
    generated include file, are scanned only when present. When caching is
    enabled, SHA-256 is the authoritative content identity. File size and
    modification time are retained as useful metadata and positive change
    signals, but matching metadata never suppresses hash verification.

    Cache failures are treated as optimization failures rather than source-load
    failures. The function falls back to parsing authoritative AutoCorrect2
    source files when persisted cache data cannot be used.

    Args:
        project_dir:
            AutoCorrect2 project directory.
        required_source_paths:
            Relative source paths that must exist.
        optional_source_paths:
            Relative source paths scanned when present.
        cache_path:
            Persistent JSON cache path, or `None` to disable caching.

    Returns:
        Existing hotstrings in source-file and declaration order.

    Raises:
        TypeError:
            If a path argument has an invalid type.
        FileNotFoundError:
            If a required source does not exist.
        UnicodeDecodeError:
            If a changed source is not valid UTF-8 text.
        ValueError:
            If a parsed hotstring declaration is invalid.
        OSError:
            If an authoritative source cannot be inspected or read.
    """
    if not isinstance(project_dir, Path):
        raise TypeError(
            f"AutoCorrect2 project directory must be a Path, not {type(project_dir).__name__}"
        )
    if cache_path is not None and not isinstance(cache_path, Path):
        raise TypeError(
            f"Source cache path must be a Path or None, not {type(cache_path).__name__}"
        )

    LOGGER.debug("Loading AutoCorrect2 hotstrings from project %s.", project_dir)

    cache = (
        load_source_cache(cache_path, project_dir=project_dir) if cache_path is not None else None
    )
    cache_dirty = False
    hotstrings: list[ExistingHotstring] = []

    for relative_path in required_source_paths:
        file_path = project_dir / relative_path
        if not file_path.is_file():
            LOGGER.debug("Required hotstring source is missing: %s.", file_path)
            raise FileNotFoundError(f"Hotstring source file was not found: {file_path}")

        loaded, source_cache_changed = _load_source_hotstrings(
            file_path,
            source=relative_path,
            cache=cache,
        )
        hotstrings.extend(loaded)
        cache_dirty = cache_dirty or source_cache_changed

    for relative_path in optional_source_paths:
        file_path = project_dir / relative_path
        if not file_path.is_file():
            LOGGER.debug(
                "Optional hotstring source is absent and will be skipped: %s.",
                file_path,
            )
            if cache is not None:
                source_key = source_cache_key(relative_path)
                if cache.files.pop(source_key, None) is not None:
                    LOGGER.debug(
                        "Removed stale cache entry for absent optional source %s.",
                        relative_path,
                    )
                    cache_dirty = True
            continue

        loaded, source_cache_changed = _load_source_hotstrings(
            file_path,
            source=relative_path,
            cache=cache,
        )
        hotstrings.extend(loaded)
        cache_dirty = cache_dirty or source_cache_changed

    if cache is not None and cache_dirty and cache_path is not None:
        try:
            save_source_cache(cache, cache_path)
        except OSError:
            LOGGER.debug(
                "Updated source cache could not be persisted to %s; continuing without failure.",
                cache_path,
                exc_info=True,
            )
    elif cache is not None:
        LOGGER.debug("Source cache remained unchanged; no cache write is required.")

    LOGGER.debug("Loaded %d existing AutoCorrect2 hotstring(s).", len(hotstrings))
    return hotstrings

_load_source_hotstrings

_load_source_hotstrings(
    file_path: Path,
    *,
    source: Path,
    cache: SourceCache | None,
) -> tuple[list[ExistingHotstring], bool]

Load one source using cache reuse when its content hash matches.

Parameters:

Name	Type	Description	Default
file_path	Path	Authoritative source file to inspect.	required
source	Path	Relative source identifier stored on extracted hotstrings.	required
cache	SourceCache | None	Loaded persistent cache, or None when caching is disabled.	required

Returns:

Type	Description
list[ExistingHotstring]	Pair containing loaded hotstrings and whether the in-memory cache was
bool	modified.

Raises:

Type	Description
UnicodeDecodeError	If source bytes requiring parsing are not valid UTF-8 text.
ValueError	If a parsed hotstring declaration is invalid.
OSError	If the source cannot be inspected or read.

Source code in hotstring\autocorrect2\source_loading\loader.py

def _load_source_hotstrings(
    file_path: Path,
    *,
    source: Path,
    cache: SourceCache | None,
) -> tuple[list[ExistingHotstring], bool]:
    """Load one source using cache reuse when its content hash matches.

    Args:
        file_path:
            Authoritative source file to inspect.
        source:
            Relative source identifier stored on extracted hotstrings.
        cache:
            Loaded persistent cache, or `None` when caching is disabled.

    Returns:
        Pair containing loaded hotstrings and whether the in-memory cache was
        modified.

    Raises:
        UnicodeDecodeError:
            If source bytes requiring parsing are not valid UTF-8 text.
        ValueError:
            If a parsed hotstring declaration is invalid.
        OSError:
            If the source cannot be inspected or read.
    """
    if cache is None:
        LOGGER.debug("Cache disabled for source %s; parsing authoritative file.", source)
        content = file_path.read_bytes()
        return _parse_source_content(content, source=source), False

    source_key = source_cache_key(source)
    cached_entry = cache.files.get(source_key)
    source_stat = file_path.stat()

    if cached_entry is None:
        LOGGER.debug("Cache miss for source %s; parsing authoritative file.", source)
        return _parse_and_refresh_source(
            file_path,
            source=source,
            source_key=source_key,
            source_stat=source_stat,
            cache=cache,
        )

    if source_stat.st_size != cached_entry.size:
        LOGGER.debug(
            "Source size changed for %s (%d -> %d); reparsing without old-hash comparison.",
            source,
            cached_entry.size,
            source_stat.st_size,
        )
        return _parse_and_refresh_source(
            file_path,
            source=source,
            source_key=source_key,
            source_stat=source_stat,
            cache=cache,
        )

    if source_stat.st_mtime_ns != cached_entry.modification_time_ns:
        LOGGER.debug("Source modification time changed for %s; verifying content hash.", source)
    else:
        LOGGER.debug(
            "Source size and modification time match cache for %s; verifying content hash anyway.",
            source,
        )

    content = file_path.read_bytes()
    current_hash = compute_content_hash(content)

    if current_hash != cached_entry.sha256:
        LOGGER.debug("Content hash changed for source %s; reparsing.", source)
        return _parse_and_refresh_source(
            file_path,
            source=source,
            source_key=source_key,
            source_stat=source_stat,
            cache=cache,
            content=content,
            content_hash=current_hash,
        )

    try:
        hotstrings = restore_hotstrings(cached_entry, source=source)
    except (TypeError, ValueError):
        LOGGER.debug(
            "Cached parsed hotstrings for %s are incompatible; reparsing authoritative content.",
            source,
            exc_info=True,
        )
        return _parse_and_refresh_source(
            file_path,
            source=source,
            source_key=source_key,
            source_stat=source_stat,
            cache=cache,
            content=content,
            content_hash=current_hash,
        )

    cache_changed = False
    if source_stat.st_mtime_ns != cached_entry.modification_time_ns:
        cache.files[source_key] = SourceCacheEntry(
            modification_time_ns=source_stat.st_mtime_ns,
            size=source_stat.st_size,
            sha256=cached_entry.sha256,
            hotstrings=cached_entry.hotstrings,
        )
        cache_changed = True
        LOGGER.debug(
            "Content for %s is unchanged; refreshed cached filesystem metadata only.",
            source,
        )
    else:
        LOGGER.debug("Cache hit for source %s; reused extracted hotstrings.", source)

    return hotstrings, cache_changed

_parse_and_refresh_source

_parse_and_refresh_source(
    file_path: Path,
    *,
    source: Path,
    source_key: str,
    source_stat: stat_result,
    cache: SourceCache,
    content: bytes | None = None,
    content_hash: str | None = None,
) -> tuple[list[ExistingHotstring], bool]

Parse one authoritative source and replace its cache entry.

Parameters:

Name	Type	Description	Default
file_path	Path	Source file used when bytes have not already been read.	required
source	Path	Relative source identifier stored on extracted hotstrings.	required
source_key	str	Stable cache key for the source.	required
source_stat	stat_result	Filesystem metadata captured before parsing.	required
cache	SourceCache	In-memory source cache to update.	required
content	bytes | None	Already-read source bytes when available.	None
content_hash	str | None	Already-computed source digest when available.	None

Returns:

Type	Description
list[ExistingHotstring]	Pair containing parsed hotstrings and True to indicate that the cache
bool	was refreshed.

Raises:

Type	Description
TypeError	If the supplied filesystem metadata is invalid.
UnicodeDecodeError	If source bytes are not valid UTF-8 text.
ValueError	If a parsed hotstring declaration is invalid.
OSError	If source bytes must be read and the read fails.

Source code in hotstring\autocorrect2\source_loading\loader.py

def _parse_and_refresh_source(
    file_path: Path,
    *,
    source: Path,
    source_key: str,
    source_stat: os.stat_result,
    cache: SourceCache,
    content: bytes | None = None,
    content_hash: str | None = None,
) -> tuple[list[ExistingHotstring], bool]:
    """Parse one authoritative source and replace its cache entry.

    Args:
        file_path:
            Source file used when bytes have not already been read.
        source:
            Relative source identifier stored on extracted hotstrings.
        source_key:
            Stable cache key for the source.
        source_stat:
            Filesystem metadata captured before parsing.
        cache:
            In-memory source cache to update.
        content:
            Already-read source bytes when available.
        content_hash:
            Already-computed source digest when available.

    Returns:
        Pair containing parsed hotstrings and `True` to indicate that the cache
        was refreshed.

    Raises:
        TypeError:
            If the supplied filesystem metadata is invalid.
        UnicodeDecodeError:
            If source bytes are not valid UTF-8 text.
        ValueError:
            If a parsed hotstring declaration is invalid.
        OSError:
            If source bytes must be read and the read fails.
    """
    if content is None:
        content = file_path.read_bytes()
    if content_hash is None:
        content_hash = compute_content_hash(content)

    hotstrings = _parse_source_content(content, source=source)

    modification_time_ns = getattr(source_stat, "st_mtime_ns", None)
    size = getattr(source_stat, "st_size", None)
    if not isinstance(modification_time_ns, int) or isinstance(modification_time_ns, bool):
        raise TypeError("Source stat result does not provide a valid st_mtime_ns value.")
    if not isinstance(size, int) or isinstance(size, bool):
        raise TypeError("Source stat result does not provide a valid st_size value.")

    cache.files[source_key] = create_source_cache_entry(
        hotstrings,
        modification_time_ns=modification_time_ns,
        size=size,
        sha256=content_hash,
    )
    LOGGER.debug(
        "Refreshed cache entry for source %s with %d parsed hotstring(s).",
        source,
        len(hotstrings),
    )
    return hotstrings, True

_parse_source_content

_parse_source_content(
    content: bytes, *, source: Path
) -> list[ExistingHotstring]

Decode source bytes and delegate static declaration parsing.

Parameters:

Name	Type	Description	Default
content	bytes	Exact source-file bytes.	required
source	Path	Relative source identifier stored on extracted hotstrings.	required

Returns:

Type	Description
list[ExistingHotstring]	Parsed existing hotstrings in declaration order.

Raises:

Type	Description
UnicodeDecodeError	If the source is not valid UTF-8 text.
ValueError	If an extracted hotstring declaration is invalid.

Source code in hotstring\autocorrect2\source_loading\loader.py

def _parse_source_content(content: bytes, *, source: Path) -> list[ExistingHotstring]:
    """Decode source bytes and delegate static declaration parsing.

    Args:
        content:
            Exact source-file bytes.
        source:
            Relative source identifier stored on extracted hotstrings.

    Returns:
        Parsed existing hotstrings in declaration order.

    Raises:
        UnicodeDecodeError:
            If the source is not valid UTF-8 text.
        ValueError:
            If an extracted hotstring declaration is invalid.
    """
    LOGGER.debug("Decoding authoritative source %s for parsing.", source)
    return extract_hotstrings(content.decode("utf-8-sig"), source=source)

AutoCorrect2 writer

writer

Append approved AutoCorrect2 candidates to the generated include file.

GENERATED_FILE_HEADER module-attribute

GENERATED_FILE_HEADER = "; AUTO-GENERATED BY autocorrect2-hotstring-generation\n; Add this file to AutoCorrect2 with a one-time #Include.\n; Do not edit generated entries manually.\n"

Header written when the generated include file is first created.

append_candidates

append_candidates(
    candidates: Sequence[AutoCorrect2CandidateHotstring],
    *,
    project_dir: Path,
    relative_path: Path = GENERATED_HOTSTRINGS_RELATIVE_PATH,
) -> Path

Append accepted candidates to the project-owned AutoCorrect2 include.

Each candidate must explicitly use B0 and X, which are required by the AutoCorrect2 f()-based generated form. Trigger rendering is delegated to the hotstring model, which emits its canonical ahk_trigger source form.

Parameters:

Name	Type	Description	Default
candidates	Sequence[AutoCorrect2CandidateHotstring]	Accepted AutoCorrect2 candidates to append.	required
project_dir	Path	AutoCorrect2 project directory.	required
relative_path	Path	Generated include path relative to project_dir.	GENERATED_HOTSTRINGS_RELATIVE_PATH

Returns:

Type	Description
Path	Path of the generated include file.

Raises:

Type	Description
ValueError	If a candidate is not explicitly configured with B0X behavior.
OSError	If the generated file cannot be read or written.

Source code in hotstring\autocorrect2\writer.py

def append_candidates(
    candidates: Sequence[AutoCorrect2CandidateHotstring],
    *,
    project_dir: Path,
    relative_path: Path = GENERATED_HOTSTRINGS_RELATIVE_PATH,
) -> Path:
    """Append accepted candidates to the project-owned AutoCorrect2 include.

    Each candidate must explicitly use `B0` and `X`, which are required by the
    AutoCorrect2 `f()`-based generated form. Trigger rendering is delegated to
    the hotstring model, which emits its canonical `ahk_trigger` source form.

    Args:
        candidates:
            Accepted AutoCorrect2 candidates to append.
        project_dir:
            AutoCorrect2 project directory.
        relative_path:
            Generated include path relative to `project_dir`.

    Returns:
        Path of the generated include file.

    Raises:
        ValueError:
            If a candidate is not explicitly configured with `B0X` behavior.
        OSError:
            If the generated file cannot be read or written.
    """
    target_path = project_dir / relative_path
    if not candidates:
        return target_path

    for candidate in candidates:
        _validate_writable_candidate(candidate)

    prefix = ""
    if not target_path.exists() or target_path.stat().st_size == 0:
        prefix = GENERATED_FILE_HEADER
    else:
        current = read_text(target_path)
        if not current.endswith(("\n", "\r")):
            prefix = "\n"

    rendered = "\n".join(candidate.render() for candidate in candidates)
    write_text(target_path, prefix + rendered + "\n", append=True)
    return target_path

_validate_writable_candidate

_validate_writable_candidate(
    candidate: AutoCorrect2CandidateHotstring,
) -> None

Validate the AutoCorrect2-specific B0X writing contract.

Parameters:

Name	Type	Description	Default
candidate	AutoCorrect2CandidateHotstring	Candidate that may be appended to the generated include.	required

Raises:

Type	Description
ValueError	If automatic backspacing is not explicitly disabled or execution is not explicitly enabled.

Source code in hotstring\autocorrect2\writer.py

def _validate_writable_candidate(candidate: AutoCorrect2CandidateHotstring) -> None:
    """Validate the AutoCorrect2-specific `B0X` writing contract.

    Args:
        candidate:
            Candidate that may be appended to the generated include.

    Raises:
        ValueError:
            If automatic backspacing is not explicitly disabled or execution
            is not explicitly enabled.
    """
    if candidate.options.automatic_backspacing is not SettingState.DISABLED:
        raise ValueError(
            "AutoCorrect2 generated candidates must explicitly disable "
            "automatic backspacing with B0."
        )
    if candidate.options.execute is not SettingState.ENABLED:
        raise ValueError(
            "AutoCorrect2 generated candidates must explicitly enable "
            "executable content handling with X."
        )

AutoCorrect2 integration

integration

Manage custom hotstring includes in AutoCorrect2's autocorrection context.

AutoCorrect2IntegrationError

Bases: RuntimeError

Raised when AutoCorrect2's include structure is inconsistent or ambiguous.

Source code in hotstring\autocorrect2\integration.py

class AutoCorrect2IntegrationError(RuntimeError):
    """Raised when AutoCorrect2's include structure is inconsistent or ambiguous."""

_IncludeState dataclass

Store validated source state for one custom include.

Attributes:

Name	Type	Description
source_path	Path	AutoCorrect2 main script being inspected.
lines	list[str]	Main-script source lines including newline terminators.
hotif_start	int	Index of the target #HotIf directive.
hotif_end	int	Index of the next #HotIf directive terminating the context.
custom_include_index	int | None	Existing custom include line, or None when absent.

Source code in hotstring\autocorrect2\integration.py

@dataclass(frozen=True, slots=True)
class _IncludeState:
    """Store validated source state for one custom include.

    Attributes:
        source_path:
            AutoCorrect2 main script being inspected.
        lines:
            Main-script source lines including newline terminators.
        hotif_start:
            Index of the target `#HotIf` directive.
        hotif_end:
            Index of the next `#HotIf` directive terminating the context.
        custom_include_index:
            Existing custom include line, or `None` when absent.
    """

    source_path: Path
    lines: list[str]
    hotif_start: int
    hotif_end: int
    custom_include_index: int | None

has_custom_hotstring_include

has_custom_hotstring_include(
    custom_file_path: str | Path, *, project_dir: str | Path
) -> bool

Return whether a custom file is included in AutoCorrect2's correction context.

Parameters:

Name	Type	Description	Default
custom_file_path	str | Path	Custom file to look for. A relative path is interpreted relative to the AutoCorrect2 project directory.	required
project_dir	str | Path	AutoCorrect2 project directory.	required

Returns:

Type	Description
bool	True when exactly one include exists inside the expected
bool	#HotIf AutoCorrectionsActivelyRunning() context; otherwise False
bool	when the include is completely absent.

Raises:

Type	Description
FileNotFoundError	If AutoCorrect2's main source file does not exist.
ValueError	If the custom path refers to a protected integration source.
AutoCorrect2IntegrationError	If the expected include/context structure is ambiguous.
OSError	If AutoCorrect2's main source file cannot be read.

Source code in hotstring\autocorrect2\integration.py

def has_custom_hotstring_include(
    custom_file_path: str | Path,
    *,
    project_dir: str | Path,
) -> bool:
    """Return whether a custom file is included in AutoCorrect2's correction context.

    Args:
        custom_file_path:
            Custom file to look for. A relative path is interpreted relative
            to the AutoCorrect2 project directory.
        project_dir:
            AutoCorrect2 project directory.

    Returns:
        `True` when exactly one include exists inside the expected
        `#HotIf AutoCorrectionsActivelyRunning()` context; otherwise `False`
        when the include is completely absent.

    Raises:
        FileNotFoundError:
            If AutoCorrect2's main source file does not exist.
        ValueError:
            If the custom path refers to a protected integration source.
        AutoCorrect2IntegrationError:
            If the expected include/context structure is ambiguous.
        OSError:
            If AutoCorrect2's main source file cannot be read.
    """
    return (
        _inspect_include_state(Path(custom_file_path), Path(project_dir)).custom_include_index
        is not None
    )

add_custom_hotstring_include

add_custom_hotstring_include(
    custom_file_path: str | Path, *, project_dir: str | Path
) -> bool

Add a custom file to AutoCorrect2's autocorrection context if absent.

Parameters:

Name	Type	Description	Default
custom_file_path	str | Path	Custom file to include. A relative path is interpreted relative to the AutoCorrect2 project directory.	required
project_dir	str | Path	AutoCorrect2 project directory.	required

Returns:

Type	Description
bool	True if the source file was modified, or False if the include was
bool	already correctly present.

Raises:

Type	Description
FileNotFoundError	If AutoCorrect2's main source file does not exist.
ValueError	If the path is invalid or cannot be represented safely.
AutoCorrect2IntegrationError	If the expected include/context structure is ambiguous.
OSError	If the source file cannot be read or written.

Source code in hotstring\autocorrect2\integration.py

def add_custom_hotstring_include(
    custom_file_path: str | Path,
    *,
    project_dir: str | Path,
) -> bool:
    """Add a custom file to AutoCorrect2's autocorrection context if absent.

    Args:
        custom_file_path:
            Custom file to include. A relative path is interpreted relative to
            the AutoCorrect2 project directory.
        project_dir:
            AutoCorrect2 project directory.

    Returns:
        `True` if the source file was modified, or `False` if the include was
        already correctly present.

    Raises:
        FileNotFoundError:
            If AutoCorrect2's main source file does not exist.
        ValueError:
            If the path is invalid or cannot be represented safely.
        AutoCorrect2IntegrationError:
            If the expected include/context structure is ambiguous.
        OSError:
            If the source file cannot be read or written.
    """
    custom_file_path = Path(custom_file_path)
    project_dir = Path(project_dir)
    state = _inspect_include_state(custom_file_path, project_dir)
    if state.custom_include_index is not None:
        return False

    custom_path = _resolve_custom_file_path(custom_file_path, project_dir)
    include_path = _render_include_path(custom_path, state.source_path.parent)
    indentation = _hotif_indentation(state)
    newline = _detect_newline(state.lines)
    comment = (
        "; Library of custom hotstrings for auto-correction generated by the "
        "python package 'autocorrect2-hotstring-generation'."
    )
    include_line = f'{indentation}#Include "{include_path}" {comment}{newline}'

    lines = state.lines.copy()
    lines.insert(state.hotif_end, include_line)
    write_text(
        state.source_path,
        "".join(lines),
        encoding="utf-8-sig",
        create_parents=False,
    )
    return True

remove_custom_hotstring_include

remove_custom_hotstring_include(
    custom_file_path: str | Path, *, project_dir: str | Path
) -> bool

Remove a custom file from AutoCorrect2's autocorrection context if present.

Parameters:

Name	Type	Description	Default
custom_file_path	str | Path	Custom file whose include should be removed.	required
project_dir	str | Path	AutoCorrect2 project directory.	required

Returns:

Type	Description
bool	True if the source file was modified, or False if the include was
bool	already absent.

Raises:

Type	Description
FileNotFoundError	If AutoCorrect2's main source file does not exist.
ValueError	If the custom path refers to a protected integration source.
AutoCorrect2IntegrationError	If the expected include/context structure is ambiguous.
OSError	If the source file cannot be read or written.

Source code in hotstring\autocorrect2\integration.py

def remove_custom_hotstring_include(
    custom_file_path: str | Path,
    *,
    project_dir: str | Path,
) -> bool:
    """Remove a custom file from AutoCorrect2's autocorrection context if present.

    Args:
        custom_file_path:
            Custom file whose include should be removed.
        project_dir:
            AutoCorrect2 project directory.

    Returns:
        `True` if the source file was modified, or `False` if the include was
        already absent.

    Raises:
        FileNotFoundError:
            If AutoCorrect2's main source file does not exist.
        ValueError:
            If the custom path refers to a protected integration source.
        AutoCorrect2IntegrationError:
            If the expected include/context structure is ambiguous.
        OSError:
            If the source file cannot be read or written.
    """
    custom_file_path = Path(custom_file_path)
    project_dir = Path(project_dir)
    state = _inspect_include_state(custom_file_path, project_dir)
    if state.custom_include_index is None:
        return False

    lines = state.lines.copy()
    del lines[state.custom_include_index]
    write_text(
        state.source_path,
        "".join(lines),
        encoding="utf-8-sig",
        create_parents=False,
    )
    return True

_inspect_include_state

_inspect_include_state(
    custom_file_path: Path, project_dir: Path
) -> _IncludeState

Read and validate AutoCorrect2's include state for one custom file.

Source code in hotstring\autocorrect2\integration.py

def _inspect_include_state(custom_file_path: Path, project_dir: Path) -> _IncludeState:
    """Read and validate AutoCorrect2's include state for one custom file."""
    source_path = (project_dir / AUTOCORRECT2_MAIN_RELATIVE_PATH).resolve(strict=False)
    if not source_path.is_file():
        raise FileNotFoundError(f"AutoCorrect2 main source file was not found: {source_path}")

    custom_path = _resolve_custom_file_path(custom_file_path, project_dir)
    built_in_hotstrings_path = (project_dir / AUTOCORRECT_HOTSTRINGS_RELATIVE_PATH).resolve(
        strict=False
    )

    if _same_path(custom_path, source_path):
        raise ValueError("The custom include path cannot refer to AutoCorrect2.ahk itself.")
    if _same_path(custom_path, built_in_hotstrings_path):
        raise ValueError("The custom include path cannot refer to AutoCorrectHotstrings.ahk.")

    content = read_text(source_path, encoding="utf-8-sig")
    lines = content.splitlines(keepends=True)
    hotif_start, hotif_end = _find_autocorrection_hotif(lines, source_path)

    built_in_indices = _find_include_indices(
        lines,
        target_path=built_in_hotstrings_path,
        source_dir=source_path.parent,
    )
    if len(built_in_indices) != 1:
        raise AutoCorrect2IntegrationError(
            "Expected exactly one include of AutoCorrectHotstrings.ahk in "
            f"{source_path}, found {len(built_in_indices)}."
        )

    built_in_index = built_in_indices[0]
    if not hotif_start < built_in_index < hotif_end:
        raise AutoCorrect2IntegrationError(
            "AutoCorrectHotstrings.ahk is not included inside the expected "
            "#HotIf AutoCorrectionsActivelyRunning() context."
        )

    custom_indices = _find_include_indices(
        lines,
        target_path=custom_path,
        source_dir=source_path.parent,
    )
    if len(custom_indices) > 1:
        raise AutoCorrect2IntegrationError(
            f"Found {len(custom_indices)} includes of the custom file {custom_path}; "
            "exactly zero or one is allowed."
        )

    custom_include_index = custom_indices[0] if custom_indices else None
    if custom_include_index is not None and not (hotif_start < custom_include_index < hotif_end):
        raise AutoCorrect2IntegrationError(
            f"The custom file {custom_path} is included outside the expected "
            "#HotIf AutoCorrectionsActivelyRunning() context."
        )

    return _IncludeState(
        source_path=source_path,
        lines=lines,
        hotif_start=hotif_start,
        hotif_end=hotif_end,
        custom_include_index=custom_include_index,
    )

_find_autocorrection_hotif

_find_autocorrection_hotif(
    lines: list[str], source_path: Path
) -> tuple[int, int]

Return the start and end indices of the autocorrection #HotIf block.

Source code in hotstring\autocorrect2\integration.py

def _find_autocorrection_hotif(lines: list[str], source_path: Path) -> tuple[int, int]:
    """Return the start and end indices of the autocorrection `#HotIf` block."""
    starts = [
        index
        for index, line in enumerate(lines)
        if _TARGET_HOTIF_PATTERN.fullmatch(line.rstrip("\r\n")) is not None
    ]
    if len(starts) != 1:
        raise AutoCorrect2IntegrationError(
            "Expected exactly one '#HotIf AutoCorrectionsActivelyRunning()' "
            f"directive in {source_path}, found {len(starts)}."
        )

    start = starts[0]
    for index in range(start + 1, len(lines)):
        if _HOTIF_PATTERN.fullmatch(lines[index].rstrip("\r\n")) is not None:
            return start, index

    raise AutoCorrect2IntegrationError(
        "The '#HotIf AutoCorrectionsActivelyRunning()' context has no terminating "
        f"#HotIf directive in {source_path}."
    )

_find_include_indices

_find_include_indices(
    lines: list[str], *, target_path: Path, source_dir: Path
) -> list[int]

Return line indices whose static include resolves to target_path.

Source code in hotstring\autocorrect2\integration.py

def _find_include_indices(lines: list[str], *, target_path: Path, source_dir: Path) -> list[int]:
    """Return line indices whose static include resolves to `target_path`."""
    return [
        index
        for index, line in enumerate(lines)
        if (include_path := _parse_include_path(line, source_dir)) is not None
        and _same_path(include_path, target_path)
    ]

_parse_include_path

_parse_include_path(
    line: str, source_dir: Path
) -> Path | None

Resolve a static AutoHotkey include directive, if the line contains one.

Source code in hotstring\autocorrect2\integration.py

def _parse_include_path(line: str, source_dir: Path) -> Path | None:
    """Resolve a static AutoHotkey include directive, if the line contains one."""
    match = _INCLUDE_PATTERN.fullmatch(line.rstrip("\r\n"))
    if match is None:
        return None

    include_text = match.group(1) if match.group(1) is not None else match.group(2)
    if include_text is None:
        return None

    include_text = _OPTIONAL_INCLUDE_PREFIX_PATTERN.sub("", include_text.strip(), count=1)
    if not include_text or (include_text.startswith("<") and include_text.endswith(">")):
        return None

    include_text = include_text.replace("\\", os.sep).replace("/", os.sep)
    include_path = Path(include_text)
    if not include_path.is_absolute():
        include_path = source_dir / include_path

    return include_path.resolve(strict=False)

_resolve_custom_file_path

_resolve_custom_file_path(
    custom_file_path: Path, project_dir: Path
) -> Path

Resolve a caller-supplied custom path against the AutoCorrect2 project.

Source code in hotstring\autocorrect2\integration.py

def _resolve_custom_file_path(custom_file_path: Path, project_dir: Path) -> Path:
    """Resolve a caller-supplied custom path against the AutoCorrect2 project."""
    if not isinstance(custom_file_path, Path):
        raise TypeError(
            f"custom_file_path must be a pathlib.Path, not {type(custom_file_path).__name__}"
        )

    path = custom_file_path if custom_file_path.is_absolute() else project_dir / custom_file_path
    return path.resolve(strict=False)

_render_include_path

_render_include_path(
    target_path: Path, source_dir: Path
) -> str

Render a static include path relative to AutoCorrect2's main source file.

Source code in hotstring\autocorrect2\integration.py

def _render_include_path(target_path: Path, source_dir: Path) -> str:
    """Render a static include path relative to AutoCorrect2's main source file."""
    try:
        include_path = os.path.relpath(target_path, start=source_dir)
    except ValueError:
        include_path = str(target_path)

    include_path = include_path.replace("/", "\\")
    if '"' in include_path or "\n" in include_path or "\r" in include_path:
        raise ValueError(f"Custom include path cannot be represented safely: {target_path}")

    return include_path

_hotif_indentation

_hotif_indentation(state: _IncludeState) -> str

Return the indentation convention used inside the target #HotIf block.

Source code in hotstring\autocorrect2\integration.py

def _hotif_indentation(state: _IncludeState) -> str:
    """Return the indentation convention used inside the target `#HotIf` block."""
    for line in state.lines[state.hotif_start + 1 : state.hotif_end]:
        stripped = line.lstrip(" \t")
        if stripped and not stripped.startswith(";"):
            return line[: len(line) - len(stripped)]
    return "    "

_detect_newline

_detect_newline(lines: list[str]) -> str

Return the source file's existing newline convention.

Source code in hotstring\autocorrect2\integration.py

def _detect_newline(lines: list[str]) -> str:
    """Return the source file's existing newline convention."""
    for line in lines:
        if line.endswith("\r\n"):
            return "\r\n"
        if line.endswith("\n"):
            return "\n"
        if line.endswith("\r"):
            return "\r"
    return os.linesep

_same_path

_same_path(first: Path, second: Path) -> bool

Compare paths using Windows-style case-insensitive semantics.

Source code in hotstring\autocorrect2\integration.py

def _same_path(first: Path, second: Path) -> bool:
    """Compare paths using Windows-style case-insensitive semantics."""
    first_text = str(first.resolve(strict=False)).replace("\\", "/").casefold()
    second_text = str(second.resolve(strict=False)).replace("\\", "/").casefold()
    return first_text == second_text

AutoCorrect2 constants

constants

Define filesystem constants for the AutoCorrect2 integration.

AUTOCORRECT2_MAIN_RELATIVE_PATH module-attribute

AUTOCORRECT2_MAIN_RELATIVE_PATH: Final[Path] = Path(
    "Core/AutoCorrect2.ahk"
)

Relative path to AutoCorrect2's main script.

AUTOCORRECT_HOTSTRINGS_RELATIVE_PATH module-attribute

AUTOCORRECT_HOTSTRINGS_RELATIVE_PATH: Final[Path] = Path(
    "Core/AutoCorrectHotstrings.ahk"
)

Relative path to AutoCorrect2's main autocorrection hotstring source.

BOILERPLATE_HOTSTRINGS_RELATIVE_PATH module-attribute

BOILERPLATE_HOTSTRINGS_RELATIVE_PATH: Final[Path] = Path(
    "Core/PersonalHotstrings.ahk"
)

Relative path to AutoCorrect2's personal boilerplate hotstring source.

DATE_TOOL_HOTSTRINGS_RELATIVE_PATH module-attribute

DATE_TOOL_HOTSTRINGS_RELATIVE_PATH: Final[Path] = Path(
    "Includes/DateTool.ahk"
)

Relative path to AutoCorrect2's date-tool hotstring source.

REQUIRED_HOTSTRING_SOURCE_RELATIVE_PATHS module-attribute

REQUIRED_HOTSTRING_SOURCE_RELATIVE_PATHS: Final[
    tuple[Path, ...]
] = (
    AUTOCORRECT_HOTSTRINGS_RELATIVE_PATH,
    BOILERPLATE_HOTSTRINGS_RELATIVE_PATH,
    DATE_TOOL_HOTSTRINGS_RELATIVE_PATH,
)

Existing AutoCorrect2 files expected to contain static hotstrings.

GENERATED_HOTSTRINGS_RELATIVE_PATH module-attribute

GENERATED_HOTSTRINGS_RELATIVE_PATH: Final[Path] = Path(
    "Core/GeneratedHotstrings.ahk"
)

Project-owned generated include file appended by the writer.

OPTIONAL_HOTSTRING_SOURCE_RELATIVE_PATHS module-attribute

OPTIONAL_HOTSTRING_SOURCE_RELATIVE_PATHS: Final[
    tuple[Path, ...]
] = (GENERATED_HOTSTRINGS_RELATIVE_PATH,)

Additional active sources checked when they already exist.