docs(python): namespace registration docs update (#5565)

py-polars/docs/source/reference/api.rst

@@ -14,6 +14,7 @@ This feature is primarily intended for use by library authors providing
 domain-specific capabilities which may not exist (or belong) in the
 core library.
 
+
 Available registrations
 -----------------------
 
@@ -26,6 +27,16 @@ Available registrations
     register_lazyframe_namespace
     register_series_namespace
 
+.. note::
+
+   You cannot override existing polars namespaces (such as ``.str`` or ``.dt``), and attempting to do so
+   will raise an `AttributeError <https://docs.python.org/3/library/exceptions.html#AttributeError>`_.
+   However, you *can* override other custom namespaces (which will only generate a
+   `UserWarning <https://docs.python.org/3/library/exceptions.html#UserWarning>`_).
+
+
+Examples
+--------
 
 .. tab-set::
 
@@ -117,11 +128,3 @@ Available registrations
 
             s2 = s.math.square().rename("n2", in_place=True)
             s3 = s.math.cube().rename("n3", in_place=True)
-
-
-.. note::
-
-   You cannot override existing polars namespaces (such as ``.str`` or ``.dt``), and attempting to do so
-   will raise an `AttributeError <https://docs.python.org/3/library/exceptions.html#AttributeError>`_.
-   However, you *can* override other custom namespaces (which will only generate a
-   `UserWarning <https://docs.python.org/3/library/exceptions.html#UserWarning>`_).

py-polars/polars/api.py

@@ -66,7 +66,7 @@ def namespace(ns_class: type[NS]) -> type[NS]:
 
 def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     """
-    Decorator for registering custom functionality with a polars Expr namespace.
+    Decorator for registering custom functionality with a polars Expr.
 
     Parameters
     ----------
@@ -75,7 +75,7 @@ def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
 
     Examples
     --------
-    >>> @pl.api.register_expr_namespace("power")
+    >>> @pl.api.register_expr_namespace("pow_n")
     ... class PowersOfN:
     ...     def __init__(self, expr: pl.Expr):
     ...         self._expr = expr
@@ -93,9 +93,9 @@ def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     >>> df.select(
     ...     [
     ...         pl.col("n"),
-    ...         pl.col("n").power.next(p=2).alias("next_pow2"),
-    ...         pl.col("n").power.previous(p=2).alias("prev_pow2"),
-    ...         pl.col("n").power.nearest(p=2).alias("nearest_pow2"),
+    ...         pl.col("n").pow_n.next(p=2).alias("next_pow2"),
+    ...         pl.col("n").pow_n.previous(p=2).alias("prev_pow2"),
+    ...         pl.col("n").pow_n.nearest(p=2).alias("nearest_pow2"),
     ...     ]
     ... )
     shape: (4, 4)
@@ -125,7 +125,7 @@ def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
 
 def register_dataframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     """
-    Decorator for registering custom functionality with a polars DataFrame namespace.
+    Decorator for registering custom functionality with a polars DataFrame.
 
     Parameters
     ----------
@@ -235,7 +235,7 @@ def register_dataframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
 
 def register_lazyframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     """
-    Decorator for registering custom functionality with a polars LazyFrame namespace.
+    Decorator for registering custom functionality with a polars LazyFrame.
 
     Parameters
     ----------
@@ -244,16 +244,49 @@ def register_lazyframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
 
     Examples
     --------
-    >>> @pl.api.register_lazyframe_namespace("split")
-    ... class SplitFrame:
+    >>> @pl.api.register_lazyframe_namespace("types")
+    ... class DTypeOperations:
     ...     def __init__(self, ldf: pl.LazyFrame):
     ...         self._ldf = ldf
     ...
-    ...     def by_column_dtypes(self) -> list[pl.LazyFrame]:
+    ...     def split_by_column_dtypes(self) -> list[pl.LazyFrame]:
     ...         return [
     ...             self._ldf.select(pl.col(tp))
     ...             for tp in dict.fromkeys(self._ldf.dtypes)
     ...         ]
+    ...
+    ...     def upcast_integer_types(self) -> pl.LazyFrame:
+    ...         return self._ldf.with_columns(
+    ...             pl.col(tp).cast(pl.Int64) for tp in (pl.Int8, pl.Int16, pl.Int32)
+    ...         )
+    >>>
+    >>> ldf = pl.DataFrame(
+    ...     data={"a": [1, 2], "b": [3, 4], "c": [5.6, 6.7]},
+    ...     columns=[("a", pl.Int16), ("b", pl.Int32), ("c", pl.Float32)],
+    ... ).lazy()
+    >>>
+    >>> ldf.collect()
+    shape: (2, 3)
+    ┌─────┬─────┬─────┐
+    │ a   ┆ b   ┆ c   │
+    │ --- ┆ --- ┆ --- │
+    │ i16 ┆ i32 ┆ f32 │
+    ╞═════╪═════╪═════╡
+    │ 1   ┆ 3   ┆ 5.6 │
+    ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌┤
+    │ 2   ┆ 4   ┆ 6.7 │
+    └─────┴─────┴─────┘
+    >>> ldf.types.upcast_integer_types().collect()
+    shape: (2, 3)
+    ┌─────┬─────┬─────┐
+    │ a   ┆ b   ┆ c   │
+    │ --- ┆ --- ┆ --- │
+    │ i64 ┆ i64 ┆ f32 │
+    ╞═════╪═════╪═════╡
+    │ 1   ┆ 3   ┆ 5.6 │
+    ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌┤
+    │ 2   ┆ 4   ┆ 6.7 │
+    └─────┴─────┴─────┘
     >>>
     >>> ldf = pl.DataFrame(
     ...     data=[["xx", 2, 3, 4], ["xy", 4, 5, 6], ["yy", 5, 6, 7], ["yz", 6, 7, 8]],
@@ -276,7 +309,7 @@ def register_lazyframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌┤
     │ yz  ┆ 6   ┆ 7   ┆ 8   │
     └─────┴─────┴─────┴─────┘
-    >>> [ldf.collect() for ldf in ldf.split.by_column_dtypes()]
+    >>> [ldf.collect() for ldf in ldf.types.split_by_column_dtypes()]
     [shape: (4, 1)
     ┌─────┐
     │ a1  │
@@ -317,7 +350,7 @@ def register_lazyframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
 
 def register_series_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     """
-    Decorator for registering custom functionality with a polars Series namespace.
+    Decorator for registering custom functionality with a polars Series.
 
     Parameters
     ----------