Gotchas

Don’t use this library

Seriously, don’t.

  • It straight up lies to you.

  • It messes with your __dict__.

  • Every attribute access goes through a slow, convoluted __getattr__ hook.

  • The error messages are patchy at best.

  • Have you even looked at the code?

This was a proof of concept for a prototype. Don’t invite the cat in. If you insist on it, you will be bitten.

Using cattrs? You need a hook factory

If you’re using cattrs to un/structure xattree classes, you must tell cattrs to use xattree’s own asdict function. Simple as:

converter.register_unstructure_hook_factory(
    xattree.has,
    lambda _: xattree.asdict
)

By default, it will use attrs.asdict, which doesn’t know that xattree-managed fields (name, parent, etc) should not be included.

Static type checkers can’t see xattree-managed fields

Your average felid is aloof by constitution — similarly, this library keeps to itself, though it will not prevent you from exposing your (classes’) guts in public if you so choose.

Since xattree-managed fields are attached via field_transformer, they are not visible to static type checkers. Static checkers don’t run your code, they just look at it. This means you will not see fields like data (or whatever else you called your DataTree field), parent, etc in the initializer signature on hovering over your class, nor will you see an informative type hint on hovering over xattree-managed attributes. Intellisense will work properly on your own fields.

Despite the above, xattree updates your class’ __anotations__ with the xattree-managed field information, in case you need it at runtime.