uproot-custom 2.2.0__tar.gz → 2.3.1__tar.gz

uproot_custom-2.3.1/.github/release.yml

@@ -0,0 +1,16 @@
+changelog:
+  categories:
+    - title: C++ API Changes
+      labels:
+        - break cpp
+    - title: New Features
+      labels:
+        - feature
+    - title: Bug Fixes, Performance Improvements and Refactors
+      labels:
+        - bug fix
+        - refactor
+        - performance
+    - title: Other Changes
+      labels:
+        - '*'

uproot_custom-2.3.1/.github/workflows/auto-update.yml

@@ -0,0 +1,49 @@
+name: Update pre-commit and uv lock
+
+on:
+  workflow_dispatch:
+  schedule:
+    # update hooks
+    - cron: 0 12 1 * *
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  auto-update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.13'
+          activate-environment: true
+
+      - name: Update pre-commit hooks
+        run: uvx pre-commit autoupdate
+
+      - name: Update uv lock
+        run: |
+          uv lock --upgrade
+          uvx pre-commit run --all-files
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        id: cpr
+        with:
+          title: 'chore: auto-update pre-commit hooks and uv lock'
+          commit-message: auto-update pre-commit hooks and uv lock
+          committer: github-actions[bot] ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
+          author: ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
+          branch: auto-update/pre-commit-uv
+
+      - name: Merge Pull Request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        if: steps.cpr.outputs.pull-request-number != ''
+        run: |
+          gh pr merge ${{ steps.cpr.outputs.pull-request-number }} --squash --auto --delete-branch

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/.github/workflows/build-wheels.yml

