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_attributeis for ordinary attributes. An event handler (onclick), a URL attribute (href,src) orstyleneeds more than escaping — a perfectly escapedjavascript: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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.