update docstrings

pola-rs · Jun 7, 2024 · 3aa8203 · 3aa8203
1 parent ccc1d9a
commit 3aa8203
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 6 deletions.
diff --git a/py-polars/polars/dataframe/frame.py b/py-polars/polars/dataframe/frame.py
@@ -4730,6 +4730,11 @@ def top_k(
         """
         Return the `k` largest rows.
 
+        Non-null elements are always preferred over null elements, regardless of
+        the value of `descending`. The output is not guaranteed to be in any
+        particular order, call :func:`sort` after this function if you wish the
+        output to be sorted.
+
         Parameters
         ----------
         k
@@ -4806,6 +4811,11 @@ def bottom_k(
         """
         Return the `k` smallest rows.
 
+        Non-null elements are always preferred over null elements, regardless of
+        the value of `descending`. The output is not guaranteed to be in any
+        particular order, call :func:`sort` after this function if you wish the
+        output to be sorted.
+
         Parameters
         ----------
         k

diff --git a/py-polars/polars/expr/expr.py b/py-polars/polars/expr/expr.py
@@ -1823,10 +1823,14 @@ def sort(self, *, descending: bool = False, nulls_last: bool = False) -> Self:
     def top_k(self, k: int | IntoExprColumn = 5) -> Self:
         r"""
         Return the `k` largest elements.
+        
+        Non-null elements are always preferred over null elements. The output
+        is not guaranteed to be in any particular order, call :func:`sort`
+        after this function if you wish the output to be sorted.
 
         This has time complexity:
 
-        .. math:: O(n + k \log{n})
+        .. math:: O(n)
 
         Parameters
         ----------
@@ -1874,9 +1878,14 @@ def top_k_by(
         r"""
         Return the elements corresponding to the `k` largest elements of the `by` column(s).
 
+        Non-null elements are always preferred over null elements, regardless of
+        the value of `descending`. The output is not guaranteed to be in any
+        particular order, call :func:`sort` after this function if you wish the
+        output to be sorted.
+
         This has time complexity:
 
-        .. math:: O(n + k \log{n})
+        .. math:: O(n \log{n})
 
         Parameters
         ----------
@@ -1985,9 +1994,13 @@ def bottom_k(self, k: int | IntoExprColumn = 5) -> Self:
         r"""
         Return the `k` smallest elements.
 
+        Non-null elements are always preferred over null elements. The output is
+        not guaranteed to be in any particular order, call :func:`sort` after
+        this function if you wish the output to be sorted.
+
         This has time complexity:
 
-        .. math:: O(n + k \log{n})
+        .. math:: O(n)
 
         Parameters
         ----------
@@ -2037,9 +2050,14 @@ def bottom_k_by(
         r"""
         Return the elements corresponding to the `k` smallest elements of the `by` column(s).
 
+        Non-null elements are always preferred over null elements, regardless of
+        the value of `descending`. The output is not guaranteed to be in any
+        particular order, call :func:`sort` after this function if you wish the
+        output to be sorted.
+
         This has time complexity:
 
-        .. math:: O(n + k \log{n})
+        .. math:: O(n \log{n})
 
         Parameters
         ----------

diff --git a/py-polars/polars/lazyframe/frame.py b/py-polars/polars/lazyframe/frame.py
@@ -1379,6 +1379,11 @@ def top_k(
         """
         Return the `k` largest rows.
 
+        Non-null elements are always preferred over null elements, regardless of
+        the value of `descending`. The output is not guaranteed to be in any
+        particular order, call :func:`sort` after this function if you wish the
+        output to be sorted.
+
         Parameters
         ----------
         k
@@ -1448,6 +1453,11 @@ def bottom_k(
         """
         Return the `k` smallest rows.
 
+        Non-null elements are always preferred over null elements, regardless of
+        the value of `descending`. The output is not guaranteed to be in any
+        particular order, call :func:`sort` after this function if you wish the
+        output to be sorted.
+
         Parameters
         ----------
         k

diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py
@@ -3114,9 +3114,13 @@ def top_k(self, k: int = 5) -> Series:
         r"""
         Return the `k` largest elements.
 
+        Non-null elements are always preferred over null elements. The output is
+        not guaranteed to be in any particular order, call :func:`sort` after
+        this function if you wish the output to be sorted.
+
         This has time complexity:
 
-        .. math:: O(n + k \log{n})
+        .. math:: O(n)
 
         Parameters
         ----------
@@ -3144,9 +3148,14 @@ def bottom_k(self, k: int = 5) -> Series:
         r"""
         Return the `k` smallest elements.
 
+        Non-null elements are always preferred over null elements. The output is
+        not guaranteed to be in any particular order, call :func:`sort` after
+        this function if you wish the output to be sorted. This has time
+        complexity:
+
         This has time complexity:
 
-        .. math:: O(n + k \log{n})
+        .. math:: O(n)
 
         Parameters
         ----------