sqlalchemy-cubrid 0.7.1__py3-none-any.whl

sqlalchemy_cubrid/dml.py

@@ -0,0 +1,318 @@
+# sqlalchemy_cubrid/dml.py
+# Copyright (C) 2021-2026 by sqlalchemy-cubrid authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of sqlalchemy-cubrid and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+"""CUBRID DML constructs."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Tuple, Union
+
+from sqlalchemy import exc, util
+from sqlalchemy.sql._typing import _DMLTableArgument
+from sqlalchemy.sql.base import (
+    _exclusive_against,
+    _generative,
+    ColumnCollection,
+    Generative,
+    ReadOnlyColumnCollection,
+)
+from sqlalchemy.sql.dml import Insert as StandardInsert
+from sqlalchemy.sql.elements import ClauseElement, KeyedColumnElement
+from sqlalchemy.sql.expression import Executable, alias
+from sqlalchemy.sql.selectable import NamedFromClause
+from sqlalchemy.util.typing import Self
+
+__all__ = ("Insert", "Merge", "Replace", "insert", "merge", "replace")
+
+_UpdateArg = Union[
+    Mapping[str, Any],
+    List[Tuple[str, Any]],
+]
+
+
+def insert(table: _DMLTableArgument) -> Insert:
+    """Construct a CUBRID-specific variant :class:`Insert` construct.
+
+    Includes :meth:`Insert.on_duplicate_key_update`.
+    """
+    return Insert(table)
+
+
+class Insert(StandardInsert):
+    """CUBRID-specific implementation of INSERT.
+
+    Adds methods for CUBRID-specific syntaxes such as ON DUPLICATE KEY UPDATE.
+    """
+
+    stringify_dialect = "cubrid"
+    inherit_cache = True
+
+    @property
+    def inserted(self) -> ReadOnlyColumnCollection[str, KeyedColumnElement[Any]]:
+        """Provide the "inserted" namespace for an ON DUPLICATE KEY UPDATE statement.
+
+        CUBRID uses VALUES() to reference the row being inserted,
+        identical to MySQL's pre-8.0 syntax.
+        """
+        return self.inserted_alias.columns
+
+    @util.memoized_property
+    def inserted_alias(self) -> NamedFromClause:
+        return alias(self.table, name="inserted")
+
+    @_generative
+    @_exclusive_against(
+        "_post_values_clause",
+        msgs={
+            "_post_values_clause": "This Insert construct already "
+            "has an ON DUPLICATE KEY clause present"
+        },
+    )
+    def on_duplicate_key_update(self, *args: _UpdateArg, **kw: Any) -> Self:
+        """Specifies the ON DUPLICATE KEY UPDATE clause.
+
+        :param **kw: Column keys linked to UPDATE values.
+        :param *args: A dictionary or list of 2-tuples as a single positional argument.
+        """
+        arg_values = list(args)
+        values = kw
+
+        if arg_values and kw:
+            raise exc.ArgumentError("Can't pass kwargs and positional arguments simultaneously")
+        if arg_values:
+            if len(arg_values) > 1:
+                raise exc.ArgumentError(
+                    "Only a single dictionary or list of tuples is accepted positionally."
+                )
+            values = next(iter(arg_values), kw)
+
+        self._post_values_clause = OnDuplicateClause(self.inserted_alias, values)
+        return self
+
+
+def replace(table: _DMLTableArgument) -> Replace:
+    """Construct a CUBRID REPLACE INTO statement.
+
+    CUBRID's REPLACE works like MySQL's REPLACE - it inserts a new row,
+    or if a duplicate key violation occurs, deletes the old row and inserts
+    the new one.
+
+    Usage::
+
+        from sqlalchemy_cubrid import replace
+
+        stmt = replace(users).values(id=1, name="updated")
+    """
+    return Replace(table)
+
+
+class Replace(StandardInsert):
+    """CUBRID-specific REPLACE INTO statement.
+
+    Extends StandardInsert to generate REPLACE INTO instead of INSERT INTO.
+    Supports all standard INSERT syntax (values, from_select, etc.)
+    but does NOT support ON DUPLICATE KEY UPDATE (use Insert for that).
+    """
+
+    stringify_dialect = "cubrid"
+    inherit_cache = True
+    __visit_name__ = "replace"
+
+    @property
+    def _effective_plugin_target(self) -> str:
+        return "insert"
+
+
+class OnDuplicateClause(ClauseElement):
+    __visit_name__ = "on_duplicate_key_update"
+
+    _parameter_ordering: Optional[List[str]] = None
+    update: Dict[str, Any]
+    stringify_dialect = "cubrid"
+
+    def __init__(self, inserted_alias: NamedFromClause, update: _UpdateArg) -> None:
+        self.inserted_alias = inserted_alias
+        if isinstance(update, list) and (update and isinstance(update[0], tuple)):
+            self._parameter_ordering = [key for key, _ in update]
+            update = dict(update)
+        if isinstance(update, dict):
+            if not update:
+                raise ValueError("update parameter dictionary must not be empty")
+        elif isinstance(update, ColumnCollection):
+            update = dict(update)
+        else:
+            raise ValueError(
+                "update parameter must be a non-empty dictionary "
+                "or a ColumnCollection such as the `.c.` collection "
+                "of a Table object"
+            )
+        self.update = update
+
+
+def merge(target: _DMLTableArgument) -> Merge:
+    """Construct a CUBRID-specific MERGE statement.
+
+    CUBRID's MERGE matches rows from a source against a target table
+    using an ON condition, then executes UPDATE for matched rows and/or
+    INSERT for unmatched rows.
+
+    Usage::
+
+        from sqlalchemy_cubrid import merge
+
+        stmt = (
+            merge(target_table)
+            .using(source_table)
+            .on(target_table.c.id == source_table.c.id)
+            .when_matched_then_update({"name": source_table.c.name})
+            .when_not_matched_then_insert({"id": source_table.c.id, "name": source_table.c.name})
+        )
+    """
+    return Merge(target)
+
+
+class Merge(Executable, ClauseElement, Generative):
+    __visit_name__ = "merge"
+    stringify_dialect = "cubrid"
+
+    _target: _DMLTableArgument
+    _using_source: Optional[Any]
+    _on_condition: Optional[ClauseElement]
+    _when_matched: Optional[Dict[str, Any]]
+    _when_not_matched: Optional[Dict[str, Any]]
+
+    def __init__(self, target: _DMLTableArgument) -> None:
+        self._target = target
+        self._using_source = None
+        self._on_condition = None
+        self._when_matched = None
+        self._when_not_matched = None
+
+    @_generative
+    def into(self, target_table: _DMLTableArgument) -> Self:
+        self._target = target_table
+        return self
+
+    @_generative
+    def using(self, source: Any) -> Self:
+        self._using_source = source
+        return self
+
+    @_generative
+    def on(self, condition: ClauseElement) -> Self:
+        self._on_condition = condition
+        return self
+
+    @_generative
+    def when_matched_then_update(
+        self,
+        values_dict: Union[Mapping[Any, Any], List[Tuple[Any, Any]], Tuple[Tuple[Any, Any], ...]],
+        where: Optional[ClauseElement] = None,
+        delete_where: Optional[ClauseElement] = None,
+    ) -> Self:
+        values = self._normalize_key_value_pairs(values_dict, argument_name="values_dict")
+        existing_delete_where = (
+            self._when_matched.get("delete_where") if self._when_matched is not None else None
+        )
+        self._when_matched = {
+            "values": dict(values),
+            "where": where,
+            "delete_where": (delete_where if delete_where is not None else existing_delete_where),
+        }
+        return self
+
+    @_generative
+    def when_matched_then_delete(self, where: Optional[ClauseElement] = None) -> Self:
+        if self._when_matched is None:
+            raise ValueError("WHEN MATCHED UPDATE clause must be specified before DELETE WHERE")
+
+        self._when_matched = {
+            "values": dict(self._when_matched["values"]),
+            "where": self._when_matched.get("where"),
+            "delete_where": where,
+        }
+        return self
+
+    @_generative
+    def when_not_matched_then_insert(
+        self,
+        values_dict_or_column_list: Union[
+            Mapping[Any, Any],
+            List[Tuple[Any, Any]],
+            Tuple[Tuple[Any, Any], ...],
+            List[Any],
+            Tuple[Any, ...],
+        ],
+        where: Optional[ClauseElement] = None,
+    ) -> Self:
+        columns: List[Any]
+        values: List[Any]
+
+        if isinstance(values_dict_or_column_list, Mapping):
+            pairs = self._normalize_key_value_pairs(
+                values_dict_or_column_list,
+                argument_name="values_dict_or_column_list",
+            )
+            columns = [column for column, _ in pairs]
+            values = [value for _, value in pairs]
+        elif isinstance(values_dict_or_column_list, ColumnCollection):
+            pairs = self._normalize_key_value_pairs(
+                dict(values_dict_or_column_list),
+                argument_name="values_dict_or_column_list",
+            )
+            columns = [column for column, _ in pairs]
+            values = [value for _, value in pairs]
+        elif isinstance(values_dict_or_column_list, (list, tuple)):
+            if values_dict_or_column_list and isinstance(values_dict_or_column_list[0], tuple):
+                pairs = self._normalize_key_value_pairs(
+                    list(values_dict_or_column_list),
+                    argument_name="values_dict_or_column_list",
+                )
+                columns = [column for column, _ in pairs]
+                values = [value for _, value in pairs]
+            else:
+                columns = list(values_dict_or_column_list)
+                if not columns:
+                    raise ValueError(
+                        "values_dict_or_column_list must be a non-empty dictionary, "
+                        "a list of tuples, or a non-empty column list"
+                    )
+                values = list(columns)
+        else:
+            raise ValueError(
+                "values_dict_or_column_list must be a non-empty dictionary, "
+                "a list of tuples, or a non-empty column list"
+            )
+
+        self._when_not_matched = {
+            "columns": columns,
+            "values": values,
+            "where": where,
+        }
+        return self
+
+    def _normalize_key_value_pairs(
+        self,
+        values: Union[Mapping[Any, Any], List[Tuple[Any, Any]], Tuple[Tuple[Any, Any], ...]],
+        argument_name: str,
+    ) -> List[Tuple[Any, Any]]:
+        if isinstance(values, Mapping):
+            pairs = list(values.items())
+        elif isinstance(values, list):
+            pairs = list(values)
+        elif isinstance(values, tuple):
+            pairs = list(values)
+        else:
+            raise ValueError(f"{argument_name} must be a non-empty dictionary or a list of tuples")
+
+        if not pairs:
+            raise ValueError(f"{argument_name} must be a non-empty dictionary or a list of tuples")
+
+        if not all(isinstance(pair, tuple) and len(pair) == 2 for pair in pairs):
+            raise ValueError(f"{argument_name} must be a non-empty dictionary or a list of tuples")
+
+        return pairs

