From: Mike Bayer Date: Mon, 2 Mar 2020 15:28:32 +0000 (-0500) Subject: Update dialect API documentation X-Git-Tag: rel_1_4_0b1~496 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=649de79950dcf952d7a44069faf36925c23c4e63;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Update dialect API documentation The docstrings for connect() and on_connect() were incorrect between Dialect vs. DefaultDialect. Redocumented related methods, clean up formatting, and remove unicode-related attribute descriptions from the top level Dialect document as these don't apply to Python 3. Change-Id: I45baab757f8e20627eba42c30b9e8dbe26356275 --- diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py index 7efc4bda2f..28a59e6601 100644 --- a/lib/sqlalchemy/engine/default.py +++ b/lib/sqlalchemy/engine/default.py @@ -338,17 +338,7 @@ class DefaultDialect(interfaces.Dialect): ) def on_connect(self): - """return a callable which sets up a newly created DBAPI connection. - - This is used to set dialect-wide per-connection options such as - isolation modes, unicode modes, etc. - - If a callable is returned, it will be assembled into a pool listener - that receives the direct DBAPI connection, with all wrappers removed. - - If None is returned, no listener will be generated. - - """ + # inherits the docstring from interfaces.Dialect.on_connect return None def _check_max_identifier_length(self, connection): @@ -478,9 +468,11 @@ class DefaultDialect(interfaces.Dialect): ) def connect(self, *cargs, **cparams): + # inherits the docstring from interfaces.Dialect.connect return self.dbapi.connect(*cargs, **cparams) def create_connect_args(self, url): + # inherits the docstring from interfaces.Dialect.create_connect_args opts = url.translate_connect_args() opts.update(url.query) return [[], opts] diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 3d4308df29..04e572c2d2 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -22,86 +22,80 @@ class Dialect(object): database-specific object implementations including ExecutionContext, Compiled, DefaultGenerator, and TypeEngine. - All Dialects implement the following attributes: + .. note:: Third party dialects should not subclass :class:`.Dialect` + directly. Instead, subclass :class:`.default.DefaultDialect` or + descendant class. - name + All dialects include the following attributes. There are many other + attributes that may be supported as well: + + ``name`` identifying name for the dialect from a DBAPI-neutral point of view (i.e. 'sqlite') - driver + ``driver`` identifying name for the dialect's DBAPI - positional + ``positional`` True if the paramstyle for this Dialect is positional. - paramstyle + ``paramstyle`` the paramstyle to be used (some DB-APIs support multiple paramstyles). - convert_unicode - True if Unicode conversion should be applied to all ``str`` - types. - - encoding + ``encoding`` type of encoding to use for unicode, usually defaults to 'utf-8'. - statement_compiler + ``statement_compiler`` a :class:`.Compiled` class used to compile SQL statements - ddl_compiler + ``ddl_compiler`` a :class:`.Compiled` class used to compile DDL statements - server_version_info + ``server_version_info`` a tuple containing a version number for the DB backend in use. This value is only available for supporting dialects, and is typically populated during the initial connection to the database. - default_schema_name + ``default_schema_name`` the name of the default schema. This value is only available for supporting dialects, and is typically populated during the initial connection to the database. - execution_ctx_cls + ``execution_ctx_cls`` a :class:`.ExecutionContext` class used to handle statement execution - execute_sequence_format + ``execute_sequence_format`` either the 'tuple' or 'list' type, depending on what cursor.execute() accepts for the second argument (they vary). - preparer + ``preparer`` a :class:`~sqlalchemy.sql.compiler.IdentifierPreparer` class used to quote identifiers. - supports_alter - ``True`` if the database supports ``ALTER TABLE``. + ``supports_alter`` + ``True`` if the database supports ``ALTER TABLE`` - used only for + generating foreign key constraints in certain circumstances - max_identifier_length + ``max_identifier_length`` The maximum length of identifier names. - supports_unicode_statements - Indicate whether the DB-API can receive SQL statements as Python - unicode strings - - supports_unicode_binds - Indicate whether the DB-API can receive string bind parameters - as Python unicode strings - - supports_sane_rowcount + ``supports_sane_rowcount`` Indicate whether the dialect properly implements rowcount for ``UPDATE`` and ``DELETE`` statements. - supports_sane_multi_rowcount + ``supports_sane_multi_rowcount`` Indicate whether the dialect properly implements rowcount for ``UPDATE`` and ``DELETE`` statements when executed via executemany. - preexecute_autoincrement_sequences + ``preexecute_autoincrement_sequences`` True if 'implicit' primary key functions must be executed separately in order to get their value. This is currently oriented towards PostgreSQL. - implicit_returning + ``implicit_returning`` use RETURNING or equivalent during INSERT execution in order to load newly generated primary keys and other column defaults in one execution, which are then available via inserted_primary_key. @@ -109,37 +103,37 @@ class Dialect(object): the "implicit" functionality is not used and inserted_primary_key will not be available. - colspecs + ``colspecs`` A dictionary of TypeEngine classes from sqlalchemy.types mapped to subclasses that are specific to the dialect class. This dictionary is class-level only and is not accessed from the dialect instance itself. - supports_default_values + ``supports_default_values`` Indicates if the construct ``INSERT INTO tablename DEFAULT VALUES`` is supported - supports_sequences + ``supports_sequences`` Indicates if the dialect supports CREATE SEQUENCE or similar. - sequences_optional + ``sequences_optional`` If True, indicates if the "optional" flag on the Sequence() construct should signal to not generate a CREATE SEQUENCE. Applies only to dialects that support sequences. Currently used only to allow PostgreSQL SERIAL to be used on a column that specifies Sequence() for usage on other backends. - supports_native_enum + ``supports_native_enum`` Indicates if the dialect supports a native ENUM construct. This will prevent types.Enum from generating a CHECK constraint when that type is used. - supports_native_boolean + ``supports_native_boolean`` Indicates if the dialect supports a native boolean construct. This will prevent types.Boolean from generating a CHECK constraint when that type is used. - dbapi_exception_translation_map + ``dbapi_exception_translation_map`` A dictionary of names that will contain as values the names of pep-249 exceptions ("IntegrityError", "OperationalError", etc) keyed to alternate class names, to support the case where a @@ -156,9 +150,31 @@ class Dialect(object): def create_connect_args(self, url): """Build DB-API compatible connection arguments. - Given a :class:`~sqlalchemy.engine.url.URL` object, returns a tuple - consisting of a `*args`/`**kwargs` suitable to send directly - to the dbapi's connect function. + Given a :class:`.URL` object, returns a tuple + consisting of a ``(*args, **kwargs)`` suitable to send directly + to the dbapi's connect function. The arguments are sent to the + :meth:`.Dialect.connect` method which then runs the DBAPI-level + ``connect()`` function. + + The method typically makes use of the + :meth:`.URL.translate_connect_args` + method in order to generate a dictionary of options. + + The default implementation is:: + + def create_connect_args(self, url): + opts = url.translate_connect_args() + opts.update(url.query) + return [[], opts] + + :param url: a :class:`.URL` object + + :return: a tuple of ``(*args, **kwargs)`` which will be passed to the + :meth:`.Dialect.connect` method. + + .. seealso:: + + :meth:`.URL.translate_connect_args` """ @@ -676,19 +692,79 @@ class Dialect(object): raise NotImplementedError() - def connect(self): + def connect(self, *cargs, **cparams): + r"""Establish a connection using this dialect's DBAPI. + + The default implementation of this method is:: + + def connect(self, *cargs, **cparams): + return self.dbapi.connect(*cargs, **cparams) + + The ``*cargs, **cparams`` parameters are generated directly + from this dialect's :meth:`.Dialect.create_connect_args` method. + + This method may be used for dialects that need to perform programmatic + per-connection steps when a new connection is procured from the + DBAPI. + + + :param \*cargs: positional parameters returned from the + :meth:`.Dialect.create_connect_args` method + + :param \*\*cparams: keyword parameters returned from the + :meth:`.Dialect.create_connect_args` method. + + :return: a DBAPI connection, typically from the :pep:`249` module + level ``.connect()`` function. + + .. seealso:: + + :meth:`.Dialect.create_connect_args` + + :meth:`.Dialect.on_connect` + + """ + + def on_connect(self): """return a callable which sets up a newly created DBAPI connection. - The callable accepts a single argument "conn" which is the - DBAPI connection itself. It has no return value. + The callable should accept a single argument "conn" which is the + DBAPI connection itself. The inner callable has no + return value. + + E.g.:: + + class MyDialect(default.DefaultDialect): + # ... + + def on_connect(self): + def do_on_connect(connection): + connection.execute("SET SPECIAL FLAGS etc") + + return do_on_connect This is used to set dialect-wide per-connection options such as - isolation modes, unicode modes, etc. + isolation modes, Unicode modes, etc. - If a callable is returned, it will be assembled into a pool listener - that receives the direct DBAPI connection, with all wrappers removed. + The "do_on_connect" callable is invoked by using the + :meth:`.PoolEvents.first_connect` and :meth:`.PoolEvents.connect` event + hooks, then unwrapping the DBAPI connection and passing it into the + callable. The reason it is invoked for both events is so that any + dialect-level initialization that occurs upon first connection, which + also makes use of the :meth:`.PoolEvents.first_connect` method, will + proceed after this hook has been called. This currently means the + hook is in fact called twice for the very first connection in which a + dialect creates; and once per connection afterwards. + + If None is returned, no event listener is generated. + + :return: a callable that accepts a single DBAPI connection as an + argument, or None. + + .. seealso:: - If None is returned, no listener will be generated. + :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence + itself to be controlled. """ return None