API Reference

Package (typytypy)

TypyTypy — A Bespoke Character-by-Character Text Printer.

A utility Python library which provides for a realistic, “real-time typing” simulation with highly configurable implementations. It features a flexible API for both simple and advanced use, quick-use “character personality” presets, and granular timing control for creating custom text presentations with authentic temporal dynamics.

Born of the KitschCode philosophy of applying meticulous craftsmanship to humble functionality.

Classes:

PrintingPress: Main character-by-character text printer class.

Examples

Basic usage:

>>> import typytypy
...
>>> typytypy.type_out("Hello, World!")

Using “character personality” presets:

>>> nervous = typytypy.use_preset('nervous')
...
>>> nervous.type_out("Um, hello there...")

Advanced instance management (full functionality; recommended approach):

>>> printer = typytypy.PrintingPress()
...
>>> printer.create_profile("highlight", 0.1, 0.05, "IMPORTANT")
...
>>> printer.type_out("This is IMPORTANT information!")

Metadata:

Author: KitscherEins, Version: 0.1.0, License: Apache-2.0

typytypy.get_available_presets() → _PresetCollection

List all predefined timing presets with their configuration details.

This function retrieves all predefined timing presets and returns them in a formatted collection. Each preset includes both ‘base_delay’ and ‘delay_range’ values, visually formatted for human readability.

The returned collection maintains full dictionary compatibility, allowing users to check preset availability using standard membership testing (e.g. ‘in’, ‘for’, etc.) while providing clean, formatted output, in list format, when printed.

Returns:

A formatted dictionary of preset names and their timing

configurations, with lowercase preset names as keys.

Return type:

_PresetCollection

Examples

Displaying all presets:

>>> print(typytypy.get_available_presets())
Available presets:
 - default: (base_delay: 0.015s, delay_range: 0.042s)
 - emphasis: (base_delay: 0.031s, delay_range: 0.099s)
 ...

Extending use-case of preset availablity:

>>> presets = typytypy.get_available_presets()
>>> if 'nervous' in presets:
...     print("I can use this to do something more... maybe?")

typytypy.type_out(text: str, base_delay: float | None = None, delay_range: float | None = None) → None

Print text to stdout one character at a time, simulating real-time typing.

Renders the given text in real time, inserting calculated delays between printed characters. Stdout is flushed after printing each character for immediate display.

All original formatting (spacing, punctuation, and line breaks) is preserved.

Provides direct access to TypyTypy’s core functionality without requiring class instantiation.

Parameters:

• text (str) – The text to print.

• base_delay (float | None) – Overide (optional) for the session minimum delay per character, in seconds.

• delay_range (float | None) – Override (optional) for the session delay range, in seconds.

Returns:

None.

Raises:

InvalidTimingError – If invalid timing values are provided.

Examples

General use:

>>> typytypy.type_out("Hello, World!")

With custom timings:

>>> typytypy.type_out("HeLlO, WoRlD!",
...                   base_delay=0.05, delay_range=0.50)

typytypy.use_preset(preset_name: str) → _PresetPrinter

Create a limited PresetPrinter instance using a predefined timing configuration.

This function returns a ‘_PresetPrinter’ instance that only exposes the ‘type_out()’ functionality. It facilitates the quick application of preconfigured “character personality” styles without need for managing full ‘PrintingPress’ instances.

Parameters:

preset_name (str) – Name of the timing preset to use. Case-insensitive. To check valid options, use ‘get_available_presets()’.

Returns:

A printer instance configured with the specified preset.

Return type:

_PresetPrinter

Raises:

ValueError – If preset_name is not recognized.

Examples

Using multiple typing presets:

>>> nervous = typytypy.use_preset('nervous')
>>> confident = typytypy.use_preset('confident')
...
>>> nervous.type_out("Um, hello there...")
>>> confident.type_out("Good morning, team!")

Core Module

Core functionality for TypyTypy.

This module defines the ‘PrintingPress’ class, which implements the library’s main character-by-character text rendering engine. It provides configurable timing control, word-level profiles, and case-sensitivity options, serving as the beating heart of TypyTypy.

Classes:

PrintingPress: Main character-by-character text printer class.

Examples

Basic usage:

>>> import typytypy
...
>>> printer = typytypy.PrintingPress()
...
>>> printer.type_out("Hello, World!")

With timing profiles:

>>> printer.create_profile("highlight", 0.1, 0.05, "IMPORTANT")
...
>>> printer.type_out("This is IMPORTANT information!")

Metadata:

Author: KitscherEins, Version: 0.1.0, License: Apache-2.0

class typytypy.core.PrintingPress(base_delay: float | None = None, delay_range: float | None = None)

