feat: Add custom interpretation API

[mrzimu]

This is an idea/design of making uproot able to read custom classes, also allowing users to customize the reading process in uproot.

A summary of the design is:

• Add a registration mechanism for user-defined custom interpretation.
• Add a pre-defined interpretation AsCustom, which
  • Introduces a new layer of interface Reader for converting custom classes to awkward arrays.
  • Defines a series of readers following standard ROOT streaming rules.
  • Allows users to register their own custom readers.

The full description is in dev/custom-interpretation/README.md.

Since I have limited understanding and experience on either ROOT streaming or interface design, it would be grateful if any suggestion or help is provided😄

[ianna]

Here is the link to the discussion: #1424

[mrzimu]

Hi, I think embedding the whole custom-class reading mechanism is too complicated and may make things a mess, so I created a standalone repository named uproot-custom for handling DIY custom class reading.

I removed the design docs of custom-class reading mechanism (so-call Readers), but I kept the custom interpretation registration interface.

Please let me know if anything I can help or improve, both for this MR and uproot-custom, thanks!

[mrzimu]

And I have no idea why the docs build failed....

[ariostas]

And I have no idea why the docs build failed....

pandas is an optional dependency, but you have pandas = uproot.extras.pandas() at the top level of custom.py, so it is crashing once it tries to load uproot. You can move that statement inside final_array, which is where it's actually needed.

Also, thanks for the updates! I'll look at this when I have some time. When you get a chance could you add a test so that we have a concrete usage example and we see if it actually works? Thanks!

[mrzimu]

Yes, I moved the import statement, and improved the test in test_1477_custom_interpretation.py. It just simply transforms the uint8 data to uint32 with big endian.

[ariostas]

This is looking really nice! I'll look a bit more into how you're using this with pybes3.

[ariostas]

I'll tag @nsmith- since he has more insight than me on how this should work and how this would involve rootfilespec.