chore: adjust <Backend>.do_connect() be kw or positional only, add callouts to url connection method

ibis/backends/__init__.py

@@ -1668,7 +1668,7 @@ def _from_url(self, url: ParseResult, **kwargs: Any) -> BaseBackend:
             database = database.absolute()
 
         self._convert_kwargs(kwargs)
-        return self.connect(database=database, **kwargs)
+        return self.connect(database, **kwargs)
 
 
 class NoUrl:

ibis/backends/bigquery/__init__.py

@@ -337,6 +337,7 @@ def _from_url(self, url: ParseResult, **kwargs):
 
     def do_connect(
         self,
+        *,
         project_id: str | None = None,
         dataset_id: str = "",
         credentials: google.auth.credentials.Credentials | None = None,
@@ -351,6 +352,10 @@ def do_connect(
     ) -> Backend:
         """Create a `Backend` for use with Ibis.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"bigquery://{project_id}/{dataset_id}")`.
+
         Parameters
         ----------
         project_id

ibis/backends/clickhouse/__init__.py

@@ -107,6 +107,7 @@ def _convert_kwargs(self, kwargs):
 
     def do_connect(
         self,
+        *,
         host: str = "localhost",
         port: int | None = None,
         database: str = "default",
@@ -120,6 +121,10 @@ def do_connect(
     ):
         """Create a ClickHouse client for use with Ibis.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"clickhouse://{user}:{password}@{host}:{port}/{database}")`.
+
         Parameters
         ----------
         host

ibis/backends/duckdb/__init__.py

@@ -364,6 +364,8 @@ def version(self) -> str:
     def do_connect(
         self,
         database: str | Path = ":memory:",
+        /,
+        *,
         read_only: bool = False,
         extensions: Sequence[str] | None = None,
         **config: Any,

ibis/backends/exasol/__init__.py

@@ -57,6 +57,7 @@ def version(self) -> str:
 
     def do_connect(
         self,
+        *,
         user: str,
         password: str,
         host: str = "localhost",
@@ -66,6 +67,10 @@ def do_connect(
     ) -> None:
         """Create an Ibis client connected to an Exasol database.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"exasol://{user}:{password}@{host}:{port}")`.
+
         Parameters
         ----------
         user

ibis/backends/flink/__init__.py

@@ -61,7 +61,7 @@ def dialect(self):
         # TODO: remove when ported to sqlglot
         return self.compiler.dialect
 
-    def do_connect(self, table_env: TableEnvironment) -> None:
+    def do_connect(self, table_env: TableEnvironment, /) -> None:
         """Create a Flink `Backend` for use with Ibis.
 
         Parameters

ibis/backends/impala/__init__.py

@@ -90,20 +90,25 @@ def _from_url(self, url: ParseResult, **kwargs: Any) -> Backend:
 
     def do_connect(
         self,
+        *,
+        user: str | None = None,
+        password: str | None = None,
         host: str = "localhost",
         port: int = 21050,
         database: str = "default",
         timeout: int = 45,
         use_ssl: bool = False,
         ca_cert: str | Path | None = None,
-        user: str | None = None,
-        password: str | None = None,
         auth_mechanism: Literal["NOSASL", "PLAIN", "GSSAPI", "LDAP"] = "NOSASL",
         kerberos_service_name: str = "impala",
         **params: Any,
     ):
         """Create an Impala `Backend` for use with Ibis.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"impala://{user}:{password}@{host}:{port}/{database}")`.
+
         Parameters
         ----------
         host

ibis/backends/mssql/__init__.py

@@ -88,6 +88,7 @@ def version(self) -> str:
 
     def do_connect(
         self,
+        *,
         host: str = "localhost",
         user: str | None = None,
         password: str | None = None,
@@ -98,6 +99,10 @@ def do_connect(
     ) -> None:
         """Connect to MSSQL database.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"mssql://{user}:{password}@{host}:{port}/{database}")`.
+
         Parameters
         ----------
         host

ibis/backends/mysql/__init__.py

@@ -91,6 +91,7 @@ def version(self):
 
     def do_connect(
         self,
+        *,
         host: str = "localhost",
         user: str | None = None,
         password: str | None = None,
@@ -100,6 +101,10 @@ def do_connect(
     ) -> None:
         """Create an Ibis client using the passed connection parameters.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"mysql://{user}:{password}@{host}:{port}/{database}")`.
+
         Parameters
         ----------
         host

ibis/backends/postgres/__init__.py

@@ -179,6 +179,7 @@ def version(self):
 
     def do_connect(
         self,
+        *,
         host: str | None = None,
         user: str | None = None,
         password: str | None = None,
@@ -190,6 +191,10 @@ def do_connect(
     ) -> None:
         """Create an Ibis client connected to PostgreSQL database.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"postgres://{user}:{password}@{host}:{port}/{database}")`.
+
         Parameters
         ----------
         host

ibis/backends/pyspark/__init__.py

@@ -137,6 +137,8 @@ def __init__(self, *args, **kwargs):
     def do_connect(
         self,
         session: SparkSession | None = None,
+        /,
+        *,
         mode: ConnectionMode = "batch",
         **kwargs,
     ) -> None:
@@ -210,7 +212,7 @@ def from_connection(
         kwargs
             Additional keyword arguments used to configure the SparkSession.
         """
-        return ibis.pyspark.connect(session, mode, **kwargs)
+        return ibis.pyspark.connect(session, mode=mode, **kwargs)
 
     def disconnect(self) -> None:
         self._session.stop()

ibis/backends/risingwave/__init__.py

@@ -431,6 +431,7 @@ def _safe_raw_sql(self, *args, **kwargs):
 
     def do_connect(
         self,
+        *,
         host: str | None = None,
         user: str | None = None,
         password: str | None = None,
@@ -440,6 +441,10 @@ def do_connect(
     ) -> None:
         """Create an Ibis client connected to RisingWave database.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"risingwave://{user}:{password}@{host}:{port}/{database}")`.
+
         Parameters
         ----------
         host

ibis/backends/snowflake/__init__.py

@@ -239,9 +239,13 @@ def _make_udf(self, name: str, defn) -> str:
 AS
 $$ {defn["source"]} $$"""
 
-    def do_connect(self, create_object_udfs: bool = True, **kwargs: Any):
+    def do_connect(self, *, create_object_udfs: bool = True, **kwargs: Any):
         """Connect to Snowflake.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"snowflake://{user}@{account}/{database}/{schema}?warehouse={warehouse}")`.
+
         Parameters
         ----------
         user

ibis/backends/sqlite/__init__.py

@@ -59,6 +59,8 @@ def version(self) -> str:
     def do_connect(
         self,
         database: str | Path | None = None,
+        /,
+        *,
         type_map: dict[str, str | dt.DataType] | None = None,
     ) -> None:
         """Create an Ibis client connected to a SQLite database.

ibis/backends/trino/__init__.py

@@ -243,6 +243,7 @@ def list_tables(
 
     def do_connect(
         self,
+        *,
         user: str = "user",
         password: str | None = None,
         host: str = "localhost",
@@ -256,6 +257,10 @@ def do_connect(
     ) -> None:
         """Connect to Trino.
 
+        This method is useful if you have individual connection parameters.
+        If you have a connection URL then you can connect directly using
+        `ibis.connect(f"trino://{user}:{password}@{host}:{port}/{database}/{schema}")`.
+
         Parameters
         ----------
         user