Escapers

Escapers for CSV, Markdown, XML, HTML, JSON and URL, each verified against a real parser

Overview

Text that came from somewhere else — a name, a status, a free-text reason — cannot be dropped into a document as it stands. A comma reshapes a CSV row, a pipe splits a Markdown table cell, an unescaped quote ends an HTML attribute early and starts whatever follows it. An escaper takes such a value and returns one that embeds at a specific place in a specific format without changing the document's structure.

There is no general "escaped string": a value is escaped for somewhere. The same name that is safe inside a Markdown code span breaks a CSV row, and the same value quoted for CSV is meaningless inside an XML attribute. So each escaper here names the position it is for and is correct there and nowhere else. Two escapers are never applied to the same value for extra safety; where a document genuinely contains another, they nest once per layer.

Every escaper accepts any value whose str() succeeds — None included — and returns a string that can be written as UTF-8. Each is verified by round-tripping a hostile value through a real parser for its format, in the position a consumer would use it, rather than by reading the specification.

Installation

pip install vcti-escapers

In requirements.txt

vcti-escapers>=1.0.0

In pyproject.toml dependencies

dependencies = [
    "vcti-escapers>=1.0.0",
]

Quick Start

from vcti.escapers import csv_field, html_attribute, json_string, xml_text

csv_field("failed, retried")  # '"failed, retried"'
csv_field(138.0)  # '138.0'  — numbers stay bare
xml_text("a & b")  # 'a & b'
html_attribute('" onclick="')  # '" onclick="'
json_string("</script>")  # '"\\u003c/script\\u003e"'

Every escaper takes any value whose str() succeeds, None included. What absence looks like is the target's decision, so each escaper documents its own answer.

csv_field(None)      # ''    — an empty field
json_string(None)    # '""'  — an empty JSON string, since null is not one

The escapers

They form one flat pool, grouped here by format for finding rather than because a format owns them.

A format appears more than once because a format needs different escaping in different positions — that distinction is the point, and picking the wrong one is the mistake this package exists to prevent. Read each escaper's docstring before first use; several carry limits that matter.

Two worth knowing up front:

• html_attribute is for ordinary attributes. An event handler (onclick), a URL attribute (href, src) or style needs more than escaping — a perfectly escaped javascript: URL still runs.
• Escapers do not chain for extra safety. They nest, once per layer, when a document genuinely contains another — see docs/patterns.md.

Using them with a template engine

Escapers are plain functions, so they register wherever a template engine takes callables. Nothing here depends on a template engine or knows one exists.

from vcti.escapers import csv_field, markdown_code

filters = {"csv_field": csv_field, "markdown_code": markdown_code}
# Jinja2:  environment.filters.update(filters)

Registered under their own names, they read the same in a template as in Python — {{ item.name | csv_field }}.

Dependencies

None.

Documentation