Bases: object

Character-by-character text printer engine with custom timing profile support.

This class prints text to stdout character-by-character, simulating real-time typing. It supports configurable timing parameters and custom timing profiles that override default timings for specific words or phrases.

base_delay

Default minimum delay per character, in seconds.

Type:

float

delay_range

Default random delay range, in seconds.

Type:

float

profiles

Mapping of profile names to profile data.

Type:

dict[str, _ProfileData]

word_to_profile

Mapping of normalized words to their assigned profile name.

Type:

dict[str, str]

normalized_to_original

Mapping of normalized words to their original form for case-sensitivity restoration.

Type:

dict[str, str]

case_sensitive_setting

True if profile word matching is case-sensitive.

Type:

bool

Examples

Basic initialization:

>>> printer = PrintingPress()
...
>>> printer.type_out("Hello, World!")

Custom timing:

>>> printer = PrintingPress(base_delay=0.1, delay_range=0.2)
...
>>> printer.type_out("Slow typing...")

Timing profiles:

>>> printer.create_profile("fast", 0.01, 0.005, "URGENT")
...
>>> printer.type_out("This is URGENT!")

DEFAULT_BASE_DELAY = 0.015

DEFAULT_DELAY_RANGE = 0.042

EMPHASIS_BASE_DELAY = 0.0314

EMPHASIS_DELAY_RANGE = 0.0985

add_words_to_profile(profile_name: str, words: str | list[str]) → int

Add word(s) to an existing custom timing profile.

Words are validated according to the active case-sensitivity setting (default=True), and duplicates (based on those rules) are not allowed. If a word already exists in another profile, it will be automatically transferred to the target profile.

Parameters:

• profile_name (str) – Name of the existing custom timing profile to add words to.

• words (str | list[str]) – Word(s) to add (single string or list). Matching is case-sensitive or case-insensitive based on the instance’s case-sensitivity setting.

Returns:

The number of words successfully added to the profile.

Return type:

int

Raises:

ProfileError – If the profile does not exist or if adding the words would violate duplicate rules under the current case-sensitivity setting.

Examples

Add a single word:

>>> count = printer.add_words_to_profile("emotions", "happy")
>>> print(count)  # 1

Add multiple words:

>>> count = printer.add_words_to_profile("emotions", ["happy", "sad"])
>>> print(count)  # 2

create_profile(profile_name: str, base_delay: float, delay_range: float, words: str | list[str] | None = None) → bool

Create a new custom timing profile with the specified parameters.

A custom timing profile defines a base_delay and delay_range that override the printer’s defaults for a specific set of words. If initial words are provided, they are added to the profile immediately after creation.

Parameters:

• profile_name (str) – Unique name for the custom timing profile. If a profile with the same name already exists, creation fails.

• base_delay (float) – Minimum delay per character, in seconds, for words in this profile.

• delay_range (float) – Random delay range, in seconds, for words in this profile.

• words (str | list[str] | None) – Initial word(s) to add to the profile (optional). Can be a single word string, list of words, or None.

Returns:

True if the profile was created successfully, False if a profile with

the given name already exists.

Return type:

bool

Raises:

InvalidTimingError – If invalid timing values are provided.

Examples

Create empty profile:

>>> printer.create_profile("emotions", 0.08, 0.12)
True

Create profile with initial word:

>>> printer.create_profile("calm", 0.1, 0.015, "holistic")
True

Create profile with multiple initial words:

>>> printer.create_profile("fast", 0.01, 0.005, ["CLEAR", "UNDERSTAND"])
True

delete_profile(profile_name: str) → bool

Delete an entire custom timing profile and remove all associated mappings.

Permanently removes the specified profile from the printer instance. It also cleans up all associated words from the ‘word_to_profile’ and ‘normalized_to_original’ lookup mappings using the current case-sensitivity rules.

Parameters:

profile_name (str) – Name of the custom timing profile to delete.

Returns:

True if the profile existed and was deleted successfully, False if no

such profile exists.

Return type:

bool

Examples

>>> success = printer.delete_profile("profile_omega")
>>> print(success)  # True if profile existed, False otherwise

get_profile_info(profile_name: str) → dict[str, float | int | list[str]] | None

Return detailed information about a custom timing profile.

If the profile exists, returns its configuration and current words. If no matching profile is found, returns None.

Parameters:

profile_name (str) – Name of the custom timing profile.

Returns:

A dictionary containing the following keys, or None if the profile does not exist:

• base_delay (float): Minimum delay per character, in seconds, for

  words in this profile.

• delay_range (float): Random delay range, in seconds, for words in this

  profile.

