mediaparse 0.2.0__py3-none-any.whl

mediaparse/__init__.py

@@ -0,0 +1,28 @@
+"""Parse and build HTTP media types, Content-Type and Accept headers, exactly."""
+
+from __future__ import annotations
+
+from ._accept import AcceptItem, negotiate, parse_accept, quality
+from ._build import build
+from ._errors import MediaTypeError
+from ._mediatype import MediaType
+from ._normalize import matches, normalize
+from ._parse import parse, parse_media_type
+from ._rfc2231 import decode_extended
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AcceptItem",
+    "MediaType",
+    "MediaTypeError",
+    "build",
+    "decode_extended",
+    "matches",
+    "negotiate",
+    "normalize",
+    "parse",
+    "parse_accept",
+    "parse_media_type",
+    "quality",
+]

mediaparse/_accept.py

@@ -0,0 +1,175 @@
+"""Read an Accept header and pick a representation (RFC 9110 sections 12.4.2 and 12.5.1)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+
+from ._errors import MediaTypeError, show
+from ._lenient import collect_quoted, parse_lenient
+from ._mediatype import MediaType
+from ._parse import parse_media_type
+from ._strict import parse_strict
+from ._tokens import HTTP_WHITESPACE, OWS, ascii_lower
+
+# qvalue = ( "0" [ "." 0*3DIGIT ] ) / ( "1" [ "." 0*3("0") ] )
+_QVALUE = re.compile(r"0(?:\.[0-9]{0,3})?|1(?:\.0{0,3})?")
+
+
+@dataclass(frozen=True)
+class AcceptItem:
+    """One media range of an Accept header and its weight ``q`` (0 to 1, default 1)."""
+
+    media_range: MediaType
+    q: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.media_range, MediaType):
+            raise TypeError(
+                f"media_range must be a MediaType, got {type(self.media_range).__name__}"
+            )
+        if isinstance(self.q, bool) or not isinstance(self.q, (int, float)):
+            raise TypeError(f"q must be a number, got {type(self.q).__name__}")
+        if not 0 <= self.q <= 1:
+            raise MediaTypeError(f"q must be between 0 and 1, got {show(self.q)}")
+        object.__setattr__(self, "q", float(self.q))
+
+    def specificity(self) -> tuple[bool, bool, int]:
+        """Precedence of the range: concrete type, concrete subtype, parameter count."""
+        rng = self.media_range
+        return (rng.type != "*", rng.subtype != "*", len(rng.params))
+
+    def matches(self, media: MediaType) -> bool:
+        """Return whether the range covers ``media``, parameters included."""
+        rng = self.media_range
+        if rng.type not in ("*", media.type) or rng.subtype not in ("*", media.subtype):
+            return False
+        return all(_same(name, value, media.get(name)) for name, value in rng.params)
+
+
+def parse_accept(header: str, *, strict: bool = False) -> list[AcceptItem]:
+    """Read an Accept header into its media ranges, in header order.
+
+    Elements are split on commas outside quoted strings and empty elements are ignored.
+    The ``q`` parameter is the weight wherever it appears and is removed from the range.
+    By default an element that is not a valid media range, or whose ``q`` breaks the
+    ``qvalue`` grammar, is skipped; with ``strict=True`` it raises :class:`MediaTypeError`
+    and each range must match the RFC 9110 grammar exactly.
+    """
+    if not isinstance(header, str):
+        raise TypeError(f"expected str, got {type(header).__name__}")
+    items: list[AcceptItem] = []
+    for start, element in _elements(header):
+        if not element.strip(OWS if strict else HTTP_WHITESPACE):
+            continue
+        try:
+            items.append(_item(element, strict))
+        except MediaTypeError as error:
+            if strict:
+                where = None if error.position is None else start + error.position
+                raise MediaTypeError(str(error), position=where) from None
+    return items
+
+
+def quality(accept: str | None, offer: str) -> float:
+    """Return the weight ``accept`` gives ``offer``: the ``q`` of the most specific range
+    that covers it (the earliest such range on a tie), 0 if none does. ``None`` means the
+    request had no Accept field, which accepts everything with weight 1.
+    """
+    media = _offer(offer)
+    if accept is None:
+        return 1.0
+    return _quality(parse_accept(accept), media)
+
+
+def negotiate(accept: str | None, offers: Iterable[str]) -> str | None:
+    """Return the offer with the highest non-zero weight, or ``None`` if none is acceptable.
+
+    Offers are concrete media types in the server's order of preference, which breaks ties.
+    The chosen offer is returned exactly as given.
+    """
+    if isinstance(offers, str):
+        raise TypeError("offers must be an iterable of media types, not a single str")
+    items = None if accept is None else parse_accept(accept)
+    best, best_q = None, 0.0
+    for offer in offers:
+        media = _offer(offer)
+        weight = 1.0 if items is None else _quality(items, media)
+        if weight > best_q:
+            best, best_q = offer, weight
+    return best
+
+
+def _quality(items: list[AcceptItem], media: MediaType) -> float:
+    covering = [item for item in items if item.matches(media)]
+    if not covering:
+        return 0.0
+    top = max(item.specificity() for item in covering)
+    return next(item.q for item in covering if item.specificity() == top)
+
+
+def _item(element: str, strict: bool) -> AcceptItem:
+    quoted: set[str] = set()
+    media = parse_strict(element, quoted) if strict else parse_lenient(element)
+    if media.type == "*" and media.subtype != "*":
+        raise MediaTypeError(f"invalid media range: {media.essence!r}")
+    weight = media.get("q")
+    if weight is None and not strict and "q" in _raw_names(element):
+        # The browser algorithm dropped a malformed q (q =0, q=, a control character);
+        # reading it as the default weight 1 would turn "not acceptable" into "best".
+        raise MediaTypeError("invalid weight")
+    q = 1.0
+    if weight is not None:
+        if _QVALUE.fullmatch(weight) is None or "q" in quoted:
+            raise MediaTypeError(f"invalid weight q={show(weight)}")
+        q = float(weight)
+    rest = tuple(pair for pair in media.params if pair[0] != "q")
+    return AcceptItem(MediaType(media.type, media.subtype, rest), q)
+
+
+def _elements(header: str) -> Iterator[tuple[int, str]]:
+    start = index = 0
+    while index < len(header):
+        char = header[index]
+        if char == '"':
+            _, index = collect_quoted(header, index)
+            continue
+        if char == ",":
+            yield start, header[start:index]
+            start = index + 1
+        index += 1
+    yield start, header[start:]
+
+
+def _raw_names(element: str) -> set[str]:
+    """Parameter names as written, trimmed and lower-cased, even where the value is broken."""
+    names: set[str] = set()
+    index, length = element.find(";"), len(element)
+    while 0 <= index < length:
+        index += 1
+        start = index
+        while index < length and element[index] not in ";=":
+            index += 1
+        names.add(ascii_lower(element[start:index].strip(HTTP_WHITESPACE)))
+        while index < length and element[index] != ";":
+            if element[index] == '"':
+                _, index = collect_quoted(element, index)
+            else:
+                index += 1
+    return names
+
+
+def _offer(offer: str) -> MediaType:
+    media = parse_media_type(offer)
+    if "*" in (media.type, media.subtype):
+        raise MediaTypeError(f"an offer must be a concrete media type, not {show(offer)}")
+    return media
+
+
+def _same(name: str, wanted: str, actual: str | None) -> bool:
+    if actual is None:
+        return False
+    if name == "charset":
+        return ascii_lower(wanted) == ascii_lower(actual)
+    return wanted == actual

mediaparse/_build.py

@@ -0,0 +1,69 @@
+"""Build a Content-Type style header from a media type and parameters."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ._errors import MediaTypeError, show
+from ._extended import encode_extended
+from ._tokens import OWS, ascii_lower, is_quotable, is_token, quote
+
+
+def build(mimetype: str, params: Mapping[str, str] | None = None, *, extended: bool = False) -> str:
+    """Render ``mimetype`` and ``params`` as a header value such as ``text/html; charset=utf-8``.
+
+    The media type and parameter names are lower-cased. Each value is written as a bare
+    token when it can be and as a quoted string otherwise. A value that no header can carry
+    raises :class:`MediaTypeError`: control characters (other than tab) would split or
+    corrupt the header, and characters outside ASCII have no agreed byte form. With
+    ``extended=True`` such a value is written instead as ``name*=UTF-8''...``, the
+    percent-encoded form of RFC 8187 and RFC 2231, and names may not end in ``*``. Two
+    parameters that would be written under the same name raise :class:`MediaTypeError`.
+    """
+    parts = [essence(mimetype)]
+    if params is not None and not isinstance(params, Mapping):
+        raise TypeError(f"params must be a mapping, got {type(params).__name__}")
+    seen: set[str] = set()
+    for name, value in (params or {}).items():
+        key = _name(name)
+        if not isinstance(value, str):
+            raise TypeError(f"parameter {show(key)} must be a str, got {type(value).__name__}")
+        if extended and key.endswith("*"):
+            raise MediaTypeError(f"parameter {show(key)} ends in '*'; extended=True adds it")
+        if value.isascii() and all(map(is_quotable, value)):
+            field = f"{key}={quote(value)}"
+        elif extended:
+            key += "*"
+            field = f"{key}={encode_extended(value)}"
+        else:
+            raise MediaTypeError(
+                f"parameter {show(key)} holds a control or non-ASCII character; "
+                "pass extended=True to percent-encode it"
+            )
+        if key in seen:
+            raise MediaTypeError(f"parameter {show(key)} is given more than once")
+        seen.add(key)
+        parts.append(field)
+    return "; ".join(parts)
+
+
+def essence(mimetype: str) -> str:
+    """Return the lower-cased ``type/subtype``, or raise if it is not two tokens."""
+    if not isinstance(mimetype, str):
+        raise TypeError(f"mimetype must be a str, got {type(mimetype).__name__}")
+    cleaned = mimetype.strip(OWS)
+    main, slash, subtype = cleaned.partition("/")
+    if not slash:
+        raise MediaTypeError(f"media type has no subtype: {show(mimetype)}")
+    if not is_token(main) or not is_token(subtype):
+        raise MediaTypeError(f"invalid media type: {show(mimetype)}")
+    return ascii_lower(cleaned)
+
+
+def _name(name: str) -> str:
+    if not isinstance(name, str):
+        raise TypeError(f"parameter names must be str, got {type(name).__name__}")
+    key = ascii_lower(name.strip(OWS))
+    if not is_token(key):
+        raise MediaTypeError(f"invalid parameter name: {show(name)}")
+    return key

