5 ms·
I would urge people who have had issues with the documentation to give the 2.0 documentation a try. Many aspects of it have been completely rewritten, both to
by zzzeek 4y ago
I would urge people who have had issues with the documentation to give the 2.0 documentation a try. Many aspects of it have been completely rewritten, both to correctly describe things in terms of the new APIs as well as to modernize a lot of old documentation that was written many years ago.
First off, SQLAlchemy's docs are pretty easy to get to, for a direct link just go to:
https://docs.sqlalchemy.org/ https://docs.sqlalchemy.org/
It's an esoteric URL I know! ;)
from there, docs that are new include:
- the Quickstart, so one can see in one quick page what SQLAlchemy usually looks like: https://docs.sqlalchemy.org/en/20/orm/quickstart.html https://docs.sqlalchemy.org/en/20/orm/quickstart.html
- the Unified Tutorial, which is a dive into basically every important concept across Core / ORM : https://docs.sqlalchemy.org/en/20/tutorial/index.html https://docs.sqlalchemy.org/en/20/tutorial/index.html
- the ORM Querying guide, which is a "how to" for a full range of SQL generation: https://docs.sqlalchemy.org/en/20/orm/queryguide/index.html https://docs.sqlalchemy.org/en/20/orm/queryguide/index.html
it's still a lot to read of course but part of the idea of SQLAlchemy 2.0 was to create a straighter and more consistent narrative, while it continues to take on a very broad-based problem space. If you compare the docs to those of like, PostgreSQL or MySQL, those docs have a lot of sections and text too (vastly more). It's a big library.
- mixmastamyk 4y agoGreat tool. I think this is why folks have trouble finding the docs: Whole entire site is docs everywhere, including home page. Links to "docs" are tiny on the home page. Main menu calls them "library" instead of docs, why? Majority of the stuff is focused on migration rather than new users. These two should be separated into separate tracks immediately. There is an attempt, but it gets lost somehow. Also the release page linked here and "what's new in 2.0" go straight into the deep end, "inside baseball" style. These kind of pages should be very light. Tons of history-I'm personally not interested when trying to get something done. Unsolicited advice, move that into another blog post. ;-)
- zzzeek 4y agoThe link I posted here is the blog post. That's why it's historical and chatty, it's the blog post.
- inquirer39243 4y agoLove your tools! I think you should consider changing "library" to "documentation" - for whatever reason I also struggled to discover "library" actually meant docs - but only after I also clicked on a specific version. I think the best UI/UX for this is something like django's [0], where "documentation" brings you straight to the latest version's documentation. [0] https://www.djangoproject.com/ https://www.djangoproject.com/
- zzzeek 4y ago> I think you should consider changing "library" to "documentation" - for whatever reason I also struggled to discover "library" actually meant docs - but only after I also clicked on a specific version. you got it, look now > I think the best UI/UX for this is something like django's [0], where "documentation" brings you straight to the latest version's documentation. the design of our main docs index page was taken completely from how Django does it (e.g. how they have "paragraphs of links" at https://docs.djangoproject.com/en/4.1/ https://docs.djangoproject.com/en/4.1/)
- inquirer39243 4y agoOh yeah I love it! I don't know why but it's just way more intuitive this way for me at least, thanks!
- zzzeek 4y ago> Whole entire site is docs everywhere, including home page. Links to "docs" are tiny on the home page. you got it, look now. If you can't find the docs now, I dont know what to say. > Main menu calls them "library" instead of docs, why? A library is where you'd go to learn...but I guess, because the product is a "library", that's why it's not obvious? The term is gone from the nav etc. the sub-page is still called "library" but nobody needs to go there.
- mmerickel 4y agoSQLAlchemy and your efforts are so amazing and appreciated. Thank you and the team for all of your hard work on 2.0 as well as the heroic effort that was put into 1.4 as a stepping stone for existing codebases!
- Dowwie 4y agoHey Mike! :) Hope all is well.
- westurner 4y agoPandas had a docs sprint awhile back. Are the DOCs issues labeled?
- v3ss0n 4y agoSo confused after reading unified tutorial. It's so confusing and too many styles to declare ORM >>> class User(Base): ... __tablename__ = "user_account" ... ... id: Mapped[int] = mapped_column(primary_key=True) ... name: Mapped[str] = mapped_column(String(30)) ... fullname: Mapped[Optional[str]] ... ... addresses: Mapped[List["Address"]] = relationship(back_populates="user") ... ... def __repr__(self) -> str: ... return f"User(id={self.id!r}, name={self.name!r}, VS class User(Base): __tablename__ = "user_account" id = mapped_column(Integer, primary_key=True) name = mapped_column(String(30), nullable=False) fullname = mapped_column(String) addresses = relationship("Address", back_populates="user") # ... definition continues Vs user_table = Table( "user", mapper_registry.metadata, Column("id", Integer, primary_key=True), Column("name", String(50)), Column("fullname", String(50)), Column("nickname", String(12)), ) Vs class Customers(Base): __tablename__ = 'customers' id = Column(Integer, primary_key = True) name = Column(String) address = Column(String) email = Column(String) Why so many styles? Why can't be like pydantic or Django and use just one style for ORM? it's breaking zen of python, it makes searching examples on Google very hard ( esp with Google getting really crappy)
- dragonwriter 4y ago> Why can't be like pydantic Pydantic also has multiple styles, in fact, I think it has more styles than SQLAlchemy. > and use just one style for ORM? To be fair, one of the “styles” you show is not ORM, its the lower-level Core which can be used without the ORM and which the ORM is built on top of. And the two ORM styles include an older one largely for backward compatibility and a more modern one.
- deleted 4y ago[deleted]
- v3ss0n 4y agoThen one really simple question: what to use ?
- 4y ago
- elephantum 4y agoJust want to thank you for all the work you do! We are heavy users of sqlalchemy, our life would be much harder without it!
- zzzeek 4y agoyoure welcome, glad it is of help
- robertlagrant 4y agoThis has been a long time coming. Many congratulations.
- thisismyswamp 4y agoAs a first time reader of these docs, they don't seem at all approachable. For example: for the quickstart, the premise is simple - show me quickly how I can create a class, map it to the database, create some examples, and delete them. Something like what mongoose does here: https://mongoosejs.com/docs/ https://mongoosejs.com/docs/ Instead, SQLAlchemy goes from how to declare models (with a wall of code followed by a wall of text), jumps into creating "engines", shows some generated SQL code for creating tables, and so on. Sessions are simply used without being introduced, and many questions arise - am I hoarding a database connection as long as I am holding onto the session? Why should I do anything other than executing queries while that is happening? Then that means the `with` expression is useless, unless I want to explicitly run a multiple-query transaction - but why should this be the default? It also comes across as clunky to be importing a `select` statement at the top level. Why not call select on the table objects themselves? And what's up with `select(...).select_from(...)`?