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

uproot_custom-2.0.0.dev0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,34 @@
+name: Deploy docs
+
+on:
+    workflow_dispatch:
+    workflow_call:
+
+permissions:
+  contents: write
+
+jobs:
+    deploy-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]
+
+        - name: Build docs
+          run: |
+            sphinx-build -b html docs/ build/html
+
+        - name: Deploy to GitHub Pages
+          uses: peaceiris/actions-gh-pages@v3
+          with:
+            github_token: ${{ secrets.GITHUB_TOKEN }}
+            publish_dir: ./build/html

{uproot_custom-1.2.0 → uproot_custom-2.0.0.dev0}/.github/workflows/python-publish.yml

@@ -13,12 +13,17 @@ on:
     types: [published]
 
 permissions:
-  contents: read
+  contents: write
 
 jobs:
   build-wheels:
     uses: ./.github/workflows/build-wheels.yml
 
+  deploy-docs:
+    uses: ./.github/workflows/deploy-docs.yml
+    needs:
+      - pypi-publish
+
   pypi-publish:
     runs-on: ubuntu-latest
     needs:

{uproot_custom-1.2.0 → uproot_custom-2.0.0.dev0}/.github/workflows/run-pytest.yml

@@ -34,4 +34,4 @@ jobs:
       - name: Run pytest
         run: |
           pytest --version
-          pytest tests/
+          pytest -n auto tests/

uproot_custom-2.0.0.dev0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.2
+Name: uproot-custom
+Version: 2.0.0.dev0
+Summary: uproot extension for reading custom classes
+Author-Email: Mingrun Li <mrli@ihep.ac.cn>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+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-Dist: uproot>=5.0
+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"
+Description-Content-Type: text/markdown
+
+# 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`.
+
+## 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:
+
+- `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`.
+
+> [!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).
+
+> [!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.
+
+## Documentation
+
+View the [documentation](https://mrzimu.github.io/uproot-custom/) for more details about customizing your own `reader`/`factory`, and the architecture of `uproot-custom`.

uproot_custom-2.0.0.dev0/README.md

@@ -0,0 +1,26 @@
+# 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`.
+
+## 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:
+
+- `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`.
+
+> [!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).
+
+> [!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.
+
+## Documentation
+
+View the [documentation](https://mrzimu.github.io/uproot-custom/) for more details about customizing your own `reader`/`factory`, and the architecture of `uproot-custom`.

{uproot_custom-1.2.0 → uproot_custom-2.0.0.dev0}/cpp/include/uproot-custom/uproot-custom.hh

@@ -1,13 +1,16 @@
 #pragma once
 
-#include <cstdint>
-#include <memory>
 #include <pybind11/cast.h>
 #include <pybind11/detail/common.h>
 #include <pybind11/numpy.h>
 #include <pybind11/pybind11.h>
 #include <pybind11/pytypes.h>
 #include <pybind11/stl.h>
+
+#include <cstdint>
+#include <iostream>
+#include <memory>
+#include <sstream>
 #include <string>
 
 #if defined( _MSC_VER )
@@ -37,6 +40,8 @@ namespace uproot {
     const uint16_t kMaxVersion     = 0x3FFF;     // highest possible version number
     const int32_t kMapOffset = 2; // first 2 map entries are taken by null obj and self obj
 
+    const uint16_t kStreamedMemberWise = 1 << 14; // streamed member-wise mask
+
     class BinaryBuffer {
       public:
         enum EStatusBits {
@@ -125,6 +130,14 @@ namespace uproot {
             else return std::string();
         }
 
+        const std::string read_TString() {
+            uint32_t length = read<uint8_t>();
+            if ( length == 255 ) length = read<uint32_t>();
+            auto start = m_cursor;
+            m_cursor += length;
+            return std::string( start, m_cursor );
+        }
+
         void skip( const size_t n ) { m_cursor += n; }
 
         void skip_fNBytes() { read_fNBytes(); } // need to check the mask
@@ -148,9 +161,16 @@ namespace uproot {
             if ( fBits & ( kIsReferenced ) ) skip( 2 ); // pidf
         }
 
+        const uint8_t* get_data() const { return m_data; }
         const uint8_t* get_cursor() const { return m_cursor; }
+        const uint32_t* get_offsets() const { return m_offsets; }
         const uint64_t entries() const { return m_entries; }
 
+        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;
@@ -176,6 +196,31 @@ namespace uproot {
 
         virtual void read( BinaryBuffer& buffer ) = 0;
         virtual py::object data() const           = 0;
+
+        virtual uint32_t read_many( BinaryBuffer& buffer, const int64_t count ) {
+            for ( int32_t i = 0; i < count; i++ ) { read( buffer ); }
+            return count;
+        }
+
+        virtual uint32_t read_until( BinaryBuffer& buffer, const uint8_t* end_pos ) {
+            uint32_t cur_count = 0;
+            while ( buffer.get_cursor() < end_pos )
+            {
+                read( buffer );
+                cur_count++;
+            }
+            return cur_count;
+        }
+
+        virtual uint32_t read_many_memberwise( BinaryBuffer& buffer, const int64_t count ) {
+            if ( count < 0 )
+            {
+                std::stringstream msg;
+                msg << name() << "::read_many_memberwise with negative count: " << count;
+                throw std::runtime_error( msg.str() );
+            }
+            return read_many( buffer, count );
+        }
     };
 
     using SharedReader = shared_ptr<IElementReader>;
@@ -192,9 +237,9 @@ namespace uproot {
     }
 
     template <typename ReaderType, typename... Args>
-    void register_reader( py::module& m, const char* name ) {
+    void declare_reader( py::module& m, const char* name ) {
         py::class_<ReaderType, shared_ptr<ReaderType>, IElementReader>( m, name ).def(
-            py::init( &CreateReader<ReaderType, std::string, Args...> ) );
+            py::init( &CreateReader<ReaderType, Args...> ) );
     }
 
     /*
@@ -215,4 +260,29 @@ namespace uproot {
         return py::array_t<T>( size, data, capsule );
     }
 
+    /*
+    -----------------------------------------------------------------------------
+    -----------------------------------------------------------------------------
+    -----------------------------------------------------------------------------
+    */
+
+    template <typename... Args>
+    inline void debug_printf( const char* msg, Args... args ) {
+        bool do_print = getenv( "UPROOT_DEBUG" );
+#ifdef UPROOT_DEBUG
+        do_print = true;
+#endif
+        if ( !do_print ) return;
+        printf( msg, std::forward<Args>( args )... );
+    }
+
+    inline void debug_printf( uproot::BinaryBuffer& buffer, const size_t n = 100 ) {
+        bool do_print = getenv( "UPROOT_DEBUG" );
+#ifdef UPROOT_DEBUG
+        do_print = true;
+#endif
+        if ( !do_print ) return;
+        buffer.debug_print( n );
+    }
+
 } // namespace uproot