mediaparse/_errors.py

@@ -0,0 +1,21 @@
+"""Error type raised when a media type, parameter or Accept header is invalid."""
+
+from __future__ import annotations
+
+
+class MediaTypeError(ValueError):
+    """Raised when a media type, a parameter or an Accept header is invalid.
+
+    ``position`` is the index in the input of the first offending character when the
+    error comes from parsing text, and ``None`` otherwise.
+    """
+
+    def __init__(self, message: str, *, position: int | None = None) -> None:
+        super().__init__(message)
+        self.position = position
+
+
+def show(value: object, limit: int = 80) -> str:
+    """Return ``repr(value)`` cut to ``limit`` characters, so a huge input stays out of messages."""
+    text = repr(value)
+    return text if len(text) <= limit else text[: limit - 3] + "..."

mediaparse/_extended.py

@@ -0,0 +1,41 @@
+"""Extended parameter values: ``charset'language'percent-encoded`` (RFC 8187, RFC 2231)."""
+
+from __future__ import annotations
+
+from ._errors import MediaTypeError, show
+
+# attr-char from RFC 8187 section 3.2.1: a token character other than "*", "'" and "%".
+ATTR_CHARS = frozenset("!#$&+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")
+_HEX = "0123456789abcdefABCDEF"
+
+
+def encode_extended(value: str) -> str:
+    """Return ``UTF-8''`` followed by the value with every non attr-char byte percent-encoded."""
+    try:
+        data = value.encode("utf-8")
+    except UnicodeEncodeError as error:
+        raise MediaTypeError(f"value is not encodable as UTF-8: {value!r}") from error
+    encoded = "".join(chr(byte) if chr(byte) in ATTR_CHARS else f"%{byte:02X}" for byte in data)
+    return f"UTF-8''{encoded}"
+
+
+def percent_decode(text: str) -> bytes:
+    """Decode ``%XX`` escapes; other characters must be ASCII and are kept as they are."""
+    out = bytearray()
+    index, length = 0, len(text)
+    while index < length:
+        char = text[index]
+        if char == "%":
+            pair = text[index + 1 : index + 3]
+            if len(pair) != 2 or pair[0] not in _HEX or pair[1] not in _HEX:
+                raise MediaTypeError(f"invalid percent escape in {show(text)}", position=index)
+            out.append(int(pair, 16))
+            index += 3
+            continue
+        if not char.isascii():
+            raise MediaTypeError(
+                f"non-ASCII character in encoded value {show(text)}", position=index
+            )
+        out.append(ord(char))
+        index += 1
+    return bytes(out)

