codekingpro/portable-devtools
115k
1# engine/interfaces.py
2# Copyright (C) 2005-2024 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
7
8"""Define core interfaces used by the engine system."""
9
10from __future__ import annotations
11
12from enum import Enum
13from types import ModuleType
14from typing import Any
15from typing import Awaitable
16from typing import Callable
17from typing import ClassVar
18from typing import Collection
19from typing import Dict
20from typing import Iterable
21from typing import Iterator
22from typing import List
23from typing import Mapping
24from typing import MutableMapping
25from typing import Optional
26from typing import Sequence
27from typing import Set
28from typing import Tuple
29from typing import Type
30from typing import TYPE_CHECKING
31from typing import TypeVar
32from typing import Union
33
34from .. import util
35from ..event import EventTarget
36from ..pool import Pool
37from ..pool import PoolProxiedConnection
38from ..sql.compiler import Compiled as Compiled
39from ..sql.compiler import Compiled # noqa
40from ..sql.compiler import TypeCompiler as TypeCompiler
41from ..sql.compiler import TypeCompiler # noqa
42from ..util import immutabledict
43from ..util.concurrency import await_only
44from ..util.typing import Literal
45from ..util.typing import NotRequired
46from ..util.typing import Protocol
47from ..util.typing import TypedDict
48
49if TYPE_CHECKING:
50 from .base import Connection
51 from .base import Engine
52 from .cursor import CursorResult
53 from .url import URL
54 from ..event import _ListenerFnType
55 from ..event import dispatcher
56 from ..exc import StatementError
57 from ..sql import Executable
58 from ..sql.compiler import _InsertManyValuesBatch
59 from ..sql.compiler import DDLCompiler
60 from ..sql.compiler import IdentifierPreparer
61 from ..sql.compiler import InsertmanyvaluesSentinelOpts
62 from ..sql.compiler import Linting
63 from ..sql.compiler import SQLCompiler
64 from ..sql.elements import BindParameter
65 from ..sql.elements import ClauseElement
66 from ..sql.schema import Column
67 from ..sql.schema import DefaultGenerator
68 from ..sql.schema import SchemaItem
69 from ..sql.schema import Sequence as Sequence_SchemaItem
70 from ..sql.sqltypes import Integer
71 from ..sql.type_api import _TypeMemoDict
72 from ..sql.type_api import TypeEngine
73
74ConnectArgsType = Tuple[Sequence[str], MutableMapping[str, Any]]
75
76_T = TypeVar("_T", bound="Any")
77
78
79class CacheStats(Enum):
80 CACHE_HIT = 0
81 CACHE_MISS = 1
82 CACHING_DISABLED = 2
83 NO_CACHE_KEY = 3
84 NO_DIALECT_SUPPORT = 4
85
86
87class ExecuteStyle(Enum):
88 """indicates the :term:`DBAPI` cursor method that will be used to invoke
89 a statement."""
90
91 EXECUTE = 0
92 """indicates cursor.execute() will be used"""
93
94 EXECUTEMANY = 1
95 """indicates cursor.executemany() will be used."""
96
97 INSERTMANYVALUES = 2
98 """indicates cursor.execute() will be used with an INSERT where the
99 VALUES expression will be expanded to accommodate for multiple
100 parameter sets
101
102 .. seealso::
103
104 :ref:`engine_insertmanyvalues`
105
106 """
107
108
109class DBAPIConnection(Protocol):
110 """protocol representing a :pep:`249` database connection.
111
112 .. versionadded:: 2.0
113
114 .. seealso::
115
116 `Connection Objects <https://www.python.org/dev/peps/pep-0249/#connection-objects>`_
117 - in :pep:`249`
118
119 """ # noqa: E501
120
121 def close(self) -> None: ...
122
123 def commit(self) -> None: ...
124
125 def cursor(self) -> DBAPICursor: ...
126
127 def rollback(self) -> None: ...
128
129 autocommit: bool
130
131
132class DBAPIType(Protocol):
133 """protocol representing a :pep:`249` database type.
134
135 .. versionadded:: 2.0
136
137 .. seealso::
138
139 `Type Objects <https://www.python.org/dev/peps/pep-0249/#type-objects>`_
140 - in :pep:`249`
141
142 """ # noqa: E501
143
144
145class DBAPICursor(Protocol):
146 """protocol representing a :pep:`249` database cursor.
147
148 .. versionadded:: 2.0
149
150 .. seealso::
151
152 `Cursor Objects <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_
153 - in :pep:`249`
154
155 """ # noqa: E501
156
157 @property
158 def description(
159 self,
160 ) -> _DBAPICursorDescription:
161 """The description attribute of the Cursor.
162
163 .. seealso::
164
165 `cursor.description <https://www.python.org/dev/peps/pep-0249/#description>`_
166 - in :pep:`249`
167
168
169 """ # noqa: E501
170 ...
171
172 @property
173 def rowcount(self) -> int: ...
174
175 arraysize: int
176
177 lastrowid: int
178
179 def close(self) -> None: ...
180
181 def execute(
182 self,
183 operation: Any,
184 parameters: Optional[_DBAPISingleExecuteParams] = None,
185 ) -> Any: ...
186
187 def executemany(
188 self,
189 operation: Any,
190 parameters: _DBAPIMultiExecuteParams,
191 ) -> Any: ...
192
193 def fetchone(self) -> Optional[Any]: ...
194
195 def fetchmany(self, size: int = ...) -> Sequence[Any]: ...
196
197 def fetchall(self) -> Sequence[Any]: ...
198
199 def setinputsizes(self, sizes: Sequence[Any]) -> None: ...
200
201 def setoutputsize(self, size: Any, column: Any) -> None: ...
202
203 def callproc(
204 self, procname: str, parameters: Sequence[Any] = ...
205 ) -> Any: ...
206
207 def nextset(self) -> Optional[bool]: ...
208
209 def __getattr__(self, key: str) -> Any: ...
210
211
212_CoreSingleExecuteParams = Mapping[str, Any]
213_MutableCoreSingleExecuteParams = MutableMapping[str, Any]
214_CoreMultiExecuteParams = Sequence[_CoreSingleExecuteParams]
215_CoreAnyExecuteParams = Union[
216 _CoreMultiExecuteParams, _CoreSingleExecuteParams
217]
218
219_DBAPISingleExecuteParams = Union[Sequence[Any], _CoreSingleExecuteParams]
220
221_DBAPIMultiExecuteParams = Union[
222 Sequence[Sequence[Any]], _CoreMultiExecuteParams
223]
224_DBAPIAnyExecuteParams = Union[
225 _DBAPIMultiExecuteParams, _DBAPISingleExecuteParams
226]
227_DBAPICursorDescription = Sequence[
228 Tuple[
229 str,
230 "DBAPIType",
231 Optional[int],
232 Optional[int],
233 Optional[int],
234 Optional[int],
235 Optional[bool],
236 ]
237]
238
239_AnySingleExecuteParams = _DBAPISingleExecuteParams
240_AnyMultiExecuteParams = _DBAPIMultiExecuteParams
241_AnyExecuteParams = _DBAPIAnyExecuteParams
242
243CompiledCacheType = MutableMapping[Any, "Compiled"]
244SchemaTranslateMapType = Mapping[Optional[str], Optional[str]]
245
246_ImmutableExecuteOptions = immutabledict[str, Any]
247
248_ParamStyle = Literal[
249 "qmark", "numeric", "named", "format", "pyformat", "numeric_dollar"
250]
251
252_GenericSetInputSizesType = List[Tuple[str, Any, "TypeEngine[Any]"]]
253
254IsolationLevel = Literal[
255 "SERIALIZABLE",
256 "REPEATABLE READ",
257 "READ COMMITTED",
258 "READ UNCOMMITTED",
259 "AUTOCOMMIT",
260]
261
262
263class _CoreKnownExecutionOptions(TypedDict, total=False):
264 compiled_cache: Optional[CompiledCacheType]
265 logging_token: str
266 isolation_level: IsolationLevel
267 no_parameters: bool
268 stream_results: bool
269 max_row_buffer: int
270 yield_per: int
271 insertmanyvalues_page_size: int
272 schema_translate_map: Optional[SchemaTranslateMapType]
273 preserve_rowcount: bool
274
275
276_ExecuteOptions = immutabledict[str, Any]
277CoreExecuteOptionsParameter = Union[
278 _CoreKnownExecutionOptions, Mapping[str, Any]
279]
280
281
282class ReflectedIdentity(TypedDict):
283 """represent the reflected IDENTITY structure of a column, corresponding
284 to the :class:`_schema.Identity` construct.
285
286 The :class:`.ReflectedIdentity` structure is part of the
287 :class:`.ReflectedColumn` structure, which is returned by the
288 :meth:`.Inspector.get_columns` method.
289
290 """
291
292 always: bool
293 """type of identity column"""
294
295 on_null: bool
296 """indicates ON NULL"""
297
298 start: int
299 """starting index of the sequence"""
300
301 increment: int
302 """increment value of the sequence"""
303
304 minvalue: int
305 """the minimum value of the sequence."""
306
307 maxvalue: int
308 """the maximum value of the sequence."""
309
310 nominvalue: bool
311 """no minimum value of the sequence."""
312
313 nomaxvalue: bool
314 """no maximum value of the sequence."""
315
316 cycle: bool
317 """allows the sequence to wrap around when the maxvalue
318 or minvalue has been reached."""
319
320 cache: Optional[int]
321 """number of future values in the
322 sequence which are calculated in advance."""
323
324 order: bool
325 """if true, renders the ORDER keyword."""
326
327
328class ReflectedComputed(TypedDict):
329 """Represent the reflected elements of a computed column, corresponding
330 to the :class:`_schema.Computed` construct.
331
332 The :class:`.ReflectedComputed` structure is part of the
333 :class:`.ReflectedColumn` structure, which is returned by the
334 :meth:`.Inspector.get_columns` method.
335
336 """
337
338 sqltext: str
339 """the expression used to generate this column returned
340 as a string SQL expression"""
341
342 persisted: NotRequired[bool]
343 """indicates if the value is stored in the table or computed on demand"""
344
345
346class ReflectedColumn(TypedDict):
347 """Dictionary representing the reflected elements corresponding to
348 a :class:`_schema.Column` object.
349
350 The :class:`.ReflectedColumn` structure is returned by the
351 :class:`.Inspector.get_columns` method.
352
353 """
354
355 name: str
356 """column name"""
357
358 type: TypeEngine[Any]
359 """column type represented as a :class:`.TypeEngine` instance."""
360
361 nullable: bool
362 """boolean flag if the column is NULL or NOT NULL"""
363
364 default: Optional[str]
365 """column default expression as a SQL string"""
366
367 autoincrement: NotRequired[bool]
368 """database-dependent autoincrement flag.
369
370 This flag indicates if the column has a database-side "autoincrement"
371 flag of some kind. Within SQLAlchemy, other kinds of columns may
372 also act as an "autoincrement" column without necessarily having
373 such a flag on them.
374
375 See :paramref:`_schema.Column.autoincrement` for more background on
376 "autoincrement".
377
378 """
379
380 comment: NotRequired[Optional[str]]
381 """comment for the column, if present.
382 Only some dialects return this key
383 """
384
385 computed: NotRequired[ReflectedComputed]
386 """indicates that this column is computed by the database.
387 Only some dialects return this key.
388
389 .. versionadded:: 1.3.16 - added support for computed reflection.
390 """
391
392 identity: NotRequired[ReflectedIdentity]
393 """indicates this column is an IDENTITY column.
394 Only some dialects return this key.
395
396 .. versionadded:: 1.4 - added support for identity column reflection.
397 """
398
399 dialect_options: NotRequired[Dict[str, Any]]
400 """Additional dialect-specific options detected for this reflected
401 object"""
402
403
404class ReflectedConstraint(TypedDict):
405 """Dictionary representing the reflected elements corresponding to
406 :class:`.Constraint`
407
408 A base class for all constraints
409 """
410
411 name: Optional[str]
412 """constraint name"""
413
414 comment: NotRequired[Optional[str]]
415 """comment for the constraint, if present"""
416
417
418class ReflectedCheckConstraint(ReflectedConstraint):
419 """Dictionary representing the reflected elements corresponding to
420 :class:`.CheckConstraint`.
421
422 The :class:`.ReflectedCheckConstraint` structure is returned by the
423 :meth:`.Inspector.get_check_constraints` method.
424
425 """
426
427 sqltext: str
428 """the check constraint's SQL expression"""
429
430 dialect_options: NotRequired[Dict[str, Any]]
431 """Additional dialect-specific options detected for this check constraint
432
433 .. versionadded:: 1.3.8
434 """
435
436
437class ReflectedUniqueConstraint(ReflectedConstraint):
438 """Dictionary representing the reflected elements corresponding to
439 :class:`.UniqueConstraint`.
440
441 The :class:`.ReflectedUniqueConstraint` structure is returned by the
442 :meth:`.Inspector.get_unique_constraints` method.
443
444 """
445
446 column_names: List[str]
447 """column names which comprise the unique constraint"""
448
449 duplicates_index: NotRequired[Optional[str]]
450 "Indicates if this unique constraint duplicates an index with this name"
451
452 dialect_options: NotRequired[Dict[str, Any]]
453 """Additional dialect-specific options detected for this unique
454 constraint"""
455
456
457class ReflectedPrimaryKeyConstraint(ReflectedConstraint):
458 """Dictionary representing the reflected elements corresponding to
459 :class:`.PrimaryKeyConstraint`.
460
461 The :class:`.ReflectedPrimaryKeyConstraint` structure is returned by the
462 :meth:`.Inspector.get_pk_constraint` method.
463
464 """
465
466 constrained_columns: List[str]
467 """column names which comprise the primary key"""
468
469 dialect_options: NotRequired[Dict[str, Any]]
470 """Additional dialect-specific options detected for this primary key"""
471
472
473class ReflectedForeignKeyConstraint(ReflectedConstraint):
474 """Dictionary representing the reflected elements corresponding to
475 :class:`.ForeignKeyConstraint`.
476
477 The :class:`.ReflectedForeignKeyConstraint` structure is returned by
478 the :meth:`.Inspector.get_foreign_keys` method.
479
480 """
481
482 constrained_columns: List[str]
483 """local column names which comprise the foreign key"""
484
485 referred_schema: Optional[str]
486 """schema name of the table being referred"""
487
488 referred_table: str
489 """name of the table being referred"""
490
491 referred_columns: List[str]
492 """referred column names that correspond to ``constrained_columns``"""
493
494 options: NotRequired[Dict[str, Any]]
495 """Additional options detected for this foreign key constraint"""
496
497
498class ReflectedIndex(TypedDict):
499 """Dictionary representing the reflected elements corresponding to
500 :class:`.Index`.
501
502 The :class:`.ReflectedIndex` structure is returned by the
503 :meth:`.Inspector.get_indexes` method.
504
505 """
506
507 name: Optional[str]
508 """index name"""
509
510 column_names: List[Optional[str]]
511 """column names which the index references.
512 An element of this list is ``None`` if it's an expression and is
513 returned in the ``expressions`` list.
514 """
515
516 expressions: NotRequired[List[str]]
517 """Expressions that compose the index. This list, when present, contains
518 both plain column names (that are also in ``column_names``) and
519 expressions (that are ``None`` in ``column_names``).
520 """
521
522 unique: bool
523 """whether or not the index has a unique flag"""
524
525 duplicates_constraint: NotRequired[Optional[str]]
526 "Indicates if this index mirrors a constraint with this name"
527
528 include_columns: NotRequired[List[str]]
529 """columns to include in the INCLUDE clause for supporting databases.
530
531 .. deprecated:: 2.0
532
533 Legacy value, will be replaced with
534 ``index_dict["dialect_options"]["<dialect name>_include"]``
535
536 """
537
538 column_sorting: NotRequired[Dict[str, Tuple[str]]]
539 """optional dict mapping column names or expressions to tuple of sort
540 keywords, which may include ``asc``, ``desc``, ``nulls_first``,
541 ``nulls_last``.
542
543 .. versionadded:: 1.3.5
544 """
545
546 dialect_options: NotRequired[Dict[str, Any]]
547 """Additional dialect-specific options detected for this index"""
548
549
550class ReflectedTableComment(TypedDict):
551 """Dictionary representing the reflected comment corresponding to
552 the :attr:`_schema.Table.comment` attribute.
553
554 The :class:`.ReflectedTableComment` structure is returned by the
555 :meth:`.Inspector.get_table_comment` method.
556
557 """
558
559 text: Optional[str]
560 """text of the comment"""
561
562
563class BindTyping(Enum):
564 """Define different methods of passing typing information for
565 bound parameters in a statement to the database driver.
566
567 .. versionadded:: 2.0
568
569 """
570
571 NONE = 1
572 """No steps are taken to pass typing information to the database driver.
573
574 This is the default behavior for databases such as SQLite, MySQL / MariaDB,
575 SQL Server.
576
577 """
578
579 SETINPUTSIZES = 2
580 """Use the pep-249 setinputsizes method.
581
582 This is only implemented for DBAPIs that support this method and for which
583 the SQLAlchemy dialect has the appropriate infrastructure for that
584 dialect set up. Current dialects include cx_Oracle as well as
585 optional support for SQL Server using pyodbc.
586
587 When using setinputsizes, dialects also have a means of only using the
588 method for certain datatypes using include/exclude lists.
589
590 When SETINPUTSIZES is used, the :meth:`.Dialect.do_set_input_sizes` method
591 is called for each statement executed which has bound parameters.
592
593 """
594
595 RENDER_CASTS = 3
596 """Render casts or other directives in the SQL string.
597
598 This method is used for all PostgreSQL dialects, including asyncpg,
599 pg8000, psycopg, psycopg2. Dialects which implement this can choose
600 which kinds of datatypes are explicitly cast in SQL statements and which
601 aren't.
602
603 When RENDER_CASTS is used, the compiler will invoke the
604 :meth:`.SQLCompiler.render_bind_cast` method for the rendered
605 string representation of each :class:`.BindParameter` object whose
606 dialect-level type sets the :attr:`.TypeEngine.render_bind_cast` attribute.
607
608 The :meth:`.SQLCompiler.render_bind_cast` is also used to render casts
609 for one form of "insertmanyvalues" query, when both
610 :attr:`.InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT` and
611 :attr:`.InsertmanyvaluesSentinelOpts.RENDER_SELECT_COL_CASTS` are set,
612 where the casts are applied to the intermediary columns e.g.
613 "INSERT INTO t (a, b, c) SELECT p0::TYP, p1::TYP, p2::TYP "
614 "FROM (VALUES (?, ?), (?, ?), ...)".
615
616 .. versionadded:: 2.0.10 - :meth:`.SQLCompiler.render_bind_cast` is now
617 used within some elements of the "insertmanyvalues" implementation.
618
619
620 """
621
622
623VersionInfoType = Tuple[Union[int, str], ...]
624TableKey = Tuple[Optional[str], str]
625
626
627class Dialect(EventTarget):
628 """Define the behavior of a specific database and DB-API combination.
629
630 Any aspect of metadata definition, SQL query generation,
631 execution, result-set handling, or anything else which varies
632 between databases is defined under the general category of the
633 Dialect. The Dialect acts as a factory for other
634 database-specific object implementations including
635 ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
636
637 .. note:: Third party dialects should not subclass :class:`.Dialect`
638 directly. Instead, subclass :class:`.default.DefaultDialect` or
639 descendant class.
640
641 """
642
643 CACHE_HIT = CacheStats.CACHE_HIT
644 CACHE_MISS = CacheStats.CACHE_MISS
645 CACHING_DISABLED = CacheStats.CACHING_DISABLED
646 NO_CACHE_KEY = CacheStats.NO_CACHE_KEY
647 NO_DIALECT_SUPPORT = CacheStats.NO_DIALECT_SUPPORT
648
649 dispatch: dispatcher[Dialect]
650
651 name: str
652 """identifying name for the dialect from a DBAPI-neutral point of view
653 (i.e. 'sqlite')
654 """
655
656 driver: str
657 """identifying name for the dialect's DBAPI"""
658
659 dialect_description: str
660
661 dbapi: Optional[ModuleType]
662 """A reference to the DBAPI module object itself.
663
664 SQLAlchemy dialects import DBAPI modules using the classmethod
665 :meth:`.Dialect.import_dbapi`. The rationale is so that any dialect
666 module can be imported and used to generate SQL statements without the
667 need for the actual DBAPI driver to be installed. Only when an
668 :class:`.Engine` is constructed using :func:`.create_engine` does the
669 DBAPI get imported; at that point, the creation process will assign
670 the DBAPI module to this attribute.
671
672 Dialects should therefore implement :meth:`.Dialect.import_dbapi`
673 which will import the necessary module and return it, and then refer
674 to ``self.dbapi`` in dialect code in order to refer to the DBAPI module
675 contents.
676
677 .. versionchanged:: The :attr:`.Dialect.dbapi` attribute is exclusively
678 used as the per-:class:`.Dialect`-instance reference to the DBAPI
679 module. The previous not-fully-documented ``.Dialect.dbapi()``
680 classmethod is deprecated and replaced by :meth:`.Dialect.import_dbapi`.
681
682 """
683
684 @util.non_memoized_property
685 def loaded_dbapi(self) -> ModuleType:
686 """same as .dbapi, but is never None; will raise an error if no
687 DBAPI was set up.
688
689 .. versionadded:: 2.0
690
691 """
692 raise NotImplementedError()
693
694 positional: bool
695 """True if the paramstyle for this Dialect is positional."""
696
697 paramstyle: str
698 """the paramstyle to be used (some DB-APIs support multiple
699 paramstyles).
700 """
701
702 compiler_linting: Linting
703
704 statement_compiler: Type[SQLCompiler]
705 """a :class:`.Compiled` class used to compile SQL statements"""
706
707 ddl_compiler: Type[DDLCompiler]
708 """a :class:`.Compiled` class used to compile DDL statements"""
709
710 type_compiler_cls: ClassVar[Type[TypeCompiler]]
711 """a :class:`.Compiled` class used to compile SQL type objects
712
713 .. versionadded:: 2.0
714
715 """
716
717 type_compiler_instance: TypeCompiler
718 """instance of a :class:`.Compiled` class used to compile SQL type
719 objects
720
721 .. versionadded:: 2.0
722
723 """
724
725 type_compiler: Any
726 """legacy; this is a TypeCompiler class at the class level, a
727 TypeCompiler instance at the instance level.
728
729 Refer to type_compiler_instance instead.
730
731 """
732
733 preparer: Type[IdentifierPreparer]
734 """a :class:`.IdentifierPreparer` class used to
735 quote identifiers.
736 """
737
738 identifier_preparer: IdentifierPreparer
739 """This element will refer to an instance of :class:`.IdentifierPreparer`
740 once a :class:`.DefaultDialect` has been constructed.
741
742 """
743
744 server_version_info: Optional[Tuple[Any, ...]]
745 """a tuple containing a version number for the DB backend in use.
746
747 This value is only available for supporting dialects, and is
748 typically populated during the initial connection to the database.
749 """
750
751 default_schema_name: Optional[str]
752 """the name of the default schema. This value is only available for
753 supporting dialects, and is typically populated during the
754 initial connection to the database.
755
756 """
757
758 # NOTE: this does not take into effect engine-level isolation level.
759 # not clear if this should be changed, seems like it should
760 default_isolation_level: Optional[IsolationLevel]
761 """the isolation that is implicitly present on new connections"""
762
763 # create_engine() -> isolation_level currently goes here
764 _on_connect_isolation_level: Optional[IsolationLevel]
765
766 execution_ctx_cls: Type[ExecutionContext]
767 """a :class:`.ExecutionContext` class used to handle statement execution"""
768
769 execute_sequence_format: Union[
770 Type[Tuple[Any, ...]], Type[Tuple[List[Any]]]
771 ]
772 """either the 'tuple' or 'list' type, depending on what cursor.execute()
773 accepts for the second argument (they vary)."""
774
775 supports_alter: bool
776 """``True`` if the database supports ``ALTER TABLE`` - used only for
777 generating foreign key constraints in certain circumstances
778 """
779
780 max_identifier_length: int
781 """The maximum length of identifier names."""
782
783 supports_server_side_cursors: bool
784 """indicates if the dialect supports server side cursors"""
785
786 server_side_cursors: bool
787 """deprecated; indicates if the dialect should attempt to use server
788 side cursors by default"""
789
790 supports_sane_rowcount: bool
791 """Indicate whether the dialect properly implements rowcount for
792 ``UPDATE`` and ``DELETE`` statements.
793 """
794
795 supports_sane_multi_rowcount: bool
796 """Indicate whether the dialect properly implements rowcount for
797 ``UPDATE`` and ``DELETE`` statements when executed via
798 executemany.
799 """
800
801 supports_empty_insert: bool
802 """dialect supports INSERT () VALUES (), i.e. a plain INSERT with no
803 columns in it.
804
805 This is not usually supported; an "empty" insert is typically
806 suited using either "INSERT..DEFAULT VALUES" or
807 "INSERT ... (col) VALUES (DEFAULT)".
808
809 """
810
811 supports_default_values: bool
812 """dialect supports INSERT... DEFAULT VALUES syntax"""
813
814 supports_default_metavalue: bool
815 """dialect supports INSERT...(col) VALUES (DEFAULT) syntax.
816
817 Most databases support this in some way, e.g. SQLite supports it using
818 ``VALUES (NULL)``. MS SQL Server supports the syntax also however
819 is the only included dialect where we have this disabled, as
820 MSSQL does not support the field for the IDENTITY column, which is
821 usually where we like to make use of the feature.
822
823 """
824
825 default_metavalue_token: str = "DEFAULT"
826 """for INSERT... VALUES (DEFAULT) syntax, the token to put in the
827 parenthesis.
828
829 E.g. for SQLite this is the keyword "NULL".
830
831 """
832
833 supports_multivalues_insert: bool
834 """Target database supports INSERT...VALUES with multiple value
835 sets, i.e. INSERT INTO table (cols) VALUES (...), (...), (...), ...
836
837 """
838
839 insert_executemany_returning: bool
840 """dialect / driver / database supports some means of providing
841 INSERT...RETURNING support when dialect.do_executemany() is used.
842
843 """
844
845 insert_executemany_returning_sort_by_parameter_order: bool
846 """dialect / driver / database supports some means of providing
847 INSERT...RETURNING support when dialect.do_executemany() is used
848 along with the :paramref:`_dml.Insert.returning.sort_by_parameter_order`
849 parameter being set.
850
851 """
852
853 update_executemany_returning: bool
854 """dialect supports UPDATE..RETURNING with executemany."""
855
856 delete_executemany_returning: bool
857 """dialect supports DELETE..RETURNING with executemany."""
858
859 use_insertmanyvalues: bool
860 """if True, indicates "insertmanyvalues" functionality should be used
861 to allow for ``insert_executemany_returning`` behavior, if possible.
862
863 In practice, setting this to True means:
864
865 if ``supports_multivalues_insert``, ``insert_returning`` and
866 ``use_insertmanyvalues`` are all True, the SQL compiler will produce
867 an INSERT that will be interpreted by the :class:`.DefaultDialect`
868 as an :attr:`.ExecuteStyle.INSERTMANYVALUES` execution that allows
869 for INSERT of many rows with RETURNING by rewriting a single-row
870 INSERT statement to have multiple VALUES clauses, also executing
871 the statement multiple times for a series of batches when large numbers
872 of rows are given.
873
874 The parameter is False for the default dialect, and is set to
875 True for SQLAlchemy internal dialects SQLite, MySQL/MariaDB, PostgreSQL,
876 SQL Server. It remains at False for Oracle, which provides native
877 "executemany with RETURNING" support and also does not support
878 ``supports_multivalues_insert``. For MySQL/MariaDB, those MySQL
879 dialects that don't support RETURNING will not report
880 ``insert_executemany_returning`` as True.
881
882 .. versionadded:: 2.0
883
884 .. seealso::
885
886 :ref:`engine_insertmanyvalues`
887
888 """
889
890 use_insertmanyvalues_wo_returning: bool
891 """if True, and use_insertmanyvalues is also True, INSERT statements
892 that don't include RETURNING will also use "insertmanyvalues".
893
894 .. versionadded:: 2.0
895
896 .. seealso::
897
898 :ref:`engine_insertmanyvalues`
899
900 """
901
902 insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts
903 """Options indicating the database supports a form of bulk INSERT where
904 the autoincrement integer primary key can be reliably used as an ordering
905 for INSERTed rows.
906
907 .. versionadded:: 2.0.10
908
909 .. seealso::
910
911 :ref:`engine_insertmanyvalues_returning_order`
912
913 """
914
915 insertmanyvalues_page_size: int
916 """Number of rows to render into an individual INSERT..VALUES() statement
917 for :attr:`.ExecuteStyle.INSERTMANYVALUES` executions.
918
919 The default dialect defaults this to 1000.
920
921 .. versionadded:: 2.0
922
923 .. seealso::
924
925 :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size` -
926 execution option available on :class:`_engine.Connection`, statements
927
928 """ # noqa: E501
929
930 insertmanyvalues_max_parameters: int
931 """Alternate to insertmanyvalues_page_size, will additionally limit
932 page size based on number of parameters total in the statement.
933
934
935 """
936
937 preexecute_autoincrement_sequences: bool
938 """True if 'implicit' primary key functions must be executed separately
939 in order to get their value, if RETURNING is not used.
940
941 This is currently oriented towards PostgreSQL when the
942 ``implicit_returning=False`` parameter is used on a :class:`.Table`
943 object.
944
945 """
946
947 insert_returning: bool
948 """if the dialect supports RETURNING with INSERT
949
950 .. versionadded:: 2.0
951
952 """
953
954 update_returning: bool
955 """if the dialect supports RETURNING with UPDATE
956
957 .. versionadded:: 2.0
958
959 """
960
961 update_returning_multifrom: bool
962 """if the dialect supports RETURNING with UPDATE..FROM
963
964 .. versionadded:: 2.0
965
966 """
967
968 delete_returning: bool
969 """if the dialect supports RETURNING with DELETE
970
971 .. versionadded:: 2.0
972
973 """
974
975 delete_returning_multifrom: bool
976 """if the dialect supports RETURNING with DELETE..FROM
977
978 .. versionadded:: 2.0
979
980 """
981
982 favor_returning_over_lastrowid: bool
983 """for backends that support both a lastrowid and a RETURNING insert
984 strategy, favor RETURNING for simple single-int pk inserts.
985
986 cursor.lastrowid tends to be more performant on most backends.
987
988 """
989
990 supports_identity_columns: bool
991 """target database supports IDENTITY"""
992
993 cte_follows_insert: bool
994 """target database, when given a CTE with an INSERT statement, needs
995 the CTE to be below the INSERT"""
996
997 colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]]
998 """A dictionary of TypeEngine classes from sqlalchemy.types mapped
999 to subclasses that are specific to the dialect class. This
1000 dictionary is class-level only and is not accessed from the
1001 dialect instance itself.
1002 """
1003
1004 supports_sequences: bool
1005 """Indicates if the dialect supports CREATE SEQUENCE or similar."""
1006
1007 sequences_optional: bool
1008 """If True, indicates if the :paramref:`_schema.Sequence.optional`
1009 parameter on the :class:`_schema.Sequence` construct
1010 should signal to not generate a CREATE SEQUENCE. Applies only to
1011 dialects that support sequences. Currently used only to allow PostgreSQL
1012 SERIAL to be used on a column that specifies Sequence() for usage on
1013 other backends.
1014 """
1015
1016 default_sequence_base: int
1017 """the default value that will be rendered as the "START WITH" portion of
1018 a CREATE SEQUENCE DDL statement.
1019
1020 """
1021
1022 supports_native_enum: bool
1023 """Indicates if the dialect supports a native ENUM construct.
1024 This will prevent :class:`_types.Enum` from generating a CHECK
1025 constraint when that type is used in "native" mode.
1026 """
1027
1028 supports_native_boolean: bool
1029 """Indicates if the dialect supports a native boolean construct.
1030 This will prevent :class:`_types.Boolean` from generating a CHECK
1031 constraint when that type is used.
1032 """
1033
1034 supports_native_decimal: bool
1035 """indicates if Decimal objects are handled and returned for precision
1036 numeric types, or if floats are returned"""
1037
1038 supports_native_uuid: bool
1039 """indicates if Python UUID() objects are handled natively by the
1040 driver for SQL UUID datatypes.
1041
1042 .. versionadded:: 2.0
1043
1044 """
1045
1046 returns_native_bytes: bool
1047 """indicates if Python bytes() objects are returned natively by the
1048 driver for SQL "binary" datatypes.
1049
1050 .. versionadded:: 2.0.11
1051
1052 """
1053
1054 construct_arguments: Optional[
1055 List[Tuple[Type[Union[SchemaItem, ClauseElement]], Mapping[str, Any]]]
1056 ] = None
1057 """Optional set of argument specifiers for various SQLAlchemy
1058 constructs, typically schema items.
1059
1060 To implement, establish as a series of tuples, as in::
1061
1062 construct_arguments = [
1063 (schema.Index, {
1064 "using": False,
1065 "where": None,
1066 "ops": None
1067 })
1068 ]
1069
1070 If the above construct is established on the PostgreSQL dialect,
1071 the :class:`.Index` construct will now accept the keyword arguments
1072 ``postgresql_using``, ``postgresql_where``, nad ``postgresql_ops``.
1073 Any other argument specified to the constructor of :class:`.Index`
1074 which is prefixed with ``postgresql_`` will raise :class:`.ArgumentError`.
1075
1076 A dialect which does not include a ``construct_arguments`` member will
1077 not participate in the argument validation system. For such a dialect,
1078 any argument name is accepted by all participating constructs, within
1079 the namespace of arguments prefixed with that dialect name. The rationale
1080 here is so that third-party dialects that haven't yet implemented this
1081 feature continue to function in the old way.
1082
1083 .. seealso::
1084
1085 :class:`.DialectKWArgs` - implementing base class which consumes
1086 :attr:`.DefaultDialect.construct_arguments`
1087
1088
1089 """
1090
1091 reflection_options: Sequence[str] = ()
1092 """Sequence of string names indicating keyword arguments that can be
1093 established on a :class:`.Table` object which will be passed as
1094 "reflection options" when using :paramref:`.Table.autoload_with`.
1095
1096 Current example is "oracle_resolve_synonyms" in the Oracle dialect.
1097
1098 """
1099
1100 dbapi_exception_translation_map: Mapping[str, str] = util.EMPTY_DICT
1101 """A dictionary of names that will contain as values the names of
1102 pep-249 exceptions ("IntegrityError", "OperationalError", etc)
1103 keyed to alternate class names, to support the case where a
1104 DBAPI has exception classes that aren't named as they are
1105 referred to (e.g. IntegrityError = MyException). In the vast
1106 majority of cases this dictionary is empty.
1107 """
1108
1109 supports_comments: bool
1110 """Indicates the dialect supports comment DDL on tables and columns."""
1111
1112 inline_comments: bool
1113 """Indicates the dialect supports comment DDL that's inline with the
1114 definition of a Table or Column. If False, this implies that ALTER must
1115 be used to set table and column comments."""
1116
1117 supports_constraint_comments: bool
1118 """Indicates if the dialect supports comment DDL on constraints.
1119
1120 .. versionadded: 2.0
1121 """
1122
1123 _has_events = False
1124
1125 supports_statement_cache: bool = True
1126 """indicates if this dialect supports caching.
1127
1128 All dialects that are compatible with statement caching should set this
1129 flag to True directly on each dialect class and subclass that supports
1130 it. SQLAlchemy tests that this flag is locally present on each dialect
1131 subclass before it will use statement caching. This is to provide
1132 safety for legacy or new dialects that are not yet fully tested to be
1133 compliant with SQL statement caching.
1134
1135 .. versionadded:: 1.4.5
1136
1137 .. seealso::
1138
1139 :ref:`engine_thirdparty_caching`
1140
1141 """
1142
1143 _supports_statement_cache: bool
1144 """internal evaluation for supports_statement_cache"""
1145
1146 bind_typing = BindTyping.NONE
1147 """define a means of passing typing information to the database and/or
1148 driver for bound parameters.
1149
1150 See :class:`.BindTyping` for values.
1151
1152 .. versionadded:: 2.0
1153
1154 """
1155
1156 is_async: bool
1157 """Whether or not this dialect is intended for asyncio use."""
1158
1159 has_terminate: bool
1160 """Whether or not this dialect has a separate "terminate" implementation
1161 that does not block or require awaiting."""
1162
1163 engine_config_types: Mapping[str, Any]
1164 """a mapping of string keys that can be in an engine config linked to
1165 type conversion functions.
1166
1167 """
1168
1169 label_length: Optional[int]
1170 """optional user-defined max length for SQL labels"""
1171
1172 include_set_input_sizes: Optional[Set[Any]]
1173 """set of DBAPI type objects that should be included in
1174 automatic cursor.setinputsizes() calls.
1175
1176 This is only used if bind_typing is BindTyping.SET_INPUT_SIZES
1177
1178 """
1179
1180 exclude_set_input_sizes: Optional[Set[Any]]
1181 """set of DBAPI type objects that should be excluded in
1182 automatic cursor.setinputsizes() calls.
1183
1184 This is only used if bind_typing is BindTyping.SET_INPUT_SIZES
1185
1186 """
1187
1188 supports_simple_order_by_label: bool
1189 """target database supports ORDER BY <labelname>, where <labelname>
1190 refers to a label in the columns clause of the SELECT"""
1191
1192 div_is_floordiv: bool
1193 """target database treats the / division operator as "floor division" """
1194
1195 tuple_in_values: bool
1196 """target database supports tuple IN, i.e. (x, y) IN ((q, p), (r, z))"""
1197
1198 _bind_typing_render_casts: bool
1199
1200 _type_memos: MutableMapping[TypeEngine[Any], _TypeMemoDict]