From 5f73cf9c514b6e6bd0d52b95397e165d9a82db67 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 28 Oct 2012 12:27:32 -0400 Subject: [PATCH] glossary updates --- doc/build/dialects/postgresql.rst | 2 - doc/build/glossary.rst | 70 +++++++++++++++++++++++-------- doc/build/static/docs.css | 1 + 3 files changed, 54 insertions(+), 19 deletions(-) diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst index 55705a037a..072469406d 100644 --- a/doc/build/dialects/postgresql.rst +++ b/doc/build/dialects/postgresql.rst @@ -69,8 +69,6 @@ construction arguments, are as follows: :members: __init__ :show-inheritance: -.. _psycopg2: - psycopg2 -------------- diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 62f1e785ff..41c8db1a05 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -11,7 +11,7 @@ Glossary terms soon! .. glossary:: - + :sorted: descriptor In Python, a descriptor is an object attribute with “binding behavior”, one whose attribute access has been overridden by methods in the `descriptor protocol `_. @@ -74,6 +74,7 @@ Glossary or relationship to a related class. lazy load + lazy loads In object relational mapping, a "lazy load" refers to an attribute that does not contain its database-side value for some period of time, typically when the object is @@ -139,27 +140,62 @@ Glossary release releases released - This term refers to when an operation terminates some state which - corresponds to a service of some kind. Specifically within - SQLAlchemy, it usually refers to a reference to a database connection, - and typically a transaction associated with that connection. - When we say "the operation releases transactional resources", - it means basically that we have a :class:`.Connection` object - and we are calling the :meth:`.Connection.close` method, which has - the effect of the underlying DBAPI connection being returned - to the connection pool. The connection pool, when it receives - a connection for return, unconditionally calls the ``rollback()`` - method of the DBAPI connection, so that any locks or data snapshots within - that connection are removed. Then, the connection is either - stored locally in memory, still connected but not in a transaction, - for subsequent reuse by another operation, or it is closed - immediately, depending on the configuration and current - state of the connection pool. + In the context of SQLAlchemy, the term "released" + refers to the process of ending the usage of a particular + database connection. SQLAlchemy features the usage + of connection pools, which allows configurability as to + the lifespan of database connections. When using a pooled + connection, the process of "closing" it, i.e. invoking + a statement like ``connection.close()``, may have the effect + of the connection being returned to an existing pool, + or it may have the effect of actually shutting down the + underlying TCP/IP connection referred to by that connection - + which one takes place depends on configuration as well + as the current state of the pool. So we used the term + *released* instead, to mean "do whatever it is you do + with connections when we're done using them". + + The term will sometimes be used in the phrase, "release + transactional resources", to indicate more explicitly that + what we are actually "releasing" is any transactional + state which as accumulated upon the connection. In most + situations, the proces of selecting from tables, emitting + updates, etc. acquires :term:`isolated` state upon + that connection as well as potential row or table locks. + This state is all local to a particular transaction + on the connection, and is released when we emit a rollback. + An important feature of the connection pool is that when + we return a connection to the pool, the ``connection.rollback()`` + method of the DBAPI is called as well, so that as the + connection is set up to be used again, it's in a "clean" + state with no references held to the previous series + of operations. .. seealso:: :ref:`pooling_toplevel` + DBAPI + DBAPI is shorthand for the phrase "Python Database API + Specification". This is a widely used specification + within Python to define common usage patterns for all + database connection packages. The DBAPI is a "low level" + API which is typically the lowest level system used + in a Python application to talk to a database. SQLAlchemy's + :term:`dialect` system is constructed around the + operation of the DBAPI, providing individual dialect + classes which service a specific DBAPI on top of a + specific database engine; for example, the :func:`.create_engine` + URL ``postgresql+psycopg2://@localhost/test`` + refers to the :mod:`psycopg2 <.postgresql.psycopg2>` + DBAPI/dialect combination, whereas the URL ``mysql+mysqldb://@localhost/test`` + refers to the :mod:`MySQL for Python <.mysql.mysqldb>` + DBAPI DBAPI/dialect combination. + + .. seealso:: + + `PEP 249 - Python Database API Specification v2.0 `_ + unit of work This pattern is where the system transparently keeps diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css index c0dbdcb289..bb300e829b 100644 --- a/doc/build/static/docs.css +++ b/doc/build/static/docs.css @@ -374,6 +374,7 @@ dl.exception > dt dl.glossary > dt { font-weight:bold; font-size:1.1em; + padding-top:10px; } -- 2.47.3