telegram-escape 0.3.0

Escape text for Telegram's MarkdownV2 format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# telegram-escape

A Rust library for escaping text according to Telegram's MarkdownV2 formatting rules, with Python bindings.

## Overview

This library provides the `tg_escape` function that properly escapes special characters in text for use with Telegram Bot API's MarkdownV2 parse mode. It intelligently handles different escaping rules for regular text versus code blocks/inline code.

Available as both a Rust crate and a Python package (via [PyO3](https://pyo3.rs/)).

## Features

- Escapes special characters according to [Telegram MarkdownV2 rules](https://core.telegram.org/bots/api#formatting-options)
- Smart context-aware escaping:
  - In regular text: escapes `_*[]()~`>#+-=|{}.!\` characters
  - In code blocks and inline code: only escapes `` ` `` and `\` characters
- Preserves markdown structure while ensuring proper escaping
- Uses `pulldown-cmark` for robust markdown parsing

## Python Usage

Requires Python 3.13+.

### Installation

```bash
# With uv
uv add telegram-escape

# With pip
pip install telegram-escape
```

To install from source (requires Rust toolchain):

```bash
# With uv
uv pip install .

# With pip
pip install .
```

### Example

```python
from telegram_escape import tg_escape

# Basic escaping
escaped = tg_escape("Check /get_stat command :)")
# Result: "Check /get\\_stat command :\\)"

# Code blocks have different escaping rules
escaped = tg_escape("Before `a_*~>#+-=|{}.!\\` after")
# Inside backticks, only ` and \ are escaped
```

### Type Checking

The package ships with PEP 561 type stubs, so `tg_escape` is fully typed out of the box.

## Rust Usage

```rust
use telegram_escape::tg_escape;

let text = "Soon you'll get a stats for today, and the overall status can be viewed by the /get_stat command :)";
let escaped = tg_escape(text);
```

### Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
telegram-escape = "0.1.0"
```

## Testing

```bash
# Rust tests
cargo test

# Python (after installing in a venv)
python -c "from telegram_escape import tg_escape; print(tg_escape('hello_world'))"
```

**Note:** Some Rust tests are currently marked as `#[ignore]` due to failing edge cases:
- `test_escaped_characters` - handling of already-escaped characters
- `test_math_expressions` - mathematical operators escaping

## Dependencies

### Rust
- `pulldown-cmark` - Markdown parsing
- `pulldown-cmark-to-cmark` - Markdown serialization (using custom fork)
- `regex` - Pattern matching for escape characters

### Python build
- `maturin` - Build backend (PEP 517 compliant, works with pip/uv/any standard tool)
- `pyo3` - Rust ↔ Python bindings

## License

See LICENSE file for details.

## Author

Vlad Stepanov <utterstep@hey.com>