From ddaf28461b302ab6c66ee563a1a5c483eafaa396 Mon Sep 17 00:00:00 2001 From: Jonathan Ellis Date: Tue, 1 Aug 2006 18:43:28 +0000 Subject: [PATCH] expand explanation of Query methods --- lib/sqlalchemy/ext/sqlsoup.py | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/lib/sqlalchemy/ext/sqlsoup.py b/lib/sqlalchemy/ext/sqlsoup.py index 431939e2e9..15d23a7c6b 100644 --- a/lib/sqlalchemy/ext/sqlsoup.py +++ b/lib/sqlalchemy/ext/sqlsoup.py @@ -46,11 +46,23 @@ select by a key or other field: >>> db.users.selectone_by(name='Bhargan Basepair') MappedUsers(name='Bhargan Basepair',email='basepair@example.edu',password='basepair',classname=None,admin=1) -All the SqlAlchemy Query select variants (select, select_by, selectone, selectone_by, selectfirst, selectfirst_by) -are available. See the SqlAlchemy documentation for details: -http://www.sqlalchemy.org/docs/datamapping.myt#datamapping_query for general info and examples, -and http://www.sqlalchemy.org/docs/sqlconstruction.myt for details on construction WHERE clauses. +Select variants +--------------- + +All the SqlAlchemy Query select variants are available. +Here's a quick summary of these methods: + +- get(PK): load a single object identified by its primary key (either a scalar, or a tuple) +- select(Clause, **kwargs): perform a select restricted by the Clause argument; returns a list of objects. The most common clause argument takes the form "db.tablename.c.columname == value." The most common optional argument is order_by. +- select_by(**params): the *_by selects allow using bare column names. (columname=value)This feels more natural to most Python programmers; the downside is you can't specify order_by or other select options. +- selectfirst, selectfirst_by: returns only the first object found; equivalent to select(...)[0] or select_by(...)[0], except None is returned if no rows are selected. +- selectone, selectone_by: like selectfirst or selectfirst_by, but raises if less or more than one object is selected. +- count, count_by: returns an integer count of the rows selected. + +See the SqlAlchemy documentation for details: +- http://www.sqlalchemy.org/docs/datamapping.myt#datamapping_query for general info and examples, +- http://www.sqlalchemy.org/docs/sqlconstruction.myt for details on construction WHERE clauses. Modifying objects @@ -92,7 +104,7 @@ You can similarly update multiple rows at once. This will change the book_id to >>> db.loans.select_by(db.loans.c.book_id==1) [MappedLoans(book_id=1,user_name='Joe Student',loan_date=datetime.datetime(2006, 7, 12, 0, 0))] - + Joins ===== @@ -132,6 +144,15 @@ you would also see on a cursor. Joe Student student@example.edu You can also pass this engine object to other SQLAlchemy constructs. + + +Extra tests +=========== + +Boring tests here. Nothing of real expository value. + + >>> db.users.select(db.users.c.classname==None, order_by=[db.users.c.name]) + [MappedUsers(name='Bhargan Basepair',email='basepair+nospam@example.edu',password='basepair',classname=None,admin=1), MappedUsers(name='Joe Student',email='student@example.edu',password='student',classname=None,admin=0)] """ from sqlalchemy import * -- 2.47.2