From: Mike Bayer Date: Thu, 9 Sep 2010 03:06:40 +0000 (-0400) Subject: doc edits X-Git-Tag: rel_0_6_5~79 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ce7768e3130ce1f83796c6090307e4591cbbfc45;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git doc edits --- diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 02c904f189..de81a6d730 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -13,13 +13,13 @@ The general structure can be illustrated as follows: .. image:: sqla_engine_arch.png -Where above, a :class:`~sqlalchemy.engine.base.Engine` references both a -:class:`~sqlalchemy.engine.base.Dialect` and :class:`~sqlalchemy.pool.Pool`, +Where above, an :class:`~sqlalchemy.engine.base.Engine` references both a +:class:`~sqlalchemy.engine.base.Dialect` and a :class:`~sqlalchemy.pool.Pool`, which together interpret the DBAPI's module functions as well as the behavior of the database. Creating an engine is just a matter of issuing a single call, -:func:`create_engine()`:: +:func:`.create_engine()`:: engine = create_engine('postgresql://scott:tiger@localhost:5432/mydatabase') @@ -146,7 +146,7 @@ Database Urls SQLAlchemy indicates the source of an Engine strictly via `RFC-1738 `_ style URLs, combined with optional keyword -arguments to specify options for the Engine. The form of the URL is: +arguments to specify options for the Engine. The form of the URL is:: dialect+driver://username:password@host:port/database @@ -277,22 +277,14 @@ namespace of SA loggers that can be turned on is as follows: * ``sqlalchemy.engine`` - controls SQL echoing. set to ``logging.INFO`` for SQL query output, ``logging.DEBUG`` for query + result set output. * ``sqlalchemy.dialects`` - controls custom logging for SQL dialects. See the documentation of individual dialects for details. * ``sqlalchemy.pool`` - controls connection pool logging. set to ``logging.INFO`` or lower to log connection pool checkouts/checkins. -* ``sqlalchemy.orm`` - controls logging of various ORM functions. set to ``logging.INFO`` for configurational logging as well as unit of work dumps, ``logging.DEBUG`` for extensive logging during query and flush() operations. Subcategories of ``sqlalchemy.orm`` include: - * ``sqlalchemy.orm.attributes`` - logs certain instrumented attribute operations, such as triggered callables - * ``sqlalchemy.orm.mapper`` - logs Mapper configuration and operations - * ``sqlalchemy.orm.unitofwork`` - logs flush() operations, including dependency sort graphs and other operations - * ``sqlalchemy.orm.strategies`` - logs relationship loader operations (i.e. lazy and eager loads) - * ``sqlalchemy.orm.sync`` - logs synchronization of attributes from parent to child instances during a flush() +* ``sqlalchemy.orm`` - controls logging of various ORM functions. set to ``logging.INFO`` for information on mapper configurations. -For example, to log SQL queries as well as unit of work debugging: - -.. sourcecode:: python+sql +For example, to log SQL queries using Python logging instead of the ``echo=True`` flag:: import logging logging.basicConfig() logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO) - logging.getLogger('sqlalchemy.orm.unitofwork').setLevel(logging.DEBUG) By default, the log level is set to ``logging.ERROR`` within the entire ``sqlalchemy`` namespace so that no log operations occur, even within an diff --git a/doc/build/core/types.rst b/doc/build/core/types.rst index 2205fa4819..89a84abc8d 100644 --- a/doc/build/core/types.rst +++ b/doc/build/core/types.rst @@ -1,4 +1,4 @@ -.. _types: +.. _types_toplevel: Column and Data Types ===================== diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index b4894250f5..43d3dd0381 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -132,12 +132,19 @@ def create_engine(*args, **kwargs): additional keyword arguments. :param convert_unicode=False: if set to True, all - String/character based types will convert Unicode values to raw - byte values going into the database, and all raw byte values to + String/character based types will convert Python Unicode values to raw + byte values sent to the DBAPI as bind parameters, and all raw byte values to Python Unicode coming out in result sets. This is an - engine-wide method to provide unicode conversion across the - board. For unicode conversion on a column-by-column level, use - the ``Unicode`` column type instead, described in `types`. + engine-wide method to provide Unicode conversion across the + board for those DBAPIs that do not accept Python Unicode objects + as input. For Unicode conversion on a column-by-column level, use + the ``Unicode`` column type instead, described in :ref:`types_toplevel`. Note that + many DBAPIs have the ability to return Python Unicode objects in + result sets directly - SQLAlchemy will use these modes of operation + if possible and will also attempt to detect "Unicode returns" + behavior by the DBAPI upon first connect by the + :class:`.Engine`. When this is detected, string values in + result sets are passed through without further processing. :param creator: a callable which returns a DBAPI connection. This creation function will be passed to the underlying @@ -188,10 +195,13 @@ def create_engine(*args, **kwargs): opened above and beyond the pool_size setting, which defaults to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`. - :param module=None: used by database implementations which - support multiple DBAPI modules, this is a reference to a DBAPI2 - module to be used instead of the engine's default module. For - PostgreSQL, the default is psycopg2. For Oracle, it's cx_Oracle. + :param module=None: reference to a Python module object (the module itself, not + its string name). Specifies an alternate DBAPI module to be used + by the engine's dialect. Each sub-dialect references a specific DBAPI which + will be imported before first connect. This parameter causes the + import to be bypassed, and the given module to be used instead. + Can be used for testing of DBAPIs as well as to inject "mock" + DBAPI implementations into the :class:`.Engine`. :param pool=None: an already-constructed instance of :class:`~sqlalchemy.pool.Pool`, such as a @@ -199,7 +209,7 @@ def create_engine(*args, **kwargs): pool will be used directly as the underlying connection pool for the engine, bypassing whatever connection parameters are present in the URL argument. For information on constructing - connection pools manually, see `pooling`. + connection pools manually, see :ref:`pooling_toplevel`. :param poolclass=None: a :class:`~sqlalchemy.pool.Pool` subclass, which will be used to create a connection pool @@ -224,7 +234,7 @@ def create_engine(*args, **kwargs): connections after the given number of seconds has passed. It defaults to -1, or no timeout. For example, setting to 3600 means connections will be recycled after one hour. Note that - MySQL in particular will ``disconnect automatically`` if no + MySQL in particular will disconnect automatically if no activity is detected on a connection for eight hours (although this is configurable with the MySQLDB connection itself and the server configuration as well). @@ -233,8 +243,8 @@ def create_engine(*args, **kwargs): up on getting a connection from the pool. This is only used with :class:`~sqlalchemy.pool.QueuePool`. - :param strategy='plain': used to invoke alternate :class:`~sqlalchemy.engine.base.Engine.` - implementations. Currently available is the ``threadlocal`` + :param strategy='plain': selects alternate engine implementations. + Currently available is the ``threadlocal`` strategy, which is described in :ref:`threadlocal_strategy`. """