that is, the whole rationale behind alembic was to avoid having to write out those big "Table" objects in almost all cases. The use case where the whole table is being added is less common. And, a central theme I'm trying to get across in the docs is that people don't need these full-blown heavyweight Table objects with every column just to do an UPDATE (though an INSERT, sure you need all the columns usually). in many ways folks are in the habit of spending too much time with Table formality either because they came from Migrate or they don't know enough of what's going on to know that an UPDATE statement only needs the columns that are actually rendered.
So if I were to revise these docs I'd try to break them up a little bit, into use cases: "Update statements", "inserting into new tables", then maybe info on "bulk updates" as we have the bulk_update() function. Within "Update statements" at least we'd need to put some info on how to deal with literal parameters, e.g. using inline_literal(), but that even might be becoming obsolete as we've been talking about turning on a relatively new feature in SQLAlchemy that will automatically inline-render bounds, which would mean the docs need to change in quite a few places.
also don't hate me but looking at the docs here, we might as well return the Table object that's generated from op.create_table() and probably change autogenerate to render:
I'm possibly concerned that the Table which autogenerate creates doesn't have any of the Python-side defaults set up, though these can be added to the create_table definition anyway...I guess it's fine.