Skip to content

Commit

Permalink
docs(python): Adding examples to binary functions (pola-rs#9553)
Browse files Browse the repository at this point in the history
  • Loading branch information
@datapythonista @c-peters
datapythonista authored and c-peters committed Jul 14, 2023
1 parent 9aadcad commit 2775ed2
Showing 1 changed file with 123 additions and 4 deletions.
127 changes: 123 additions & 4 deletions py-polars/polars/expr/binary.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ def __init__(self, expr: Expr):
self._pyexpr = expr._pyexpr

def contains(self, literal: bytes) -> Expr:
"""
r"""
Check if binaries in Series contain a binary substring.
Parameters
Expand All @@ -30,30 +30,128 @@ def contains(self, literal: bytes) -> Expr:
-------
Boolean mask
See Also
--------
starts_with : Check if the binary substring exists at the start
ends_with : Check if the binary substring exists at the end
Examples
--------
>>> colors = pl.DataFrame(
... {
... "name": ["black", "yellow", "blue"],
... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"],
... }
... )
>>> colors.select(
... "name",
... pl.col("code").bin.encode("hex").alias("code_encoded_hex"),
... pl.col("code").bin.contains(b"\xff").alias("contains_ff"),
... pl.col("code").bin.starts_with(b"\xff").alias("starts_with_ff"),
... pl.col("code").bin.ends_with(b"\xff").alias("ends_with_ff"),
... )
shape: (3, 5)
┌────────┬──────────────────┬─────────────┬────────────────┬──────────────┐
│ name ┆ code_encoded_hex ┆ contains_ff ┆ starts_with_ff ┆ ends_with_ff │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ bool ┆ bool ┆ bool │
╞════════╪══════════════════╪═════════════╪════════════════╪══════════════╡
│ black ┆ 000000 ┆ false ┆ false ┆ false │
│ yellow ┆ ffff00 ┆ true ┆ true ┆ false │
│ blue ┆ 0000ff ┆ true ┆ false ┆ true │
└────────┴──────────────────┴─────────────┴────────────────┴──────────────┘
"""
return wrap_expr(self._pyexpr.bin_contains(literal))

def ends_with(self, suffix: bytes) -> Expr:
"""
r"""
Check if string values end with a binary substring.
Parameters
----------
suffix
Suffix substring.
Returns
-------
Boolean mask
See Also
--------
starts_with : Check if the binary substring exists at the start
contains : Check if the binary substring exists anywhere
Examples
--------
>>> colors = pl.DataFrame(
... {
... "name": ["black", "yellow", "blue"],
... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"],
... }
... )
>>> colors.select(
... "name",
... pl.col("code").bin.encode("hex").alias("code_encoded_hex"),
... pl.col("code").bin.contains(b"\xff").alias("contains_ff"),
... pl.col("code").bin.starts_with(b"\xff").alias("starts_with_ff"),
... pl.col("code").bin.ends_with(b"\xff").alias("ends_with_ff"),
... )
shape: (3, 5)
┌────────┬──────────────────┬─────────────┬────────────────┬──────────────┐
│ name ┆ code_encoded_hex ┆ contains_ff ┆ starts_with_ff ┆ ends_with_ff │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ bool ┆ bool ┆ bool │
╞════════╪══════════════════╪═════════════╪════════════════╪══════════════╡
│ black ┆ 000000 ┆ false ┆ false ┆ false │
│ yellow ┆ ffff00 ┆ true ┆ true ┆ false │
│ blue ┆ 0000ff ┆ true ┆ false ┆ true │
└────────┴──────────────────┴─────────────┴────────────────┴──────────────┘
"""
return wrap_expr(self._pyexpr.bin_ends_with(suffix))

def starts_with(self, prefix: bytes) -> Expr:
"""
r"""
Check if values start with a binary substring.
Parameters
----------
prefix
Prefix substring.
Returns
-------
Boolean mask
See Also
--------
ends_with : Check if the binary substring exists at the end
contains : Check if the binary substring exists anywhere
Examples
--------
>>> colors = pl.DataFrame(
... {
... "name": ["black", "yellow", "blue"],
... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"],
... }
... )
>>> colors.select(
... "name",
... pl.col("code").bin.encode("hex").alias("code_encoded_hex"),
... pl.col("code").bin.contains(b"\xff").alias("contains_ff"),
... pl.col("code").bin.starts_with(b"\xff").alias("starts_with_ff"),
... pl.col("code").bin.ends_with(b"\xff").alias("ends_with_ff"),
... )
shape: (3, 5)
┌────────┬──────────────────┬─────────────┬────────────────┬──────────────┐
│ name ┆ code_encoded_hex ┆ contains_ff ┆ starts_with_ff ┆ ends_with_ff │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ bool ┆ bool ┆ bool │
╞════════╪══════════════════╪═════════════╪════════════════╪══════════════╡
│ black ┆ 000000 ┆ false ┆ false ┆ false │
│ yellow ┆ ffff00 ┆ true ┆ true ┆ false │
│ blue ┆ 0000ff ┆ true ┆ false ┆ true │
└────────┴──────────────────┴─────────────┴────────────────┴──────────────┘
"""
return wrap_expr(self._pyexpr.bin_starts_with(prefix))

Expand All @@ -80,7 +178,7 @@ def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:
)

def encode(self, encoding: TransferEncoding) -> Expr:
"""
r"""
Encode a value using the provided encoding.
Parameters
Expand All @@ -92,6 +190,27 @@ def encode(self, encoding: TransferEncoding) -> Expr:
-------
Binary array with values encoded using provided encoding
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("code_encoded_hex"),
... )
shape: (3, 3)
┌────────┬───────────────┬──────────────────┐
│ name ┆ code ┆ code_encoded_hex │
│ --- ┆ --- ┆ --- │
│ str ┆ binary ┆ str │
╞════════╪═══════════════╪══════════════════╡
│ black ┆ [binary data] ┆ 000000 │
│ yellow ┆ [binary data] ┆ ffff00 │
│ blue ┆ [binary data] ┆ 0000ff │
└────────┴───────────────┴──────────────────┘
"""
if encoding == "hex":
return wrap_expr(self._pyexpr.bin_hex_encode())
Expand Down

0 comments on commit 2775ed2

Please sign in to comment.