From 1de4791ddb4594c2b4dc5b7af8cf3cae91f8b719 Mon Sep 17 00:00:00 2001
From: alexander-beedie <alexander.m.beedie@icloud.com>
Date: Wed, 20 Mar 2024 23:03:38 +0400
Subject: [PATCH] docs(python): add a note about the behaviour of lower/upper
 bounds for `is_between`, and add an example

---
 py-polars/polars/expr/expr.py     | 24 ++++++++++++++++++++++++
 py-polars/polars/series/series.py |  5 +++++
 2 files changed, 29 insertions(+)

diff --git a/py-polars/polars/expr/expr.py b/py-polars/polars/expr/expr.py
index 641ff283325e8..7019fba0a7740 100644
--- a/py-polars/polars/expr/expr.py
+++ b/py-polars/polars/expr/expr.py
@@ -5438,6 +5438,11 @@ def is_between(
         closed : {'both', 'left', 'right', 'none'}
             Define which sides of the interval are closed (inclusive).
 
+        Notes
+        -----
+        If the value of the `lower_bound` is greater than that of the `upper_bound`
+        then the result will be False.
+
         Returns
         -------
         Expr
@@ -5500,6 +5505,25 @@ def is_between(
         │ d   ┆ false      │
         │ e   ┆ false      │
         └─────┴────────────┘
+
+        Use column expressions as lower/upper bounds, comparing to a literal value:
+
+        >>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5], "b": [5, 4, 3, 2, 1]})
+        >>> df.with_columns(
+        ...     pl.lit(3).is_between(pl.col("a"), pl.col("b")).alias("between_ab")
+        ... )
+        shape: (5, 3)
+        ┌─────┬─────┬────────────┐
+        │ a   ┆ b   ┆ between_ab │
+        │ --- ┆ --- ┆ ---        │
+        │ i64 ┆ i64 ┆ bool       │
+        ╞═════╪═════╪════════════╡
+        │ 1   ┆ 5   ┆ true       │
+        │ 2   ┆ 4   ┆ true       │
+        │ 3   ┆ 3   ┆ true       │
+        │ 4   ┆ 2   ┆ false      │
+        │ 5   ┆ 1   ┆ false      │
+        └─────┴─────┴────────────┘
         """
         lower_bound = parse_as_expression(lower_bound)
         upper_bound = parse_as_expression(upper_bound)
diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py
index 39877d4dc341a..50a54e2fc22b5 100644
--- a/py-polars/polars/series/series.py
+++ b/py-polars/polars/series/series.py
@@ -4200,6 +4200,11 @@ def is_between(
         closed : {'both', 'left', 'right', 'none'}
             Define which sides of the interval are closed (inclusive).
 
+        Notes
+        -----
+        If the value of the `lower_bound` is greater than that of the `upper_bound`
+        then the result will be False.
+
         Examples
         --------
         >>> s = pl.Series("num", [1, 2, 3, 4, 5])