Thread: [Sqlalchemy-commits] [1990] sqlalchemy/trunk/doc/build/content: doc tweaks
Brought to you by:
zzzeek
From: <co...@sq...> - 2006-10-15 22:42:12
|
<!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>[1990] sqlalchemy/trunk/doc/build/content: doc tweaks</title> </head> <body> <div id="msg"> <dl> <dt>Revision</dt> <dd>1990</dd> <dt>Author</dt> <dd>zzzeek</dd> <dt>Date</dt> <dd>2006-10-15 18:40:33 -0500 (Sun, 15 Oct 2006)</dd> </dl> <h3>Log Message</h3> <pre>doc tweaks</pre> <h3>Modified Paths</h3> <ul> <li><a href="#sqlalchemytrunkdocbuildcontentdbenginetxt">sqlalchemy/trunk/doc/build/content/dbengine.txt</a></li> <li><a href="#sqlalchemytrunklibsqlalchemyormmapperpy">sqlalchemy/trunk/lib/sqlalchemy/orm/mapper.py</a></li> </ul> </div> <div id="patch"> <h3>Diff</h3> <a id="sqlalchemytrunkdocbuildcontentdbenginetxt"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/content/dbengine.txt (1989 => 1990)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/content/dbengine.txt 2006-10-15 23:10:37 UTC (rev 1989) +++ sqlalchemy/trunk/doc/build/content/dbengine.txt 2006-10-15 23:40:33 UTC (rev 1990) </span><span class="lines">@@ -4,7 +4,7 @@ </span><span class="cx"> A database engine is a subclass of `sqlalchemy.sql.Engine`, and is the starting point for where SQLAlchemy provides a layer of abstraction on top of the various DBAPI2 database modules. For all databases supported by SA, there is a specific "implementation" module, found in the `sqlalchemy.databases` package, that provides all the objects an `Engine` needs in order to perform its job. A typical user of SQLAlchemy never needs to deal with these modules directly. For many purposes, the only knowledge that's needed is how to create an Engine for a particular connection URL. When dealing with direct execution of SQL statements, one would also be aware of Result, Connection, and Transaction objects. The primary public facing objects are: </span><span class="cx"> </span><span class="cx"> * **URL** - represents the identifier for a particular database. URL objects are usually created automatically based on a given connect string passed to the `create_engine()` function. </span><del>-* **Engine** - Combines a connection-providing resource with implementation-provided objects that know how to generate, execute, and gather information about SQL statements. It also provides the primary interface by which Connections are obtained, as well as a context for constructed SQL objects and schema constructs to "implicitly execute" themselves, which is an optional feature of SA 0.2. The Engine object that is normally dealt with is an instance of `sqlalchemy.engine.base.ComposedSQLEngine`. </del><ins>+* **Engine** - Combines a connection-providing resource with implementation-provided objects that know how to generate, execute, and gather information about SQL statements. It also provides the primary interface by which Connections are obtained, as well as a context for constructed SQL objects and schema constructs to "implicitly execute" themselves, which is an optional feature of SQLAlchemy. The Engine object that is normally dealt with is an instance of `sqlalchemy.engine.base.ComposedSQLEngine`. </ins><span class="cx"> * **Connection** - represents a connection to the database. The underlying connection object returned by a DBAPI's connect() method is referenced internally by the Connection object. Connection provides methods that handle the execution of SQLAlchemy's own SQL constructs, as well as literal string-based statements. </span><span class="cx"> * **Transaction** - represents a transaction on a single Connection. Includes `begin()`, `commit()` and `rollback()` methods that support basic "nestable" behavior, meaning an outermost transaction is maintained against multiple nested calls to begin/commit. </span><span class="cx"> * **ResultProxy** - Represents the results of an execution, and is most analgous to the cursor object in DBAPI. It primarily allows iteration over result sets, but also provides an interface to information about inserts/updates/deletes, such as the count of rows affected, last inserted IDs, etc. </span><span class="lines">@@ -35,7 +35,7 @@ </span><span class="cx"> </span><span class="cx"> ### Establishing a Database Engine {@name=establishing} </span><span class="cx"> </span><del>-SQLAlchemy 0.2 indicates the source of an Engine strictly via [RFC-1738](http://rfc.net/rfc1738.html) style URLs, combined with optional keyword arguments to specify options for the Engine. The form of the URL is: </del><ins>+SQLAlchemy indicates the source of an Engine strictly via [RFC-1738](http://rfc.net/rfc1738.html) style URLs, combined with optional keyword arguments to specify options for the Engine. The form of the URL is: </ins><span class="cx"> </span><span class="cx"> $ driver://username:password@host:port/database </span><span class="cx"> </span><span class="lines">@@ -107,7 +107,7 @@ </span><span class="cx"> </span><span class="cx"> engine = create_engine('mysql://', pool=pool.QueuePool(getconn, pool_size=20, max_overflow=40)) </span><span class="cx"> </span><del>-* pool_size=5 : the number of connections to keep open inside the connection pool. This used with `QueuePool` as well as `SingletonThreadPool` as of 0.2.7. </del><ins>+* pool_size=5 : the number of connections to keep open inside the connection pool. This used with `QueuePool` as well as `SingletonThreadPool`. </ins><span class="cx"> * max_overflow=10 : the number of connections to allow in "overflow", that is connections that can be opened above and beyond the initial five. this is only used with `QueuePool`. </span><span class="cx"> * pool_timeout=30 : number of seconds to wait before giving up on getting a connection from the pool. This is only used with `QueuePool`. </span><span class="cx"> * pool_recycle=-1 : this setting causes the pool to recycle connections after the given number of seconds has passed. It defaults to -1, or no timeout. For example, setting to 3600 means connections will be recycled after one hour. Note that MySQL in particular will disconnect automatically if no activity is detected on a connection for eight hours (although this is configurable with the MySQLDB connection itself and the server configuration as well). </span><span class="lines">@@ -116,14 +116,14 @@ </span><span class="cx"> * module=None : used by database implementations which support multiple DBAPI modules, this is a reference to a DBAPI2 module to be used instead of the engine's default module. For Postgres, the default is psycopg2, or psycopg1 if 2 cannot be found. For Oracle, its cx_Oracle. </span><span class="cx"> * use_ansi=True : used only by Oracle; when False, the Oracle driver attempts to support a particular "quirk" of Oracle versions 8 and previous, that the LEFT OUTER JOIN SQL syntax is not supported, and the "Oracle join" syntax of using `&lt;column1&gt;(+)=&lt;column2&gt;` must be used in order to achieve a LEFT OUTER JOIN. </span><span class="cx"> * threaded=True : used by cx_Oracle; sets the `threaded` parameter of the connection indicating thread-safe usage. cx_Oracle docs indicate setting this flag to `False` will speed performance by 10-15%. While this defaults to `False` in cx_Oracle, SQLAlchemy defaults it to `True`, preferring stability over early optimization. </span><del>-* strategy='plain' : the Strategy argument is used to select alternate implementations of the underlying Engine object, which coordinates operations between dialects, compilers, connections, and so on. Currently, the only alternate strategy besides the default value of "plain" is the "threadlocal" strategy, which selects the usage of the `TLEngine` class that provides a modified connection scope for implicit executions. Implicit execution as well as further detail on this setting are described in [connections_context](rel:dbengine_implicit). </del><ins>+* strategy='plain' : the Strategy argument is used to select alternate implementations of the underlying Engine object, which coordinates operations between dialects, compilers, connections, and so on. Currently, the only alternate strategy besides the default value of "plain" is the "threadlocal" strategy, which selects the usage of the `TLEngine` class that provides a modified connection scope for implicit executions. Implicit execution as well as further detail on this setting are described in [dbengine_implicit](rel:dbengine_implicit). </ins><span class="cx"> * use_oids=False : used only by Postgres, will enable the column name "oid" as the object ID column, which is also used for the default sort order of tables. Postgres as of 8.1 has object IDs disabled by default. </span><span class="cx"> * convert_unicode=False : if set to True, all String/character based types will convert Unicode values to raw byte values going into the database, and all raw byte values to Python Unicode coming out in result sets. This is an engine-wide method to provide unicode across the board. For unicode conversion on a column-by-column level, use the `Unicode` column type instead. </span><span class="cx"> * encoding='utf-8' : the encoding to use for all Unicode translations, both by engine-wide unicode conversion as well as the `Unicode` type object. </span><span class="cx"> </span><span class="cx"> ### Using Connections {@name=connections} </span><span class="cx"> </span><del>-In this section we describe the SQL execution interface available from an `Engine` instance. Note that when using the Object Relational Mapper (ORM) as well as when dealing with with "bound" metadata objects, SQLAlchemy deals with the Engine for you and you generally don't need to know much about it; in those cases, you can skip this section and go to [metadata](rel:metadata). "Bound" metadata is described in [metadata_tables_binding](rel:metadata_tables_binding). </del><ins>+In this section we describe the SQL execution interface available from an `Engine` instance. Note that when using the Object Relational Mapper (ORM) as well as when dealing with with "bound" metadata objects, SQLAlchemy deals with the Engine and Connections for you and you generally don't need to know much about it; in those cases, you can skip this section and go to [metadata](rel:metadata). "Bound" metadata is described in [metadata_tables_binding](rel:metadata_tables_binding). </ins><span class="cx"> </span><span class="cx"> The Engine provides a `connect()` method which returns a `Connection` object. This object provides methods by which literal SQL text as well as SQL clause constructs can be compiled and executed. </span><span class="cx"> </span><span class="lines">@@ -223,6 +223,8 @@ </span><span class="cx"> print row['col1'], row['col2'] </span><span class="cx"> result.close() </span><span class="cx"> </span><ins>+Using "bound" metadata: + </ins><span class="cx"> {python title="Implicit Execution Using Engine-Bound SQL Construct"} </span><span class="cx"> engine = create_engine('sqlite:///:memory:') </span><span class="cx"> meta = BoundMetaData(engine) </span><span class="lines">@@ -296,7 +298,7 @@ </span><span class="cx"> conn1 = db.contextual_connection() </span><span class="cx"> conn2 = db.contextual_connection() </span><span class="cx"> </span><del>- >>> assert conn1.connection is conn2.connection </del><ins>+ >>> conn1.connection is conn2.connection </ins><span class="cx"> True </span><span class="cx"> </span><span class="cx"> When the `plain` strategy is used, the `contextual_connection()` method is synonymous with the `connect()` method; both return a distinct connection from the pool. </span></span></pre></div> <a id="sqlalchemytrunklibsqlalchemyormmapperpy"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/lib/sqlalchemy/orm/mapper.py (1989 => 1990)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/lib/sqlalchemy/orm/mapper.py 2006-10-15 23:10:37 UTC (rev 1989) +++ sqlalchemy/trunk/lib/sqlalchemy/orm/mapper.py 2006-10-15 23:40:33 UTC (rev 1990) </span><span class="lines">@@ -30,9 +30,9 @@ </span><span class="cx"> EXT_PASS = object() </span><span class="cx"> </span><span class="cx"> class Mapper(object): </span><del>- """Persists object instances to and from schema.Table objects via the sql package. - Instances of this class should be constructed through this package's mapper() or - relation() function.""" </del><ins>+ """Defines the correlation of class attributes to database table columns. + + Instances of this class should be constructed via the sqlalchemy.orm.mapper() function.""" </ins><span class="cx"> def __init__(self, </span><span class="cx"> class_, </span><span class="cx"> local_table, </span></span></pre> </div> </div> </body> </html> |