primarysource 0.1.0__py3-none-any.whl

primarysource/readers/markdown.py

@@ -0,0 +1,189 @@
+"""A small, strict Markdown reader: headings, blocks, front matter. The core's `cl.reader_markdown`.
+
+Written for the C2SP specifications (`primarysource/c2sp/markdown.py`, now a re-export of this module). It reads
+the subset those specifications use and nothing else is interpreted: ATX headings (`#` to `######`),
+setext headings over one paragraph line, fenced code (backticks or tildes), blank-line-separated blocks, and a
+leading `---` front-matter block of `key: value` lines. HTML, links and images are never followed or rendered;
+a heading's title is its text with link targets, emphasis marks and code ticks removed.
+
+Input is bounded (`MAX_BYTES`, `MAX_LINE`, `MAX_SECTIONS`) because the text of a specification is untrusted data:
+a document over a bound is refused with a `LibError`, never truncated.
+
+Units: `¶n` counts blocks. A block is a blank-line-separated chunk of lines, or one whole fenced code block
+(blank lines inside a fence do not split it). A section's units are every block from its heading to the next
+heading of the same or a higher level, subsection headings included as blocks, its own heading excluded.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+
+from primarysource.errors import LibError
+
+MAX_BYTES = 4 * 1024 * 1024
+MAX_LINE = 20_000
+MAX_SECTIONS = 20_000
+
+_ATX = re.compile(r"^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$")
+_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+_SETEXT = re.compile(r"^ {0,3}(=+|-+)[ \t]*$")
+_LINK = re.compile(r"!?\[([^\]]*)\]\([^)]*\)")
+_REFLINK = re.compile(r"\[([^\]]+)\]\[[^\]]*\]")
+_TAG = re.compile(r"<[^>\n]*>")
+_MARKS = re.compile(r"[`*_~]+")
+_SLUG_DROP = re.compile(r"[^\w\- ]", re.UNICODE)
+
+
+@dataclass(frozen=True, slots=True)
+class Heading:
+    """One section of a document, in document order. `units` are its blocks (see the module docstring)."""
+
+    title: str
+    slug: str
+    level: int
+    units: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class MarkdownDocument:
+    """What the reader found. `preamble` is the blocks before the first heading; `title` is the first level-1
+    heading, else the front matter's `title`, else empty."""
+
+    front: dict[str, str]
+    title: str
+    preamble: tuple[str, ...]
+    headings: tuple[Heading, ...]
+
+    def units(self) -> tuple[str, ...]:
+        """The whole document as units: the preamble, then every block of every top-level section, with each
+        heading as a block of its own."""
+        if not self.headings:
+            return self.preamble
+        top = min(h.level for h in self.headings)
+        out = list(self.preamble)
+        for heading in self.headings:
+            if heading.level == top:
+                out.append(f"{'#' * heading.level} {heading.title}")
+                out.extend(heading.units)
+        return tuple(out)
+
+
+def plain(text: str) -> str:
+    """A heading's text without Markdown: links reduced to their text, tags, ticks and emphasis marks removed."""
+    text = _LINK.sub(r"\1", text)
+    text = _REFLINK.sub(r"\1", text)
+    text = _TAG.sub("", text)
+    text = _MARKS.sub("", text)
+    return " ".join(text.split())
+
+
+def slugify(title: str) -> str:
+    """The GitHub-style anchor of a title: lower case, punctuation dropped, spaces to hyphens."""
+    folded = unicodedata.normalize("NFKC", title).lower()
+    return _SLUG_DROP.sub("", folded).strip().replace(" ", "-")
+
+
+def _front_matter(lines: list[str]) -> tuple[dict[str, str], int]:
+    """Parse a leading `---` block of `key: value` lines; return it and the index of the first body line."""
+    if not lines or lines[0].strip() != "---":
+        return {}, 0
+    for end in range(1, min(len(lines), 60)):
+        if lines[end].strip() == "---":
+            front: dict[str, str] = {}
+            for line in lines[1:end]:
+                key, sep, value = line.partition(":")
+                if sep and re.fullmatch(r"[A-Za-z][\w-]*", key.strip()):
+                    front[key.strip()] = value.strip().strip("\"'")
+            return front, end + 1
+    return {}, 0
+
+
+def decode(data: bytes) -> str:
+    """UTF-8 text from bytes, or a `LibError`: over the bound, not UTF-8, or containing a NUL."""
+    if len(data) > MAX_BYTES:
+        raise LibError(f"document is {len(data)} bytes, over the {MAX_BYTES} byte bound", "")
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise LibError("document is not valid UTF-8", "re-import it; the pinned file is UTF-8") from exc
+    if "\x00" in text:
+        raise LibError("document contains a NUL byte", "re-import it; the pinned file is plain text")
+    return text
+
+
+def parse(data: bytes | str) -> MarkdownDocument:
+    """Parse one document. Raises `LibError` for a document that is not UTF-8 text or exceeds a bound."""
+    text = decode(data) if isinstance(data, bytes) else data
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    if any(len(line) > MAX_LINE for line in lines):
+        raise LibError(f"document has a line over {MAX_LINE} characters", "")
+    front, first = _front_matter(lines)
+
+    # pass 1: split into (kind, level, text) items: headings and blocks, fences kept whole
+    items: list[tuple[str, int, str]] = []
+    paragraph: list[str] = []
+    fence: tuple[str, int] | None = None
+    fenced: list[str] = []
+
+    def flush() -> None:
+        if paragraph:
+            items.append(("block", 0, "\n".join(paragraph)))
+            paragraph.clear()
+
+    for line in lines[first:]:
+        if fence is not None:
+            fenced.append(line)
+            close = _FENCE.match(line)
+            if close and close.group(1)[0] == fence[0] and len(close.group(1)) >= fence[1] and not line.strip(" `~"):
+                items.append(("block", 0, "\n".join(fenced)))
+                fence, fenced = None, []
+            continue
+        opening = _FENCE.match(line)
+        if opening:
+            flush()
+            fence, fenced = (opening.group(1)[0], len(opening.group(1))), [line]
+            continue
+        if not line.strip():
+            flush()
+            continue
+        atx = _ATX.match(line)
+        if atx:
+            flush()
+            items.append(("heading", len(atx.group(1)), plain(atx.group(2) or "")))
+            continue
+        setext = _SETEXT.match(line)
+        if setext and len(paragraph) == 1 and not paragraph[0].lstrip().startswith(("-", "*", ">", "|")):
+            items.append(("heading", 1 if setext.group(1)[0] == "=" else 2, plain(paragraph[0])))
+            paragraph.clear()
+            continue
+        paragraph.append(line)
+    if fence is not None:  # an unclosed fence runs to the end of the document, as in CommonMark
+        items.append(("block", 0, "\n".join(fenced)))
+    flush()
+
+    # pass 2: assign blocks to sections
+    spans = [(body, level, index) for index, (kind, level, body) in enumerate(items) if kind == "heading"]
+    if len(spans) > MAX_SECTIONS:
+        raise LibError(f"document has {len(spans)} headings, over the {MAX_SECTIONS} bound", "")
+    first_heading = spans[0][2] if spans else len(items)
+    preamble = tuple(body for kind, _, body in items[:first_heading] if kind == "block")
+    headings: list[Heading] = []
+    seen: dict[str, int] = {}
+    for n, (title, level, start) in enumerate(spans):
+        end = len(items)
+        for _, later_level, later in spans[n + 1 :]:
+            if later_level <= level:
+                end = later
+                break
+        units = tuple(
+            f"{'#' * item_level} {body}".rstrip() if kind == "heading" else body
+            for kind, item_level, body in items[start + 1 : end]
+        )
+        slug = slugify(title)
+        count = seen.get(slug, 0)
+        seen[slug] = count + 1
+        headings.append(Heading(title, slug if count == 0 else f"{slug}-{count}", level, units))
+    top = next((h.title for h in headings if h.level == 1), "")
+    return MarkdownDocument(front, top or front.get("title", ""), preamble, tuple(headings))

