uproot-custom 1.0.0a1__tar.gz

uproot_custom-1.0.0a1/.clang-format

@@ -0,0 +1,127 @@
+# This .clang_format file is derectly copied from Gaudi project.
+---
+Language:        Cpp
+BasedOnStyle:  Google
+AccessModifierOffset: -2
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: Always
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: AllIfsAndElse
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: true
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      true
+  IndentBraces:    false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: true
+BreakConstructorInitializers: BeforeComma
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:     95
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
+    Priority:        2
+  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
+    Priority:        3
+  - Regex:           '.*'
+    Priority:        1
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+IndentPPDirectives: AfterHash
+IndentWidth:     4
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: All
+ObjCBinPackProtocolList: Auto
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 60
+PenaltyBreakFirstLessLess: 30
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    CaseSensitive
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: true
+Standard:        c++11
+TabWidth:        8
+UseTab:          Never
+---
+Language:        Json
+IndentWidth:     4
+ColumnLimit:     95
+---
+Language:        JavaScript
+ColumnLimit:     95
+---
+Language: ObjC
+# Don't format Objective-C, Objective-C++ files.
+DisableFormat: true
+...

uproot_custom-1.0.0a1/.gitignore

@@ -0,0 +1,209 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+_version.py

uproot_custom-1.0.0a1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Mingrun Li
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

