docs(python): update read_sql and row docstrings (#6028)

pola-rs · Jan 4, 2023 · a52c3b5 · a52c3b5
1 parent b94fffc
commit a52c3b5
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 15 deletions.
diff --git a/py-polars/polars/internals/dataframe/frame.py b/py-polars/polars/internals/dataframe/frame.py
@@ -6350,7 +6350,7 @@ def row(
         named: bool = False,
     ) -> tuple[Any, ...] | Any:
         """
-        Get a row as tuple, either by index or by predicate.
+        Get a single row as a tuple, either by index or by predicate.
 
         Parameters
         ----------
@@ -6371,6 +6371,11 @@ def row(
         one row is returned; more than one row raises ``TooManyRowsReturned``, and
         zero rows will raise ``NoRowsReturned`` (both inherit from ``RowsException``).
 
+        Warning
+        -------
+        You should NEVER use this method to iterate over a DataFrame; if you absolutely
+        require row-iteration you should strongly prefer ``iterrows()`` instead.
+
         Examples
         --------
         Specify an index to return the row at the given index as a tuple.
@@ -6395,6 +6400,11 @@ def row(
         >>> df.row(by_predicate=(pl.col("ham") == "b"))
         (2, 7, 'b')
 
+        See Also
+        --------
+        iterrows : Row iterator over frame data (does not materialise all rows).
+        rows : Materialises all frame data as a list of rows.
+
         """
         if index is not None and by_predicate is not None:
             raise ValueError(
@@ -6467,7 +6477,7 @@ def rows(self, named: bool = False) -> list[tuple[Any, ...]] | list[Any]:
 
         See Also
         --------
-        iterrows : row iterator over frame data (does not materialise all rows).
+        iterrows : Row iterator over frame data (does not materialise all rows).
 
         """
         if named:
@@ -6532,7 +6542,7 @@ def iterrows(
 
         See Also
         --------
-        rows : materialises all frame data as a list of rows.
+        rows : Materialises all frame data as a list of rows.
 
         """
         # note: buffering rows results in a 2-4x speedup over individual calls

diff --git a/py-polars/polars/io.py b/py-polars/polars/io.py
@@ -1028,19 +1028,11 @@ def read_sql(
     """
     Read a SQL query into a DataFrame.
 
-    Reading a SQL query from the following data sources are supported:
+    A range of databases are supported, such as PostgreSQL, Redshift, MySQL, MariaDB,
+    Clickhouse, Oracle, BigQuery, SQL Server, and so on. For an up-to-date list
+    please see the connectorx docs:
 
-        * Postgres
-        * Mysql
-        * Sqlite
-        * Redshift (through postgres protocol)
-        * Clickhouse (through mysql protocol)
-
-    If a database source is not supported, an alternative solution is to first use
-    pandas to load the SQL query, then converting the result into a polars DataFrame:
-
-    >>> import pandas as pd
-    >>> df = pl.from_pandas(pd.read_sql(sql, engine))  # doctest: +SKIP
+    * https://github.com/sfu-db/connector-x#supported-sources--destinations
 
     Parameters
     ----------