diff options
Diffstat (limited to 'lib/sqlalchemy')
34 files changed, 248 insertions, 189 deletions
diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py index b5c49246f..b0021e873 100644 --- a/lib/sqlalchemy/dialects/mssql/base.py +++ b/lib/sqlalchemy/dialects/mssql/base.py @@ -171,7 +171,8 @@ The process for fetching this value has several variants: * Other dialects such as pymssql will call upon ``SELECT scope_identity() AS lastrowid`` subsequent to an INSERT statement. If the flag ``use_scope_identity=False`` is passed to - :func:`.create_engine`, the statement ``SELECT @@identity AS lastrowid`` + :func:`_sa.create_engine`, + the statement ``SELECT @@identity AS lastrowid`` is used instead. A table that contains an ``IDENTITY`` column will prohibit an INSERT statement @@ -293,8 +294,8 @@ Transaction Isolation Level All SQL Server dialects support setting of transaction isolation level both via a dialect-specific parameter -:paramref:`.create_engine.isolation_level` -accepted by :func:`.create_engine`, +:paramref:`_sa.create_engine.isolation_level` +accepted by :func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. @@ -302,7 +303,7 @@ This feature works by issuing the command ``SET TRANSACTION ISOLATION LEVEL <level>`` for each new connection. -To set isolation level using :func:`.create_engine`:: +To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "mssql+pyodbc://scott:tiger@ms_2008", @@ -394,7 +395,7 @@ behavior of this flag is as follows: or ``False`` based on whether 2012 or greater is detected. * The flag can be set to either ``True`` or ``False`` when the dialect - is created, typically via :func:`.create_engine`:: + is created, typically via :func:`_sa.create_engine`:: eng = create_engine("mssql+pymssql://user:pass@host/db", deprecate_large_types=True) @@ -497,7 +498,7 @@ below:: This mode of behavior is now off by default, as it appears to have served no purpose; however in the case that legacy applications rely upon it, it is available using the ``legacy_schema_aliasing`` argument to -:func:`.create_engine` as illustrated above. +:func:`_sa.create_engine` as illustrated above. .. versionchanged:: 1.1 the ``legacy_schema_aliasing`` flag introduced in version 1.0.5 to allow disabling of legacy mode for schemas now @@ -638,7 +639,7 @@ Declarative form:: This option can also be specified engine-wide using the -``implicit_returning=False`` argument on :func:`.create_engine`. +``implicit_returning=False`` argument on :func:`_sa.create_engine`. .. _mssql_rowcount_versioning: diff --git a/lib/sqlalchemy/dialects/mssql/pyodbc.py b/lib/sqlalchemy/dialects/mssql/pyodbc.py index ffaf66fdd..5cb92ef07 100644 --- a/lib/sqlalchemy/dialects/mssql/pyodbc.py +++ b/lib/sqlalchemy/dialects/mssql/pyodbc.py @@ -103,7 +103,8 @@ Microsoft ODBC drivers. The feature is enabled by setting the flag ``.fast_executemany`` on the DBAPI cursor when an executemany call is to be used. The SQLAlchemy pyodbc SQL Server dialect supports setting this flag automatically when the ``.fast_executemany`` flag is passed to -:func:`.create_engine`; note that the ODBC driver must be the Microsoft driver +:func:`_sa.create_engine` +; note that the ODBC driver must be the Microsoft driver in order to use this flag:: engine = create_engine( diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index e44dfa829..c7c3bd433 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -29,7 +29,7 @@ Connection Timeouts and Disconnects MySQL features an automatic connection close behavior, for connections that have been idle for a fixed period of time, defaulting to eight hours. To circumvent having this issue, use -the :paramref:`.create_engine.pool_recycle` option which ensures that +the :paramref:`_sa.create_engine.pool_recycle` option which ensures that a connection will be discarded and replaced with a new one if it has been present in the pool for a fixed number of seconds:: @@ -120,8 +120,9 @@ Transaction Isolation Level --------------------------- All MySQL dialects support setting of transaction isolation level both via a -dialect-specific parameter :paramref:`.create_engine.isolation_level` accepted -by :func:`.create_engine`, as well as the +dialect-specific parameter :paramref:`_sa.create_engine.isolation_level` +accepted +by :func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. This feature works by issuing the @@ -129,7 +130,7 @@ command ``SET SESSION TRANSACTION ISOLATION LEVEL <level>`` for each new connection. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used. -To set isolation level using :func:`.create_engine`:: +To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "mysql://scott:tiger@localhost/test", @@ -198,7 +199,7 @@ will receive results. The most typical way of invoking this feature is via the :paramref:`.Connection.execution_options.stream_results` connection execution option. Server side cursors can also be enabled for all SELECT statements unconditionally by passing ``server_side_cursors=True`` to -:func:`.create_engine`. +:func:`_sa.create_engine`. .. versionadded:: 1.1.4 - added server-side cursor support. @@ -468,7 +469,7 @@ This setting is currently hardcoded. .. seealso:: - :attr:`.ResultProxy.rowcount` + :attr:`_engine.ResultProxy.rowcount` CAST Support diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py index bbf65371c..50fa71d7e 100644 --- a/lib/sqlalchemy/dialects/oracle/base.py +++ b/lib/sqlalchemy/dialects/oracle/base.py @@ -125,7 +125,7 @@ As of SQLAlchemy 1.4, the default max identifier length for the Oracle dialect is 128 characters. Upon first connect, the compatibility version is detected and if it is less than Oracle version 12.2, the max identifier length is changed to be 30 characters. In all cases, setting the -:paramref:`.create_engine.max_identifier_length` parameter will bypass this +:paramref:`_sa.create_engine.max_identifier_length` parameter will bypass this change and the value given will be used as is:: engine = create_engine( @@ -183,7 +183,8 @@ database migration that wishes to "DROP CONSTRAINT" on a name that was previously generated with the shorter length. This migration will fail when the identifier length is changed without the name of the index or constraint first being adjusted. Such applications are strongly advised to make use of -:paramref:`.create_engine.max_identifier_length` in order to maintain control +:paramref:`_sa.create_engine.max_identifier_length` +in order to maintain control of the generation of truncated names, and to fully review and test all database migrations in a staging environment when changing this value to ensure that the impact of this change has been mitigated. @@ -206,7 +207,7 @@ There is currently a single option to affect its behavior: * the "FIRST_ROWS()" optimization keyword is not used by default. To enable the usage of this optimization directive, specify ``optimize_limits=True`` - to :func:`.create_engine`. + to :func:`_sa.create_engine`. .. versionchanged:: 1.4 The Oracle dialect renders limit/offset integer values using a "post @@ -242,7 +243,7 @@ on the Oracle backend. By default, "implicit returning" typically only fetches the value of a single ``nextval(some_seq)`` expression embedded into an INSERT in order to increment a sequence within an INSERT statement and get the value back at the same time. To disable this feature across the board, -specify ``implicit_returning=False`` to :func:`.create_engine`:: +specify ``implicit_returning=False`` to :func:`_sa.create_engine`:: engine = create_engine("oracle://scott:tiger@dsn", implicit_returning=False) diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index 2cbf5b04a..b555c4555 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -33,7 +33,7 @@ If ``dbname`` is not present, then the value of ``hostname`` in the URL is used directly as the DSN passed to ``cx_Oracle.connect()``. Additional connection arguments may be sent to the ``cx_Oracle.connect()`` -function using the :paramref:`.create_engine.connect_args` dictionary. +function using the :paramref:`_sa.create_engine.connect_args` dictionary. Any cx_Oracle parameter value and/or constant may be passed, such as:: import cx_Oracle @@ -55,11 +55,12 @@ within the URL, which includes parameters such as ``mode``, ``purity``, .. versionchanged:: 1.3 the cx_oracle dialect now accepts all argument names within the URL string itself, to be passed to the cx_Oracle DBAPI. As was the case earlier but not correctly documented, the - :paramref:`.create_engine.connect_args` parameter also accepts all + :paramref:`_sa.create_engine.connect_args` parameter also accepts all cx_Oracle DBAPI connect arguments. There are also options that are consumed by the SQLAlchemy cx_oracle dialect -itself. These options are always passed directly to :func:`.create_engine`, +itself. These options are always passed directly to :func:`_sa.create_engine` +, such as:: e = create_engine( @@ -99,14 +100,15 @@ the VARCHAR2 and CLOB datatypes can accommodate the data. In the case that the Oracle database is not configured with a Unicode character set, the two options are to use the :class:`_oracle.NCHAR` and :class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag -``use_nchar_for_unicode=True`` to :func:`.create_engine`, which will cause the +``use_nchar_for_unicode=True`` to :func:`_sa.create_engine`, +which will cause the SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` / :class:`.UnicodeText` datatypes instead of VARCHAR/CLOB. .. versionchanged:: 1.3 The :class:`.Unicode` and :class:`.UnicodeText` datatypes now correspond to the ``VARCHAR2`` and ``CLOB`` Oracle datatypes unless the ``use_nchar_for_unicode=True`` is passed to the dialect - when :func:`.create_engine` is called. + when :func:`_sa.create_engine` is called. When result sets are fetched that include strings, under Python 3 the cx_Oracle DBAPI returns all strings as Python Unicode objects, since Python 3 only has a @@ -118,7 +120,7 @@ made use of converters that were supplied by cx_Oracle but were found to be non-performant; SQLAlchemy's own converters are used for the string to Unicode conversion under Python 2. To disable the Python 2 Unicode conversion for VARCHAR2, CHAR, and CLOB, the flag ``coerce_to_unicode=False`` can be passed to -:func:`.create_engine`. +:func:`_sa.create_engine`. .. versionchanged:: 1.3 Unicode conversion is applied to all string values by default under python 2. The ``coerce_to_unicode`` now defaults to True @@ -235,7 +237,7 @@ As of the 6 series, this limitation has been lifted. Nevertheless, because SQLAlchemy pre-reads these LOBs up front, this issue is avoided in any case. To disable the auto "read()" feature of the dialect, the flag -``auto_convert_lobs=False`` may be passed to :func:`.create_engine`. Under +``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`. Under the cx_Oracle 5 series, having this flag turned off means there is the chance of reading from a stale LOB object if not read as it is fetched. With cx_Oracle 6, this issue is resolved. @@ -281,7 +283,7 @@ When no typing objects are present, as when executing plain SQL strings, a default "outputtypehandler" is present which will generally return numeric values which specify precision and scale as Python ``Decimal`` objects. To disable this coercion to decimal for performance reasons, pass the flag -``coerce_to_decimal=False`` to :func:`.create_engine`:: +``coerce_to_decimal=False`` to :func:`_sa.create_engine`:: engine = create_engine("oracle+cx_oracle://dsn", coerce_to_decimal=False) @@ -756,7 +758,7 @@ class OracleDialect_cx_oracle(OracleDialect): "in a future release. As of version 1.3, it defaults to False " "rather than True. The 'threaded' option can be passed to " "cx_Oracle directly in the URL query string passed to " - ":func:`.create_engine`.", + ":func:`_sa.create_engine`.", ) ) def __init__( diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index 670de4ebf..f9b3d9b95 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -41,7 +41,7 @@ apply; no RETURNING clause is emitted nor is the sequence pre-executed in this case. To force the usage of RETURNING by default off, specify the flag -``implicit_returning=False`` to :func:`.create_engine`. +``implicit_returning=False`` to :func:`_sa.create_engine`. PostgreSQL 10 IDENTITY columns ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -84,7 +84,8 @@ Transaction Isolation Level All PostgreSQL dialects support setting of transaction isolation level both via a dialect-specific parameter -:paramref:`.create_engine.isolation_level` accepted by :func:`.create_engine`, +:paramref:`_sa.create_engine.isolation_level` accepted by +:func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. When using a non-psycopg2 dialect, this feature works by issuing the command @@ -92,7 +93,7 @@ When using a non-psycopg2 dialect, this feature works by issuing the command each new connection. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used. -To set isolation level using :func:`.create_engine`:: +To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "postgresql+pg8000://scott:tiger@localhost/test", diff --git a/lib/sqlalchemy/dialects/postgresql/json.py b/lib/sqlalchemy/dialects/postgresql/json.py index 811159953..953ad9993 100644 --- a/lib/sqlalchemy/dialects/postgresql/json.py +++ b/lib/sqlalchemy/dialects/postgresql/json.py @@ -154,7 +154,7 @@ class JSON(sqltypes.JSON): may be called upon the result type. Custom serializers and deserializers are specified at the dialect level, - that is using :func:`.create_engine`. The reason for this is that when + that is using :func:`_sa.create_engine`. The reason for this is that when using psycopg2, the DBAPI only allows serializers at the per-cursor or per-connection level. E.g.:: @@ -274,7 +274,7 @@ class JSONB(JSON): are shared with the :class:`_types.JSON` class, using the ``json_serializer`` and ``json_deserializer`` keyword arguments. These must be specified - at the dialect level using :func:`.create_engine`. When using + at the dialect level using :func:`_sa.create_engine`. When using psycopg2, the serializers are associated with the jsonb type using ``psycopg2.extras.register_default_jsonb`` on a per-connection basis, in the same way that ``psycopg2.extras.register_default_json`` is used diff --git a/lib/sqlalchemy/dialects/postgresql/pg8000.py b/lib/sqlalchemy/dialects/postgresql/pg8000.py index b6e838738..197d11cf4 100644 --- a/lib/sqlalchemy/dialects/postgresql/pg8000.py +++ b/lib/sqlalchemy/dialects/postgresql/pg8000.py @@ -36,7 +36,7 @@ The ``client_encoding`` can be overridden for a session by executing the SQL: SET CLIENT_ENCODING TO 'utf8'; SQLAlchemy will execute this SQL on all new connections based on the value -passed to :func:`.create_engine` using the ``client_encoding`` parameter:: +passed to :func:`_sa.create_engine` using the ``client_encoding`` parameter:: engine = create_engine( "postgresql+pg8000://user:pass@host/dbname", client_encoding='utf8') diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index 6d2672bbe..769fbb06a 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -15,7 +15,7 @@ psycopg2 Connect Arguments ----------------------------------- psycopg2-specific keyword arguments which are accepted by -:func:`.create_engine()` are: +:func:`_sa.create_engine()` are: * ``server_side_cursors``: Enable the usage of "server side cursors" for SQL statements which support this feature. What this essentially means from a @@ -161,7 +161,7 @@ when used with :ref:`multiple parameter sets <execute_multiple>`, which includes the use of this feature both by the Core as well as by the ORM for inserts of objects with non-autogenerated primary key values, by adding the ``executemany_mode`` flag to -:func:`.create_engine`:: +:func:`_sa.create_engine`:: engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", @@ -251,7 +251,7 @@ A second way to affect the client encoding is to set it within Psycopg2 locally. SQLAlchemy will call psycopg2's :meth:`psycopg2:connection.set_client_encoding` method on all new connections based on the value passed to -:func:`.create_engine` using the ``client_encoding`` parameter:: +:func:`_sa.create_engine` using the ``client_encoding`` parameter:: # set_client_encoding() setting; # works for *all* PostgreSQL versions @@ -263,11 +263,12 @@ When using the parameter in this way, the psycopg2 driver emits ``SET client_encoding TO 'utf8'`` on the connection explicitly, and works in all PostgreSQL versions. -Note that the ``client_encoding`` setting as passed to :func:`.create_engine` +Note that the ``client_encoding`` setting as passed to +:func:`_sa.create_engine` is **not the same** as the more recently added ``client_encoding`` parameter now supported by libpq directly. This is enabled when ``client_encoding`` is passed directly to ``psycopg2.connect()``, and from SQLAlchemy is passed -using the :paramref:`.create_engine.connect_args` parameter:: +using the :paramref:`_sa.create_engine.connect_args` parameter:: engine = create_engine( "postgresql://user:pass@host/dbname", @@ -288,10 +289,11 @@ SQLAlchemy can also be instructed to skip the usage of the psycopg2 ``UNICODE`` extension and to instead utilize its own unicode encode/decode services, which are normally reserved only for those DBAPIs that don't fully support unicode directly. Passing ``use_native_unicode=False`` to -:func:`.create_engine` will disable usage of ``psycopg2.extensions.UNICODE``. +:func:`_sa.create_engine` will disable usage of ``psycopg2.extensions. +UNICODE``. SQLAlchemy will instead encode data itself into Python bytestrings on the way in and coerce from bytes on the way back, -using the value of the :func:`.create_engine` ``encoding`` parameter, which +using the value of the :func:`_sa.create_engine` ``encoding`` parameter, which defaults to ``utf-8``. SQLAlchemy's own unicode encode/decode functionality is steadily becoming obsolete as most DBAPIs now support unicode fully. @@ -329,7 +331,7 @@ from the ``size_meters`` key as well. The other solution is to use a positional format; psycopg2 allows use of the "format" paramstyle, which can be passed to -:paramref:`.create_engine.paramstyle`:: +:paramref:`_sa.create_engine.paramstyle`:: engine = create_engine( 'postgresql://scott:tiger@localhost:5432/test', paramstyle='format') @@ -360,7 +362,8 @@ Psycopg2 Transaction Isolation Level As discussed in :ref:`postgresql_isolation_level`, all PostgreSQL dialects support setting of transaction isolation level -both via the ``isolation_level`` parameter passed to :func:`.create_engine`, +both via the ``isolation_level`` parameter passed to :func:`_sa.create_engine` +, as well as the ``isolation_level`` argument used by :meth:`_engine.Connection.execution_options`. When using the psycopg2 dialect , these diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index 1e265a9eb..dbc8c5e7f 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -179,7 +179,8 @@ default mode of ``SERIALIZABLE`` isolation, and a "dirty read" isolation mode normally referred to as ``READ UNCOMMITTED``. SQLAlchemy ties into this PRAGMA statement using the -:paramref:`.create_engine.isolation_level` parameter of :func:`.create_engine`. +:paramref:`_sa.create_engine.isolation_level` parameter of +:func:`_sa.create_engine`. Valid values for this parameter when used with SQLite are ``"SERIALIZABLE"`` and ``"READ UNCOMMITTED"`` corresponding to a value of 0 and 1, respectively. SQLite defaults to ``SERIALIZABLE``, however its behavior is impacted by @@ -557,9 +558,9 @@ names are still addressable*:: 1 Therefore, the workaround applied by SQLAlchemy only impacts -:meth:`.ResultProxy.keys` and :meth:`.Row.keys()` in the public API. In +:meth:`_engine.ResultProxy.keys` and :meth:`.Row.keys()` in the public API. In the very specific case where an application is forced to use column names that -contain dots, and the functionality of :meth:`.ResultProxy.keys` and +contain dots, and the functionality of :meth:`_engine.ResultProxy.keys` and :meth:`.Row.keys()` is required to return these dotted names unmodified, the ``sqlite_raw_colnames`` execution option may be provided, either on a per-:class:`_engine.Connection` basis:: diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py b/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py index a1243f271..213cc55f2 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py @@ -69,7 +69,8 @@ dialect here defaults to using the :class:`.SingletonThreadPool` implementation, instead of the :class:`.NullPool` pool used by pysqlite. As always, the pool implementation is entirely configurable using the -:paramref:`.create_engine.poolclass` parameter; the :class:`.StaticPool` may +:paramref:`_sa.create_engine.poolclass` parameter; the :class:`. +StaticPool` may be more feasible for single-threaded use, or :class:`.NullPool` may be used to prevent unencrypted connections from being held open for long periods of time, at the expense of slower startup time for new connections. diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py index 307114c03..8da2a0323 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py @@ -72,7 +72,8 @@ as the "database" portion of the SQLAlchemy url (that is, following a slash):: .. note:: The "uri=true" parameter must appear in the **query string** of the URL. It will not currently work as expected if it is only - present in the :paramref:`.create_engine.connect_args` parameter dictionary. + present in the :paramref:`_sa.create_engine.connect_args` + parameter dictionary. The logic reconciles the simultaneous presence of SQLAlchemy's query string and SQLite's query string by separating out the parameters that belong to the @@ -99,15 +100,17 @@ Regarding future parameters added to either the Python or native drivers. new parameter names added to the SQLite URI scheme should be automatically accommodated by this scheme. New parameter names added to the Python driver side can be accommodated by specifying them in the -:paramref:`.create_engine.connect_args` dictionary, until dialect support is +:paramref:`_sa.create_engine.connect_args` dictionary, +until dialect support is added by SQLAlchemy. For the less likely case that the native SQLite driver adds a new parameter name that overlaps with one of the existing, known Python driver parameters (such as "timeout" perhaps), SQLAlchemy's dialect would require adjustment for the URL scheme to continue to support this. As is always the case for all SQLAlchemy dialects, the entire "URL" process -can be bypassed in :func:`.create_engine` through the use of the -:paramref:`.create_engine.creator` parameter which allows for a custom callable +can be bypassed in :func:`_sa.create_engine` through the use of the +:paramref:`_sa.create_engine.creator` +parameter which allows for a custom callable that creates a Python sqlite3 driver level connection directly. .. versionadded:: 1.3.9 @@ -326,7 +329,7 @@ ourselves. This is achieved using two event listeners:: .. warning:: When using the above recipe, it is advised to not use the :paramref:`.Connection.execution_options.isolation_level` setting on - :class:`_engine.Connection` and :func:`.create_engine` + :class:`_engine.Connection` and :func:`_sa.create_engine` with the SQLite driver, as this function necessarily will also alter the ".isolation_level" setting. diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 014d433a7..8a340d9ce 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -247,8 +247,8 @@ class Connection(Connectable): Set the transaction isolation level for the lifespan of this :class:`_engine.Connection` object. Valid values include those string - values accepted by the :paramref:`.create_engine.isolation_level` - parameter passed to :func:`.create_engine`. These levels are + values accepted by the :paramref:`_sa.create_engine.isolation_level` + parameter passed to :func:`_sa.create_engine`. These levels are semi-database specific; see individual dialect documentation for valid levels. @@ -282,7 +282,7 @@ class Connection(Connectable): .. seealso:: - :paramref:`.create_engine.isolation_level` + :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :meth:`_engine.Connection.get_isolation_level` @@ -420,7 +420,7 @@ class Connection(Connectable): :attr:`_engine.Connection.default_isolation_level` - view default level - :paramref:`.create_engine.isolation_level` + :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` @@ -456,7 +456,7 @@ class Connection(Connectable): :meth:`_engine.Connection.get_isolation_level` - view current level - :paramref:`.create_engine.isolation_level` + :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` @@ -950,7 +950,7 @@ class Connection(Connectable): def execute(self, object_, *multiparams, **params): r"""Executes a SQL statement construct and returns a - :class:`.ResultProxy`. + :class:`_engine.ResultProxy`. :param object: The statement to be executed. May be one of: @@ -1219,7 +1219,7 @@ class Connection(Connectable): def exec_driver_sql(self, statement, parameters=None): r"""Executes a SQL statement construct and returns a - :class:`.ResultProxy`. + :class:`_engine.ResultProxy`. :param statement: The statement str to be executed. Bound parameters must use the underlying DBAPI's paramstyle, such as "qmark", @@ -1272,7 +1272,7 @@ class Connection(Connectable): self, dialect, constructor, statement, parameters, *args ): """Create an :class:`.ExecutionContext` and execute, returning - a :class:`.ResultProxy`.""" + a :class:`_engine.ResultProxy`.""" try: try: @@ -2027,7 +2027,7 @@ class Engine(Connectable, log.Identified): default execution options that will be used for all connections. The initial contents of this dictionary can be sent via the ``execution_options`` parameter - to :func:`.create_engine`. + to :func:`_sa.create_engine`. .. seealso:: @@ -2224,10 +2224,10 @@ class Engine(Connectable, log.Identified): that the :class:`_engine.Connection` will be closed when the operation is complete. When set to ``True``, it indicates the :class:`_engine.Connection` is in "single use" mode, where the - :class:`.ResultProxy` returned by the first call to + :class:`_engine.ResultProxy` returned by the first call to :meth:`_engine.Connection.execute` will close the :class:`_engine.Connection` when - that :class:`.ResultProxy` has exhausted all result rows. + that :class:`_engine.ResultProxy` has exhausted all result rows. .. seealso:: @@ -2335,15 +2335,17 @@ class Engine(Connectable, log.Identified): ":class:`.Session`.", ) def execute(self, statement, *multiparams, **params): - """Executes the given construct and returns a :class:`.ResultProxy`. + """Executes the given construct and returns a + :class:`_engine.ResultProxy`. The arguments are the same as those used by :meth:`_engine.Connection.execute`. Here, a :class:`_engine.Connection` is acquired using the :meth:`_engine.Engine.connect` method, and the statement executed - with that connection. The returned :class:`.ResultProxy` is flagged - such that when the :class:`.ResultProxy` is exhausted and its + with that connection. The returned :class:`_engine.ResultProxy` + is flagged + such that when the :class:`_engine.ResultProxy` is exhausted and its underlying cursor is closed, the :class:`_engine.Connection` created here will also be closed, which allows its associated DBAPI connection @@ -2359,7 +2361,8 @@ class Engine(Connectable, log.Identified): "by the :meth:`_engine.Connection.execute` method of " ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " - ":class:`.Session`; the :meth:`.Result.scalar` method can then be " + ":class:`.Session`; the :meth:`_future.Result.scalar` " + "method can then be " "used to return a scalar result.", ) def scalar(self, statement, *multiparams, **params): diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index 3c1345c63..e5b8a87d3 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -19,7 +19,7 @@ from ..sql import compiler @util.deprecated_params( strategy=( "1.4", - "The :paramref:`.create_engine.strategy` keyword is deprecated, " + "The :paramref:`_sa.create_engine.strategy` keyword is deprecated, " "and the only argument accepted is 'mock'; please use " ":func:`.create_mock_engine` going forward. For general " "customization of create_engine which may have been accomplished " @@ -27,7 +27,7 @@ from ..sql import compiler ), empty_in_strategy=( "1.4", - "The :paramref:`.create_engine.empty_in_strategy` keyword is " + "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is " "deprecated, and no longer has any effect. All IN expressions " "are now rendered using " 'the "expanding parameter" strategy which renders a set of bound' @@ -36,7 +36,7 @@ from ..sql import compiler ), case_sensitive=( "1.4", - "The :paramref:`.create_engine.case_sensitive` parameter " + "The :paramref:`_sa.create_engine.case_sensitive` parameter " "is deprecated and will be removed in a future release. " "Applications should work with result column names in a case " "sensitive fashion.", @@ -73,7 +73,7 @@ def create_engine(url, **kwargs): as well as the :class:`_pool.Pool`. Specific dialects also accept keyword arguments that are unique to that dialect. Here, we describe the parameters - that are common to most :func:`.create_engine()` usage. + that are common to most :func:`_sa.create_engine()` usage. Once established, the newly resulting :class:`_engine.Engine` will request a connection from the underlying :class:`_pool.Pool` once @@ -81,7 +81,7 @@ def create_engine(url, **kwargs): such as :meth:`_engine.Engine.execute` is invoked. The :class:`_pool.Pool` in turn will establish the first actual DBAPI connection when this request - is received. The :func:`.create_engine` call itself does **not** + is received. The :func:`_sa.create_engine` call itself does **not** establish any actual DBAPI connections directly. .. seealso:: @@ -111,7 +111,7 @@ def create_engine(url, **kwargs): .. deprecated:: 1.3 - The :paramref:`.create_engine.convert_unicode` parameter + The :paramref:`_sa.create_engine.convert_unicode` parameter is deprecated and will be removed in a future release. All modern DBAPIs now support Python Unicode directly and this parameter is unnecessary. @@ -277,14 +277,15 @@ def create_engine(url, **kwargs): characters. If less than 6, labels are generated as "_(counter)". If ``None``, the value of ``dialect.max_identifier_length``, which may be affected via the - :paramref:`.create_engine.max_identifier_length` parameter, - is used instead. The value of :paramref:`.create_engine.label_length` + :paramref:`_sa.create_engine.max_identifier_length` parameter, + is used instead. The value of + :paramref:`_sa.create_engine.label_length` may not be larger than that of - :paramref:`.create_engine.max_identfier_length`. + :paramref:`_sa.create_engine.max_identfier_length`. .. seealso:: - :paramref:`.create_engine.max_identifier_length` + :paramref:`_sa.create_engine.max_identifier_length` :param listeners: A list of one or more :class:`~sqlalchemy.interfaces.PoolListener` objects which will @@ -308,7 +309,7 @@ def create_engine(url, **kwargs): .. seealso:: - :paramref:`.create_engine.label_length` + :paramref:`_sa.create_engine.label_length` :param max_overflow=10: the number of connections to allow in connection pool "overflow", that is connections that can be @@ -602,7 +603,7 @@ def engine_from_config(configuration, prefix="sqlalchemy.", **kwargs): ``sqlalchemy.url``, ``sqlalchemy.echo``, etc. The 'prefix' argument indicates the prefix to be searched for. Each matching key (after the prefix is stripped) is treated as though it were the corresponding keyword - argument to a :func:`.create_engine` call. + argument to a :func:`_sa.create_engine` call. The only required key is (assuming the default prefix) ``sqlalchemy.url``, which provides the :ref:`database URL <database_urls>`. @@ -614,7 +615,7 @@ def engine_from_config(configuration, prefix="sqlalchemy.", **kwargs): :param configuration: A dictionary (typically produced from a config file, but this is not a requirement). Items whose keys start with the value of 'prefix' will have that prefix stripped, and will then be passed to - :func:`.create_engine`. + :func:`_sa.create_engine`. :param prefix: Prefix to match and then strip from keys in 'configuration'. diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py index 5b8cb635c..5ec13d103 100644 --- a/lib/sqlalchemy/engine/default.py +++ b/lib/sqlalchemy/engine/default.py @@ -190,14 +190,14 @@ class DefaultDialect(interfaces.Dialect): @util.deprecated_params( convert_unicode=( "1.3", - "The :paramref:`.create_engine.convert_unicode` parameter " + "The :paramref:`_sa.create_engine.convert_unicode` parameter " "and corresponding dialect-level parameters are deprecated, " "and will be removed in a future release. Modern DBAPIs support " "Python Unicode natively and this parameter is unnecessary.", ), empty_in_strategy=( "1.4", - "The :paramref:`.create_engine.empty_in_strategy` keyword is " + "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is " "deprecated, and no longer has any effect. All IN expressions " "are now rendered using " 'the "expanding parameter" strategy which renders a set of bound' @@ -206,7 +206,7 @@ class DefaultDialect(interfaces.Dialect): ), case_sensitive=( "1.4", - "The :paramref:`.create_engine.case_sensitive` parameter " + "The :paramref:`_sa.create_engine.case_sensitive` parameter " "is deprecated and will be removed in a future release. " "Applications should work with result column names in a case " "sensitive fashion.", diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index 46459cf73..65b73002c 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -61,7 +61,7 @@ class ConnectionEvents(event.Events): statement = statement + " -- some comment" return statement, parameters - .. note:: :class:`.ConnectionEvents` can be established on any + .. note:: :class:`_events.ConnectionEvents` can be established on any combination of :class:`_engine.Engine`, :class:`_engine.Connection`, as well as instances of each of those classes. Events across all @@ -183,7 +183,8 @@ class ConnectionEvents(event.Events): :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. - :param result: :class:`.ResultProxy` generated by the execution. + :param result: :class:`_engine.ResultProxy` generated by the execution + . """ @@ -208,7 +209,7 @@ class ConnectionEvents(event.Events): # do something with statement, parameters return statement, parameters - See the example at :class:`.ConnectionEvents`. + See the example at :class:`_events.ConnectionEvents`. :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object @@ -237,7 +238,7 @@ class ConnectionEvents(event.Events): :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed - as they will be needed by the :class:`.ResultProxy`. + as they will be needed by the :class:`_engine.ResultProxy`. :param statement: string SQL statement, as passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the @@ -317,7 +318,8 @@ class ConnectionEvents(event.Events): "failed" in str(context.original_exception): raise MySpecialException("failed operation") - .. warning:: Because the :meth:`.ConnectionEvents.handle_error` + .. warning:: Because the + :meth:`_events.ConnectionEvents.handle_error` event specifically provides for exceptions to be re-thrown as the ultimate exception raised by the failed statement, **stack traces will be misleading** if the user-defined event @@ -358,7 +360,7 @@ class ConnectionEvents(event.Events): class for details on all available members. .. versionadded:: 0.9.7 Added the - :meth:`.ConnectionEvents.handle_error` hook. + :meth:`_events.ConnectionEvents.handle_error` hook. .. versionchanged:: 1.1 The :meth:`.handle_error` event will now receive all exceptions that inherit from ``BaseException``, @@ -429,7 +431,7 @@ class ConnectionEvents(event.Events): .. seealso:: :ref:`pool_disconnects_pessimistic` - illustrates how to use - :meth:`.ConnectionEvents.engine_connect` + :meth:`_events.ConnectionEvents.engine_connect` to transparently ensure pooled connections are connected to the database. @@ -437,7 +439,8 @@ class ConnectionEvents(event.Events): the lower-level pool checkout event for an individual DBAPI connection - :meth:`.ConnectionEvents.set_connection_execution_options` - a copy + :meth:`_events.ConnectionEvents.set_connection_execution_options` + - a copy of a :class:`_engine.Connection` is also made when the :meth:`_engine.Connection.execution_options` method is called. @@ -456,7 +459,7 @@ class ConnectionEvents(event.Events): :class:`_engine.Connection` is produced which is inheriting execution options from its parent :class:`_engine.Engine`; to intercept this condition, use the - :meth:`.ConnectionEvents.engine_connect` event. + :meth:`_events.ConnectionEvents.engine_connect` event. :param conn: The newly copied :class:`_engine.Connection` object @@ -467,7 +470,8 @@ class ConnectionEvents(event.Events): .. seealso:: - :meth:`.ConnectionEvents.set_engine_execution_options` - event + :meth:`_events.ConnectionEvents.set_engine_execution_options` + - event which is called when :meth:`_engine.Engine.execution_options` is called. @@ -483,7 +487,8 @@ class ConnectionEvents(event.Events): That new :class:`_engine.Engine` is passed here. A particular application of this - method is to add a :meth:`.ConnectionEvents.engine_connect` event + method is to add a :meth:`_events.ConnectionEvents.engine_connect` + event handler to the given :class:`_engine.Engine` which will perform some per- :class:`_engine.Connection` task specific to these execution options. @@ -497,7 +502,8 @@ class ConnectionEvents(event.Events): .. seealso:: - :meth:`.ConnectionEvents.set_connection_execution_options` - event + :meth:`_events.ConnectionEvents.set_connection_execution_options` + - event which is called when :meth:`_engine.Connection.execution_options` is called. @@ -636,17 +642,17 @@ class DialectEvents(event.Events): These hooks are not for general use and are only for those situations where intricate re-statement of DBAPI mechanics must be injected onto an existing dialect. For general-use statement-interception events, - please use the :class:`.ConnectionEvents` interface. + please use the :class:`_events.ConnectionEvents` interface. .. seealso:: - :meth:`.ConnectionEvents.before_cursor_execute` + :meth:`_events.ConnectionEvents.before_cursor_execute` - :meth:`.ConnectionEvents.before_execute` + :meth:`_events.ConnectionEvents.before_execute` - :meth:`.ConnectionEvents.after_cursor_execute` + :meth:`_events.ConnectionEvents.after_cursor_execute` - :meth:`.ConnectionEvents.after_execute` + :meth:`_events.ConnectionEvents.after_execute` .. versionadded:: 0.9.4 diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 224d4f693..e07877475 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -780,7 +780,7 @@ class Dialect(object): :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level - :paramref:`.create_engine.isolation_level` - + :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level """ @@ -807,7 +807,7 @@ class Dialect(object): :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level - :paramref:`.create_engine.isolation_level` - + :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level """ @@ -839,7 +839,7 @@ class Dialect(object): :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level - :paramref:`.create_engine.isolation_level` - + :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level @@ -945,14 +945,14 @@ class CreateEnginePlugin(object): "mysql+pymysql://scott:tiger@localhost/test?plugin=myplugin") Alternatively, the :paramref:`.create_engine.plugins" argument may be - passed as a list to :func:`.create_engine`:: + passed as a list to :func:`_sa.create_engine`:: engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test", plugins=["myplugin"]) .. versionadded:: 1.2.3 plugin names can also be specified - to :func:`.create_engine` as a list + to :func:`_sa.create_engine` as a list The ``plugin`` argument supports multiple instances, so that a URL may specify multiple plugins; they are loaded in the order stated @@ -963,7 +963,7 @@ class CreateEnginePlugin(object): "test?plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three") A plugin can receive additional arguments from the URL string as - well as from the keyword arguments passed to :func:`.create_engine`. + well as from the keyword arguments passed to :func:`_sa.create_engine`. The :class:`.URL` object and the keyword dictionary are passed to the constructor so that these arguments can be extracted from the url's :attr:`.URL.query` collection as well as from the dictionary:: @@ -1004,7 +1004,8 @@ class CreateEnginePlugin(object): """Construct a new :class:`.CreateEnginePlugin`. The plugin object is instantiated individually for each call - to :func:`.create_engine`. A single :class:`_engine.Engine` will be + to :func:`_sa.create_engine`. A single :class:`_engine. + Engine` will be passed to the :meth:`.CreateEnginePlugin.engine_created` method corresponding to this URL. @@ -1249,7 +1250,7 @@ class ExecutionContext(object): """Return the DBAPI ``cursor.rowcount`` value, or in some cases an interpreted value. - See :attr:`.ResultProxy.rowcount` for details on this. + See :attr:`_engine.ResultProxy.rowcount` for details on this. """ @@ -1296,7 +1297,8 @@ class Connectable(object): """ def execute(self, object_, *multiparams, **params): - """Executes the given construct and returns a :class:`.ResultProxy`.""" + """Executes the given construct and returns a """ + """:class:`_engine.ResultProxy`.""" raise NotImplementedError() def scalar(self, object_, *multiparams, **params): @@ -1317,7 +1319,8 @@ class ExceptionContext(object): """Encapsulate information about an error condition in progress. This object exists solely to be passed to the - :meth:`.ConnectionEvents.handle_error` event, supporting an interface that + :meth:`_events.ConnectionEvents.handle_error` event, + supporting an interface that can be extended without backwards-incompatibility. .. versionadded:: 0.9.7 @@ -1409,7 +1412,7 @@ class ExceptionContext(object): :attr:`.ExceptionContext.parameters` members may represent a different value than that of the :class:`.ExecutionContext`, potentially in the case where a - :meth:`.ConnectionEvents.before_cursor_execute` event or similar + :meth:`_events.ConnectionEvents.before_cursor_execute` event or similar modified the statement/parameters to be sent. May be None. @@ -1421,7 +1424,7 @@ class ExceptionContext(object): condition. This flag will always be True or False within the scope of the - :meth:`.ConnectionEvents.handle_error` handler. + :meth:`_events.ConnectionEvents.handle_error` handler. SQLAlchemy will defer to this flag in order to determine whether or not the connection should be invalidated subsequently. That is, by @@ -1436,7 +1439,8 @@ class ExceptionContext(object): when a "disconnect" condition is in effect. Setting this flag to False within the scope of the - :meth:`.ConnectionEvents.handle_error` event will have the effect such + :meth:`_events.ConnectionEvents.handle_error` + event will have the effect such that the full collection of connections in the pool will not be invalidated during a disconnect; only the current connection that is the subject of the error will actually be invalidated. diff --git a/lib/sqlalchemy/engine/mock.py b/lib/sqlalchemy/engine/mock.py index 19a3b8e6c..d6a542e19 100644 --- a/lib/sqlalchemy/engine/mock.py +++ b/lib/sqlalchemy/engine/mock.py @@ -92,7 +92,8 @@ def create_mock_engine(url, executor, **kw): string using :meth:`.DDLElement.compile`. .. versionadded:: 1.4 - the :func:`.create_mock_engine` function replaces - the previous "mock" engine strategy used with :func:`.create_engine`. + the previous "mock" engine strategy used with :func:`_sa.create_engine` + . .. seealso:: diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index 6944e0c67..e1e5e9016 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -1112,8 +1112,8 @@ class BaseResult(object): :class:`.BaseResult` is the base class for the 1.x style - :class:`.ResultProxy` class as well as the 2.x style - :class:`.future.Result` class. + :class:`_engine.ResultProxy` class as well as the 2.x style + :class:`_future.Result` class. """ @@ -1201,7 +1201,7 @@ class BaseResult(object): return has_key(key) def _soft_close(self, hard=False): - """Soft close this :class:`.ResultProxy`. + """Soft close this :class:`_engine.ResultProxy`. This releases all DBAPI cursor resources, but leaves the ResultProxy "open" from a semantic perspective, meaning the @@ -1219,7 +1219,7 @@ class BaseResult(object): .. seealso:: - :meth:`.ResultProxy.close` + :meth:`_engine.ResultProxy.close` """ @@ -1404,7 +1404,7 @@ class BaseResult(object): def supports_sane_rowcount(self): """Return ``supports_sane_rowcount`` from the dialect. - See :attr:`.ResultProxy.rowcount` for background. + See :attr:`_engine.ResultProxy.rowcount` for background. """ @@ -1413,7 +1413,7 @@ class BaseResult(object): def supports_sane_multi_rowcount(self): """Return ``supports_sane_multi_rowcount`` from the dialect. - See :attr:`.ResultProxy.rowcount` for background. + See :attr:`_engine.ResultProxy.rowcount` for background. """ @@ -1428,7 +1428,7 @@ class BaseResult(object): .. note:: - Notes regarding :attr:`.ResultProxy.rowcount`: + Notes regarding :attr:`_engine.ResultProxy.rowcount`: * This attribute returns the number of rows *matched*, @@ -1441,18 +1441,20 @@ class BaseResult(object): rowcount is configured by default to return the match count in all cases. - * :attr:`.ResultProxy.rowcount` is *only* useful in conjunction + * :attr:`_engine.ResultProxy.rowcount` + is *only* useful in conjunction with an UPDATE or DELETE statement. Contrary to what the Python DBAPI says, it does *not* return the number of rows available from the results of a SELECT statement as DBAPIs cannot support this functionality when rows are unbuffered. - * :attr:`.ResultProxy.rowcount` may not be fully implemented by + * :attr:`_engine.ResultProxy.rowcount` + may not be fully implemented by all dialects. In particular, most DBAPIs do not support an aggregate rowcount result from an executemany call. - The :meth:`.ResultProxy.supports_sane_rowcount` and - :meth:`.ResultProxy.supports_sane_multi_rowcount` methods + The :meth:`_engine.ResultProxy.supports_sane_rowcount` and + :meth:`_engine.ResultProxy.supports_sane_multi_rowcount` methods will report from the dialect if each usage is known to be supported. @@ -1492,19 +1494,19 @@ class BaseResult(object): @property def returns_rows(self): - """True if this :class:`.ResultProxy` returns rows. + """True if this :class:`_engine.ResultProxy` returns rows. I.e. if it is legal to call the methods - :meth:`~.ResultProxy.fetchone`, - :meth:`~.ResultProxy.fetchmany` - :meth:`~.ResultProxy.fetchall`. + :meth:`_engine.ResultProxy.fetchone`, + :meth:`_engine.ResultProxy.fetchmany` + :meth:`_engine.ResultProxy.fetchall`. """ return self._metadata is not None @property def is_insert(self): - """True if this :class:`.ResultProxy` is the result + """True if this :class:`_engine.ResultProxy` is the result of a executing an expression language compiled :func:`_expression.insert` construct. @@ -1524,7 +1526,8 @@ class ResultProxy(BaseResult): additional API features and behaviors on top of the raw data returned by the DBAPI. - Within the scope of the 1.x series of SQLAlchemy, the :class:`.ResultProxy` + Within the scope of the 1.x series of SQLAlchemy, the + :class:`_engine.ResultProxy` will in fact return instances of the :class:`.LegacyRow` class, which maintains Python mapping (i.e. dictionary) like behaviors upon the object itself. Going forward, the :attr:`.Row._mapping` attribute should be used @@ -1533,7 +1536,7 @@ class ResultProxy(BaseResult): .. seealso:: :ref:`coretutorial_selecting` - introductory material for accessing - :class:`.ResultProxy` and :class:`.Row` objects. + :class:`_engine.ResultProxy` and :class:`.Row` objects. """ @@ -1553,14 +1556,17 @@ class ResultProxy(BaseResult): yield row def close(self): - """Close this :class:`.ResultProxy`. + """Close this :class:`_engine.ResultProxy`. This closes out the underlying DBAPI cursor corresponding to the statement execution, if one is still present. Note that the - DBAPI cursor is automatically released when the :class:`.ResultProxy` - exhausts all available rows. :meth:`.ResultProxy.close` is generally + DBAPI cursor is automatically released when the + :class:`_engine.ResultProxy` + exhausts all available rows. :meth:`_engine.ResultProxy.close` + is generally an optional method except in the case when discarding a - :class:`.ResultProxy` that still has additional rows pending for fetch. + :class:`_engine.ResultProxy` + that still has additional rows pending for fetch. In the case of a result that is the product of :ref:`connectionless execution <dbengine_implicit>`, @@ -1570,7 +1576,8 @@ class ResultProxy(BaseResult): .. deprecated:: 2.0 "connectionless" execution is deprecated and will be removed in version 2.0. Version 2.0 will feature the - :class:`.future.Result` object that will no longer affect the status + :class:`_future.Result` + object that will no longer affect the status of the originating connection in any case. After this method is called, it is no longer valid to call upon @@ -1636,8 +1643,8 @@ class ResultProxy(BaseResult): cursor resource is released, and the object may be safely discarded. - Subsequent calls to :meth:`.ResultProxy.fetchall` will return - an empty list. After the :meth:`.ResultProxy.close` method is + Subsequent calls to :meth:`_engine.ResultProxy.fetchall` will return + an empty list. After the :meth:`_engine.ResultProxy.close` method is called, the method will raise :class:`.ResourceClosedError`. :return: a list of :class:`.Row` objects @@ -1661,9 +1668,10 @@ class ResultProxy(BaseResult): cursor resource is released, and the object may be safely discarded. - Calls to :meth:`.ResultProxy.fetchmany` after all rows have been + Calls to :meth:`_engine.ResultProxy.fetchmany` + after all rows have been exhausted will return - an empty list. After the :meth:`.ResultProxy.close` method is + an empty list. After the :meth:`_engine.ResultProxy.close` method is called, the method will raise :class:`.ResourceClosedError`. :return: a list of :class:`.Row` objects @@ -1690,9 +1698,9 @@ class ResultProxy(BaseResult): cursor resource is released, and the object may be safely discarded. - Calls to :meth:`.ResultProxy.fetchone` after all rows have + Calls to :meth:`_engine.ResultProxy.fetchone` after all rows have been exhausted will return ``None``. - After the :meth:`.ResultProxy.close` method is + After the :meth:`_engine.ResultProxy.close` method is called, the method will raise :class:`.ResourceClosedError`. :return: a :class:`.Row` object, or None if no rows remain @@ -1714,7 +1722,8 @@ class ResultProxy(BaseResult): """Fetch the first row and then close the result set unconditionally. After calling this method, the object is fully closed, - e.g. the :meth:`.ResultProxy.close` method will have been called. + e.g. the :meth:`_engine.ResultProxy.close` + method will have been called. :return: a :class:`.Row` object, or None if no rows remain @@ -1738,7 +1747,8 @@ class ResultProxy(BaseResult): """Fetch the first column of the first row, and close the result set. After calling this method, the object is fully closed, - e.g. the :meth:`.ResultProxy.close` method will have been called. + e.g. the :meth:`_engine.ResultProxy.close` + method will have been called. :return: a Python scalar value , or None if no rows remain diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py index b58b350e2..68e32057d 100644 --- a/lib/sqlalchemy/engine/row.py +++ b/lib/sqlalchemy/engine/row.py @@ -127,7 +127,7 @@ class Row(BaseRow, collections_abc.Sequence): The :class:`.Row` object represents a row of a database result. It is typically associated in the 1.x series of SQLAlchemy with the - :class:`.ResultProxy` object, however is also used by the ORM for + :class:`_engine.ResultProxy` object, however is also used by the ORM for tuple-like results as of SQLAlchemy 1.4. The :class:`.Row` object seeks to act as much like a Python named @@ -150,7 +150,8 @@ class Row(BaseRow, collections_abc.Sequence): and now acts mostly like a named tuple. Mapping-like functionality is moved to the :attr:`.Row._mapping` attribute, but will remain available in SQLAlchemy 1.x series via the :class:`.LegacyRow` class that is used - by :class:`.ResultProxy`. See :ref:`change_4710_core` for background + by :class:`_engine.ResultProxy`. + See :ref:`change_4710_core` for background on this change. """ diff --git a/lib/sqlalchemy/ext/baked.py b/lib/sqlalchemy/ext/baked.py index 839aae730..e5e31c1f9 100644 --- a/lib/sqlalchemy/ext/baked.py +++ b/lib/sqlalchemy/ext/baked.py @@ -112,7 +112,8 @@ class BakedQuery(object): return self def with_criteria(self, fn, *args): - """Add a criteria function to a :class:`.BakedQuery` cloned from this one. + """Add a criteria function to a :class:`.BakedQuery` cloned from this + one. This is equivalent to using the ``+`` operator to produce a new :class:`.BakedQuery` with modifications. @@ -121,7 +122,8 @@ class BakedQuery(object): return self._clone().add_criteria(fn, *args) def for_session(self, session): - """Return a :class:`.Result` object for this :class:`.BakedQuery`. + """Return a :class:`_baked.Result` object for this + :class:`.BakedQuery`. This is equivalent to calling the :class:`.BakedQuery` as a Python callable, e.g. ``result = my_baked_query(session)``. @@ -358,7 +360,7 @@ class BakedQuery(object): class Result(object): """Invokes a :class:`.BakedQuery` against a :class:`.Session`. - The :class:`.Result` object is where the actual :class:`.query.Query` + The :class:`_baked.Result` object is where the actual :class:`.query.Query` object gets created, or retrieved from the cache, against a target :class:`.Session`, and is then invoked for results. @@ -399,7 +401,8 @@ class Result(object): that **do not affect the SQL output**, such as execution options and shard identifiers (when using a shard-enabled query object) - .. warning:: :meth:`.Result.with_post_criteria` functions are applied + .. warning:: :meth:`_baked.Result.with_post_criteria` + functions are applied to the :class:`_query.Query` object **after** the query's SQL statement object has been retrieved from the cache. Any operations here diff --git a/lib/sqlalchemy/ext/horizontal_shard.py b/lib/sqlalchemy/ext/horizontal_shard.py index cfb2fd687..04491911e 100644 --- a/lib/sqlalchemy/ext/horizontal_shard.py +++ b/lib/sqlalchemy/ext/horizontal_shard.py @@ -120,13 +120,15 @@ class ShardedQuery(Query): class ShardedResult(object): - """A value object that represents multiple :class:`.ResultProxy` objects. + """A value object that represents multiple :class:`_engine.ResultProxy` + objects. This is used by the :meth:`.ShardedQuery._execute_crud` hook to return - an object that takes the place of the single :class:`.ResultProxy`. + an object that takes the place of the single :class:`_engine.ResultProxy`. Attribute include ``result_proxies``, which is a sequence of the - actual :class:`.ResultProxy` objects, as well as ``aggregate_rowcount`` + actual :class:`_engine.ResultProxy` objects, + as well as ``aggregate_rowcount`` or ``rowcount``, which is the sum of all the individual rowcount values. .. versionadded:: 1.3 diff --git a/lib/sqlalchemy/future/result.py b/lib/sqlalchemy/future/result.py index 583ff957a..82d87ddf1 100644 --- a/lib/sqlalchemy/future/result.py +++ b/lib/sqlalchemy/future/result.py @@ -26,14 +26,17 @@ class Result(Generative, BaseResult): _post_creational_filter = None def close(self): - """Close this :class:`.Result`. + """Close this :class:`_future.Result`. This closes out the underlying DBAPI cursor corresponding to the statement execution, if one is still present. Note that the - DBAPI cursor is automatically released when the :class:`.Result` - exhausts all available rows. :meth:`.Result.close` is generally + DBAPI cursor is automatically released when the + :class:`_future.Result` + exhausts all available rows. :meth:`_future.Result.close` + is generally an optional method except in the case when discarding a - :class:`.Result` that still has additional rows pending for fetch. + :class:`_future.Result` + that still has additional rows pending for fetch. After this method is called, it is no longer valid to call upon the fetch methods, which will raise a :class:`.ResourceClosedError` diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index f08ef085b..5409b9d7f 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -1747,7 +1747,8 @@ class SessionEvents(event.Events): :meth:`_query.Query.update`. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. - * ``result`` the :class:`.ResultProxy` returned as a result of the + * ``result`` the :class:`_engine.ResultProxy` + returned as a result of the bulk UPDATE operation. .. seealso:: @@ -1782,7 +1783,8 @@ class SessionEvents(event.Events): was called upon. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. - * ``result`` the :class:`.ResultProxy` returned as a result of the + * ``result`` the :class:`_engine.ResultProxy` + returned as a result of the bulk DELETE operation. .. seealso:: diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index ce051cdcb..4d7eee9ba 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -3494,7 +3494,7 @@ class Query(Generative): ] def instances(self, result_proxy, context=None): - """Return an ORM result given a :class:`.ResultProxy` and + """Return an ORM result given a :class:`_engine.ResultProxy` and :class:`.QueryContext`. """ diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 61442756d..534d67530 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1119,7 +1119,7 @@ class Session(_SessionClassMethods): r"""Execute a SQL expression construct or string statement within the current transaction. - Returns a :class:`.ResultProxy` representing + Returns a :class:`_engine.ResultProxy` representing results of the statement execution, in the same manner as that of an :class:`_engine.Engine` or :class:`_engine.Connection`. @@ -1187,14 +1187,16 @@ class Session(_SessionClassMethods): The :meth:`.Session.execute` method does *not* invoke autoflush. - The :class:`.ResultProxy` returned by the :meth:`.Session.execute` + The :class:`_engine.ResultProxy` returned by the :meth:`.Session. + execute` method is returned with the "close_with_result" flag set to true; the significance of this flag is that if this :class:`.Session` is autocommitting and does not have a transaction-dedicated :class:`_engine.Connection` available, a temporary :class:`_engine.Connection` is established for the statement execution, which is closed (meaning, - returned to the connection pool) when the :class:`.ResultProxy` has + returned to the connection pool) when the :class:`_engine.ResultProxy` + has consumed all available data. This applies *only* when the :class:`.Session` is configured with autocommit=True and no transaction has been started. diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 37d3c99cf..16aa98adb 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -313,7 +313,7 @@ def identity_key(*args, **kwargs): (<class '__main__.MyClass'>, (1, 2), None) :param class: mapped class (must be a positional argument) - :param row: :class:`.Row` row returned by a :class:`.ResultProxy` + :param row: :class:`.Row` row returned by a :class:`_engine.ResultProxy` (must be given as a keyword arg) :param identity_token: optional identity token diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py index 7da6e2c4a..ef4a12248 100644 --- a/lib/sqlalchemy/pool/base.py +++ b/lib/sqlalchemy/pool/base.py @@ -95,8 +95,8 @@ class Pool(log.Identified): ``"debug"``, the logging will include pool checkouts and checkins. The :paramref:`_pool.Pool.echo` parameter can also be set from the - :func:`.create_engine` call by using the - :paramref:`.create_engine.echo_pool` parameter. + :func:`_sa.create_engine` call by using the + :paramref:`_sa.create_engine.echo_pool` parameter. .. seealso:: @@ -141,13 +141,13 @@ class Pool(log.Identified): :param events: a list of 2-tuples, each of the form ``(callable, target)`` which will be passed to :func:`.event.listen` upon construction. Provided here so that event listeners - can be assigned via :func:`.create_engine` before dialect-level + can be assigned via :func:`_sa.create_engine` before dialect-level listeners are applied. :param dialect: a :class:`.Dialect` that will handle the job of calling rollback(), close(), or commit() on DBAPI connections. If omitted, a built-in "stub" dialect is used. Applications that - make use of :func:`~.create_engine` should not use this parameter + make use of :func:`_sa.create_engine` should not use this parameter as it is handled by the engine creation strategy. .. versionadded:: 1.1 - ``dialect`` is now a public parameter diff --git a/lib/sqlalchemy/pool/events.py b/lib/sqlalchemy/pool/events.py index 8adfa267c..3954f907f 100644 --- a/lib/sqlalchemy/pool/events.py +++ b/lib/sqlalchemy/pool/events.py @@ -110,7 +110,8 @@ class PoolEvents(event.Events): Processing of all checkout listeners will abort and restart using the new connection. - .. seealso:: :meth:`.ConnectionEvents.engine_connect` - a similar event + .. seealso:: :meth:`_events.ConnectionEvents.engine_connect` + - a similar event which occurs upon creation of a new :class:`_engine.Connection`. """ @@ -150,9 +151,9 @@ class PoolEvents(event.Events): .. seealso:: - :meth:`.ConnectionEvents.rollback` + :meth:`_events.ConnectionEvents.rollback` - :meth:`.ConnectionEvents.commit` + :meth:`_events.ConnectionEvents.commit` """ diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py index 1b9b20b32..d070027c8 100644 --- a/lib/sqlalchemy/sql/base.py +++ b/lib/sqlalchemy/sql/base.py @@ -600,7 +600,8 @@ class Executable(Generative): "by the :meth:`_engine.Connection.execute` method of " ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " - ":class:`.Session`; the :meth:`.Result.scalar` method can then be " + ":class:`.Session`; the :meth:`_future.Result.scalar` " + "method can then be " "used to return a scalar result.", ) def scalar(self, *multiparams, **params): diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index bc800de42..4ed01375e 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -345,7 +345,8 @@ class UpdateBase( Upon execution, the values of the columns to be returned are made available via the result set and can be iterated using - :meth:`.ResultProxy.fetchone` and similar. For DBAPIs which do not + :meth:`_engine.ResultProxy.fetchone` and similar. + For DBAPIs which do not natively support returning values (i.e. cx_oracle), SQLAlchemy will approximate this behavior at the result level so that a reasonable amount of behavioral neutrality is provided. @@ -546,7 +547,8 @@ class ValuesBase(UpdateBase): True, indicating that the statement will not attempt to fetch the "last inserted primary key" or other defaults. The statement deals with an arbitrary number of rows, so the - :attr:`.ResultProxy.inserted_primary_key` accessor does not + :attr:`_engine.ResultProxy.inserted_primary_key` + accessor does not apply. .. versionchanged:: 1.0.0 A multiple-VALUES INSERT now supports @@ -682,7 +684,8 @@ class ValuesBase(UpdateBase): added to any existing RETURNING clause, provided that :meth:`.UpdateBase.returning` is not used simultaneously. The column values will then be available on the result using the - :attr:`.ResultProxy.returned_defaults` accessor as a dictionary, + :attr:`_engine.ResultProxy.returned_defaults` accessor as a dictionary + , referring to values keyed to the :class:`_schema.Column` object as well as its ``.key``. @@ -712,7 +715,7 @@ class ValuesBase(UpdateBase): 3. It can be called against any backend. Backends that don't support RETURNING will skip the usage of the feature, rather than raising an exception. The return value of - :attr:`.ResultProxy.returned_defaults` will be ``None`` + :attr:`_engine.ResultProxy.returned_defaults` will be ``None`` :meth:`.ValuesBase.return_defaults` is used by the ORM to provide an efficient implementation for the ``eager_defaults`` feature of @@ -729,7 +732,7 @@ class ValuesBase(UpdateBase): :meth:`.UpdateBase.returning` - :attr:`.ResultProxy.returned_defaults` + :attr:`_engine.ResultProxy.returned_defaults` """ self._return_defaults = cols or True @@ -919,7 +922,8 @@ class Insert(ValuesBase): True, indicating that the statement will not attempt to fetch the "last inserted primary key" or other defaults. The statement deals with an arbitrary number of rows, so the - :attr:`.ResultProxy.inserted_primary_key` accessor does not apply. + :attr:`_engine.ResultProxy.inserted_primary_key` + accessor does not apply. """ @@ -1060,7 +1064,7 @@ class Update(DMLWhereBase, ValuesBase): the ``default`` keyword will be compiled 'inline' into the statement and not pre-executed. This means that their values will not be available in the dictionary returned from - :meth:`.ResultProxy.last_updated_params`. + :meth:`_engine.ResultProxy.last_updated_params`. :param preserve_parameter_order: if True, the update statement is expected to receive parameters **only** via the @@ -1185,7 +1189,7 @@ class Update(DMLWhereBase, ValuesBase): ``default`` keyword will be compiled 'inline' into the statement and not pre-executed. This means that their values will not be available in the dictionary returned from - :meth:`.ResultProxy.last_updated_params`. + :meth:`_engine.ResultProxy.last_updated_params`. .. versionchanged:: 1.4 the :paramref:`_expression.update.inline` parameter diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py index c0699c2ad..1bd63f285 100644 --- a/lib/sqlalchemy/sql/operators.py +++ b/lib/sqlalchemy/sql/operators.py @@ -610,7 +610,7 @@ class ColumnOperators(Operators): In the case that ``other`` is an empty sequence, the compiler produces an "empty not in" expression. This defaults to the expression "1 = 1" to produce true in all cases. The - :paramref:`.create_engine.empty_in_strategy` may be used to + :paramref:`_sa.create_engine.empty_in_strategy` may be used to alter this behavior. .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index bfe5d80ad..89ee7e28f 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -3471,7 +3471,7 @@ class Select( r"""Construct a new :class:`_expression.Select` using the 2. x style API. - .. versionadded:: 2.0 - the :func:`.future.select` construct is + .. versionadded:: 2.0 - the :func:`_future.select` construct is the same construct as the one returned by :func:`_expression.select`, except that the function only accepts the "columns clause" entities up front; the rest of the diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index ba8a25821..a65989e93 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -187,8 +187,8 @@ class String(Concatenable, TypeEngine): In the rare circumstance that the DBAPI does not support Python unicode under Python 2, SQLAlchemy will use its own encoder/decoder functionality on strings, referring to the - value of the :paramref:`.create_engine.encoding` parameter - parameter passed to :func:`.create_engine` as the encoding. + value of the :paramref:`_sa.create_engine.encoding` parameter + parameter passed to :func:`_sa.create_engine` as the encoding. For the extremely rare case that Python Unicode is to be encoded/decoded by SQLAlchemy on a backend @@ -218,7 +218,7 @@ class String(Concatenable, TypeEngine): .. seealso:: - :paramref:`.create_engine.convert_unicode` - + :paramref:`_sa.create_engine.convert_unicode` - :class:`_engine.Engine`-wide parameter :param unicode_error: Optional, a method to use to handle Unicode @@ -378,7 +378,7 @@ class Unicode(String): directly, SQLAlchemy does the encoding and decoding outside of the DBAPI. The encoding in this scenario is determined by the ``encoding`` flag passed to - :func:`.create_engine`. + :func:`_sa.create_engine`. When using the :class:`.Unicode` type, it is only appropriate to pass Python ``unicode`` objects, and not plain ``str``. @@ -2089,9 +2089,9 @@ class JSON(Indexable, TypeEngine): psycopg2 dialect, psycopg2 may be using its own custom loader function. In order to affect the serializer / deserializer, they are currently - configurable at the :func:`.create_engine` level via the - :paramref:`.create_engine.json_serializer` and - :paramref:`.create_engine.json_deserializer` parameters. For example, + configurable at the :func:`_sa.create_engine` level via the + :paramref:`_sa.create_engine.json_serializer` and + :paramref:`_sa.create_engine.json_deserializer` parameters. For example, to turn off ``ensure_ascii``:: engine = create_engine( |