Skip to main content

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.

Format Escaper For
Markdown markdown_code An inline code span in prose — content shown literally, not obeyed
Markdown markdown_table_cell A code span in a GFM table cell, where | must also be escaped
CSV csv_field One RFC 4180 field; text quoted, numbers bare
XML xml_text Character data between tags
XML xml_attribute Inside an attribute (caller supplies the quotes)
HTML html_text Ordinary text content between tags
HTML html_attribute Inside a quoted ordinary attribute (caller supplies the quotes)
JSON json_string A string literal, quotes included, safe inside <script>
URL url_path_segment One path segment — a slash stays inside it
URL url_query_value One query parameter value, form-encoded

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

If you want to… Read
See practical, real-world usage docs/patterns.md
Understand the architecture and design decisions docs/design.md
Navigate and understand the source docs/source-guide.md
Add an escaper docs/extending.md

Metadata

Release files for vcti-escapers 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcti-escapers 1.0.0
File Size Uploaded Provenance Actions
vcti_escapers-1.0.0.tar.gz 31.5 kB With provenance Details for vcti_escapers-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-escapers 1.0.0
File Interpreter ABI Platform Actions
vcti_escapers-1.0.0-py3-none-any.whl Python 3 none any Details for vcti_escapers-1.0.0-py3-none-any.whl

Total release size: 50.8 kB

Release files / vcti_escapers-1.0.0.tar.gz

Download URL vcti_escapers-1.0.0.tar.gz
Size 31.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0d9e371eb1f5f6f0fec175afdb42a4f104e32ab3a5255b50b1736daf3159008b
BLAKE2b-256 checksum
How to use checksums
0a186fb5d37c289756ae7276e1d9628f2d410f158468da70d1d975da1d53674b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.

Transparency log

Release files / vcti_escapers-1.0.0-py3-none-any.whl

Download URL vcti_escapers-1.0.0-py3-none-any.whl
Size 19.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07e700474b73a51ec6f84f2859c175f98f7836ae149759dc11e88b679591b97c
BLAKE2b-256 checksum
How to use checksums
3936ba760373b0927c56c4d88cf15006a03f5576669f954c463f3dcd5888a9c1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.

Transparency log

Security for vcti-escapers 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vcti_escapers-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page