uproot-custom 2.0.0.dev0__tar.gz → 2.1.1__tar.gz

{uproot_custom-2.0.0.dev0 → uproot_custom-2.1.1}/.github/workflows/build-wheels.yml

@@ -5,11 +5,11 @@ on:
     workflow_call:
 
 jobs:
-    run-pytest:
-        uses: ./.github/workflows/run-pytest.yml
+    test-package:
+        uses: ./.github/workflows/test-package.yml
 
     build-wheels:
-        needs: run-pytest
+        needs: test-package
         runs-on: ${{ matrix.os }}
         name: Build wheels on ${{ matrix.os }}
         strategy:
@@ -29,7 +29,7 @@ jobs:
                 path: ./wheelhouse/*.whl
 
     build-sdist:
-        needs: run-pytest
+        needs: test-package
         name: Build source distribution
         runs-on: ubuntu-latest
         steps:

{uproot_custom-2.0.0.dev0 → uproot_custom-2.1.1}/.github/workflows/deploy-docs.yml

@@ -13,15 +13,15 @@ jobs:
         steps:
         - uses: actions/checkout@v4
 
-        - name: Set up Python
-          uses: actions/setup-python@v4
+        - uses: astral-sh/setup-uv@v5
           with:
-            python-version: '3.13'
+            python-version: "3.13"
 
         - name: Install dependencies
           run: |
-            python -m pip install --upgrade pip
-            pip install .[docs]
+            sudo apt-get update
+            sudo apt-get install -y doxygen
+            uv sync --group=docs
 
         - name: Build docs
           run: |

uproot_custom-2.1.1/.github/workflows/semantic-pr-titles.yml

@@ -0,0 +1,19 @@
+name: 'Lint PR'
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - reopened
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

uproot_custom-2.1.1/.github/workflows/test-package.yml

@@ -0,0 +1,57 @@
+name: Test package
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test-package:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv lock --upgrade
+          uv sync --all-extras
+
+      - name: Run pytest
+        run: |
+          pytest --version
+          pytest -v tests/
+
+  test-build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen
+          uv lock --upgrade
+          uv sync --all-extras
+
+      - name: Build docs
+        run: |
+          sphinx-build -b html docs/ build/html

uproot_custom-2.1.1/.github/workflows/weekly-build.yml

@@ -0,0 +1,10 @@
+name: Weekly build
+
+on:
+  schedule:
+    - cron: '0 12 * * 5'  # Runs every day at 20:00 Beijing time
+  workflow_dispatch:
+
+jobs:
+  weekly-build:
+    uses: ./.github/workflows/build-wheels.yml

{uproot_custom-2.0.0.dev0 → uproot_custom-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: uproot-custom
-Version: 2.0.0.dev0
+Version: 2.1.1
 Summary: uproot extension for reading custom classes
 Author-Email: Mingrun Li <mrli@ihep.ac.cn>
 Classifier: Development Status :: 3 - Alpha
@@ -27,28 +27,9 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Project-URL: Homepage, https://github.com/mrzimu/uproot-custom
 Requires-Python: <3.14,>=3.9
-Requires-Dist: uproot>=5.0
+Requires-Dist: uproot>=5.6.7
 Requires-Dist: numpy
-Requires-Dist: awkward
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-xdist; extra == "dev"
-Requires-Dist: dask[complete]; extra == "dev"
-Requires-Dist: dask-awkward; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: sphinx>=8.2; extra == "docs"
-Requires-Dist: sphinx-book-theme; extra == "docs"
-Requires-Dist: myst_parser; extra == "docs"
-Requires-Dist: sphinx-design; extra == "docs"
-Requires-Dist: sphinx-copybutton; extra == "docs"
-Requires-Dist: sphinxext-rediraffe; extra == "docs"
-Requires-Dist: sphinxext-opengraph; extra == "docs"
-Requires-Dist: sphinx-tippy; extra == "docs"
-Requires-Dist: sphinx-togglebutton; extra == "docs"
-Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
-Requires-Dist: sphinx-autobuild; extra == "docs"
-Requires-Dist: sphinx-intl; extra == "docs"
+Requires-Dist: awkward>=2.8.0
 Description-Content-Type: text/markdown
 
 # Introduction
@@ -63,13 +44,36 @@ Description-Content-Type: text/markdown
 
 `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, ...)"]
+        fac["Factory (Primitive, STLVector, TString, ...)"] -- Optional --> form(["construct awkward forms"])
+        fac --> build_reader(["build corresponding C++ reader"])
+        fac --> build_ak(["construct awkward arrays"])
+    end
+
+    user_fac["User's Factory"] -. Register .-> fac
+
+    subgraph cpp["C++ field"]
+        direction TB
+        build_reader --> reader["C++ 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 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.
 
-This machanism is implemented as `uproot_custom.AsCustom` interpretation. `uproot-custom` wraps `uproot.interpretation.identify.interpretation_of` method to intercept the interpretation of specific branches. This makes `uproot-custom` well compatible with `uproot`.
+This machanism is implemented basing on `uproot_custom.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 repository](https://github.com/mrzimu/uproot-custom/tree/main/example).
+> 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).
 
 > [!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-2.0.0.dev0 → uproot_custom-2.1.1}/README.md

@@ -10,13 +10,36 @@
 
 `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, ...)"]
+        fac["Factory (Primitive, STLVector, TString, ...)"] -- Optional --> form(["construct awkward forms"])
+        fac --> build_reader(["build corresponding C++ reader"])
+        fac --> build_ak(["construct awkward arrays"])
+    end
+
+    user_fac["User's Factory"] -. Register .-> fac
+
+    subgraph cpp["C++ field"]
+        direction TB
+        build_reader --> reader["C++ 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 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.
 
-This machanism is implemented as `uproot_custom.AsCustom` interpretation. `uproot-custom` wraps `uproot.interpretation.identify.interpretation_of` method to intercept the interpretation of specific branches. This makes `uproot-custom` well compatible with `uproot`.
+This machanism is implemented basing on `uproot_custom.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 repository](https://github.com/mrzimu/uproot-custom/tree/main/example).
+> 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).
 
 > [!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-2.0.0.dev0 → uproot_custom-2.1.1}/cpp/include/uproot-custom/uproot-custom.hh

@@ -26,6 +26,10 @@
 #    error "Unsupported compiler!"
 #endif
 
+/**
+ * @brief Macro to import the uproot_custom.cpp module.
+ * @note This macro should be used in the `PYBIND11_MODULE` definition of your module.
+ */
 #define IMPORT_UPROOT_CUSTOM_CPP pybind11::module_::import( "uproot_custom.cpp" );
 
 namespace uproot {
@@ -59,12 +63,23 @@ namespace uproot {
                              << 13 ///< if object ctor succeeded but object should not be used
         };
 
+        /**
+         * @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 )
             : m_data( static_cast<uint8_t*>( data.request().ptr ) )
             , m_offsets( static_cast<uint32_t*>( offsets.request().ptr ) )
             , m_entries( offsets.request().size - 1 )
             , m_cursor( static_cast<uint8_t*>( data.request().ptr ) ) {}
 
+        /**
+         * @brief Read a value of type T from the buffer, handling endianness.
+         *
+         * @tparam T The type to read.
+         * @return The value read from the buffer.
+         */
         template <typename T>
         const T read() {
             constexpr auto size = sizeof( T );
@@ -107,8 +122,19 @@ namespace uproot {
             }
         }
 
+        /**
+         * @brief Read the fVersion field from the buffer
+         *
+         * @return The fVersion value
+         */
         const int16_t read_fVersion() { return read<int16_t>(); }
 
+        /**
+         * @brief Read the fNBytes field from the buffer, checking the byte count mask.
+         *
+         * @return The fNBytes value without the mask.
+         * @exception std::runtime_error if the byte count mask is not set.
+         */
         const uint32_t read_fNBytes() {
             auto byte_count = read<uint32_t>();
             if ( !( byte_count & kByteCountMask ) )
@@ -116,6 +142,11 @@ namespace uproot {
             return byte_count & ~kByteCountMask;
         }
 
+        /**
+         * @brief Read a null-terminated (`\0`) string from the buffer.
+         *
+         * @return The string read from the buffer.
+         */
         const std::string read_null_terminated_string() {
             auto start = m_cursor;
             while ( *m_cursor != 0 ) { m_cursor++; }
@@ -123,6 +154,14 @@ namespace uproot {
             return std::string( start, m_cursor );
         }
 
+        /**
+         * @brief Read an object header from the buffer. The object header has `fNBytes`,
+         * `fVersion`, `fTag`. If `fTag == kNewClassTag`, then a null-terminated class name
+         * follows.
+         *
+         * @return The class name if the object is a new class, empty string
+         * otherwise.
+         */
         const std::string read_obj_header() {
             read_fNBytes();
             auto fTag = read<uint32_t>();
@@ -130,6 +169,13 @@ namespace uproot {
             else return std::string();
         }
 
+        /**
+         * @brief Read a TString from the buffer. A TString has `length` (uint8_t). If `length
+         * == 255`, then the `length` is a following uint32_t. Then following `length` bytes of
+         * string data.
+         *
+         * @return The TString data read from the buffer, as a std::string.
+         */
         const std::string read_TString() {
             uint32_t length = read<uint8_t>();
             if ( length == 255 ) length = read<uint32_t>();
@@ -138,21 +184,48 @@ namespace uproot {
             return std::string( start, m_cursor );
         }
 
+        /**
+         * @brief Skip `n` bytes in the buffer.
+         *
+         * @param n Number of bytes to skip.
+         */
         void skip( const size_t n ) { m_cursor += n; }
 
-        void skip_fNBytes() { read_fNBytes(); } // need to check the mask
+        /**
+         * @brief Skip the fNBytes field. Equivalent to read_fNBytes() but does not return the
+         * value, since the mask need to be checked.
+         */
+        void skip_fNBytes() { read_fNBytes(); }
+
+        /**
+         * @brief Skip the fVersion field.
+         */
         void skip_fVersion() { skip( 2 ); }
+
+        /**
+         * @brief Skip a null-terminated (`\0`) string in the buffer.
+         */
         void skip_null_terminated_string() {
             while ( *m_cursor != 0 ) { m_cursor++; }
             m_cursor++;
         }
 
+        /**
+         * @brief Skip an object header in the buffer. The object header has `fNBytes`,
+         * `fVersion`, `fTag`. If `fTag == kNewClassTag`, then a null-terminated class name
+         * follows.
+         */
         void skip_obj_header() {
             skip_fNBytes();
             auto fTag = read<uint32_t>();
             if ( fTag == kNewClassTag ) skip_null_terminated_string();
         }
 
+        /**
+         * @brief Skip a TObject in the buffer. A TObject has `fVersion` (2 bytes), `fUniqueID`
+         * (4 bytes), `fBits` (4 bytes). If `fBits & kIsReferenced`, then a `pidf` (2 bytes)
+         * follows.
+         */
         void skip_TObject() {
             // TODO: CanIgnoreTObjectStreamer() ?
             skip_fVersion();
@@ -161,21 +234,41 @@ namespace uproot {
             if ( fBits & ( kIsReferenced ) ) skip( 2 ); // pidf
         }
 
+        /**
+         * @brief Get the raw data pointer.
+         */
         const uint8_t* get_data() const { return m_data; }
+
+        /**
+         * @brief Get the current cursor pointer.
+         */
         const uint8_t* get_cursor() const { return m_cursor; }
+
+        /**
+         * @brief Get the entry offsets array pointer.
+         */
         const uint32_t* get_offsets() const { return m_offsets; }
+
+        /**
+         * @brief Get the number of entries.
+         */
         const uint64_t entries() const { return m_entries; }
 
+        /**
+         * @brief Debug print the next `n` bytes from the current cursor.
+         *
+         * @param n Number of bytes to print.
+         */
         void debug_print( const size_t n = 100 ) const {
             for ( size_t i = 0; i < n; i++ ) { std::cout << (int)*( m_cursor + i ) << " "; }
             std::cout << std::endl;
         }
 
       private:
-        uint8_t* m_cursor;
-        const uint64_t m_entries;
-        const uint8_t* m_data;
-        const uint32_t* m_offsets; // by the time, this is not used
+        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
     };
 
     /*
@@ -184,24 +277,74 @@ namespace uproot {
     -----------------------------------------------------------------------------
     */
 
-    class IElementReader {
+    /**
+     * @brief Interface for element readers. All element readers must inherit from this class.
+     */
+    class IReader {
       protected:
-        const std::string m_name;
+        const std::string m_name; ///< name of the reader
 
       public:
-        IElementReader( std::string name ) : m_name( name ) {}
-        virtual ~IElementReader() = default;
-
+        /**
+         * @brief Construct a new IReader object.
+         *
+         * @param name Name of the reader.
+         */
+        IReader( std::string name ) : m_name( name ) {}
+
+        virtual ~IReader() = default;
+
+        /**
+         * @brief Get the name of the reader.
+         *
+         * @return Name of the reader.
+         */
         virtual const std::string name() const { return m_name; }
 
+        /**
+         * @brief Read an element from the buffer.
+         *
+         * @param buffer The binary buffer to read from.
+         */
         virtual void read( BinaryBuffer& buffer ) = 0;
-        virtual py::object data() const           = 0;
 
+        /**
+         * @brief Get the data read by the reader. This should be called after the whole
+         * reading process.
+         *
+         * @return The data read by the reader.
+         */
+        virtual py::object data() const = 0;
+
+        /**
+         * @brief Read multiple elements from the buffer in one go. Repeatedly calls @ref
+         * read() by default.
+         *
+         * @note When multiple elements are stored together, some classes may have "one common
+         * header + multiple data objects" format. This method can be overridden to handle such
+         * cases more efficiently.
+         *
+         * @param buffer The binary buffer to read from.
+         * @param count Number of elements to read.
+         * @return Number of elements read.
+         */
         virtual uint32_t read_many( BinaryBuffer& buffer, const int64_t count ) {
             for ( int32_t i = 0; i < count; i++ ) { read( buffer ); }
             return count;
         }
 
+        /**
+         * @brief Read elements from the buffer until reaching the end position. Repeatedly
+         * calls @ref read() method by default.
+         *
+         * @note When multiple elements are stored together, some classes may have "one common
+         * header + multiple data objects" format. This method can be overridden to handle such
+         * cases more efficiently.
+         *
+         * @param buffer The binary buffer to read from.
+         * @param end_pos The end position pointer.
+         * @return Number of elements read.
+         */
         virtual uint32_t read_until( BinaryBuffer& buffer, const uint8_t* end_pos ) {
             uint32_t cur_count = 0;
             while ( buffer.get_cursor() < end_pos )
@@ -212,6 +355,15 @@ namespace uproot {
             return cur_count;
         }
 
+        /**
+         * @brief Read multiple elements from the buffer in member-wise fashion. This method
+         * checks for negative count and calls @ref read_many() by default. It can be
+         * overridden to handle member-wise reading more efficiently.
+         *
+         * @param buffer The binary buffer to read from.
+         * @param count Number of elements to read.
+         * @return Number of elements read.
+         */
         virtual uint32_t read_many_memberwise( BinaryBuffer& buffer, const int64_t count ) {
             if ( count < 0 )
             {
@@ -223,7 +375,19 @@ namespace uproot {
         }
     };
 
-    using SharedReader = shared_ptr<IElementReader>;
+    /**
+     * @brief Deprecated alias for IReader.
+     * @deprecated Use IReader instead.
+     */
+    using IElementReader
+        [[deprecated( "IElementReader is deprecated. Use IReader instead." )]] = IReader;
+
+    /**
+     * @brief Shortcut for shared pointer to IReader.
+     * @note When a reader requires another reader as a member, it must use
+     * `std::shared_ptr<IReader>` to properly handle lifetime management.
+     */
+    using SharedReader = shared_ptr<IReader>;
 
     /*
     -----------------------------------------------------------------------------
@@ -231,14 +395,33 @@ namespace uproot {
     -----------------------------------------------------------------------------
     */
 
+    /**
+     * @brief Helper function to create a shared pointer to a reader. Pybind11 requires
+     * shared_ptr to handle object lifetime correctly.
+     *
+     * @tparam ReaderType The type of the reader.
+     * @tparam Args The argument types for the reader constructor.
+     * @param args The arguments for the reader constructor.
+     * @return The shared pointer to the created reader.
+     */
     template <typename ReaderType, typename... Args>
     shared_ptr<ReaderType> CreateReader( Args... args ) {
         return std::make_shared<ReaderType>( std::forward<Args>( args )... );
     }
 
+    /**
+     * @brief Helper function to declare a reader class in a pybind11 module. Automatically
+     * wraps the class' constructor to return a shared_ptr. User should always use this
+     * function to declare reader classes.
+     *
+     * @tparam ReaderType The type of the reader.
+     * @tparam Args The argument types for the reader constructor.
+     * @param m The declaring pybind11 module.
+     * @param name The name of the reader class in Python.
+     */
     template <typename ReaderType, typename... Args>
     void declare_reader( py::module& m, const char* name ) {
-        py::class_<ReaderType, shared_ptr<ReaderType>, IElementReader>( m, name ).def(
+        py::class_<ReaderType, shared_ptr<ReaderType>, IReader>( m, name ).def(
             py::init( &CreateReader<ReaderType, Args...> ) );
     }
 
@@ -248,6 +431,14 @@ namespace uproot {
     -----------------------------------------------------------------------------
     */
 
+    /**
+     * @brief Convert a shared pointer to a std::vector<T> to a numpy array without copying.
+     * User can use this function to return numpy arrays from reader's data() method.
+     *
+     * @tparam T The element type of the vector.
+     * @param seq The shared pointer to the std::vector<T>.
+     * @return The numpy array wrapping the vector data.
+     */
     template <typename T>
     inline py::array_t<T> make_array( shared_ptr<std::vector<T>> seq ) {
         auto size = seq->size();
@@ -266,6 +457,14 @@ namespace uproot {
     -----------------------------------------------------------------------------
     */
 
+    /**
+     * @brief Debug print function. Prints only when macro or environment varialbe with name
+     * `UPROOT_DEBUG` is defined. Use this function like `printf()`.
+     *
+     * @tparam Args Argument types. No need to specify explicitly.
+     * @param msg The format string.
+     * @param args Arguments to format.
+     */
     template <typename... Args>
     inline void debug_printf( const char* msg, Args... args ) {
         bool do_print = getenv( "UPROOT_DEBUG" );
@@ -276,6 +475,14 @@ namespace uproot {
         printf( msg, std::forward<Args>( args )... );
     }
 
+    /**
+     * @brief Debug print function for BinaryBuffer. Prints only when macro or environment
+     * varialbe with name `UPROOT_DEBUG` is defined. Call @ref BinaryBuffer::debug_print()
+     * internally.
+     *
+     * @param buffer The BinaryBuffer to print.
+     * @param n Number of bytes to print.
+     */
     inline void debug_printf( uproot::BinaryBuffer& buffer, const size_t n = 100 ) {
         bool do_print = getenv( "UPROOT_DEBUG" );
 #ifdef UPROOT_DEBUG