maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/dataframe/accessors/string_/accessor.py

@@ -0,0 +1,215 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from functools import wraps
+from typing import Iterable
+
+import pandas as pd
+
+from ....utils import adapt_docstring
+from .core import SeriesStringMethod, string_method_to_handlers
+
+
+class StringAccessor:
+    """
+    Vectorized string functions for Series and Index.
+    NAs stay NA unless handled otherwise by a particular method.
+    Patterned after Python's string methods, with some inspiration from
+    R's stringr package.
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> s = md.Series(["A_Str_Series"])
+    >>> s.execute()
+    0    A_Str_Series
+    dtype: object
+    >>> s.str.split("_").execute()
+    0    [A, Str, Series]
+    dtype: object
+    >>> s.str.replace("_", "").execute()
+    0    AStrSeries
+    dtype: object
+    """
+
+    def __init__(self, series):
+        self._series = series
+
+    @classmethod
+    def _gen_func(cls, method):
+        @wraps(getattr(pd.Series.str, method))
+        def _inner(self, *args, **kwargs):
+            op = SeriesStringMethod(
+                method=method, method_args=args, method_kwargs=kwargs
+            )
+            return op(self._series)
+
+        _inner.__doc__ = adapt_docstring(getattr(pd.Series.str, method).__doc__)
+        return _inner
+
+    def __getitem__(self, item):
+        return self._gen_func("__getitem__")(self, item)
+
+    def __dir__(self) -> Iterable[str]:
+        s = set(super().__dir__())
+        s.update(string_method_to_handlers.keys())
+        return list(s)
+
+    @classmethod
+    def _register(cls, method):
+        setattr(cls, method, cls._gen_func(method))
+
+    def split(self, pat=None, n=-1, expand=False):
+        r"""
+        Split strings around given separator/delimiter.
+
+        Splits the string in the Series/Index from the beginning,
+        at the specified delimiter string. Equivalent to :meth:`str.split`.
+
+        Parameters
+        ----------
+        pat : str, optional
+            String or regular expression to split on.
+            If not specified, split on whitespace.
+        n : int, default -1 (all)
+            Limit number of splits in output.
+            ``None``, 0 and -1 will be interpreted as return all splits.
+        expand : bool, default False
+            Expand the splitted strings into separate columns.
+
+            * If ``True``, return DataFrame/MultiIndex expanding dimensionality.
+            * If ``False``, return Series/Index, containing lists of strings.
+
+        Returns
+        -------
+        Series, Index, DataFrame or MultiIndex
+            Type matches caller unless ``expand=True`` (see Notes).
+
+        See Also
+        --------
+        Series.str.split : Split strings around given separator/delimiter.
+        Series.str.rsplit : Splits string around given separator/delimiter,
+            starting from the right.
+        Series.str.join : Join lists contained as elements in the Series/Index
+            with passed delimiter.
+        str.split : Standard library version for split.
+        str.rsplit : Standard library version for rsplit.
+
+        Notes
+        -----
+        The handling of the `n` keyword depends on the number of found splits:
+
+        - If found splits > `n`,  make first `n` splits only
+        - If found splits <= `n`, make all splits
+        - If for a certain row the number of found splits < `n`,
+          append `None` for padding up to `n` if ``expand=True``
+
+        If using ``expand=True``, Series and Index callers return DataFrame and
+        MultiIndex objects, respectively.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> import maxframe.dataframe as md
+        >>> s = md.Series(["this is a regular sentence",
+        >>>                "https://docs.python.org/3/tutorial/index.html",
+        >>>                np.nan])
+        >>> s.execute()
+        0                       this is a regular sentence
+        1    https://docs.python.org/3/tutorial/index.html
+        2                                              NaN
+        dtype: object
+
+        In the default setting, the string is split by whitespace.
+
+        >>> s.str.split().execute()
+        0                   [this, is, a, regular, sentence]
+        1    [https://docs.python.org/3/tutorial/index.html]
+        2                                                NaN
+        dtype: object
+
+        Without the `n` parameter, the outputs of `rsplit` and `split`
+        are identical.
+
+        >>> s.str.rsplit().execute()
+        0                   [this, is, a, regular, sentence]
+        1    [https://docs.python.org/3/tutorial/index.html]
+        2                                                NaN
+        dtype: object
+
+        The `n` parameter can be used to limit the number of splits on the
+        delimiter. The outputs of `split` and `rsplit` are different.
+
+        >>> s.str.split(n=2).execute()
+        0                     [this, is, a regular sentence]
+        1    [https://docs.python.org/3/tutorial/index.html]
+        2                                                NaN
+        dtype: object
+
+        >>> s.str.rsplit(n=2).execute()
+        0                     [this is a, regular, sentence]
+        1    [https://docs.python.org/3/tutorial/index.html]
+        2                                                NaN
+        dtype: object
+
+        The `pat` parameter can be used to split by other characters.
+
+        >>> s.str.split(pat = "/").execute()
+        0                         [this is a regular sentence]
+        1    [https:, , docs.python.org, 3, tutorial, index...
+        2                                                  NaN
+        dtype: object
+
+        When using ``expand=True``, the split elements will expand out into
+        separate columns. If NaN is present, it is propagated throughout
+        the columns during the split.
+
+        >>> s.str.split(expand=True).execute()
+                                                       0     1     2        3
+        0                                           this    is     a  regular
+        1  https://docs.python.org/3/tutorial/index.html  None  None     None
+        2                                            NaN   NaN   NaN      NaN \
+                     4
+        0     sentence
+        1         None
+        2          NaN
+
+        For slightly more complex use cases like splitting the html document name
+        from a url, a combination of parameter settings can be used.
+
+        >>> s.str.rsplit("/", n=1, expand=True).execute()
+                                            0           1
+        0          this is a regular sentence        None
+        1  https://docs.python.org/3/tutorial  index.html
+        2                                 NaN         NaN
+
+        Remember to escape special characters when explicitly using regular
+        expressions.
+
+        >>> s = pd.Series(["1+1=2"])
+        >>> s.str.split(r"\+|=", expand=True).execute()
+             0    1    2
+        0    1    1    2
+        """
+        return self._gen_func("split")(self, pat=pat, n=n, expand=expand)
+
+    def rsplit(self, pat=None, n=-1, expand=False):
+        return self._gen_func("rsplit")(self, pat=pat, n=n, expand=expand)
+
+    def cat(self, others=None, sep=None, na_rep=None, join="left"):
+        return self._gen_func("cat")(
+            self, others=others, sep=sep, na_rep=na_rep, join=join
+        )
+
+    rsplit.__doc__ = adapt_docstring(pd.Series.str.rsplit.__doc__)
+    cat.__doc__ = adapt_docstring(pd.Series.str.cat.__doc__)