• word_count (int): Number of words currently assigned to the profile.

• words (list[str]): All words in the profile, in their original form.

Return type:

dict[str, float | int | list[str]] | None

Examples

Retrieve and inspect a profile:

>>> info = printer.get_profile_info("emotions")
>>> print(info)  # Full profile record
>>> print(info['word_count'])  # Number of words in profile

list_profiles() → list[str]

Return the names of all custom timing profiles in this printer instance.

Profiles are listed in the order they were added to the instance (insertion order). Result reflects profiles stored in memory for the current instance.

Returns:

A list of custom timing profile names, in insertion order.

Return type:

list[str]

Examples

>>> profiles = printer.list_profiles()
>>> print(profiles)  # ['emotions', 'technical', 'emphasis']

remove_words_from_profile(profile_name: str, words: str | list[str]) → int

Remove word(s) from an existing custom timing profile.

Any specified words that are found in the target profile are removed, and their entries are cleaned from the lookup mappings. Words that are not present in the profile are ignored.

Parameters:

• profile_name (str) – Name of the existing custom timing profile to remove words from.

• words (str | list[str]) – Word(s) to remove (single string or list). Matching is case-sensitive or case-insensitive based on the instance’s case-sensitivity setting.

Returns:

The number of words successfully removed from the profile.

Return type:

int

Raises:

ProfileError – If the profile does not exist.

Examples

Remove a single word:

>>> count = printer.remove_words_from_profile("emotions", "guilty")
>>> print(count)  # 1

Remove multiple words:

>>> count = printer.remove_words_from_profile("emotions",
...                                           ["angry", "guilty"])
>>> print(count)  # 2 if both existed

set_profile_case_sensitivity(sensitive: bool) → None

Configure the case-sensitivity setting for profile word matching.

Enables switching the instance’s word matching mode between case-sensitive and case-insensitive. Before applying a change, it analyzes all existing profiles to detect whether the new mode would cause conflicting normalized word mappings (e.g., “Apple” and “apple” would collide in case-insensitive mode).

If a switch is deemed safe, all internal lookup mappings are rebuilt to match the new case-sensitivity rules. If the target mode is the same as the current mode, no changes are made.

Parameters:

sensitive (bool) – True to enable case-sensitive matching, False to enable case-insensitive matching.

Raises:

ConfigurationError – If ‘sensitive’ is not a boolean, or if switching to the new mode would cause collisions in normalized word mappings.

Examples

Safe switch to case-insensitive mode:

>>> printer.set_profile_case_sensitivity(False)  # No conflicts

Unsafe switch with conflicts:

>>> printer.set_profile_case_sensitivity(False)
Traceback (most recent call last):
    ...
ConfigurationError: Cannot switch to case-insensitive mode: 1 word
collision(s) detected...

set_timing(base_delay: float, delay_range: float) → None

Update the default timing parameters for this printer instance.

Permanently changes the instance’s base delay and delay range values for all subsequent calls to ‘type_out()’, unless per-call overrides are provided. Both values are validated against the globally defined minimum and maximum timing limits.

Parameters:

• base_delay (float) – New minimum delay per character, in seconds.

• delay_range (float) – New random delay range, in seconds.

Raises:

InvalidTimingError – If invalid timing values are provided.

Examples

Set slower default typing speed:

>>> printer_one.set_timing(0.05, 0.02)

Set faster default typing speed:

>>> printer_two.set_timing(0.005, 0.01)

type_out(text: str, base_delay: float | None = None, delay_range: float | None = None) → None

Print text to stdout one character at a time, simulating real-time typing.

Renders the given text in real time, inserting calculated delays between printed characters. Words in custom timing profiles use their configured timing, while other words and whitespace use the provided or the instance’s default timing parameters. Stdout is flushed after printing each character for immediate display.

All original formatting (spacing, punctuation, and line breaks) is preserved.

Parameters:

• text (str) – The text to print.

• base_delay (float | None) – Override (optional) for the instance minimum delay per character, in seconds, for non-profile words.

• delay_range (float | None) – Override (optional) for the instance random delay range, in seconds, for non-profile words.

Returns:

None.

Raises:

InvalidTimingError – If invalid timing values are provided.

Examples

Basic usage:

>>> printer.type_out("Hello, World!")

With per-call timing overrides:

>>> printer.type_out("Fast message",
                     base_delay=0.01, delay_range=0.005)

With timing profiles:

>>> printer.create_profile("emphasis", 0.1, 0.05, "IMPORTANT")
...
>>> printer.type_out("This is IMPORTANT information!")

update_profile_timing(profile_name: str, base_delay: float, delay_range: float) → bool

