SQLAlchemy 2.0 Released • Hacker News Board

Re: SQLAlchemy 2.0 Released

#81

Post by abenga » Mon, Jan 30, 2023, 7:12 AM UTC

throwme_123 wrote: post #17

trevor-e wrote: post #6

Sorry for detracting from the release news but SQLAlchemy has to have the least helpful website of any major library I can think of. I'm trying to find basic 101 code examples and it's just one wall of text after another. I found how to cite SQLAlchemy in a research paper and have yet to find a single code example.

When I see such a poor website, I also expect the codebase to be clunky and cluttered. Better alternative: - https://pugsql.org/

Yeah, no. A programming library using half my viewport for an empty banner with a logo and a menu shows they are not to be taken seriously. Like at all.

Re: SQLAlchemy 2.0 Released

#82

Post by thisismyswamp » Mon, Jan 30, 2023, 12:14 PM UTC

zzzeek wrote: post #19

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/ It's an eso…

As 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/

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(...)`?

Re: SQLAlchemy 2.0 Released

#83

Post by thisismyswamp » Mon, Jan 30, 2023, 12:20 PM UTC

v3ss0n wrote: post #34

For a decade I avoided sqlalchemy, we finally got to use it last year and found it quite overwhelmingly complex and 1.4 documentation is messy. We had to use mixed styles. I checked unified doc and it had improved but , still wall of texts.. quite hard to read. Readability count's.

Absolutely agree, coming from the Node.js world documentation for Python packages (especially more established ones) is largely unapproachable, wording is unnecessarily obtuse and descriptions go on for too long. Code is presented in walls instead of being elegantly interspersed with short descriptions.

Re: SQLAlchemy 2.0 Released

#84

Post by thisismyswamp » Mon, Jan 30, 2023, 12:24 PM UTC

It doesn't matter how good a library is, if care is not taken to make the documentation clean, accessible, elegant, concise, its legs are cut off from the start.

Documentation authors should get out of their own heads while writing, and try as hard as possible to attain the perspective of a complete newcomer who will have no idea why a library needed to be split into Core and ORM in the first place.