From 52d2e67edbbe6e05df04b18f3a47fac33ede3970 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 6 Dec 2009 01:27:35 +0000 Subject: [PATCH] some doc reference fixes per [ticket:1597] --- doc/build/dbengine.rst | 12 +++++++----- doc/build/mappers.rst | 8 +++++--- doc/build/metadata.rst | 2 +- doc/build/ormtutorial.rst | 2 +- doc/build/reference/orm/collections.rst | 3 +++ doc/build/session.rst | 10 ++++++++-- doc/build/sqlexpression.rst | 2 +- 7 files changed, 26 insertions(+), 13 deletions(-) diff --git a/doc/build/dbengine.rst b/doc/build/dbengine.rst index c7f924a9dc..275ceaf11c 100644 --- a/doc/build/dbengine.rst +++ b/doc/build/dbengine.rst @@ -182,7 +182,7 @@ The ``execute()`` methods on both ``Engine`` and ``Connection`` can also receive print row['col1'], row['col2'] connection.close() -The above SQL construct is known as a ``select()``. The full range of SQL constructs available are described in `sql`. +The above SQL construct is known as a ``select()``. The full range of SQL constructs available are described in :ref:`sqlexpression_toplevel`. Both ``Connection`` and ``Engine`` fulfill an interface known as ``Connectable`` which specifies common functionality between the two objects, namely being able to call ``connect()`` to return a ``Connection`` object (``Connection`` just returns itself), and being able to call ``execute()`` to get a result set. Following this, most SQLAlchemy functions and objects which accept an ``Engine`` as a parameter or attribute with which to execute SQL will also accept a ``Connection``. As of SQLAlchemy 0.3.9, this argument is named ``bind``:: @@ -253,7 +253,7 @@ The ``Transaction`` object also handles "nested" behavior by keeping track of th Above, ``method_a`` is called first, which calls ``connection.begin()``. Then it calls ``method_b``. When ``method_b`` calls ``connection.begin()``, it just increments a counter that is decremented when it calls ``commit()``. If either ``method_a`` or ``method_b`` calls ``rollback()``, the whole transaction is rolled back. The transaction is not committed until ``method_a`` calls the ``commit()`` method. This "nesting" behavior allows the creation of functions which "guarantee" that a transaction will be used if one was not already available, but will automatically participate in an enclosing transaction if one exists. -Note that SQLAlchemy's Object Relational Mapper also provides a way to control transaction scope at a higher level; this is described in `unitofwork_transaction`. +Note that SQLAlchemy's Object Relational Mapper also provides a way to control transaction scope at a higher level; this is described in :ref:`unitofwork_transaction`. .. index:: single: thread safety; transactions @@ -274,12 +274,14 @@ The above transaction example illustrates how to use ``Transaction`` so that sev conn = engine.connect() conn.execute("INSERT INTO users VALUES (1, 'john')") # autocommits +.. _dbengine_implicit: + Connectionless Execution, Implicit Execution ============================================= -Recall from the first section we mentioned executing with and without a ``Connection``. ``Connectionless`` execution refers to calling the ``execute()`` method on an object which is not a ``Connection``, which could be on the ``Engine`` itself, or could be a constructed SQL object. When we say "implicit", we mean that we are calling the ``execute()`` method on an object which is neither a ``Connection`` nor an ``Engine`` object; this can only be used with constructed SQL objects which have their own ``execute()`` method, and can be "bound" to an ``Engine``. A description of "constructed SQL objects" may be found in `sql`. +Recall from the first section we mentioned executing with and without a ``Connection``. ``Connectionless`` execution refers to calling the ``execute()`` method on an object which is not a ``Connection``, which could be on the ``Engine`` itself, or could be a constructed SQL object. When we say "implicit", we mean that we are calling the ``execute()`` method on an object which is neither a ``Connection`` nor an ``Engine`` object; this can only be used with constructed SQL objects which have their own ``execute()`` method, and can be "bound" to an ``Engine``. A description of "constructed SQL objects" may be found in :ref:`sqlexpression_toplevel`. -A summary of all three methods follows below. First, assume the usage of the following ``MetaData`` and ``Table`` objects; while we haven't yet introduced these concepts, for now you only need to know that we are representing a database table, and are creating an "executable" SQL construct which issues a statement to the database. These objects are described in `metadata`. +A summary of all three methods follows below. First, assume the usage of the following ``MetaData`` and ``Table`` objects; while we haven't yet introduced these concepts, for now you only need to know that we are representing a database table, and are creating an "executable" SQL construct which issues a statement to the database. These objects are described in :ref:`metadata_toplevel`. .. sourcecode:: python+sql @@ -310,7 +312,7 @@ Explicit, connectionless execution delivers the expression to the ``execute()`` # .... result.close() -Implicit execution is also connectionless, and calls the ``execute()`` method on the expression itself, utilizing the fact that either an ``Engine`` or ``Connection`` has been *bound* to the expression object (binding is discussed further in the next section, `metadata`): +Implicit execution is also connectionless, and calls the ``execute()`` method on the expression itself, utilizing the fact that either an ``Engine`` or ``Connection`` has been *bound* to the expression object (binding is discussed further in the next section, :ref:`metadata_toplevel`): .. sourcecode:: python+sql diff --git a/doc/build/mappers.rst b/doc/build/mappers.rst index 20a23b0c4c..b9f598a3ef 100644 --- a/doc/build/mappers.rst +++ b/doc/build/mappers.rst @@ -881,6 +881,8 @@ Multiple extensions will be chained together and processed in order; they are sp m = mapper(User, users_table, extension=[ext1, ext2, ext3]) +.. _advdatamapping_relation: + Relation Configuration ======================= @@ -1466,7 +1468,7 @@ Dictionary-Based Collections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A ``dict`` can be used as a collection, but a keying strategy is needed to map entities loaded by the ORM to key, value pairs. The `sqlalchemy.orm.collections` package provides several built-in types for dictionary-based collections: +A ``dict`` can be used as a collection, but a keying strategy is needed to map entities loaded by the ORM to key, value pairs. The :mod:`sqlalchemy.orm.collections` package provides several built-in types for dictionary-based collections: .. sourcecode:: python+sql @@ -1488,7 +1490,7 @@ A ``dict`` can be used as a collection, but a keying strategy is needed to map e These functions each provide a ``dict`` subclass with decorated ``set`` and ``remove`` methods and the keying strategy of your choice. -The `sqlalchemy.orm.collections.MappedCollection` class can be used as a base class for your custom types or as a mix-in to quickly add ``dict`` collection support to other classes. It uses a keying function to delegate to ``__setitem__`` and ``__delitem__``: +The :class:`sqlalchemy.orm.collections.MappedCollection` class can be used as a base class for your custom types or as a mix-in to quickly add ``dict`` collection support to other classes. It uses a keying function to delegate to ``__setitem__`` and ``__delitem__``: .. sourcecode:: python+sql @@ -1521,7 +1523,7 @@ The decorations are lightweight and no-op outside of relations, but they do add The ORM uses this approach for built-ins, quietly substituting a trivial subclass when a ``list``, ``set`` or ``dict`` is used directly. -The collections package provides additional decorators and support for authoring custom types. See the `sqlalchemy.orm.collections` for more information and discussion of advanced usage and Python 2.3-compatible decoration options. +The collections package provides additional decorators and support for authoring custom types. See the :mod:`sqlalchemy.orm.collections` package for more information and discussion of advanced usage and Python 2.3-compatible decoration options. Configuring Loader Strategies: Lazy Loading, Eager Loading ----------------------------------------------------------- diff --git a/doc/build/metadata.rst b/doc/build/metadata.rst index f79c637ee0..cd6f44b705 100644 --- a/doc/build/metadata.rst +++ b/doc/build/metadata.rst @@ -31,7 +31,7 @@ To represent a Table, use the ``Table`` class:: Column('pref_value', String(100)) ) -The specific datatypes for each Column, such as Integer, String, etc. are described in `types`, and exist within the module ``sqlalchemy.types`` as well as the global ``sqlalchemy`` namespace. +The specific datatypes for each Column, such as Integer, String, etc. are described in :mod:`sqlalchemy.types`, and exist within the module ``sqlalchemy.types`` as well as the global ``sqlalchemy`` namespace. .. _metadata_foreignkeys: diff --git a/doc/build/ormtutorial.rst b/doc/build/ormtutorial.rst index e1d833cb82..8be9f264ea 100644 --- a/doc/build/ormtutorial.rst +++ b/doc/build/ormtutorial.rst @@ -784,7 +784,7 @@ If you want to reduce the number of queries (dramatically, in many cases), we ca >>> jack.addresses [, ] -SQLAlchemy has the ability to control exactly which attributes and how many levels deep should be joined together in a single SQL query. More information on this feature is available in `advdatamapping_relation`. +SQLAlchemy has the ability to control exactly which attributes and how many levels deep should be joined together in a single SQL query. More information on this feature is available in :ref:`advdatamapping_relation`. Querying with Joins ==================== diff --git a/doc/build/reference/orm/collections.rst b/doc/build/reference/orm/collections.rst index e8cf67884c..350e631251 100644 --- a/doc/build/reference/orm/collections.rst +++ b/doc/build/reference/orm/collections.rst @@ -9,6 +9,9 @@ This is an in-depth discussion of collection mechanics. For simple examples, se .. autoclass:: collection +.. autoclass:: sqlalchemy.orm.collections.MappedCollection + :members: + .. autofunction:: collection_adapter .. autofunction:: column_mapped_collection diff --git a/doc/build/session.rst b/doc/build/session.rst index b2b66c32fe..c89a7cb632 100644 --- a/doc/build/session.rst +++ b/doc/build/session.rst @@ -135,7 +135,7 @@ Frequently Asked Questions You typically invoke ``Session()`` when you first need to talk to your database, and want to save some objects or load some existing ones. Then, you work with it, save your changes, and then dispose of it....or at the very least ``close()`` it. It's not a "global" kind of object, and should be handled more like a "local variable", as it's generally **not** safe to use with concurrent threads. Sessions are very inexpensive to make, and don't use any resources whatsoever until they are first used...so create some ! - There is also a pattern whereby you're using a **contextual session**, this is described later in `unitofwork_contextual`. In this pattern, a helper object is maintaining a ``Session`` for you, most commonly one that is local to the current thread (and sometimes also local to an application instance). SQLAlchemy has worked this pattern out such that it still *looks* like you're creating a new session as you need one...so in that case, it's still a guaranteed win to just say ``Session()`` whenever you want a session. + There is also a pattern whereby you're using a **contextual session**, this is described later in :ref:`unitofwork_contextual`. In this pattern, a helper object is maintaining a ``Session`` for you, most commonly one that is local to the current thread (and sometimes also local to an application instance). SQLAlchemy has worked this pattern out such that it still *looks* like you're creating a new session as you need one...so in that case, it's still a guaranteed win to just say ``Session()`` whenever you want a session. * Is the Session a cache ? @@ -197,7 +197,7 @@ To add a list of items to the session at once, use ``add_all()``:: session.add_all([item1, item2, item3]) -The ``add()`` operation **cascades** along the ``save-update`` cascade. For more details see the section `unitofwork_cascades`. +The ``add()`` operation **cascades** along the ``save-update`` cascade. For more details see the section :ref:`unitofwork_cascades`. Merging ------- @@ -368,6 +368,8 @@ The session is also keeping track of all newly created (i.e. pending) objects, a Note that objects within the session are by default *weakly referenced*. This means that when they are dereferenced in the outside application, they fall out of scope from within the ``Session`` as well and are subject to garbage collection by the Python interpreter. The exceptions to this include objects which are pending, objects which are marked as deleted, or persistent objects which have pending changes on them. After a full flush, these collections are all empty, and all objects are again weakly referenced. To disable the weak referencing behavior and force all objects within the session to remain until explicitly expunged, configure ``sessionmaker()`` with the ``weak_identity_map=False`` setting. +.. _unitofwork_cascades: + Cascades ======== @@ -388,6 +390,8 @@ Note that the ``delete-orphan`` cascade only functions for relationships where t The default value for ``cascade`` on :func:`~sqlalchemy.orm.relation()` is ``save-update, merge``. +.. _unitofwork_transaction: + Managing Transactions ===================== @@ -558,6 +562,8 @@ When using the ``threadlocal`` engine context, the process above is simplified; engine.commit() # commit the transaction +.. _unitofwork_contextual: + Contextual/Thread-local Sessions ================================= diff --git a/doc/build/sqlexpression.rst b/doc/build/sqlexpression.rst index eba1496b51..ee3e4d3738 100644 --- a/doc/build/sqlexpression.rst +++ b/doc/build/sqlexpression.rst @@ -213,7 +213,7 @@ When the ``MetaData`` is bound, statements will also compile against the engine' >>> metadata.bind = None -Detailed examples of connectionless and implicit execution are available in the "Engines" chapter: `dbengine_implicit`. +Detailed examples of connectionless and implicit execution are available in the "Engines" chapter: :ref:`dbengine_implicit`. Selecting ========== -- 2.47.2