@@ -17,13 +17,18 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+
+      - name: Install cibuildwheel
+        run: pip install cibuildwheel==3.4
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.1.3
+        run: cibuildwheel --output-dir ./wheelhouse
 
       - name: Upload distributions
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ci-wheels-${{ matrix.os }}-${{ strategy.job-index }}
           path: ./wheelhouse/*.whl
@@ -33,12 +38,12 @@ jobs:
     name: Build source distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Build sdist
         run: pipx run build --sdist
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: ci-sdist
           path: dist/*.tar.gz

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/.github/workflows/deploy-docs.yml

@@ -11,24 +11,25 @@ jobs:
   deploy-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: '3.13'
+          activate-environment: true
 
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y doxygen
-          uv sync --group=docs
+          uv pip install -e . --group docs
 
       - name: Build docs
         run: |
-          sphinx-build -b html docs/ build/html
+          uv run sphinx-build -b html docs/ build/html
 
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./build/html

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/.github/workflows/python-publish.yml

@@ -45,7 +45,7 @@ jobs:
 
     steps:
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: dist/
           pattern: ci-*

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/.github/workflows/test-package.yml

@@ -16,42 +16,42 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
         os: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
 
       - name: Install dependencies
         run: |
-          uv lock --upgrade
-          uv sync --all-extras
+          uv pip install -e . --group dev
 
       - name: Run pytest
         run: |
-          pytest --version
-          pytest -v tests/
+          uv run pytest --version
+          uv run pytest -v tests/
 
   test-build-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: '3.13'
+          activate-environment: true
 
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y doxygen
-          uv lock --upgrade
-          uv sync --all-extras
+          uv pip install -e . --group docs
 
       - name: Build docs
         run: |
-          sphinx-build -b html docs/ build/html
+          uv run sphinx-build -b html docs/ build/html

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/.gitignore

@@ -206,4 +206,8 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
+# Versioneer
 _version.py
+
+# Claude
+.claude

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/.pre-commit-config.yaml

@@ -23,12 +23,12 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 26.1.0
+    rev: 26.3.1
     hooks:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.14
+    rev: v0.15.9
     hooks:
       - id: ruff-check
         args: [--fix, --show-fixes]

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: uproot-custom
-Version: 2.2.0
+Version: 2.3.1
 Summary: uproot extension for reading custom classes
 Author-Email: Mingrun Li <mrli@ihep.ac.cn>
 Classifier: Development Status :: 3 - Alpha
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Scientific/Engineering :: Mathematics
@@ -26,7 +27,7 @@ Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Project-URL: Homepage, https://github.com/mrzimu/uproot-custom
-Requires-Python: <3.14,>=3.9
+Requires-Python: <3.15,>=3.9
 Requires-Dist: uproot>=5.6.7
 Requires-Dist: numpy
 Requires-Dist: awkward>=2.8.0
@@ -36,9 +37,12 @@ Description-Content-Type: text/markdown
 
 Uproot-custom is an extension of [Uproot](https://uproot.readthedocs.io/en/latest/basic.html) that provides an enhanced way to read custom classes stored in `TTree`.
 
+> [!WARNING]
+> Because of earlier mistakes in version management, the `v2.x.x` series should still be treated as a development version rather than a stable release.
+
 ## What uproot-custom can do
 
-Uproot-custom can natively read complicated combinations of nested classes and c-style arrays (e.g. `map<int, map<int, map<int, string>>>`, `vector<TString>[3]`, etc), and memberwisely stored classes. It also exposes a way for users to implement their own readers for custom classes that are not supported by Uproot or uproot-custom built-in readers, so that users can read their custom classes seamlessly.
+Uproot-custom can natively read complicated combinations of nested classes and c-style arrays (e.g. `map<int, map<int, map<int, string>>>`, `vector<TString>[3]`, etc), and memberwisely stored classes. It also exposes a way for users to implement their own readers for custom classes that are not supported by Uproot or uproot-custom built-in readers.
 
 ## When to use uproot-custom
 
@@ -46,23 +50,21 @@ Uproot-custom aims to handle cases that classes are too complex for Uproot to re
 
 ## How uproot-custom works
 
-Uproot-custom uses a `reader`/`factory` mechanism to read classes:
+Uproot-custom uses a Reader / Factory mechanism to read classes:
 
 ```mermaid
 flowchart TD
     subgraph py["Python field"]
         direction TB
-        AsCustom --> fac["Factory (Primitive, STLVector, TString, ...)"]
+        AsCustom -- Recursively generate --> fac["Factory (Primitive, STLVector, TString, ...)"]
         fac["Factory (Primitive, STLVector, TString, ...)"] -- Optional --> form(["construct awkward forms"])
-        fac --> build_reader(["build corresponding C++ reader"])
+        fac --> build_reader(["build corresponding reader"])
         fac --> build_ak(["construct awkward arrays"])
     end
 
-    user_fac["User's Factory"] -. Register .-> fac
-
-    subgraph cpp["C++ field"]
+    subgraph reader_field["Reader (Python or C++)"]
         direction TB
-        build_reader --> reader["C++ Reader"]
+        build_reader --> reader["Reader"]
         reader --> read_bin(["read binary data"])
         read_bin --> ret_data(["return data"])
     end
@@ -71,16 +73,21 @@ flowchart TD
     raw_data --> build_ak
 ```
 
-- `reader` is a C++ class that implements the logic to read data from binary buffers.
-- `factory` is a Python class that creates, combines `reader`s, and post-processes the data read by `reader`s.
+- `Reader` is a class that implements the logic to read data from binary buffers. It can be written in **Python** (for development and debugging) or **C++** (for production performance).
+- `Factory` is a Python class that creates, combines `Reader`s, and post-processes the data read by `Reader`s.
 
-This machanism is implemented basing on `uproot_custom.AsCustom` interpretation. This makes uproot-custom well compatible with Uproot.
+This mechanism is implemented as `AsCustom` interpretation. This makes uproot-custom well compatible with Uproot.
 
 > [!TIP]
-> Users can implement their own `factory` and `reader`, register them to uproot-custom. An example of implementing a custom `factory`/`reader` can be found in [the example repository](https://github.com/mrzimu/uproot-custom-example).
+> Users can implement their own Factory and Reader, register them to uproot-custom. Start with a **Python reader** for rapid prototyping, then port the logic to **C++** for production speed. The default reader backend is C++; during development, explicitly set the backend to Python. An example of implementing a custom Factory / Reader can be found in [the example repository](https://github.com/mrzimu/uproot-custom-example).
 
 > [!NOTE]
-> Uproot-custom does not provide a full reimplementation of `ROOT`'s I/O system. Users are expected to implement their own `factory`/`reader` for their custom classes that built-in factories cannot handle.
+> Uproot-custom does not provide a full reimplementation of `ROOT`'s TTree I/O system. Users are expected to implement their own Factory / Reader for their custom classes that built-in factories cannot handle.
+
+## System Requirements
+
+- **C++17 compatible compiler**: Required for building C++ readers and the uproot-custom extension module. The CMake configuration sets `CMAKE_CXX_STANDARD 17`.
+- **Python 3.9+**: Uproot-custom supports Python 3.9 through 3.14.
 
 ## Documentation
 

uproot_custom-2.3.1/README.md

@@ -0,0 +1,59 @@
+# Introduction
+
+Uproot-custom is an extension of [Uproot](https://uproot.readthedocs.io/en/latest/basic.html) that provides an enhanced way to read custom classes stored in `TTree`.
+
+> [!WARNING]
+> Because of earlier mistakes in version management, the `v2.x.x` series should still be treated as a development version rather than a stable release.
+
+## What uproot-custom can do
+
+Uproot-custom can natively read complicated combinations of nested classes and c-style arrays (e.g. `map<int, map<int, map<int, string>>>`, `vector<TString>[3]`, etc), and memberwisely stored classes. It also exposes a way for users to implement their own readers for custom classes that are not supported by Uproot or uproot-custom built-in readers.
+
+## When to use uproot-custom
+
+Uproot-custom aims to handle cases that classes are too complex for Uproot to read, such as when their `Streamer` methods are overridden or some specific data members are not supported by Uproot.
+
+## How uproot-custom works
+
+Uproot-custom uses a Reader / Factory mechanism to read classes:
+
+```mermaid
+flowchart TD
+    subgraph py["Python field"]
+        direction TB
+        AsCustom -- Recursively generate --> fac["Factory (Primitive, STLVector, TString, ...)"]
+        fac["Factory (Primitive, STLVector, TString, ...)"] -- Optional --> form(["construct awkward forms"])
+        fac --> build_reader(["build corresponding reader"])
+        fac --> build_ak(["construct awkward arrays"])
+    end
+
+    subgraph reader_field["Reader (Python or C++)"]
+        direction TB
+        build_reader --> reader["Reader"]
+        reader --> read_bin(["read binary data"])
+        read_bin --> ret_data(["return data"])
+    end
+
+    ret_data --> raw_data[("tuple, list, numpy arrays, ...")]
+    raw_data --> build_ak
+```
+
+- `Reader` is a class that implements the logic to read data from binary buffers. It can be written in **Python** (for development and debugging) or **C++** (for production performance).
+- `Factory` is a Python class that creates, combines `Reader`s, and post-processes the data read by `Reader`s.
+
+This mechanism is implemented as `AsCustom` interpretation. This makes uproot-custom well compatible with Uproot.
+
+> [!TIP]
+> Users can implement their own Factory and Reader, register them to uproot-custom. Start with a **Python reader** for rapid prototyping, then port the logic to **C++** for production speed. The default reader backend is C++; during development, explicitly set the backend to Python. An example of implementing a custom Factory / Reader can be found in [the example repository](https://github.com/mrzimu/uproot-custom-example).
+
+> [!NOTE]
+> Uproot-custom does not provide a full reimplementation of `ROOT`'s TTree I/O system. Users are expected to implement their own Factory / Reader for their custom classes that built-in factories cannot handle.
+
+## System Requirements
+
+- **C++17 compatible compiler**: Required for building C++ readers and the uproot-custom extension module. The CMake configuration sets `CMAKE_CXX_STANDARD 17`.
+- **Python 3.9+**: Uproot-custom supports Python 3.9 through 3.14.
+
+## Documentation
+
+View the [documentation](https://mrzimu.github.io/uproot-custom/) for more details about customizing your own `reader`/`factory`, the architecture of uproot-custom, and build-only dependencies (e.g., `pybind11` is needed only at build time and should not be present in the runtime environment).

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/cpp/CMakeLists.txt

@@ -6,6 +6,7 @@ endif()
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(PYBIND11_NEWPYTHON ON)
+set(CMAKE_CXX_STANDARD 17)
 
 project(${SKBUILD_PROJECT_NAME}
     VERSION ${SKBUILD_PROJECT_VERSION}
@@ -15,7 +16,6 @@ project(${SKBUILD_PROJECT_NAME}
 find_package(pybind11 REQUIRED)
 
 # Add the uproot-custom module
-
 pybind11_add_module(cpp
     src/uproot-custom.cc
 )

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/cpp/include/uproot-custom/uproot-custom.hh

@@ -9,9 +9,10 @@
 
 #include <cstdint>
 #include <iostream>
+#include <map>
 #include <memory>
-#include <sstream>
 #include <string>
+#include <variant>
 
 #if defined( _MSC_VER )
 #    include <stdlib.h>
@@ -63,14 +64,26 @@ namespace uproot {
                              << 13 ///< if object ctor succeeded but object should not be used
         };
 
+        struct RefCls {
+            std::string name;
+        };
+
+        struct RefObj {
+            int64_t index;
+        };
+
+        using Reference = std::variant<RefCls, RefObj>;
+
         /**
          * @brief Construct a BinaryBuffer from numpy arrays.
          * @param data A numpy array of uint8_t containing the raw data.
          * @param offsets A numpy array of uint32_t containing the offsets for each entry.
          */
