mysqlengine 1.0.0__cp311-cp311-win_amd64.whl → 1.0.3__cp311-cp311-win_amd64.whl

mysqlengine/dml.py

@@ -2559,8 +2559,22 @@ class DML:
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments for the placeholders in the statement. Defaults to `None`.
 
-        :param cursor `<'type[Cursor]/None'>`: The cursor type (class) to use. Defaults to `None` (use pool default).
-            Determines the data type of the fetched result set after executing the statement.
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
+        :param cursor `<'type[Cursor]/None'>`: The cursor class (type) to use. Defaults to `None` (use pool default).
+            Determines the data type of the fetched result set.
             Also accepts:
             1. `tuple` => `Cursor`;
             2. `dict` => `DictCursor`;
@@ -2619,13 +2633,28 @@ class DML:
         fetch: cython.bint = True,
         many: cython.bint = False,
         conn: object | None = None,
+        batch: cython.bint = False,
     ) -> object:
         """(internal) [async] Execute the DML statement.
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments for the placeholders in the statement. Defaults to `None`.
 
-        :param cursor `<'type[Cursor]/None'>`: The cursor type (class) to use. Defaults to `None` (use pool default).
-            Determines the data type of the fetched result set after executing the statement.
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
+        :param cursor `<'type[Cursor]/None'>`: The cursor class (type) to use. Defaults to `None` (use pool default).
+            Determines the data type of the fetched result set.
             Also accepts:
             1. `tuple` => `Cursor`;
             2. `dict` => `DictCursor`;
@@ -2642,6 +2671,9 @@ class DML:
             If 'conn=None', the statement will be executed by a (random) connection
             from the pool, and commit automatically after the statement execution.
 
+        :param batch `<'bool'>`: Whether to execute the INSERT/REPLACE statement in batch mode. Defaults to `False`.
+            Should only be `True` for INSERT/REPLACE ... VALUES ... statements.
+
         :returns `<'tuple[tuple]/tuple[dict]/DataFrame/int'>`: The result set of the statement.
             Returns the number of affected rows `<'int'>` only when 'fetch=False'.
         """
@@ -2670,8 +2702,8 @@ class DML:
             )
 
         # Connection from pool
-        # . no arguments / single-row
-        if args is None or not many:
+        # . no arguments / single-row / batch-insert
+        if args is None or not many or batch:
             async with self._pool.acquire() as conn:
                 if self._multi_table:
                     await conn.select_database(self._db_name)
@@ -4313,8 +4345,22 @@ class SelectDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments for the placeholders in the statement. Defaults to `None`.
 
-        :param cursor `<'type[Cursor]/None'>`: The cursor type (class) to use. Defaults to `None` (use pool default).
-            Determines the data type of the fetched result set after executing the statement.
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
+        :param cursor `<'type[Cursor]/None'>`: The cursor class (type) to use. Defaults to `None` (use pool default).
+            Determines the data type of the fetched result set.
             Also accepts:
             1. `tuple` => `Cursor`;
             2. `dict` => `DictCursor`;
@@ -4382,8 +4428,22 @@ class SelectDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments for the placeholders in the statement. Defaults to `None`.
 
-        :param cursor `<'type[Cursor]/None'>`: The cursor type (class) to use. Defaults to `None` (use pool default).
-            Determines the data type of the fetched result set after executing the statement.
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
+        :param cursor `<'type[Cursor]/None'>`: The cursor class (type) to use. Defaults to `None` (use pool default).
+            Determines the data type of the fetched result set.
             Also accepts:
             1. `tuple` => `Cursor`;
             2. `dict` => `DictCursor`;
@@ -4437,7 +4497,7 @@ class SelectDML(DML):
             UPDATE ...;
             COMMIT;
         """
-        return await self._aioExecute(args, cursor, fetch, False, conn)
+        return await self._aioExecute(args, cursor, fetch, False, conn, False)
 
     # Validate -----------------------------------------------------------------------------
     @cython.cfunc
@@ -5522,6 +5582,20 @@ class InsertDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -5575,6 +5649,20 @@ class InsertDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -5616,7 +5704,8 @@ class InsertDML(DML):
             INSERT INTO db.tb VALUES (...);
             COMMIT;
         """
-        return await self._aioExecute(args, None, False, many, conn)
+        batch: cython.bint = self._insert_mode == utils.INSERT_MODE.VALUES_MODE
+        return await self._aioExecute(args, None, False, many, conn, batch)
 
     # Validate -----------------------------------------------------------------------------
     @cython.cfunc
@@ -6577,6 +6666,20 @@ class ReplaceDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -6630,6 +6733,20 @@ class ReplaceDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -6671,7 +6788,8 @@ class ReplaceDML(DML):
             REPLACE INTO db.tb VALUES (...);
             COMMIT;
         """
-        return await self._aioExecute(args, None, False, many, conn)
+        batch: cython.bint = self._insert_mode == utils.INSERT_MODE.VALUES_MODE
+        return await self._aioExecute(args, None, False, many, conn, batch)
 
     # Validate -----------------------------------------------------------------------------
     @cython.cfunc
@@ -7277,6 +7395,20 @@ class UpdateDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -7348,6 +7480,20 @@ class UpdateDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -7407,7 +7553,7 @@ class UpdateDML(DML):
             WHERE id=1;
             COMMIT;
         """
-        return await self._aioExecute(args, None, False, many, conn)
+        return await self._aioExecute(args, None, False, many, conn, False)
 
     # Validate -----------------------------------------------------------------------------
     @cython.cfunc
@@ -7983,6 +8129,20 @@ class DeleteDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -8044,6 +8204,20 @@ class DeleteDML(DML):
 
         :param args `<'list/tuple/DataFrame/Any'>`: The arguments (data) for the placeholders in the statement. Defaults to `None`.
 
+            Supports:
+            - **Python built-ins**:
+                int, float, bool, str, None, datetime, date, time,
+                timedelta, struct_time, bytes, bytearray, memoryview,
+                Decimal, dict, list, tuple, set, frozenset, range
+            - **Library [numpy](https://github.com/numpy/numpy)**:
+                np.int, np.uint, np.float, np.bool, np.bytes,
+                np.str, np.datetime64, np.timedelta64, np.ndarray
+            - **Library [pandas](https://github.com/pandas-dev/pandas)**:
+                pd.Timestamp, pd.Timedelta, pd.DatetimeIndex,
+                pd.TimedeltaIndex, pd.Series, pd.DataFrame
+            - **Library [cytimes](https://github.com/AresJef/cyTimes)**:
+                cytimes.Pydt, cytimes.Pddt
+
         :param many `<'bool'>`: Whether the 'args' (data) is multi-rows. Determines how the data is escaped. Defaults to `False`.
             For a single-row data, set 'many=False'. For a multi-row data, set 'many=True'.
 
@@ -8093,7 +8267,7 @@ class DeleteDML(DML):
             DELETE FROM db.tb AS t0 WHERE id=1;
             COMMIT;
         """
-        return await self._aioExecute(args, None, False, many, conn)
+        return await self._aioExecute(args, None, False, many, conn, False)
 
     # Validate -----------------------------------------------------------------------------
     @cython.cfunc