polars-runtime-compat 1.34.0b3__cp39-abi3-win_amd64.whl → 1.34.0b4__cp39-abi3-win_amd64.whl

polars/expr/binary.py

@@ -1,346 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from polars._utils.parse import parse_into_expression
-from polars._utils.various import scale_bytes
-from polars._utils.wrap import wrap_expr
-from polars.datatypes import parse_into_datatype_expr
-
-if TYPE_CHECKING:
-    from polars import DataTypeExpr, Expr
-    from polars._typing import (
-        Endianness,
-        IntoExpr,
-        PolarsDataType,
-        SizeUnit,
-        TransferEncoding,
-    )
-
-
-class ExprBinaryNameSpace:
-    """Namespace for bin related expressions."""
-
-    _accessor = "bin"
-
-    def __init__(self, expr: Expr) -> None:
-        self._pyexpr = expr._pyexpr
-
-    def contains(self, literal: IntoExpr) -> Expr:
-        r"""
-        Check if binaries in Series contain a binary substring.
-
-        Parameters
-        ----------
-        literal
-            The binary substring to look for
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`Boolean`.
-
-        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"],
-        ...         "lit": [b"\x00", b"\xff\x00", b"\xff\xff"],
-        ...     }
-        ... )
-        >>> colors.select(
-        ...     "name",
-        ...     pl.col("code").bin.contains(b"\xff").alias("contains_with_lit"),
-        ...     pl.col("code").bin.contains(pl.col("lit")).alias("contains_with_expr"),
-        ... )
-        shape: (3, 3)
-        ┌────────┬───────────────────┬────────────────────┐
-        │ name   ┆ contains_with_lit ┆ contains_with_expr │
-        │ ---    ┆ ---               ┆ ---                │
-        │ str    ┆ bool              ┆ bool               │
-        ╞════════╪═══════════════════╪════════════════════╡
-        │ black  ┆ false             ┆ true               │
-        │ yellow ┆ true              ┆ true               │
-        │ blue   ┆ true              ┆ false              │
-        └────────┴───────────────────┴────────────────────┘
-        """
-        literal_pyexpr = parse_into_expression(literal, str_as_lit=True)
-        return wrap_expr(self._pyexpr.bin_contains(literal_pyexpr))
-
-    def ends_with(self, suffix: IntoExpr) -> Expr:
-        r"""
-        Check if string values end with a binary substring.
-
-        Parameters
-        ----------
-        suffix
-            Suffix substring.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`Boolean`.
-
-        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"],
-        ...         "suffix": [b"\x00", b"\xff\x00", b"\x00\x00"],
-        ...     }
-        ... )
-        >>> colors.select(
-        ...     "name",
-        ...     pl.col("code").bin.ends_with(b"\xff").alias("ends_with_lit"),
-        ...     pl.col("code").bin.ends_with(pl.col("suffix")).alias("ends_with_expr"),
-        ... )
-        shape: (3, 3)
-        ┌────────┬───────────────┬────────────────┐
-        │ name   ┆ ends_with_lit ┆ ends_with_expr │
-        │ ---    ┆ ---           ┆ ---            │
-        │ str    ┆ bool          ┆ bool           │
-        ╞════════╪═══════════════╪════════════════╡
-        │ black  ┆ false         ┆ true           │
-        │ yellow ┆ false         ┆ true           │
-        │ blue   ┆ true          ┆ false          │
-        └────────┴───────────────┴────────────────┘
-        """
-        suffix_pyexpr = parse_into_expression(suffix, str_as_lit=True)
-        return wrap_expr(self._pyexpr.bin_ends_with(suffix_pyexpr))
-
-    def starts_with(self, prefix: IntoExpr) -> Expr:
-        r"""
-        Check if values start with a binary substring.
-
-        Parameters
-        ----------
-        prefix
-            Prefix substring.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`Boolean`.
-
-        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"],
-        ...         "prefix": [b"\x00", b"\xff\x00", b"\x00\x00"],
-        ...     }
-        ... )
-        >>> colors.select(
-        ...     "name",
-        ...     pl.col("code").bin.starts_with(b"\xff").alias("starts_with_lit"),
-        ...     pl.col("code")
-        ...     .bin.starts_with(pl.col("prefix"))
-        ...     .alias("starts_with_expr"),
-        ... )
-        shape: (3, 3)
-        ┌────────┬─────────────────┬──────────────────┐
-        │ name   ┆ starts_with_lit ┆ starts_with_expr │
-        │ ---    ┆ ---             ┆ ---              │
-        │ str    ┆ bool            ┆ bool             │
-        ╞════════╪═════════════════╪══════════════════╡
-        │ black  ┆ false           ┆ true             │
-        │ yellow ┆ true            ┆ false            │
-        │ blue   ┆ false           ┆ true             │
-        └────────┴─────────────────┴──────────────────┘
-        """
-        prefix_pyexpr = parse_into_expression(prefix, str_as_lit=True)
-        return wrap_expr(self._pyexpr.bin_starts_with(prefix_pyexpr))
-
-    def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Expr:
-        r"""
-        Decode values using the provided encoding.
-
-        Parameters
-        ----------
-        encoding : {'hex', 'base64'}
-            The encoding to use.
-        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
-        --------
-        >>> colors = pl.DataFrame(
-        ...     {
-        ...         "name": ["black", "yellow", "blue"],
-        ...         "encoded": [b"000000", b"ffff00", b"0000ff"],
-        ...     }
-        ... )
-        >>> colors.with_columns(
-        ...     pl.col("encoded").bin.decode("hex").alias("code"),
-        ... )
-        shape: (3, 3)
-        ┌────────┬───────────┬─────────────────┐
-        │ name   ┆ encoded   ┆ code            │
-        │ ---    ┆ ---       ┆ ---             │
-        │ str    ┆ binary    ┆ binary          │
-        ╞════════╪═══════════╪═════════════════╡
-        │ black  ┆ b"000000" ┆ b"\x00\x00\x00" │
-        │ yellow ┆ b"ffff00" ┆ b"\xff\xff\x00" │
-        │ blue   ┆ b"0000ff" ┆ b"\x00\x00\xff" │
-        └────────┴───────────┴─────────────────┘
-        """
-        if encoding == "hex":
-            return wrap_expr(self._pyexpr.bin_hex_decode(strict))
-        elif encoding == "base64":
-            return wrap_expr(self._pyexpr.bin_base64_decode(strict))
-        else:
-            msg = f"`encoding` must be one of {{'hex', 'base64'}}, got {encoding!r}"
-            raise ValueError(msg)
-
-    def encode(self, encoding: TransferEncoding) -> Expr:
-        r"""
-        Encode a value using the provided encoding.
-
-        Parameters
-        ----------
-        encoding : {'hex', 'base64'}
-            The encoding to use.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`Binary`.
-
-        Examples
-        --------
-        >>> colors = pl.DataFrame(
-        ...     {
-        ...         "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("encoded"),
-        ... )
-        shape: (3, 3)
-        ┌────────┬─────────────────┬─────────┐
-        │ 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())
-        elif encoding == "base64":
-            return wrap_expr(self._pyexpr.bin_base64_encode())
-        else:
-            msg = f"`encoding` must be one of {{'hex', 'base64'}}, got {encoding!r}"
-            raise ValueError(msg)
-
-    def size(self, unit: SizeUnit = "b") -> Expr:
-        r"""
-        Get the size of binary values in the given unit.
-
-        Parameters
-        ----------
-        unit : {'b', 'kb', 'mb', 'gb', 'tb'}
-            Scale the returned size to the given unit.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`UInt32` or `Float64`.
-
-        Examples
-        --------
-        >>> from os import urandom
-        >>> df = pl.DataFrame({"data": [urandom(n) for n in (512, 256, 1024)]})
-        >>> df.with_columns(  # doctest: +IGNORE_RESULT
-        ...     n_bytes=pl.col("data").bin.size(),
-        ...     n_kilobytes=pl.col("data").bin.size("kb"),
-        ... )
-        shape: (4, 3)
-        ┌─────────────────────────────────┬─────────┬─────────────┐
-        │ data                            ┆ n_bytes ┆ n_kilobytes │
-        │ ---                             ┆ ---     ┆ ---         │
-        │ binary                          ┆ u32     ┆ f64         │
-        ╞═════════════════════════════════╪═════════╪═════════════╡
-        │ b"y?~B\x83\xf4V\x07\xd3\xfb\xb… ┆ 512     ┆ 0.5         │
-        │ b"\xee$4@f\xc14\x07\x8e\x88\x1… ┆ 256     ┆ 0.25        │
-        │ b"\x80\xbd\xb9nEq;2\x99$\xf9\x… ┆ 1024    ┆ 1.0         │
-        └─────────────────────────────────┴─────────┴─────────────┘
-        """
-        sz = wrap_expr(self._pyexpr.bin_size_bytes())
-        sz = scale_bytes(sz, unit)
-        return sz
-
-    def reinterpret(
-        self, *, dtype: PolarsDataType | DataTypeExpr, endianness: Endianness = "little"
-    ) -> Expr:
-        r"""
-        Interpret bytes as another type.
-
-        Supported types are numerical or temporal dtypes, or an ``Array`` of
-        these dtypes.
-
-        Parameters
-        ----------
-        dtype : PolarsDataType
-            Which type to interpret binary column into.
-        endianness : {"big", "little"}, optional
-            Which endianness to use when interpreting bytes, by default "little".
-
-        Returns
-        -------
-        Expr
-            Expression of data type `dtype`.
-            Note that rows of the binary array where the length does not match
-            the size in bytes of the output array (number of items * byte size
-            of item) will become NULL.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame({"data": [b"\x05\x00\x00\x00", b"\x10\x00\x01\x00"]})
-        >>> df.with_columns(  # doctest: +IGNORE_RESULT
-        ...     bin2int=pl.col("data").bin.reinterpret(
-        ...         dtype=pl.Int32, endianness="little"
-        ...     ),
-        ... )
-        shape: (2, 2)
-        ┌─────────────────────┬─────────┐
-        │ data                ┆ bin2int │
-        │ ---                 ┆ ---     │
-        │ binary              ┆ i32     │
-        ╞═════════════════════╪═════════╡
-        │ b"\x05\x00\x00\x00" ┆ 5       │
-        │ b"\x10\x00\x01\x00" ┆ 65552   │
-        └─────────────────────┴─────────┘
-        """
-        dtype = parse_into_datatype_expr(dtype)
-
-        return wrap_expr(
-            self._pyexpr.bin_reinterpret(dtype._pydatatype_expr, endianness)
-        )

polars/expr/categorical.py

@@ -1,306 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from polars._utils.various import qualified_type_name
-from polars._utils.wrap import wrap_expr
-
-if TYPE_CHECKING:
-    from polars import Expr
-
-
-class ExprCatNameSpace:
-    """Namespace for categorical related expressions."""
-
-    _accessor = "cat"
-
-    def __init__(self, expr: Expr) -> None:
-        self._pyexpr = expr._pyexpr
-
-    def get_categories(self) -> Expr:
-        """
-        Get the categories stored in this data type.
-
-        Examples
-        --------
-        >>> df = pl.Series(
-        ...     "cats", ["foo", "bar", "foo", "foo", "ham"], dtype=pl.Categorical
-        ... ).to_frame()
-        >>> df.select(pl.col("cats").cat.get_categories())  # doctest: +SKIP
-        shape: (3, 1)
-        ┌──────┐
-        │ cats │
-        │ ---  │
-        │ str  │
-        ╞══════╡
-        │ foo  │
-        │ bar  │
-        │ ham  │
-        └──────┘
-        """
-        return wrap_expr(self._pyexpr.cat_get_categories())
-
-    def len_bytes(self) -> Expr:
-        """
-        Return the byte-length of the string representation of each value.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`UInt32`.
-
-        See Also
-        --------
-        len_chars
-
-        Notes
-        -----
-        When working with non-ASCII text, the length in bytes is not the same as the
-        length in characters. You may want to use :func:`len_chars` instead.
-        Note that :func:`len_bytes` is much more performant (_O(1)_) than
-        :func:`len_chars` (_O(n)_).
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {"a": pl.Series(["Café", "345", "東京", None], dtype=pl.Categorical)}
-        ... )
-        >>> df.with_columns(
-        ...     pl.col("a").cat.len_bytes().alias("n_bytes"),
-        ...     pl.col("a").cat.len_chars().alias("n_chars"),
-        ... )
-        shape: (4, 3)
-        ┌──────┬─────────┬─────────┐
-        │ a    ┆ n_bytes ┆ n_chars │
-        │ ---  ┆ ---     ┆ ---     │
-        │ cat  ┆ u32     ┆ u32     │
-        ╞══════╪═════════╪═════════╡
-        │ Café ┆ 5       ┆ 4       │
-        │ 345  ┆ 3       ┆ 3       │
-        │ 東京 ┆ 6       ┆ 2       │
-        │ null ┆ null    ┆ null    │
-        └──────┴─────────┴─────────┘
-        """
-        return wrap_expr(self._pyexpr.cat_len_bytes())
-
-    def len_chars(self) -> Expr:
-        """
-        Return the number of characters of the string representation of each value.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`UInt32`.
-
-        See Also
-        --------
-        len_bytes
-
-        Notes
-        -----
-        When working with ASCII text, use :func:`len_bytes` instead to achieve
-        equivalent output with much better performance:
-        :func:`len_bytes` runs in _O(1)_, while :func:`len_chars` runs in (_O(n)_).
-
-        A character is defined as a `Unicode scalar value`_. A single character is
-        represented by a single byte when working with ASCII text, and a maximum of
-        4 bytes otherwise.
-
-        .. _Unicode scalar value: https://www.unicode.org/glossary/#unicode_scalar_value
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {"a": pl.Series(["Café", "345", "東京", None], dtype=pl.Categorical)}
-        ... )
-        >>> df.with_columns(
-        ...     pl.col("a").cat.len_chars().alias("n_chars"),
-        ...     pl.col("a").cat.len_bytes().alias("n_bytes"),
-        ... )
-        shape: (4, 3)
-        ┌──────┬─────────┬─────────┐
-        │ a    ┆ n_chars ┆ n_bytes │
-        │ ---  ┆ ---     ┆ ---     │
-        │ cat  ┆ u32     ┆ u32     │
-        ╞══════╪═════════╪═════════╡
-        │ Café ┆ 4       ┆ 5       │
-        │ 345  ┆ 3       ┆ 3       │
-        │ 東京 ┆ 2       ┆ 6       │
-        │ null ┆ null    ┆ null    │
-        └──────┴─────────┴─────────┘
-        """
-        return wrap_expr(self._pyexpr.cat_len_chars())
-
-    def starts_with(self, prefix: str) -> Expr:
-        """
-        Check if string representations of values start with a substring.
-
-        Parameters
-        ----------
-        prefix
-            Prefix substring.
-
-        See Also
-        --------
-        contains : Check if string repr contains a substring that matches a pattern.
-        ends_with : Check if string repr end with a substring.
-
-        Notes
-        -----
-        Whereas `str.starts_with` allows expression inputs, `cat.starts_with` requires
-        a literal string value.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {"fruits": pl.Series(["apple", "mango", None], dtype=pl.Categorical)}
-        ... )
-        >>> df.with_columns(
-        ...     pl.col("fruits").cat.starts_with("app").alias("has_prefix"),
-        ... )
-        shape: (3, 2)
-        ┌────────┬────────────┐
-        │ fruits ┆ has_prefix │
-        │ ---    ┆ ---        │
-        │ cat    ┆ bool       │
-        ╞════════╪════════════╡
-        │ apple  ┆ true       │
-        │ mango  ┆ false      │
-        │ null   ┆ null       │
-        └────────┴────────────┘
-
-        Using `starts_with` as a filter condition:
-
-        >>> df.filter(pl.col("fruits").cat.starts_with("app"))
-        shape: (1, 1)
-        ┌────────┐
-        │ fruits │
-        │ ---    │
-        │ cat    │
-        ╞════════╡
-        │ apple  │
-        └────────┘
-        """
-        if not isinstance(prefix, str):
-            msg = f"'prefix' must be a string; found {qualified_type_name(prefix)!r}"
-            raise TypeError(msg)
-        return wrap_expr(self._pyexpr.cat_starts_with(prefix))
-
-    def ends_with(self, suffix: str) -> Expr:
-        """
-        Check if string representations of values end with a substring.
-
-        Parameters
-        ----------
-        suffix
-            Suffix substring.
-
-        See Also
-        --------
-        contains : Check if string reprs contains a substring that matches a pattern.
-        starts_with : Check if string reprs start with a substring.
-
-        Notes
-        -----
-        Whereas `str.ends_with` allows expression inputs, `cat.ends_with` requires a
-        literal string value.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {"fruits": pl.Series(["apple", "mango", None], dtype=pl.Categorical)}
-        ... )
-        >>> df.with_columns(pl.col("fruits").cat.ends_with("go").alias("has_suffix"))
-        shape: (3, 2)
-        ┌────────┬────────────┐
-        │ fruits ┆ has_suffix │
-        │ ---    ┆ ---        │
-        │ cat    ┆ bool       │
-        ╞════════╪════════════╡
-        │ apple  ┆ false      │
-        │ mango  ┆ true       │
-        │ null   ┆ null       │
-        └────────┴────────────┘
-
-        Using `ends_with` as a filter condition:
-
-        >>> df.filter(pl.col("fruits").cat.ends_with("go"))
-        shape: (1, 1)
-        ┌────────┐
-        │ fruits │
-        │ ---    │
-        │ cat    │
-        ╞════════╡
-        │ mango  │
-        └────────┘
-        """
-        if not isinstance(suffix, str):
-            msg = f"'suffix' must be a string; found {qualified_type_name(suffix)!r}"
-            raise TypeError(msg)
-        return wrap_expr(self._pyexpr.cat_ends_with(suffix))
-
-    def slice(self, offset: int, length: int | None = None) -> Expr:
-        """
-        Extract a substring from the string representation of each value.
-
-        Parameters
-        ----------
-        offset
-            Start index. Negative indexing is supported.
-        length
-            Length of the slice. If set to `None` (default), the slice is taken to the
-            end of the string.
-
-        Returns
-        -------
-        Expr
-            Expression of data type :class:`String`.
-
-        Notes
-        -----
-        Both the `offset` and `length` inputs are defined in terms of the number
-        of characters in the (UTF8) string. A character is defined as a
-        `Unicode scalar value`_. A single character is represented by a single byte
-        when working with ASCII text, and a maximum of 4 bytes otherwise.
-
-        .. _Unicode scalar value: https://www.unicode.org/glossary/#unicode_scalar_value
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {
-        ...         "s": pl.Series(
-        ...             ["pear", None, "papaya", "dragonfruit"],
-        ...             dtype=pl.Categorical,
-        ...         )
-        ...     }
-        ... )
-        >>> df.with_columns(pl.col("s").cat.slice(-3).alias("slice"))
-        shape: (4, 2)
-        ┌─────────────┬───────┐
-        │ s           ┆ slice │
-        │ ---         ┆ ---   │
-        │ cat         ┆ str   │
-        ╞═════════════╪═══════╡
-        │ pear        ┆ ear   │
-        │ null        ┆ null  │
-        │ papaya      ┆ aya   │
-        │ dragonfruit ┆ uit   │
-        └─────────────┴───────┘
-
-        Using the optional `length` parameter
-
-        >>> df.with_columns(pl.col("s").cat.slice(4, length=3).alias("slice"))
-        shape: (4, 2)
-        ┌─────────────┬───────┐
-        │ s           ┆ slice │
-        │ ---         ┆ ---   │
-        │ cat         ┆ str   │
-        ╞═════════════╪═══════╡
-        │ pear        ┆       │
-        │ null        ┆ null  │
-        │ papaya      ┆ ya    │
-        │ dragonfruit ┆ onf   │
-        └─────────────┴───────┘
-        """
-        return wrap_expr(self._pyexpr.cat_slice(offset, length))