xml2arrow 0.16.0__tar.gz → 0.17.0__tar.gz

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

@@ -31,6 +31,20 @@ jobs:
       - name: Run Ruff format
         run: ruff format python/ --check
 
+  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

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

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "_xml2arrow"
-version = "0.16.0"
+version = "0.17.0"
 dependencies = [
  "arrow",
  "pyo3",
@@ -1051,9 +1051,9 @@ checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
 [[package]]
 name = "xml2arrow"
-version = "0.16.0"
+version = "0.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dbf8199409730f9f76a71d4ee945b2e5eead8f1aece63e4aa907313083e4f1e2"
+checksum = "b0b0db78456d3e962998f25ccd2020b072aad6ba7240d3b27f2a1ec2f97eec20"
 dependencies = [
  "arrow",
  "atoi",

{xml2arrow-0.16.0 → xml2arrow-0.17.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "_xml2arrow"
-version = "0.16.0"
+version = "0.17.0"
 edition = "2024"
 readme = "README.md"
 
@@ -10,7 +10,7 @@ name = "_xml2arrow"
 crate-type = ["cdylib"]
 
 [dependencies]
-xml2arrow = { version = "0.16.0", features = ["python"] }
+xml2arrow = { version = "0.17.0", features = ["python"] }
 arrow = { version = "58.1.0", features = ["pyarrow"] }
 
 [dependencies.pyo3]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xml2arrow
-Version: 0.16.0
+Version: 0.17.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: MIT License
@@ -158,6 +158,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.17.0}/README.md

@@ -129,6 +129,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.17.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.17.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,19 +14,25 @@ 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.
+            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.
 
@@ -49,5 +56,12 @@ class XmlToArrowParser:
 
     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.17.0}/src/lib.rs

@@ -6,12 +6,12 @@ use pyo3::{
 use std::fs::File;
 use std::io::{BufReader, Read};
 use std::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;
@@ -72,10 +72,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 +95,13 @@ impl XmlToArrowParser {
     ///     XmlToArrowParser: A new parser instance.
     #[new]
     pub fn new(config_path: PathBuf) -> PyResult<Self> {
+        // 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)?,
         })
     }
 
@@ -109,12 +119,10 @@ impl XmlToArrowParser {
     #[pyo3(signature = (source))]
     pub fn parse(&self, py: Python<'_>, source: XmlInput<'_>) -> PyResult<Py<PyAny>> {
         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::FileLike(f) => {
-                parse_xml(BufReader::new(XmlReader::FileLike(f)), &self.config)?
-            }
+            XmlInput::Bytes(b) => self.parser.parse_slice(b.as_bytes())?,
+            XmlInput::OwnedBytes(v) => self.parser.parse_slice(&v)?,
+            XmlInput::File(f) => self.parser.parse(BufReader::new(XmlReader::File(f)))?,
+            XmlInput::FileLike(f) => self.parser.parse(BufReader::new(XmlReader::FileLike(f)))?,
         };
         let tables = PyDict::new(py);
         for (name, batch) in batches {