Registry / serialization / escapism

escapism

JSON →
library1.1.0pypypi✓ verified 86d ago

Escapism is a Python library providing a simple, generic API for escaping strings. It offers functions for reversible escaping, ideal for preserving string content across systems, and a 'safe_slug' API for creating unique, URL-safe or filesystem-safe strings which are not necessarily reversible. The current version is 1.1.0, and it is part of the Project Jupyter ecosystem, with development continuing as needed.

pip install escapism
INSTALL
IMPORT
SIG · ESCAPISM
E
escapism
serializationpythonv1.1.0
Install
1.7s avg
Import
10ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.010s · 17.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.7s · import 0.010s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

escape
from escapism import escape
unescape
from escapism import unescape
safe_slug
from escapism import safe_slug

This quickstart demonstrates the core functionalities: `escape` for reversible encoding/decoding, `unescape` to revert `escape` operations, and `safe_slug` for creating valid, unique, and often lossy identifiers suitable for system names like Kubernetes object names or filenames. It shows how to customize safe characters and escape characters for precise control.

import escapism import string # Reversible escaping escaped = escapism.escape('my string with spaces and /slashes!', escape_char='_') print(f"Escaped: {escaped}") # Output: my_20string_20with_20spaces_20and_2Fslashes! original = escapism.unescape(escaped, escape_char='_') print(f"Unescaped: {original}") # Output: my string with spaces and /slashes! # Escaping with custom safe characters and escape character safe_chars = string.ascii_letters + string.digits + '@_-.+' custom_escaped = escapism.escape('foø-bar@%!xX?', safe=safe_chars, escape_char=r'%') print(f"Custom Escaped: {custom_escaped}") # Output: fo%C3%B8-bar@%25%21xX%3F custom_original = escapism.unescape(custom_escaped, escape_char=r'%') print(f"Custom Unescaped: {custom_original}") # Output: foø-bar@%!xX? # Lossy slug generation for unique, safe names (e.g., for Kubernetes) # safe_slug ensures validity and uniqueness (by hashing if needed) slug_name = escapism.safe_slug('My User Name With Special Chars & A Long Name That Needs To Be Shortened And Unique') print(f"Safe Slug: {slug_name}") already_safe_slug = escapism.safe_slug('simple-name-123') print(f"Already Safe Slug: {already_safe_slug}") # Output: simple-name-123
Debug
Known issues
breakingThe `safe_slug` function (added in version 1.1) is inherently lossy and not designed for round-trip conversion. It prioritizes creating valid and unique identifiers for contexts like filenames or URLs by transforming/hashing input strings, which means the original string cannot be recovered.
fix
Do not attempt to `unescape` strings produced by `safe_slug`. Use `escape` and `unescape` for reversible encoding/decoding, and `safe_slug` only when a canonical, safe, and unique representation is needed.
affects: 1.1.0+
gotchaIf you use a non-default `escape_char` when calling `escapism.escape()`, you *must* provide the same `escape_char` to `escapism.unescape()` to correctly reverse the operation. Failing to do so will result in an incorrect or incomplete unescaping.
fix
Always pass the `escape_char` argument to `unescape()` if you customized it during the `escape()` call. Example: `escapism.unescape(escaped_string, escape_char=my_char)`.
affects: All
gotchaThe default set of 'safe' characters for `escapism.escape()` includes ASCII letters and numbers. Other characters will be escaped. For `escapism.safe_slug()`, the default `is_valid` callable applies strict Kubernetes-like rules, requiring lowercase ASCII letters, numbers, and hyphens, starting with a letter and ending with a letter or number, and a length between 1 and 63.
fix
Always review the default `safe` characters or `is_valid` rules. If your use case requires different characters to remain unescaped or different validity constraints for slugs, provide custom `safe` (for `escape`) or `is_valid` (for `safe_slug`) arguments. For `safe_slug`, you can also provide `max_length` and `slug_char`.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'escapism'
The 'escapism' library is not installed in your Python environment or there's a problem with the Python path.
fix
Install the library using pip: `pip install escapism`
AttributeError: module 'escapism' has no attribute 'escape_string'
You are trying to call a function (e.g., 'escape_string') that does not exist within the 'escapism' module, or you have misspelled an existing function name.
fix
Ensure you are using the correct function names as defined in the library, such as `escapism.escape()` or `escapism.safe_slug()`.
TypeError: 'safe' argument must be a string or set of characters
The `safe` argument passed to `escapism.escape()` is not of type `str` or `set`.
fix
Provide the `safe` argument as a string containing allowed characters or a set of characters. For example, `escapism.escape('my string', safe='abc')` or `escapism.escape('my string', safe={'a', 'b', 'c'})`.
TypeError: escape_char must be a single character string
The `escape_char` argument passed to `escapism.escape()` or `escapism.unescape()` is not a single character string.
fix
Ensure the `escape_char` argument is a string with exactly one character. For example, `escapism.escape('my string', escape_char='_')`.
ValueError: escape_char cannot be a safe character
The character specified for `escape_char` is also present in the `safe` set of characters, which would lead to ambiguity during escaping/unescaping.
fix
Choose an `escape_char` that is not included in the `safe` string or set of characters you provide to `escapism.escape()`.
Upgrade
Version history
1.1.0latest on PyPI · released Dec 11, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
Agent activity
16 hits · last 30 days
node
12
Amazon
2
Resources
escapism — pip install escapism · libregistry