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. ;-)
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.
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/)
I don't know why but it's just way more intuitive this way for me at least, thanks!
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.
>>> 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
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)
it's breaking zen of python, it makes searching examples on Google very hard ( esp with Google getting really crappy)
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.
Choose a form that works for you and looks nice, apply it to all your oddest use cases like many to many relationships and self-referential relationships, and then use that as a template going forward.
Instead, use either an ORM, or even better the SQLALchemy core, to manage and abstract out the database; and use something like dataclasses, attrs or Pydantic to define your business logic models. In a network-oriented application, i.e. an API, I would recommend to use a separate tool to model the I/O entities, again unless they correspond very closely to the business ones.
Then you have some layer that stores things in the database. It’s like a record keeper. It uses an ORM or not.
One benefit of this is ORMs are giant, complex objects by necessity. It’s good to only use them where they’re needed, at the database. Then you don’t have all their magic floating through your business code. They’re also rather opinionated. I, at least, experience whay more freedom when making a class from scratch than using an ORM.
This comes at a cost of maintaining two versions of lots of things and a translation layer in between. It is overkill for super CRUDy stuff (most apps).
this is the quickstart:
https://docs.sqlalchemy.org/en/20/orm/quickstart.html
that's the one you use. That's it! There is no other style listed there
lots of people still want to use other styles or still have to because they have legacy code. So these are documented also. However, SQLAlchemy wants you to use the style at:
https://docs.sqlalchemy.org/en/20/orm/quickstart.html
that's the only style we would have if we were starting now.
The second example is a Core table. The new tutorial makes it clear that this is an underlying element that nonetheless you have to sometimes create directly.
the third example is gone. That style is not in the docs anymore *except* in a clearly marked side-box that is talking about a legacy version of SQLAlhcemy - you don't have to read that and the box IMO makes it as clear as it can that this is not the current way of doing things.
> Why so many styles? Why can't be like pydantic or Django and use just one style for ORM?
pydantic is extremely new and SQLAlchemy's declarative style pre-dates Python 3 entirely. So we have changed it. The old ways of doing things have to be maintained for backwards compatibility with millions of existing applications. You can't be around for 16 years and have exactly one way of doing things that never changes, legacy patterns for large software libraries are a fact of life.
as for django I dont know what they are doing, I am sure things had to change for them to accommodate pep-484 typing in models (if they have even done that).
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/
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(...)`?
First off, SQLAlchemy's docs are pretty easy to get to, for a direct link just go to:
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
- the Unified Tutorial, which is a dive into basically every important concept across Core / ORM : 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
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.