Let user write custom interpretation to read their custom classes

[mrzimu]

Dear developers,

I'm working for BESIII experiment, and have successfully written a self-defined interpretation to transform BESIII custom classes to awkward array. In detail I wrote a c++ module that receives binary data, class names and streamer information, fills arrays and returns them back to python. An exmaple is https://mrzimu.github.io/pybes3/user-manual/bes3-data-reading/, and the implementation is in https://github.com/mrzimu/pybes3 (rough but usable).

During my work, I found

1. It seems there is no specific design in uproot allowing me to use my own interpretation
2. ROOT IO technical documentation may be out of date, and lack of details about streaming

I think this may be a solution for uproot to handle with custom classes -- letting users write their custom interpretations. I have an idea that, is it possible to:

1. prepare such interface in uproot
2. write some docs to guide users writing their own interpretation, or even prepare some parsers for base types, STL, ...
3. request ROOT for further IO documentation (not sure if it's necessary)

so that people (especially in large experiment) can read out custom classes via uproot?

Best regards.

[ianna]

Dear @mrzimu,

Thank you for reaching out and for sharing your work with the BESIII data and your custom interpretation for reading ROOT files into Awkward Arrays—this is very impressive! It's great to see this kind of integration work and the initiative you've taken to build your own C++ module to handle streaming and array conversion. Your example and repository are very helpful.

You've brought up excellent points:

1. Custom Interpretations in uproot: You're right that uproot does not currently provide a public-facing interface for fully custom class interpretations. Internally, uproot's model is modular enough that this is feasible, and your use case makes a strong argument for formalizing a plugin system or user-provided interpretation interface. We’d love to discuss further how such a design might look and whether it could live inside uproot or as an extension.
2. Documentation on ROOT IO Streaming: Yes, this is a well-known pain point. ROOT's streamer format is not fully documented and changes subtly between ROOT versions. Requesting more comprehensive and version-specific documentation from ROOT would be very helpful, and a joint effort from different experiments might give this more weight.
3. Improved Documentation & Tools for Users: Totally agree—it would be valuable to provide guidance on implementing interpretations for custom classes. The idea of generic tools for base types and STL containers is also worth exploring, as it would significantly lower the barrier for new users.

Would you be interested in contributing a small prototype or design proposal on what this interface might look like from the user’s side (e.g. hooks, APIs, registration patterns)? It could serve as a basis for further discussion and refinement.

Again, thank you for your work and for starting this important conversation!

Best regards,
Ianna

[mrzimu]

Hi @ianna

Thank you for recognizing my work! Of course I am interested in making the contribution.

I may write some design proposal, also some codes and commit a PR later.

Since this is my first time making contribution, I'm not quite clear the contribution procedures. Please inform me if you have any suggestions.

Best regards,
Mingrun.

[ianna]

Hi @mrzimu

We have a brief description on the project website. I realized, it may need some explanation. Please, have a look at https://github.com/scikit-hep/uproot5/pull/1425/files where I tried to put the detailed instructions. Please, let me know if something is missing, unclear or does not work. Thanks!

Kind regard,

Ianna

[mrzimu]

That would be helpful, thanks!