safexml 1.0.0__tar.gz

safexml-1.0.0/.githooks/pre-commit

@@ -0,0 +1,72 @@
+#!/bin/sh
+set -e
+
+# Export standard toolchain paths if not in PATH
+if [ -n "$USERPROFILE" ]; then
+    export PATH="$USERPROFILE/.rustup/toolchains/stable-x86_64-pc-windows-msvc/bin:$USERPROFILE/.cargo/bin:$PATH"
+fi
+if [ -n "$HOME" ]; then
+    export PATH="$HOME/.cargo/bin:$PATH"
+fi
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo -e "${BLUE}[git-hook: pre-commit]${NC} Running pre-commit validation checks..."
+
+# 1. Multi-Manifest Version Parity Check
+echo -e "${BLUE}[1/3] Checking version parity across manifests...${NC}"
+if command -v uv >/dev/null 2>&1; then
+    uv run python scripts/sync_version.py --check || {
+        echo -e "${RED}[FAIL] Version parity check failed! Run 'python scripts/sync_version.py --set <version>' to fix.${NC}"
+        exit 1
+    }
+    echo -e "${GREEN}[OK] Version parity confirmed.${NC}"
+elif command -v python3 >/dev/null 2>&1; then
+    python3 scripts/sync_version.py --check || exit 1
+    echo -e "${GREEN}[OK] Version parity confirmed.${NC}"
+elif command -v python >/dev/null 2>&1; then
+    python scripts/sync_version.py --check || exit 1
+    echo -e "${GREEN}[OK] Version parity confirmed.${NC}"
+else
+    echo -e "${YELLOW}[SKIP] Python/uv not found; skipping version check.${NC}"
+fi
+
+# 2. Rust Code Formatting Check
+echo -e "${BLUE}[2/3] Checking Rust code formatting (cargo fmt)...${NC}"
+if command -v cargo >/dev/null 2>&1; then
+    cargo fmt --all -- --check || {
+        echo -e "${RED}[FAIL] Rust code formatting check failed! Run 'cargo fmt --all' to fix.${NC}"
+        exit 1
+    }
+    echo -e "${GREEN}[OK] Rust formatting clean.${NC}"
+else
+    echo -e "${YELLOW}[SKIP] Cargo not found in PATH; skipping cargo fmt.${NC}"
+fi
+
+# 3. Python Linting & Formatting (Ruff)
+echo -e "${BLUE}[3/3] Checking Python code quality (ruff)...${NC}"
+if command -v uvx >/dev/null 2>&1; then
+    uvx ruff check python tests || {
+        echo -e "${RED}[FAIL] Ruff lint failed! Run 'uvx ruff check --fix' to auto-fix.${NC}"
+        exit 1
+    }
+    uvx ruff format --check python tests || {
+        echo -e "${RED}[FAIL] Ruff format failed! Run 'uvx ruff format' to auto-format.${NC}"
+        exit 1
+    }
+    echo -e "${GREEN}[OK] Python code quality clean.${NC}"
+elif command -v ruff >/dev/null 2>&1; then
+    ruff check python tests || exit 1
+    ruff format --check python tests || exit 1
+    echo -e "${GREEN}[OK] Python code quality clean.${NC}"
+else
+    echo -e "${YELLOW}[SKIP] Ruff not found; skipping python linting.${NC}"
+fi
+
+echo -e "${GREEN}[git-hook: pre-commit] All pre-commit checks passed successfully!${NC}"
+exit 0
+

safexml-1.0.0/.githooks/pre-push

@@ -0,0 +1,41 @@
+#!/bin/sh
+set -e
+
+if [ -n "$USERPROFILE" ]; then
+    export PATH="$USERPROFILE/.rustup/toolchains/stable-x86_64-pc-windows-msvc/bin:$USERPROFILE/.cargo/bin:$PATH"
+fi
+if [ -n "$HOME" ]; then
+    export PATH="$HOME/.cargo/bin:$PATH"
+fi
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo -e "${BLUE}[git-hook: pre-push]${NC} Running pre-push verification tests..."
+
+# 1. Rust Cargo Check & Tests
+echo -e "${BLUE}[1/2] Running Rust tests (cargo test)...${NC}"
+cargo test || {
+    echo -e "${RED}[FAIL] cargo test failed!${NC}"
+    exit 1
+}
+echo -e "${GREEN}[OK] Cargo tests passed.${NC}"
+
+# 2. Python Tests
+echo -e "${BLUE}[2/2] Running Python tests (pytest)...${NC}"
+if [ -f ".venv/bin/pytest" ]; then
+    .venv/bin/pytest || {
+        echo -e "${RED}[FAIL] pytest failed!${NC}"
+        exit 1
+    }
+    echo -e "${GREEN}[OK] Pytest passed.${NC}"
+elif command -v pytest >/dev/null 2>&1; then
+    pytest || exit 1
+    echo -e "${GREEN}[OK] Pytest passed.${NC}"
+fi
+
+echo -e "${GREEN}[git-hook: pre-push] All tests passed! Ready to push.${NC}"
+exit 0
+

