xml2arrow 0.16.0__tar.gz → 0.18.0__tar.gz

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/.github/workflows/CI.yml

@@ -31,9 +31,37 @@ jobs:
       - name: Run Ruff format
         run: ruff format python/ --check
 
+  rust-lint:
+    name: Rust Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt,clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Run rustfmt
+        run: cargo fmt --check
+      - name: Run clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+  type-check:
+    name: Type Check
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install mypy pyarrow
+      - name: Run mypy
+        run: mypy
+
   test:
     name: Test
-    needs: lint # Only run tests if linting passes
+    needs: [lint, rust-lint] # Only run tests if linting passes
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -48,11 +76,13 @@ jobs:
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
       - name: Install dependencies
-        run: pip install maturin pytest pytest-cov
+        run: pip install maturin pytest pytest-cov pyarrow
       - name: Build wheel
         run: maturin build --release --out dist
       - name: Install wheel
-        run: pip install --find-links=dist xml2arrow
+        # --no-index forces the just-built wheel; without it pip may pick a
+        # released version from PyPI and silently test the wrong artifact.
+        run: pip install --no-index --find-links=dist xml2arrow
       - name: Run tests with coverage
         run: pytest tests/ -v --cov=xml2arrow --cov-report=xml --cov-report=term
       - name: Upload coverage to Codecov

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "_xml2arrow"
-version = "0.16.0"
+version = "0.18.0"
 dependencies = [
  "arrow",
  "pyo3",
@@ -51,9 +51,9 @@ dependencies = [
 
 [[package]]
 name = "arrow"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d441fdda254b65f3e9025910eb2c2066b6295d9c8ed409522b8d2ace1ff8574c"
+checksum = "ffaaa3e009861fd829d0a24dd6f115aa8e4634324bb092147d43baafe69ca4a7"
 dependencies = [
  "arrow-arith",
  "arrow-array",
@@ -73,9 +73,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-arith"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ced5406f8b720cc0bc3aa9cf5758f93e8593cda5490677aa194e4b4b383f9a59"
+checksum = "3ac95125e1d71c4a252b5a9c729aef111e80418f08aaa6dbabd1ba66918247fc"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -87,9 +87,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-array"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "772bd34cacdda8baec9418d80d23d0fb4d50ef0735685bd45158b83dfeb6e62d"
+checksum = "0c60c79628e9a97cb90d7a0dc3e944f216a902f837d4ecabc14d524bddbbc137"
 dependencies = [
  "ahash",
  "arrow-buffer",
@@ -97,7 +97,7 @@ dependencies = [
  "arrow-schema",
  "chrono",
  "half",
- "hashbrown 0.16.0",
+ "hashbrown",
  "num-complex",
  "num-integer",
  "num-traits",
@@ -105,9 +105,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-buffer"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "898f4cf1e9598fdb77f356fdf2134feedfd0ee8d5a4e0a5f573e7d0aec16baa4"
+checksum = "6026f638c400e9878c1b1cc05c3cfd46fbf381285916ab408678701c1df46c1a"
 dependencies = [
  "bytes",
  "half",
@@ -117,9 +117,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-cast"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b0127816c96533d20fc938729f48c52d3e48f99717e7a0b5ade77d742510736d"
+checksum = "c82c236c3caf8df5664284f3f1fbe89938852163998c3fdbf37e84ac220445e9"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -138,9 +138,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-csv"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca025bd0f38eeecb57c2153c0123b960494138e6a957bbda10da2b25415209fe"
+checksum = "12714e5fb7954159af1e26d4e0d37108bcf1a2ad5ee5c5bf02a944d564d588b7"
 dependencies = [
  "arrow-array",
  "arrow-cast",
@@ -153,9 +153,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-data"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42d10beeab2b1c3bb0b53a00f7c944a178b622173a5c7bcabc3cb45d90238df4"
+checksum = "7bd568aa70c4ec5947027b0d5caee94877433b661a0bb9e8ddceeeb5f0c9b1ab"
 dependencies = [
  "arrow-buffer",
  "arrow-schema",
@@ -166,9 +166,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-ipc"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "609a441080e338147a84e8e6904b6da482cefb957c5cdc0f3398872f69a315d0"
+checksum = "e57ee4d470eab1a021bc4b63fa2b2c15d572892bf227b0a982d3b755a6c662b5"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -180,15 +180,16 @@ dependencies = [
 
 [[package]]
 name = "arrow-json"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ead0914e4861a531be48fe05858265cf854a4880b9ed12618b1d08cba9bebc8"
+checksum = "38f47e0e7a284e1f3707a780dc8cd5451b1614e9e398ea2d9ca03c7a2fe9a9ed"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
  "arrow-cast",
- "arrow-data",
+ "arrow-ord",
  "arrow-schema",
+ "arrow-select",
  "chrono",
  "half",
  "indexmap",
@@ -204,9 +205,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-ord"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "763a7ba279b20b52dad300e68cfc37c17efa65e68623169076855b3a9e941ca5"
+checksum = "a79cf73ad2eba8686ec2aa9bbf8671208e509025f166afc040cedbd94ffe4983"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -217,9 +218,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-pyarrow"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e63351dc11981a316c828a6032a5021345bba882f68bc4a36c36825a50725089"
+checksum = "b9e66bd74e4a47c6df9a2af16d9cca97e37cdfe5b3207d5e3558646e07957a27"
 dependencies = [
  "arrow-array",
  "arrow-data",
@@ -229,9 +230,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-row"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e14fe367802f16d7668163ff647830258e6e0aeea9a4d79aaedf273af3bdcd3e"
+checksum = "cea0f7d8ed6182f14952761e2c0f989852d5aa334fcbc49f73a9f2247c25b879"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -242,18 +243,18 @@ dependencies = [
 
 [[package]]
 name = "arrow-schema"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c30a1365d7a7dc50cc847e54154e6af49e4c4b0fddc9f607b687f29212082743"
+checksum = "80b3e786a0dd9103acd583a6fb486dbf2f3268466cc0bd571dcf34cef231c1f1"
 dependencies = [
  "bitflags",
 ]
 
 [[package]]
 name = "arrow-select"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78694888660a9e8ac949853db393af2a8b8fc82c19ce333132dfa2e72cc1a7fe"
+checksum = "067a67e0361f6c31f4a7248759f36ca4ca71b187a941ed4d49da1c7d3d4db624"
 dependencies = [
  "ahash",
  "arrow-array",
@@ -265,9 +266,9 @@ dependencies = [
 
 [[package]]
 name = "arrow-string"
-version = "58.1.0"
+version = "59.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61e04a01f8bb73ce54437514c5fd3ee2aa3e8abe4c777ee5cc55853b1652f79e"
+checksum = "99bc95847f3ff62a2b03d6f8ce2e3e78f01362060549a2a311898dd442f6256d"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -479,12 +480,6 @@ dependencies = [
  "num-traits",
 ]
 
-[[package]]
-name = "hashbrown"
-version = "0.16.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5419bdc4f6a9207fbeba6d11b604d481addf78ecd10c11ad51e76c2f6482748d"
-
 [[package]]
 name = "hashbrown"
 version = "0.17.0"
@@ -527,7 +522,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.17.0",
+ "hashbrown",
 ]
 
 [[package]]
@@ -752,9 +747,9 @@ dependencies = [
 
 [[package]]
 name = "quick-xml"
-version = "0.39.2"
+version = "0.41.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "958f21e8e7ceb5a1aa7fa87fab28e7c75976e0bfe7e23ff069e0a260f894067d"
+checksum = "e660451e55124f798a69a5af3f49ccfbefbd41910eefd25caf2393e1f3473ec1"
 dependencies = [
  "memchr",
 ]
@@ -1051,9 +1046,9 @@ checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
 [[package]]
 name = "xml2arrow"
-version = "0.16.0"
+version = "0.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dbf8199409730f9f76a71d4ee945b2e5eead8f1aece63e4aa907313083e4f1e2"
+checksum = "966e16865b1dc8abf5f1f4c4cb1600a5f36fc3382ddcf053ba2ae65def571ff3"
 dependencies = [
  "arrow",
  "atoi",

xml2arrow-0.18.0/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "_xml2arrow"
+version = "0.18.0"
+edition = "2024"
+readme = "README.md"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[lib]
+name = "_xml2arrow"
+crate-type = ["cdylib"]
+
+[dependencies]
+xml2arrow = { version = "0.18.0", features = ["python"] }
+arrow = { version = "59.0.0", features = ["pyarrow"] }
+
+[dependencies.pyo3]
+version = "0.28"
+features = ["extension-module", "abi3-py310"]
+
+# Wheel builds go through this profile (maturin build --release); the
+# size/speed win is worth the slower release compile.
+[profile.release]
+lto = true
+codegen-units = 1
+strip = "symbols"

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xml2arrow
-Version: 0.16.0
+Version: 0.18.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: MIT License
@@ -48,7 +48,10 @@ Rust crate for high performance.
 - 🎯 **Type conversion** including automatic scale and offset transforms for float fields
 - 💡 **Attribute and element extraction** using `@`-prefixed path segments for attributes
 - ⏹️ **Early termination** via `stop_at_paths` for efficiently reading only part of a file
-- 🐍 **Flexible input** — accepts file paths, path-like objects, or any file-like object
+- 🐍 **Flexible input** — accepts file paths, path-like objects, readable file-like
+  objects, or in-memory `bytes`/`bytearray` (parsed zero-copy, no intermediate buffering)
+- 🧵 **Thread-friendly** — the GIL is released while parsing, so threads sharing one
+  parser instance can parse multiple documents in parallel
 
 ## Installation
 
@@ -137,7 +140,8 @@ import polars as pl
 from xml2arrow import XmlToArrowParser
 
 parser = XmlToArrowParser("config.yaml")
-record_batches = parser.parse("data.xml")  # also accepts pathlib.Path or any file-like object
+record_batches = parser.parse("data.xml")  # also accepts pathlib.Path, bytes,
+                                           # bytearray, or any file-like object
 
 # Access a table by name
 batch = record_batches["measurements"]     # pyarrow.RecordBatch
@@ -158,6 +162,19 @@ names defined in your config. Because the values are standard PyArrow
 `RecordBatch` objects they integrate directly with pandas, Polars, DuckDB,
 and any other tool in the Arrow ecosystem.
 
+> **Tip:** Constructing an `XmlToArrowParser` validates the config and compiles
+> its path lookup table once, up front. When processing many files with the same
+> config, build the parser **once** and reuse it across `parse()` calls — this
+> amortizes that fixed setup cost and is noticeably faster than creating a new
+> parser per file, especially for many small documents.
+>
+> ```python
+> parser = XmlToArrowParser("config.yaml")  # validate + compile once
+> for path in xml_files:
+>     record_batches = parser.parse(path)   # reused for every file
+>     ...
+> ```
+
 ## Example
 
 This example extracts meteorological station data from a nested XML document into

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/README.md

@@ -19,7 +19,10 @@ Rust crate for high performance.
 - 🎯 **Type conversion** including automatic scale and offset transforms for float fields
 - 💡 **Attribute and element extraction** using `@`-prefixed path segments for attributes
 - ⏹️ **Early termination** via `stop_at_paths` for efficiently reading only part of a file
-- 🐍 **Flexible input** — accepts file paths, path-like objects, or any file-like object
+- 🐍 **Flexible input** — accepts file paths, path-like objects, readable file-like
+  objects, or in-memory `bytes`/`bytearray` (parsed zero-copy, no intermediate buffering)
+- 🧵 **Thread-friendly** — the GIL is released while parsing, so threads sharing one
+  parser instance can parse multiple documents in parallel
 
 ## Installation
 
@@ -108,7 +111,8 @@ import polars as pl
 from xml2arrow import XmlToArrowParser
 
 parser = XmlToArrowParser("config.yaml")
-record_batches = parser.parse("data.xml")  # also accepts pathlib.Path or any file-like object
+record_batches = parser.parse("data.xml")  # also accepts pathlib.Path, bytes,
+                                           # bytearray, or any file-like object
 
 # Access a table by name
 batch = record_batches["measurements"]     # pyarrow.RecordBatch
@@ -129,6 +133,19 @@ names defined in your config. Because the values are standard PyArrow
 `RecordBatch` objects they integrate directly with pandas, Polars, DuckDB,
 and any other tool in the Arrow ecosystem.
 
+> **Tip:** Constructing an `XmlToArrowParser` validates the config and compiles
+> its path lookup table once, up front. When processing many files with the same
+> config, build the parser **once** and reuse it across `parse()` calls — this
+> amortizes that fixed setup cost and is noticeably faster than creating a new
+> parser per file, especially for many small documents.
+>
+> ```python
+> parser = XmlToArrowParser("config.yaml")  # validate + compile once
+> for path in xml_files:
+>     record_batches = parser.parse(path)   # reused for every file
+>     ...
+> ```
+
 ## Example
 
 This example extracts meteorological station data from a nested XML document into

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/pyproject.toml

@@ -61,6 +61,14 @@ requires-python = ">=3.10"
 python-source = "python"
 module-name = "xml2arrow._xml2arrow"
 
+[tool.mypy]
+strict = true
+files = ["python/xml2arrow"]
+
+[[tool.mypy.overrides]]
+module = ["pyarrow", "pyarrow.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 # Target the minimum Python version supported by your project
 target-version = "py310"

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/python/xml2arrow/_xml2arrow.pyi

@@ -1,8 +1,9 @@
 from os import PathLike
-from typing import IO, Any
+from typing import IO, Any, final
 
 from pyarrow import RecordBatch
 
+@final
 class XmlToArrowParser:
     """A parser for converting XML files to Arrow tables based on a configuration.
 
@@ -13,24 +14,34 @@ class XmlToArrowParser:
             base exception.
     """
 
-    def __init__(self, config_path: str | PathLike) -> None:
+    def __init__(self, config_path: str | PathLike[str]) -> None:
         """Initializes the parser with a configuration file path.
 
+        The configuration is loaded, validated, and compiled here, once. Reuse a
+        single parser instance across many files to amortize this setup cost.
+
         Args:
             config_path: The path to the YAML configuration file.
 
         Raises:
-            Xml2ArrowError: If the configuration file cannot be loaded or parsed.
+            OSError: If the configuration file cannot be opened (e.g.
+                FileNotFoundError); the message includes the path.
+            Xml2ArrowError: If the configuration file cannot be loaded, parsed, or
+                validated. Because validation happens at construction time, an
+                invalid config (e.g. InvalidConfigError) is raised here rather
+                than on the first ``parse()`` call.
         """
 
     def parse(
         self,
-        source: str | PathLike | bytes | bytearray | IO[Any],
+        source: str | PathLike[str] | bytes | bytearray | IO[Any],
     ) -> dict[str, RecordBatch]:
         """Parses an XML source and returns a dictionary of Arrow RecordBatches.
 
         In-memory inputs (``bytes`` and ``bytearray``) take a zero-copy fast
         path. Paths and file-like objects stream through a buffered reader.
+        The GIL is released while parsing, so threads sharing one parser
+        instance can parse different sources in parallel.
 
         Args:
             source: The XML to parse. Accepts a path (``str`` or ``os.PathLike``),
@@ -42,12 +53,26 @@ class XmlToArrowParser:
             PyArrow RecordBatch objects.
 
         Raises:
+            OSError: If ``source`` is a path that cannot be opened (e.g.
+                FileNotFoundError); the message includes the path.
+            ValueError: If ``source`` is a ``str`` holding XML content rather
+                than a file path.
+            TypeError: If ``source`` is not a supported input type.
             Xml2ArrowError: If an error occurs during XML parsing or Arrow
                 table creation. This can include errors such as invalid XML,
-                incorrect configuration, or unsupported data types.
+                incorrect configuration, or unsupported data types. Exceptions
+                raised by a file-like object's ``read()`` method propagate
+                unchanged.
         """
 
     def __repr__(self) -> str: ...
 
+class Xml2ArrowError(Exception): ...
+class XmlParsingError(Xml2ArrowError): ...
+class YamlParsingError(Xml2ArrowError): ...
+class ParseError(Xml2ArrowError): ...
+class UnsupportedConversionError(Xml2ArrowError): ...
+class InvalidConfigError(Xml2ArrowError): ...
+
 def _get_version() -> str:
     """Returns the version of the xml2arrow package."""

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/src/file_like.rs

@@ -20,6 +20,11 @@ use pyo3::prelude::*;
 use pyo3::sync::PyOnceLock;
 
 /// A read-only adapter over a Python file-like object.
+///
+/// Exceptions raised inside `read()` are flattened into `io::Error` here (the
+/// `Read` interface demands it), but pyo3 stores the original `PyErr` as the
+/// inner error and upstream's `From<Error> for PyErr` recovers it, so the
+/// caller still sees the real exception rather than a stringified wrapper.
 pub struct PyBinaryFile {
     inner: Py<PyAny>,
     is_text: bool,

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/src/lib.rs

@@ -1,17 +1,18 @@
 use arrow::pyarrow::ToPyArrow;
 use pyo3::{
+    exceptions::{PyOSError, PyValueError},
     prelude::*,
     types::{PyByteArray, PyBytes, PyDict},
 };
 use std::fs::File;
 use std::io::{BufReader, Read};
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
+use xml2arrow::Parser;
 use xml2arrow::config::Config;
 use xml2arrow::errors::{
     InvalidConfigError, ParseError, UnsupportedConversionError, Xml2ArrowError, XmlParsingError,
     YamlParsingError,
 };
-use xml2arrow::{parse_xml, parse_xml_slice};
 
 mod file_like;
 use file_like::PyBinaryFile;
@@ -23,6 +24,41 @@ fn _get_version() -> &'static str {
     VERSION
 }
 
+/// Rebuilds a filesystem error as a Python `OSError` that carries the path;
+/// the raw `io::Error` drops it, which made "No such file or directory
+/// (os error 2)" unactionable. Also catches the common mistake of passing
+/// XML *content* as a `str`, which would otherwise surface as a baffling
+/// `FileNotFoundError` (or `ENAMETOOLONG` for larger documents).
+fn open_error(err: std::io::Error, path: &Path) -> PyErr {
+    let text = path.to_string_lossy();
+    if text
+        .trim_start_matches('\u{feff}')
+        .trim_start()
+        .starts_with('<')
+    {
+        return PyValueError::new_err(
+            "source looks like XML content, not a file path; pass XML content as bytes \
+             (e.g. source.encode()) or wrap it in io.StringIO",
+        );
+    }
+    let Some(code) = err.raw_os_error() else {
+        return err.into();
+    };
+    // Strip io::Error's "(os error N)" suffix; OSError re-renders the code.
+    let msg = err.to_string();
+    let msg = msg.split(" (os error ").next().unwrap_or(&msg).to_string();
+    let filename = text.into_owned();
+    // OSError's multi-arg constructor picks the right subclass
+    // (FileNotFoundError, PermissionError, ...) from the error code and
+    // includes the filename in the message. On Windows `raw_os_error` is a
+    // winerror, which OSError translates only via its fourth argument.
+    #[cfg(windows)]
+    let args = (code, msg, filename, code);
+    #[cfg(not(windows))]
+    let args = (code, msg, filename);
+    PyOSError::new_err(args)
+}
+
 /// Represents an XML input source.
 ///
 /// `Bytes` (zero-copy) and `OwnedBytes` (a safe copy of a mutable
@@ -46,11 +82,12 @@ impl<'a, 'py> FromPyObject<'a, 'py> for XmlInput<'py> {
         if let Ok(ba) = ob.cast::<PyByteArray>() {
             return Ok(Self::OwnedBytes(ba.to_vec()));
         }
+        // `PathBuf` extraction accepts both `str` and `os.PathLike`.
         if let Ok(path) = ob.extract::<PathBuf>() {
-            return Ok(Self::File(File::open(path)?));
-        }
-        if let Ok(path) = ob.extract::<String>() {
-            return Ok(Self::File(File::open(path)?));
+            return match File::open(&path) {
+                Ok(f) => Ok(Self::File(f)),
+                Err(e) => Err(open_error(e, &path)),
+            };
         }
         Ok(Self::FileLike(PyBinaryFile::from_bound(ob)?))
     }
@@ -72,10 +109,16 @@ impl Read for XmlReader {
 }
 
 /// A parser for converting XML files to Arrow tables based on a configuration.
+///
+/// The configuration's path trie is compiled once, here, and reused for every
+/// `parse()` call via [`xml2arrow::Parser`]. This matters most when one parser
+/// instance processes many files: the fixed per-document setup cost (config
+/// validation + path-trie construction) is paid a single time rather than on
+/// every parse.
 #[pyclass(name = "XmlToArrowParser")]
 pub struct XmlToArrowParser {
     config_path: PathBuf,
-    config: Config,
+    parser: Parser,
 }
 
 #[pymethods]
@@ -89,9 +132,16 @@ impl XmlToArrowParser {
     ///     XmlToArrowParser: A new parser instance.
     #[new]
     pub fn new(config_path: PathBuf) -> PyResult<Self> {
+        // A missing/unreadable config should name the offending path; the
+        // io::Error that bubbles out of `from_yaml_file` drops it.
+        std::fs::metadata(&config_path).map_err(|e| open_error(e, &config_path))?;
+        // Compile the config once here. `Parser::new` also runs config
+        // validation, so an invalid config now surfaces at construction time
+        // rather than on the first `parse()` call.
+        let config = Config::from_yaml_file(config_path.clone())?;
         Ok(XmlToArrowParser {
-            config_path: config_path.clone(),
-            config: Config::from_yaml_file(config_path)?,
+            config_path,
+            parser: Parser::new(&config)?,
         })
     }
 
@@ -99,6 +149,8 @@ impl XmlToArrowParser {
     ///
     /// In-memory inputs (``bytes`` and ``bytearray``) take a zero-copy fast
     /// path. Paths and file-like objects stream through a buffered reader.
+    /// The GIL is released while parsing, so threads sharing one parser
+    /// instance can parse different sources in parallel.
     ///
     /// Args:
     ///     source: The XML to parse. Accepts ``str``, ``os.PathLike``,
@@ -108,12 +160,20 @@ impl XmlToArrowParser {
     ///     dict: A dictionary where keys are table names (strings) and values are PyArrow RecordBatch objects.
     #[pyo3(signature = (source))]
     pub fn parse(&self, py: Python<'_>, source: XmlInput<'_>) -> PyResult<Py<PyAny>> {
+        // Detaching from the interpreter is sound for every variant: `Bytes`
+        // is immutable, `OwnedBytes` was copied at extraction, `File` is a
+        // plain OS handle, and `FileLike` re-attaches for each read() call.
         let batches = match source {
-            XmlInput::Bytes(b) => parse_xml_slice(b.as_bytes(), &self.config)?,
-            XmlInput::OwnedBytes(v) => parse_xml_slice(&v, &self.config)?,
-            XmlInput::File(f) => parse_xml(BufReader::new(XmlReader::File(f)), &self.config)?,
+            XmlInput::Bytes(b) => {
+                let bytes = b.as_bytes();
+                py.detach(|| self.parser.parse_slice(bytes))?
+            }
+            XmlInput::OwnedBytes(v) => py.detach(|| self.parser.parse_slice(&v))?,
+            XmlInput::File(f) => {
+                py.detach(|| self.parser.parse(BufReader::new(XmlReader::File(f))))?
+            }
             XmlInput::FileLike(f) => {
-                parse_xml(BufReader::new(XmlReader::FileLike(f)), &self.config)?
+                py.detach(|| self.parser.parse(BufReader::new(XmlReader::FileLike(f))))?
             }
         };
         let tables = PyDict::new(py);

{xml2arrow-0.16.0 → xml2arrow-0.18.0}/tests/test_xml2arrow.py

@@ -1115,6 +1115,162 @@ tables:
     assert batch.to_pydict()["value"] == ["Ünïcödé 中文 🌍"]
 
 
+def test_parse_str_path(stations_parser: XmlToArrowParser, test_data_dir: Path) -> None:
+    """Test that parse() accepts a plain str path, not just os.PathLike."""
+    record_batches = stations_parser.parse(str(test_data_dir / "stations.xml"))
+    assert "stations" in record_batches
+
+
+def test_parse_missing_file_error_includes_path(
+    stations_parser: XmlToArrowParser, tmp_path: Path
+) -> None:
+    """Test that a nonexistent XML path raises FileNotFoundError naming the file."""
+    missing = tmp_path / "nope.xml"
+    with pytest.raises(FileNotFoundError, match="nope.xml"):
+        stations_parser.parse(missing)
+    with pytest.raises(FileNotFoundError, match="nope.xml"):
+        stations_parser.parse(str(missing))
+
+
+def test_missing_config_file_error_includes_path(tmp_path: Path) -> None:
+    """Test that a nonexistent config path raises FileNotFoundError naming the file."""
+    with pytest.raises(FileNotFoundError, match="no_config.yaml"):
+        XmlToArrowParser(tmp_path / "no_config.yaml")
+
+
+def test_parse_xml_content_as_str_raises_helpful_error(
+    stations_parser: XmlToArrowParser,
+) -> None:
+    """Test that passing XML content as a str gets a hint instead of FileNotFoundError."""
+    with pytest.raises(ValueError, match=r"looks like XML content"):
+        stations_parser.parse("<report></report>")
+    # Leading whitespace and an XML declaration should still trigger the hint
+    with pytest.raises(ValueError, match=r"looks like XML content"):
+        stations_parser.parse('\n  <?xml version="1.0"?><report/>')
+
+
+def test_parse_rejects_non_source_types(stations_parser: XmlToArrowParser) -> None:
+    """Test that unsupported source types raise TypeError with the documented message."""
+    with pytest.raises(TypeError, match=r"path, bytes-like, or file-like"):
+        stations_parser.parse(12345)  # type: ignore[arg-type]
+
+
+def test_file_like_read_exception_propagates(stations_parser: XmlToArrowParser) -> None:
+    """Test that an exception raised inside a file-like's read() is re-raised as-is.
+
+    Before the read-error slot in PyBinaryFile, the original exception was
+    flattened into an XmlParsingError message string.
+    """
+
+    class ExplodingReader:
+        def read(self, _size: int) -> bytes:
+            raise ConnectionResetError("connection lost mid-stream")
+
+    with pytest.raises(ConnectionResetError, match="connection lost mid-stream"):
+        stations_parser.parse(ExplodingReader())
+
+
+def test_file_like_read_wrong_type_raises_type_error(
+    stations_parser: XmlToArrowParser,
+) -> None:
+    """Test that a read() returning a non-buffer type surfaces as TypeError."""
+
+    class BadReader:
+        def read(self, _size: int) -> int:
+            return 42
+
+    with pytest.raises(TypeError):
+        stations_parser.parse(BadReader())
+
+
+def test_parse_closed_file_raises_value_error(
+    stations_parser: XmlToArrowParser, test_data_dir: Path
+) -> None:
+    """Test that parsing an already-closed file raises the original ValueError."""
+    f = open(test_data_dir / "stations.xml", "rb")
+    f.close()
+    with pytest.raises(ValueError, match="closed file"):
+        stations_parser.parse(f)
+
+
+def test_parse_releases_the_gil(tmp_path: Path) -> None:
+    """Test that parse() releases the GIL so other Python threads keep running.
+
+    A worker thread parses a document sized so that one parse takes ~0.3s on
+    this machine; the main thread must be able to execute Python (several
+    loop iterations) before the worker finishes. If parse() held the GIL
+    throughout, the main thread would freeze until the parse completed,
+    accumulating at most the 1-2 iterations it can squeeze in before the
+    worker enters the extension call.
+
+    The document size is calibrated rather than hardcoded: a release wheel
+    parses roughly an order of magnitude faster than a debug build, and CI
+    runners add sleep-granularity noise, so a fixed size either starves the
+    counter on fast machines or wastes time on slow ones.
+    """
+    import threading
+    import time
+
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(
+        """
+tables:
+  - name: items
+    xml_path: /root
+    levels: [item]
+    fields:
+      - name: value
+        xml_path: /root/item/value
+        data_type: Int64
+        nullable: false
+"""
+    )
+    parser = XmlToArrowParser(config_path)
+
+    def build_doc(items: int) -> bytes:
+        return b"<root>" + b"<item><value>12345</value></item>" * items + b"</root>"
+
+    # Calibrate: measure a 200k-item parse, then scale the document so one
+    # parse takes ~0.3s (capped at 2M items / ~70 MB to bound memory and
+    # runtime on very slow machines).
+    target_seconds = 0.3
+    items = 200_000
+    start = time.perf_counter()
+    parser.parse(build_doc(items))
+    duration = time.perf_counter() - start
+    if duration < target_seconds:
+        items = min(int(items * target_seconds / max(duration, 1e-6)), 2_000_000)
+    big = build_doc(items)
+
+    started = threading.Event()
+    done = threading.Event()
+    worker_error: list[BaseException] = []
+
+    def work() -> None:
+        started.set()
+        try:
+            parser.parse(big)
+        except BaseException as exc:  # pragma: no cover - only on regression
+            worker_error.append(exc)
+        finally:
+            # Always set, even on failure: the main loop below must not spin
+            # forever if the parse raises.
+            done.set()
+
+    worker = threading.Thread(target=work)
+    worker.start()
+    assert started.wait(timeout=10)
+    iterations = 0
+    deadline = time.monotonic() + 60
+    while not done.is_set() and time.monotonic() < deadline:
+        iterations += 1
+        time.sleep(0.001)
+    worker.join(timeout=10)
+    assert done.is_set(), "worker never finished parsing"
+    assert not worker_error, f"parse() raised in the worker: {worker_error[0]!r}"
+    assert iterations >= 3, "main thread was starved: parse() appears to hold the GIL"
+
+
 def test_version_returns_string() -> None:
     """Test that the package version is a non-empty string.
 

xml2arrow-0.16.0/Cargo.toml

@@ -1,18 +0,0 @@
-[package]
-name = "_xml2arrow"
-version = "0.16.0"
-edition = "2024"
-readme = "README.md"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-[lib]
-name = "_xml2arrow"
-crate-type = ["cdylib"]
-
-[dependencies]
-xml2arrow = { version = "0.16.0", features = ["python"] }
-arrow = { version = "58.1.0", features = ["pyarrow"] }
-
-[dependencies.pyo3]
-version = "0.28"
-features = ["extension-module", "abi3-py310"]