purexml 1.0.0__tar.gz

purexml-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Russell Pfister
+
+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.

purexml-1.0.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: purexml
+Version: 1.0.0
+Summary: Safely parse untrusted XML using only the Python standard library — a zero-dependency defusedxml replacement.
+Author-email: Russell Pfister <russalo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/russalo/purexml
+Project-URL: Repository, https://github.com/russalo/purexml
+Project-URL: Issues, https://github.com/russalo/purexml/issues
+Keywords: xml,security,defusedxml,xxe,billion-laughs,stdlib,hardening
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: defusedxml; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: fuzz
+Requires-Dist: atheris; extra == "fuzz"
+Requires-Dist: defusedxml; extra == "fuzz"
+Dynamic: license-file
+
+<!-- Plain markdown image with an ABSOLUTE raw URL (not <picture>/<img>): the GitHub iOS
+     app doesn't render <picture>, and PyPI doesn't resolve relative paths — markdown ![]
+     with a raw.githubusercontent URL renders on all three (GitHub web + mobile, PyPI). -->
+![purexml logo](https://raw.githubusercontent.com/russalo/purexml/main/assets/logo-light.svg)
+
+# purexml
+
+> Safely parse untrusted XML using only the Python standard library.
+
+[![tests](https://img.shields.io/github/actions/workflow/status/russalo/purexml/tests.yml?branch=main&label=tests)](https://github.com/russalo/purexml/actions/workflows/tests.yml)
+![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
+![runtime deps: zero](https://img.shields.io/badge/runtime%20deps-zero-brightgreen)
+![pure stdlib](https://img.shields.io/badge/pure-stdlib-blue)
+![coverage ≥90%](https://img.shields.io/badge/coverage-%E2%89%A590%25-brightgreen)
+![lint: ruff](https://img.shields.io/badge/lint-ruff-30173D)
+![types: mypy](https://img.shields.io/badge/types-mypy-blue)
+![differentially fuzzed](https://img.shields.io/badge/differentially-fuzzed-blueviolet)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+**purexml is a zero-dependency, drop-in replacement for [`defusedxml`](https://pypi.org/project/defusedxml/).**
+It hardens Python's standard-library XML parsers against the known attack classes —
+entity-expansion bombs, external-entity resolution (XXE), and external-DTD retrieval —
+and hands back the same standard `xml.etree` / `minidom` / SAX objects your code already
+expects. Migrating is a literal find-and-replace: `s/defusedxml/purexml/`.
+
+![How purexml defends untrusted XML in two layers: purexml's own Python-layer handlers block entity bombs, XXE and external-DTD resolution version-independently, while the libexpat parser layer mitigates parser-level DoS depending on your runtime; the result is a standard, trusted xml.etree tree.](https://raw.githubusercontent.com/russalo/purexml/main/assets/defense-layers.svg)
+
+## Why purexml
+
+- **Zero runtime dependencies.** Pure standard library — drop a third-party dependency
+  with no loss of protection (same parses succeed, same attacks blocked).
+- **A real drop-in.** Mirrors `defusedxml`'s API and defaults across the surface the
+  ecosystem actually imports, validated **oracle-gated against `defusedxml` itself**.
+- **Maintained.** `defusedxml` has been frozen since 2021 — the XML threat landscape
+  hasn't. purexml tracks the moving libexpat / CPython mitigations and can report what
+  your runtime is actually protected against.
+- **Opt-in hardening.** Structural-DoS caps and a posture report that `defusedxml`
+  lacks — **off by default**, so the drop-in promise is never broken.
+
+## Install & migrate
+
+Until purexml is published to PyPI, depend on it via a git or path reference. Then the
+only change to your code is the import path:
+
+```python
+# before:  from defusedxml.ElementTree import fromstring
+from purexml.ElementTree import fromstring
+
+root = fromstring(untrusted_xml)   # raises on bomb / XXE / external DTD; returns a standard Element
+```
+
+Defaults match `defusedxml` exactly (`forbid_entities=True`, `forbid_external=True`,
+`forbid_dtd=False`), so nothing else changes.
+
+> Runnable examples for every surface: **[`examples/`](examples/)** ·
+> Module-by-module migration guide: **[`docs/MIGRATING.md`](docs/MIGRATING.md)**
+
+## What it covers
+
+Drop-in replacements for the `defusedxml` modules the ecosystem imports:
+
+| purexml module | replaces | surface |
+|---|---|---|
+| `purexml.ElementTree` | `defusedxml.ElementTree` | `fromstring`, `parse`, `iterparse`, `XML`, `XMLParser`, `tostring`, `forbid_*` |
+| `purexml.minidom` | `defusedxml.minidom` | `parse`, `parseString` |
+| `purexml.sax` / `.expatreader` | `defusedxml.sax` | `make_parser`, `parse`, `parseString` |
+| `purexml.xmlrpc` | `defusedxml.xmlrpc` | `monkey_patch`, `unmonkey_patch` |
+| `purexml.common` | `defusedxml.common` | exception catch-site aliases |
+
+`defusedxml.pulldom` is deferred (low measured demand); `defusedxml.lxml` is excluded by
+the zero-dependency contract (it wraps the third-party `lxml`).
+
+## Opt-in defense-in-depth
+
+Bounded protections `defusedxml` never had — **default-off**, so the strict mirror is
+unchanged until you ask:
+
+```python
+import purexml
+from purexml import fromstring, RECOMMENDED_LIMITS
+
+# Bound structural DoS (deep nesting / attribute floods / giant documents):
+root = fromstring(untrusted, limits=RECOMMENDED_LIMITS)   # raises LimitExceeded past the caps
+
+# See what THIS runtime is actually protected against (read-only; no parse):
+print(purexml.security_report())
+```
+
+There's also a posture CLI — `python -m purexml` (`--json` for machine output, or
+`--check --min-expat X.Y.Z` as an opt-in CI gate).
+
+## Status
+
+**v1.0.0 — the public contract is frozen and binding.** The `defusedxml`-mirror surface
+won't move under you without a 2.0 (see [`PUBLIC_CONTRACT.md`](PUBLIC_CONTRACT.md)).
+
+- Runs on **CPython 3.10–3.13**, zero runtime dependencies.
+- Correctness is **oracle-gated against `defusedxml` every release** — C14N + event-stream
+  equivalence over a real corpus, an adversarial attack battery, and differential fuzzing
+  (see [`docs/EQUIVALENCE.md`](docs/EQUIVALENCE.md)).
+- The contract freeze was ratified with the anchor consumer (file-observer) — see
+  [`docs/v1.0.0_RFC_Specification.md`](docs/v1.0.0_RFC_Specification.md). The opt-in
+  defense-in-depth (`Limits`, `security_report()`) stays **provisional** (it tracks the
+  moving libexpat threat landscape).
+- **Not yet published to PyPI**, and the `purexml` name is not yet claimed — distribution
+  is a separate, deliberate step. Depend on it via git/path until then.
+- **License: MIT.**
+
+## Documentation
+
+- **[`examples/`](examples/)** — runnable, copy-paste examples for every surface
+- **[`docs/MIGRATING.md`](docs/MIGRATING.md)** — the `s/defusedxml/purexml/` migration guide
+- [`COMPATIBILITY.md`](COMPATIBILITY.md) — drop-in compatibility contract + exception edge cases
+- [`LIMITATIONS.md`](LIMITATIONS.md) — what purexml deliberately does **not** do
+- [`SECURITY.md`](SECURITY.md) — security policy and how to report issues
+- [`PUBLIC_CONTRACT.md`](PUBLIC_CONTRACT.md) — consumer stability commitments (binds at 1.0)
+- [`CHANGELOG.md`](CHANGELOG.md) — release notes · [`HISTORY.md`](HISTORY.md) — full per-release record
+- [`STACK.md`](STACK.md) — language, runtime, dependencies · [`CONVENTIONS.md`](CONVENTIONS.md) — project conventions
+
+## License
+
+[MIT](LICENSE) — purexml is give-it-away, zero-dependency infrastructure: pure open
+source, maximum reuse. Publishing to PyPI and claiming the `purexml` name remain a
+separate, deliberate call.

purexml-1.0.0/README.md

@@ -0,0 +1,124 @@
+<!-- Plain markdown image with an ABSOLUTE raw URL (not <picture>/<img>): the GitHub iOS
+     app doesn't render <picture>, and PyPI doesn't resolve relative paths — markdown ![]
+     with a raw.githubusercontent URL renders on all three (GitHub web + mobile, PyPI). -->
+![purexml logo](https://raw.githubusercontent.com/russalo/purexml/main/assets/logo-light.svg)
+
+# purexml
+
+> Safely parse untrusted XML using only the Python standard library.
+
+[![tests](https://img.shields.io/github/actions/workflow/status/russalo/purexml/tests.yml?branch=main&label=tests)](https://github.com/russalo/purexml/actions/workflows/tests.yml)
+![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
+![runtime deps: zero](https://img.shields.io/badge/runtime%20deps-zero-brightgreen)
+![pure stdlib](https://img.shields.io/badge/pure-stdlib-blue)
+![coverage ≥90%](https://img.shields.io/badge/coverage-%E2%89%A590%25-brightgreen)
+![lint: ruff](https://img.shields.io/badge/lint-ruff-30173D)
+![types: mypy](https://img.shields.io/badge/types-mypy-blue)
+![differentially fuzzed](https://img.shields.io/badge/differentially-fuzzed-blueviolet)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+**purexml is a zero-dependency, drop-in replacement for [`defusedxml`](https://pypi.org/project/defusedxml/).**
+It hardens Python's standard-library XML parsers against the known attack classes —
+entity-expansion bombs, external-entity resolution (XXE), and external-DTD retrieval —
+and hands back the same standard `xml.etree` / `minidom` / SAX objects your code already
+expects. Migrating is a literal find-and-replace: `s/defusedxml/purexml/`.
+
+![How purexml defends untrusted XML in two layers: purexml's own Python-layer handlers block entity bombs, XXE and external-DTD resolution version-independently, while the libexpat parser layer mitigates parser-level DoS depending on your runtime; the result is a standard, trusted xml.etree tree.](https://raw.githubusercontent.com/russalo/purexml/main/assets/defense-layers.svg)
+
+## Why purexml
+
+- **Zero runtime dependencies.** Pure standard library — drop a third-party dependency
+  with no loss of protection (same parses succeed, same attacks blocked).
+- **A real drop-in.** Mirrors `defusedxml`'s API and defaults across the surface the
+  ecosystem actually imports, validated **oracle-gated against `defusedxml` itself**.
+- **Maintained.** `defusedxml` has been frozen since 2021 — the XML threat landscape
+  hasn't. purexml tracks the moving libexpat / CPython mitigations and can report what
+  your runtime is actually protected against.
+- **Opt-in hardening.** Structural-DoS caps and a posture report that `defusedxml`
+  lacks — **off by default**, so the drop-in promise is never broken.
+
+## Install & migrate
+
+Until purexml is published to PyPI, depend on it via a git or path reference. Then the
+only change to your code is the import path:
+
+```python
+# before:  from defusedxml.ElementTree import fromstring
+from purexml.ElementTree import fromstring
+
+root = fromstring(untrusted_xml)   # raises on bomb / XXE / external DTD; returns a standard Element
+```
+
+Defaults match `defusedxml` exactly (`forbid_entities=True`, `forbid_external=True`,
+`forbid_dtd=False`), so nothing else changes.
+
+> Runnable examples for every surface: **[`examples/`](examples/)** ·
+> Module-by-module migration guide: **[`docs/MIGRATING.md`](docs/MIGRATING.md)**
+
+## What it covers
+
+Drop-in replacements for the `defusedxml` modules the ecosystem imports:
+
+| purexml module | replaces | surface |
+|---|---|---|
+| `purexml.ElementTree` | `defusedxml.ElementTree` | `fromstring`, `parse`, `iterparse`, `XML`, `XMLParser`, `tostring`, `forbid_*` |
+| `purexml.minidom` | `defusedxml.minidom` | `parse`, `parseString` |
+| `purexml.sax` / `.expatreader` | `defusedxml.sax` | `make_parser`, `parse`, `parseString` |
+| `purexml.xmlrpc` | `defusedxml.xmlrpc` | `monkey_patch`, `unmonkey_patch` |
+| `purexml.common` | `defusedxml.common` | exception catch-site aliases |
+
+`defusedxml.pulldom` is deferred (low measured demand); `defusedxml.lxml` is excluded by
+the zero-dependency contract (it wraps the third-party `lxml`).
+
+## Opt-in defense-in-depth
+
+Bounded protections `defusedxml` never had — **default-off**, so the strict mirror is
+unchanged until you ask:
+
+```python
+import purexml
+from purexml import fromstring, RECOMMENDED_LIMITS
+
+# Bound structural DoS (deep nesting / attribute floods / giant documents):
+root = fromstring(untrusted, limits=RECOMMENDED_LIMITS)   # raises LimitExceeded past the caps
+
+# See what THIS runtime is actually protected against (read-only; no parse):
+print(purexml.security_report())
+```
+
+There's also a posture CLI — `python -m purexml` (`--json` for machine output, or
+`--check --min-expat X.Y.Z` as an opt-in CI gate).
+
+## Status
+
+**v1.0.0 — the public contract is frozen and binding.** The `defusedxml`-mirror surface
+won't move under you without a 2.0 (see [`PUBLIC_CONTRACT.md`](PUBLIC_CONTRACT.md)).
+
+- Runs on **CPython 3.10–3.13**, zero runtime dependencies.
+- Correctness is **oracle-gated against `defusedxml` every release** — C14N + event-stream
+  equivalence over a real corpus, an adversarial attack battery, and differential fuzzing
+  (see [`docs/EQUIVALENCE.md`](docs/EQUIVALENCE.md)).
+- The contract freeze was ratified with the anchor consumer (file-observer) — see
+  [`docs/v1.0.0_RFC_Specification.md`](docs/v1.0.0_RFC_Specification.md). The opt-in
+  defense-in-depth (`Limits`, `security_report()`) stays **provisional** (it tracks the
+  moving libexpat threat landscape).
+- **Not yet published to PyPI**, and the `purexml` name is not yet claimed — distribution
+  is a separate, deliberate step. Depend on it via git/path until then.
+- **License: MIT.**
+
+## Documentation
+
+- **[`examples/`](examples/)** — runnable, copy-paste examples for every surface
+- **[`docs/MIGRATING.md`](docs/MIGRATING.md)** — the `s/defusedxml/purexml/` migration guide
+- [`COMPATIBILITY.md`](COMPATIBILITY.md) — drop-in compatibility contract + exception edge cases
+- [`LIMITATIONS.md`](LIMITATIONS.md) — what purexml deliberately does **not** do
+- [`SECURITY.md`](SECURITY.md) — security policy and how to report issues
+- [`PUBLIC_CONTRACT.md`](PUBLIC_CONTRACT.md) — consumer stability commitments (binds at 1.0)
+- [`CHANGELOG.md`](CHANGELOG.md) — release notes · [`HISTORY.md`](HISTORY.md) — full per-release record
+- [`STACK.md`](STACK.md) — language, runtime, dependencies · [`CONVENTIONS.md`](CONVENTIONS.md) — project conventions
+
+## License
+
+[MIT](LICENSE) — purexml is give-it-away, zero-dependency infrastructure: pure open
+source, maximum reuse. Publishing to PyPI and claiming the `purexml` name remain a
+separate, deliberate call.

purexml-1.0.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "purexml"
+version = "1.0.0"
+description = "Safely parse untrusted XML using only the Python standard library — a zero-dependency defusedxml replacement."
+readme = "README.md"
+requires-python = ">=3.10"
+# MIT (decided 2026-06-28) — pure open source, maximum reuse; one-way compatible with
+# AGPL so it's clean as a future file-observer dependency. See LICENSE. Table form
+# (`{text="MIT"}`) + classifier is used rather than the bare SPDX `license = "MIT"`
+# string: the string form needs setuptools>=77 and (per PEP 639) deprecates the license
+# classifier — this form keeps the classifier (which PyPI's UI surfaces) with no warning
+# on the current setuptools>=65 floor.
+license = {text = "MIT"}
+authors = [
+    {name = "Russell Pfister", email = "russalo@gmail.com"},
+]
+keywords = ["xml", "security", "defusedxml", "xxe", "billion-laughs", "stdlib", "hardening"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: Text Processing :: Markup :: XML",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Start empty. Add real runtime deps as the project grows; prefer stdlib first.
+dependencies = []
+
+[project.optional-dependencies]
+# defusedxml is the dev/test ORACLE only (RFC §3/§5) — never a runtime dependency,
+# never imported under src/. It is the incumbent purexml is validated against.
+# ruff (lint) + pytest-cov (coverage gate) are dev-only quality tooling, run in CI;
+# never runtime deps. (mypy is intentionally NOT here yet — see the typed-badge note
+# in scratch/publish_prep_checklist.md: the surface needs annotating first.)
+dev = ["pytest", "defusedxml", "ruff", "pytest-cov", "mypy"]
+
+# Coverage-guided differential fuzzing (v0.5 RFC §3/§4). DEV-ONLY, opt-in — Atheris
+# is heavier tooling (libFuzzer/clang) for on-demand deep sweeps; the always-run
+# seeded differential gate (tests/test_fuzz_equivalence.py) needs NO extra. Atheris
+# is NEVER a runtime dependency and is never imported under src/.
+fuzz = ["atheris", "defusedxml"]
+
+# URLs PROVISIONAL — repo home not confirmed (adoption model open; may be vendored
+# rather than published). russalo convention path shown; revisit when publishing is decided.
+[project.urls]
+Homepage = "https://github.com/russalo/purexml"
+Repository = "https://github.com/russalo/purexml"
+Issues = "https://github.com/russalo/purexml/issues"
+
+# If/when this project ships a CLI, declare it here:
+# [project.scripts]
+# purexml = "purexml.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Ship the PEP 561 marker so downstream type-checkers consume purexml's types (v0.8).
+[tool.setuptools.package-data]
+purexml = ["py.typed"]
+
+[tool.pytest.ini_options]
+# Only collect the project's own tests. Prevents `pytest` from walking the repo
+# root and importing test files inside scratch/ or any harvested corpora — that
+# both errors on collection AND writes __pycache__/*.pyc into shared dirs.
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.coverage.run]
+source = ["purexml"]
+# CI runs: pytest --cov=purexml --cov-fail-under=90 (enforced floor; currently ~94%).
+
+[tool.mypy]
+files = ["src/purexml"]
+python_version = "3.10"
+strict = true       # v0.8.1: full strict — internals annotated, Any leaks resolved.

purexml-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

purexml-1.0.0/src/purexml/ElementTree.py

@@ -0,0 +1,52 @@
+"""purexml.ElementTree — canonical namespace mirroring ``defusedxml.ElementTree``.
+
+The migration off defusedxml is a literal ``s/defusedxml/purexml/`` for the
+implemented surface::
+
+    # was: from defusedxml.ElementTree import fromstring, parse, XML, XMLParser
+    from purexml.ElementTree import fromstring, parse, XML, XMLParser
+
+As of v0.3 this covers defusedxml.ElementTree's full surface: ``fromstring``,
+``parse``, ``iterparse``, ``XML``, ``XMLParser`` (+ ``XMLParse``/``XMLTreeBuilder``
+aliases), ``tostring``, ``ParseError``.
+
+``ParseError`` and ``tostring`` are re-exported from the stdlib exactly as
+defusedxml does. ``Element`` is intentionally NOT re-exported (defusedxml doesn't
+either); import it from ``xml.etree.ElementTree`` if needed. ``fromstringlist`` is
+a stdlib-parity extra beyond defusedxml's surface.
+"""
+from xml.etree.ElementTree import ParseError, tostring
+
+from ._parser import XMLParser, fromstring, fromstringlist, iterparse, parse
+from .errors import (
+    DTDForbidden,
+    EntitiesForbidden,
+    ExternalReferenceForbidden,
+    PureXMLError,
+)
+
+#: ``XML`` is defusedxml's/stdlib's alias for ``fromstring``.
+XML = fromstring
+
+#: defusedxml back-compat aliases for the parser class.
+XMLParse = XMLTreeBuilder = XMLParser
+
+__all__ = [
+    # mirrors defusedxml.ElementTree's __all__ (for the implemented surface)
+    "ParseError",
+    "XML",
+    "XMLParse",
+    "XMLParser",
+    "XMLTreeBuilder",
+    "fromstring",
+    "parse",
+    "iterparse",
+    "tostring",
+    # stdlib-parity extra (not in defusedxml)
+    "fromstringlist",
+    # purexml exception hierarchy
+    "PureXMLError",
+    "DTDForbidden",
+    "EntitiesForbidden",
+    "ExternalReferenceForbidden",
+]

purexml-1.0.0/src/purexml/__init__.py

@@ -0,0 +1,98 @@
+"""purexml — safely parse untrusted XML using only the Python standard library.
+
+A maintained, zero-dependency, stdlib-only replacement for ``defusedxml``: returns
+standard ``xml.etree`` objects while blocking the known XML attack classes
+(entity-expansion bombs, XXE, external reference resolution), behaviorally
+equivalent to defusedxml's defaults.
+
+The canonical namespace mirrors ``defusedxml.ElementTree`` (migration is a literal
+``s/defusedxml/purexml/``)::
+
+    from purexml.ElementTree import fromstring, parse, XML, XMLParser
+
+The common entry points are also re-exported at the top level for convenience::
+
+    from purexml import fromstring
+    root = fromstring("<r><a>x</a></r>")   # raises on bomb / XXE / malformed
+"""
+from xml.etree.ElementTree import ParseError, tostring
+
+from . import ElementTree, common, expatreader, minidom, sax, xmlrpc
+from ._expat_security import (
+    BLOCKED,
+    EXPAT_MITIGATED,
+    EXPAT_PARTIAL,
+    EXPAT_VERSION,
+    LIVE,
+    OPT_IN,
+    RECOMMENDED_EXPAT_VERSION,
+    SAFE_EXPAT_VERSION,
+    SecurityReport,
+    assert_expat_secure,
+    expat_is_secure,
+    security_report,
+)
+from ._parser import XMLParser, fromstring, fromstringlist, iterparse, parse
+from .errors import (
+    AttributesExceeded,
+    DepthExceeded,
+    DTDForbidden,
+    EntitiesForbidden,
+    ExternalReferenceForbidden,
+    LimitExceeded,
+    NotSupportedError,
+    PureXMLError,
+    SizeExceeded,
+)
+from .limits import RECOMMENDED_LIMITS, Limits
+
+XML = fromstring
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # the ElementTree family (also at purexml.ElementTree)
+    "ElementTree",
+    "fromstring",
+    "parse",
+    "iterparse",
+    "fromstringlist",
+    "XML",
+    "XMLParser",
+    "tostring",
+    "ParseError",
+    # other defusedxml-surface modules — import-compatible submodules
+    "minidom",          # v0.10
+    "common",           # v0.10
+    "sax",              # v0.12
+    "expatreader",      # v0.12 (sax engine)
+    "xmlrpc",           # v0.13 (monkeypatch shim — lazy)
+    # exception hierarchy
+    "PureXMLError",
+    "DTDForbidden",
+    "EntitiesForbidden",
+    "ExternalReferenceForbidden",
+    "NotSupportedError",
+    # opt-in structural-DoS limits (v0.4 mirror-plus)
+    "Limits",
+    "RECOMMENDED_LIMITS",
+    "LimitExceeded",
+    "DepthExceeded",
+    "AttributesExceeded",
+    "SizeExceeded",
+    # libexpat version awareness (v0.1.2) — opt-in
+    "EXPAT_VERSION",
+    "SAFE_EXPAT_VERSION",
+    "RECOMMENDED_EXPAT_VERSION",
+    "expat_is_secure",
+    "assert_expat_secure",
+    # security-posture report (v0.5 trust surface) — read-only introspection
+    "security_report",
+    "SecurityReport",
+    "BLOCKED",
+    "EXPAT_MITIGATED",
+    "EXPAT_PARTIAL",
+    "OPT_IN",
+    "LIVE",
+    "__version__",
+]

purexml-1.0.0/src/purexml/__main__.py

@@ -0,0 +1,78 @@
+"""CLI: ``python -m purexml`` — report this runtime's XML-security posture.
+
+Read-only introspection over `purexml.security_report()`. **Informs by default
+(exit 0)**; ``--check`` is the *caller* opting into a CI gate (the inform-by-default
+version-assertion stance). This module is the package's one **I/O boundary** — it
+prints, and imports ``argparse``/``json``/``sys`` on top of purexml — but nothing
+that reaches the network / filesystem / subprocess. `tests/test_no_io` enforces both
+halves: the parse surface stays strict stdlib-`xml`, and this file may add only those
+CLI-output modules, never a forbidden one.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, security_report
+from . import _expat_security as _es
+
+
+def _ver(t: tuple[int, ...]) -> str:
+    return ".".join(map(str, t))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="python -m purexml",
+        description="Report this runtime's XML-security posture (purexml).")
+    p.add_argument("--json", action="store_true",
+                   help="emit the posture as JSON (machine-readable; PROVISIONAL shape)")
+    p.add_argument("--check", action="store_true",
+                   help="exit non-zero if libexpat is below the floor (opt-in CI gate)")
+    p.add_argument("--min-expat", metavar="X.Y.Z", default=None,
+                   help="floor for --check (default: the recommended-latest floor)")
+    p.add_argument("--version", action="store_true",
+                   help="print purexml and libexpat versions, then exit")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # --min-expat is meaningless without --check; silently ignoring it would let a
+    # user who meant to gate (`--min-expat X`) get a silent exit-0 pass — a security
+    # footgun in CI. Fail loudly instead (PR#15 Gemini).
+    if args.min_expat is not None and not args.check:
+        parser.error("--min-expat requires --check")
+
+    if args.version:
+        print("purexml %s (libexpat %s)" % (__version__, _ver(_es.EXPAT_VERSION)))
+        return 0
+
+    report = security_report()
+    if args.json:
+        print(json.dumps({"purexml_version": __version__, **report.as_dict()}))
+    else:
+        print(report)
+
+    if args.check:
+        if args.min_expat is not None:
+            try:
+                floor = _es._as_version_tuple(args.min_expat)
+            except (ValueError, TypeError):
+                parser.error("--min-expat must be a version like 2.8.1, got %r"
+                             % args.min_expat)
+        else:
+            floor = _es.RECOMMENDED_EXPAT_VERSION
+        if _es.EXPAT_VERSION < floor:
+            print("FAIL: libexpat %s is below the required floor %s"
+                  % (_ver(_es.EXPAT_VERSION), _ver(floor)), file=sys.stderr)
+            return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())