polars-runtime-compat 1.34.0b2__cp39-abi3-macosx_11_0_arm64.whl

polars/series/binary.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from polars.series.utils import expr_dispatch
+
+if TYPE_CHECKING:
+    from polars import Series
+    from polars._plr import PySeries
+    from polars._typing import (
+        Endianness,
+        IntoExpr,
+        PolarsDataType,
+        SizeUnit,
+        TransferEncoding,
+    )
+
+
+@expr_dispatch
+class BinaryNameSpace:
+    """Series.bin namespace."""
+
+    _accessor = "bin"
+
+    def __init__(self, series: Series) -> None:
+        self._s: PySeries = series._s
+
+    def contains(self, literal: IntoExpr) -> Series:
+        r"""
+        Check if binaries in Series contain a binary substring.
+
+        Parameters
+        ----------
+        literal
+            The binary substring to look for
+
+        Returns
+        -------
+        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.contains(b"\xff")
+        shape: (3,)
+        Series: 'colors' [bool]
+        [
+            false
+            true
+            true
+        ]
+        """
+
+    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 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
+        -------
+        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,)
+        Series: 'colors' [binary]
+        [
+            b"\x00\x00\x00"
+            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,)
+        Series: 'colors' [binary]
+        [
+            b"\x00\x00\x00"
+            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 values using the provided encoding.
+
+        Parameters
+        ----------
+        encoding : {'hex', 'base64'}
+            The encoding to use.
+
+        Returns
+        -------
+        Series
+            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,)
+        Series: 'colors' [str]
+        [
+            "000000"
+            "ffff00"
+            "0000ff"
+        ]
+
+        Encode values using Base64 encoding.
+
+        >>> s.bin.encode("base64")
+        shape: (3,)
+        Series: 'colors' [str]
+        [
+            "AAAA"
+            "//8A"
+            "AAD/"
+        ]
+        """
+
+    def size(self, unit: SizeUnit = "b") -> Series:
+        r"""
+        Get the size of the binary values in a Series in the given unit.
+
+        Returns
+        -------
+        Series
+            Series of data type :class:`UInt32`.
+
+        Examples
+        --------
+        >>> from os import urandom
+        >>> s = pl.Series("data", [urandom(n) for n in (512, 256, 2560, 1024)])
+        >>> s.bin.size("kb")
+        shape: (4,)
+        Series: 'data' [f64]
+        [
+            0.5
+            0.25
+            2.5
+            1.0
+        ]
+        """
+
+    def reinterpret(
+        self, *, dtype: PolarsDataType, endianness: Endianness = "little"
+    ) -> Series:
+        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
+        -------
+        Series
+            Series 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
+        --------
+        >>> s = pl.Series("data", [b"\x05\x00\x00\x00", b"\x10\x00\x01\x00"])
+        >>> s.bin.reinterpret(dtype=pl.Int32, endianness="little")
+        shape: (2,)
+        Series: 'data' [i32]
+        [
+            5
+            65552
+        ]
+
+        """

polars/series/categorical.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from polars._utils.unstable import unstable
+from polars._utils.wrap import wrap_s
+from polars.series.utils import expr_dispatch
+
+if TYPE_CHECKING:
+    from polars import Series
+    from polars._plr import PySeries
+
+
+@expr_dispatch
+class CatNameSpace:
+    """Namespace for categorical related series."""
+
+    _accessor = "cat"
+
+    def __init__(self, series: Series) -> None:
+        self._s: PySeries = series._s
+
+    def get_categories(self) -> Series:
+        """
+        Get the categories stored in this data type.
+
+        Examples
+        --------
+        >>> s = pl.Series(["foo", "bar", "foo", "foo", "ham"], dtype=pl.Categorical)
+        >>> s.cat.get_categories()  # doctest: +SKIP
+        shape: (3,)
+        Series: '' [str]
+        [
+            "foo"
+            "bar"
+            "ham"
+        ]
+        """
+
+    def is_local(self) -> bool:
+        """
+        Return whether or not the column is a local categorical.
+
+        Always returns false.
+        """
+        return self._s.cat_is_local()
+
+    def to_local(self) -> Series:
+        """Simply returns the column as-is, local representations are deprecated."""
+        return wrap_s(self._s.cat_to_local())
+
+    @unstable()
+    def uses_lexical_ordering(self) -> bool:
+        """
+        Indicate whether the Series uses lexical ordering.
+
+        .. warning::
+            This functionality is considered **unstable**. It may be changed
+            at any point without it being considered a breaking change.
+
+        Examples
+        --------
+        >>> s = pl.Series(["b", "a", "b"]).cast(pl.Categorical)
+        >>> s.cat.uses_lexical_ordering()
+        True
+        """
+        return self._s.cat_uses_lexical_ordering()
+
+    def len_bytes(self) -> Series:
+        """
+        Return the byte-length of the string representation of each value.
+
+        Returns
+        -------
+        Series
+            Series 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
+        --------
+        >>> s = pl.Series(["Café", "345", "東京", None], dtype=pl.Categorical)
+        >>> s.cat.len_bytes()
+        shape: (4,)
+        Series: '' [u32]
+        [
+            5
+            3
+            6
+            null
+        ]
+        """
+
+    def len_chars(self) -> Series:
+        """
+        Return the number of characters of the string representation of each value.
+
+        Returns
+        -------
+        Series
+            Series 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
+        --------
+        >>> s = pl.Series(["Café", "345", "東京", None], dtype=pl.Categorical)
+        >>> s.cat.len_chars()
+        shape: (4,)
+        Series: '' [u32]
+        [
+            4
+            3
+            2
+            null
+        ]
+        """
+
+    def starts_with(self, prefix: str) -> Series:
+        """
+        Check if string representations of values start with a substring.
+
+        Parameters
+        ----------
+        prefix
+            Prefix substring.
+
+        See Also
+        --------
+        contains : Check if the string repr contains a substring that matches a pattern.
+        ends_with : Check if string repr ends with a substring.
+
+        Examples
+        --------
+        >>> s = pl.Series("fruits", ["apple", "mango", None], dtype=pl.Categorical)
+        >>> s.cat.starts_with("app")
+        shape: (3,)
+        Series: 'fruits' [bool]
+        [
+            true
+            false
+            null
+        ]
+        """
+
+    def ends_with(self, suffix: str) -> Series:
+        """
+        Check if string representations of values end with a substring.
+
+        Parameters
+        ----------
+        suffix
+            Suffix substring.
+
+        See Also
+        --------
+        contains : Check if the string repr contains a substring that matches a pattern.
+        starts_with : Check if string repr starts with a substring.
+
+        Examples
+        --------
+        >>> s = pl.Series("fruits", ["apple", "mango", None], dtype=pl.Categorical)
+        >>> s.cat.ends_with("go")
+        shape: (3,)
+        Series: 'fruits' [bool]
+        [
+            false
+            true
+            null
+        ]
+        """
+
+    def slice(self, offset: int, length: int | None = None) -> Series:
+        """
+        Extract a substring from the string representation of each string 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
+        -------
+        Series
+            Series 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
+        --------
+        >>> s = pl.Series(["pear", None, "papaya", "dragonfruit"], dtype=pl.Categorical)
+        >>> s.cat.slice(-3)
+        shape: (4,)
+        Series: '' [str]
+        [
+            "ear"
+            null
+            "aya"
+            "uit"
+        ]
+
+        Using the optional `length` parameter
+
+        >>> s.cat.slice(4, length=3)
+        shape: (4,)
+        Series: '' [str]
+        [
+            ""
+            null
+            "ya"
+            "onf"
+        ]
+        """