Escapism

Warnings

• breaking The `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.
• gotcha If 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)`.
• gotcha The 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`.

Install

• pip install escapism Install with pip

Imports

• escape

  from escapism import escape

• unescape

  from escapism import unescape

• safe_slug

  from escapism import safe_slug

Quickstart

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