uproot_custom-1.0.0a1/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.2
+Name: uproot-custom
+Version: 1.0.0a1
+Summary: uproot extension for reading custom classes
+Author-Email: Mingrun Li <mrun_lee@foxmail.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Project-URL: Repository, https://github.com/mrzimu/uproot-custom
+Requires-Python: >=3.9
+Requires-Dist: uproot>=5.0
+Requires-Dist: awkward
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Description-Content-Type: text/markdown
+
+# uproot-custom
+
+This is a prototype repository of an extension that allows `uproot` to read custom classes from ROOT files.
+
+`uproot` can already read some custom classes directly. However, in some cases, custom 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`.
+
+This extension privides a `Reader` interface and allows you to read such custom classes by providing  your own `Reader`. The `Reader` interface defines how to read the data members of a class from the binary stream.
+
+## Design overview
+
+In ROOT, data are stored in a tree structure. For example, when a custom class is defined as:
+
+```cpp
+class TMySubClass : public TObject {
+    int m_index;
+    float m_x;
+};
+
+class TMyClass : public TObject {
+    double m_energy;
+    std::vector<MySubClass> m_daughters;
+};
+```
+
+The data tree is:
+
+```mermaid
+graph TD
+    A([TMyClass]) --> B(double m_energy)
+    A --> C(std::vector&lt;TMySubClass&gt; m_daughters)
+    C --> D([TMySubClass])
+    D --> E(int m_index)
+    D --> F(float m_x)
+```
+
+To handle the tree-like data structure, `Reader` is introduced. It consists of `Python` and `C++` parts. The `Python` part is responsible for generating the information tree, constructing C++ readers, and reconstructing data to `awkward` array. The `C++` part is responsible for reading the data members of the class from the binary stream.
+
+### Generate information tree
+
+`uproot` can read these structure information from the ROOT file, but not in tree format. So the first step is to generate an information tree from the ROOT file. The information tree is a nested structure that contains the data members of the class, including types, names and children if any.
+
+### Construct C++ readers
+
+According to the information tree, we can instantiate C++ readers and combine them into a tree structure. The top reader drives its sub-readers to read data recursively. After the reading process,
+readers obtain the results from their sub-readers recursively, then the top reader returns the final result.
+
+### Reconstruct data to `awkward` array
+
+Since embedding arrays together into `awkward` array in C++ is not straightforward, we left this task to Python. After the C++ reader returns the result, we can reconstruct the data into `awkward` array according to the information tree.
+
+## Predefined readers
+
+`uproot-custom` provides some predefined readers for common ROOT classes:
+
+| Reader             | Description |
+|--------------------|-------------|
+| BasicTypeReader<T> | Reads basic types like `int`, `float`, `double`, etc. |
+| TObjectReader      | Skip `TObject` header when reading classes that inherit from `TObject`. |
+| TStringReader      | Reads `TString` |
+| STLSeqReader       | Reads `std::vector`, `std::array`, etc. |
+| STLMapReader       | Reads `std::map`, `std::unordered_map`, etc. |
+| STLStringReader    | Reads `std::string` |
+| TArrayReader<T>    | Reads `TArray` types like `TArrayI`, `TArrayF`, `TArrayD`, etc. |
+| ObjectReader       | Reads custom classes that inherit from `TObject`. |
+| CArrayReader       | Reads C-style arrays like `int[]` |
+| EmptyReader        | A reader that does nothing. Some branches may not have any data, and the information of the corresponding class will not be stored in the ROOT file. In this case, `EmptyReader` is used to skip the branch. |
+
+## Implement your own `Reader`
+
+### Full example
+
+A complete example of how to impolement your own readers is available in the `example` directory of this repository.
+
+### Pre-requisites
+
+Make sure you have `GCC>13.1`/`Clang>=16.0.0`/`MSVC>=19.31`, `cmake` installed on your system.
+
+1. Create a Python project and install `uproot-custom`:
+
+    ```bash
+    mkdir my_reader
+    cd my_reader
+    python3 -m venv .venv
+    source .venv/bin/activate
+    pip install uproot-custom
+    ```
+
+2. Create a `pyproject.toml` file in the root directory of your project:
+
+    ```toml
+    [build-system]
+    requires = ["scikit-build-core>=0.11", "pybind11>=2.10.0", "uproot-custom"]
+    build-backend = "scikit_build_core.build"
+
+    [project]
+    name = "my-reader"
+    requires-python = ">=3.9"
+    dependencies = ["uproot-custom"]
+    version = "0.1.0"
+
+    [tool.scikit-build]
+    wheel.packages = ["my_reader"]
+    build-dir = "build/{wheel_tag}"
+    cmake.source-dir = "cpp"
+    cmake.build-type = "Debug" # Comment for release builds
+
+    [tool.black]
+    exclude = "/(build|dist|env|.git|.tox|.eggs|.venv)/"
+    line-length = 95
+    target-version = ['py39', 'py310', 'py311', 'py312', 'py313']
+    ```
+
+    you can change the `name`, `version`, and other fields as you like.
+
+### Reader interface
+
+For a custom `Reader`, a C++ part and a Python part are both required.
+
+For C++ part, the constructor must inherit from `IElementReader`, and these methods must be implemented:
+- `void read(BinaryBuffer& buffer)`: Read data from the binary buffer.
+- `py::object data() const`: Return the data as a Python object. You can return anything defined in `pybind11`, such as `py::tuple`, `py::list`, `py::array_t`, etc.
+
+For Python part, the class must inherit from `uproot_custom.BaseReader` and implement the following class methods:
+
+- `gen_tree_config`: Generate a configuration dictionary for the reader based on the information tree. It should return a dictionary if you want your reader to be used, otherwise return `None`.
+- `get_cpp_reader`: Identify the tree configuration and return the C++ reader instance if it matches, otherwise return `None`.
+- `reconstruct_array`: Reconstruct the raw data to an `awkward` array according to the tree configuration.
+
+### Implement the C++ reader
+
+1. Create a `cpp` directory in the root directory of your project, and create a `my_reader.cc` file in it.
+
+2. In `my_reader.cc`, include the necessary headers and implement your reader class. For example:
+
+    ```cpp
+    #include "uproot-custom/uproot-custom.hh"
+    using namespace uproot;
+
+    class MyReader : public IElementReader {
+        public:
+            // Must at least receive a name
+            MyReader( std::string name )
+                : IElementReader(name), m_data( std::make_shared<std::vector<int>>() ) {}
+
+            // Implement these methods
+            void read( BinaryBuffer& buffer ) {
+                // Read data from the buffer
+                // Implement your reading logic here
+            }
+
+            py::object data() const {
+                // Return the data as a Python object
+                return make_array( m_data );
+            }
+
+        private:
+            const std::string m_name;
+            std::shared_ptr<std::vector<int>> m_data; // Example data member
+    };
+    ```
+
+    then declare the C++ module in the same file:
+
+    ```cpp
+    PYBIND11_MODULE( my_reader_cpp, m ) {
+        register_reader<MyReader>(m, "MyReader");
+    }
+    ```
+
+    if the constructor requires more parameters, register it with the constructor signature (except the name):
+
+    ```cpp
+    // Constructor signature:
+    MyReader( std::string name, bool param1, std::vector<IElementReader> sub_readers )
+
+    // Register the reader with the constructor signature:
+    PYBIND11_MODULE( my_reader_cpp, m ) {
+        register_reader<MyReader, bool, std::vector<IElementReader>>(m, "MyReader");
+    }
+    ```
+
+> [!IMPORTANT]
+> Use `std::shared_ptr` for data members in your reader class, as `uproot-custom` will manage the memory of the data members. This is important to avoid memory leaks and ensure proper cleanup.
+
+3. Create a `CMakeLists.txt` file in `cpp` directory:
+
+    ```cmake
+    cmake_minimum_required(VERSION 3.20)
+
+    if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.27)
+        cmake_policy(SET CMP0148 NEW)
+    endif()
+
+    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+    set(CMAKE_CXX_STANDARD 20)
+
+    project(${SKBUILD_PROJECT_NAME}
+        VERSION ${SKBUILD_PROJECT_VERSION}
+        LANGUAGES CXX
+    )
+        
+    set(PYBIND11_NEWPYTHON ON)
+    find_package(pybind11 REQUIRED)
+    find_package(uproot-custom REQUIRED)
+
+    pybind11_add_module(my_reader_cpp
+        my_reader.cc
+        # Add other source files here if needed
+    )
+
+    target_link_libraries(my_reader_cpp PRIVATE uproot-custom)
+
+    if(DEFINED SKBUILD_PROJECT_NAME)
+        install(
+            TARGETS my_reader_cpp
+            LIBRARY DESTINATION ${SKBUILD_PROJECT_NAME}
+        )
+    endif()
+    ```
+
+### Implement the Python reader
+
+1. Create a `my_reader` directory in the root directory of your project, and create a `__init__.py` file in it.
+
+2. In `__init__.py`, import the C++ module and implement your Python reader class:
+
+    ```python
+    from . import my_reader_cpp as _cpp
+    from uproot_custom import BaseReader
+
+
+    class MyReader(BaseReader):
+        @classmethod
+        def gen_tree_config(
+            cls,
+            top_type_name: str,
+            cls_streamer_info: dict,
+            all_streamer_info: dict,
+            item_path: str = "",
+        ) -> dict | None:
+            """
+            Identify the node in the information tree,
+            return the configuration dictionary if the node is matched,
+            otherwise return None.
+            """
+
+        @classmethod
+        def get_cpp_reader(cls, tree_config) -> _cpp.MyReader | None:
+            """
+            Identify the tree_config,
+            if it is matched, return the C++ reader instance,
+            otherwise return None.
+            """
+
+        @classmethod
+        def reconstruct_array(cls, raw_data, tree_config):
+            """
+            Reconstruct the raw data to an `awkward` array according to the tree_config.
+            """
+    ```
+
+    > ![NOTE]
+    > The `@classmethod` is not necesarry, but when a regular member method is used, you should pass the instance of the class to `registered_readers`.
+
+### Register the reader
+
+#### Register branch path
+
+The default interpretation `uproot_custom.AsCustom` needs to know which branch to read with custom readers. You can export the branch path with:
+
+```python
+import uproot
+from uproot_custom import regularize_object_path
+
+f = uproot.open("my_file.root")
+branch = f["path/to/my_branch"]
+
+print(regularize_object_path(branch.object_path))
+```
+
+This will print the regularized object path like `/my_tree:my_branch`. Then you can add it to the `AsCustom.target_branches` set:
+
+```python
+from uproot_custom import AsCustom
+
+AsCustom.target_branches.add("your-branch-path")
+```
+
+#### Register the reader
+
+To let `uproot_custom.AsCustom` know your reader, you need to register it:
+
+```python
+from uproot_custom import registered_readers
+from my_reader import MyReader
+
+registered_readers.add(MyReader)
+```
+
+Then you can use `uproot` to read the custom class as usual.
+
+> [!TIP]
+> It is recommended to do the registration in your project `__init__.py`, so that you can use your custom reader as long as you import your project.