Classes¶

Stateful objects and builders for repeated or specialized text processing.

Text¶

>>> from translit import Text
>>> Text("Straße").fold_case().value
'strasse'
>>> Text("  hello   world  ").collapse_whitespace().value
'hello world'
>>> str(Text("café").strip_accents())
'cafe'

value: str

normalize(*, form: NormalizationForm = 'NFC') -> Text

normalize_confusables(*, target_script: str = 'latin') -> Text

strip_accents() -> Text

transliterate(*, lang: str | None = None, target: str | None = None, errors: ErrorMode = 'replace', replace_with: str = '[?]', strict_iso9: bool = False, gost7034: bool = False) -> Text

fold_case() -> Text

collapse_whitespace(*, strip_control: bool = True, strip_zero_width: bool = True) -> Text

slugify(*, separator: str = '-', lowercase: bool = True, max_length: int = 0, word_boundary: bool = False, save_order: bool = False, stopwords: Iterable[str] = (), regex_pattern: str | None = None, replacements: Iterable[tuple[str, str]] = (), allow_unicode: bool = False, lang: str | None = None, entities: bool = True, decimal: bool = True, hexadecimal: bool = True) -> Text

sanitize_filename(*, separator: str = '_', max_length: int = 255, platform: Platform = 'universal', lang: str | None = None, preserve_extension: bool = True) -> Text

demojize(*, strip_modifiers: bool = False, errors: ErrorMode = 'replace', replace_with: str = '[?]', provider: EmojiProvider | None = None) -> Text

strip_bidi() -> Text

security_clean() -> Text

ml_normalize(*, lang: str | None = None, emoji: str = 'cldr') -> Text

display_clean() -> Text

is_ascii() -> bool

is_normalized(*, form: NormalizationForm = 'NFC') -> bool

is_confusable(*, target_script: str = 'latin') -> bool

is_mixed_script() -> bool

detect_scripts() -> list[Script]

grapheme_len() -> int

grapheme_split() -> list[str]

grapheme_truncate(max_graphemes: int) -> Text

catalog_key(*, lang: str | None = None, strict_iso9: bool = False) -> Text

Usage¶

from translit import Text

result = (
    Text("Ünïcödé Café ☕")
    .normalize("NFKC")
    .transliterate()
    .strip_accents()
    .fold_case()
    .value
)
# => "unicode cafe hot beverage"

Each transform method returns a new Text instance (immutable semantics, matching Python str). Predicates return their native type (bool, list) and do not chain.

Chainable transforms¶

All core transforms are available as methods:

Non-chaining predicates¶

Result extraction¶

Use .value or str() to extract the underlying string:

text = Text("café").strip_accents()
text.value   # => "cafe"
str(text)    # => "cafe"

Text supports ==, hash(), len(), and bool() — comparing against the underlying string value.

Slugifier¶

>>> s = Slugifier(separator="_", lang="de")
>>> s("Ärger im Büro")
'aerger_im_buero'

Usage¶

from translit import Slugifier

slug = Slugifier(separator="_", lang="de", max_length=50)
slug("Ärger im Büro")     # => "aerger_im_buero"
slug("Über den Wolken")   # => "ueber_den_wolken"

# Auto-detect language from script
auto_slug = Slugifier(lang="auto")
auto_slug("Москва")       # => "moskva" (detects Cyrillic → Russian)

Accepts all the same parameters as slugify(). Construct once, call many times.

UniqueSlugifier¶

>>> u = UniqueSlugifier()
>>> u("My Post")
'my-post'
>>> u("My Post")
'my-post-1'

reset() -> None

Usage¶

from translit import UniqueSlugifier

unique = UniqueSlugifier()
unique("My Post")   # => "my-post"
unique("My Post")   # => "my-post-1"
unique("My Post")   # => "my-post-2"

unique.reset()      # clear seen slugs
unique("My Post")   # => "my-post"

External uniqueness check¶

def exists_in_db(slug: str) -> bool:
    return db.slugs.filter(slug=slug).exists()

unique = UniqueSlugifier(check=exists_in_db)

The check callback is called for each candidate slug. If it returns True, the slugifier increments the suffix and tries again.

TextPipeline¶

>>> pipe = TextPipeline(normalize="NFC", fold_case=True, collapse_whitespace=True)
>>> pipe("  Héllo  WÖRLD  ")
'héllo wörld'

steps: list[tuple[str, str | None]]

>>> pipe = TextPipeline(normalize="NFC", fold_case=True)
>>> pipe.steps
[('normalize', 'NFC'), ('fold_case', None)]

explain() -> str

>>> pipe = TextPipeline(normalize="NFC", fold_case=True)
>>> print(pipe.explain())
TextPipeline with 2 steps:
  1. normalize (NFC)
  2. fold_case

Usage¶

from translit import TextPipeline

pipe = TextPipeline(
    normalize="NFC",
    confusables=True,
    strip_accents=True,
    fold_case=True,
    collapse_whitespace=True,
)

pipe("  Héllo Wörld  ")  # => "hello world"

Execution order¶

Operations execute in this fixed order regardless of construction order:

1. Normalize → 2. Confusables → 3. Demojize → 4. Strip accents → 5. Transliterate → 6. Fold case → 7. Collapse whitespace

Performance¶

The pipeline is pre-compiled at construction. Enabled steps are stored as a bitflag set — only enabled steps execute at call time.

Compatibility aliases (awesome-slugify)¶

These classes provide drop-in replacements for awesome-slugify's Slugify and UniqueSlugify. They accept awesome-slugify's parameter names and map them to native translit parameters.

See the migration guide for full details.

Slugify¶

from translit import Slugify
custom = Slugify(to_lower=True)
custom("Hello World")  # => "hello-world"

from translit import Slugify

# Same API as awesome-slugify
custom = Slugify(to_lower=True)
custom("Hello World")  # => "hello-world"

# Attribute-style configuration (awesome-slugify pattern)
s = Slugify()
s.to_lower = True
s.stop_words = ("the", "a")
s.max_length = 200
s("The Big Fox")  # => "big-fox"

Accepts both awesome-slugify parameter names (to_lower, stop_words, safe_chars, capitalize, pretranslate) and native translit names (lowercase, stopwords, replacements).

Defaults to to_lower=False (matching awesome-slugify). For python-slugify compatibility (which defaults to lowercase=True), use the native Slugifier class or the slugify() function.

UniqueSlugify¶

from translit import UniqueSlugify
unique = UniqueSlugify()
unique("My Post")   # => "My-Post"
unique("My Post")   # => "My-Post-1"

reset() -> None

from translit import UniqueSlugify

unique = UniqueSlugify(to_lower=True)
unique("My Post")   # => "my-post"
unique("My Post")   # => "my-post-1"

unique.reset()
unique("My Post")   # => "my-post"

Extends Slugify with uniqueness tracking. Accepts uids and unique_check parameters from awesome-slugify.

Preconfigured instances¶

Drop-in replacements for awesome-slugify's preconfigured slugifiers:

from translit import (
    slugify_url,       # lowercase, strips articles, max 200 chars
    slugify_filename,  # underscore separator, preserves -., max 255 chars
    slugify_unicode,   # keeps non-ASCII letters
    slugify_ru,        # Russian transliteration
    slugify_de,        # German transliteration (ä→ae, ö→oe, ü→ue)
    slugify_el,        # Greek transliteration
)

slugify_url("The Big Fox")        # => "big-fox"
slugify_de("Ärger im Büro")       # => "Aerger-im-Buero"
slugify_filename("My Report.pdf") # => "My_Report.pdf"