maxframe/dataframe/accessors/string_/core.py

@@ -0,0 +1,226 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import List
+
+import numpy as np
+import pandas as pd
+
+from .... import opcodes
+from ....core import EntityData, OutputType
+from ....serialization.serializables import DictField, KeyField, StringField, TupleField
+from ....tensor import tensor as astensor
+from ....tensor.core import TENSOR_TYPE
+from ...core import SERIES_TYPE
+from ...initializer import Series as asseries
+from ...operators import DataFrameOperator, DataFrameOperatorMixin
+from ...utils import build_empty_series, build_series, infer_index_value, parse_index
+
+
+class SeriesStringMethod(DataFrameOperator, DataFrameOperatorMixin):
+    _op_type_ = opcodes.STRING_METHOD
+
+    _input = KeyField("input")
+    method = StringField("method", default=None)
+    method_args = TupleField("method_args", default=None)
+    method_kwargs = DictField("method_kwargs", default=None)
+
+    def __init__(self, output_types=None, **kw):
+        super().__init__(_output_types=output_types, **kw)
+        if not self.output_types:
+            self.output_types = [OutputType.series]
+
+    @property
+    def input(self):
+        return self._input
+
+    @classmethod
+    def _set_inputs(cls, op: "SeriesStringMethod", inputs: List[EntityData]):
+        super()._set_inputs(op, inputs)
+        op._input = op._inputs[0]
+        if len(op._inputs) == 2:
+            # for method cat
+            op.method_kwargs["others"] = op._inputs[1]
+
+    def __call__(self, inp):
+        return string_method_to_handlers[self.method].call(self, inp)
+
+
+class SeriesStringMethodBaseHandler:
+    @classmethod
+    def call(cls, op: SeriesStringMethod, inp):
+        if op.method == "__getitem__":
+            op.method = "slice"
+            kwargs = {
+                "start": op.method_args[0].start,
+                "stop": op.method_args[0].stop,
+                "step": op.method_args[0].step,
+            }
+            op.method_args = ()
+            op.method_kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+        empty_series = build_empty_series(inp.dtype)
+        dtype = getattr(empty_series.str, op.method)(
+            *op.method_args, **op.method_kwargs
+        ).dtype
+        return op.new_series(
+            [inp],
+            shape=inp.shape,
+            dtype=dtype,
+            index_value=inp.index_value,
+            name=inp.name,
+        )
+
+
+class SeriesStringSplitHandler(SeriesStringMethodBaseHandler):
+    @classmethod
+    def call(cls, op, inp):
+        method_kwargs = op.method_kwargs
+        if method_kwargs.get("expand", False) is False:
+            return super().call(op, inp)
+        n = method_kwargs.get("n", -1)
+
+        op.output_types = [OutputType.dataframe]
+
+        if n >= 0:
+            columns = pd.RangeIndex(n + 1)
+            n_cols = n + 1
+            columns_value = parse_index(columns, store_data=True)
+            dtypes = pd.Series([inp.dtype] * len(columns), index=columns)
+        else:
+            dtypes = columns_value = None
+            n_cols = np.nan
+
+        return op.new_dataframe(
+            [inp],
+            shape=(inp.shape[0], n_cols),
+            dtypes=dtypes,
+            columns_value=columns_value,
+            index_value=inp.index_value,
+        )
+
+
+class SeriesStringCatHandler(SeriesStringMethodBaseHandler):
+    CAT_TYPE_ERROR = (
+        "others must be Series, Index, DataFrame, "
+        "Tensor, np.ndarrary or list-like "
+        "(either containing only strings or "
+        "containing only objects of "
+        "type Series/Index/Tensor/np.ndarray[1-dim])"
+    )
+    CAT_LEN_ERROR = (
+        "If `others` contains arrays or lists (or other list-likes without an index), "
+        "these must all be of the same length as the calling Series/Index."
+    )
+
+    @classmethod
+    def call(cls, op, inp):
+        method_kwargs = op.method_kwargs
+        others = method_kwargs.get("others")
+
+        if others is None:
+            from ...reduction import build_str_concat_object
+
+            return build_str_concat_object(
+                inp,
+                sep=op.method_kwargs.get("sep"),
+                na_rep=op.method_kwargs.get("na_rep"),
+            )
+        elif isinstance(others, (tuple, list, np.ndarray, TENSOR_TYPE)):
+            others = astensor(others, dtype=object)
+            if others.ndim != 1:
+                raise TypeError(cls.CAT_TYPE_ERROR)
+            if (
+                not np.isnan(inp.shape[0])
+                and not np.isnan(others.shape[0])
+                and inp.shape[0] != others.shape[0]
+            ):
+                raise ValueError(cls.CAT_LEN_ERROR)
+            inputs = [inp]
+            if isinstance(others, TENSOR_TYPE):
+                inputs.append(others)
+            return op.new_series(
+                inputs,
+                shape=inp.shape,
+                dtype=inp.dtype,
+                index_value=inp.index_value,
+                name=inp.name,
+            )
+        elif isinstance(others, (pd.Series, SERIES_TYPE)):
+            others = asseries(others)
+            if op.method_kwargs.get("join") != "outer":  # pragma: no cover
+                raise NotImplementedError("only outer join supported for now")
+            return op.new_series(
+                [inp, others],
+                shape=inp.shape,
+                dtype=inp.dtype,
+                index_value=infer_index_value(inp.index_value, others.index_value),
+                name=inp.name,
+            )
+        elif isinstance(others, str) and op.method_kwargs.get("sep") is None:
+            raise ValueError("Did you mean to supply a `sep` keyword?")
+        else:
+            raise TypeError(cls.CAT_TYPE_ERROR)
+
+
+class SeriesStringExtractHandler(SeriesStringMethodBaseHandler):
+    @classmethod
+    def call(cls, op, inp):
+        mock_series = build_series(inp)
+        test_df = getattr(mock_series.str, op.method)(
+            *op.method_args, **op.method_kwargs
+        )
+        if test_df.ndim == 1:
+            return op.new_series(
+                [inp],
+                shape=inp.shape,
+                dtype=test_df.dtype,
+                index_value=inp.index_value,
+                name=inp.name,
+            )
+        else:
+            op.output_types = [OutputType.dataframe]
+            if op.method == "extractall":
+                index_value = parse_index(test_df.index, inp)
+                shape = (np.nan, test_df.shape[1])
+            else:
+                index_value = inp.index_value
+                shape = (inp.shape[0], test_df.shape[1])
+            return op.new_dataframe(
+                [inp],
+                shape=shape,
+                dtypes=test_df.dtypes,
+                index_value=index_value,
+                columns_value=parse_index(test_df.columns, store_data=True),
+            )
+
+
+string_method_to_handlers = {}
+_not_implements = ["get_dummies"]
+# start to register handlers for string methods
+# register special methods first
+string_method_to_handlers["split"] = SeriesStringSplitHandler
+string_method_to_handlers["rsplit"] = SeriesStringSplitHandler
+string_method_to_handlers["cat"] = SeriesStringCatHandler
+string_method_to_handlers["extract"] = SeriesStringExtractHandler
+string_method_to_handlers["extractall"] = SeriesStringExtractHandler
+# then come to the normal methods
+for method in dir(pd.Series.str):
+    if method.startswith("_") and method != "__getitem__":
+        continue
+    if method in _not_implements:
+        continue
+    if method in string_method_to_handlers:
+        continue
+    string_method_to_handlers[method] = SeriesStringMethodBaseHandler

