#source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
# General information about the project.
project = u'SQLAlchemy'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('index', 'sqlalchemy_%s.tex' % release.replace('.', '_'), ur'SQLAlchemy Documentation',
+ ('contents', 'sqlalchemy_%s.tex' % release.replace('.', '_'), ur'SQLAlchemy Documentation',
ur'Mike Bayer', 'manual'),
]
--- /dev/null
+.. _contents:
+
+Table of Contents
+=================
+
+Full table of contents. For a high level overview of all
+documentation, see :ref:`index_toplevel`.
+
+.. toctree::
+ :maxdepth: 3
+
+ intro
+ orm/index
+ core/index
+ dialects/index
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`search`
.. module:: sqlalchemy.schema
+
+.. _metadata_describing:
+
Describing Databases with MetaData
==================================
:undoc-members:
:show-inheritance:
+
+.. _metadata_defaults:
+
Column Insert/Update Defaults
==============================
=================================
.. _metadata_foreignkeys:
+.. _metadata_constraints:
Defining Foreign Keys
---------------------
.. autoclass:: Index
:show-inheritance:
+.. _metadata_ddl:
+
Customizing DDL
===============
typically accept a type class or instance; ``Integer`` is equivalent
to ``Integer()`` with no construction arguments in this case.
+.. _types_generic:
+
Generic Types
-------------
:show-inheritance:
:members:
+.. _types_sqlstandard:
+
SQL Standard Types
------------------
.. autoclass:: VARCHAR
:show-inheritance:
+.. _types_vendor:
Vendor-Specific Types
---------------------
Column('col2', TEXT(charset='latin1'))
)
+.. _types_custom:
+
Custom Types
------------
:inherited-members:
:show-inheritance:
+.. _types_api:
+
Base Type API
--------------
-Table of Contents
-=================
+.. _index_toplevel:
-.. toctree::
- :maxdepth: 2
+========================
+SQLAlchemy Documentation
+========================
- intro
- orm/index
- core/index
- dialects/index
+Getting Started
+===============
+
+A high level view and getting set up.
+
+:ref:`Overview <overview>` |
+:ref:`Installation Guide <installation>` |
+:ref:`Migration from 0.5 <migration>`
+
+SQLAlchemy ORM
+==============
+
+Here, the Object Relational Mapper is introduced and
+fully described. If you want to work with higher-level SQL which is
+constructed automatically for you, as well as automated persistence
+of Python objects, proceed first to the tutorial.
+
+* **Read this first:**
+ :doc:`orm/tutorial`
+
+* **ORM Configuration:**
+ :doc:`Mapper Configuration <orm/mapper_config>` |
+ :doc:`Relationship Configuration <orm/relationships>` |
+ :doc:`Inheritance Mapping <orm/inheritance>` |
+ :doc:`Advanced Collection Configuration <orm/collections>`
+
+* **Configuration Extensions:**
+ :doc:`Declarative Extension <orm/extensions/declarative>` |
+ :doc:`Association Proxy <orm/extensions/associationproxy>` |
+ :doc:`Ordered List <orm/extensions/orderinglist>`
+
+* **ORM Usage:**
+ :doc:`Session Usage and Guidelines <orm/session>` |
+ :doc:`Query API reference <orm/query>` |
+ :doc:`Relationship Loading Techniques <orm/loading>`
+
+* **Extending the ORM:**
+ :doc:`ORM Event Interfaces <orm/interfaces>`
+
+* **Other:**
+ :doc:`Introduction to Examples <orm/examples>` |
+ :doc:`ORM Exceptions <orm/exceptions>` |
+ :doc:`Horizontal Sharding <orm/extensions/horizontal_shard>` |
+ :doc:`SQLSoup <orm/extensions/sqlsoup>`
+
+SQLAlchemy Core
+===============
+
+The breadth of SQLAlchemy's SQL rendering engine, DBAPI
+integration, transaction integration, and schema description services
+are documented here. In contrast to the ORM's domain-centric mode of usage, the SQL Expression Language provides a schema-centric usage paradigm.
+
+* **Read this first:**
+ :doc:`core/tutorial`
+
+* **All the Built In SQL:**
+ :doc:`SQL Expression API <core/expression_api>`
+
+* **Engines, Connections, Pools:**
+ :doc:`Engine Configuration <core/engines>` |
+ :doc:`Connections, Transactions <core/connections>` |
+ :doc:`Connection Pooling <core/pooling>`
+
+* **Schema Definition:**
+ :ref:`Tables and Columns <metadata_describing>` |
+ :ref:`Database Introspection (Reflection) <metadata_reflection>` |
+ :ref:`Insert/Update Defaults <metadata_defaults>` |
+ :ref:`Constraints and Indexes <metadata_constraints>` |
+ :ref:`Using Data Definition Language (DDL) <metadata_ddl>`
+
+* **Datatypes:**
+ :ref:`Overview <types_toplevel>` |
+ :ref:`Generic Types <types_generic>` |
+ :ref:`SQL Standard Types <types_sqlstandard>` |
+ :ref:`Vendor Specific Types <types_vendor>` |
+ :ref:`Building Custom Types <types_custom>` |
+ :ref:`API <types_api>`
+
+* **Extending the Core:**
+ :doc:`Core Event Interfaces <core/interfaces>` |
+ :doc:`Creating Custom SQL Constructs <core/compiler>`
+
+* **Other:**
+ :doc:`Serializing Expressions <core/serializer>` |
+ :doc:`core/exceptions`
+
+Dialect Documentation
+======================
+
+The **dialect** is the system SQLAlchemy uses to communicate with various types of DBAPIs and databases. This section describes notes, options, and
+usage patterns regarding individual dialects.
+
+:doc:`dialects/firebird` |
+:doc:`dialects/informix` |
+:doc:`dialects/maxdb` |
+:doc:`dialects/access` |
+:doc:`dialects/mssql` |
+:doc:`dialects/mysql` |
+:doc:`dialects/oracle` |
+:doc:`dialects/postgresql` |
+:doc:`dialects/sqlite` |
+:doc:`dialects/sybase`
-Indices and tables
-------------------
-* :ref:`genindex`
-* :ref:`search`
.. _overview_toplevel:
-=======================
-Overview / Installation
-=======================
-
+========
Overview
========
+.. _overview:
+
+Overview
+========
The SQLAlchemy SQL Toolkit and Object Relational Mapper
is a comprehensive set of tools for working with
as it is used within object-relational configurations and
queries.
+.. _doc_overview:
+
Documentation Overview
======================
In :ref:`core_toplevel`, the breadth of SQLAlchemy's SQL and database
integration and description services are documented, the core of which is the
-SQL Expression language. The SQL Expression Language is a toolkit all its own,
-independent of the ORM package, which can be used to construct manipulable SQL
+SQL Expression language. The SQL Expression Language is a toolkit all its own, independent of the ORM package, which can be used to construct manipulable SQL
expressions which can be programmatically constructed, modified, and executed,
-returning cursor-like result sets. In contrast to the ORM's domain-centric
+returning cursor-like result sets. In contrast to the ORM's domain-centric
mode of usage, the expression language provides a schema-centric usage
paradigm. New users should begin here with :ref:`sqlexpression_toplevel`.
-SQLAlchemy engine, connection, and pooling services are also described in
+SQLAlchemy engine, connection, and pooling services are also described in
:ref:`core_toplevel`.
-In :ref:`dialect_toplevel`, reference documentation for all provided
+In :ref:`dialect_toplevel`, reference documentation for all provided
database and DBAPI backends is provided.
Code Examples
constructs as well as the ORM on the wiki. See
`<http://www.sqlalchemy.org/trac/wiki/UsageRecipes>`_.
-Installing SQLAlchemy
-======================
+.. _installation:
+
+Installation Guide
+==================
+
+SQLAlchemy builds using the standard `Python Distutils <http://docs.python.org/distutils/>`_ approach.
+
+Installing with setuptools or pip
+----------------------------------
Installing SQLAlchemy from scratch is most easily achieved with `setuptools
<http://pypi.python.org/pypi/setuptools/>`_, or alternatively
-`pip <http://pypi.python.org/pypi/pip/>`_. Assuming it's installed, just run
-this from the command-line:
+`pip <http://pypi.python.org/pypi/pip/>`_. Assuming it's installed, just run this from the command-line:
.. sourcecode:: none
# pip install SQLAlchemy
This command will download the latest version of SQLAlchemy from the `Python
-Cheese Shop <http://pypi.python.org/pypi/SQLAlchemy>`_ and install it to your
-system.
+Cheese Shop <http://pypi.python.org/pypi/SQLAlchemy>`_ and install it to your system.
+
+Installing using setup.py
+----------------------------------
Otherwise, you can install from the distribution using the ``setup.py`` script:
# python setup.py install
+Installing the C Extensions
+----------------------------------
+
+SQLAlchemy includes C extensions which provide an extra speed boost for
+dealing with result sets. In version 0.6, these extensions must be explicitly
+enabled (in 0.7 they will build by default).
+
+To install including building the C extensions, use the ``--with-cextensions`` flag.
+This flag must be on the command line before the actual install or build command::
+
+ python setup.py --with-cextensions install
+
+Installing on Python 3
+----------------------------------
+
+SQLAlchemy ships as Python 2 code. For Python 3 usage, the ``setup.py`` script will invoke the Python ``2to3`` tool on the build, plugging in an extra "preprocessor" as well. Using the Python 3 interpreter with ``setup.py`` or a Python 3 version of easy_install or pip is all that's needed.
+
Installing a Database API
-==========================
+----------------------------------
SQLAlchemy is designed to operate with a `DB-API <http://www.python.org/doc/peps/pep-0249/>`_ implementation built for a particular database, and includes support for the most popular databases. The current list is at :ref:`supported_dbapis`.
Checking the Installed SQLAlchemy Version
-=========================================
+------------------------------------------
This documentation covers SQLAlchemy version 0.6. If you're working on a system that already has SQLAlchemy installed, check the version from your Python prompt like this:
>>> sqlalchemy.__version__ # doctest: +SKIP
0.6.0
+.. _migration:
+
0.5 to 0.6 Migration
=====================
padding:20px;
}
+
+#navbanner {
+}
+
#pagecontrol {
- float:right;
+ float:right;
+ width:300px;
}
-.topnav
-{
+#pagecontrol ul {
+ padding:0;
+ margin:0;
+}
+#pagecontrol li {
+ font-size:.9em;
+ list-style-type:none;
+}
+
+.topnav {
background-color: #fbfbee;
border: solid 1px #ccc;
padding:10px;
margin:10px 0px 10px 0px;
+ display:block;
}
.document {
}
.topnav h2 {
- margin:26px 4px 0px 5px;
+ margin:8px 4px 0px 5px;
font-family:arial,helvetica,sans-serif;
font-size:1.6em;
font-weight:normal;
padding-top:10px;
}
+.section ul {
+ padding: 0 0 0 25px;
+}
+
.section {
line-height: 1.5em;
- padding:8px 10px 20px 10px;
+ padding:0px 10px 20px 10px;
margin:10px 0px 0px;
}
margin:0px 0px 0px 20px;
}
+div#sqlalchemy-documentation {
+ font-size:.95em;
+}
+div#sqlalchemy-documentation em {
+ font-style:normal;
+}
+div#sqlalchemy-documentation .rubric{
+ font-size:14px;
+ background-color:#EEFFEF;
+ padding:5px;
+ border:1px solid #BFBFBF;
+}
+div#sqlalchemy-documentation a, div#sqlalchemy-documentation li {
+ padding:5px 0px;
+}
+
+div#getting-started {
+ border-bottom:1px solid;
+}
+
+div#sqlalchemy-orm {
+ float:left;
+ width:48%;
+}
+
+div#sqlalchemy-core {
+ float:left;
+ width:48%;
+ margin:0;
+ padding-left:10px;
+ border-left:1px solid;
+}
+
+div#dialect-documentation {
+ border-top:1px solid;
+ clear:left;
+}
+
+
th.field-name {
text-align:right;
}
+
div.note, div.warning, p.deprecated {
background-color:#EEFFEF;
}
<div class="topnav">
<div id="pagecontrol">
- <a href="${pathto('genindex')}">Index</a>
-
- % if sourcename:
- <div class="sourcelink">(<a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')})</div>
+ <ul>
+ % if prevtopic:
+ <li>Prev:
+ <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+ </li>
+ % endif
+ % if nexttopic:
+ <li>Next:
+ <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+ </li>
% endif
- </div>
- <div class="navbanner">
- <a class="totoc" href="${pathto(master_doc)}">Table of Contents</a>
+ <li>
+ <a href="${pathto('contents')}">Table of Contents</a> |
+ <a href="${pathto('genindex')}">Index</a>
+ % if sourcename:
+ | <a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')}
+ % endif
+ </li>
+ </ul>
+ </div>
+ <div id="navbanner">
+ <a class="totoc" href="${pathto('index')}">${docstitle|h}</a>
% if parents:
% for parent in parents:
» <a href="${parent['link']|h}" title="${parent['title']}">${parent['title']}</a>
% endfor
% endif
- % if current_page_name != master_doc:
+ % if current_page_name != 'index':
» ${self.show_title()}
% endif
- ${prevnext()}
<h2>
${self.show_title()}
</h2>
- </div>
- % if display_toc and not current_page_name.startswith('index'):
+ % if display_toc and \
+ not current_page_name.startswith('index') and \
+ not current_page_name.startswith('contents'):
${toc}
% endif
+ </div>
<div class="clearboth"></div>
</div>
<%def name="footer()">
<div class="bottomnav">
- ${prevnext()}
+ % if prevtopic:
+ Previous:
+ <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+ % endif
+ % if nexttopic:
+ Next:
+ <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+ % endif
<div class="doc_copyright">
% if hasdoc('copyright'):
© <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
</%def>
${self.footer()}
-<%def name="prevnext()">
-<div class="prevnext">
- % if prevtopic:
- Previous:
- <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
- % endif
- % if nexttopic:
- Next:
- <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
- % endif
-</div>
-</%def>
-
<%def name="show_title()">
% if title:
${title}
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
