Modified implementation to take in user input as string, not list

Author: mpak123

pandas/io/sql.py

@@ -231,39 +231,16 @@ def _wrap_result_adbc(
     return df
 
 
-def _process_sql_hints(
-    hints: dict[str, str | list[str]] | None, dialect_name: str
-) -> str | None:
-    if hints is None or not hints:
+def _process_sql_hints(hints: dict[str, str] | None, dialect_name: str) -> str | None:
+    if hints is None:
         return None
 
     dialect_name = dialect_name.lower()
-
-    hint_value = None
     for key, value in hints.items():
         if key.lower() == dialect_name:
-            hint_value = value
-            break
-
-    if hint_value is None:
-        return None
+            return value
 
-    if isinstance(hint_value, list):
-        hint_str = " ".join(hint_value)
-    else:
-        hint_str = str(hint_value)
-
-    if hint_str.strip().startswith("/*+") and hint_str.strip().endswith("*/"):
-        return hint_str.strip()
-
-    if dialect_name == "oracle":
-        return f"/*+ {hint_str} */"
-    elif dialect_name == "mysql":
-        return hint_str
-    elif dialect_name == "mssql":
-        return hint_str
-    else:
-        return f"/*+ {hint_str} */"
+    return None
 
 
 # -----------------------------------------------------------------------------
@@ -784,7 +761,7 @@ def to_sql(
     dtype: DtypeArg | None = None,
     method: Literal["multi"] | Callable | None = None,
     engine: str = "auto",
-    hints: dict[str, str | list[str]] | None = None,
+    hints: dict[str, str] | None = None,
     **engine_kwargs,
 ) -> int | None:
     """
@@ -845,6 +822,23 @@ def to_sql(
 
         .. versionadded:: 1.3.0
 
+    hints : dict[str, str], optional
+        SQL hints to optimize insertion performance, keyed by database dialect name.
+        Each hint should be a complete string formatted exactly as required by the
+        target database. The user is responsible for constructing dialect-specific
+        syntax.
+
+        Examples: ``{'oracle': '/*+ APPEND PARALLEL(4) */'}``
+                  ``{'mysql': 'DELAYED'}``
+                  ``{'mssql': 'WITH (TABLOCK)'}``
+
+        .. note::
+            - Hints are database-specific and will be ignored for unsupported dialects
+            - SQLite will raise a UserWarning (hints not supported)
+            - ADBC connections will raise NotImplementedError
+
+        .. versionadded::
+
     **engine_kwargs
         Any additional kwargs are passed to the engine.
 
@@ -1142,7 +1136,7 @@ def insert(
         self,
         chunksize: int | None = None,
         method: Literal["multi"] | Callable | None = None,
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         dialect_name: str | None = None,
     ) -> int | None:
         # set insert method
@@ -1570,7 +1564,7 @@ def to_sql(
         chunksize: int | None = None,
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         engine: str = "auto",
         **engine_kwargs,
     ) -> int | None:
@@ -1607,7 +1601,7 @@ def insert_records(
         schema=None,
         chunksize: int | None = None,
         method=None,
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         dialect_name: str | None = None,
         **engine_kwargs,
     ) -> int | None:
@@ -1633,7 +1627,7 @@ def insert_records(
         schema=None,
         chunksize: int | None = None,
         method=None,
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         dialect_name: str | None = None,
         **engine_kwargs,
     ) -> int | None:
@@ -2047,7 +2041,7 @@ def to_sql(
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
         engine: str = "auto",
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         **engine_kwargs,
     ) -> int | None:
         """
@@ -2414,7 +2408,7 @@ def to_sql(
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
         engine: str = "auto",
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         **engine_kwargs,
     ) -> int | None:
         """
@@ -2894,7 +2888,7 @@ def to_sql(
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
         engine: str = "auto",
-        hints: dict[str, str | list[str]] | None = None,
+        hints: dict[str, str] | None = None,
         **engine_kwargs,
     ) -> int | None:
         """

pandas/tests/io/test_sql.py

@@ -4407,31 +4407,25 @@ def test_xsqlite_if_exists(sqlite_buildin):
 class TestProcessSQLHints:
     """Tests for _process_sql_hints helper function."""
 
-    def test_process_sql_hints_oracle_list(self):
-        """Test hint processing with Oracle dialect and list input."""
-        hints = {"oracle": ["APPEND", "PARALLEL"]}
-        result = sql._process_sql_hints(hints, "oracle")
-        assert result == "/*+ APPEND PARALLEL */"
-
     def test_process_sql_hints_oracle_string(self):
-        """Test hint processing with Oracle dialect and string input."""
-        hints = {"oracle": "APPEND PARALLEL"}
+        """Test hint processing with Oracle dialect - user provides complete string."""
+        hints = {"oracle": "/*+ APPEND PARALLEL */"}
         result = sql._process_sql_hints(hints, "oracle")
         assert result == "/*+ APPEND PARALLEL */"
 
-    def test_process_sql_hints_preformatted(self):
-        """Test that pre-formatted hints are returned as-is."""
-        hints = {"oracle": "/*+ APPEND PARALLEL */"}
+    def test_process_sql_hints_oracle_simple(self):
+        """Test hint processing with simple Oracle hint string."""
+        hints = {"oracle": "/*+ PARALLEL */"}
         result = sql._process_sql_hints(hints, "oracle")
-        assert result == "/*+ APPEND PARALLEL */"
+        assert result == "/*+ PARALLEL */"
 
     def test_process_sql_hints_case_insensitive(self):
         """Test that dialect names are case-insensitive."""
-        hints = {"ORACLE": ["APPEND"]}
+        hints = {"ORACLE": "/*+ APPEND */"}
         result = sql._process_sql_hints(hints, "oracle")
         assert result == "/*+ APPEND */"
 
-        hints = {"oracle": ["APPEND"]}
+        hints = {"oracle": "/*+ APPEND */"}
         result = sql._process_sql_hints(hints, "ORACLE")
         assert result == "/*+ APPEND */"
 
@@ -4459,9 +4453,20 @@ def test_process_sql_hints_mysql(self):
 
     def test_process_sql_hints_mssql(self):
         """Test hint processing for SQL Server dialect."""
-        hints = {"mssql": "TABLOCK"}
+        hints = {"mssql": "WITH (TABLOCK)"}
         result = sql._process_sql_hints(hints, "mssql")
-        assert result == "TABLOCK"
+        assert result == "WITH (TABLOCK)"
+
+    def test_process_sql_hints_multiple_dialects(self):
+        """Test extraction from dict with multiple dialects."""
+        hints = {
+            "oracle": "/*+ PARALLEL */",
+            "mysql": "DELAYED",
+            "postgresql": "/* comment */",
+        }
+        assert sql._process_sql_hints(hints, "oracle") == "/*+ PARALLEL */"
+        assert sql._process_sql_hints(hints, "mysql") == "DELAYED"
+        assert sql._process_sql_hints(hints, "postgresql") == "/* comment */"
 
 
 @pytest.mark.parametrize("conn", sqlalchemy_connectable)
@@ -4471,7 +4476,10 @@ def test_to_sql_with_hints_parameter(conn, test_frame1, request):
 
     with pandasSQL_builder(conn, need_transaction=True) as pandasSQL:
         pandasSQL.to_sql(
-            test_frame1, "test_hints", hints={"oracle": ["APPEND"]}, if_exists="replace"
+            test_frame1,
+            "test_hints",
+            hints={"oracle": "/*+ APPEND */"},
+            if_exists="replace",
         )
         assert pandasSQL.has_table("test_hints")
     assert count_rows(conn, "test_hints") == len(test_frame1)
@@ -4505,7 +4513,7 @@ def sample(pd_table, conn, keys, data_iter):
             test_frame1,
             "test_hints_method",
             method=sample,
-            hints={"oracle": ["APPEND"]},
+            hints={"oracle": "/*+ APPEND */"},
         )
         assert pandasSQL.has_table("test_hints_method")
 
