📝 Update docs to advise against using `from __future__ import annotations`

[aholten]

Hi all!

I've made this documentation PR after encountering issue 196. Many devs are accustomed to using the from __future__ import annotations import when working with forward references. Even though the docs page for type annotation strings explains how to work with forward reference type annotation strings with no mention of needing that import, myself an several others have perhaps by habit or assumption included the import and spent time scratching our heads at the mapping errors the import creates.

Python is close to making this future feature part of the language, but given that it is still up in the air, I think it's worth calling out how SQLModel interacts with this import in the interim.

Thanks!

[github-actions[bot]]

📝 Docs preview for commit 6f688f5e1952915533490f0ba296e53bae7fd946 at: https://40964f25.sqlmodel.pages.dev

[pawrequest]

YES!!! thankyou kind soul! i mean i already (eventually) found the issue, but its nice to see it going in the docs, itll save so many people so many headaches.

can we get a useful exception too? like FromFuturAnnotationsException('Thou shalt not hide typehints from sqlomodel') or something?

i dont know what this actually entails or if im upto it, but if someone can point me in a useful direction im happy to try....

[aholten]

@pawrequest Are you able to review this PR? It looks like tiangolo has this repo locked down as he is virtually the only contributor

[github-actions[bot]]

📝 Docs preview for commit 6525725eb8b29f106ebd827c56bd761f11782f10 at: https://306c077a.sqlmodel.pages.dev

[aholten]

hey @tiangolo, this PR addresses one of the oldest and most commented on SQLModel issues by documenting advice against a commonly used pattern that causes mappings to break. For those of us who've discussed the issue, it's taken a long time to debug or find the issue in Github with the solution. For anyone who didn't find the solution, they may conclude that SQLModel's SQLAlchemy mapping simply doesn't work, when in reality it just doesn't work with from __future__ import annotations. I believe it's worth a call out as such.

Hoping you can approve this docs PR, thank you!

[pawrequest]

@pawrequest Are you able to review this PR? It looks like tiangolo has this repo locked down as he is virtually the only contributor

done, but i have zero clout....

[aholten]

thank you!!

[PowerOfCreation]

I can only support this. I have just lost many hours as I tried adding SQLModel to an existing project which already used the future annotations and I got some really weird error messages that I couldn't figure out. The docs were not helpful at all nor was the error message good. I started stripping down the existing classes bit by bit and in a last ditch effort I tried removing the future annotation and that helped, I have searched in a lot of places but not this would be nice if this would be supported or at least mentioned in the docs

[pawrequest]

@tiangolo please? the docs at least, but realistically this needs a custom exception or some other runtime feedback if it's at all feasible. each new user is almost guaranteed to run into this issue, and it's so difficult to troubleshoot if you dont know what's happening. it ends up super-disheartening.