typio 0.4
Typio: Make Your Terminal Type Like a Human
License: MIT
Requires Python: >=3.8
Keywords: terminal cli typing typewriter typing-effect console stdout ux


<div align="center">
<img src="https://github.com/sepandhaghighi/typio/raw/main/otherfiles/logo.png" width="320">
<h1>Typio: Make Your Terminal Type Like a Human</h1>
<br/>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/built%20with-Python3-green.svg" alt="built with Python3"></a>
<a href="https://github.com/sepandhaghighi/typio"><img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/sepandhaghighi/typio"></a>
<a href="https://badge.fury.io/py/typio"><img src="https://badge.fury.io/py/typio.svg" alt="PyPI version"></a>
<a href="https://codecov.io/gh/sepandhaghighi/typio"><img src="https://codecov.io/gh/sepandhaghighi/typio/graph/badge.svg?token=UPhwanwQVw"></a>
</div>			
				
## Overview	

<p align="justify">
Typio is a lightweight Python library that prints text to the terminal as if it were being typed by a human. It supports multiple typing modes (character, word, line, sentence, typewriter, and adaptive), configurable delays and jitter for natural variation, and seamless integration with existing code via a simple function or a decorator. Typio is designed to be minimal, extensible, and safe, making it ideal for demos, CLIs, tutorials, and storytelling in the terminal.
</p>

<table>
	<tr>
		<td align="center">PyPI Counter</td>
		<td align="center"><a href="http://pepy.tech/project/typio"><img src="http://pepy.tech/badge/typio"></a></td>
	</tr>
	<tr>
		<td align="center">Github Stars</td>
		<td align="center"><a href="https://github.com/sepandhaghighi/typio"><img src="https://img.shields.io/github/stars/sepandhaghighi/typio.svg?style=social&label=Stars"></a></td>
	</tr>
</table>



<table>
	<tr> 
		<td align="center">Branch</td>
		<td align="center">main</td>	
		<td align="center">dev</td>	
	</tr>
	<tr>
		<td align="center">CI</td>
		<td align="center"><img src="https://github.com/sepandhaghighi/typio/actions/workflows/test.yml/badge.svg?branch=main"></td>
		<td align="center"><img src="https://github.com/sepandhaghighi/typio/actions/workflows/test.yml/badge.svg?branch=dev"></td>
	</tr>
</table>

<table>
    <tr> 
        <td align="center">Code Quality</td>
        <td align="center"><a href="https://www.codefactor.io/repository/github/sepandhaghighi/typio"><img src="https://www.codefactor.io/repository/github/sepandhaghighi/typio/badge" alt="CodeFactor"></a></td>
        <td align="center"><a href="https://app.codacy.com/gh/sepandhaghighi/typio/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/e047db39052a4be2859f299dd7f7ce3c"></a></td>
    </tr>
</table>

## Installation		

