From: Mike Bayer Date: Sat, 26 Nov 2005 01:07:06 +0000 (+0000) Subject: added page title via attributes to each document X-Git-Tag: rel_0_1_0~305 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e319b2a2880864814341b287bb04878b86465d78;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git added page title via attributes to each document --- diff --git a/doc/build/content/adv_datamapping.myt b/doc/build/content/adv_datamapping.myt index 146a56a36f..98aad5e767 100644 --- a/doc/build/content/adv_datamapping.myt +++ b/doc/build/content/adv_datamapping.myt @@ -1,4 +1,5 @@ <%flags>inherit='document_base.myt' +<%attr>title='Advanced Data Mapping' <&|doclib.myt:item, name="adv_datamapping", description="Advanced Data Mapping" &>

This section is under construction. For now, it has just the basic recipe for each concept without much else.

diff --git a/doc/build/content/coolthings.myt b/doc/build/content/coolthings.myt deleted file mode 100644 index f47cab8483..0000000000 --- a/doc/build/content/coolthings.myt +++ /dev/null @@ -1,101 +0,0 @@ -<%flags>inherit='document_base.myt' - - - -<&|doclib.myt:item, name="coolthings", description="Cool Things You Can Do With SQLAlchemy" &> - -<&|formatting.myt:code, syntaxtype="python" &> - # first, some imports - from sqlalchemy.sql import * - from sqlalchemy.schema import * - - - # make a database engine based on sqlite - import sqlalchemy.databases.sqlite as sqlite_db - db = sqlite_db.engine('foo.db', pool_size = 10, max_overflow = 5) - - # define metadata for a table - - users = Table('users', db, - Column('user_id', INT), - Column('user_name', VARCHAR(20)), - Column('password', CHAR(10)) - ) - - - # select rows from the table - - query = users.select() - cursor = query.execute() - rows = cursor.fetchall() - - - # select rows from the table where user_name=='ed' - rows = users.select(users.c.user_name == 'ed').execute().fetchall() - - # make a query with a bind param - query = select([users], users.c.user_id == bindparam('userid')) - - # execute with params - rows = query.execute(userid = 7).fetchall() - - - # make another table - addresses = Table('addresses', db, - Column('address_id', INT), - Column('user_id', INT), - Column('street', VARCHAR(20)), - Column('city', VARCHAR(20)), - Column('state', CHAR(2)), - Column('zip', CHAR(5)) - ) - - # no, really, make this table in the DB via CREATE - addresses.build() - - - # make a nonsensical query that selects from an outer join, and - # throws in a literally-defined EXISTS clause - query = select( - [users, addresses], - and_( - addresses.c.street == 'Green Street', - addresses.c.city == 'New York', - users.c.user_id != 12, - "EXISTS (select 1 from special_table where user_id=users.user_id)" - ), - from_obj = [ outerjoin(users, addresses, addresses.user_id==users.user_id) ] - ) - - - # insert into a table - users.insert().execute(user_id = 7, user_name = 'jack') - - # update the table - users.update(users.c.user_id == 7).execute(user_name = 'fred') - - - # get DBAPI connections from the higher-level engine - c = db.connection() - - - # use the connection pooling directly: - - # import a real DBAPI database - from pysqlite2 import dbapi2 as sqlite - - # make an implicit pool around it - import sqlalchemy.pool as pool - sqlite = pool.manage(sqlite, pool_size = 10, max_overflow = 5, use_threadlocal = True) - - # get a pooled connection local to the current thread - c = sqlite.connect('foo.db') - cursor = c.cursor() - - # return the connection to the pool - cursor = None - c = None - - - - diff --git a/doc/build/content/datamapping.myt b/doc/build/content/datamapping.myt index 0530b60d4d..9c8f631dcd 100644 --- a/doc/build/content/datamapping.myt +++ b/doc/build/content/datamapping.myt @@ -1,4 +1,6 @@ <%flags>inherit='document_base.myt' +<%attr>title='Data Mapping' + <&|doclib.myt:item, name="datamapping", description="Basic Data Mapping" &>

Data mapping describes the process of defining Mapper objects, which associate table metadata with user-defined classes. diff --git a/doc/build/content/dbengine.myt b/doc/build/content/dbengine.myt index 409dc48aea..d9385c05ed 100644 --- a/doc/build/content/dbengine.myt +++ b/doc/build/content/dbengine.myt @@ -1,4 +1,6 @@ <%flags>inherit='document_base.myt' +<%attr>title='Database Engines' + <&|doclib.myt:item, name="dbengine", description="Database Engines" &>

A database engine is a subclass of sqlalchemy.engine.SQLEngine, and is the starting point for where SQLAlchemy provides a layer of abstraction on top of the various DBAPI2 database modules. It serves as an abstract factory for database-specific implementation objects as well as a layer of abstraction over the most essential tasks of a database connection, including connecting, executing queries, returning result sets, and managing transactions.

