[Sqlalchemy-commits] [1156] sqlalchemy/trunk/doc/build/content/tutorial.txt: making the verbiage a l
Brought to you by:
zzzeek
Menu
▾
▴
[Sqlalchemy-commits] [1156] sqlalchemy/trunk/doc/build/content/tutorial.txt: making the verbiage a little more formal...(its good stuff, just not sure what I want yet)
|
From: <co...@sq...> - 2006-03-17 06:11:47
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head><style type="text/css"><!-- #msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; } #msg dt { float: left; width: 6em; font-weight: bold; } #msg dt:after { content:':';} #msg dl, #msg dt, #msg ul, #msg li { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; } #msg dl a { font-weight: bold} #msg dl a:link { color:#fc3; } #msg dl a:active { color:#ff0; } #msg dl a:visited { color:#cc6; } h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; } #msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; } #msg ul, pre { overflow: auto; } #patch { width: 100%; } #patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;} #patch .propset h4, #patch .binary h4 {margin:0;} #patch pre {padding:0;line-height:1.2em;margin:0;} #patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;} #patch .propset .diff, #patch .binary .diff {padding:10px 0;} #patch span {display:block;padding:0 10px;} #patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;} #patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;} #patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;} #patch .lines, .info {color:#888;background:#fff;} --></style> <title>[1156] sqlalchemy/trunk/doc/build/content/tutorial.txt: making the verbiage a little more formal...(its good stuff, just not sure what I want yet)</title> </head> <body> <div id="msg"> <dl> <dt>Revision</dt> <dd>1156</dd> <dt>Author</dt> <dd>zzzeek</dd> <dt>Date</dt> <dd>2006-03-17 00:11:34 -0600 (Fri, 17 Mar 2006)</dd> </dl> <h3>Log Message</h3> <pre>making the verbiage a little more formal...(its good stuff, just not sure what I want yet)</pre> <h3>Modified Paths</h3> <ul> <li><a href="#sqlalchemytrunkdocbuildcontenttutorialtxt">sqlalchemy/trunk/doc/build/content/tutorial.txt</a></li> </ul> </div> <div id="patch"> <h3>Diff</h3> <a id="sqlalchemytrunkdocbuildcontenttutorialtxt"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/content/tutorial.txt (1155 => 1156)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/content/tutorial.txt 2006-03-17 02:51:08 UTC (rev 1155) +++ sqlalchemy/trunk/doc/build/content/tutorial.txt 2006-03-17 06:11:34 UTC (rev 1156) </span><span class="lines">@@ -1,10 +1,7 @@ </span><span class="cx"> Tutorial </span><span class="cx"> ======== </span><del>-This tutorial is a "quick start" guide to SQLAlchemy, the Python SQL Toolkit and Object Relational Mapper. -SQLAlchemy provides a lot of functionality to help manage SQL databases, but you don't need much in order to begin doing useful things with it. </del><ins>+This tutorial is a "quick start" guide to SQLAlchemy. You may wish to skip it and dive into the [main manual][manual] which is more reference-oriented. </ins><span class="cx"> </span><del>-Note that it is not neccessary to read this tutorial; you may wish to skip it and dive into the [main manual][manual] which is more reference-oriented. - </del><span class="cx"> [manual]: rel:howtoread </span><span class="cx"> </span><span class="cx"> Installation </span><span class="lines">@@ -12,7 +9,7 @@ </span><span class="cx"> </span><span class="cx"> ### Installing SQLAlchemy {@name=sqlalchemy} </span><span class="cx"> </span><del>-Installing SQLAlchemy is easy if you have [setuptools][] on your system (if you don't, [install it][install setuptools], it's easy!). Just run this from the command-line: </del><ins>+Installing SQLAlchemy from scratch is most easily achieved with [setuptools][]. ([setuptools installation][install setuptools]). Just run this from the command-line: </ins><span class="cx"> </span><span class="cx"> $ easy_install SQLAlchemy </span><span class="cx"> </span><span class="lines">@@ -24,25 +21,23 @@ </span><span class="cx"> </span><span class="cx"> ### Installing A Database Manager {@name=dbms} </span><span class="cx"> </span><del>- SQLAlchemy is designed to operate with the [DBAPI][DBAPI] built for a particular database, and includes implementations supporting the most popular ones. If you have one of the [supported database managers][supported dbms], you can proceed to the following section. Otherwise we recommend installing [SQLite][] for starters. SQLite needs very little configuration and is easy to work with. </del><ins>+ SQLAlchemy is designed to operate with a [DBAPI][DBAPI] implementation built for a particular database, and includes support for the most popular databases. If you have one of the [supported database managers][supported dbms], you can proceed to the following section. Otherwise [SQLite][] is an easy to use database to get started with, requiring very little configuration. </ins><span class="cx"> </span><span class="cx"> [DBAPI]: http://www.python.org/doc/peps/pep-0249/ </span><span class="cx"> </span><span class="cx"> To work with SQLite, you'll need: </span><span class="cx"> </span><del>- * SQLite library </del><span class="cx"> * [pysqlite][] - Python interface for SQLite </span><ins>+ * SQLite library </ins><span class="cx"> </span><del>-If you use Windows, you only have to download and install the compiled [pysqlite binary][pysqlite]. It includes the SQLite library already linked in, so you don't have to install it separately. </del><ins>+Note that the SQLite library download is not required with Windows, as the Windows Pysqlite library already includes it linked in. Pysqlite and SQLite can also be installed on Linux or FreeBSD via pre-made [packages][pysqlite packages] or [from sources][pysqlite]. </ins><span class="cx"> </span><del>-If you use Linux or FreeBSD, you may want to install pysqlite and SQLite from [packages][pysqlite packages] made for your operating system. Or you may install them [from sources][pysqlite]. - </del><span class="cx"> [supported dbms]: rel:dbengine_establishing </span><span class="cx"> [sqlite]: http://sqlite.org/ </span><span class="cx"> [pysqlite]: http://pysqlite.org/ </span><span class="cx"> [pysqlite packages]: http://initd.org/tracker/pysqlite/wiki/PysqlitePackages </span><span class="cx"> </span><del>-Get Going! {@name=getgoing} </del><ins>+Getting Started {@name=gettingstarted} </ins><span class="cx"> -------------------------- </span><span class="cx"> </span><span class="cx"> ### Connecting to the Database </span><span class="lines">@@ -52,11 +47,11 @@ </span><span class="cx"> >>> from sqlalchemy import * </span><span class="cx"> >>> db = create_engine('sqlite://filename=tutorial.db') </span><span class="cx"> </span><del>-Main documentation: [dbengine](rel:dbengine). </del><ins>+Documentation on creating engines is available in [dbengine](rel:dbengine). </ins><span class="cx"> </span><span class="cx"> ### Creating a Table {@name=table} </span><span class="cx"> </span><del>-A core philosophy of SQLAlchemy is that tables and domain classes are different beasts. That's why SQLAlchemy doesn't mix them. So let's first work with just tables alone; we construct an object that represents a table: </del><ins>+A core philosophy of SQLAlchemy is that tables and domain classes are different beasts. For this reason, SQLAlchemy provides constructs that represent tables by themselves (known as *table metadata*). So we will begin by constructing table metadata objects and performing SQL operations with them directly, keeping in mind that there is also an Object Relational Mapper (ORM) which does the same thing except via domain models. Let's construct an object that represents a table: </ins><span class="cx"> </span><span class="cx"> >>> users = Table('users', db, </span><span class="cx"> ... Column('user_id', Integer, primary_key = True), </span><span class="lines">@@ -64,7 +59,7 @@ </span><span class="cx"> ... Column('password', String(80)) </span><span class="cx"> ... ) </span><span class="cx"> </span><del>-As you might have guessed, we have just defined a table `users` with 3 columns: `user_id` (which is a primary key column), `user_name` and `password`. Currently it is just an object that may not correspond to an existing table in your database. So let's create the real table! To make it interesting we will ask SQLAlchemy to echo the SQL statements it sends to the database: </del><ins>+As you might have guessed, we have just defined a table named `users` which has three columns: `user_id` (which is a primary key column), `user_name` and `password`. Currently it is just an object that may not correspond to an existing table in your database. To actually create the table, we use the `create()` method. To make it interesting we will have SQLAlchemy to echo the SQL statements it sends to the database: </ins><span class="cx"> </span><span class="cx"> >>> db.echo = True </span><span class="cx"> >>> users.create() # doctest:+ELLIPSIS,+NORMALIZE_WHITESPACE </span><span class="lines">@@ -82,11 +77,11 @@ </span><span class="cx"> >>> list(users.columns)[0].name </span><span class="cx"> 'user_id' </span><span class="cx"> </span><del>-Main documentation: [metadata](rel:metadata). </del><ins>+Documentation on table metadata is available in [metadata](rel:metadata). </ins><span class="cx"> </span><del>-### Filling the Table </del><ins>+### Inserting Rows </ins><span class="cx"> </span><del>-So now we have the table. To insert some data, use the `insert()` method to create a query: </del><ins>+Inserting is achieved via the `insert()` method, which defines a *clause object* representing an INSERT statement: </ins><span class="cx"> </span><span class="cx"> >>> i = users.insert() </span><span class="cx"> >>> i # doctest:+ELLIPSIS </span><span class="lines">@@ -94,7 +89,7 @@ </span><span class="cx"> >>> print i </span><span class="cx"> INSERT INTO users (user_id, user_name, password) VALUES (?, ?, ?) </span><span class="cx"> </span><del>-Call the `execute()` method of the query object to actually add users: </del><ins>+The `execute()` method of the clause object executes the statement at the database level: </ins><span class="cx"> </span><span class="cx"> >>> for name in ['Tom', 'Dick', 'Harry']: # doctest:+ELLIPSIS </span><span class="cx"> ... i.execute(user_name = name) </span><span class="lines">@@ -103,15 +98,15 @@ </span><span class="cx"> >>> i.execute(user_name = 'Mary', password = 'secure') # doctest:+ELLIPSIS </span><span class="cx"> <sqlalchemy.engine.ResultProxy instance at 0x...> </span><span class="cx"> </span><del>-SQLAlchemy will bind all literal values into bind parameters, according to the paramstyle of the underlying DBAPI. This allows for better performance, because the database may cache a compiled representation of the statement and reuse upon new executions, substituting the new values. Also, when using bound values, you need not worry about [SQL injection][] attacks. </del><ins>+When constructing clause objects, SQLAlchemy will bind all literal values into bind parameters, according to the paramstyle of the underlying DBAPI. This allows for better performance, as the database may cache a compiled representation of the statement and reuse it for new executions, substituting the new values. Also, when using bound values, you need not worry about [SQL injection][] attacks. </ins><span class="cx"> </span><span class="cx"> [SQL injection]: http://en.wikipedia.org/wiki/SQL_injection </span><span class="cx"> </span><del>-Main documentation: [sql_insert](rel:sql_insert). </del><ins>+Documentation on inserting: [sql_insert](rel:sql_insert). </ins><span class="cx"> </span><del>-### Querying the Table </del><ins>+### Constructing Queries </ins><span class="cx"> </span><del>-Let's check that the data we have put into `users` table is actually there. The procedure is analogous to the insert example above, except you now call the `select()` function: </del><ins>+Let's check that the data we have put into `users` table is actually there. The procedure is analogous to the insert example above, except you now call the `select()` method off the `users` table: </ins><span class="cx"> </span><span class="cx"> >>> s = users.select() </span><span class="cx"> >>> print s </span><span class="lines">@@ -131,7 +126,7 @@ </span><span class="cx"> >>> r.fetchall() </span><span class="cx"> [(2, u'Dick', None), (3, u'Harry', None), (4, u'Mary', u'secure')] </span><span class="cx"> </span><del>-Main documentation: [sql_select](rel:sql_select). </del><ins>+Documentation on selecting: [sql_select](rel:sql_select). </ins><span class="cx"> </span><span class="cx"> ### Related Table </span><span class="cx"> </span></span></pre> </div> </div> </body> </html> |
