Fixed most See Also docstring formatting, quietened the last warnin…

…gs coming from `doctests` (#3932)
pola-rs · Jul 9, 2022 · e4371fa · e4371fa
1 parent 01300fc
commit e4371fa
Show file tree

Hide file tree

Showing 11 changed files with 75 additions and 78 deletions.
diff --git a/py-polars/Makefile b/py-polars/Makefile
@@ -31,6 +31,7 @@ test-all: venv
 	$(PYTHON_BIN)/maturin develop
 	$(PYTHON) -m pytest tests
 	$(PYTHON) -m pytest tests_parametric
+	$(PYTHON) tests/run_doc_examples.py
 
 test-with-cov: venv
 	$(PYTHON) -m pytest \

diff --git a/py-polars/polars/convert.py b/py-polars/polars/convert.py
@@ -49,7 +49,6 @@ def from_dict(
 
     Examples
     --------
-
     >>> data = {"a": [1, 2], "b": [3, 4]}
     >>> df = pl.from_dict(data)
     >>> df

diff --git a/py-polars/polars/internals/expr.py b/py-polars/polars/internals/expr.py
@@ -5679,7 +5679,6 @@ def contains(self, pattern: str, literal: bool = False) -> Expr:
 
         Examples
         --------
-
         >>> df = pl.DataFrame({"a": ["Crab", "cat and dog", "rab$bit", None]})
         >>> df.select(
         ...     [
@@ -5703,6 +5702,10 @@ def contains(self, pattern: str, literal: bool = False) -> Expr:
         │ null        ┆ null  ┆ null    │
         └─────────────┴───────┴─────────┘
 
+        See Also
+        --------
+        starts_with : Check if string values start with a substring.
+        ends_with : Check if string values end with a substring.
         """
         return wrap_expr(self._pyexpr.str_contains(pattern, literal))
 
@@ -5713,11 +5716,10 @@ def ends_with(self, sub: str) -> Expr:
         Parameters
         ----------
         sub
-            Suffix
+            Suffix substring.
 
         Examples
         --------
-
         >>> df = pl.DataFrame({"fruits": ["apple", "mango", None]})
         >>> df.with_column(
         ...     pl.col("fruits").str.ends_with("go").alias("has_suffix"),
@@ -5750,7 +5752,7 @@ def ends_with(self, sub: str) -> Expr:
         See Also
         --------
         contains : Check if string contains a substring that matches a regex.
-
+        starts_with : Check if string values start with a substring.
         """
         return wrap_expr(self._pyexpr.str_ends_with(sub))
 
@@ -5761,11 +5763,10 @@ def starts_with(self, sub: str) -> Expr:
         Parameters
         ----------
         sub
-            Prefix
+            Prefix substring.
 
         Examples
         --------
-
         >>> df = pl.DataFrame({"fruits": ["apple", "mango", None]})
         >>> df.with_column(
         ...     pl.col("fruits").str.starts_with("app").alias("has_prefix"),
@@ -5798,7 +5799,7 @@ def starts_with(self, sub: str) -> Expr:
         See Also
         --------
         contains : Check if string contains a substring that matches a regex.
-
+        ends_with : Check if string values end with a substring.
         """
         return wrap_expr(self._pyexpr.str_starts_with(sub))
 
@@ -5822,7 +5823,6 @@ def json_path_match(self, json_path: str) -> Expr:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {"json_val": ['{"a":"1"}', None, '{"a":2}', '{"a":2.1}', '{"a":true}']}
         ... )
@@ -6173,7 +6173,6 @@ def replace(self, pattern: str, value: str) -> Expr:
 
         Examples
         --------
-
         >>> df = pl.DataFrame({"id": [1, 2], "text": ["123abc", "abc456"]})
         >>> df.with_column(
         ...     pl.col("text").str.replace(r"abc\b", "ABC")

diff --git a/py-polars/polars/internals/frame.py b/py-polars/polars/internals/frame.py
@@ -796,7 +796,9 @@ def _read_json(
         json_lines: bool = False,
     ) -> DF:
         """
-        See Also pl.read_json
+        See Also
+        --------
+        read_json
         """
         if isinstance(file, StringIO):
             file = BytesIO(file.getvalue().encode())
@@ -2204,7 +2206,7 @@ def dtypes(self) -> list[type[DataType]]:
 
         See Also
         --------
-        schema : Return a dict of [column name, dtype]
+        schema : Returns a {colname:dtype} mapping.
         """
         return self._df.dtypes()
 
@@ -2533,7 +2535,6 @@ def slice(self: DF, offset: int, length: int | None = None) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "foo": [1, 2, 3],
@@ -2562,7 +2563,9 @@ def limit(self: DF, length: int = 5) -> DF:
         """
         Get first N rows as DataFrame.
 
-        See Also `DataFrame.head`
+        See Also
+        --------
+        head, tail, slice
 
         Parameters
         ----------
@@ -6014,7 +6017,6 @@ class GroupBy(Generic[DF]):
 
     Examples
     --------
-
     >>> df = pl.DataFrame({"foo": ["a", "a", "b"], "bar": [1, 2, 3]})
     >>> for group in df.groupby("foo"):
     ...     print(group)
@@ -6535,15 +6537,14 @@ def pivot(
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "foo": ["one", "one", "one", "two", "two", "two"],
         ...         "bar": ["A", "B", "C", "A", "B", "C"],
         ...         "baz": [1, 2, 3, 4, 5, 6],
         ...     }
         ... )
-        >>> df.groupby("foo", maintain_order=True).pivot(
+        >>> df.groupby("foo", maintain_order=True).pivot(  # doctest: +SKIP
         ...     pivot_column="bar", values_column="baz"
         ... ).first()
         shape: (2, 4)
@@ -6576,7 +6577,6 @@ def first(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6608,7 +6608,6 @@ def last(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6640,7 +6639,6 @@ def sum(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6672,7 +6670,6 @@ def min(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6704,7 +6701,6 @@ def max(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6736,7 +6732,6 @@ def count(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6768,7 +6763,6 @@ def mean(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6801,7 +6795,6 @@ def n_unique(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 1, 3, 4, 5],
@@ -6839,7 +6832,6 @@ def quantile(self, quantile: float, interpolation: str = "nearest") -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6870,7 +6862,6 @@ def median(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [1, 2, 2, 3, 4, 5],
@@ -6899,7 +6890,6 @@ def agg_list(self) -> DF:
 
         Examples
         --------
-
         >>> df = pl.DataFrame({"a": ["one", "two", "one", "two"], "b": [1, 2, 3, 4]})
         >>> df.groupby("a", maintain_order=True).agg_list()
         shape: (2, 2)

diff --git a/py-polars/polars/internals/lazy_frame.py b/py-polars/polars/internals/lazy_frame.py
@@ -133,7 +133,9 @@ def scan_csv(
         parse_dates: bool = False,
     ) -> LDF:
         """
-        See Also: `pl.scan_csv`
+        See Also
+        --------
+        scan_csv
         """
         dtype_list: list[tuple[str, type[DataType]]] | None = None
         if dtypes is not None:
@@ -179,7 +181,9 @@ def scan_parquet(
         storage_options: dict | None = None,
     ) -> LDF:
         """
-        See Also: `pl.scan_parquet`
+        See Also
+        --------
+        scan_ipc, scan_csv
         """
 
         # try fsspec scanner
@@ -214,7 +218,9 @@ def scan_ipc(
         storage_options: dict | None = None,
     ) -> LDF:
         """
-        See Also: `pl.scan_ipc`
+        See Also
+        --------
+        scan_parquet, scan_csv
         """
         if isinstance(file, (str, Path)):
             file = format_path(file)
@@ -241,7 +247,9 @@ def scan_ipc(
     @classmethod
     def from_json(cls, json: str) -> LazyFrame:
         """
-        See Also pl.read_json
+        See Also
+        --------
+        read_json
         """
         f = StringIO(json)
         return cls.read_json(f)
@@ -252,7 +260,11 @@ def read_json(
         file: str | Path | IOBase,
     ) -> LazyFrame:
         """
-        See Also pl.read_json
+        Read into a DataFrame from JSON format.
+
+        See Also
+        --------
+        write_json
         """
         if isinstance(file, StringIO):
             file = BytesIO(file.getvalue().encode())
@@ -303,6 +315,10 @@ def write_json(
             Write to this file instead of returning a string.
         to_string
             Ignore file argument and return a string.
+
+        See Also
+        --------
+        read_json
         """
         if isinstance(file, (str, Path)):
             file = format_path(file)
@@ -356,7 +372,6 @@ def pipe(self, func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
 
         Examples
         --------
-
         >>> def cast_str_to_int(data, col_name):
         ...     return data.with_column(pl.col(col_name).cast(pl.Int64))
         ...
@@ -717,7 +732,7 @@ def dtypes(self) -> list[type[DataType]]:
 
         See Also
         --------
-        schema : Return a dict of [column name, dtype]
+        schema : Returns a {colname:dtype} mapping.
         """
         return self._ldf.dtypes()
 

diff --git a/py-polars/polars/internals/lazy_functions.py b/py-polars/polars/internals/lazy_functions.py
@@ -82,7 +82,6 @@ def col(
 
     Examples
     --------
-
     >>> df = pl.DataFrame(
     ...     {
     ...         "ham": [1, 2, 3],
@@ -896,10 +895,8 @@ def exclude(columns: str | list[str]) -> pli.Expr:
     columns
         Column(s) to exclude from selection
 
-
     Examples
     --------
-
     >>> df = pl.DataFrame(
     ...     {
     ...         "a": [1, 2, 3],
@@ -1272,7 +1269,6 @@ def format(fstring: str, *args: pli.Expr | str) -> pli.Expr:
 
     Examples
     --------
-
     >>> df = pl.DataFrame(
     ...     {
     ...         "a": ["a", "b", "c"],
@@ -1452,7 +1448,6 @@ def select(
 
     Examples
     --------
-
     >>> foo = pl.Series("foo", [1, 2, 3])
     >>> bar = pl.Series("bar", [3, 2, 1])
     >>> pl.select(
@@ -1517,7 +1512,6 @@ def struct(
 
     Examples
     --------
-
     >>> pl.DataFrame(
     ...     {
     ...         "int": [1, 2],
@@ -1663,7 +1657,6 @@ def arg_where(
 
     Examples
     --------
-
     >>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5]})
     >>> df.select(
     ...     [