Flask SQLAlchemy Integration - Documentation Suggestion

Firstly, thank you for the great extension!!

I've ran into an error that I'm sure others will have ran into, it may be worth updating the docs with a warning about it.

Our structure was as follows:

• Each model has it's own module
• Each model module also contains a Schema and Manager for example UserModel, UserSchema, UserManager all defined within /models/user.py

Some background - with SQLAlchemy, with separate models, you need to import them all at runtime, before the DB is initialised to avoid circular dependancies within relationships.

When the UserSchema(ma.ModelSchema) is hit during import from app.models import * (in bootstrap) this initialises the models and attempts to execute the relationships. At this stage, we may not have a relationship requirement (which SQLAlchemy avoids using string based relationships) however as the ma.ModelSchema initialises the models it creates errors such as this:

sqlalchemy.exc.InvalidRequestError: When initializing mapper mapped class User->users, expression ‘Team’ failed to locate a name (“name ‘Team’ is not defined”). If this is a class name, consider adding this relationship() to the <class ‘app.models.user.User’> class after both dependent classes have been defined.

and, on subsequent loads:

sqlalchemy.exc.InvalidRequestError: Table ‘users_teams’ is already defined for this MetaData instance. Specify ‘extend_existing=True’ to redefine options and columns on an existing Table object.

The solution to this is to simply build the UserSchemas in a different import namespace, we've now got:

/schemas/user_schema.py
/models/user.py

And no more circular issues - hopefully this helps someone else, went around in circles (pun intended) for a few hours before I realised it was the ModelSchema causing it.

Could the docs be updated to make a point of explaining that the ModelSchema initialises the model, and therefore it's a good idea for them to be in separate import destinations?

Locate the Flask-M marshmallow documentation covering ModelSchema and SQLAlchemy model setup, then read the surrounding integration guidance. Add a warning explaining the reported import-order and separate-schema-module issue, using the examples and error messages in this report; done when the documentation clearly describes the workaround.