smssafe

Turn arbitrary text into guaranteed GSM-7 deliverable SMS — no UCS-2 fallback.

A single non-GSM-7 character (a smart quote, an em-dash, a stray emoji) forces an entire SMS into UCS-2 encoding: 70 characters per segment instead of 160, triple the cost, and silent delivery failure on feature/dumb phones that can't render it.

smssafe sanitizes text before you send it — transliterating, replacing, or dropping every non-GSM-7 character while preserving as much meaning as possible.

• ✅ Zero dependencies — pure Python standard library, 3.10+
• ✅ Fully typed — ships py.typed (PEP 561)
• ✅ Homoglyph-aware — Cyrillic/Greek/full-width lookalikes are transliterated, not dropped
• ✅ Accurate segment & cost accounting (extended chars correctly counted as 2)
• ✅ Deterministic, side-effect-free, full audit trail of every change

Install

pip install smssafe

Usage

from smssafe import sanitize

result = sanitize("Hi — “there”, pay ~5,000 now… 🙂")

result.sanitized          # 'Hi - "there", pay ~5,000 now...'
result.encoding           # 'gsm7'
result.char_count         # encoded length (extended chars count as 2)
result.segments           # number of SMS parts
result.replacements       # list[dict] — audit trail of every substitution
result.remaining_unsafe   # list[str] — chars that could not be mapped (dropped)
result.is_clean           # True if no changes were needed

What it handles

Tilde: ~ is a GSM-7 extended character (escape 0x3D, costs 2 septets), so it passes through unchanged — ~5,000 stays ~5,000 rather than becoming a misleading -5,000. Non-ASCII tilde lookalikes (˜ ∼ ～) normalise to ~.

Drop vs. replace unknowns

By default, characters with no safe mapping are dropped. Pass drop_unknown=False to replace them with ? instead:

sanitize("A中B", drop_unknown=False).sanitized   # 'A?B'

How it works

A deterministic 8-step pipeline (smssafe.core), each step independently testable:

0. Strip non-BMP / surrogate codepoints (emoji, math-alphanumerics)
1. Apply the homoglyph map (Cyrillic/Greek/full-width → Latin)
2. Apply the explicit replacement map (quotes, dashes, currency, symbols…)
3. NFD-normalize per character and strip diacritics for remaining accented chars
4. Normalize whitespace (tabs, exotic/zero-width spaces)
5. Collapse artifacts (runs of dashes/spaces)
6. Final GSM-7 scan — drop or ?-replace anything left
7. Compute encoding, character count (extended = 2), and segment count

Development

git clone https://github.com/BRIQ-BLOCK/smssafe
cd smssafe
pip install -e ".[dev]"
pytest            # 689 tests
ruff check .
mypy

License

MIT © Eddie Gulay