httpquoted 0.2.0__py3-none-any.whl

httpquoted/__init__.py

@@ -0,0 +1,26 @@
+"""Typed codec for the HTTP quoted-string and comment primitives (RFC 9110)."""
+
+from __future__ import annotations
+
+from ._chars import QuotedStringError
+from ._comment import quote_comment, unquote_comment
+from ._quote import quote, quote_if_needed, unquote
+from ._scan import scan_comment, scan_quoted_string
+from ._split import split_list
+from ._token import is_token, needs_quoting
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "QuotedStringError",
+    "is_token",
+    "needs_quoting",
+    "quote",
+    "quote_comment",
+    "quote_if_needed",
+    "scan_comment",
+    "scan_quoted_string",
+    "split_list",
+    "unquote",
+    "unquote_comment",
+]

httpquoted/__main__.py

@@ -0,0 +1,9 @@
+"""Run the command line with `python -m httpquoted`."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

httpquoted/_chars.py

@@ -0,0 +1,71 @@
+"""Character classes of RFC 9110 section 5.6, the error type and the bytes bridge."""
+
+from __future__ import annotations
+
+import re
+import string
+from typing import AnyStr
+
+# tchar: any VCHAR except the delimiters DQUOTE and "(),/:;<=>?@[\]{}" (section 5.6.2).
+TCHAR = frozenset(string.ascii_letters + string.digits + "!#$%&'*+-.^_`|~")
+VCHAR = frozenset(chr(code) for code in range(0x21, 0x7F))
+OBS_TEXT = frozenset(chr(code) for code in range(0x80, 0x100))
+# What may follow a backslash, and what a sender may put between the quotes once DQUOTE
+# and backslash are escaped: HTAB, SP, VCHAR and obs-text.
+FIELD_TEXT = frozenset("\t ") | VCHAR | OBS_TEXT
+QDTEXT = FIELD_TEXT - frozenset('"\\')
+CTEXT = FIELD_TEXT - frozenset("()\\")
+
+# Runs of plain text. A single character class with `*` never backtracks, so every scan
+# stays linear however hostile the input is.
+QDTEXT_RUN = re.compile(r"[\t\x20\x21\x23-\x5b\x5d-\x7e\x80-\xff]*")
+CTEXT_RUN = re.compile(r"[\t\x20-\x27\x2a-\x5b\x5d-\x7e\x80-\xff]*")
+LOOSE_QUOTED_RUN = re.compile(r'[^"\\]*')
+LOOSE_COMMENT_RUN = re.compile(r"[^()\\]*")
+TOKEN_RE = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
+NOT_FIELD_TEXT = re.compile(r"[^\t\x20-\x7e\x80-\xff]")
+NOT_ASCII_TEXT = re.compile(r"[^\t\x20-\x7e]")
+
+
+class QuotedStringError(ValueError):
+    """A value breaks the quoted-string, comment or token grammar of RFC 9110.
+
+    `reason` names the broken rule and `offset` is the index of the offending character
+    in the text that was being read or written.
+    """
+
+    def __init__(self, reason: str, offset: int) -> None:
+        super().__init__(f"{reason} at offset {offset}")
+        self.reason = reason
+        self.offset = offset
+
+
+def describe(char: str) -> str:
+    """A readable name for a character in an error message."""
+    return f"U+{ord(char):04X}"
+
+
+def check_field_text(value: str, *, ascii_only: bool = False) -> None:
+    """Raise unless every character may appear in a field value written by a sender."""
+    bad = (NOT_ASCII_TEXT if ascii_only else NOT_FIELD_TEXT).search(value)
+    if bad is None:
+        return
+    char = bad.group()
+    kind = "is obs-text" if char in OBS_TEXT else "is not allowed"
+    raise QuotedStringError(f"{describe(char)} {kind}", bad.start())
+
+
+def as_text(value: str | bytes) -> str:
+    """Read bytes as ISO-8859-1, where every octet maps to the code point of the same value."""
+    if isinstance(value, bytes):
+        return value.decode("latin-1")
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"expected str or bytes, got {type(value).__name__}")
+
+
+def like(text: str, original: AnyStr) -> AnyStr:
+    """Return `text` in the type of `original`: bytes in, bytes out."""
+    if isinstance(original, bytes):
+        return text.encode("latin-1")
+    return text

httpquoted/_cli.py

@@ -0,0 +1,90 @@
+"""Command line: quote, unquote or split header values from arguments or standard input."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from ._chars import QuotedStringError
+from ._comment import quote_comment, unquote_comment
+from ._quote import quote, unquote
+from ._split import check_separator, split_list
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="httpquoted",
+        description="Quote, unquote or split HTTP field values (RFC 9110 section 5.6). "
+        "Values come from the arguments, or one per line from standard input.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, text in (
+        ("quote", "write each value as a quoted-string"),
+        ("unquote", "read each quoted-string or token back"),
+    ):
+        command = commands.add_parser(name, help=text)
+        command.add_argument("--comment", action="store_true", help="use (comment) syntax")
+        if name == "quote":
+            command.add_argument("--ascii-only", action="store_true", help="refuse obs-text")
+        else:
+            command.add_argument("--strict", action="store_true", help="reject malformed input")
+        command.add_argument("values", nargs="*")
+    split = commands.add_parser("split", help="print each list element on its own line")
+    split.add_argument("--separator", default=",", help='"," (default) or ";" for parameters')
+    split.add_argument("--comments", action="store_true", help="skip (comments) as a unit")
+    split.add_argument("--strict", action="store_true", help="reject malformed input")
+    split.add_argument("values", nargs="*")
+    return parser
+
+
+def _convert(args: argparse.Namespace, value: str) -> list[str]:
+    if args.command == "quote":
+        encode = quote_comment if args.comment else quote
+        return [encode(value, ascii_only=args.ascii_only)]
+    if args.command == "unquote":
+        decode = unquote_comment if args.comment else unquote
+        return [decode(value, strict=args.strict)]
+    return split_list(value, separator=args.separator, comments=args.comments, strict=args.strict)
+
+
+def _read_lines() -> list[str]:
+    # Field values are octets: read standard input as ISO-8859-1, never the locale codec.
+    buffer = getattr(sys.stdin, "buffer", None)
+    data = buffer.read().decode("latin-1") if buffer is not None else sys.stdin.read()
+    lines = [line.removesuffix("\r") for line in data.split("\n")]
+    return lines[:-1] if lines and not lines[-1] else lines
+
+
+def _write_line(line: str) -> None:
+    buffer = getattr(sys.stdout, "buffer", None)
+    if buffer is None:
+        sys.stdout.write(line + "\n")
+        return
+    sys.stdout.flush()
+    buffer.write(line.encode("latin-1") + b"\n")
+    buffer.flush()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point of the `httpquoted` command; returns the exit status."""
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.command == "split":
+        try:
+            check_separator(args.separator)
+        except ValueError as error:
+            parser.error(str(error))
+    values = args.values or _read_lines()
+    try:
+        for value in values:
+            for line in _convert(args, value):
+                _write_line(line)
+    except QuotedStringError as error:
+        print(f"httpquoted: {error}", file=sys.stderr)
+        return 1
+    except UnicodeEncodeError as error:
+        char = error.object[error.start]
+        print(f"httpquoted: U+{ord(char):04X} is not an ISO-8859-1 octet", file=sys.stderr)
+        return 1
+    return 0

httpquoted/_comment.py

@@ -0,0 +1,42 @@
+"""Quote and unquote HTTP comments (RFC 9110 section 5.6.5)."""
+
+from __future__ import annotations
+
+from typing import AnyStr
+
+from ._chars import QuotedStringError, as_text, check_field_text, like
+from ._quote import _unescape
+from ._scan import scan_comment
+
+
+def quote_comment(value: AnyStr, *, ascii_only: bool = False) -> AnyStr:
+    """Wrap a value in parentheses, escaping parentheses and backslash.
+
+    Every "(", ")" and backslash in the value becomes a quoted-pair, the only ones
+    section 5.6.4 lets a sender write in a comment, so the result reads back with
+    :func:`unquote_comment` as the same text and never opens a nested comment. The
+    characters refused are the ones :func:`quote` refuses.
+    """
+    text = as_text(value)
+    check_field_text(text, ascii_only=ascii_only)
+    escaped = text.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)")
+    return like(f"({escaped})", value)
+
+
+def unquote_comment(value: AnyStr, *, strict: bool = False) -> AnyStr:
+    """Strip the outer parentheses of a comment and resolve its quoted-pairs.
+
+    Nested comments stay in the result as text, parentheses included. Lenient by
+    default: a value not wrapped in parentheses comes back unchanged. With
+    `strict=True` the value must be exactly one comment, balanced and made of ctext,
+    quoted-pairs and nested comments; anything else raises `QuotedStringError`.
+    """
+    text = as_text(value)
+    if strict:
+        result, end = scan_comment(text, strict=True)
+        if end != len(text):
+            raise QuotedStringError("text after the closing parenthesis", end)
+        return like(result, value)
+    if len(text) >= 2 and text[0] == "(" and text[-1] == ")":
+        return like(_unescape(text[1:-1]), value)
+    return value

httpquoted/_quote.py

@@ -0,0 +1,67 @@
+"""Quote and unquote HTTP quoted-string field values (RFC 9110 section 5.6.4)."""
+
+from __future__ import annotations
+
+import re
+from typing import AnyStr
+
+from ._chars import TOKEN_RE, QuotedStringError, as_text, check_field_text, like
+from ._scan import scan_quoted_string
+
+_QUOTED_PAIR = re.compile(r"\\(.)", re.DOTALL)
+
+
+def quote(value: AnyStr, *, ascii_only: bool = False) -> AnyStr:
+    """Wrap a value in a quoted-string, escaping backslash and double quote.
+
+    Only those two characters become quoted-pairs, as section 5.6.4 asks of senders,
+    so the result parses back to the original with :func:`unquote`. A character a
+    quoted-string cannot carry (CR, LF, NUL and the other controls, DEL, anything above
+    U+00FF) raises `QuotedStringError` instead of reaching the header; `ascii_only=True`
+    also refuses obs-text (U+0080 to U+00FF). Accepts `str` or `bytes`.
+    """
+    text = as_text(value)
+    check_field_text(text, ascii_only=ascii_only)
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    return like(f'"{escaped}"', value)
+
+
+def quote_if_needed(value: AnyStr, *, ascii_only: bool = False) -> AnyStr:
+    """Return a token unchanged and quote anything else (a parameter value, 5.6.6)."""
+    if TOKEN_RE.fullmatch(as_text(value)):
+        return value
+    return quote(value, ascii_only=ascii_only)
+
+
+def unquote(value: AnyStr, *, strict: bool = False) -> AnyStr:
+    """Strip the surrounding quotes and resolve quoted-pairs.
+
+    Lenient by default: a value that is not wrapped in double quotes is returned
+    unchanged, so a bare token passes through untouched, and the inside of a quoted
+    value is unescaped without further checks. With `strict=True` the value must be
+    exactly a token or a quoted-string (the `token / quoted-string` choice of a
+    parameter value); anything else raises `QuotedStringError`.
+    """
+    text = as_text(value)
+    if strict:
+        return like(_strict_unquote(text), value)
+    if len(text) >= 2 and text[0] == '"' and text[-1] == '"':
+        return like(_unescape(text[1:-1]), value)
+    return value
+
+
+def _strict_unquote(text: str) -> str:
+    if text.startswith('"'):
+        result, end = scan_quoted_string(text, strict=True)
+        if end != len(text):
+            raise QuotedStringError("text after the closing quote", end)
+        return result
+    if TOKEN_RE.fullmatch(text):
+        return text
+    bad = TOKEN_RE.match(text)
+    raise QuotedStringError("not a token or a quoted-string", bad.end() if bad else 0)
+
+
+def _unescape(inner: str) -> str:
+    # A trailing lone backslash has nothing to quote and is kept as it is.
+    return _QUOTED_PAIR.sub(r"\1", inner)

httpquoted/_scan.py

@@ -0,0 +1,98 @@
+"""Scan one quoted-string or comment inside a larger field value (RFC 9110 5.6.4, 5.6.5)."""
+
+from __future__ import annotations
+
+import re
+from typing import AnyStr
+
+from ._chars import (
+    CTEXT_RUN,
+    FIELD_TEXT,
+    LOOSE_COMMENT_RUN,
+    LOOSE_QUOTED_RUN,
+    QDTEXT_RUN,
+    QuotedStringError,
+    as_text,
+    describe,
+    like,
+)
+
+
+def scan_quoted_string(text: AnyStr, start: int = 0, *, strict: bool = False) -> tuple[AnyStr, int]:
+    """Read the quoted-string that opens at `start` and return its value and end offset.
+
+    The value has its quoted-pairs resolved; the offset points just past the closing
+    DQUOTE. Lenient mode accepts any character between the quotes and lets an
+    unterminated string run to the end of the text. `strict=True` raises
+    `QuotedStringError` for a character that is not qdtext, a bad quoted-pair or a
+    missing closing quote.
+    """
+    source = as_text(text)
+    _expect(source, start, '"', "quoted-string")
+    value, end = _scan(source, start, QDTEXT_RUN if strict else LOOSE_QUOTED_RUN, strict, 0)
+    return like(value, text), end
+
+
+def scan_comment(text: AnyStr, start: int = 0, *, strict: bool = False) -> tuple[AnyStr, int]:
+    """Read the comment that opens at `start` and return its value and end offset.
+
+    Comments nest: the value keeps the parentheses of inner comments and has every
+    quoted-pair resolved, and the offset points just past the matching ")". Inside a
+    comment DQUOTE is plain text. Strict and lenient modes work as in
+    `scan_quoted_string`; nesting depth is only limited by the length of the text.
+    """
+    source = as_text(text)
+    _expect(source, start, "(", "comment")
+    value, end = _scan(source, start, CTEXT_RUN if strict else LOOSE_COMMENT_RUN, strict, 1)
+    return like(value, text), end
+
+
+def _expect(source: str, start: int, opener: str, rule: str) -> None:
+    if isinstance(start, bool) or not isinstance(start, int):
+        raise TypeError(f"start must be an int, got {type(start).__name__}")
+    if not 0 <= start < len(source) or source[start] != opener:
+        raise QuotedStringError(f"a {rule} must start with {opener}", start)
+
+
+def _scan(
+    source: str, start: int, run: re.Pattern[str], strict: bool, depth: int
+) -> tuple[str, int]:
+    """Shared loop: depth 0 reads a quoted-string, depth 1 and more a nested comment."""
+    rule = "comment" if depth else "quoted-string"
+    closer = ")" if depth else '"'
+    parts: list[str] = []
+    pos = start + 1
+    length = len(source)
+    while True:
+        match = run.match(source, pos)
+        assert match is not None  # a pattern ending in `*` always matches
+        parts.append(match.group())
+        pos = match.end()
+        if pos >= length:
+            if strict:
+                raise QuotedStringError(f"unterminated {rule}", start)
+            return "".join(parts), length
+        char = source[pos]
+        if char == "\\":
+            if pos + 1 >= length:
+                if strict:
+                    raise QuotedStringError("a quoted-pair needs a character", pos)
+                parts.append(char)
+                return "".join(parts), length
+            escaped = source[pos + 1]
+            if strict and escaped not in FIELD_TEXT:
+                raise QuotedStringError(f"{describe(escaped)} cannot be quoted", pos + 1)
+            parts.append(escaped)
+            pos += 2
+        elif char == closer and depth <= 1:
+            return "".join(parts), pos + 1
+        elif char == closer:
+            depth -= 1
+            parts.append(char)
+            pos += 1
+        elif char == "(" and depth:
+            depth += 1
+            parts.append(char)
+            pos += 1
+        else:
+            raise QuotedStringError(f"{describe(char)} is not allowed in a {rule}", pos)

httpquoted/_split.py

@@ -0,0 +1,80 @@
+"""Split a delimited header value while respecting quoted-strings and comments."""
+
+from __future__ import annotations
+
+import re
+from typing import AnyStr
+
+from ._chars import FIELD_TEXT, NOT_FIELD_TEXT, QuotedStringError, as_text, describe, like
+from ._scan import scan_comment, scan_quoted_string
+
+_RESERVED = frozenset('"\\()')
+
+
+def split_list(
+    header: AnyStr,
+    *,
+    separator: str | bytes = ",",
+    comments: bool = False,
+    strict: bool = False,
+) -> list[AnyStr]:
+    """Split a list-style header on separators that sit outside quoted-strings.
+
+    A separator inside double quotes is part of the value, and a quoted-pair never ends
+    the quotes. With `comments=True` a parenthesised comment (in Via, User-Agent or
+    Server) is skipped as a unit too, nested or not, and a DQUOTE inside it is plain
+    text. Each element is trimmed of surrounding spaces and tabs, and empty elements
+    are dropped, as section 5.6.1.2 asks of recipients. `separator` is "," for lists
+    and ";" for parameters, as `str` or `bytes`. Elements keep their quotes.
+
+    Lenient by default: an unterminated quoted-string or comment runs to the end. With
+    `strict=True`, `QuotedStringError` is raised for a character that is not field
+    content (CR, LF, NUL, other controls, DEL), a quoted-string or comment that breaks
+    its grammar or never ends, and a stray ")" when `comments=True`. The grammar of
+    each element belongs to the field and is left to the caller: `"a"b` is one element.
+    """
+    separator = check_separator(separator)
+    text = as_text(header)
+    if strict:
+        bad = NOT_FIELD_TEXT.search(text)
+        if bad is not None:
+            raise QuotedStringError(f"{describe(bad.group())} is not allowed", bad.start())
+    stops = re.compile("[" + re.escape(separator + '"' + ("()" if comments else "")) + "]")
+    elements: list[AnyStr] = []
+    begin = pos = 0
+    length = len(text)
+    while pos < length:
+        found = stops.search(text, pos)
+        if found is None:
+            break
+        pos = found.start()
+        char = text[pos]
+        if char == separator:
+            _keep(text[begin:pos], header, elements)
+            begin = pos = pos + 1
+        elif char == '"':
+            pos = scan_quoted_string(text, pos, strict=strict)[1]
+        elif char == "(":
+            pos = scan_comment(text, pos, strict=strict)[1]
+        elif strict:
+            raise QuotedStringError("unbalanced )", pos)
+        else:
+            pos += 1
+    _keep(text[begin:], header, elements)
+    return elements
+
+
+def check_separator(separator: str | bytes) -> str:
+    """Return the separator as text, or raise ValueError if it cannot split a field value."""
+    sep = as_text(separator)
+    if len(sep) != 1 or sep in _RESERVED or sep not in FIELD_TEXT:
+        raise ValueError(
+            "separator must be one field character other than DQUOTE, backslash, ( or )"
+        )
+    return sep
+
+
+def _keep(element: str, header: AnyStr, elements: list[AnyStr]) -> None:
+    element = element.strip(" \t")
+    if element:
+        elements.append(like(element, header))

httpquoted/_token.py

@@ -0,0 +1,26 @@
+"""Recognise an HTTP token (RFC 9110 section 5.6.2, the tchar production)."""
+
+from __future__ import annotations
+
+from typing import AnyStr
+
+from ._chars import TOKEN_RE, as_text
+
+
+def is_token(value: AnyStr) -> bool:
+    """Report whether a value is a non-empty run of token characters.
+
+    A token needs at least one character and may contain only tchar: letters,
+    digits and a fixed set of symbols. Anything else, including an empty string,
+    whitespace or a delimiter, is not a token. Accepts `str` or `bytes`.
+    """
+    return TOKEN_RE.fullmatch(as_text(value)) is not None
+
+
+def needs_quoting(value: AnyStr) -> bool:
+    """Report whether a parameter value must be sent as a quoted-string.
+
+    RFC 9110 section 5.6.6 lets a value that is a token travel bare or quoted with the
+    same meaning; anything else, the empty value included, needs the quotes.
+    """
+    return not is_token(value)

httpquoted-0.2.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: httpquoted
+Version: 0.2.0
+Summary: Strict, typed and zero-dependency codec for HTTP quoted-strings, comments and tokens (RFC 9110): safe quoting, strict parsing, scanners and quote-aware list splitting
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/httpquoted
+Project-URL: Issues, https://github.com/JaviLianes8/httpquoted/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/httpquoted/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: comment,field-value,header,http,list,parser,quote,quoted-string,rfc7230,rfc9110,token,unquote
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# httpquoted
+
+Strict, typed and zero-dependency codec for the HTTP quoted-string, comment and token
+primitives of RFC 9110 section 5.6: safe quoting, strict or lenient parsing, scanners for
+hand-written parsers and list splitting that respects quotes and comments.
+
+## Install
+
+```
+pip install httpquoted
+```
+
+## Usage
+
+Quote a value for a header and read it back. Only DQUOTE and backslash are escaped, as
+section 5.6.4 asks of senders, and a value that is a token can travel bare:
+
+```python
+from httpquoted import quote, quote_if_needed, unquote
+
+print(quote('say "hi"'))
+print(unquote('"say \\"hi\\""'))
+print(quote_if_needed("utf-8"), quote_if_needed("two words"))
+# "say \"hi\""
+# say "hi"
+# utf-8 "two words"
+```
+
+Quoting refuses what a quoted-string cannot carry, so a CR LF never reaches a header.
+Parsing is lenient by default; `strict=True` raises with the broken rule and its offset:
+
+```python
+from httpquoted import QuotedStringError, quote, unquote
+
+for call in (lambda: quote("a\r\nX-Injected: 1"), lambda: unquote('"a"b"', strict=True)):
+    try:
+        call()
+    except QuotedStringError as error:
+        print(error.reason, error.offset)
+print(unquote('"a"b"'))
+# U+000D is not allowed 1
+# text after the closing quote 3
+# a"b
+```
+
+Split a list on commas outside quoted-strings, or parameters on semicolons. Fields
+whose grammar has comments (Via, User-Agent, Server) pass `comments=True`:
+
+```python
+from httpquoted import split_list, unquote
+
+print(split_list('gzip, "a,b", , br'))
+print(split_list('text/plain; charset="utf-8"', separator=";"))
+print(split_list("1.0 fred (proxy, eu), 1.1 example.net", comments=True))
+print([unquote(tag, strict=True) for tag in split_list('"xyzzy", "r2d2xxxx"')])
+# ['gzip', '"a,b"', 'br']
+# ['text/plain', 'charset="utf-8"']
+# ['1.0 fred (proxy, eu)', '1.1 example.net']
+# ['xyzzy', 'r2d2xxxx']
+```
+
+Comments nest and have their own escaping. The scanners read one quoted-string or
+comment inside a larger value and return where it ends:
+
+```python
+from httpquoted import quote_comment, scan_comment, scan_quoted_string, unquote_comment
+
+print(quote_comment("Windows NT 10.0; (x64)"))
+print(unquote_comment("(a (nested) \\) comment)", strict=True))
+text = 'title="a, \\"b\\""; lang=en'
+value, end = scan_quoted_string(text, 6, strict=True)
+print(value, text[end:])
+print(scan_comment("Mozilla/5.0 (X11; Linux) Gecko", 12))
+# (Windows NT 10.0; \(x64\))
+# a (nested) ) comment
+# a, "b" ; lang=en
+# ('X11; Linux', 24)
+```
+
+Every function takes `str` or `bytes` and returns the same type. Bytes are read as
+ISO-8859-1, so the obs-text octets 0x80 to 0xFF round-trip unchanged:
+
+```python
+from httpquoted import quote, split_list, unquote
+
+print(quote(b"caf\xe9"))
+print(unquote(b'"caf\xe9"', strict=True))
+print(split_list(b'a, "b,c"'))
+# b'"caf\xe9"'
+# b'caf\xe9'
+# [b'a', b'"b,c"']
+```
+
+## Command line
+
+```
+$ httpquoted quote 'say "hi"'
+"say \"hi\""
+$ httpquoted unquote --strict '"a"b"'
+httpquoted: text after the closing quote at offset 3
+$ httpquoted split --comments '1.0 fred (proxy, eu), 1.1 example.net'
+1.0 fred (proxy, eu)
+1.1 example.net
+```
+
+Values come from the arguments, or one per line from standard input. `quote` takes
+`--comment` and `--ascii-only`; `unquote` takes `--comment` and `--strict`; `split`
+takes `--separator`, `--comments` and `--strict`. Standard input and output are read
+and written as ISO-8859-1, so octets pass through unchanged. A rejected value exits with
+status 1.
+
+## API
+
+| Name | What it does |
+|---|---|
+| `quote(value, *, ascii_only=False)` | Quoted-string with DQUOTE and backslash escaped; refuses controls, DEL and anything above U+00FF, and obs-text when `ascii_only` |
+| `unquote(value, *, strict=False)` | Strips quotes and resolves quoted-pairs; a bare value comes back unchanged. Strict: exactly a token or a quoted-string |
+| `quote_if_needed(value, *, ascii_only=False)` | A token unchanged, anything else quoted (parameter values, section 5.6.6) |
+| `needs_quoting(value)` | True unless the value is a token |
+| `is_token(value)` | True for a non-empty run of tchar |
+| `quote_comment(value, *, ascii_only=False)` | Comment with "(", ")" and backslash escaped |
+| `unquote_comment(value, *, strict=False)` | Strips the outer parentheses and resolves quoted-pairs; nested comments stay as text |
+| `scan_quoted_string(text, start=0, *, strict=False)` | Value of the quoted-string at `start` and the offset after it |
+| `scan_comment(text, start=0, *, strict=False)` | Value of the (nested) comment at `start` and the offset after it |
+| `split_list(header, *, separator=",", comments=False, strict=False)` | Elements outside quotes (and comments), trimmed, empty ones dropped |
+| `QuotedStringError` | `ValueError` with `reason` and `offset` |
+
+Lenient mode never raises on malformed input. The scanners stop at the first closing
+quote or parenthesis and let an unterminated value run to the end, while lenient
+`unquote` and `unquote_comment` keep the 0.1.0 behaviour: they strip the first and last
+character when those are the quotes (or parentheses) and resolve quoted-pairs in between.
+
+Strict mode checks the token, quoted-string, quoted-pair and comment rules of RFC 9110
+sections 5.6.2 to 5.6.5 character by character; the tests evaluate that grammar from the
+fetched RFC and compare it with the functions for every code point up to U+010F. Strict
+`split_list` checks field content and every quoted-string and comment it meets, not the
+grammar of each element, which belongs to the field (`"a"b` is one element).
+
+The value of a comment is display text: quoted-pairs are resolved and nested comments
+keep their parentheses, so `\)` and a nesting `)` look alike. To parse it again, slice
+the raw comment with the end offset that `scan_comment` returns.
+
+obs-text includes U+0080 to U+009F, which some tools treat as line breaks (U+0085);
+section 5.5 asks new fields to use ASCII, which `ascii_only=True` enforces. Every scan
+is linear in the length of the input, including a megabyte of backslashes or nested
+parentheses.
+
+## Why
+
+The quoted-string codec of RFC 9110 sits under almost every HTTP header parser, yet no
+small typed library ships it on its own: the stdlib `quopri` handles MIME
+quoted-printable (a different thing), and the logic is vendored privately into
+frameworks and SDKs, often without the checks that stop header injection. Other
+ecosystems expose it directly (Ruby has `Protocol::HTTP::QuotedString`). This is that
+primitive, zero-dependency and typed, for the times you parse or build a header by hand.
+
+## Development
+
+`scripts/check.ps1` runs format, lint, `mypy --strict` and the tests. The RFC checks
+read the RFCs from `tests/upstream/`, which is not committed: `python
+scripts/fetch_upstream.py` downloads them and verifies the sha256 of each against
+`tests/upstream/MANIFEST.json`; until then those tests skip. Set `HTTPQUOTED_E2E=1` to
+build the wheel and drive it from a fresh virtual environment.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

httpquoted-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+httpquoted/__init__.py,sha256=aT8OJxvht21t8dFmVKX0ABmzoSRPOL4BhhjY7nY8C0o,646
+httpquoted/__main__.py,sha256=eAlCbqOjLh4dsdmEXJVPd1CCEm6cYQXxyNvc2yINFbA,146
+httpquoted/_chars.py,sha256=Xk7Xvhru7UgC_NOonv-evnVqkgTYr9_-YYCz90R2_a8,2795
+httpquoted/_cli.py,sha256=jnOmRSopl3qK4FPTKUEMQUCxQPaL3cVGDheDmK5EvJQ,3653
+httpquoted/_comment.py,sha256=N5sC0eiIng6i0XhEEp8YEGBzeaL1kA6NsrQvCCM-1tY,1768
+httpquoted/_quote.py,sha256=PbpSUEdSVDyP1SxTfTXJOuRaAlNxPpwsTSulhs_e4RE,2670
+httpquoted/_scan.py,sha256=yPIrIb-t0KiSouYo5XfLWXIhueOYwldmB1jAzVumcgA,3782
+httpquoted/_split.py,sha256=zzw5KfM3bDGJpQuvsX3-6VgdUFfizazc99rKH_7bZR0,3109
+httpquoted/_token.py,sha256=SR3FoNKY_dBxG8LdRcAq1_IqToUB5-FhETc5sL5S8F4,909
+httpquoted/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+httpquoted-0.2.0.dist-info/METADATA,sha256=YlfqMlQExKucJDzcB8u91nhqB5RYkyAit2acvlGMK2k,8898
+httpquoted-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+httpquoted-0.2.0.dist-info/entry_points.txt,sha256=J_OiTaAI7jN25NLc7pP7ScTQ3iV2K_lliM5t85s5x2I,52
+httpquoted-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+httpquoted-0.2.0.dist-info/RECORD,,

httpquoted-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

httpquoted-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+httpquoted = httpquoted._cli:main

httpquoted-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.