sqlalchemy_cubrid/pycubrid_dialect.py

@@ -0,0 +1,124 @@
+# sqlalchemy_cubrid/pycubrid_dialect.py
+# Copyright (C) 2021-2026 by sqlalchemy-cubrid authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of sqlalchemy-cubrid and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+"""CUBRID dialect variant using the pycubrid pure-Python DB-API 2.0 driver."""
+
+from __future__ import annotations
+
+
+from sqlalchemy_cubrid.base import CubridExecutionContext
+from sqlalchemy_cubrid.dialect import CubridDialect
+
+
+class PyCubridExecutionContext(CubridExecutionContext):
+    """Execution context for pycubrid connections.
+
+    pycubrid exposes ``cursor.lastrowid`` as a proper ``int | None``,
+    so we use it directly instead of the CUBRIDdb workaround.
+    """
+
+    def get_lastrowid(self):
+        """Return the last inserted row ID from pycubrid's cursor."""
+        try:
+            return self.cursor.lastrowid
+        except AttributeError:
+            pass
+
+        # Fallback: use SQL function
+        cursor = self.create_server_side_cursor()
+        try:
+            cursor.execute("SELECT LAST_INSERT_ID()")
+            row = cursor.fetchone()
+            if row:
+                return int(row[0])
+        finally:
+            cursor.close()
+        return None
+
+
+class PyCubridDialect(CubridDialect):
+    """SQLAlchemy dialect for CUBRID using the pycubrid pure-Python driver.
+
+    Connection URL: ``cubrid+pycubrid://user:password@host:port/dbname``
+
+    This dialect subclasses :class:`CubridDialect` and overrides only
+    the driver-specific methods: ``import_dbapi``, ``create_connect_args``,
+    ``on_connect``, and ``do_ping``.  All SQL compilation, type mapping,
+    and schema reflection is inherited unchanged.
+    """
+
+    driver = "pycubrid"
+    supports_statement_cache = True
+    execution_ctx_cls = PyCubridExecutionContext
+
+    # pycubrid uses qmark paramstyle natively
+    default_paramstyle = "qmark"
+
+    @classmethod
+    def import_dbapi(cls):
+        """Import and return the pycubrid DBAPI module."""
+        try:
+            import pycubrid as dbapi_module
+        except ImportError as e:
+            raise e
+        return dbapi_module
+
+    # Keep legacy dbapi() for SA 1.x compat
+    @classmethod
+    def dbapi(cls):
+        return cls.import_dbapi()
+
+    def create_connect_args(self, url):
+        """Build DB-API connection arguments for pycubrid.
+
+        pycubrid accepts keyword arguments directly::
+
+            pycubrid.connect(host=..., port=..., database=..., user=..., password=...)
+        """
+        if url is None:
+            raise ValueError("Unexpected database URL format")
+
+        opts = url.translate_connect_args(username="user", database="database")
+        return (), {
+            "host": opts.get("host", "localhost"),
+            "port": opts.get("port", 33000),
+            "database": opts.get("database", ""),
+            "user": opts.get("user", "dba"),
+            "password": opts.get("password", ""),
+        }
+
+    def on_connect(self):
+        """Return a callable to set up a new pycubrid connection.
+
+        Disables autocommit so that SQLAlchemy manages transactions.
+        """
+        isolation_level = self.isolation_level
+
+        def connect(conn):
+            # pycubrid uses a property setter for autocommit
+            conn.autocommit = False
+            if isolation_level is not None:
+                self.set_isolation_level(conn, isolation_level)
+
+        return connect
+
+    def do_ping(self, dbapi_connection):
+        """Ping the server to check connection liveness.
+
+        pycubrid does not expose a native ``ping()`` method, so we
+        execute a lightweight query instead.
+        """
+        cursor = dbapi_connection.cursor()
+        try:
+            cursor.execute("SELECT 1")
+            cursor.fetchone()
+        finally:
+            cursor.close()
+        return True
+
+
+dialect = PyCubridDialect