@@ -4524,7 +4532,7 @@ def test_to_sql_hints_with_different_methods(conn, method, test_frame1, request)
             test_frame1,
             "test_hints_methods",
             method=method,
-            hints={"oracle": ["APPEND", "PARALLEL"]},
+            hints={"oracle": "/*+ APPEND PARALLEL */"},
             if_exists="replace",
         )
         assert pandasSQL.has_table("test_hints_methods")
@@ -4538,10 +4546,10 @@ def test_to_sql_hints_multidb_dict(conn, test_frame1, request):
     conn = request.getfixturevalue(conn)
 
     hints = {
-        "oracle": ["APPEND", "PARALLEL"],
+        "oracle": "/*+ APPEND PARALLEL */",
         "mysql": "HIGH_PRIORITY",
-        "postgresql": "some_pg_hint",
-        "sqlite": "ignored",
+        "postgresql": "/* pg hint */",
+        "sqlite": "IGNORED",
     }
 
     with pandasSQL_builder(conn, need_transaction=True) as pandasSQL:
@@ -4561,7 +4569,7 @@ def test_to_sql_hints_adbc_not_supported(sqlite_adbc_conn, test_frame1):
     msg = "'hints' is not implemented for ADBC drivers"
 
     with pytest.raises(NotImplementedError, match=msg):
-        df.to_sql("test", sqlite_adbc_conn, hints={"oracle": ["APPEND"]})
+        df.to_sql("test", sqlite_adbc_conn, hints={"mysql": "SOME_HINT"})
 
 
 def test_to_sql_hints_sqlite_builtin(sqlite_buildin, test_frame1):