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

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

@@ -6,7 +6,7 @@ on:
 
 jobs:
     run-pytest:
-        uses: ./.github/workflows/run-pytest.yml
+        uses: ./.github/workflows/test-package.yml
 
     build-wheels:
         needs: run-pytest

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

@@ -16,12 +16,14 @@ jobs:
         - name: Set up Python
           uses: actions/setup-python@v4
           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
 
         - name: Build docs
           run: |

uproot_custom-2.1.0/.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.0.0.dev0/.github/workflows/run-pytest.yml → uproot_custom-2.1.0/.github/workflows/test-package.yml

@@ -12,7 +12,7 @@ permissions:
   contents: read
 
 jobs:
-  test:
+  test-package:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -34,4 +34,25 @@ jobs:
       - name: Run pytest
         run: |
           pytest --version
-          pytest -n auto tests/
+          pytest -v tests/
+
+  test-build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          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
+
+      - name: Build docs
+        run: |
+          sphinx-build -b html docs/ build/html

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: uproot-custom
-Version: 2.0.0.dev0
+Version: 2.1.0
 Summary: uproot extension for reading custom classes
 Author-Email: Mingrun Li <mrli@ihep.ac.cn>
 Classifier: Development Status :: 3 - Alpha
@@ -27,9 +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
+Requires-Dist: awkward>=2.8.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-xdist; extra == "dev"
@@ -49,6 +49,7 @@ 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: breathe; extra == "docs"
 Description-Content-Type: text/markdown
 
 # Introduction
@@ -63,6 +64,29 @@ 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.
 

{uproot_custom-2.0.0.dev0 → uproot_custom-2.1.0}/README.md

@@ -10,6 +10,29 @@
 
 `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.
 

{uproot_custom-2.0.0.dev0 → uproot_custom-2.1.0}/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