[Sqlalchemy-commits] [1147] sqlalchemy/trunk/doc/build: added txt2myt.py to the genhtml/runhtml scri
Brought to you by:
zzzeek
Menu
▾
▴
[Sqlalchemy-commits] [1147] sqlalchemy/trunk/doc/build: added txt2myt.py to the genhtml/runhtml scripts, added exception if required modules arent found.
|
From: <co...@sq...> - 2006-03-16 19:08:51
|
<!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>[1147] sqlalchemy/trunk/doc/build: added txt2myt.py to the genhtml/runhtml scripts, added exception if required modules arent found.</title> </head> <body> <div id="msg"> <dl> <dt>Revision</dt> <dd>1147</dd> <dt>Author</dt> <dd>zzzeek</dd> <dt>Date</dt> <dd>2006-03-16 13:08:35 -0600 (Thu, 16 Mar 2006)</dd> </dl> <h3>Log Message</h3> <pre>added txt2myt.py to the genhtml/runhtml scripts, added exception if required modules arent found. edited tutorial.txt, added particles, etc. added clue that firebird might be supported to dbengine.myt</pre> <h3>Modified Paths</h3> <ul> <li><a href="#sqlalchemytrunkdocbuildcontentdbenginemyt">sqlalchemy/trunk/doc/build/content/dbengine.myt</a></li> <li><a href="#sqlalchemytrunkdocbuildcontenttutorialtxt">sqlalchemy/trunk/doc/build/content/tutorial.txt</a></li> <li><a href="#sqlalchemytrunkdocbuildgenhtmlpy">sqlalchemy/trunk/doc/build/genhtml.py</a></li> <li><a href="#sqlalchemytrunkdocbuildrunhtmlpy">sqlalchemy/trunk/doc/build/runhtml.py</a></li> <li><a href="#sqlalchemytrunkdocbuildtxt2mytpy">sqlalchemy/trunk/doc/build/txt2myt.py</a></li> </ul> </div> <div id="patch"> <h3>Diff</h3> <a id="sqlalchemytrunkdocbuildcontentdbenginemyt"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/content/dbengine.myt (1146 => 1147)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/content/dbengine.myt 2006-03-16 17:48:51 UTC (rev 1146) +++ sqlalchemy/trunk/doc/build/content/dbengine.myt 2006-03-16 19:08:35 UTC (rev 1147) </span><span class="lines">@@ -11,7 +11,7 @@ </span><span class="cx"> </p> </span><span class="cx"> <&|doclib.myt:item, name="establishing", description="Establishing a Database Engine" &> </span><span class="cx"> <p> </span><del>- Engines exist for SQLite, Postgres, MySQL, and Oracle, using the Pysqlite, Psycopg (1 or 2), MySQLDB, and cx_Oracle modules. Each engine imports its corresponding module which is required to be installed. For Postgres and Oracle, an alternate module may be specified at construction time as well. </del><ins>+ Engines exist for SQLite, Postgres, MySQL, and Oracle, using the Pysqlite, Psycopg (1 or 2), MySQLDB, and cx_Oracle modules (there is also experimental support for Firebird). Each engine imports its corresponding module which is required to be installed. For Postgres and Oracle, an alternate module may be specified at construction time as well. </ins><span class="cx"> </p> </span><span class="cx"> <p>The string based argument names for connecting are translated to the appropriate names when the connection is made; argument names include "host" or "hostname" for database host, "database", "db", or "dbname" for the database name (also is dsn for Oracle), "user" or "username" for the user, and "password", "pw", or "passwd" for the password. SQLite expects "filename" or "file" for the filename, or if None it defaults to "":memory:".</p> </span><span class="cx"> <p>The connection arguments can be specified as a string + dictionary pair, or a single URL-encoded string, as follows:</p> </span></span></pre></div> <a id="sqlalchemytrunkdocbuildcontenttutorialtxt"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/content/tutorial.txt (1146 => 1147)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/content/tutorial.txt 2006-03-16 17:48:51 UTC (rev 1146) +++ sqlalchemy/trunk/doc/build/content/tutorial.txt 2006-03-16 19:08:35 UTC (rev 1147) </span><span class="lines">@@ -1,9 +1,9 @@ </span><span class="cx"> Tutorial </span><span class="cx"> ======== </span><del>-In this tutorial we will guide you to get started with SQLAlchemy, Python SQL toolkit and Object Relational Mapper. -SQLAlchemy provides a *lot* of functionality that will help you manage your SQL database. But very little is needed to know in order to begin doing useful things with it. </del><ins>+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. </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 [main manual][manual]. </del><ins>+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. </ins><span class="cx"> </span><span class="cx"> [manual]: rel:howtoread </span><span class="cx"> </span><span class="lines">@@ -22,16 +22,18 @@ </span><span class="cx"> [install setuptools]: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions </span><span class="cx"> [cheese]: http://cheeseshop.python.org/pypi </span><span class="cx"> </span><del>-### Installing Database Manager {@name=dbms} </del><ins>+### Installing A Database Manager {@name=dbms} </ins><span class="cx"> </span><del>-If you have one of the [supported database managers][supported dbms], you can proceed to the following section. Otherwise we recommend installing [SQLite][]. SQLite needs very little configuration and is easy to work with. </del><ins>+ 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. </ins><span class="cx"> </span><ins>+[DBAPI]: http://www.python.org/doc/peps/pep-0249/ + </ins><span class="cx"> To work with SQLite, you'll need: </span><span class="cx"> </span><span class="cx"> * SQLite library </span><span class="cx"> * [pysqlite][] - Python interface for SQLite </span><span class="cx"> </span><del>-If you use Windows, you only have to download and install compiled [pysqlite binary][pysqlite]. It includes SQLite library, so you don't have to install it separately. </del><ins>+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. </ins><span class="cx"> </span><span class="cx"> 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]. </span><span class="cx"> </span><span class="lines">@@ -43,18 +45,18 @@ </span><span class="cx"> Get Going! {@name=getgoing} </span><span class="cx"> -------------------------- </span><span class="cx"> </span><del>-### Connecting to Database </del><ins>+### Connecting to the Database </ins><span class="cx"> </span><del>-First of all you need to connect to database you want to work with: </del><ins>+First, you need to connect to the database you want to work with: </ins><span class="cx"> </span><span class="cx"> >>> from sqlalchemy import * </span><del>- >>> db = create_engine('sqlite', {'filename': 'tutorial.db'}) </del><ins>+ >>> db = create_engine('sqlite://filename=tutorial.db') </ins><span class="cx"> </span><span class="cx"> Main documentation: [dbengine](rel:dbengine). </span><span class="cx"> </span><span class="cx"> ### Creating a Table {@name=table} </span><span class="cx"> </span><del>-SQL tables and your domain classes are different beasts. That's why SQLAlchemy don't mix them. Let's construct an object that represents an SQL table: </del><ins>+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: </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">@@ -62,7 +64,7 @@ </span><span class="cx"> ... Column('password', String(80)) </span><span class="cx"> ... ) </span><span class="cx"> </span><del>-As you can guess we have just defined a table `users` with 3 columns: `user_id` (which is a primary key), `user_name` and `password`. Currently it is just an object that may not correspond to existing table in your database. So let's create the real table! To make it interesting we will ask SQLAlchemy to echo SQL statements it sends to database: </del><ins>+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: </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">@@ -74,7 +76,7 @@ </span><span class="cx"> ... </span><span class="cx"> >>> db.echo = False # you can skip this if you want to keep logging SQL statements </span><span class="cx"> </span><del>-Alternatively, `users` table could already exist (e.g. you're running examples from this introduction for the second time). In this case you can just skip `create()` method call. You can even skip defining `users` table in your code and ask SQLAlchemy to load its definition from the database: </del><ins>+Alternatively, the `users` table might already exist (such as, if you're running examples from this tutorial for the second time), in which case you can just skip the `create()` method call. You can even skip defining the individual columns in the `users` table and ask SQLAlchemy to load its definition from the database: </ins><span class="cx"> </span><span class="cx"> >>> users = Table('users', db, autoload = True) </span><span class="cx"> >>> list(users.columns)[0].name </span><span class="lines">@@ -84,7 +86,7 @@ </span><span class="cx"> </span><span class="cx"> ### Filling the Table </span><span class="cx"> </span><del>-Ok, we have the table. To insert some data into the table you have to prepare a query first. You can use `insert()` method to do it: </del><ins>+So now we have the table. To insert some data, use the `insert()` method to create a query: </ins><span class="cx"> </span><span class="cx"> >>> i = users.insert() </span><span class="cx"> >>> i # doctest:+ELLIPSIS </span><span class="lines">@@ -92,7 +94,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 `execute()` method of the prepared query to actually add users: </del><ins>+Call the `execute()` method of the query object to actually add users: </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">@@ -101,7 +103,7 @@ </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>-If possible, SQLAlchemy will bind values into a prepared query using native database API. This allows for better performance, because the database may cache compiled representation of the statement and reuse it between executions with different values. Also, when using bound values, you need not worry about [SQL injection][] attacks. </del><ins>+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. </ins><span class="cx"> </span><span class="cx"> [SQL injection]: http://en.wikipedia.org/wiki/SQL_injection </span><span class="cx"> </span><span class="lines">@@ -109,7 +111,7 @@ </span><span class="cx"> </span><span class="cx"> ### Querying the Table </span><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 insert example above. The difference is that you have to call `select()` method now: </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()` function: </ins><span class="cx"> </span><span class="cx"> >>> s = users.select() </span><span class="cx"> >>> print s </span><span class="lines">@@ -117,7 +119,7 @@ </span><span class="cx"> FROM users </span><span class="cx"> >>> r = s.execute() </span><span class="cx"> </span><del>-Now we won't ignore return value of `execute()`: </del><ins>+This time, we won't ignore the return value of `execute()`: </ins><span class="cx"> </span><span class="cx"> >>> r # doctest:+ELLIPSIS </span><span class="cx"> <sqlalchemy.engine.ResultProxy instance at 0x...> </span></span></pre></div> <a id="sqlalchemytrunkdocbuildgenhtmlpy"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/genhtml.py (1146 => 1147)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/genhtml.py 2006-03-16 17:48:51 UTC (rev 1146) +++ sqlalchemy/trunk/doc/build/genhtml.py 2006-03-16 19:08:35 UTC (rev 1147) </span><span class="lines">@@ -1,6 +1,9 @@ </span><span class="cx"> #!/usr/bin/env python </span><span class="cx"> import sys,re,os </span><span class="cx"> </span><ins>+print "Running txt2myt.py..." +execfile("txt2myt.py") + </ins><span class="cx"> component_root = [ </span><span class="cx"> {'components': './components'}, </span><span class="cx"> {'content' : './content'} </span></span></pre></div> <a id="sqlalchemytrunkdocbuildrunhtmlpy"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/runhtml.py (1146 => 1147)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/runhtml.py 2006-03-16 17:48:51 UTC (rev 1146) +++ sqlalchemy/trunk/doc/build/runhtml.py 2006-03-16 19:08:35 UTC (rev 1147) </span><span class="lines">@@ -1,6 +1,9 @@ </span><span class="cx"> #!/usr/bin/env python </span><span class="cx"> import sys,re,os </span><span class="cx"> </span><ins>+print "Running txt2myt.py..." +execfile("txt2myt.py") + </ins><span class="cx"> component_root = [ </span><span class="cx"> {'components': './components'}, </span><span class="cx"> {'content' : './content'} </span><span class="lines">@@ -23,4 +26,4 @@ </span><span class="cx"> </span><span class="cx"> ) </span><span class="cx"> </span><del>-httpd.serve_forever() </del><span class="cx">\ No newline at end of file </span><ins>+httpd.serve_forever() </ins></span></pre></div> <a id="sqlalchemytrunkdocbuildtxt2mytpy"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/txt2myt.py (1146 => 1147)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/txt2myt.py 2006-03-16 17:48:51 UTC (rev 1146) +++ sqlalchemy/trunk/doc/build/txt2myt.py 2006-03-16 19:08:35 UTC (rev 1147) </span><span class="lines">@@ -6,7 +6,10 @@ </span><span class="cx"> import string </span><span class="cx"> import re </span><span class="cx"> </span><del>-import elementtree.ElementTree as et </del><ins>+try: + import elementtree.ElementTree as et +except: + raise "This module requires ElementTree to run (http://effbot.org/zone/element-index.htm)" </ins><span class="cx"> </span><span class="cx"> sys.path.insert(0, './lib') </span><span class="cx"> import markdown </span></span></pre> </div> </div> </body> </html> |