### Source Code
- Download [Version 0.4](https://github.com/sepandhaghighi/typio/archive/v0.4.zip) or [Latest Source](https://github.com/sepandhaghighi/typio/archive/dev.zip)
- `pip install .`				

### PyPI

- Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
- `pip install typio==0.4`						


## Usage

### Function

Use `type_print` function to print text with human-like typing effects. You can control the typing speed, randomness, mode, and output stream.

#### Example

```python
from typio import type_print
from typio import TypeMode

type_print("Hello, world!")

type_print(
    "Typing with style and personality.",
    delay=0.06,
    jitter=0.02,
	end="\n",
    mode=TypeMode.ADAPTIVE,
)
```

You can also redirect the output to any file-like object:

```python
with open("output.txt", "w") as file:
    type_print("Saved with typing effects.", file=file)
```

#### Parameters

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `text` | `str` | Text to be printed | -- |
| `delay` | `float` | Base delay (seconds) between emitted units | `0.04` |
| `jitter` | `float` | Random delay variation (seconds) | `0` |
| `end` | `str` | Ending character(s) | `\n` |
| `mode` | `TypeMode \| Callable` | Typing mode (built-in or custom) | `TypeMode.CHAR` |
| `file` | `TextIOBase` | Output stream | `sys.stdout` |


#### Built-in Modes

| Mode | Description |
|------|-------------|
| `TypeMode.CHAR` | Emit text **character by character** |
| `TypeMode.WORD` | Emit text **word by word**, preserving whitespace |
| `TypeMode.LINE` | Emit text **line by line** |
| `TypeMode.SENTENCE` | Emit text character by character with **longer pauses after `.`, `!`, `?`** |
| `TypeMode.TYPEWRITER` | Emit text character by character with **longer pauses after newlines** |
| `TypeMode.ADAPTIVE` | Emit text with **adaptive delays** based on character type (spaces, punctuation, alphanumeric) |


### Decorator

Use the `@typestyle` decorator to apply typing effects to all `print` calls inside a function, without changing the function's implementation.

#### Example

```python
from typio import typestyle
from typio import TypeMode

@typestyle(delay=0.05, mode=TypeMode.TYPEWRITER)
def intro():
    print("Welcome to Typio.")
    print("Every print is typed.")

intro()
```

#### Parameters

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `delay` | `float` | Base delay (seconds) between emitted units | `0.04` |
| `jitter` | `float` | Random delay variation (seconds) | `0` |
| `mode` | `TypeMode \| Callable` | Typing mode (built-in or custom) | `TypeMode.CHAR` |

### Custom Mode

Typio also allows defining custom typing modes.

A custom mode is a callable that receives a typing context and the text being printed.

#### Example

This custom mode, named `dramatic`, adds exaggerated pauses after punctuation to create a dramatic typing effect.

```python
from typio import TypioContext

def dramatic(ctx: TypioContext, text: str):
    for ch in text:
        ctx.emit(ch)
        if ch in ".!?":
            ctx.sleep(delay=ctx.delay * 6)
```

Usage with `type_print` function:

```python
type_print(
    "Wait... what?!",
    mode=dramatic,
    delay=0.05,
    jitter=0.02,
)
```

Usage with `@typestyle` decorator:

```python
@typestyle(delay=0.06, mode=dramatic)
def demo():
    print("This is serious.")
    print("Very serious!")

demo()
```

#### Parameters

This table describes the `TypioContext` API, which is the interface exposed to custom typing modes for emitting text, controlling timing, and accessing delay settings.

| Name | Type | Description |
|------|------|-------------|
| `emit(text)` | `method` | Emit a text fragment using typing effects |
| `sleep(delay=None, jitter=None)` | `method` | Pause execution with optional delay and jitter override |
| `flush()` | `method` | Flush the underlying output stream |
| `delay` | `property` | Base delay in seconds |
| `jitter` | `property` | Jitter value in seconds |


### CLI

Typio provides a simple command line interface for printing text with typing effects.

#### Example

```console
> typio --text="Hello world!" --mode=typewriter --delay=0.03
```


## Issues & Bug Reports			

Just fill an issue and describe it. We'll check it ASAP!

- Please complete the issue template

## Show Your Support
								
<h3>Star This Repo</h3>					

Give a ⭐️ if this project helped you!

<h3>Donate to Our Project</h3>	

<h4>Bitcoin</h4>
1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy
<h4>Ethereum</h4>
0xcD4Db18B6664A9662123D4307B074aE968535388
<h4>Litecoin</h4>
Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ
<h4>Doge</h4>
DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh
<h4>Tron</h4>
TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7
<h4>Ripple</h4>
rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq
<h4>Binance Coin</h4>
bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef
<h4>Tether</h4>
0xcD4Db18B6664A9662123D4307B074aE968535388
<h4>Dash</h4>
Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s
<h4>Stellar</h4>		
GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL
<h4>Zilliqa</h4>
zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5
<h4>Coffeete</h4>
<a href="http://www.coffeete.ir/opensource">
<img src="http://www.coffeete.ir/images/buttons/lemonchiffon.png" style="width:260px;" />
</a>


# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [Unreleased]
## [0.4] - 2026-02-19
### Added
- Command line interface
### Changed
- `_emit` method modified
- `README.md` updated
- Test system modified
## [0.3] - 2026-02-11
### Added
- `TypioContext` class
### Changed
- Test system modified
- `README.md` updated
- `_TypioPrinter` class all attributes changed to private
- `_emit` method modified
- `_sleep` function modified
## [0.2] - 2026-02-04
### Changed
- `README.md` updated
- `end` parameter added to `type_print` function
- Test system modified
## [0.1] - 2026-01-31
### Added
- `type_print` function
- `typestyle` decorator
- `CHAR` mode
- `WORD` mode
- `LINE` mode
- `SENTENCE` mode
- `TYPEWRITER` mode
- `ADAPTIVE` mode

[Unreleased]: https://github.com/sepandhaghighi/typio/compare/v0.4...dev
[0.4]: https://github.com/sepandhaghighi/typio/compare/v0.3...v0.4
[0.3]: https://github.com/sepandhaghighi/typio/compare/v0.2...v0.3
[0.2]: https://github.com/sepandhaghighi/typio/compare/v0.1...v0.2
[0.1]: https://github.com/sepandhaghighi/typio/compare/750c00e...v0.1