Add docs about integrating pure SQLAlchemy

[tiangolo]

Add section explaining how to write pure SQLAlchemy models that can be easily imported and used in non-Flask code, and how to integrate them with Flask-SQLAlchemy for Flask code, to be able to use the Flask-specific features, like scoped sessions.

With inspiration from @dmckeone comment on #98 and @gtalarico comment on #250

I developed and tried the code before writing the guide to make sure it "works". Also, it's actually a simplification of what I'm doing at this Flask project generator https://github.com/tiangolo/full-stack

I tried to keep it as concise as possible while still being understandable, practical and something that can be copy-pasted and tried without more modifications.

[davidism]

Just curious, is there a reason for the emoji placeholder in the title? I've seen a bunch of PRs in the last day with that pattern. Note that they don't work in the title, they just look weird.

[tiangolo]

Hehe, oops, sorry for the weird title. I didn't pay attention to it and left if like that from the commit message 😁

Using emoji in commit messages comes from this https://gitmoji.carloscuesta.me/ (as far as I know)

The idea is to specify what kind of action was done with a bit of cosmetic decoration. Nothing important, really. Just an attempt to look fancy... 😂

[rsyring]

Do we have tests that mirror these examples so they know they work?

Maybe better yet, is it possible to import test content into the docs so that we could actually embed the source of tests? That would ensure the examples we have in the docs always work.

[davidism]

You can look at Sphinx's doctest extension or Click's doc runner, but I don't think doctests are worth it right now.

[tiangolo]

@rsyring just as a note/comment, although I guess it probably doesn't apply here as the docs are generated differently.

---

I'm using MkDocs for FastAPI, I use https://github.com/cmacmackin/markdown-include to include source Python files in the docs, and most of the tests are actually run against those same Python files from the docs.

That does what you say, it ensures the sources in the docs work, and also it helps ensuring that the features are documented: if coverage is 100% and all (or most of) the tests are from docs, all (or most of) the features are documented.

The equivalent of this PR in FastAPI would be from this source file: https://github.com/tiangolo/fastapi/blob/master/docs/src/sql_databases/tutorial001.py

And the docs (that include it) are here: https://fastapi.tiangolo.com/tutorial/sql-databases/

[davidism]

I was reviewing this, and it seems like it's really just saying that you can call db.session.query() on any model, not just ones derived from db.Model. I guess that's useful information, but I don't think it really warrants a section this long. This seems to be more of a mini-tutorial on creating a base class with SQLAlchemy than doing anything specific with Flask-SQLAlchemy.

You don't even need to pass model_class=Model the only thing that does that's relevant to the given use case is adding a query property, but even then if you're using this outside Flask you're probably just doing session.query() instead already.

Going to close this, but I'm open to adding something about being able to pass any model to db.session.query() if someone finds a good place for it.