{"id":6617,"library":"escapism","title":"Escapism","description":"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.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/jupyterhub/escapism","tags":["string manipulation","escaping","slugification","jupyter","url-safe","filename-safe"],"install":[{"cmd":"pip install escapism","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"symbol":"escape","correct":"from escapism import escape"},{"symbol":"unescape","correct":"from escapism import unescape"},{"symbol":"safe_slug","correct":"from escapism import safe_slug"}],"quickstart":{"code":"import escapism\nimport string\n\n# Reversible escaping\nescaped = escapism.escape('my string with spaces and /slashes!', escape_char='_')\nprint(f\"Escaped: {escaped}\") # Output: my_20string_20with_20spaces_20and_2Fslashes!\noriginal = escapism.unescape(escaped, escape_char='_')\nprint(f\"Unescaped: {original}\") # Output: my string with spaces and /slashes!\n\n# Escaping with custom safe characters and escape character\nsafe_chars = string.ascii_letters + string.digits + '@_-.+'\ncustom_escaped = escapism.escape('foø-bar@%!xX?', safe=safe_chars, escape_char=r'%')\nprint(f\"Custom Escaped: {custom_escaped}\") # Output: fo%C3%B8-bar@%25%21xX%3F\ncustom_original = escapism.unescape(custom_escaped, escape_char=r'%')\nprint(f\"Custom Unescaped: {custom_original}\") # Output: foø-bar@%!xX?\n\n# Lossy slug generation for unique, safe names (e.g., for Kubernetes)\n# safe_slug ensures validity and uniqueness (by hashing if needed)\nslug_name = escapism.safe_slug('My User Name With Special Chars & A Long Name That Needs To Be Shortened And Unique')\nprint(f\"Safe Slug: {slug_name}\")\n\nalready_safe_slug = escapism.safe_slug('simple-name-123')\nprint(f\"Already Safe Slug: {already_safe_slug}\") # Output: simple-name-123\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"1.1.0+"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}