safexml-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  rust-check:
+    name: Rust Checks (fmt, clippy, test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Run Rust tests
+        run: cargo test --all-targets
+
+  python-test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    needs: rust-check
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies and build safexml
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Lint Python with Ruff
+        run: |
+          ruff check python tests
+          ruff format --check python tests
+
+      - name: Run pytest
+        run: pytest -v
+
+  version-parity:
+    name: Version Parity Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify Cargo.toml and pyproject.toml versions match
+        run: python scripts/sync_version.py --check
+

safexml-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,161 @@
+name: Release Python Wheels (PyPI)
+
+concurrency:
+  group: release-pypi-${{ github.ref_name || github.ref }}
+  cancel-in-progress: false
+
+on:
+  push:
+    tags:
+      - 'v*'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  linux:
+    name: Build Linux Wheels (${{ matrix.target }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Sync Tag Version Across Manifests
+        shell: bash
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            TAG_VER="${GITHUB_REF_NAME#v}"
+            echo "Synchronizing version from tag to: $TAG_VER"
+            python scripts/sync_version.py --set "$TAG_VER"
+          fi
+      - name: Build Wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: 'true'
+          manylinux: auto
+      - name: Upload Wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  windows:
+    name: Build Windows Wheels (${{ matrix.target }})
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        target: [x64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Sync Tag Version Across Manifests
+        shell: bash
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            TAG_VER="${GITHUB_REF_NAME#v}"
+            echo "Synchronizing version from tag to: $TAG_VER"
+            python scripts/sync_version.py --set "$TAG_VER"
+          fi
+      - name: Build Wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: 'true'
+      - name: Upload Wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-${{ matrix.target }}
+          path: dist
+
+  macos:
+    name: Build macOS Wheels (${{ matrix.target }})
+    runs-on: macos-14
+    strategy:
+      matrix:
+        target: [x86_64-apple-darwin, aarch64-apple-darwin]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Sync Tag Version Across Manifests
+        shell: bash
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            TAG_VER="${GITHUB_REF_NAME#v}"
+            echo "Synchronizing version from tag to: $TAG_VER"
+            python scripts/sync_version.py --set "$TAG_VER"
+          fi
+      - name: Build Wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: 'true'
+      - name: Upload Wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    name: Build Source Distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Sync Tag Version Across Manifests
+        shell: bash
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            TAG_VER="${GITHUB_REF_NAME#v}"
+            echo "Synchronizing version from tag to: $TAG_VER"
+            python scripts/sync_version.py --set "$TAG_VER"
+          fi
+      - name: Build Source Distribution
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  publish:
+    name: Publish to PyPI
+    needs: [linux, windows, macos, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/safexml
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+

safexml-1.0.0/.gitignore

@@ -0,0 +1,28 @@
+# Rust
+target/
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+venv/
+dist/
+build/
+uv.lock
+*.egg-info/
+.eggs/
+
+# IDE & Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+

safexml-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: ['--unsafe']
+      - id: check-toml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^(python|tests)/
+      - id: ruff-format
+        files: ^(python|tests)/
+
+  - repo: local
+    hooks:
+      - id: version-parity
+        name: Version parity check (Cargo.toml vs pyproject.toml)
+        entry: python scripts/sync_version.py --check
+        language: system
+        pass_filenames: false
+        files: ^(Cargo\.toml|pyproject\.toml)$
+
+      - id: cargo-fmt
+        name: Rust format check (cargo fmt)
+        entry: cargo fmt --all -- --check
+        language: system
+        pass_filenames: false
+        files: \.rs$
+

safexml-1.0.0/.releaserc

@@ -0,0 +1,43 @@
+{
+  "tagFormat": "v${version}",
+  "branches": [
+    "main"
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "python3 scripts/sync_version.py --set ${nextRelease.version} && cargo check"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "CHANGELOG.md",
+          "Cargo.toml",
+          "Cargo.lock",
+          "pyproject.toml"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "successComment": false,
+        "failComment": false,
+        "releasedLabels": false
+      }
+    ]
+  ]
+}
+

safexml-1.0.0/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+Instructions and guidelines for AI coding assistants working in the `safexml` repository.
+
+---
+
+## 1. Project Overview
+
+`safexml` is a high-performance, secure, modern XML parser and drop-in `defusedxml` replacement built in Rust.
+
+- **Technology**: Rust 2021, PyO3 (`abi3-py312`), `quick-xml` (0.42+), `maturin`.
+- **Repository**: `polyxml/safexml`
+- **Supported Python**: `Python >= 3.12` exclusively. No legacy Python 2 or Python 3.7–3.11 backward-compatibility shims.
+- **Maintainer**: Bailey Nguyen (`bailey.tan.nguyen@gmail.com`).
+- **Organization**: [PolyXML](https://github.com/polyxml).
+
+---
+
+## 2. Core Architectural Decisions & Invariants
+
+When contributing or refactoring, strictly maintain the following invariants:
+
+1. **Python >= 3.12 Exclusively**:
+   - Never introduce Python 2 or legacy Python 3 (< 3.12) compatibility shims (e.g. `sys.version_info < (3, ...)` or `six`).
+   - Use modern syntax (`X | Y` type unions, PEP 561 typing, built-in generics).
+
+2. **Drop-in Compatibility with `defusedxml.ElementTree` & `xml.etree.ElementTree`**:
+   - Returns standard `xml.etree.ElementTree.Element` instances to maintain 100% compatibility with libraries like `pysaml2`, `python3-saml`, `openpyxl`, `python-docx`, `feedparser`, `botocore`.
+   - Re-exports standard ElementTree symbols (`Element`, `SubElement`, `Comment`, `PI`, `indent`, `register_namespace`, `dump`, `tostring`, `tostringlist`).
+   - Signature parity: `fromstring(text, parser=None, forbid_dtd=False, forbid_entities=True, forbid_external=True, ...)` must accept `parser` keyword argument (resolving `tiran/defusedxml#78`).
+
+3. **True GIL Detachment in Rust**:
+   - All tokenization, XML scanning, DTD validation, and entity checking in Rust must execute outside the Python GIL using `py.detach(|| ...)` to allow multi-threaded Python servers (FastAPI, Django, Celery, gunicorn) to parse XML concurrently without blocking.
+
+4. **Security by Default**:
+   - **Billion Laughs / Entity Expansion**: Reject non-predefined entities when `forbid_entities=True` (`EntitiesForbidden`).
+   - **XXE (XML External Entity)**: Reject `SYSTEM` and `PUBLIC` references when `forbid_external=True` (`ExternalReferenceForbidden`).
+   - **DTD Injections**: Reject `<!DOCTYPE>` declarations when `forbid_dtd=True` (`DTDForbidden`).
+   - **Nesting Depth Limit**: Enforce `max_depth` (default 1,000) to protect against stack exhaustion.
+   - **Size Limits**: Enforce `max_text_size` and `max_entity_size` to prevent memory exhaustion attacks.
+
+5. **Upstream Issue Fixes**:
+   - Maintain the fixes for tracked upstream issues:
+     - `tiran/defusedxml#105`: Exception formatting for `rich` tracebacks.
+     - `tiran/defusedxml#104`: PEP 561 `py.typed` marker and full type annotations.
+     - `tiran/defusedxml#87`: Standard `ElementTree.indent()` support.
+     - `tiran/defusedxml#80`: Direct `Element` class export.
+     - `tiran/defusedxml#79`: `register_namespace()` support.
+     - `tiran/defusedxml#76`, `#77`, `#88`: Safe `defuse_stdlib()` without breaking 3rd-party libs.
+
+---
+
+## 3. Tooling & Development Workflow
+
+### Rust Toolchain
+- Check workspace:
+  ```bash
+  cargo check
+  ```
+- Run Rust tests:
+  ```bash
+  cargo test
+  ```
+- Format code:
+  ```bash
+  cargo fmt --all
+  ```
+- Clippy:
+  ```bash
+  cargo clippy -- -D warnings
+  ```
+
+### Python Development
+- Compile extension into local virtualenv:
+  ```bash
+  maturin develop
+  ```
+- Run test suite:
+  ```bash
+  pytest -v
+  ```
+- Lint & format with Ruff:
+  ```bash
+  ruff check python tests
+  ruff format python tests
+  ```
+- Version parity check:
+  ```bash
+  python scripts/sync_version.py --check
+  ```
+
+---
+
+## 4. Release Process
+- Releases are automated via GitHub Actions (`.github/workflows/release.yml`) using Semantic Release (`.releaserc`) and PyPI Trusted Publishing.
+- Manifest versions (`Cargo.toml` and `pyproject.toml`) are kept in sync via `scripts/sync_version.py`.
+

safexml-1.0.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+## [1.0.0] - 2026-10-11
+
+### Features
+- Initial release of `safexml`: High-performance, secure, modern XML parser and drop-in `defusedxml` replacement built in Rust.
+- Core Rust streaming XML parser powered by `quick-xml` and `PyO3` with true GIL release (`py.detach`).
+- Full drop-in parity for `defusedxml.ElementTree` and `xml.etree.ElementTree`.
+- Strict security against Billion Laughs (exponential entity expansion), Quadratic Blowup, XXE, cyclic entities, and external DTDs.
+- Enforced depth recursion limits (default 1,000) and text/entity memory bounds.
+- Resolved upstream `defusedxml` open issues:
+  - tiran/defusedxml#105: Rich traceback exception formatting.
+  - tiran/defusedxml#104: PEP 561 `py.typed` marker and full typing annotations.
+  - tiran/defusedxml#87: Standard `ElementTree.indent()` support.
+  - tiran/defusedxml#80: `Element` class export.
+  - tiran/defusedxml#79: `register_namespace()` helper.
+  - tiran/defusedxml#78: `fromstring(..., parser=None)` keyword signature parity.
+  - tiran/defusedxml#76, #77, #88: Safe non-destructive `defuse_stdlib()`.
+