SQLAlchemy 2.1.0rc1__cp315-cp315-win32.whl

sqlalchemy/dialects/mysql/mysqlconnector.py

@@ -0,0 +1,291 @@
+# dialects/mysql/mysqlconnector.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+
+
+r"""
+.. dialect:: mysql+mysqlconnector
+    :name: MySQL Connector/Python
+    :dbapi: myconnpy
+    :connectstring: mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>
+    :url: https://pypi.org/project/mysql-connector-python/
+
+Driver Status
+-------------
+
+MySQL Connector/Python is supported as of SQLAlchemy 2.0.39 to the
+degree which the driver is functional.   There are still ongoing issues
+with features such as server side cursors which remain disabled until
+upstream issues are repaired.
+
+.. warning:: The MySQL Connector/Python driver published by Oracle is subject
+   to frequent, major regressions of essential functionality such as being able
+   to correctly persist simple binary strings which indicate it is not well
+   tested.  The SQLAlchemy project is not able to maintain this dialect fully as
+   regressions in the driver prevent it from being included in continuous
+   integration.
+
+.. versionchanged:: 2.0.39
+
+    The MySQL Connector/Python dialect has been updated to support the
+    latest version of this DBAPI.   Previously, MySQL Connector/Python
+    was not fully supported.  However, support remains limited due to ongoing
+    regressions introduced in this driver.
+
+Connecting to MariaDB with MySQL Connector/Python
+--------------------------------------------------
+
+MySQL Connector/Python may attempt to pass an incompatible collation to the
+database when connecting to MariaDB.  Experimentation has shown that using
+``?charset=utf8mb4&collation=utfmb4_general_ci`` or similar MariaDB-compatible
+charset/collation will allow connectivity.
+
+
+"""  # noqa
+
+from __future__ import annotations
+
+from typing import Any
+from typing import cast
+from typing import Optional
+from typing import Sequence
+from typing import TYPE_CHECKING
+from typing import Union
+
+from .base import MySQLCompiler
+from .base import MySQLDialect
+from .base import MySQLExecutionContext
+from .base import MySQLIdentifierPreparer
+from .mariadb import MariaDBDialect
+from .types import BIT
+from ... import util
+
+if TYPE_CHECKING:
+
+    from ...engine.base import Connection
+    from ...engine.cursor import CursorResult
+    from ...engine.interfaces import ConnectArgsType
+    from ...engine.interfaces import DBAPIConnection
+    from ...engine.interfaces import DBAPICursor
+    from ...engine.interfaces import DBAPIModule
+    from ...engine.interfaces import IsolationLevel
+    from ...engine.interfaces import PoolProxiedConnection
+    from ...engine.row import Row
+    from ...engine.url import URL
+    from ...sql.elements import BinaryExpression
+    from ...util.typing import TupleAny
+    from ...util.typing import Unpack
+
+
+class MySQLExecutionContext_mysqlconnector(MySQLExecutionContext):
+    def create_server_side_cursor(self) -> DBAPICursor:
+        return self._dbapi_connection.cursor(buffered=False)
+
+    def create_default_cursor(self) -> DBAPICursor:
+        return self._dbapi_connection.cursor(buffered=True)
+
+
+class MySQLCompiler_mysqlconnector(MySQLCompiler):
+    def visit_mod_binary(
+        self, binary: BinaryExpression[Any], operator: Any, **kw: Any
+    ) -> str:
+        return (
+            self.process(binary.left, **kw)
+            + " % "
+            + self.process(binary.right, **kw)
+        )
+
+
+class IdentifierPreparerCommon_mysqlconnector:
+    @property
+    def _double_percents(self) -> bool:
+        return False
+
+    @_double_percents.setter
+    def _double_percents(self, value: Any) -> None:
+        pass
+
+    def _escape_identifier(self, value: str) -> str:
+        value = value.replace(
+            self.escape_quote,  # type: ignore[attr-defined]
+            self.escape_to_quote,  # type: ignore[attr-defined]
+        )
+        return value
+
+
+class MySQLIdentifierPreparer_mysqlconnector(
+    IdentifierPreparerCommon_mysqlconnector, MySQLIdentifierPreparer
+):
+    pass
+
+
+class _myconnpyBIT(BIT):
+    def result_processor(self, dialect: Any, coltype: Any) -> None:
+        """MySQL-connector already converts mysql bits, so."""
+
+        return None
+
+
+class MySQLDialect_mysqlconnector(MySQLDialect):
+    driver = "mysqlconnector"
+    supports_statement_cache = True
+
+    supports_sane_rowcount = True
+    supports_sane_multi_rowcount = True
+
+    supports_native_decimal = True
+
+    supports_native_bit = True
+
+    # not until https://bugs.mysql.com/bug.php?id=117548
+    supports_server_side_cursors = False
+
+    default_paramstyle = "format"
+    statement_compiler = MySQLCompiler_mysqlconnector
+
+    execution_ctx_cls = MySQLExecutionContext_mysqlconnector
+
+    preparer: type[MySQLIdentifierPreparer] = (
+        MySQLIdentifierPreparer_mysqlconnector
+    )
+
+    colspecs = util.update_copy(MySQLDialect.colspecs, {BIT: _myconnpyBIT})
+
+    @classmethod
+    def import_dbapi(cls) -> DBAPIModule:
+        return cast("DBAPIModule", __import__("mysql.connector").connector)
+
+    def do_ping(self, dbapi_connection: DBAPIConnection) -> bool:
+        dbapi_connection.ping(False)
+        return True
+
+    def create_connect_args(self, url: URL) -> ConnectArgsType:
+        opts = url.translate_connect_args(username="user")
+
+        opts.update(url.query)
+
+        util.coerce_kw_type(opts, "allow_local_infile", bool)
+        util.coerce_kw_type(opts, "autocommit", bool)
+        util.coerce_kw_type(opts, "buffered", bool)
+        util.coerce_kw_type(opts, "client_flag", int)
+        util.coerce_kw_type(opts, "compress", bool)
+        util.coerce_kw_type(opts, "connection_timeout", int)
+        util.coerce_kw_type(opts, "connect_timeout", int)
+        util.coerce_kw_type(opts, "consume_results", bool)
+        util.coerce_kw_type(opts, "force_ipv6", bool)
+        util.coerce_kw_type(opts, "get_warnings", bool)
+        util.coerce_kw_type(opts, "pool_reset_session", bool)
+        util.coerce_kw_type(opts, "pool_size", int)
+        util.coerce_kw_type(opts, "raise_on_warnings", bool)
+        util.coerce_kw_type(opts, "raw", bool)
+        util.coerce_kw_type(opts, "ssl_verify_cert", bool)
+        util.coerce_kw_type(opts, "use_pure", bool)
+        util.coerce_kw_type(opts, "use_unicode", bool)
+
+        # note that "buffered" is set to False by default in MySQL/connector
+        # python.  If you set it to True, then there is no way to get a server
+        # side cursor because the logic is written to disallow that.
+
+        # leaving this at True until
+        # https://bugs.mysql.com/bug.php?id=117548 can be fixed
+        opts["buffered"] = True
+
+        # FOUND_ROWS must be set in ClientFlag to enable
+        # supports_sane_rowcount.
+        if self.dbapi is not None:
+            try:
+                from mysql.connector import constants  # type: ignore[import-not-found]  # noqa: E501
+
+                ClientFlag = constants.ClientFlag
+
+                client_flags = opts.get(
+                    "client_flags", ClientFlag.get_default()
+                )
+                client_flags |= ClientFlag.FOUND_ROWS
+                opts["client_flags"] = client_flags
+            except Exception:
+                pass
+
+        return [], opts
+
+    def retrieve_dbapi_version(self, dbapi: DBAPIModule) -> util.VersionInfo:
+        return util.parse_version_string(getattr(dbapi, "__version__", None))
+
+    def _detect_charset(self, connection: Connection) -> str:
+        return connection.connection.charset  # type: ignore[no-any-return]
+
+    def _extract_error_code(self, exception: BaseException) -> int:
+        return exception.errno  # type: ignore[attr-defined, no-any-return]
+
+    def is_disconnect(
+        self,
+        e: Exception,
+        connection: Optional[Union[PoolProxiedConnection, DBAPIConnection]],
+        cursor: Optional[DBAPICursor],
+    ) -> bool:
+        errnos = (2006, 2013, 2014, 2045, 2055, 2048)
+        exceptions = (
+            self.loaded_dbapi.OperationalError,  #
+            self.loaded_dbapi.InterfaceError,
+            self.loaded_dbapi.ProgrammingError,
+        )
+        if isinstance(e, exceptions):
+            return (
+                e.errno in errnos
+                or "MySQL Connection not available." in str(e)
+                or "Connection to MySQL is not available" in str(e)
+            )
+        else:
+            return False
+
+    def _compat_fetchall(
+        self,
+        rp: CursorResult[Unpack[TupleAny]],
+        charset: Optional[str] = None,
+    ) -> Sequence[Row[Unpack[TupleAny]]]:
+        return rp.fetchall()
+
+    def _compat_fetchone(
+        self,
+        rp: CursorResult[Unpack[TupleAny]],
+        charset: Optional[str] = None,
+    ) -> Optional[Row[Unpack[TupleAny]]]:
+        return rp.fetchone()
+
+    def get_isolation_level_values(
+        self, dbapi_conn: DBAPIConnection
+    ) -> Sequence[IsolationLevel]:
+        return (
+            "SERIALIZABLE",
+            "READ UNCOMMITTED",
+            "READ COMMITTED",
+            "REPEATABLE READ",
+            "AUTOCOMMIT",
+        )
+
+    def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
+        return bool(dbapi_conn.autocommit)
+
+    def set_isolation_level(
+        self, dbapi_connection: DBAPIConnection, level: IsolationLevel
+    ) -> None:
+        if level == "AUTOCOMMIT":
+            dbapi_connection.autocommit = True
+        else:
+            dbapi_connection.autocommit = False
+            super().set_isolation_level(dbapi_connection, level)
+
+
+class MariaDBDialect_mysqlconnector(
+    MariaDBDialect, MySQLDialect_mysqlconnector
+):
+    supports_statement_cache = True
+    _allows_uuid_binds = False
+    preparer = MySQLIdentifierPreparer_mysqlconnector
+
+
+dialect = MySQLDialect_mysqlconnector
+mariadb_dialect = MariaDBDialect_mysqlconnector

