From: Mike Bayer Date: Wed, 8 Sep 2010 19:43:24 +0000 (-0400) Subject: edits X-Git-Tag: rel_0_6_5~81 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a191ded054899fe2d827b4341529f1a5ec1d711e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git edits --- diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 1bd7278328..91e1d698b3 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -97,13 +97,6 @@ DBAPI connection resource to the pool (SQLAlchemy achieves this by the usage of weakref callbacks - *never* the ``__del__`` method) - however it's never a good idea to rely upon Python garbage collection to manage resources. -We have just summarized two of three usage patterns that are possible -with the :class:`.Engine`. When the :class:`.Connection` object is used -explicitly, it's referred to as **explicit execution**. When the -:meth:`~.Engine.execute` method of :class:`.Engine` is used, this -pattern is referred to as **explicit, connectionless execution**. The -third pattern is known as **implicit execution** and is described later. - Our example above illustrated the execution of a textual SQL string. The :meth:`~.Connection.execute` method can of course accommodate more than that, including the variety of SQL expression constructs described @@ -240,7 +233,8 @@ refers to the usage of the ``execute()`` method on an object which is not a :class:`.Connection`. This was illustrated using the :meth:`~.Engine.execute` method of :class:`.Engine`. -A third case exists, which is to use the :meth:`~.Executable.execute` method of +In addition to "connectionless" execution, it is also possible +to use the :meth:`~.Executable.execute` method of any :class:`.Executable` construct, which is a marker for SQL expression objects that support execution. The SQL expression object itself references an :class:`.Engine` or :class:`.Connection` known as the **bind**, which it uses @@ -329,7 +323,7 @@ connection resources derived from a thread-local variable whenever :meth:`.Engine.execute` or :meth:`.Engine.contextual_connect` is called. This connection resource is maintained as long as it is referenced, which allows multiple points of an application to share a transaction while using -connectionless, explicit execution:: +connectionless execution:: def call_operation1(): engine.execute("insert into users values (?, ?)", 1, "john") @@ -372,4 +366,4 @@ call :meth:`.Engine.contextual_connect`:: Calling :meth:`~.Connection.close` on the "contextual" connection does not release its resources until all other usages of that resource are closed as well, including -that any ongoing transactions are rolled back or committed. \ No newline at end of file +that any ongoing transactions are rolled back or committed. diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 63d76efa02..79cadaea90 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -812,10 +812,7 @@ class Connection(Connectable): upon the connection, including its expiration or timeout state. For the connection pool to properly manage connections, connections should be returned to the connection pool (i.e. ``connection.close()``) whenever the - connection is not in use. If your application has a need for management - of multiple connections or is otherwise long running (this includes all - web applications, threaded or not), don't hold a single connection open at - the module level. + connection is not in use. .. index:: single: thread safety; Connection diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 4eae375d8b..879a7b0c1e 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -318,25 +318,28 @@ def relationship(argument, secondary=None, **kwargs): which is already higher up in the chain. This option applies both to joined- and subquery- eager loaders. - :param lazy=('select'|'joined'|'subquery'|'noload'|'dynamic'): specifies - how the related items should be loaded. Values include: + :param lazy='select': specifies + how the related items should be loaded. Default value is + ``select``. Values include: - * 'select' - items should be loaded lazily when the property is first - accessed. + * ``select`` - items should be loaded lazily when the property is first + accessed, using a separate SELECT statement. - * 'joined' - items should be loaded "eagerly" in the same query as - that of the parent, using a JOIN or LEFT OUTER JOIN. + * ``joined`` - items should be loaded "eagerly" in the same query as + that of the parent, using a JOIN or LEFT OUTER JOIN. Whether + the join is "outer" or not is determined by the ``innerjoin`` + parameter. - * 'subquery' - items should be loaded "eagerly" within the same + * ``subquery`` - items should be loaded "eagerly" within the same query as that of the parent, using a second SQL statement which issues a JOIN to a subquery of the original statement. - * 'noload' - no loading should occur at any time. This is to + * ``noload`` - no loading should occur at any time. This is to support "write-only" attributes, or attributes which are populated in some manner specific to the application. - * 'dynamic' - the attribute will return a pre-configured + * ``dynamic`` - the attribute will return a pre-configured :class:`~sqlalchemy.orm.query.Query` object for all read operations, onto which further filtering operations can be applied before iterating the results. The dynamic