primarysource/readers/pdf.py

@@ -0,0 +1,187 @@
+"""Read a publisher's PDF into bookmarked sections of sentences (`cl.reader_pdf_pypdf`).
+
+`pypdf` is an ingest-time extra (PLAN.md §5.13): it is imported inside the functions that need it, never at
+module level, so a server that answers from stored extractions imports this module without it. Asking for a PDF
+read without it is a `LibError` naming the extra, not an `ImportError`.
+
+Lifted from the ecma collection's private reader (`primarysource/ecma/_pdf.py`, now a re-export), with its tests.
+The bookmarks always come from `pypdf`; the page text comes from `pdftotext` (poppler or Xpdf) when it is on PATH
+and a path to the PDF is given, else from `pypdf`. Backends give different text, so the backend's name and
+version are in every extraction (`extractor`) and are what an index puts into its source hash (PLAN.md §4).
+Figures, tables and equations are whatever the backend extracts: expect broken columns.
+
+Cutting the page texts into sections is `primarysource.readers.bookmarks` (`cl.segment_bookmarks`).
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import shutil
+import subprocess  # noqa: S404 - runs the user's own pdftotext on a PDF whose sha256 the caller pinned
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+from typing import Any, NamedTuple
+
+from primarysource.errors import LibError
+from primarysource.readers.bookmarks import Outline, cut, cut_numbered
+
+MAX_BYTES = 64 * 1024 * 1024
+MAX_PAGES = 2000
+MAX_OUTLINE = 6000
+INSTALL_HINT = 'pip install "primarysource[ecma]"  (or [bbf], [ieee], [itu], [iso]); each brings pypdf'
+
+_PDFTOTEXT_VERSION = re.compile(rb"pdftotext\s+version\s+(\S+)", re.IGNORECASE)
+
+
+class Backend(NamedTuple):
+    """The program that produced a text: what an index hashes so a change of backend rebuilds it."""
+
+    name: str
+    version: str
+
+    def label(self) -> str:
+        """`name version`, the form stored as an extraction's `extractor`."""
+        return f"{self.name} {self.version}"
+
+
+def _pypdf() -> ModuleType:
+    try:
+        import pypdf
+    except ImportError as exc:  # ModuleNotFoundError, or None in sys.modules
+        raise LibError("reading a PDF needs pypdf, which is not installed", INSTALL_HINT) from exc
+    return pypdf
+
+
+def pypdf_backend() -> Backend:
+    """`pypdf` and its version, or a `LibError` naming the extra when it is not installed."""
+    return Backend("pypdf", str(_pypdf().__version__))
+
+
+def pdftotext_backend() -> Backend | None:
+    """`pdftotext` and the version it reports, or None when it is not on PATH. A version it does not report is
+    `unknown`."""
+    exe = shutil.which("pdftotext")
+    if exe is None:
+        return None
+    try:
+        done = subprocess.run([exe, "-v"], capture_output=True, timeout=30, check=False)  # noqa: S603 - fixed argv
+    except (OSError, subprocess.SubprocessError):
+        return None
+    found = _PDFTOTEXT_VERSION.search(done.stderr + b"\n" + done.stdout)
+    return Backend("pdftotext", found.group(1).decode("ascii", errors="replace") if found else "unknown")
+
+
+def _page_of(reader: Any, item: Any) -> int:
+    """The 0-based page a bookmark points at, or -1 if its destination is unusable."""
+    try:
+        return int(reader.get_destination_page_number(item))
+    except Exception:  # noqa: BLE001 - pypdf raises many types for a broken destination
+        return -1
+
+
+def outline(reader: Any) -> Outline:
+    """A `pypdf.PdfReader`'s bookmark tree flattened to (title, 0-based page, depth), in document order, bounded
+    by `MAX_OUTLINE` entries and 12 levels."""
+    flat: Outline = []
+
+    def walk(items: Sequence[Any], depth: int) -> None:
+        for item in items:
+            if len(flat) >= MAX_OUTLINE or depth > 12:
+                return
+            if isinstance(item, list):
+                walk(item, depth + 1)
+                continue
+            page = _page_of(reader, item)
+            title = " ".join(str(item.title).split())
+            if title and page >= 0:
+                flat.append((title, page, depth))
+
+    walk(reader.outline, 0)
+    return flat
+
+
+def pdftotext_pages(path: Path, count: int, *, layout: bool = False) -> list[str] | None:
+    """The page texts from `pdftotext` if it is on PATH and returns `count` pages, else None. Its text keeps word
+    spacing that `pypdf` loses on some fonts, and puts headings where they are read. `layout` keeps the page's
+    columns (`-layout`), which the numbered-heading splitter reads contents rows and table cells by."""
+    exe = shutil.which("pdftotext")
+    if exe is None:
+        return None
+    argv = [exe, *(["-layout"] if layout else []), "-enc", "UTF-8", "-q", str(path), "-"]
+    try:
+        done = subprocess.run(argv, capture_output=True, timeout=300, check=False)  # noqa: S603 - no shell
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if done.returncode != 0:
+        return None
+    pages = done.stdout.decode("utf-8", errors="replace").split("\f")
+    if pages and not pages[-1].strip():
+        pages.pop()
+    return pages if len(pages) == count else None
+
+
+def extract(data: bytes, path: Path | None = None, *, numbered: bool = False) -> dict[str, Any]:
+    """Read a PDF into `{"title", "pages", "extractor", "pypdf", "headings_found", "sections": [{"id", "title",
+    "depth", "page", "text"}]}`.
+
+    `text` is the section's sentences joined by newlines. `extractor` is the backend that gave the page text, as
+    `name version` (`Backend.label`); `pypdf` is the version that gave the bookmarks. If `path` names the PDF on
+    disk and `pdftotext` is on PATH, its page text is used; otherwise `pypdf`'s, in content-stream order first,
+    and if fewer than 70% of the bookmarked headings are found in it as lines (some typesetters emit headings out
+    of order) the pages are re-read in `layout` mode and the better result is kept. With `numbered`, a PDF without
+    bookmarks is cut at numbered headings instead (`bookmarks.cut_numbered`), and `segmenter` says which was used.
+    Raises `LibError` for a PDF that is too large, cannot be read, has no bookmarks (and, with `numbered`, fewer
+    than 3 numbered headings), or when `pypdf` is not installed."""
+    if len(data) > MAX_BYTES:
+        raise LibError(f"PDF is {len(data)} bytes, over the {MAX_BYTES} byte bound", "")
+    pypdf = _pypdf()
+    try:
+        reader = pypdf.PdfReader(io.BytesIO(data), strict=False)
+        count = len(reader.pages)
+        if count > MAX_PAGES:
+            raise LibError(f"PDF has {count} pages, over the {MAX_PAGES} bound", "")
+        bookmarks = outline(reader)
+        if not bookmarks and not numbered:
+            raise LibError("the PDF has no bookmarks to split it into sections", "this reader needs a bookmarked PDF")
+        meta = reader.metadata
+        title = str(meta.title) if meta is not None and meta.title else ""
+        external = pdftotext_pages(path, count, layout=not bookmarks) if path is not None else None
+        backend = Backend("pypdf", str(pypdf.__version__))
+        if not bookmarks:
+            if external is not None:
+                backend = pdftotext_backend() or Backend("pdftotext", "unknown")
+            texts = external
+            if texts is None:
+                texts = [str(p.extract_text(extraction_mode="layout") or "") for p in reader.pages]
+            sections, located = cut_numbered(texts)
+            if located < 3:
+                raise LibError(
+                    "the PDF has no bookmarks, and fewer than 3 numbered headings were found in its text",
+                    "this reader needs a bookmarked PDF or numbered clause headings",
+                )
+        elif external is not None:
+            backend = pdftotext_backend() or Backend("pdftotext", "unknown")
+            sections, located = cut(external, bookmarks)
+        else:
+            sections, located = cut([str(reader.pages[i].extract_text() or "") for i in range(count)], bookmarks)
+        if bookmarks and external is None and located * 10 < len(bookmarks) * 7:
+            layout = [str(reader.pages[i].extract_text(extraction_mode="layout") or "") for i in range(count)]
+            better, better_located = cut(layout, bookmarks)
+            if better_located > located:
+                sections, located = better, better_located
+    except LibError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - pypdf raises many types on hostile input
+        message = f"could not read the PDF: {type(exc).__name__}: {exc}"
+        raise LibError(message, "check the file is the publisher's PDF") from exc
+    return {
+        "title": title,
+        "pages": count,
+        "extractor": backend.label(),
+        "pypdf": pypdf.__version__,
+        "headings_found": located,
+        "segmenter": "bookmarks" if bookmarks else "numbered headings",
+        "sections": sections,
+    }

