Migrating from pathvalidate¶

translit's sanitize_filename() replaces pathvalidate for filename sanitization use cases.

Quick migration¶

# Before
from pathvalidate import sanitize_filename

# After
from translit import sanitize_filename

API comparison¶

pathvalidate	translit	Notes
`sanitize_filename(s)`	`sanitize_filename(s)`	Same function name
`sanitize_filepath(s)`	Not available	translit handles filenames only
`validate_filename(s)`	Not available	translit sanitizes rather than validates
`validate_filepath(s)`	Not available
`is_valid_filename(s)`	Not available

Parameter mapping¶

# pathvalidate — these work directly in translit (compatibility aliases)
sanitize_filename("my<file>.txt", replacement_text="_")  # accepted
sanitize_filename("my<file>.txt", max_len=100)           # accepted

# translit native names
sanitize_filename("my<file>.txt", separator="_")
sanitize_filename("my<file>.txt", max_length=100)

# platform values are lowercase in translit
sanitize_filename("my<file>.txt", platform="windows")  # not "Windows"

pathvalidate parameter	translit parameter	Notes
`replacement_text`	`separator`	Both accepted — `replacement_text` maps to `separator`
`platform`	`platform`	Values are lowercase in translit
`max_len`	`max_length`	Both accepted — `max_len` maps to `max_length`
—	`lang`	New: language-aware transliteration
—	`preserve_extension`	New: protect file extension during truncation

New features in translit¶

Unicode transliteration¶

pathvalidate strips or replaces non-ASCII characters. translit transliterates them:

# pathvalidate
from pathvalidate import sanitize_filename
sanitize_filename("café résumé.pdf")  # => "caf rsm.pdf" (stripped)

# translit
from translit import sanitize_filename
sanitize_filename("café résumé.pdf")  # => "cafe_resume.pdf" (transliterated)

Language-aware filenames¶

from translit import sanitize_filename

sanitize_filename("Ärger.txt", lang="de")  # => "Aerger.txt"
sanitize_filename("Ärger.txt")             # => "Arger.txt"

Extension preservation¶

from translit import sanitize_filename

sanitize_filename("very_long_name.pdf", max_length=15, preserve_extension=True)
# => "very_long_.pdf"  (extension preserved)

What's not covered¶

translit focuses on filename sanitization. pathvalidate also provides:

File path sanitization (sanitize_filepath) — translit handles filenames only, not full paths
Validation (validate_filename, is_valid_filename) — translit sanitizes rather than validates

If you need path sanitization or validation, you may need to keep pathvalidate for those specific functions.