TIF_E41253394/venv/Lib/site-packages/narwhals/series_cat.py

53 lines
2.1 KiB
Python

from __future__ import annotations
from typing import Generic
from narwhals._constants import GET_CATEGORIES_DEPRECATION_TEMPLATE
from narwhals._exceptions import issue_deprecation_warning
from narwhals._utils import Version
from narwhals.dtypes import String
from narwhals.typing import SeriesT
class SeriesCatNamespace(Generic[SeriesT]):
def __init__(self, series: SeriesT) -> None:
self._narwhals_series = series
def get_categories(self) -> SeriesT:
"""Get unique categories from column.
Warning:
This is deprecated and it will be removed in a future version, as Polars
removed its own `cat.get_categories`.
To get the distinct values present in a Categorical column, use
[`Series.unique`][narwhals.series.Series.unique].
For the fixed category list of an Enum, use its `dtype.categories`.
Until it is removed, it is implemented as
`unique(maintain_order=True).drop_nulls().cast(String)`, so it returns only
the values which are actually present, in order of appearance.
Note:
In `narwhals.stable.v1` and `narwhals.stable.v2` this stays available, and
keeps dispatching to each backend's native implementation.
Examples:
>>> import pandas as pd
>>> import narwhals.stable.v2 as nw
>>> s_native = pd.Series(["apple", "mango", "mango"], dtype="category")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cat.get_categories().to_native()
0 apple
1 mango
dtype: str
"""
if self._narwhals_series._version in {Version.V1, Version.V2}:
return self._narwhals_series._with_compliant(
self._narwhals_series._compliant_series.cat.get_categories()
)
issue_deprecation_warning(
GET_CATEGORIES_DEPRECATION_TEMPLATE.format(cls="Series"), _version="2.26.0"
)
return self._narwhals_series.unique(maintain_order=True).drop_nulls().cast(String)