From 29f7c1ad48ef5afb2900d56f76f1bbbdab02c70b Mon Sep 17 00:00:00 2001
From: Michael Buhidar <mbuhidar@gmail.com>
Date: Tue, 13 Feb 2024 21:43:13 -0500
Subject: [PATCH] docs(python): Add examples for Series.bin.ends_with,
 Series.bin.starts_with, Series.bin.decode, Series.bin.encode.

---
 py-polars/polars/series/binary.py | 73 +++++++++++++++++++++++++++++--
 1 file changed, 69 insertions(+), 4 deletions(-)

diff --git a/py-polars/polars/series/binary.py b/py-polars/polars/series/binary.py
index 9d9a4eb1955c..482773bef65f 100644
--- a/py-polars/polars/series/binary.py
+++ b/py-polars/polars/series/binary.py
@@ -47,27 +47,51 @@ def contains(self, literal: IntoExpr) -> Series:
         """
 
     def ends_with(self, suffix: IntoExpr) -> Series:
-        """
+        r"""
         Check if string values end with a binary substring.
 
         Parameters
         ----------
         suffix
             Suffix substring.
+
+        Examples
+        --------
+        >>> s = pl.Series("colors", [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"])
+        >>> s.bin.ends_with(b"\x00")
+        shape: (3,)
+        Series: 'colors' [bool]
+        [
+            true
+            true
+            false
+        ]
         """
 
     def starts_with(self, prefix: IntoExpr) -> Series:
-        """
+        r"""
         Check if values start with a binary substring.
 
         Parameters
         ----------
         prefix
             Prefix substring.
+
+        Examples
+        --------
+        >>> s = pl.Series("colors", [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"])
+        >>> s.bin.starts_with(b"\x00")
+        shape: (3,)
+        Series: 'colors' [bool]
+        [
+            true
+            false
+            true
+        ]
         """
 
     def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
-        """
+        r"""
         Decode a value using the provided encoding.
 
         Parameters
@@ -77,10 +101,31 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
         strict
             Raise an error if the underlying value cannot be decoded,
             otherwise mask out with a null value.
+
+        Examples
+        --------
+        >>> s = pl.Series("colors", [b"000000", b"ffff00", b"0000ff"])
+        >>> s.bin.decode("hex")
+        shape: (3,)
+        Series: 'colors' [binary]
+        [
+            b"\x00\x00\x00"
+            b"\xff\xff\x00"
+            b"\x00\x00\xff"
+        ]
+        >>> s = pl.Series("colors", [b"AAAA", b"//8A", b"AAD/"])
+        >>> s.bin.decode("base64")
+        shape: (3,)
+        Series: 'colors' [binary]
+        [
+            b"\x00\x00\x00"
+            b"\xff\xff\x00"
+            b"\x00\x00\xff"
+        ]
         """
 
     def encode(self, encoding: TransferEncoding) -> Series:
-        """
+        r"""
         Encode a value using the provided encoding.
 
         Parameters
@@ -92,4 +137,24 @@ def encode(self, encoding: TransferEncoding) -> Series:
         -------
         Series
             Series of data type :class:`Boolean`.
+
+        Examples
+        --------
+        >>> s = pl.Series("colors", [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"])
+        >>> s.bin.encode("hex")
+        shape: (3,)
+        Series: 'colors' [str]
+        [
+            "000000"
+            "ffff00"
+            "0000ff"
+        ]
+        >>> s.bin.encode("base64")
+        shape: (3,)
+        Series: 'colors' [str]
+        [
+            "AAAA"
+            "//8A"
+            "AAD/"
+        ]
         """