sqlalchemy_cubrid/requirements.py

@@ -0,0 +1,270 @@
+# sqlalchemy_cubrid/requirements.py
+# Copyright (C) 2021-2026 by sqlalchemy-cubrid authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of sqlalchemy-cubrid and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+"""CUBRID test-suite requirement flags.
+
+These tell SQLAlchemy's built-in test suite which features this dialect
+supports so tests are automatically skipped when the feature is absent.
+
+Reference: https://github.com/sqlalchemy/sqlalchemy/blob/main/README.dialects.rst
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.testing import exclusions
+from sqlalchemy.testing.requirements import SuiteRequirements
+
+
+class Requirements(SuiteRequirements):
+    """CUBRID-specific requirement flags for the SA test suite."""
+
+    # ----- RETURNING -----
+
+    @property
+    def returning(self):
+        """CUBRID does not support INSERT/UPDATE/DELETE … RETURNING."""
+        return exclusions.closed()
+
+    @property
+    def insert_returning(self):
+        return exclusions.closed()
+
+    @property
+    def update_returning(self):
+        return exclusions.closed()
+
+    @property
+    def delete_returning(self):
+        return exclusions.closed()
+
+    # ----- Booleans -----
+
+    @property
+    def nullable_booleans(self):
+        """CUBRID maps BOOLEAN to SMALLINT which is nullable."""
+        return exclusions.open()
+
+    @property
+    def non_native_boolean_unconstrained(self):
+        """The SMALLINT emulation has no CHECK constraint."""
+        return exclusions.open()
+
+    # ----- Sequences -----
+
+    @property
+    def sequences(self):
+        """CUBRID does not support sequences."""
+        return exclusions.closed()
+
+    @property
+    def sequences_optional(self):
+        return exclusions.closed()
+
+    # ----- Schema / DDL -----
+
+    @property
+    def schemas(self):
+        """CUBRID does not support multiple schemas."""
+        return exclusions.closed()
+
+    @property
+    def temp_table_names(self):
+        return exclusions.closed()
+
+    @property
+    def temporary_tables(self):
+        return exclusions.closed()
+
+    @property
+    def temporary_views(self):
+        return exclusions.closed()
+
+    @property
+    def table_ddl_if_exists(self):
+        """CUBRID supports IF NOT EXISTS / IF EXISTS in DDL."""
+        return exclusions.open()
+
+    @property
+    def comment_reflection(self):
+        """CUBRID supports table and column comments."""
+        return exclusions.open()
+
+    @property
+    def check_constraint_reflection(self):
+        return exclusions.closed()
+
+    # ----- DML -----
+
+    @property
+    def empty_inserts(self):
+        """CUBRID supports INSERT INTO t DEFAULT VALUES."""
+        return exclusions.open()
+
+    @property
+    def insert_from_select(self):
+        return exclusions.open()
+
+    @property
+    def ctes(self):
+        """CUBRID 11 supports CTEs."""
+        return exclusions.open()
+
+    @property
+    def ctes_on_dml(self):
+        return exclusions.closed()
+
+    # ----- SELECT features -----
+
+    @property
+    def window_functions(self):
+        """CUBRID supports window functions (ROW_NUMBER, RANK, etc.) with OVER()."""
+        return exclusions.open()
+
+    @property
+    def intersect(self):
+        return exclusions.open()
+
+    @property
+    def except_(self):
+        return exclusions.open()
+
+    @property
+    def fetch_no_order(self):
+        return exclusions.open()
+
+    @property
+    def order_by_col_from_union(self):
+        return exclusions.open()
+
+    # ----- Type support -----
+
+    @property
+    def unicode_ddl(self):
+        return exclusions.open()
+
+    @property
+    def datetime_literals(self):
+        return exclusions.closed()
+
+    @property
+    def date(self):
+        return exclusions.open()
+
+    @property
+    def time(self):
+        return exclusions.open()
+
+    @property
+    def datetime(self):
+        return exclusions.open()
+
+    @property
+    def timestamp(self):
+        return exclusions.open()
+
+    @property
+    def text_type(self):
+        return exclusions.open()
+
+    @property
+    def json_type(self):
+        """CUBRID does not support JSON type."""
+        return exclusions.closed()
+
+    @property
+    def array_type(self):
+        return exclusions.closed()
+
+    @property
+    def uuid_data_type(self):
+        return exclusions.closed()
+
+    # ----- Misc -----
+
+    @property
+    def views(self):
+        return exclusions.open()
+
+    @property
+    def savepoints(self):
+        return exclusions.open()
+
+    @property
+    def foreign_keys(self):
+        return exclusions.open()
+
+    @property
+    def self_referential_foreign_keys(self):
+        return exclusions.open()
+
+    @property
+    def unique_constraint_reflection(self):
+        return exclusions.open()
+
+    @property
+    def foreign_key_constraint_reflection(self):
+        return exclusions.open()
+
+    @property
+    def index_reflection(self):
+        return exclusions.open()
+
+    @property
+    def primary_key_constraint_reflection(self):
+        return exclusions.open()
+
+    @property
+    def on_update_cascade(self):
+        return exclusions.open()
+
+    @property
+    def on_delete_cascade(self):
+        return exclusions.open()
+
+    @property
+    def server_side_cursors(self):
+        return exclusions.closed()
+
+    @property
+    def independent_connections(self):
+        return exclusions.open()
+
+    # ----- Binary / LOB -----
+
+    @property
+    def binary_comparisons(self):
+        """CUBRID BLOB roundtrip has driver-level issues."""
+        return exclusions.closed()
+
+    @property
+    def binary_literals(self):
+        """CUBRID does not support binary literal syntax."""
+        return exclusions.closed()
+
+    # ----- Identifier quoting -----
+
+    @property
+    def unusual_column_name_characters(self):
+        """CUBRID has limited support for special characters in identifiers."""
+        return exclusions.closed()
+
+    @property
+    def implicitly_named_constraints(self):
+        """CUBRID FK reflection has issues with special-character table names."""
+        return exclusions.closed()
+
+    # ----- SELECT FOR UPDATE -----
+
+    @property
+    def update_nowait(self):
+        """CUBRID does not support SELECT ... FOR UPDATE NOWAIT."""
+        return exclusions.closed()
+
+    @property
+    def for_update(self):
+        """CUBRID supports SELECT ... FOR UPDATE [OF col1, col2]."""
+        return exclusions.open()