primarysource/readers/xml.py

@@ -0,0 +1,230 @@
+"""The one hardened XML reader (`cl.reader_xml_hardened`), built on `xml.parsers.expat` and nothing else.
+
+Three copies were compared: `primarysource/iana/xmlsafe.py`, `primarysource/bbf/_xml.py` and devicespy's
+`devicespy/xmlsafe.py` (read, not imported; devicespy commit e26c820). This keeps the strictest behaviour of each:
+devicespy's design and typed refusals, iana's text bound, bbf's scan for declarations before parsing. The iana and
+bbf modules are now thin wrappers over this one that keep their own bounds and messages.
+
+It refuses rather than defends:
+
+- any document type declaration, entity or parameter-entity declaration, notation or external reference, so no
+  entity can be declared, expansion attacks are impossible and nothing is ever fetched. The raw bytes are scanned
+  for `<!DOCTYPE`, `<!ENTITY`, `<!ELEMENT`, `<!ATTLIST` and `<!NOTATION` before expat sees them (also in a
+  UTF-16 or UTF-32 decoding, so a declaration hidden by the encoding is named as one), and every expat handler
+  that a declaration would reach refuses too;
+- any processing instruction other than the XML declaration, unless `ignore_processing_instructions` is set, in
+  which case they are dropped and never acted on (IANA registry files open with two);
+- any declared encoding other than UTF-8, and input that looks like UTF-16 or UTF-32;
+- input over `limit` bytes (checked before a parser exists), nesting over `max_depth`, more than `max_elements`
+  elements, more than `max_attributes` attributes on one element, an attribute value over
+  `max_attribute_length` characters, and text or a tail in one element over `max_text` characters;
+- empty, truncated and malformed input, an undefined entity and a second root element.
+
+XInclude and XSLT are never processed: ElementTree has no such step and only `Element` objects are built here.
+Every refusal is an `XmlRefused`, which is a `LibError` with a hint, in one of four kinds: `XmlTooLarge`,
+`XmlTooDeep`, `XmlForbidden`, `XmlMalformed`.
+
+Names come out in ElementTree's `{namespace}local` form, unless `namespaces=False`, when they are the raw
+qualified names (`dm:document`) and an undeclared prefix is not an error.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET  # noqa: S405 - only used to build elements; parsing is expat with DTDs refused
+from typing import NoReturn
+from xml.parsers import expat  # noqa: S406 - hardened below: declarations refused, no entities, bounded
+
+from primarysource.errors import LibError
+
+__all__ = [
+    "DEFAULT_HINT",
+    "XmlForbidden",
+    "XmlMalformed",
+    "XmlRefused",
+    "XmlTooDeep",
+    "XmlTooLarge",
+    "localname",
+    "parse",
+]
+
+DEFAULT_HINT = "the file is damaged or not the expected document; fetch or import it again"
+_SEP = "}"
+_DECLARATION = re.compile(rb"<!\s*(?:DOCTYPE|ENTITY|ELEMENT|ATTLIST|NOTATION)", re.IGNORECASE)
+_DECLARATION_TEXT = re.compile(r"<!\s*(?:DOCTYPE|ENTITY|ELEMENT|ATTLIST|NOTATION)", re.IGNORECASE)
+_WIDE_CODECS = ("utf-16", "utf-16-le", "utf-16-be", "utf-32", "utf-32-le", "utf-32-be")
+_FORBIDDEN_DECLARATIONS = "document type declarations, entities and notations are not accepted"
+
+
+class XmlRefused(LibError):  # noqa: N818 - the name is the contract, as in devicespy
+    """The document was refused. `reason` says why in one short phrase; the message is `XML refused: <reason>`."""
+
+    def __init__(self, reason: str, hint: str = DEFAULT_HINT) -> None:
+        super().__init__(f"XML refused: {reason}", hint)
+        self.reason = reason
+
+
+class XmlTooLarge(XmlRefused):
+    """A size bound was exceeded: bytes, elements, attributes, attribute length or text length."""
+
+
+class XmlTooDeep(XmlRefused):
+    """Element nesting went past `max_depth`."""
+
+
+class XmlForbidden(XmlRefused):
+    """A construct this reader never accepts: a declaration, an entity, a processing instruction, an encoding."""
+
+
+class XmlMalformed(XmlRefused):
+    """Not well-formed XML, including empty and truncated input."""
+
+
+def _qname(name: str) -> str:
+    # expat with a namespace separator yields "uri}local" (the local part cannot contain it).
+    if _SEP in name:
+        uri, local = name.rsplit(_SEP, 1)
+        return "{" + uri + "}" + local
+    return name
+
+
+def localname(tag: str) -> tuple[str, str]:
+    """Split an ElementTree name `{namespace}local` into `(namespace, local)`; no namespace gives `("", name)`."""
+    if tag.startswith("{"):
+        uri, sep, local = tag[1:].partition("}")
+        if sep:
+            return uri, local
+    return "", tag
+
+
+class _Builder:
+    def __init__(
+        self,
+        hint: str,
+        max_depth: int,
+        max_elements: int,
+        max_attributes: int,
+        max_attribute_length: int,
+        max_text: int,
+    ) -> None:
+        self.hint = hint
+        self.max_depth = max_depth
+        self.max_elements = max_elements
+        self.max_attributes = max_attributes
+        self.max_attribute_length = max_attribute_length
+        self.max_text = max_text
+        self.stack: list[ET.Element] = []
+        self.root: ET.Element | None = None
+        self.count = 0
+        self.tail_of: ET.Element | None = None
+
+    def refuse(self, *_args: object) -> NoReturn:
+        raise XmlForbidden(_FORBIDDEN_DECLARATIONS, self.hint)
+
+    def refuse_pi(self, *_args: object) -> NoReturn:
+        raise XmlForbidden("processing instructions are not accepted", self.hint)
+
+    def xml_decl(self, _version: str, encoding: str | None, _standalone: int) -> None:
+        if encoding is not None and encoding.lower() not in ("utf-8", "utf8"):
+            raise XmlForbidden("only UTF-8 is accepted, the document declares " + encoding, self.hint)
+
+    def start(self, name: str, attrs: dict[str, str]) -> None:
+        if len(self.stack) >= self.max_depth:
+            raise XmlTooDeep(f"nesting deeper than {self.max_depth}", self.hint)
+        self.count += 1
+        if self.count > self.max_elements:
+            raise XmlTooLarge(f"more than {self.max_elements} elements", self.hint)
+        if len(attrs) > self.max_attributes:
+            raise XmlTooLarge(f"more than {self.max_attributes} attributes on one element", self.hint)
+        for value in attrs.values():
+            if len(value) > self.max_attribute_length:
+                raise XmlTooLarge(f"an attribute value is longer than {self.max_attribute_length}", self.hint)
+        element = ET.Element(_qname(name), {_qname(k): v for k, v in attrs.items()})
+        if self.stack:
+            self.stack[-1].append(element)
+        else:
+            self.root = element
+        self.stack.append(element)
+        self.tail_of = None
+
+    def end(self, _name: str) -> None:
+        self.tail_of = self.stack.pop()
+
+    def data(self, text: str) -> None:
+        if self.tail_of is not None:
+            self.tail_of.tail = (self.tail_of.tail or "") + text
+            if len(self.tail_of.tail) > self.max_text:
+                raise XmlTooLarge(f"text longer than {self.max_text}", self.hint)
+        elif self.stack:
+            top = self.stack[-1]
+            top.text = (top.text or "") + text
+            if len(top.text) > self.max_text:
+                raise XmlTooLarge(f"text longer than {self.max_text}", self.hint)
+
+
+def _looks_wide(head: bytes) -> bool:
+    return head[:2] in (b"\xfe\xff", b"\xff\xfe") or b"\x00" in head
+
+
+def _declares_in_wide_text(raw: bytes) -> bool:
+    return any(_DECLARATION_TEXT.search(raw.decode(codec, errors="ignore")) for codec in _WIDE_CODECS)
+
+
+def parse(
+    raw: bytes,
+    limit: int,
+    *,
+    max_depth: int = 32,
+    max_elements: int = 50_000,
+    max_attributes: int = 16,
+    max_attribute_length: int = 4096,
+    max_text: int = 1_000_000,
+    ignore_processing_instructions: bool = False,
+    namespaces: bool = True,
+    hint: str = DEFAULT_HINT,
+) -> ET.Element:
+    """Parse `raw` into its root Element, or raise `XmlRefused` (a `LibError` carrying `hint`).
+
+    `limit` is the largest acceptable `len(raw)` and is checked before any parsing. The whole document is passed
+    at once. The defaults are the strictest any of the three source copies used; a caller with larger documents
+    passes its own bounds. The root returned is never a placeholder: every refusal raises."""
+    if not isinstance(raw, bytes | bytearray | memoryview):
+        raise TypeError("raw must be bytes")
+    if limit < 0:
+        raise ValueError("limit must not be negative")
+    if len(raw) > limit:
+        raise XmlTooLarge(f"{len(raw):,} bytes exceeds the limit of {limit:,}", hint)
+    data = bytes(raw)
+    if not data:
+        raise XmlMalformed("empty document", hint)
+    if _DECLARATION.search(data):
+        raise XmlForbidden(_FORBIDDEN_DECLARATIONS, hint)
+    if _looks_wide(data[:4]):
+        if _declares_in_wide_text(data):
+            raise XmlForbidden(_FORBIDDEN_DECLARATIONS, hint)
+        raise XmlForbidden("only UTF-8 is accepted, the input looks like UTF-16 or UTF-32", hint)
+    builder = _Builder(hint, max_depth, max_elements, max_attributes, max_attribute_length, max_text)
+    parser = expat.ParserCreate(None, _SEP) if namespaces else expat.ParserCreate()
+    parser.buffer_text = True
+    parser.SetParamEntityParsing(expat.XML_PARAM_ENTITY_PARSING_NEVER)
+    parser.StartDoctypeDeclHandler = builder.refuse
+    parser.EntityDeclHandler = builder.refuse
+    parser.ExternalEntityRefHandler = builder.refuse
+    parser.NotationDeclHandler = builder.refuse
+    if not ignore_processing_instructions:
+        parser.ProcessingInstructionHandler = builder.refuse_pi
+    parser.XmlDeclHandler = builder.xml_decl
+    parser.StartElementHandler = builder.start
+    parser.EndElementHandler = builder.end
+    parser.CharacterDataHandler = builder.data
+    try:
+        parser.Parse(data, True)
+    except XmlRefused:
+        raise
+    except expat.ExpatError as error:
+        raise XmlMalformed("not well-formed XML: " + expat.ErrorString(error.code), hint) from None
+    except (ValueError, RecursionError) as error:
+        raise XmlMalformed(f"not well-formed XML: {type(error).__name__}", hint) from None
+    if builder.root is None:
+        raise XmlMalformed("no root element", hint)
+    return builder.root