maxframe/dataframe/accessors/string_/tests/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

maxframe/dataframe/accessors/string_/tests/test_string_accessor.py

@@ -0,0 +1,73 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from ....core import OutputType
+from ....datasource.series import from_pandas as from_pandas_series
+
+
+def test_string_method():
+    s = pd.Series(["a", "b", "c"], name="s")
+    series = from_pandas_series(s, chunk_size=2)
+
+    with pytest.raises(AttributeError):
+        _ = series.str.non_exist
+
+    r = series.str.contains("c")
+    assert r.dtype == np.bool_
+    assert r.name == s.name
+    pd.testing.assert_index_equal(r.index_value.to_pandas(), s.index)
+    assert r.shape == s.shape
+
+    r = series.str.split(",", expand=True, n=1)
+    assert r.op.output_types[0] == OutputType.dataframe
+    assert r.shape == (3, 2)
+    pd.testing.assert_index_equal(r.index_value.to_pandas(), s.index)
+    pd.testing.assert_index_equal(r.columns_value.to_pandas(), pd.RangeIndex(2))
+
+    with pytest.raises(TypeError):
+        _ = series.str.cat([["1", "2"]])
+
+    with pytest.raises(ValueError):
+        _ = series.str.cat(["1", "2"])
+
+    with pytest.raises(ValueError):
+        _ = series.str.cat(",")
+
+    with pytest.raises(TypeError):
+        _ = series.str.cat({"1", "2", "3"})
+
+    r = series.str.cat(sep=",")
+    assert r.op.output_types[0] == OutputType.scalar
+    assert r.dtype == s.dtype
+
+    r = series.str.extract(r"[ab](\d)", expand=False)
+    assert r.op.output_types[0] == OutputType.series
+    assert r.dtype == s.dtype
+
+    r = series.str.extract(r"[ab](\d)", expand=True)
+    assert r.op.output_types[0] == OutputType.dataframe
+    assert r.shape == (3, 1)
+    pd.testing.assert_index_equal(r.index_value.to_pandas(), s.index)
+    pd.testing.assert_index_equal(r.columns_value.to_pandas(), pd.RangeIndex(1))
+
+    assert "lstrip" in dir(series.str)
+
+    r = series.str[1:10:2]
+    assert r.op.method == "slice"
+    assert r.op.method_args == ()
+    assert r.op.method_kwargs == {"start": 1, "stop": 10, "step": 2}