diff --git a/doc/build/content/docstrings.myt b/doc/build/content/docstrings.myt index b52bd55168..b45c90f757 100644 --- a/doc/build/content/docstrings.myt +++ b/doc/build/content/docstrings.myt @@ -1,4 +1,5 @@ <%flags>inherit='document_base.myt' +<%attr>title='Modules and Classes' <&|doclib.myt:item, name="docstrings", description="Modules and Classes" &> <%init> import sqlalchemy.schema as schema diff --git a/doc/build/content/document_base.myt b/doc/build/content/document_base.myt index 65110d8b1e..39355c916d 100644 --- a/doc/build/content/document_base.myt +++ b/doc/build/content/document_base.myt @@ -26,6 +26,14 @@ version = '0.91' +<%method title> +% try: +# avoid inheritance via attr instead of attributes + <% m.base_component.attr['title'] %> - SQLAlchemy Documentation +% except KeyError: + SQLAlchemy Documentation +% + diff --git a/doc/build/content/metadata.myt b/doc/build/content/metadata.myt index 32dd0d0c02..49ca04bb27 100644 --- a/doc/build/content/metadata.myt +++ b/doc/build/content/metadata.myt @@ -1,4 +1,5 @@ <%flags>inherit='document_base.myt' +<%attr>title='Database Meta Data' <&|doclib.myt:item, name="metadata", description="Database Meta Data" &> <&|doclib.myt:item, name="tables", description="Describing Tables with MetaData" &>

The core of SQLAlchemy's query and object mapping operations is table metadata, which are Python objects that describe tables. Metadata objects can be created by explicitly naming the table and all its properties, using the Table, Column, ForeignKey, and Sequence objects imported from sqlalchemy.schema, and a database engine constructed as described in the previous section, or they can be automatically pulled from an existing database schema. First, the explicit version:

diff --git a/doc/build/content/pooling.myt b/doc/build/content/pooling.myt index 209b3313b3..0bec280830 100644 --- a/doc/build/content/pooling.myt +++ b/doc/build/content/pooling.myt @@ -1,4 +1,5 @@ <%flags>inherit='document_base.myt' +<%attr>title='Connection Pooling' <&|doclib.myt:item, name="pooling", description="Connection Pooling" &>

Note:This section describes the connection pool module of SQLAlchemy, which is the smallest component of the library that can be used on its own. If you are interested in using SQLAlchemy for query construction or Object Relational Mapping, this module is automatically managed behind the scenes; you can skip ahead to <&formatting.myt:link,path="dbengine"&> in that case.

At the base of any database helper library is a system of efficiently acquiring connections to the database. Since the establishment of a database connection is typically a somewhat expensive operation, an application needs a way to get at database connections repeatedly without incurring the full overhead each time. Particularly for server-side web applications, a connection pool is the standard way to maintain a "pool" of database connections which are used over and over again among many requests. Connection pools typically are configured to maintain a certain "size", which represents how many connections can be used simultaneously without resorting to creating more newly-established connections. diff --git a/doc/build/content/roadmap.myt b/doc/build/content/roadmap.myt index 40460b362a..146d7d843c 100644 --- a/doc/build/content/roadmap.myt +++ b/doc/build/content/roadmap.myt @@ -1,4 +1,5 @@ <%flags>inherit='document_base.myt' +<%attr>title='Roadmap' <&|doclib.myt:item, name="roadmap", description="Roadmap" &>

SQLAlchemy includes several components, each of which are useful by themselves to give varying levels of assistance to a database-enabled application. Below is a roadmap of the "knowledge dependencies" between these components indicating the order in which concepts may be learned.

diff --git a/doc/build/content/sqlconstruction.myt b/doc/build/content/sqlconstruction.myt index d11bfdde7e..ec81e44c5f 100644 --- a/doc/build/content/sqlconstruction.myt +++ b/doc/build/content/sqlconstruction.myt @@ -1,4 +1,6 @@ <%flags>inherit='document_base.myt' +<%attr>title='Constructing SQL Queries via Python Expressions' + <&|doclib.myt:item, name="sql", description="Constructing SQL Queries via Python Expressions" &>

Note: This section describes how to use SQLAlchemy to construct SQL queries and receive result sets. It does not cover the object relational mapping capabilities of SQLAlchemy; that is covered later on in <&formatting.myt:link, path="datamapping"&>. However, both areas of functionality work similarly in how selection criterion is constructed, so if you are interested just in ORM, you should probably skim through basic <&formatting.myt:link, path="sql_select_whereclause"&> construction before moving on.

Once you have used the sqlalchemy.schema module to construct your tables and/or reflect them from the database, performing SQL queries using those table meta data objects is done via the sqlalchemy.sql package. This package defines a large set of classes, each of which represents a particular kind of lexical construct within a SQL query; all are descendants of the common base class sqlalchemy.sql.ClauseElement. A full query is represented via a structure of ClauseElements. A set of reasonably intuitive creation functions is provided by the sqlalchemy.sql package to create these structures; these functions are described in the rest of this section.

diff --git a/doc/build/content/types.myt b/doc/build/content/types.myt index 6f4de36195..d9d3cb141e 100644 --- a/doc/build/content/types.myt +++ b/doc/build/content/types.myt @@ -1,4 +1,6 @@ <%flags>inherit='document_base.myt' +<%attr>title='The Types System' + <&|doclib.myt:item, name="types", description="The Types System" &>

The package sqlalchemy.types defines the datatype identifiers which may be used when defining <&formatting.myt:link, path="metadata", text="table metadata"&>. This package includes a set of generic types, a set of SQL-specific subclasses of those types, and a small extension system used by specific database connectors to adapt these generic types into database-specific type objects.

diff --git a/doc/build/content/unitofwork.myt b/doc/build/content/unitofwork.myt index 71345393da..d96e41ee4a 100644 --- a/doc/build/content/unitofwork.myt +++ b/doc/build/content/unitofwork.myt @@ -1,4 +1,6 @@ <%flags>inherit='document_base.myt' +<%attr>title='Unit of Work' + <&|doclib.myt:item, name="unitofwork", description="Unit of Work" &> <&|doclib.myt:item, name="overview", description="Overview" &>