From 1ad3f6a4bc4e815b5844a2123b370322f0c7f38d Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 19 Apr 2007 16:00:35 +0000 Subject: [PATCH] some docstrings --- lib/sqlalchemy/engine/__init__.py | 45 +++++++++++++++++++++++++++++-- lib/sqlalchemy/engine/base.py | 28 +++++++++++++++++-- lib/sqlalchemy/sql.py | 1 + 3 files changed, 70 insertions(+), 4 deletions(-) diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 43dec46e3c..5a4865de05 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -4,6 +4,47 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php +"""defines the basic components used to interface DBAPI modules with +higher-level statement-construction, connection-management, +execution and result contexts. The primary "entry point" class into +this package is the Engine. + +The package is represented among several individual modules, including: + + base.py + Defines interface classes and some implementation classes + which comprise the basic components used to interface between + a DBAPI, constructed and plain-text statements, + connections, transactions, and results. + + default.py + Contains default implementations of some of the components + defined in base.py. All current database dialects use the + classes in default.py as base classes for their own database-specific + implementations. + + strategies.py + the mechanics of constructing ``Engine`` objects are represented here. + Defines the ``EngineStrategy`` class which represents how to go from + arguments specified to the ``create_engine()`` function, to a fully + constructed ``Engine``, including initialization of connection pooling, + dialects, and specific subclasses of ``Engine``. + + threadlocal.py + the ``TLEngine`` class is defined here, which is a subclass of the generic + ``Engine`` and tracks ``Connection`` and ``Transaction`` objects against + the identity of the current thread. This allows certain programming patterns + based around the concept of a "thread-local connection" to be possible. The + ``TLEngine`` is created by using the "threadlocal" engine strategy in + conjunction with the ``create_engine()`` function. + + url.py + Defines the ``URL`` class which represents the individual components of a + string URL passed to ``create_engine()``. Also defines a basic module-loading + strategy for the dialect specifier within a URL. + +""" + from sqlalchemy import databases from sqlalchemy.engine.base import * from sqlalchemy.engine import strategies @@ -45,10 +86,10 @@ def create_engine(*args, **kwargs): dialect and connection arguments, with additional keyword arguments sent as options to the dialect and resulting Engine. - The URL is in the form + The URL is a string in the form ``dialect://user:password@host/dbname[?key=value..]``, where ``dialect`` is a name such as ``mysql``, ``oracle``, ``postgres``, - etc. + etc. Alternatively, the URL can be an instance of ``sqlalchemy.engine.url.URL``. `**kwargs` represents options to be sent to the Engine itself as well as the components of the Engine, including the Dialect, the diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index e7a3f8feb1..b38e8faef6 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -1,3 +1,13 @@ +# engine/base.py +# Copyright (C) 2005, 2006, 2007 Michael Bayer mike_mp@zzzcomputing.com +# +# This module is part of SQLAlchemy and is released under +# the MIT License: http://www.opensource.org/licenses/mit-license.php + +"""defines the basic components used to interface DBAPI modules with +higher-level statement-construction, connection-management, +execution and result contexts.""" + from sqlalchemy import exceptions, sql, schema, util, types, logging import StringIO, sys, re @@ -1018,6 +1028,16 @@ class ResultProxy(object): self.close() class BufferedRowResultProxy(ResultProxy): + """``ResultProxy`` that buffers the contents of a selection of rows before + ``fetchone()`` is called. This is to allow the results of + ``cursor.description`` to be available immediately, when interfacing + with a DBAPI that requires rows to be consumed before this information is + available (currently psycopg2, when used with server-side cursors). + + The pre-fetching behavior fetches only one row initially, and then grows + its buffer size by a fixed amount with each successive need for additional + rows up to a size of 100. + """ def _init_metadata(self): self.__buffer_rows() super(BufferedRowResultProxy, self)._init_metadata() @@ -1062,9 +1082,13 @@ class BufferedRowResultProxy(ResultProxy): return self.__rowbuffer + list(self.cursor.fetchall()) class BufferedColumnResultProxy(ResultProxy): - """ResultProxy that loads all columns into memory each time fetchone() is + """``ResultProxy`` that loads all columns into memory each time fetchone() is called. If fetchmany() or fetchall() are called, the full grid of results - is fetched. + is fetched. This is to operate with databases where result rows contain "live" + results that fall out of scope unless explicitly fetched. Currently this includes + just cx_Oracle LOB objects, but this behavior is known to exist in other DBAPIs as + well (Pygresql, currently unsupported). + """ def _get_col(self, row, key): rec = self._convert_key(key) diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py index a8663ed4c3..c3d0f9de08 100644 --- a/lib/sqlalchemy/sql.py +++ b/lib/sqlalchemy/sql.py @@ -1,3 +1,4 @@ +# sql.py # Copyright (C) 2005, 2006, 2007 Michael Bayer mike_mp@zzzcomputing.com # # This module is part of SQLAlchemy and is released under -- 2.47.2