From: Mike Bayer Date: Sun, 8 Aug 2010 17:57:18 +0000 (-0400) Subject: introductions X-Git-Tag: rel_0_6_4~49 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c71513ce42d9a5efc621e39e858169ad069e009b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git introductions --- diff --git a/doc/build/ormtutorial.rst b/doc/build/ormtutorial.rst index b5d7c83f07..2d6a3325ea 100644 --- a/doc/build/ormtutorial.rst +++ b/doc/build/ormtutorial.rst @@ -3,7 +3,44 @@ ========================== Object Relational Tutorial ========================== -In this tutorial we will cover a basic SQLAlchemy object-relational mapping scenario, where we store and retrieve Python objects from a database representation. The tutorial is in doctest format, meaning each ``>>>`` line represents something you can type at a Python command prompt, and the following text represents the expected return value. + +Introduction +============ + +The SQLAlchemy Object Relational Mapper presents a method of associating +user-defined Python classes with database tables, and instances of those +classes (objects) with rows in their corresponding tables. It includes a +system that transparently synchronizes all changes in state between objects +and their related rows, called a `unit of work +`_, as well as a system +for expressing database queries in terms of the user defined classes and their +defined relationships between each other. + +The ORM is in contrast to the SQLAlchemy Expression Language, upon which the +ORM is constructed. Whereas the SQL Expression Language, introduced in +:ref:`sqlexpression_toplevel`, presents a system of representing the primitive +constructs of the relational database directly without opinion, the ORM +presents a high level and abstracted pattern of usage, which itself is an +example of applied usage of the Expression Language. + +While there is overlap among the usage patterns of the ORM and the Expression +Language, the similarities are more superficial than they may at first appear. +One approaches the structure and content of data from the perspective of a +user-defined `domain model +`_ which is transparently +persisted and refreshed from its underlying storage model. The other +approaches it from the perspective of literal schema and SQL expression +representations which are explicitly composed into messages consumed +individually by the database. + +A successful application may be constructed using the Object Relational Mapper +exclusively. In advanced situations, an application constructed with the ORM +may make occasional usage of the Expression Language directly in certain areas +where specific database interactions are required. + +The following tutorial is in doctest format, meaning each ``>>>`` line +represents something you can type at a Python command prompt, and the +following text represents the expected return value. Version Check ============= diff --git a/doc/build/sqlexpression.rst b/doc/build/sqlexpression.rst index 15116a273c..23190a143c 100644 --- a/doc/build/sqlexpression.rst +++ b/doc/build/sqlexpression.rst @@ -4,7 +4,50 @@ SQL Expression Language Tutorial ================================ -This tutorial will cover SQLAlchemy SQL Expressions, which are Python constructs that represent SQL statements. The tutorial is in doctest format, meaning each ``>>>`` line represents something you can type at a Python command prompt, and the following text represents the expected return value. The tutorial has no prerequisites. +Introduction +============= + +The SQLAlchemy Expression Language presents a system of representing +relational database structures and expressions using Python constructs. These +constructs are modeled to resemble those of the underlying database as closely +as possible, while providing a modicum of abstraction of the various +implementation differences between database backends. While the constructs +attempt to represent equivalent concepts between backends with consistent +structures, they do not conceal useful concepts that are unique to particular +subsets of backends. The Expression Language therefore presents a method of +writing backend-neutral SQL expressions, but does not attempt to enforce that +expressions are backend-neutral. + +The Expression Language is in contrast to the Object Relational Mapper, which +is a distinct API that builds on top of the Expression Language. Whereas the +ORM, introduced in :ref:`ormtutorial_toplevel`, presents a high level and +abstracted pattern of usage, which itself is an example of applied usage of +the Expression Language, the Expression Language presents a system of +representing the primitive constructs of the relational database directly +without opinion. + +While there is overlap among the usage patterns of the ORM and the Expression +Language, the similarities are more superficial than they may at first appear. +One approaches the structure and content of data from the perspective of a +user-defined `domain model +`_ which is transparently +persisted and refreshed from its underlying storage model. The other +approaches it from the perspective of literal schema and SQL expression +representations which are explicitly composed into messages consumed +individually by the database. + +A successful application may be constructed using the Expression Language +exclusively, though the application will need to define its own system of +translating application concepts into individual database messages and from +individual database result sets. Alternatively, an application constructed +with the ORM may, in advanced scenarios, make occasional usage of the +Expression Language directly in certain areas where specific database +interactions are required. + +The following tutorial is in doctest format, meaning each ``>>>`` line +represents something you can type at a Python command prompt, and the +following text represents the expected return value. The tutorial has no +prerequisites. Version Check ============= diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css index 9127e980bb..c0d6345570 100644 --- a/doc/build/static/docs.css +++ b/doc/build/static/docs.css @@ -159,7 +159,8 @@ div.note, div.warning { background-color:#EEFFEF; } -div.admonition { + +div.admonition, div.topic { border:1px solid #CCCCCC; margin:5px 5px 5px 5px; padding:5px 5px 5px 35px;