Update the timing parameters for an existing custom timing profile.

Replaces the profile’s current ‘base_delay’ and ‘delay_range’ values with the specified ones, after validating that both are within the allowed limits.

Parameters:

• profile_name (str) – Name of the custom timing profile to update.

• base_delay (float) – New minimum delay per character, in seconds.

• delay_range (float) – New random delay range, in seconds.

Returns:

True if the profile exists and was updated successfully, False if no

profile with the given name exists.

Return type:

bool

Raises:

InvalidTimingError – If invalid timing values are provided.

Examples

Update an existing profile’s timings:

>>> success = printer.update_profile_timing("emotions", 0.1, 0.05)
>>> print(success)  # True if profile exists

Exceptions Module

Custom exception classes for TypyTypy.

This module defines all TypyTypy-specific exceptions, providing clear error categories for precise handling and debugging across the library.

Classes:

PrintingPressError: Base exception for all TypyTypy errors. InvalidTimingError: Raised when timing parameters are invalid. ProfileError: Raised when timing profile operations fail. ConfigurationError: Raised when configuration values are invalid.

Examples

Basic exception handling:

>>> try:
...     printer = PrintingPress(base_delay=-1.0)
... except InvalidTimingError as e:
...     print(f"Invalid timing: {e}")

Metadata:

Author: KitscherEins, Version: 0.1.0, License: Apache-2.0

exception typytypy.exceptions.ConfigurationError(message: str, setting_name: str | None = None, setting_value: str | int | float | bool | None = None, expected_type: type | None = None)

Bases: PrintingPressError

Raised when configuration values are invalid or incompatible.

This exception is thrown when configuration settings are malformed, contain invalid combinations, or fail validation checks.

message

Human-readable error description.

Type:

str

setting_name

Name of the configuration setting that failed.

Type:

str | None

setting_value

The invalid value that was provided.

Type:

ConfigValue | None

expected_type

Expected type for the configuration setting, or None if not type-constrained.

Type:

type | None

Examples

Setting case-sensitivity with the wrong type:

>>> try:
...     printer = PrintingPress()
...     printer.set_profile_case_sensitivity("invalid")
... except ConfigurationError as e:
...     print(f"Configuration error: {e}")

exception typytypy.exceptions.InvalidTimingError(message: str, parameter_name: str | None = None, parameter_value: float | None = None, valid_range: tuple[float, float] | None = None)

Bases: PrintingPressError

Raised when timing parameters are invalid or out of acceptable range.

This exception is thrown when ‘base_delay’ or ‘delay_range’ values do not meet the validation criteria for safe and reasonable typing simulation.

message

Human-readable error description.

Type:

str

parameter_name

Name of the invalid parameter.

Type:

str | None

parameter_value

The invalid value that was provided.

Type:

float | None

valid_range

Minimum and maximum acceptable values for the parameter.

Type:

tuple[float, float] | None

Examples

Negative delay:

>>> try:
...     printer = PrintingPress(base_delay=-0.5)
... except InvalidTimingError as e:
...     print(f"Timing error: {e}")

exception typytypy.exceptions.PrintingPressError(message: str, context: dict[str, str | int | float | bool | None] | None = None)

Bases: Exception

Base exception for all TypyTypy-specific errors.

All custom exceptions in the TypyTypy library inherit from this class. Catching ‘PrintingPressError’ will also catch any more TypyTypy-specific exceptions.

message

Human-readable error description.

Type:

str

context

Optional dictionary containing additional error context (e.g., parameter name, invalid value, etc.).

Type:

dict[str, ConfigValue] | None

Examples

Catch any TypyTypy-related exception:

>>> try:
...     # Some TypyTypy operation
...     pass
... except PrintingPressError as e:
...     print(f"PrintingPress error occurred: {e}")

exception typytypy.exceptions.ProfileError(message: str, profile_name: str | None = None, operation: str | None = None, word_count: int | None = None)

Bases: PrintingPressError

Raised when timing profile operations fail or encounter invalid states.

This exception covers errors in timing profile management, including attempts to operate on non-existent profiles, invalid word formats, or conflicting profile operations.

message

Human-readable error description.

Type:

str

profile_name

Name of the timing profile involved, or None if not applicable.

Type:

str | None

operation

The operation that failed (add, remove, create, etc.).

Type:

str | None

word_count

Number of words involved in the operation, or None.

Type:

int | None

Examples

Adding a word to a missing profile:

>>> printer = PrintingPress()
>>> try:
...     printer.add_words_to_profile("missing_profile", "word")
... except ProfileError as e:
...     print(f"Profile error: {e}")