mediaparse/_lenient.py

@@ -0,0 +1,83 @@
+"""The WHATWG MIME Sniffing "parse a MIME type" algorithm, step by step.
+
+https://mimesniff.spec.whatwg.org/#parse-a-mime-type, with "collect an HTTP quoted
+string" from https://fetch.spec.whatwg.org/. Where the algorithm returns failure this
+module raises :class:`MediaTypeError`; everything else it tolerates the way browsers do.
+"""
+
+from __future__ import annotations
+
+from ._errors import MediaTypeError, show
+from ._mediatype import MediaType
+from ._tokens import HTTP_WHITESPACE, ascii_lower, is_quotable, is_token
+
+
+def parse_lenient(text: str) -> MediaType:
+    """Parse ``text`` exactly as a browser parses a MIME type."""
+    data = text.strip(HTTP_WHITESPACE)
+    offset = len(text) - len(text.lstrip(HTTP_WHITESPACE))
+    slash = data.find("/")
+    main = data if slash < 0 else data[:slash]
+    if not is_token(main):
+        raise MediaTypeError(f"invalid media type: {show(text)}", position=offset)
+    if slash < 0:
+        raise MediaTypeError(
+            f"media type has no subtype: {show(text)}", position=offset + len(data)
+        )
+    end = _find(data, ";", slash + 1)
+    subtype = data[slash + 1 : end].rstrip(HTTP_WHITESPACE)
+    if not is_token(subtype):
+        raise MediaTypeError(f"invalid media subtype: {show(text)}", position=offset + slash + 1)
+    params: dict[str, str] = {}
+    position, length = end, len(data)
+    while position < length:
+        position += 1  # skip the ";"
+        while position < length and data[position] in HTTP_WHITESPACE:
+            position += 1
+        start = position
+        while position < length and data[position] not in ";=":
+            position += 1
+        name = ascii_lower(data[start:position])
+        if position < length:
+            if data[position] == ";":
+                continue
+            position += 1  # skip the "="
+        if position >= length:
+            break
+        if data[position] == '"':
+            value, position = collect_quoted(data, position)
+            position = _find(data, ";", position)
+        else:
+            stop = _find(data, ";", position)
+            value = data[position:stop].rstrip(HTTP_WHITESPACE)
+            position = stop
+            if not value:
+                continue
+        if is_token(name) and all(map(is_quotable, value)) and name not in params:
+            params[name] = value
+    return MediaType(main, subtype, tuple(params.items()))
+
+
+def collect_quoted(data: str, position: int) -> tuple[str, int]:
+    """Collect an HTTP quoted string with extract-value set: ``(value, next position)``."""
+    chars: list[str] = []
+    position += 1  # skip the opening quote
+    length = len(data)
+    while position < length:
+        char = data[position]
+        position += 1
+        if char == '"':
+            break
+        if char == "\\":
+            if position >= length:
+                chars.append("\\")
+                break
+            char = data[position]
+            position += 1
+        chars.append(char)
+    return "".join(chars), position
+
+
+def _find(data: str, char: str, start: int) -> int:
+    index = data.find(char, start)
+    return len(data) if index < 0 else index

