feat(python): allow use of StringCache object as a function decorat…

…or (#9309)

polars/polars-core/src/frame/row/av_buffer.rs

@@ -293,7 +293,7 @@ impl From<(&DataType, usize)> for AnyValueBuffer<'_> {
     }
 }
 
-/// An `AnyValyeBuffer` that should be used when we trust the builder
+/// An `AnyValueBuffer` that should be used when we trust the builder
 #[derive(Clone)]
 pub enum AnyValueBufferTrusted<'a> {
     Boolean(BooleanChunkedBuilder),

polars/tests/it/core/rolling_window.rs

@@ -269,23 +269,23 @@ fn test_rolling_var() {
         .unwrap();
     let out = out.f64().unwrap().to_vec();
 
-    let expres = &[
+    let exp_res = &[
         None,
         Some(17.333333333333332),
         Some(11.583333333333334),
         Some(21.583333333333332),
         Some(24.666666666666668),
         Some(34.33333333333334),
     ];
-    let testres = out.iter().zip(expres.iter()).all(|(&a, &b)| match (a, b) {
+    let test_res = out.iter().zip(exp_res.iter()).all(|(&a, &b)| match (a, b) {
         (None, None) => true,
         (Some(a), Some(b)) => (a - b).abs() < 1e-12,
         (_, _) => false,
     });
     assert!(
-        testres,
+        test_res,
         "{:?} is not approximately equal to {:?}",
-        out, expres
+        out, exp_res
     );
 }
 

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

@@ -45,8 +45,13 @@ Parallelization
 
 StringCache
 ~~~~~~~~~~~
+
+Note that the `StringCache` can be used as both a context manager
+and a decorator, in order to explicitly scope cache lifetime.
+
 .. autosummary::
    :toctree: api/
 
-    enable_string_cache
     StringCache
+    enable_string_cache
+    using_string_cache

py-polars/polars/expr/string.py

@@ -504,7 +504,19 @@ def strip(self, characters: str | None = None) -> Expr:
 
         Examples
         --------
-        >>> df = pl.DataFrame({"foo": [" hello ", "\tworld"]})
+        >>> df = pl.DataFrame({"foo": [" hello", "\nworld"]})
+        >>> df
+        shape: (2, 1)
+        ┌────────┐
+        │ foo    │
+        │ ---    │
+        │ str    │
+        ╞════════╡
+        │  hello │
+        │        │
+        │ world  │
+        └────────┘
+
         >>> df.select(pl.col("foo").str.strip())
         shape: (2, 1)
         ┌───────┐
@@ -517,18 +529,19 @@ def strip(self, characters: str | None = None) -> Expr:
         └───────┘
 
         Characters can be stripped by passing a string as argument. Note that whitespace
-        will not be stripped automatically when doing so.
+        will not be stripped automatically when doing so, unless that whitespace is
+        also included in the string.
 
-        >>> df.select(pl.col("foo").str.strip("od\t"))
+        >>> df.select(pl.col("foo").str.strip("ow\n"))
         shape: (2, 1)
-        ┌─────────┐
-        │ foo     │
-        │ ---     │
-        │ str     │
-        ╞═════════╡
-        │  hello  │
-        │ worl    │
-        └─────────┘
+        ┌───────┐
+        │ foo   │
+        │ ---   │
+        │ str   │
+        ╞═══════╡
+        │  hell │
+        │ rld   │
+        └───────┘
 
         """
         return wrap_expr(self._pyexpr.str_strip(characters))
@@ -588,7 +601,18 @@ def rstrip(self, characters: str | None = None) -> Expr:
 
         Examples
         --------
-        >>> df = pl.DataFrame({"foo": [" hello ", "world\t"]})
+        >>> df = pl.DataFrame({"foo": [" hello", "world\n"]})
+        >>> df
+        shape: (2, 1)
+        ┌────────┐
+        │ foo    │
+        │ ---    │
+        │ str    │
+        ╞════════╡
+        │  hello │
+        │ world  │
+        │        │
+        └────────┘
         >>> df.select(pl.col("foo").str.rstrip())
         shape: (2, 1)
         ┌────────┐
@@ -601,18 +625,20 @@ def rstrip(self, characters: str | None = None) -> Expr:
         └────────┘
 
         Characters can be stripped by passing a string as argument. Note that whitespace
-        will not be stripped automatically when doing so.
+        will not be stripped automatically when doing so, unless that whitespace is
+        also included in the string.
 
-        >>> df.select(pl.col("foo").str.rstrip("wod\t"))
+        >>> df.select(pl.col("foo").str.rstrip("oldw "))
         shape: (2, 1)
-        ┌─────────┐
-        │ foo     │
-        │ ---     │
-        │ str     │
-        ╞═════════╡
-        │  hello  │
-        │ worl    │
-        └─────────┘
+        ┌───────┐
+        │ foo   │
+        │ ---   │
+        │ str   │
+        ╞═══════╡
+        │  he   │
+        │ world │
+        │       │
+        └───────┘
 
         """
         return wrap_expr(self._pyexpr.str_rstrip(characters))

py-polars/polars/series/string.py

@@ -1038,14 +1038,15 @@ def strip(self, characters: str | None = None) -> Series:
         ]
 
         Characters can be stripped by passing a string as argument. Note that whitespace
-        will not be stripped automatically when doing so.
+        will not be stripped automatically when doing so, unless that whitespace is
+        also included in the string.
 
-        >>> s.str.strip("od\t")
+        >>> s.str.strip("o ")
         shape: (2,)
         Series: '' [str]
         [
-                " hello "
-                "worl"
+            "hell"
+            "	world"
         ]
 
         """
@@ -1110,12 +1111,12 @@ def rstrip(self, characters: str | None = None) -> Series:
         Characters can be stripped by passing a string as argument. Note that whitespace
         will not be stripped automatically when doing so.
 
-        >>> s.str.rstrip("wod\t")
+        >>> s.str.rstrip("orld\t")
         shape: (2,)
         Series: '' [str]
         [
-                " hello "
-                "worl"
+            " hello "
+            "w"
         ]
 
         """

py-polars/polars/string_cache.py

@@ -14,7 +14,7 @@
     from types import TracebackType
 
 
-class StringCache:
+class StringCache(contextlib.ContextDecorator):
     """
     Context manager that allows data sources to share the same categorical features.