Commits

Mike Bayer  committed 208a6ed Merge

merge tip.

  • Participants
  • Parent commits 5d73fc4, f2e0c7b

Comments (0)

Files changed (15)

File doc/build/core/connections.rst

 Working with Engines and Connections
 =====================================
 
-.. module:: sqlalchemy.engine.base
+.. module:: sqlalchemy.engine
 
 This section details direct usage of the :class:`.Engine`,
 :class:`.Connection`, and related objects. Its important to note that when
   object internally. See :ref:`unitofwork_transaction` for further
   information.
 
-The :class:`~sqlalchemy.engine.base.Connection` object provides a ``begin()``
+The :class:`~sqlalchemy.engine.Connection` object provides a ``begin()``
 method which returns a :class:`~sqlalchemy.engine.base.Transaction` object.
 This object is usually used within a try/except clause so that it is
 guaranteed to ``rollback()`` or ``commit()``::
     )
 
 Explicit execution delivers the SQL text or constructed SQL expression to the
-``execute()`` method of :class:`~sqlalchemy.engine.base.Connection`:
+``execute()`` method of :class:`~sqlalchemy.engine.Connection`:
 
 .. sourcecode:: python+sql
 
     connection.close()
 
 Explicit, connectionless execution delivers the expression to the
-``execute()`` method of :class:`~sqlalchemy.engine.base.Engine`:
+``execute()`` method of :class:`~sqlalchemy.engine.Engine`:
 
 .. sourcecode:: python+sql
 
 
 Implicit execution is also connectionless, and calls the ``execute()`` method
 on the expression itself, utilizing the fact that either an
-:class:`~sqlalchemy.engine.base.Engine` or
-:class:`~sqlalchemy.engine.base.Connection` has been *bound* to the expression
+:class:`~sqlalchemy.engine.Engine` or
+:class:`~sqlalchemy.engine.Connection` has been *bound* to the expression
 object (binding is discussed further in
 :ref:`metadata_toplevel`):
 
     result.close()
 
 In both "connectionless" examples, the
-:class:`~sqlalchemy.engine.base.Connection` is created behind the scenes; the
-:class:`~sqlalchemy.engine.base.ResultProxy` returned by the ``execute()``
-call references the :class:`~sqlalchemy.engine.base.Connection` used to issue
+:class:`~sqlalchemy.engine.Connection` is created behind the scenes; the
+:class:`~sqlalchemy.engine.ResultProxy` returned by the ``execute()``
+call references the :class:`~sqlalchemy.engine.Connection` used to issue
 the SQL statement. When the :class:`.ResultProxy` is closed, the underlying
 :class:`.Connection` is closed for us, resulting in the
 DBAPI connection being returned to the pool with transactional resources removed.
     :show-inheritance:
     :members:
 
-.. autoclass:: sqlalchemy.engine.base.ResultProxy
+.. autoclass:: sqlalchemy.engine.ResultProxy
     :members:
 
-.. autoclass:: sqlalchemy.engine.base.RowProxy
+.. autoclass:: sqlalchemy.engine.RowProxy
     :members:
 
 .. autoclass:: Transaction

File doc/build/core/engines.rst

 
 .. image:: sqla_engine_arch.png
 