-        BinaryBuffer( py::array_t<uint8_t> data, py::array_t<uint32_t> offsets )
+        BinaryBuffer( py::array_t<uint8_t> data, py::array_t<uint32_t> offsets,
+                      uint32_t initial_cursor_position )
             : m_data( static_cast<uint8_t*>( data.request().ptr ) )
             , m_offsets( static_cast<uint32_t*>( offsets.request().ptr ) )
+            , m_initial_cursor_offset( initial_cursor_position )
             , m_entries( offsets.request().size - 1 )
             , m_cursor( static_cast<uint8_t*>( data.request().ptr ) ) {}
 
@@ -249,6 +262,28 @@ namespace uproot {
          */
         const uint32_t* get_offsets() const { return m_offsets; }
 
+        /**
+         * @brief Get the index object
+         *
+         * @return const uint32_t
+         */
+        const uint32_t get_index() const { return m_cursor - m_data; }
+
+        /**
+         * @brief Get the initial cursor offset, which is used for calculating relative
+         * offsets.
+         *
+         * @return const uint32_t
+         */
+        const uint32_t get_initial_cursor_offset() const { return m_initial_cursor_offset; }
+
+        /**
+         * @brief Get the references map, which is used for pointer reading.
+         *
+         * @return The references map.
+         */
+        std::map<uint32_t, Reference>& get_refs() { return m_refs; }
+
         /**
          * @brief Get the number of entries.
          */
@@ -265,10 +300,15 @@ namespace uproot {
         }
 
       private:
-        uint8_t* m_cursor;         ///< current cursor position
-        const uint64_t m_entries;  ///< number of entries
-        const uint8_t* m_data;     ///< raw data pointer
-        const uint32_t* m_offsets; ///< entry offsets pointer
+        uint8_t* m_cursor;                      ///< current cursor position
+        const uint64_t m_entries;               ///< number of entries
+        const uint8_t* m_data;                  ///< raw data pointer
+        const uint32_t* m_offsets;              ///< entry offsets pointer
+        const uint32_t m_initial_cursor_offset; ///< initial cursor position, used for
+                                                ///< calculating relative offsets
+
+        std::map<uint32_t, Reference> m_refs; ///< offset -> reference, used for pointer
+                                              ///< reading
     };
 
     /*

{uproot_custom-2.2.0 → uproot_custom-2.3.1}/cpp/share/cmake/uproot-customConfig.cmake

@@ -15,5 +15,6 @@ find_package_handle_standard_args(uproot-custom
 if(uproot-custom_FOUND AND NOT TARGET uproot-custom)
     add_library(uproot-custom INTERFACE IMPORTED)
     target_include_directories(uproot-custom INTERFACE ${UPROOT_CUSTOM_INCLUDE_DIR})
+    target_compile_features(uproot-custom INTERFACE cxx_std_17)
     message(DEBUG "[DEBUG] Target uproot-custom created")
 endif()