mediaparse/_mediatype.py

@@ -0,0 +1,86 @@
+"""The parsed media type value."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._errors import MediaTypeError, show
+from ._tokens import ascii_lower, is_quotable, is_token, quote
+
+
+@dataclass(frozen=True)
+class MediaType:
+    """A media type: ``type``, ``subtype`` and ordered ``params`` as ``(name, value)`` pairs.
+
+    Construction checks the parts: type, subtype and parameter names must be tokens and
+    are stored in lower case, names must be unique, and values must fit a quoted string.
+    ``str()`` serializes it the way the WHATWG MIME Sniffing standard does, which is the
+    form browsers expose, for example ``text/html;charset=utf-8``. Equality compares the
+    parameters in order; use :func:`matches` to ignore order and ``charset`` case. A part
+    of the wrong type raises :class:`TypeError`, an invalid one :class:`MediaTypeError`.
+    """
+
+    type: str
+    subtype: str
+    params: tuple[tuple[str, str], ...] = ()
+
+    def __post_init__(self) -> None:
+        for label, part in (("type", self.type), ("subtype", self.subtype)):
+            _require_str(label, part)
+            if not is_token(part):
+                raise MediaTypeError(f"invalid media {label}: {show(part)}")
+        if not isinstance(self.params, (tuple, list)):
+            raise TypeError(f"params must be a tuple of pairs, got {type(self.params).__name__}")
+        names: list[str] = []
+        pairs = tuple(self.params)
+        for pair in pairs:
+            if not isinstance(pair, tuple) or len(pair) != 2:
+                raise TypeError(f"parameters must be (name, value) tuples, got {show(pair)}")
+            name, value = pair
+            _require_str("parameter name", name)
+            _require_str("parameter value", value)
+            if not is_token(name):
+                raise MediaTypeError(f"invalid parameter name: {show(name)}")
+            if not all(is_quotable(char) for char in value):
+                raise MediaTypeError(f"parameter {show(name)} has a value no header can carry")
+            names.append(ascii_lower(name))
+        if len(set(names)) != len(names):
+            raise MediaTypeError("a parameter is given more than once")
+        object.__setattr__(self, "type", ascii_lower(self.type))
+        object.__setattr__(self, "subtype", ascii_lower(self.subtype))
+        lowered = tuple((name, value) for name, (_, value) in zip(names, pairs, strict=True))
+        object.__setattr__(self, "params", lowered)
+
+    @property
+    def essence(self) -> str:
+        """``type/subtype`` without parameters."""
+        return f"{self.type}/{self.subtype}"
+
+    @property
+    def suffix(self) -> str | None:
+        """The structured syntax suffix of RFC 6838 section 4.2.8 (``json`` for ``+json``)."""
+        _, plus, tail = self.subtype.rpartition("+")
+        return tail if plus and tail else None
+
+    @property
+    def parameters(self) -> dict[str, str]:
+        """The parameters as a new ordered dict."""
+        return dict(self.params)
+
+    def get(self, name: str, default: str | None = None) -> str | None:
+        """Return a parameter value by case-insensitive name, or ``default``."""
+        wanted = ascii_lower(name)
+        for key, value in self.params:
+            if key == wanted:
+                return value
+        return default
+
+    def __str__(self) -> str:
+        parts = [self.essence]
+        parts.extend(f"{name}={quote(value)}" for name, value in self.params)
+        return ";".join(parts)
+
+
+def _require_str(label: str, value: object) -> None:
+    if not isinstance(value, str):
+        raise TypeError(f"{label} must be a str, got {type(value).__name__}")

mediaparse/_normalize.py

@@ -0,0 +1,26 @@
+"""Canonicalize and compare media type headers."""
+
+from __future__ import annotations
+
+from ._parse import parse_media_type
+from ._tokens import ascii_lower, quote
+
+
+def normalize(header: str, *, strict: bool = False) -> str:
+    """Return a canonical form of the header for display or comparison.
+
+    The header is read like :func:`parse_media_type`. The media type and parameter names
+    are lower-cased, parameters are sorted by name and the ``charset`` value is lower-cased
+    (it is case insensitive, RFC 2046 section 4.1.2). Other values keep their case, since
+    a filename or boundary is significant. The output uses ``"; "`` between parts.
+    """
+    media = parse_media_type(header, strict=strict)
+    parts = [media.essence]
+    for name, value in sorted(media.params):
+        parts.append(f"{name}={quote(ascii_lower(value) if name == 'charset' else value)}")
+    return "; ".join(parts)
+
+
+def matches(first: str, second: str) -> bool:
+    """Return whether two headers denote the same media type and parameters."""
+    return normalize(first) == normalize(second)

mediaparse/_parse.py

@@ -0,0 +1,27 @@
+"""Parse a Content-Type style header into a media type and its parameters."""
+
+from __future__ import annotations
+
+from ._lenient import parse_lenient
+from ._mediatype import MediaType
+from ._strict import parse_strict
+
+
+def parse_media_type(text: str, *, strict: bool = False) -> MediaType:
+    """Parse a media type header value into a :class:`MediaType`.
+
+    By default the WHATWG MIME Sniffing algorithm is used, so the result is what a browser
+    would read: whitespace is trimmed, parameters a browser would ignore are skipped and
+    the first of a repeated parameter wins. With ``strict=True`` the text must match the
+    RFC 9110 grammar exactly and a repeated parameter is an error. Either way a value with
+    no valid ``type/subtype`` raises :class:`MediaTypeError`.
+    """
+    if not isinstance(text, str):
+        raise TypeError(f"expected str, got {type(text).__name__}")
+    return parse_strict(text) if strict else parse_lenient(text)
+
+
+def parse(header: str, *, strict: bool = False) -> tuple[str, dict[str, str]]:
+    """Split a media type header into ``(essence, params)``, see :func:`parse_media_type`."""
+    media = parse_media_type(header, strict=strict)
+    return media.essence, media.parameters

mediaparse/_rfc2231.py

@@ -0,0 +1,102 @@
+"""Join RFC 2231 parameter continuations and decode charset-encoded values."""
+
+from __future__ import annotations
+
+import codecs
+import re
+from collections.abc import Mapping
+
+from ._errors import MediaTypeError, show
+from ._extended import percent_decode
+from ._tokens import ascii_lower
+
+# attribute, optional section (no leading zeros, at most nine digits), optional "*" for an
+# encoded value.
+_NAME = re.compile(r"(?P<attr>[^*]+)(?:\*(?P<section>0|[1-9][0-9]{0,8}))?(?P<encoded>\*)?")
+_INITIAL = re.compile(r"(?P<charset>[^']*)'(?P<language>[^']*)'(?P<rest>.*)", re.DOTALL)
+# mime-charset characters from RFC 8187 section 3.2.1.
+_CHARSET = re.compile(r"[A-Za-z0-9!#$%&+\-^_`{}~]+")
+# Python text codecs that are not character sets: escape decoders, host code pages and
+# transforms. A header must not decide to run them.
+_NOT_CHARSETS = frozenset({"mbcs", "oem", "idna", "punycode", "undefined"})
+
+
+def decode_extended(params: Mapping[str, str]) -> dict[str, str]:
+    """Return ``params`` with RFC 2231 continuations joined and encoded values decoded.
+
+    ``title*0*=us-ascii'en'This%20is``, ``title*1=" fun"`` become ``title="This is fun"``.
+    Names are compared in ASCII lower case and results keep the order in which each name
+    first appears. When both ``name`` and an extended form are present the extended form
+    wins, as it is the one that carries the real value. The language tag is dropped.
+    Gaps or leading zeros in the sections, a section given twice, a bad percent escape, a
+    charset that is not a character set Python can decode, and bytes it cannot decode
+    raise :class:`MediaTypeError`.
+    """
+    if not isinstance(params, Mapping):
+        raise TypeError(f"params must be a mapping, got {type(params).__name__}")
+    order: dict[str, None] = {}
+    plain: dict[str, str] = {}
+    pieces: dict[str, dict[int, tuple[bool, str]]] = {}
+    for raw, value in params.items():
+        if not isinstance(raw, str) or not isinstance(value, str):
+            raise TypeError("parameter names and values must be str")
+        name = ascii_lower(raw)
+        if "*" not in name:
+            order.setdefault(name)
+            plain[name] = value
+            continue
+        match = _NAME.fullmatch(name)
+        if match is None:
+            raise MediaTypeError(f"invalid extended parameter name: {show(raw)}")
+        attr, section = match["attr"], match["section"]
+        order.setdefault(attr)
+        index = -1 if section is None else int(section)
+        slot = pieces.setdefault(attr, {})
+        if index in slot:
+            raise MediaTypeError(f"parameter {show(attr)} section {section} is given twice")
+        slot[index] = (match["encoded"] is not None, value)
+    return {attr: _join(attr, pieces[attr]) if attr in pieces else plain[attr] for attr in order}
+
+
+def _join(attr: str, slot: dict[int, tuple[bool, str]]) -> str:
+    label = show(attr)
+    if -1 in slot:
+        if len(slot) > 1:
+            raise MediaTypeError(f"parameter {label} mixes the unnumbered and numbered forms")
+        slot = {0: slot[-1]}
+    if sorted(slot) != list(range(len(slot))):
+        raise MediaTypeError(f"parameter {label} has missing sections")
+    charset = "us-ascii"
+    data = bytearray()
+    for index in range(len(slot)):
+        encoded, value = slot[index]
+        if encoded and index == 0:
+            initial = _INITIAL.fullmatch(value)
+            if initial is None:
+                raise MediaTypeError(f"parameter {label} lacks the charset'language' prefix")
+            charset = initial["charset"] or "us-ascii"
+            value = initial["rest"]
+        if encoded:
+            data += percent_decode(value)
+        elif value.isascii():
+            data += value.encode("ascii")
+        else:
+            raise MediaTypeError(f"parameter {label} has non-ASCII text in a plain section")
+    return _decode(bytes(data), charset, label)
+
+
+def _decode(data: bytes, charset: str, label: str) -> str:
+    if _CHARSET.fullmatch(charset) is None:
+        raise MediaTypeError(f"invalid charset name {show(charset)}")
+    try:
+        name = codecs.lookup(charset).name
+    except LookupError as error:
+        raise MediaTypeError(f"unknown charset {show(charset)}") from error
+    if name in _NOT_CHARSETS or "escape" in name:
+        raise MediaTypeError(f"{show(charset)} is not a character set")
+    try:
+        return data.decode(charset)
+    except LookupError as error:
+        raise MediaTypeError(f"{show(charset)} is not a text encoding") from error
+    except (UnicodeError, ValueError) as error:
+        raise MediaTypeError(f"parameter {label} is not valid {show(charset)}") from error

mediaparse/_strict.py

@@ -0,0 +1,115 @@
+"""The RFC 9110 ``media-type`` grammar, exactly, with the position of the first error.
+
+    media-type = type "/" subtype parameters               ; section 8.3.1
+    parameters = *( OWS ";" OWS [ parameter ] )            ; section 5.6.6
+    parameter  = token "=" ( token / quoted-string )       ; no whitespace around "="
+
+Leading and trailing OWS is skipped, since a field parser removes it before the value is
+read (section 5.5). A parameter given twice is an error, as RFC 6838 section 4.3 says.
+"""
+
+from __future__ import annotations
+
+from ._errors import MediaTypeError, show
+from ._mediatype import MediaType
+from ._tokens import OWS, TOKEN_CHARS, ascii_lower
+
+
+def parse_strict(text: str, quoted: set[str] | None = None) -> MediaType:
+    """Parse ``text`` against the RFC 9110 grammar, raising on the first deviation.
+
+    The names of parameters written as quoted strings are added to ``quoted`` if given.
+    """
+    reader = _Reader(text)
+    reader.skip_ows()
+    main = reader.token("media type")
+    reader.expect("/")
+    subtype = reader.token("media subtype")
+    params: dict[str, str] = {}
+    while True:
+        reader.skip_ows()
+        if reader.done():
+            break
+        reader.expect(";")
+        reader.skip_ows()
+        if reader.done() or reader.peek() == ";":
+            continue
+        start = reader.position
+        name = ascii_lower(reader.token("parameter name"))
+        if name in params:
+            raise MediaTypeError(f"parameter {show(name)} is given more than once", position=start)
+        reader.expect("=")
+        if reader.peek() == '"':
+            params[name] = reader.quoted()
+            if quoted is not None:
+                quoted.add(name)
+        else:
+            params[name] = reader.token("value")
+    return MediaType(main, subtype, tuple(params.items()))
+
+
+class _Reader:
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.position = 0
+
+    def done(self) -> bool:
+        return self.position >= len(self.text)
+
+    def peek(self) -> str:
+        return self.text[self.position : self.position + 1]
+
+    def fail(self, message: str) -> MediaTypeError:
+        found = self.peek()
+        where = f"found {found!r}" if found else "found the end"
+        return MediaTypeError(
+            f"{message} at position {self.position}, {where}: {show(self.text)}",
+            position=self.position,
+        )
+
+    def skip_ows(self) -> None:
+        while self.peek() and self.peek() in OWS:
+            self.position += 1
+
+    def expect(self, char: str) -> None:
+        if self.peek() != char:
+            raise self.fail(f"expected {char!r}")
+        self.position += 1
+
+    def token(self, label: str) -> str:
+        start = self.position
+        while self.peek() and self.peek() in TOKEN_CHARS:
+            self.position += 1
+        if self.position == start:
+            raise self.fail(f"expected a token for the {label}")
+        return self.text[start : self.position]
+
+    def quoted(self) -> str:
+        self.position += 1  # the opening quote
+        chars: list[str] = []
+        while True:
+            char = self.peek()
+            if not char:
+                raise self.fail("unterminated quoted string")
+            if char == '"':
+                self.position += 1
+                return "".join(chars)
+            if char == "\\":
+                self.position += 1
+                char = self.peek()
+                if not (char and _quoted_pair(char)):
+                    raise self.fail("invalid escape in quoted string")
+            elif not _qdtext(char):
+                raise self.fail("character not allowed in a quoted string")
+            chars.append(char)
+            self.position += 1
+
+
+def _qdtext(char: str) -> bool:
+    # HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text
+    return char in "\t !" or "#" <= char <= "[" or "]" <= char <= "~" or "\x80" <= char <= "\xff"
+
+
+def _quoted_pair(char: str) -> bool:
+    # "\" ( HTAB / SP / VCHAR / obs-text )
+    return char in "\t " or "!" <= char <= "~" or "\x80" <= char <= "\xff"

mediaparse/_tokens.py

@@ -0,0 +1,44 @@
+"""Character classes shared by the parsers, the builder and the Accept reader."""
+
+from __future__ import annotations
+
+# tchar from RFC 9110 section 5.6.2; WHATWG calls these HTTP token code points.
+TOKEN_CHARS = frozenset(
+    "!#$%&'*+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+)
+# HTTP whitespace in the WHATWG Fetch standard: tab, LF, CR and space.
+HTTP_WHITESPACE = "\t\n\r "
+# OWS in RFC 9110 section 5.6.3: space and horizontal tab only.
+OWS = " \t"
+
+_LOWER = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+
+
+def ascii_lower(text: str) -> str:
+    """Lower-case A to Z only; ``str.lower`` would also fold non-ASCII letters into ASCII."""
+    return text.translate(_LOWER)
+
+
+def is_token(value: str) -> bool:
+    """Return whether the value is a non-empty RFC 9110 token."""
+    return bool(value) and all(char in TOKEN_CHARS for char in value)
+
+
+def is_quotable(char: str) -> bool:
+    """Return whether a quoted string can carry the character (tab, 0x20-0x7E, 0x80-0xFF).
+
+    This is the WHATWG "HTTP quoted-string token code point" set, the same characters that
+    RFC 9110 ``qdtext`` and ``quoted-pair`` reach together.
+    """
+    return char == "\t" or " " <= char <= "~" or "\x80" <= char <= "\xff"
+
+
+def quote(value: str) -> str:
+    """Write a parameter value as a token when it is one, as a quoted string otherwise.
+
+    Only the double quote and the backslash are escaped, as RFC 9110 section 5.6.4 asks.
+    """
+    if is_token(value):
+        return value
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

mediaparse-0.2.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: mediaparse
+Version: 0.2.0
+Summary: Parse and build HTTP media types, Content-Type and Accept headers, exactly
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/mediaparse
+Project-URL: Issues, https://github.com/JaviLianes8/mediaparse/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/mediaparse/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: accept,cgi,content-negotiation,content-type,header,http,media-type,mime,rfc2231,rfc9110,whatwg
+Classifier: Development Status :: 4 - Beta
+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
+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
+
+# mediaparse
+
+Parse and build HTTP media types, `Content-Type` and `Accept` headers, exactly.
+
+## Install
+
+```
+pip install mediaparse
+```
+
+## Usage
+
+```python
+from mediaparse import build, matches, normalize, parse, parse_media_type
+
+# Read a Content-Type value the way a browser does.
+print(parse("text/html; charset=utf-8"))
+# ('text/html', {'charset': 'utf-8'})
+
+# Quoted values keep separators; text after the closing quote is skipped.
+print(parse('multipart/form-data; boundary="a; b=c"'))
+# ('multipart/form-data', {'boundary': 'a; b=c'})
+
+# A typed value with the essence, the +suffix and the browser serialization.
+media = parse_media_type("Application/Vnd.API+JSON; Charset=UTF-8")
+print(media.essence, media.suffix, media.get("charset"))
+# application/vnd.api+json json UTF-8
+print(media)
+# application/vnd.api+json;charset=UTF-8
+
+# Build a header, quoting only the values that need it.
+print(build("application/json", {"title": "a; b"}))
+# application/json; title="a; b"
+
+# Canonical form for display or comparison.
+print(normalize("TEXT/HTML; CharSet=UTF-8"))
+# text/html; charset=utf-8
+print(matches("Text/HTML; charset=UTF-8", "text/html;charset=utf-8"))
+# True
+```
+
+### Lenient or strict
+
+```python
+from mediaparse import MediaTypeError, parse
+
+# Default: the WHATWG algorithm. The first of a repeated parameter wins and a parameter
+# with whitespace before "=" is skipped, exactly as browsers do.
+print(parse("text/plain; charset=ascii; charset=utf-8; a =1"))
+# ('text/plain', {'charset': 'ascii'})
+
+# strict=True: the RFC 9110 grammar, with the position of the first bad character.
+try:
+    parse("text/plain; a =1", strict=True)
+except MediaTypeError as error:
+    print(error.position)
+# 13
+```
+
+### Building safely
+
+```python
+from mediaparse import MediaTypeError, build
+
+# No value can split the header: control characters are refused.
+try:
+    build("text/plain", {"name": "x\r\nSet-Cookie: a=b"})
+except MediaTypeError:
+    print("refused")
+# refused
+
+# Non-ASCII values travel as RFC 8187 / RFC 2231 extended values on request.
+print(build("text/plain", {"title": "caf\xe9"}, extended=True))
+# text/plain; title*=UTF-8''caf%C3%A9
+```
+
+### Accept and negotiation
+
+```python
+from mediaparse import negotiate, parse_accept, quality
+
+accept = "text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, */*;q=0.5"
+
+# The weight comes from the most specific range that covers the offer.
+print(quality(accept, "text/plain;format=flowed"), quality(accept, "text/html"))
+# 1.0 0.3
+
+# Pick the best offer; ties go to the order you list them in.
+print(negotiate(accept, ["image/png", "text/html"]))
+# image/png
+
+print([(str(item.media_range), item.q) for item in parse_accept("text/html, */*;q=0.1")])
+# [('text/html', 1.0), ('*/*', 0.1)]
+```
+
+### RFC 2231 parameters
+
+```python
+from mediaparse import decode_extended, parse
+
+header = "application/x-stuff; title*0*=utf-8''r%C3%A9sum; title*1=\"e.pdf\""
+print(decode_extended(parse(header)[1]))
+# {'title': 'résume.pdf'}
+```
+
+## API
+
+| Name | What it does |
+| --- | --- |
+| `parse(header, *, strict=False)` | `(essence, params)` tuple. |
+| `parse_media_type(text, *, strict=False)` | A `MediaType`; raises `MediaTypeError` when there is no valid `type/subtype`. |
+| `MediaType` | Frozen value: `type`, `subtype`, `params` pairs, `essence`, `suffix`, `parameters`, `get()`, `str()`. |
+| `build(mimetype, params=None, *, extended=False)` | Header value with `"; "` between parts and minimal quoting. |
+| `normalize(header, *, strict=False)` | Lower-cased names, sorted parameters, lower-cased `charset`. |
+| `matches(first, second)` | Whether two headers normalize to the same text. |
+| `parse_accept(header, *, strict=False)` | List of `AcceptItem` in header order. |
+| `AcceptItem` | `media_range` (a `MediaType`), `q` (0 to 1), `specificity()`, `matches(media)`. |
+| `quality(accept, offer)` | Weight of an offer under an Accept header; `None` means no header. |
+| `negotiate(accept, offers)` | Best acceptable offer, returned as given, or `None`. |
+| `decode_extended(params)` | Joins RFC 2231 sections and decodes `charset'lang'` values. |
+| `MediaTypeError` | `ValueError` subclass with `position` (or `None`). Wrong argument types raise `TypeError`. |
+
+## Rules it follows
+
+- **Default parsing** is the WHATWG MIME Sniffing "parse a MIME type" algorithm, checked
+  against the web-platform-tests MIME type corpus. Whitespace (tab, LF, CR, space) is
+  trimmed, a parameter whose name is not a token or whose value has a character above
+  U+00FF or a control character is skipped, empty values are skipped and the first
+  duplicate wins. `str(MediaType)` is the WHATWG serialization.
+- **Strict parsing** is the RFC 9110 `media-type` grammar: no whitespace around `=`,
+  values are tokens or quoted strings with `qdtext` and `quoted-pair` only, and a repeated
+  parameter is an error (RFC 6838 section 4.3). Leading and trailing spaces or tabs are
+  allowed because a field parser removes them.
+- **Names** are lower-cased in ASCII only, so a character such as the Kelvin sign never
+  turns into a token. Values keep their case; `normalize` and `quality` treat `charset`
+  as case insensitive.
+- **Building** never writes a control character or a non-ASCII character into the
+  header: by default such a value raises, and with `extended=True` it is percent-encoded
+  as `name*=UTF-8''...` (names may not end in `*` then). Two parameters that would be
+  written under one name raise. The output is always one valid header field value.
+- **Accept**: elements split on commas outside quoted strings, empty elements are
+  ignored, `q` must match the `qvalue` grammar (up to three decimals, at most 1) and may
+  appear anywhere among the parameters. In the default mode an invalid element is
+  skipped, including one whose `q` is malformed (`q =0`, `q=`), so a broken weight never
+  counts as 1. In strict mode only spaces and tabs may surround an element. A missing field (`None`) accepts everything; an empty one accepts nothing; a
+  weight of 0 means not acceptable. On equally specific ranges the earliest one counts.
+- **RFC 2231**: sections start at 0 without gaps or leading zeros, encoded and plain
+  sections may mix, a character may span sections, and `name*` wins over `name`. The
+  language tag is dropped. Names compare in ASCII lower case. The charset must be a
+  charset name Python can decode as text; escape decoders, host code pages (`mbcs`,
+  `oem`), `idna` and `punycode` are refused.
+
+## Why
+
+Python 3.13 removed `cgi.parse_header` along with the rest of the `cgi` module. The
+documented replacement, the `email.message.Message` machinery, is parse-oriented with no
+clean builder and mishandles repeated parameters, so projects keep copying a parser by
+hand. `multipart.parse_options_header` is scoped to form data and parse-only, and
+`ietfparse` is a broad multi-RFC toolkit. `mediaparse` is a small, typed,
+zero-dependency library that parses the way browsers do, validates the way the RFC says,
+builds headers that cannot be split, and negotiates `Accept`.
+
+## Development
+
+`python scripts/fetch_upstream.py` downloads the web-platform-tests MIME type files listed
+in `tests/upstream/MANIFEST.json` (they are not part of the repository; their tests skip
+without them). `scripts/check.ps1` runs format, lint, types and tests. Set
+`MEDIAPARSE_E2E=1` to also build the wheel and test the installed package.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

mediaparse-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mediaparse/__init__.py,sha256=85WfPSvUEnNJYsXE9uihyfEpTMCRR3Q6nRefcT_G8sA,658
+mediaparse/_accept.py,sha256=zxw3IgCvb-lMMq1L9lkccrpYK5iCH8RnfJEOo8ze36o,6979
+mediaparse/_build.py,sha256=23kV8UpNlRQqfl-whNyAE3dmcevfAvuQW5E8Kt3JVmo,3130
+mediaparse/_errors.py,sha256=96_0LPb7JWlYa-YClHDKZUWHu1gRJlfRMZahaCmYeKI,774
+mediaparse/_extended.py,sha256=3OuiTTAj1Kt-LN7NACLfF0aGTZFahZU5xDkO0nVVC20,1636
+mediaparse/_lenient.py,sha256=-lIvkIT84j2Ob4_Sao0VpwiLyDEdXOCvfzVMx4oUy6c,3137
+mediaparse/_mediatype.py,sha256=zvnVaY6QRhLMthaIn3Q0x-6EOs6zVIjI13JLsmwdBYs,3656
+mediaparse/_normalize.py,sha256=0nM47LftsKMcerBfdXkSC8x1TkJzhJJDfCWfz1naI7I,1084
+mediaparse/_parse.py,sha256=3AlhJIonqp74WVbsOduDlO7Ja3ELdr7OHo3BiiBCwvw,1226
+mediaparse/_rfc2231.py,sha256=WAE1W61K-uSjdryuixwPhsJ9tUN6DyG5sqOLC35bHdM,4650
+mediaparse/_strict.py,sha256=5P9LzW3djLvdcZsP2rSh86TZ4A8ggmN7p-vQpIRvhGk,4074
+mediaparse/_tokens.py,sha256=8ipvBIfR8qmSFbGsMW84U1F1--PDTpFsaUHmipak0lM,1620
+mediaparse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mediaparse-0.2.0.dist-info/METADATA,sha256=aYz0HIXZjAZGTdfRKzn1VEB3htIr0KuqdXHqEhq03ic,9195
+mediaparse-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mediaparse-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+mediaparse-0.2.0.dist-info/RECORD,,

mediaparse-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

mediaparse-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.