-Where above, an :class:`~sqlalchemy.engine.base.Engine` references both a
+Where above, an :class:`~sqlalchemy.engine.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.
 
 The ``echo`` flags present as keyword arguments to
 :func:`~sqlalchemy.create_engine` and others as well as the ``echo`` property
-on :class:`~sqlalchemy.engine.base.Engine`, when set to ``True``, will first
+on :class:`~sqlalchemy.engine.Engine`, when set to ``True``, will first
 attempt to ensure that logging is enabled. Unfortunately, the ``logging``
 module provides no way of determining if output has already been configured
 (note we are referring to if a logging configuration has been set up, not just
 **when using Python logging, ensure all echo flags are set to False at all
 times**, to avoid getting duplicate log lines.
 
-The logger name of instance such as an :class:`~sqlalchemy.engine.base.Engine`
+The logger name of instance such as an :class:`~sqlalchemy.engine.Engine`
 or :class:`~sqlalchemy.pool.Pool` defaults to using a truncated hex identifier
 string. To set this to a specific name, use the "logging_name" and
 "pool_logging_name" keyword arguments with :func:`sqlalchemy.create_engine`.

File doc/build/core/expression_api.rst

    :members:
    :special-members:
 
-
 .. autoclass:: Select
    :members:
    :show-inheritance:

File doc/build/core/internals.rst

 
 .. currentmodule: sqlalchemy
 
-.. autoclass:: sqlalchemy.engine.base.Compiled
+.. autoclass:: sqlalchemy.engine.Compiled
     :members:
     :undoc-members:
     :show-inheritance:
     :undoc-members:
     :show-inheritance:
 
-.. autoclass:: sqlalchemy.engine.base.Dialect
+.. autoclass:: sqlalchemy.engine.Dialect
     :members:
     :undoc-members:
     :show-inheritance:
     :undoc-members:
     :show-inheritance:
 
-.. autoclass:: sqlalchemy.engine.base.ExecutionContext
+.. autoclass:: sqlalchemy.engine.ExecutionContext
     :members:
     :undoc-members:
     :show-inheritance:

File doc/build/core/pooling.rst

 Connection Pool Configuration
 -----------------------------
 
-The :class:`~.engine.base.Engine` returned by the
+The :class:`~.engine.Engine` returned by the
 :func:`~sqlalchemy.create_engine` function in most cases has a :class:`.QueuePool`
 integrated, pre-configured with reasonable pooling defaults.  If
 you're reading this section only to learn how to enable pooling - congratulations!

File doc/build/core/schema.rst

 
 Notice in the previous section the creator/dropper methods accept an argument
 for the database engine in use. When a schema construct is combined with an
-:class:`~sqlalchemy.engine.base.Engine` object, or an individual
-:class:`~sqlalchemy.engine.base.Connection` object, we call this the *bind*.
+:class:`~sqlalchemy.engine.Engine` object, or an individual
+:class:`~sqlalchemy.engine.Connection` object, we call this the *bind*.
 In the above examples the bind is associated with the schema construct only
 for the duration of the operation. However, the option exists to persistently
 associate a bind with a set of schema constructs via the
     meta.bind = engine
 
 We can now call methods like :func:`~sqlalchemy.schema.MetaData.create_all`
-without needing to pass the :class:`~sqlalchemy.engine.base.Engine`::
+without needing to pass the :class:`~sqlalchemy.engine.Engine`::
 
     meta.create_all()
 
 
 * You aren't using the ORM, are usually using "connectionless" execution, and
   find yourself constantly needing to specify the same
-  :class:`~sqlalchemy.engine.base.Engine` object throughout the entire
+  :class:`~sqlalchemy.engine.Engine` object throughout the entire
   application. Bind can be used here to provide "implicit" execution.
 * Your application has multiple schemas that correspond to different engines.
   Using one :class:`~sqlalchemy.schema.MetaData` for each schema, bound to
 
 When the statement is executed with a single set of parameters (that is, it is
 not an "executemany" style execution), the returned
-:class:`~sqlalchemy.engine.base.ResultProxy` will contain a collection
+:class:`~sqlalchemy.engine.ResultProxy` will contain a collection
 accessible via ``result.postfetch_cols()`` which contains a list of all
 :class:`~sqlalchemy.schema.Column` objects which had an inline-executed
 default. Similarly, all parameters which were bound to the statement,
 including all Python and SQL expressions which were pre-executed, are present
 in the ``last_inserted_params()`` or ``last_updated_params()`` collections on
-:class:`~sqlalchemy.engine.base.ResultProxy`. The ``inserted_primary_key``
+:class:`~sqlalchemy.engine.ResultProxy`. The ``inserted_primary_key``
 collection contains a list of primary key values for the row inserted (a list
 so that single-column and composite-column primary keys are represented in the
 same format).

File doc/build/core/tutorial.rst

 
     >>> conn = engine.connect()
     >>> conn #doctest: +ELLIPSIS
-    <sqlalchemy.engine.base.Connection object at 0x...>
+    <sqlalchemy.engine.Connection object at 0x...>
 
-The :class:`~sqlalchemy.engine.base.Connection` object represents an actively
+The :class:`~sqlalchemy.engine.Connection` object represents an actively
 checked out DBAPI connection resource. Lets feed it our
 :class:`~sqlalchemy.sql.expression.Insert` object and see what happens:
 
 So the INSERT statement was now issued to the database. Although we got
 positional "qmark" bind parameters instead of "named" bind parameters in the
 output. How come ? Because when executed, the
-:class:`~sqlalchemy.engine.base.Connection` used the SQLite **dialect** to
+:class:`~sqlalchemy.engine.Connection` used the SQLite **dialect** to
 help generate the statement; when we use the ``str()`` function, the statement
 isn't aware of this dialect, and falls back onto a default which uses named
 parameters. We can view this manually as follows:
     'INSERT INTO users (name, fullname) VALUES (?, ?)'
 
 What about the ``result`` variable we got when we called ``execute()`` ? As
-the SQLAlchemy :class:`~sqlalchemy.engine.base.Connection` object references a
+the SQLAlchemy :class:`~sqlalchemy.engine.Connection` object references a
 DBAPI connection, the result, known as a
-:class:`~sqlalchemy.engine.base.ResultProxy` object, is analogous to the DBAPI
+:class:`~sqlalchemy.engine.ResultProxy` object, is analogous to the DBAPI
 cursor object. In the case of an INSERT, we can get important information from
 it, such as the primary key values which were generated from our statement:
 
 various behaviors of expression language constructs. In the usual case, an
 :class:`~sqlalchemy.sql.expression.Insert` statement is usually compiled
 against the parameters sent to the ``execute()`` method on
-:class:`~sqlalchemy.engine.base.Connection`, so that there's no need to use
+:class:`~sqlalchemy.engine.Connection`, so that there's no need to use
 the ``values`` keyword with :class:`~sqlalchemy.sql.expression.Insert`. Lets
 create a generic :class:`~sqlalchemy.sql.expression.Insert` statement again
 and use it in the "normal" way:
     {opensql}INSERT INTO users (id, name, fullname) VALUES (?, ?, ?)
     (2, 'wendy', 'Wendy Williams')
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
 Above, because we specified all three columns in the the ``execute()`` method,
 the compiled :class:`~sqlalchemy.sql.expression.Insert` included all three
     {opensql}INSERT INTO addresses (user_id, email_address) VALUES (?, ?)
     ((1, 'jack@yahoo.com'), (1, 'jack@msn.com'), (2, 'www@www.org'), (2, 'wendy@aol.com'))
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
 Above, we again relied upon SQLite's automatic generation of primary key
 identifiers for each ``addresses`` row.
 ====================================
 
 We're executing our :class:`~sqlalchemy.sql.expression.Insert` using a
-:class:`~sqlalchemy.engine.base.Connection`. There's two options that allow
+:class:`~sqlalchemy.engine.Connection`. There's two options that allow
 you to not have to deal with the connection part. You can execute in the
 **connectionless** style, using the engine, which checks out from the
 connection pool a connection for you, performs the execute operation with that
     COMMIT
 
 and you can save even more steps than that, if you connect the
-:class:`~sqlalchemy.engine.base.Engine` to the
+:class:`~sqlalchemy.engine.Engine` to the
 :class:`~sqlalchemy.schema.MetaData` object we created earlier. When this is
 done, all SQL expressions which involve tables within the
 :class:`~sqlalchemy.schema.MetaData` object will be automatically **bound** to
-the :class:`~sqlalchemy.engine.base.Engine`. In this case, we call it
+the :class:`~sqlalchemy.engine.Engine`. In this case, we call it
 **implicit execution**:
 
 .. sourcecode:: pycon+sql
 within the COLUMNS clause of the select, and then executing. SQLAlchemy
 expanded the ``users`` table into the set of each of its columns, and also
 generated a FROM clause for us. The result returned is again a
-:class:`~sqlalchemy.engine.base.ResultProxy` object, which acts much like a
+:class:`~sqlalchemy.engine.ResultProxy` object, which acts much like a
 DBAPI cursor, including methods such as
-:func:`~sqlalchemy.engine.base.ResultProxy.fetchone` and
-:func:`~sqlalchemy.engine.base.ResultProxy.fetchall`. The easiest way to get
+:func:`~sqlalchemy.engine.ResultProxy.fetchone` and
+:func:`~sqlalchemy.engine.ResultProxy.fetchall`. The easiest way to get
 rows from it is to just iterate:
 
 .. sourcecode:: pycon+sql
 
 Result sets which have pending rows remaining should be explicitly closed
 before discarding. While the cursor and connection resources referenced by the
-:class:`~sqlalchemy.engine.base.ResultProxy` will be respectively closed and
+:class:`~sqlalchemy.engine.ResultProxy` will be respectively closed and
 returned to the connection pool when the object is garbage collected, it's
 better to make it explicit as some database APIs are very picky about such
 things:
     concat(users.name, users.fullname)
 
 The above illustrates the SQL that's generated for an
-:class:`~sqlalchemy.engine.base.Engine` that's connected to a MySQL database;
+:class:`~sqlalchemy.engine.Engine` that's connected to a MySQL database;
 the ``||`` operator now compiles as MySQL's ``concat()`` function.
 
 If you have come across an operator which really isn't available, you can
     UPDATE users SET name=? WHERE users.name = ?
     ('ed', 'jack')
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
     >>> # use bind parameters
     >>> u = users.update().\
     UPDATE users SET name=? WHERE users.name = ?
     ('ed', 'jack')
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
     >>> # with binds, you can also update many rows at once
     {sql}>>> conn.execute(u,
     UPDATE users SET name=? WHERE users.name = ?
     [('ed', 'jack'), ('mary', 'wendy'), ('jake', 'jim')]
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
     >>> # update a column to an expression.:
     {sql}>>> conn.execute(users.update().
     UPDATE users SET fullname=(? || users.name)
     ('Fullname: ',)
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
 Correlated Updates
 ------------------
     LIMIT 1 OFFSET 0)
     ()
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
 Multiple Table Updates
 ----------------------
     DELETE FROM addresses
     ()
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
     {sql}>>> conn.execute(users.delete().where(users.c.name > 'm')) #doctest: +ELLIPSIS
     DELETE FROM users WHERE users.name > ?
     ('m',)
     COMMIT
-    {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+    {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
 
 Further Reference
 ==================

File doc/build/orm/session.rst

 :class:`~sqlalchemy.orm.session.Session` within its transactional context.
 This is most easily accomplished using the
 :func:`~sqlalchemy.orm.session.Session.execute` method, which returns a
-:class:`~sqlalchemy.engine.base.ResultProxy` in the same manner as an
-:class:`~sqlalchemy.engine.base.Engine` or
-:class:`~sqlalchemy.engine.base.Connection`::
+:class:`~sqlalchemy.engine.ResultProxy` in the same manner as an
+:class:`~sqlalchemy.engine.Engine` or
+:class:`~sqlalchemy.engine.Connection`::
 
     Session = sessionmaker(bind=engine)
     session = Session()
     # execute a SQL expression construct
     result = session.execute(select([mytable]).where(mytable.c.id==7))
 
-The current :class:`~sqlalchemy.engine.base.Connection` held by the
+The current :class:`~sqlalchemy.engine.Connection` held by the
 :class:`~sqlalchemy.orm.session.Session` is accessible using the
 :func:`~sqlalchemy.orm.session.Session.connection` method::
 
     connection = session.connection()
 
 The examples above deal with a :class:`~sqlalchemy.orm.session.Session` that's
-bound to a single :class:`~sqlalchemy.engine.base.Engine` or
-:class:`~sqlalchemy.engine.base.Connection`. To execute statements using a
+bound to a single :class:`~sqlalchemy.engine.Engine` or
+:class:`~sqlalchemy.engine.Connection`. To execute statements using a
 :class:`~sqlalchemy.orm.session.Session` which is bound either to multiple
 engines, or none at all (i.e. relies upon bound metadata), both
 :func:`~sqlalchemy.orm.session.Session.execute` and

File doc/build/orm/tutorial.rst

     >>> Session = sessionmaker(bind=engine)
 
 In the case where your application does not yet have an
-:class:`~sqlalchemy.engine.base.Engine` when you define your module-level
+:class:`~sqlalchemy.engine.Engine` when you define your module-level
 objects, just set it up like this::
 
     >>> Session = sessionmaker()

File lib/sqlalchemy/dialects/postgresql/psycopg2.py

   ``connection.cursor('some name')``, which has the effect that result rows are
   not immediately pre-fetched and buffered after statement execution, but are
   instead left on the server and only retrieved as needed. SQLAlchemy's
-  :class:`~sqlalchemy.engine.base.ResultProxy` uses special row-buffering
+  :class:`~sqlalchemy.engine.ResultProxy` uses special row-buffering
   behavior when this feature is enabled, such that groups of 100 rows at a
   time are fetched over the wire to reduce conversational overhead.
   Note that the ``stream_results=True`` execution option is a more targeted

File lib/sqlalchemy/engine/__init__.py

 
     :param execution_options: Dictionary execution options which will
         be applied to all connections.  See
-        :meth:`~sqlalchemy.engine.base.Connection.execution_options`
+        :meth:`~sqlalchemy.engine.Connection.execution_options`
 
     :param implicit_returning=True: When ``True``, a RETURNING-
         compatible construct, if available, will be used to

File lib/sqlalchemy/engine/reflection.py

 
         :param bind: a :class:`~sqlalchemy.engine.base.Connectable`,
           which is typically an instance of
-          :class:`~sqlalchemy.engine.base.Engine` or
-          :class:`~sqlalchemy.engine.base.Connection`.
+          :class:`~sqlalchemy.engine.Engine` or
+          :class:`~sqlalchemy.engine.Connection`.
 
         For a dialect-specific instance of :class:`.Inspector`, see
         :meth:`Inspector.from_engine`
 
         :param bind: a :class:`~sqlalchemy.engine.base.Connectable`,
           which is typically an instance of
-          :class:`~sqlalchemy.engine.base.Engine` or
-          :class:`~sqlalchemy.engine.base.Connection`.
+          :class:`~sqlalchemy.engine.Engine` or
+          :class:`~sqlalchemy.engine.Connection`.
 
         This method differs from direct a direct constructor call of :class:`.Inspector`
         in that the :class:`~sqlalchemy.engine.base.Dialect` is given a chance to provide

File lib/sqlalchemy/ext/horizontal_shard.py

           should be issued.  Results from all shards returned will be combined
           together into a single listing.
 
-        :param shards: A dictionary of string shard names to :class:`~sqlalchemy.engine.base.Engine`
+        :param shards: A dictionary of string shard names to :class:`~sqlalchemy.engine.Engine`
           objects.
 
         """

File lib/sqlalchemy/orm/events.py

 
         :param session: The target :class:`.Session`.
         :param transaction: The :class:`.SessionTransaction`.
-        :param connection: The :class:`~.engine.base.Connection` object
+        :param connection: The :class:`~.engine.Connection` object
          which will be used for SQL statements.
 
         """

File lib/sqlalchemy/orm/mapper.py

         item from the identity map.
 
         row
-          A ``sqlalchemy.engine.base.RowProxy`` instance or a
+          A ``sqlalchemy.engine.RowProxy`` instance or a
           dictionary corresponding result-set ``ColumnElement``
           instances to their values within a row.