maxframe/dataframe/accessors/struct_/__init__.py

@@ -0,0 +1,39 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .core import SeriesStructMethod
+
+
+def _install():
+    from ....core import CachedAccessor
+    from ...core import SERIES_TYPE
+    from .accessor import StructAccessor
+    from .dtypes import struct_dtypes
+    from .field import struct_field
+
+    struct_method_to_handlers = {
+        "dtypes": struct_dtypes,
+        "field": struct_field,
+    }
+    property_names = {"dtypes"}
+
+    for name, handler in struct_method_to_handlers.items():
+        StructAccessor._register(name, handler, is_property=name in property_names)
+
+    for series in SERIES_TYPE:
+        series.struct = CachedAccessor("struct", StructAccessor)
+
+
+_install()
+del _install

maxframe/dataframe/accessors/struct_/accessor.py

@@ -0,0 +1,39 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+import pyarrow as pa
+
+from ....core import BaseMaxFrameAccessor
+from ....utils import ARROW_DTYPE_NOT_SUPPORTED
+
+if TYPE_CHECKING:
+    from ...core import Series
+
+
+class StructAccessor(BaseMaxFrameAccessor):
+    obj: "Series"
+    _api_count: int = 0
+
+    def __init__(self, series):
+        super().__init__(series)
+        if ARROW_DTYPE_NOT_SUPPORTED:
+            raise ImportError("pd.ArrowDtype is not supported in current environment")
+
+        if not isinstance(series.dtype, pd.ArrowDtype) or not isinstance(
+            series.dtype.pyarrow_dtype, pa.StructType
+        ):
+            raise AttributeError("Can only use .struct accessor with struct values")

maxframe/dataframe/accessors/struct_/core.py

@@ -0,0 +1,43 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .... import opcodes
+from ....core import OutputType
+from ....serialization.serializables import DictField, StringField, TupleField
+from ....utils import no_default
+from ...operators import DataFrameOperator, DataFrameOperatorMixin
+
+
+class SeriesStructMethod(DataFrameOperator, DataFrameOperatorMixin):
+    _op_type_ = opcodes.SERIES_STRUCT_METHOD
+
+    method = StringField("method", default=None)
+    method_args = TupleField("method_args", default_factory=list)
+    method_kwargs = DictField("method_kwargs", default_factory=dict)
+
+    def __init__(self, output_types=None, **kw):
+        output_types = output_types or [OutputType.series]
+        kw["_output_types"] = kw.get("_output_types") or output_types
+        super().__init__(**kw)
+
+    def __call__(self, inp, dtype=None, name=no_default):
+        dtype = dtype if dtype is not None else inp.dtype
+        name = inp.name if name is no_default else name
+        return self.new_series(
+            [inp],
+            shape=inp.shape,
+            dtype=dtype,
+            index_value=inp.index_value,
+            name=name,
+        )