What's the purpose of needing `allow_inheritance` for EmbeddedDocument ?

[m-vdb]

class BaseTransformationEmbedded(EmbeddedDocument):
    pass

I have this error if I don't put allow_inheritance to True in meta dict:

ValueError: Document BaseTransformationEmbedded may not be subclassed

[rozza]

Cant think of one off the top of my head - probably just an artefact of inheritance.

[noirbizarre]

This behavior is expected and very useful as it allows dynamic cast on load.

When allow_inheritance=True, the _cls attribute is serialized allowing dynamic casting.

When allow_inheritance=False, the default, you can't add attribute and you can't inherit because there is no way to determine which class to instanciate on load.

I don't think this only line is raising an error. I think you have something like that:

class BaseTransformationEmbedded(EmbeddedDocument):
    pass

class SomethingElse(BaseTransformationEmbedded):
   pass

This is the second one which raises an exception, which is the expected behavior.

Here, you have 3 options:

• BaseTransformationEmbedded is meant to be inherited and bring some common fields and behaviors, you need inheritance and you need meta.allow_inheritance=True
• BaseTransformationEmbedded doesn't bring anything because it's just a basic embedded document: just remove this intermediate class and extend EmbeddedDocument.
• BaseTransformationEmbedded is meant to have some arbitrary and non deterministic attributes: use DynamicEmbeddedDocument instead.

But maybe I misunderstood.

After re-reading the inheritance documentation, only Document is exclicitely cited. Maybe the EmbeddedDocument should be too, even it the EmbeddedDocument documentation suggests that it has the same behavior.
On the other side EmbeddedDocument API Documentation is not consistent.

Maybe only a documentation update is needed.

[MRigal]

Nice dig @noirbizarre !

We recently added significant changes, also for the 0.9, that didn't came with the required documentation adjustments. There are quite a bit of these. If you feel like, any documentation PR is also worth a lot!

[noirbizarre]

Thanks !

I will submit a PR later on this.
I will try to see if there is other documentation fixes to be submitted.

[MRigal]

@noirbizarre ping for the doc PR. We aim to release 0.10 quite soon, it would be great if it could make into it ! :-)

[noirbizarre]

@MRigal OK, I will do it ASAP !

[wojcikstefan]

@noirbizarre have you had a chance to look into this one? :)