sqlalchemy/dialects/mysql/mysqldb.py

@@ -0,0 +1,318 @@
+# dialects/mysql/mysqldb.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+
+"""
+
+.. dialect:: mysql+mysqldb
+    :name: mysqlclient (maintained fork of MySQL-Python)
+    :dbapi: mysqldb
+    :connectstring: mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>
+    :url: https://pypi.org/project/mysqlclient/
+
+Driver Status
+-------------
+
+The mysqlclient DBAPI is a maintained fork of the
+`MySQL-Python <https://sourceforge.net/projects/mysql-python>`_ DBAPI
+that is no longer maintained.  `mysqlclient`_ supports Python 2 and Python 3
+and is very stable.
+
+.. _mysqlclient: https://github.com/PyMySQL/mysqlclient-python
+
+.. _mysqldb_unicode:
+
+Unicode
+-------
+
+Please see :ref:`mysql_unicode` for current recommendations on unicode
+handling.
+
+.. _mysqldb_ssl:
+
+SSL Connections
+----------------
+
+The mysqlclient and PyMySQL DBAPIs accept an additional dictionary under the
+key "ssl", which may be specified using the
+:paramref:`_sa.create_engine.connect_args` dictionary::
+
+    engine = create_engine(
+        "mysql+mysqldb://scott:tiger@192.168.0.134/test",
+        connect_args={
+            "ssl": {
+                "ca": "/home/gord/client-ssl/ca.pem",
+                "cert": "/home/gord/client-ssl/client-cert.pem",
+                "key": "/home/gord/client-ssl/client-key.pem",
+            }
+        },
+    )
+
+For convenience, the following keys may also be specified inline within the URL
+where they will be interpreted into the "ssl" dictionary automatically:
+"ssl_ca", "ssl_cert", "ssl_key", "ssl_capath", "ssl_cipher",
+"ssl_check_hostname". An example is as follows::
+
+    connection_uri = (
+        "mysql+mysqldb://scott:tiger@192.168.0.134/test"
+        "?ssl_ca=/home/gord/client-ssl/ca.pem"
+        "&ssl_cert=/home/gord/client-ssl/client-cert.pem"
+        "&ssl_key=/home/gord/client-ssl/client-key.pem"
+    )
+
+.. seealso::
+
+    :ref:`pymysql_ssl` in the PyMySQL dialect
+
+
+Using MySQLdb with Google Cloud SQL
+-----------------------------------
+
+Google Cloud SQL now recommends use of the MySQLdb dialect.  Connect
+using a URL like the following:
+
+.. sourcecode:: text
+
+    mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename>
+
+Server Side Cursors
+-------------------
+
+The mysqldb dialect supports server-side cursors. See :ref:`mysql_ss_cursors`.
+
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any
+from typing import Callable
+from typing import cast
+from typing import Literal
+from typing import Optional
+from typing import TYPE_CHECKING
+
+from .base import MySQLCompiler
+from .base import MySQLDialect
+from .base import MySQLExecutionContext
+from .base import MySQLIdentifierPreparer
+from ... import util
+
+if TYPE_CHECKING:
+
+    from ...engine.base import Connection
+    from ...engine.interfaces import _DBAPIMultiExecuteParams
+    from ...engine.interfaces import ConnectArgsType
+    from ...engine.interfaces import DBAPIConnection
+    from ...engine.interfaces import DBAPICursor
+    from ...engine.interfaces import DBAPIModule
+    from ...engine.interfaces import ExecutionContext
+    from ...engine.interfaces import IsolationLevel
+    from ...engine.url import URL
+
+
+class MySQLExecutionContext_mysqldb(MySQLExecutionContext):
+    pass
+
+
+class MySQLCompiler_mysqldb(MySQLCompiler):
+    pass
+
+
+class MySQLDialect_mysqldb(MySQLDialect):
+    driver = "mysqldb"
+    supports_statement_cache = True
+    supports_unicode_statements = True
+    supports_sane_rowcount = True
+    supports_sane_multi_rowcount = True
+
+    supports_native_decimal = True
+
+    default_paramstyle = "format"
+    execution_ctx_cls = MySQLExecutionContext_mysqldb
+    statement_compiler = MySQLCompiler_mysqldb
+    preparer = MySQLIdentifierPreparer
+    server_version_info: tuple[int, ...]
+
+    def retrieve_dbapi_version(self, dbapi: DBAPIModule) -> util.VersionInfo:
+        # mysqlclient publishes ``version_info``, a tuple in the style of
+        # ``sys.version_info`` such as ``(2, 2, 7, "final", 0)``, and no
+        # version string of its own; MySQL-python published
+        # ``__version__``.  cymysql, which subclasses this dialect, also
+        # publishes ``__version__``.  pymysql publishes both of these as
+        # mysqlclient compatibility values rather than as its own version,
+        # so that dialect overrides this method; the asyncio dialects
+        # likewise override as their DBAPI is a wrapper module.
+        version_info = getattr(dbapi, "version_info", None)
+        if version_info is not None:
+            return util.VersionInfo(
+                tuple(
+                    itertools.takewhile(
+                        lambda part: isinstance(part, int), version_info
+                    )
+                )
+            )
+        return util.parse_version_string(getattr(dbapi, "__version__", None))
+
+    @util.langhelpers.memoized_property
+    def supports_server_side_cursors(self) -> bool:
+        try:
+            cursors = __import__("MySQLdb.cursors").cursors
+            self._sscursor = cursors.SSCursor
+            return True
+        except (ImportError, AttributeError):
+            return False
+
+    @classmethod
+    def import_dbapi(cls) -> DBAPIModule:
+        return __import__("MySQLdb")
+
+    def on_connect(self) -> Callable[[DBAPIConnection], None]:
+        super_ = super().on_connect()
+
+        def on_connect(conn: DBAPIConnection) -> None:
+            if super_ is not None:
+                super_(conn)
+
+            charset_name = conn.character_set_name()
+
+            if charset_name is not None:
+                cursor = conn.cursor()
+                cursor.execute("SET NAMES %s" % charset_name)
+                cursor.close()
+
+        return on_connect
+
+    def do_ping(self, dbapi_connection: DBAPIConnection) -> Literal[True]:
+        dbapi_connection.ping()
+        return True
+
+    def do_executemany(
+        self,
+        cursor: DBAPICursor,
+        statement: str,
+        parameters: _DBAPIMultiExecuteParams,
+        context: Optional[ExecutionContext] = None,
+    ) -> None:
+        rowcount = cursor.executemany(statement, parameters)
+        if context is not None:
+            cast(MySQLExecutionContext, context)._rowcount = rowcount
+
+    def create_connect_args(
+        self, url: URL, _translate_args: Optional[dict[str, Any]] = None
+    ) -> ConnectArgsType:
+        if _translate_args is None:
+            _translate_args = dict(
+                database="db", username="user", password="passwd"
+            )
+
+        opts = url.translate_connect_args(**_translate_args)
+        opts.update(url.query)
+
+        util.coerce_kw_type(opts, "compress", bool)
+        util.coerce_kw_type(opts, "connect_timeout", int)
+        util.coerce_kw_type(opts, "read_timeout", int)
+        util.coerce_kw_type(opts, "write_timeout", int)
+        util.coerce_kw_type(opts, "client_flag", int)
+        util.coerce_kw_type(opts, "local_infile", bool)
+        # Note: using either of the below will cause all strings to be
+        # returned as Unicode, both in raw SQL operations and with column
+        # types like String and MSString.
+        util.coerce_kw_type(opts, "use_unicode", bool)
+        util.coerce_kw_type(opts, "charset", str)
+
+        # Rich values 'cursorclass' and 'conv' are not supported via
+        # query string.
+
+        ssl = {}
+        keys = [
+            ("ssl_ca", str),
+            ("ssl_key", str),
+            ("ssl_cert", str),
+            ("ssl_capath", str),
+            ("ssl_cipher", str),
+            ("ssl_check_hostname", bool),
+        ]
+        for key, kw_type in keys:
+            if key in opts:
+                ssl[key[4:]] = opts[key]
+                util.coerce_kw_type(ssl, key[4:], kw_type)
+                del opts[key]
+        if ssl:
+            opts["ssl"] = ssl
+
+        # FOUND_ROWS must be set in CLIENT_FLAGS to enable
+        # supports_sane_rowcount.
+        client_flag = opts.get("client_flag", 0)
+
+        client_flag_found_rows = self._found_rows_client_flag()
+        if client_flag_found_rows is not None:
+            client_flag |= client_flag_found_rows
+            opts["client_flag"] = client_flag
+        return [], opts
+
+    def _found_rows_client_flag(self) -> Optional[int]:
+        if self.dbapi is not None:
+            try:
+                CLIENT_FLAGS = __import__(
+                    self.dbapi.__name__ + ".constants.CLIENT"
+                ).constants.CLIENT
+            except (AttributeError, ImportError):
+                return None
+            else:
+                return CLIENT_FLAGS.FOUND_ROWS  # type: ignore[no-any-return]
+        else:
+            return None
+
+    def _extract_error_code(self, exception: DBAPIModule.Error) -> int:
+        return exception.args[0]  # type: ignore[no-any-return]
+
+    def _detect_charset(self, connection: Connection) -> str:
+        """Sniff out the character set in use for connection results."""
+
+        try:
+            # note: the SQL here would be
+            # "SHOW VARIABLES LIKE 'character_set%%'"
+
+            cset_name: Callable[[], str] = (
+                connection.connection.character_set_name
+            )
+        except AttributeError:
+            util.warn(
+                "No 'character_set_name' can be detected with "
+                "this MySQL-Python version; "
+                "please upgrade to a recent version of MySQL-Python.  "
+                "Assuming latin1."
+            )
+            return "latin1"
+        else:
+            return cset_name()
+
+    def get_isolation_level_values(
+        self, dbapi_conn: DBAPIConnection
+    ) -> tuple[IsolationLevel, ...]:
+        return (
+            "SERIALIZABLE",
+            "READ UNCOMMITTED",
+            "READ COMMITTED",
+            "REPEATABLE READ",
+            "AUTOCOMMIT",
+        )
+
+    def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
+        return dbapi_conn.get_autocommit()  # type: ignore[no-any-return]
+
+    def set_isolation_level(
+        self, dbapi_connection: DBAPIConnection, level: IsolationLevel
+    ) -> None:
+        if level == "AUTOCOMMIT":
+            dbapi_connection.autocommit(True)
+        else:
+            dbapi_connection.autocommit(False)
+            super().set_isolation_level(dbapi_connection, level)
+
+
+dialect = MySQLDialect_mysqldb