Skip to content

Commit

Permalink
docs(python): Improve examples for Series.binary.encode and `Series…
Browse files Browse the repository at this point in the history 
….binary.decode`. (#14579)

Co-authored-by: Stijn de Gooijer <stijndegooijer@gmail.com>
  • Loading branch information
@mbuhidar @stinodego
mbuhidar and stinodego authored Feb 25, 2024
1 parent fa347cd commit 912edc3
Show file tree
Hide file tree
Showing 4 changed files with 113 additions and 23 deletions.
56 changes: 41 additions & 15 deletions py-polars/polars/expr/binary.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,8 +162,8 @@ def starts_with(self, prefix: IntoExpr) -> Expr:
return wrap_expr(self._pyexpr.bin_starts_with(prefix))

def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:
"""
Decode a value using the provided encoding.
r"""
Decode values using the provided encoding.
Parameters
----------
Expand All @@ -172,6 +172,33 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:
strict
Raise an error if the underlying value cannot be decoded,
otherwise mask out with a null value.
Returns
-------
Expr
Expression of data type :class:`String`.
Examples
--------
>>> colors = pl.DataFrame(
... {
... "name": ["black", "yellow", "blue"],
... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"],
... }
... )
>>> colors.with_columns(
... pl.col("code").bin.encode("hex").alias("encoded"),
... )
shape: (3, 3)
┌────────┬─────────────────┬─────────┐
│ name ┆ code ┆ encoded │
│ --- ┆ --- ┆ --- │
│ str ┆ binary ┆ str │
╞════════╪═════════════════╪═════════╡
│ black ┆ b"\x00\x00\x00" ┆ 000000 │
│ yellow ┆ b"\xff\xff\x00" ┆ ffff00 │
│ blue ┆ b"\x00\x00\xff" ┆ 0000ff │
└────────┴─────────────────┴─────────┘
"""
if encoding == "hex":
return wrap_expr(self._pyexpr.bin_hex_decode(strict))
Expand All @@ -193,30 +220,29 @@ def encode(self, encoding: TransferEncoding) -> Expr:
Returns
-------
Expr
Expression of data type :class:`String` with values encoded using provided
encoding.
Expression of data type :class:`String`.
Examples
--------
>>> colors = pl.DataFrame(
... {
... "name": ["black", "yellow", "blue"],
... "color": ["black", "yellow", "blue"],
... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"],
... }
... )
>>> colors.with_columns(
... pl.col("code").bin.encode("hex").alias("code_encoded_hex"),
... pl.col("code").bin.encode("hex").alias("encoded"),
... )
shape: (3, 3)
┌────────┬─────────────────┬──────────────────┐
│ name ┆ code ┆ code_encoded_hex │
│ --- ┆ --- ┆ --- │
│ str ┆ binary ┆ str │
╞════════╪═════════════════╪══════════════════╡
│ black ┆ b"\x00\x00\x00" ┆ 000000 │
│ yellow ┆ b"\xff\xff\x00" ┆ ffff00 │
│ blue ┆ b"\x00\x00\xff" ┆ 0000ff │
└────────┴─────────────────┴──────────────────┘
┌────────┬─────────────────┬─────────┐
│ color ┆ code ┆ encoded │
│ --- ┆ --- ┆ --- │
│ str ┆ binary ┆ str │
╞════════╪═════════════════╪═════════╡
│ black ┆ b"\x00\x00\x00" ┆ 000000 │
│ yellow ┆ b"\xff\xff\x00" ┆ ffff00 │
│ blue ┆ b"\x00\x00\xff" ┆ 0000ff │
└────────┴─────────────────┴─────────┘
"""
if encoding == "hex":
return wrap_expr(self._pyexpr.bin_hex_encode())
Expand Down
26 changes: 23 additions & 3 deletions py-polars/polars/expr/string.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1346,8 +1346,8 @@ def json_path_match(self, json_path: str) -> Expr:
return wrap_expr(self._pyexpr.str_json_path_match(json_path))

def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:
"""
Decode a value using the provided encoding.
r"""
Decode values using the provided encoding.
Parameters
----------
Expand All @@ -1356,6 +1356,26 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:
strict
Raise an error if the underlying value cannot be decoded,
otherwise mask out with a null value.
Returns
-------
Expr
Expression of data type :class:`Binary`.
Examples
--------
>>> df = pl.DataFrame({"color": ["000000", "ffff00", "0000ff"]})
>>> df.with_columns(pl.col("color").str.decode("hex").alias("decoded"))
shape: (3, 2)
┌────────┬─────────────────┐
│ color ┆ decoded │
│ --- ┆ --- │
│ str ┆ binary │
╞════════╪═════════════════╡
│ 000000 ┆ b"\x00\x00\x00" │
│ ffff00 ┆ b"\xff\xff\x00" │
│ 0000ff ┆ b"\x00\x00\xff" │
└────────┴─────────────────┘
"""
if encoding == "hex":
return wrap_expr(self._pyexpr.str_hex_decode(strict))
Expand All @@ -1367,7 +1387,7 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:

def encode(self, encoding: TransferEncoding) -> Expr:
"""
Encode a value using the provided encoding.
Encode values using the provided encoding.
Parameters
----------
Expand Down
33 changes: 30 additions & 3 deletions py-polars/polars/series/binary.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ def starts_with(self, prefix: IntoExpr) -> Series:

def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
r"""
Decode a value using the provided encoding.
Decode values using the provided encoding.
Parameters
----------
Expand All @@ -102,8 +102,15 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
Raise an error if the underlying value cannot be decoded,
otherwise mask out with a null value.
Returns
-------
Series
Series of data type :class:`String`.
Examples
--------
Decode values using hexadecimal encoding.
>>> s = pl.Series("colors", [b"000000", b"ffff00", b"0000ff"])
>>> s.bin.decode("hex")
shape: (3,)
Expand All @@ -113,6 +120,9 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
b"\xff\xff\x00"
b"\x00\x00\xff"
]
Decode values using Base64 encoding.
>>> s = pl.Series("colors", [b"AAAA", b"//8A", b"AAD/"])
>>> s.bin.decode("base64")
shape: (3,)
Expand All @@ -122,11 +132,23 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
b"\xff\xff\x00"
b"\x00\x00\xff"
]
Set `strict=False` to set invalid values to null instead of raising an error.
>>> s = pl.Series("colors", [b"000000", b"ffff00", b"invalid_value"])
>>> s.bin.decode("hex", strict=False)
shape: (3,)
Series: 'colors' [binary]
[
b"\x00\x00\x00"
b"\xff\xff\x00"
null
]
"""

def encode(self, encoding: TransferEncoding) -> Series:
r"""
Encode a value using the provided encoding.
Encode values using the provided encoding.
Parameters
----------
Expand All @@ -136,10 +158,12 @@ def encode(self, encoding: TransferEncoding) -> Series:
Returns
-------
Series
Series of data type :class:`Boolean`.
Series of data type :class:`String`.
Examples
--------
Encode values using hexadecimal encoding.
>>> s = pl.Series("colors", [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"])
>>> s.bin.encode("hex")
shape: (3,)
Expand All @@ -149,6 +173,9 @@ def encode(self, encoding: TransferEncoding) -> Series:
"ffff00"
"0000ff"
]
Encode values using Base64 encoding.
>>> s.bin.encode("base64")
shape: (3,)
Series: 'colors' [str]
Expand Down
21 changes: 19 additions & 2 deletions py-polars/polars/series/string.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -635,8 +635,8 @@ def starts_with(self, prefix: str | Expr) -> Series:
"""

def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
"""
Decode a value using the provided encoding.
r"""
Decode values using the provided encoding.
Parameters
----------
Expand All @@ -645,6 +645,23 @@ 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.
Returns
-------
Series
Series of data type :class:`Binary`.
Examples
--------
>>> s = pl.Series("color", ["000000", "ffff00", "0000ff"])
>>> s.str.decode("hex")
shape: (3,)
Series: 'color' [binary]
[
b"\x00\x00\x00"
b"\xff\xff\x00"
b"\x00\x00\xff"
]
"""

def encode(self, encoding: TransferEncoding) -> Series:
Expand Down

0 comments on commit 912edc3

Please sign in to comment.