From: Mike Bayer Date: Mon, 13 Aug 2012 21:35:27 +0000 (-0400) Subject: - update engine docstrings due to move X-Git-Tag: rel_0_8_0b1~251^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8c7914e1818961e8d3acee33bea8e006b13993fa;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - update engine docstrings due to move - struggle with Operators class autodoc --- diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 7a88573a4c..a43585ba01 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -4,7 +4,7 @@ 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 @@ -114,7 +114,7 @@ Using Transactions 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()``:: @@ -248,7 +248,7 @@ Given a table as below:: ) 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 @@ -260,7 +260,7 @@ Explicit execution delivers the SQL text or constructed SQL expression to the 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 @@ -272,8 +272,8 @@ Explicit, connectionless execution delivers the expression to the 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`): @@ -287,9 +287,9 @@ object (binding is discussed further in 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. @@ -432,10 +432,10 @@ Connection / Engine API :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 diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index eb55472655..13750c3551 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -13,7 +13,7 @@ The general structure can be illustrated as follows: .. 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. @@ -352,7 +352,7 @@ application that has logging enabled otherwise. 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 @@ -364,7 +364,7 @@ configured **in addition** to any existing logger configurations. Therefore, **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`. diff --git a/doc/build/core/expression_api.rst b/doc/build/core/expression_api.rst index de9181252a..f2bcf2a0de 100644 --- a/doc/build/core/expression_api.rst +++ b/doc/build/core/expression_api.rst @@ -200,12 +200,9 @@ Classes :show-inheritance: .. autoclass:: sqlalchemy.sql.operators.Operators - :members: + :members: __and__, __or__, __invert__, op, operate, reverse_operate :undoc-members: - .. automethod:: __and__ - .. automethod:: __or__ - .. automethod:: __invert__ .. autoclass:: Select :members: diff --git a/doc/build/core/internals.rst b/doc/build/core/internals.rst index 5ea4aecead..3127127978 100644 --- a/doc/build/core/internals.rst +++ b/doc/build/core/internals.rst @@ -7,7 +7,7 @@ Some key internal constructs are listed here. .. currentmodule: sqlalchemy -.. autoclass:: sqlalchemy.engine.base.Compiled +.. autoclass:: sqlalchemy.engine.Compiled :members: :undoc-members: :show-inheritance: @@ -21,7 +21,7 @@ Some key internal constructs are listed here. :undoc-members: :show-inheritance: -.. autoclass:: sqlalchemy.engine.base.Dialect +.. autoclass:: sqlalchemy.engine.Dialect :members: :undoc-members: :show-inheritance: @@ -31,7 +31,7 @@ Some key internal constructs are listed here. :undoc-members: :show-inheritance: -.. autoclass:: sqlalchemy.engine.base.ExecutionContext +.. autoclass:: sqlalchemy.engine.ExecutionContext :members: :undoc-members: :show-inheritance: diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst index 2906a6fea3..394fa86003 100644 --- a/doc/build/core/pooling.rst +++ b/doc/build/core/pooling.rst @@ -24,7 +24,7 @@ plain DBAPI approach. 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! diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst index ccaa89d0a6..709366f2b0 100644 --- a/doc/build/core/schema.rst +++ b/doc/build/core/schema.rst @@ -281,8 +281,8 @@ Binding MetaData to an Engine or Connection 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 @@ -297,7 +297,7 @@ 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() @@ -328,7 +328,7 @@ specific need to arise. Bind is useful if: * 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 @@ -740,13 +740,13 @@ performance reasons. 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). diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index abb9ea520b..143f55df9a 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -236,9 +236,9 @@ we use the ``connect()`` method:: >>> conn = engine.connect() >>> conn #doctest: +ELLIPSIS - + -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: @@ -252,7 +252,7 @@ checked out DBAPI connection resource. Lets feed it our 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: @@ -264,9 +264,9 @@ 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: @@ -292,7 +292,7 @@ Our insert example above was intentionally a little drawn out to show some 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: @@ -304,7 +304,7 @@ and use it in the "normal" way: {opensql}INSERT INTO users (id, name, fullname) VALUES (?, ?, ?) (2, 'wendy', 'Wendy Williams') COMMIT - {stop} + {stop} Above, because we specified all three columns in the the ``execute()`` method, the compiled :class:`~sqlalchemy.sql.expression.Insert` included all three @@ -328,7 +328,7 @@ inserted, as we do here to add some email addresses: {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} + {stop} Above, we again relied upon SQLite's automatic generation of primary key identifiers for each ``addresses`` row. @@ -344,7 +344,7 @@ Connectionless / Implicit Execution ==================================== 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 @@ -359,11 +359,11 @@ of the operation: 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 @@ -409,10 +409,10 @@ Above, we issued a basic :func:`.select` call, placing the ``users`` table 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 @@ -464,7 +464,7 @@ But another way, whose usefulness will become apparent later on, is to use the 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: @@ -642,7 +642,7 @@ not all of them. MySQL users, fear not: 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 @@ -1460,7 +1460,7 @@ that can be specified: UPDATE users SET name=? WHERE users.name = ? ('ed', 'jack') COMMIT - {stop} + {stop} >>> # use bind parameters >>> u = users.update().\ @@ -1470,7 +1470,7 @@ that can be specified: UPDATE users SET name=? WHERE users.name = ? ('ed', 'jack') COMMIT - {stop} + {stop} >>> # with binds, you can also update many rows at once {sql}>>> conn.execute(u, @@ -1481,7 +1481,7 @@ that can be specified: UPDATE users SET name=? WHERE users.name = ? [('ed', 'jack'), ('mary', 'wendy'), ('jake', 'jim')] COMMIT - {stop} + {stop} >>> # update a column to an expression.: {sql}>>> conn.execute(users.update(). @@ -1490,7 +1490,7 @@ that can be specified: UPDATE users SET fullname=(? || users.name) ('Fullname: ',) COMMIT - {stop} + {stop} Correlated Updates ------------------ @@ -1508,7 +1508,7 @@ table, or the same table: LIMIT 1 OFFSET 0) () COMMIT - {stop} + {stop} Multiple Table Updates ---------------------- @@ -1571,13 +1571,13 @@ Finally, a delete. This is accomplished easily enough using the DELETE FROM addresses () COMMIT - {stop} + {stop} {sql}>>> conn.execute(users.delete().where(users.c.name > 'm')) #doctest: +ELLIPSIS DELETE FROM users WHERE users.name > ? ('m',) COMMIT - {stop} + {stop} Further Reference ================== diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index 47e17cbae0..eea46375c6 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -1404,9 +1404,9 @@ SQL expressions and strings can be executed via the :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() @@ -1417,15 +1417,15 @@ This is most easily accomplished using the # 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 diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index f63caffe19..59dcc77c00 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -319,7 +319,7 @@ objects:: >>> 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() diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index e572b49b0c..8a4360b341 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -30,7 +30,7 @@ psycopg2-specific keyword arguments which are accepted by ``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 diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 279c037ee8..eb9ef266bd 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -228,7 +228,7 @@ def create_engine(*args, **kwargs): :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 diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py index f991a4acd4..613d733019 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -82,8 +82,8 @@ class Inspector(object): :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` @@ -111,8 +111,8 @@ class Inspector(object): :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 diff --git a/lib/sqlalchemy/ext/horizontal_shard.py b/lib/sqlalchemy/ext/horizontal_shard.py index aa5bab2e22..f55cfae0a4 100644 --- a/lib/sqlalchemy/ext/horizontal_shard.py +++ b/lib/sqlalchemy/ext/horizontal_shard.py @@ -92,7 +92,7 @@ class ShardedSession(Session): 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. """ diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 53b42d051d..05f640ab08 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -1056,7 +1056,7 @@ class SessionEvents(event.Events): :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. """ diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 069de25972..bcc1a24548 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -1746,7 +1746,7 @@ class Mapper(_InspectionAttr): 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.