flatbread 0.1.5__tar.gz → 0.2.0__tar.gz

flatbread-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+*.pyc
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+.vscode
+notebooks

{flatbread-0.1.5 → flatbread-0.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: flatbread
-Version: 0.1.5
+Version: 0.2.0
 Summary: Pandas extension for aggregation and tabular display
-Project-URL: Homepage, https://github.com/lcvriend/flatbread
+Project-URL: Homepage, https://github.com/flatbread-dataframes/flatbread
 Author-email: "L.C. Vriend" <vanboefer@gmail.com>
 License: # GNU GENERAL PUBLIC LICENSE
         
@@ -693,6 +693,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: jinja2
 Requires-Dist: pandas>=2.0.0
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: jupyter; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Flatbread

flatbread-0.2.0/flatbread/__init__.py

@@ -0,0 +1,17 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+    from flatbread.accessors.dataframe import PitaFrame
+    from flatbread.accessors.series import PitaSeries
+
+    class DataFrame(pd.DataFrame):
+        pita: PitaFrame
+
+    class Series(pd.Series):
+        pita: PitaSeries
+
+from flatbread.config import DEFAULTS
+import flatbread.accessors.dataframe
+import flatbread.accessors.series
+import flatbread.accessors.index

{flatbread-0.1.5 → flatbread-0.2.0}/flatbread/accessors/dataframe.py

@@ -1,12 +1,14 @@
 from typing import Any, Callable
+from pathlib import Path
 
 import pandas as pd
 
-import flatbread.percentages as pct
-import flatbread.agg.aggregation as agg
-import flatbread.agg.totals as tot
-import flatbread.tooling as tool
-from flatbread.render.display import PitaDisplayMixin
+import flatbread.transforms.percentages as pct
+import flatbread.transforms.aggregation as agg
+import flatbread.transforms.totals as totals
+import flatbread.axes as axes
+from flatbread.types import Axis, Level
+from flatbread.output.html import PitaDisplayMixin
 
 
 @pd.api.extensions.register_dataframe_accessor("pita")
@@ -19,8 +21,8 @@ class PitaFrame(PitaDisplayMixin):
         self,
         aggfunc: str|Callable,
         *args,
-        axis: int = 0,
-        label: str = None,
+        axis: Axis = 0,
+        label: str|None = None,
         ignore_keys: str|list[str]|None = None,
         _fill: str = '',
         **kwargs,
@@ -32,7 +34,7 @@ class PitaFrame(PitaDisplayMixin):
         ----------
         aggfunc (str|Callable):
             Function to use for aggregating the data.
-        axis (int):
+        axis (int | Literal["index", "columns", "both"]):
             Axis to aggregate. Default 0.
         label (str|None):
             Label for the aggregation row/column. Default None.
@@ -62,11 +64,12 @@ class PitaFrame(PitaDisplayMixin):
     def add_subagg(
         self,
         aggfunc: str|Callable,
-        axis: int = 0,
+        axis: Axis = 0,
         level: int|str|list[int|str] = 0,
-        label: str = None,
+        label: str|None = None,
         include_level_name: bool = False,
         ignore_keys: str|list[str]|None = None,
+        skip_single_rows: bool = True,
         _fill: str = '',
     ) -> pd.DataFrame:
         """
@@ -76,14 +79,18 @@ class PitaFrame(PitaDisplayMixin):
         ----------
         aggfunc (str|Callable):
             Function to use for aggregating the data.
-        axis (int):
+        axis (int | Literal["index", "columns", "both"]):
             Axis to aggregate. Default 0.
         levels (int|str|list[int|str]):
             Levels to aggregate. Default 0.
         label (str|None):
             Label for the aggregation row/column. Default None.
+        include_level_name (bool):
+            Whether to add level name to subtotal label.
         ignore_keys (str|list[str]|None):
-            Keys of rows to ignore when aggregating.
+            Keys of rows to ignore when aggregating. Default 'Totals'
+        skip_single_rows (bool):
+            Whether to skip single rows when aggregating. Default True.
         *args:
             Positional arguments to pass to func.
         **kwargs:
@@ -102,18 +109,19 @@ class PitaFrame(PitaDisplayMixin):
             label = label,
             include_level_name = include_level_name,
             ignore_keys = ignore_keys,
+            skip_single_rows = skip_single_rows,
             _fill = _fill,
         )
 
     #region percentages
     def as_percentages(
         self,
-        axis: int = 2,
+        axis: Axis = 2,
         label_totals: str|None = None,
         ignore_keys: str|list[str]|None = None,
         ndigits: int|None = None,
         base: int = 1,
-        apportioned_rounding: bool = True,
+        apportioned_rounding: bool|None = None,
     ) -> pd.DataFrame:
         """
         Transform data to percentages based on specified axis.
@@ -122,7 +130,7 @@ class PitaFrame(PitaDisplayMixin):
         ----------
         data (pd.DataFrame):
             The input DataFrame.
-        axis (int):
+        axis (int | Literal["index", "columns", "both"]):
             The axis along which percentages are calculated. Percentages are based on:
             - when axis is 2 then grand total
             - when axis is 1 then column totals
@@ -157,14 +165,14 @@ class PitaFrame(PitaDisplayMixin):
 
     def add_percentages(
         self,
-        axis: int = 2,
+        axis: Axis = 2,
         label_n: str|None = None,
         label_pct: str|None = None,
         label_totals: str|None = None,
         ignore_keys: str|list[str]|None = None,
         ndigits: int|None = None,
         base: int = 1,
-        apportioned_rounding: bool = True,
+        apportioned_rounding: bool|None = None,
         interleaf: bool = False,
     ) -> pd.DataFrame:
         """
@@ -174,7 +182,7 @@ class PitaFrame(PitaDisplayMixin):
         ----------
         data (pd.DataFrame):
             The input DataFrame.
-        axis (int):
+        axis (int | Literal["index", "columns", "both"]):
             The axis along which percentages are calculated. Percentages are based on:
             - when axis is 2 then grand total
             - when axis is 1 then row totals
@@ -219,7 +227,7 @@ class PitaFrame(PitaDisplayMixin):
     #region totals
     def add_totals(
         self,
-        axis: int = 2,
+        axis: Axis = 2,
         label: str|None = None,
         ignore_keys: str|list[str]|None = None,
         _fill: str = '',
@@ -229,7 +237,7 @@ class PitaFrame(PitaDisplayMixin):
 
         Parameters
         ----------
-        axis (int):
+        axis (int | Literal["index", "columns", "both"]):
             Axis to sum. If axis == 2 then add totals to both rows and columns. Default 2.
         label (str|None):
             Label for the totals row/column. Default 'Totals'.
@@ -241,7 +249,7 @@ class PitaFrame(PitaDisplayMixin):
         pd.DataFrame:
             Table with total rows/columns added.
         """
-        return tot.add_totals(
+        return totals.add_totals( # type: ignore
             self._obj,
             axis = axis,
             label = label,
@@ -251,11 +259,12 @@ class PitaFrame(PitaDisplayMixin):
 
     def add_subtotals(
         self,
-        axis: int = 2,
+        axis: Axis = 2,
         level: int|str|list[int|str] = 0,
         label: str|None = None,
         include_level_name: bool = False,
         ignore_keys: str|list[str]|None = None,
+        skip_single_rows: bool = True,
         _fill: str = '',
     ) -> pd.DataFrame:
         """
@@ -263,47 +272,119 @@ class PitaFrame(PitaDisplayMixin):
 
         Parameters
         ----------
-        axis (int):
+        axis (int | Literal["index", "columns", "both"]):
             Axis to sum. If axis == 2 then add totals to both rows and columns. Default 2.
         levels (int|str|list[int|str]):
             Levels to sum with func. Default 0.
         label (str|None):
             Label for the subtotals row/column. Default 'Subtotals'.
+        include_level_name (bool):
+            Whether to add level name to subtotal label.
         ignore_keys (str|list[str]|None):
             Keys of rows to ignore when aggregating. Default 'Totals'
+        skip_single_rows (bool):
+            Whether to skip single rows when aggregating. Default True.
 
         Returns
         -------
         pd.DataFrame:
             Table with total rows/columns added.
         """
-        return tot.add_subtotals(
+        return totals.add_subtotals( # type: ignore
             self._obj,
             axis = axis,
             level = level,
             label = label,
             include_level_name = include_level_name,
             ignore_keys = ignore_keys,
+            skip_single_rows = skip_single_rows,
             _fill = _fill,
         )
 
     def sort_totals(
         self,
-        axis: int = 0,
-        level: int = 0,
-        **kwargs
-    ):
-        return tool.sort_totals(
+        axis: Axis = 0,
+        level: Level|list[Level]|None = None,
+        labels: list[str]|None = None,
+        totals_last: bool = True,
+        sort_remaining: bool = True,
+    ) -> pd.DataFrame:
+        """
+        Sort index/columns to position totals and subtotals at start or end within groups.
+
+        Convenience function that sorts common aggregate labels (totals, subtotals) to
+        their appropriate positions, while leaving other items in their existing order.
+        Uses default labels from flatbread configuration unless custom labels are provided.
+
+        Parameters
+        ----------
+        axis : Axis, default 0
+            Axis to sort along:
+            - 0 or 'index': sort the index (rows)
+            - 1 or 'columns': sort the columns
+        level : Level | list[Level] | None, default None
+            Index level(s) to sort. Can be level number(s), level name(s), or None for all levels.
+        labels : list[str] | None, default None
+            Custom labels to treat as totals/subtotals. If None, uses default labels from
+            flatbread configuration ('Totals', 'Subtotals').
+        totals_last : bool, default True
+            Whether to place totals/subtotals at the end (True) or beginning (False) of each group.
+        sort_remaining : bool, default True
+            Whether to sort non-target levels alphabetically.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with totals/subtotals repositioned according to the specified parameters.
+        """
+        return axes.sort_totals( # type: ignore
             self._obj,
             axis = axis,
             level = level,
-            **kwargs,
+            labels = labels,
+            totals_last = totals_last,
+            sort_remaining = sort_remaining,
         )
 
     def drop_totals(
         self
     ):
-        return tot.drop_totals(self._obj)
+        return totals.drop_totals(self._obj)
+
+    # region io
+    def export_excel(
+        self,
+        filepath: str | Path,
+        title: str | None = None,
+        number_formats: dict | None = None,
+        border_specs: dict | None = None,
+        **kwargs
+    ) -> None:
+        """
+        Export DataFrame to Excel with automatic formatting based on flatbread configuration.
+
+        Parameters
+        ----------
+        filepath : str | Path
+            Path to save the Excel file
+        title : str, optional
+            Title for the worksheet
+        number_formats : dict, optional
+            Custom number formats (overrides auto-detected ones)
+        border_specs : dict, optional
+            Custom border specifications (merged with margin borders)
+        **kwargs
+            Additional arguments passed to pandasxl WorksheetManager
+        """
+        from flatbread.output.excel import export_excel
+        return export_excel(
+            self._obj,
+            filepath,
+            title=title,
+            number_formats=number_formats,
+            border_specs=border_specs,
+            **kwargs
+        )
 
     # region tooling
     def add_level(
@@ -334,7 +415,7 @@ class PitaFrame(PitaDisplayMixin):
         pd.DataFrame:
             DataFrame with the new level added to the specified axis.
         """
-        return tool.add_level(
+        return axes.add_level(
             self._obj,
             value = value,
             level = level,

{flatbread-0.1.5 → flatbread-0.2.0}/flatbread/accessors/series.py

@@ -1,12 +1,14 @@
-from typing import Any, Callable
+from typing import Any, Callable, Hashable, Literal, TypeAlias
+from pathlib import Path
 
 import pandas as pd
 
-import flatbread.percentages as pct
-import flatbread.agg.aggregation as agg
-import flatbread.agg.totals as tot
-import flatbread.tooling as tool
-from flatbread.render.display import PitaDisplayMixin
+import flatbread.transforms.percentages as pct
+import flatbread.transforms.aggregation as agg
+import flatbread.transforms.totals as totals
+import flatbread.axes as axes
+from flatbread.types import Axis, Level
+from flatbread.output.html import PitaDisplayMixin
 
 
 @pd.api.extensions.register_series_accessor("pita")
@@ -19,7 +21,7 @@ class PitaSeries(PitaDisplayMixin):
         self,
         aggfunc: str|Callable,
         *args,
-        label: str = None,
+        label: str|None = None,
         ignore_keys: str|list[str]|None = None,
         _fill: str = '',
         **kwargs,
@@ -58,10 +60,11 @@ class PitaSeries(PitaDisplayMixin):
     def add_subagg(
         self,
         aggfunc: str|Callable,
-        level: int|str|list[int|str] = 0,
-        label: str = None,
+        level: Level|list[Level] = 0,
+        label: str|None = None,
         include_level_name: bool = False,
         ignore_keys: str|list[str]|None = None,
+        skip_single_rows: bool = True,
         _fill: str = '',
     ) -> pd.Series:
         """
@@ -71,12 +74,16 @@ class PitaSeries(PitaDisplayMixin):
         ----------
         aggfunc (str|Callable):
             Function to use for aggregating the data.
-        levels (int|str|list[int|str]):
-            Levels to aggregate with func. Default 0.
+        level (int|str|list[int|str]):
+            Level(s) to aggregate with func. Default 0.
         label (str|None):
             Label for the aggregated rows. Default None.
+        include_level_name (bool):
+            Whether to add level name to subtotal label.
         ignore_keys (str|list[str]|None):
-            Keys of rows to ignore when aggregating.
+            Keys of rows to ignore when aggregating. Default 'Totals'
+        skip_single_rows (bool):
+            Whether to skip single rows when aggregating. Default True.
         *args:
             Positional arguments to pass to func.
         **kwargs:
@@ -94,6 +101,7 @@ class PitaSeries(PitaDisplayMixin):
             label = label,
             include_level_name = include_level_name,
             ignore_keys = ignore_keys,
+            skip_single_rows = skip_single_rows,
             _fill = _fill,
         )
 
@@ -131,7 +139,7 @@ class PitaSeries(PitaDisplayMixin):
             Series reporting the count of each value in the original series.
         """
         s = self._obj if fillna is None else self._obj.fillna(fillna)
-        result = s.value_counts().rename(label_n).pipe(tot.add_totals)
+        result = s.value_counts().rename(label_n).pipe(totals.add_totals)
         if add_pct:
             return result.pipe(
                 pct.add_percentages,
@@ -145,10 +153,11 @@ class PitaSeries(PitaDisplayMixin):
     #region percentages
     def as_percentages(
         self,
-        label_pct: str = None,
+        label_pct: str|None = None,
         label_totals: str|None = None,
-        ndigits: int = None,
+        ndigits: int|None = None,
         base: int = 1,
+        apportioned_rounding: bool|None = None,
     ) -> pd.Series:
         """
         Transform data into percentages.
@@ -177,6 +186,7 @@ class PitaSeries(PitaDisplayMixin):
             label_totals = label_totals,
             ndigits = ndigits,
             base = base,
+            apportioned_rounding = apportioned_rounding,
         )
 
     def as_pct(self, *args, **kwargs):
@@ -189,6 +199,7 @@ class PitaSeries(PitaDisplayMixin):
         label_totals: str|None = None,
         ndigits: int|None = None,
         base: int = 1,
+        apportioned_rounding: bool|None = None,
     ) -> pd.DataFrame:
         """
         Add percentage column to a Series.
@@ -220,6 +231,7 @@ class PitaSeries(PitaDisplayMixin):
             label_totals = label_totals,
             ndigits = ndigits,
             base = base,
+            apportioned_rounding = apportioned_rounding,
         )
 
     def add_pct(self, *args, **kwargs):
@@ -247,7 +259,7 @@ class PitaSeries(PitaDisplayMixin):
         pd.Series:
             Series with totals row added.
         """
-        return tot.add_totals(
+        return totals.add_totals( # type: ignore
             self._obj,
             label = label,
             ignore_keys = ignore_keys,
@@ -256,10 +268,11 @@ class PitaSeries(PitaDisplayMixin):
 
     def add_subtotals(
         self,
-        level: int|str|list[int|str] = 0,
+        level: Level|list[Level] = 0,
         label: str|None = None,
         include_level_name: bool = False,
         ignore_keys: str|list[str]|None = None,
+        skip_single_rows: bool = True,
         _fill: str = '',
     ) -> pd.Series:
         """
@@ -267,38 +280,110 @@ class PitaSeries(PitaDisplayMixin):
 
         Parameters
         ----------
-        levels (int|str|list[int|str]):
-            Levels to add subtotals to. Default 0.
+        level (int|str|list[int|str]):
+            Level(s) to add subtotals to. Default 0.
         label (str|None):
             Label for the subtotals rows. Default 'Subtotals'.
+        include_level_name (bool):
+            Whether to add level name to subtotal label.
         ignore_keys (str|list[str]|None):
             Keys of rows to ignore when aggregating. Default 'Totals'
+        skip_single_rows (bool):
+            Whether to skip single rows when aggregating. Default True.
 
         Returns
         -------
         pd.Series:
             Series with subtotal rows added.
         """
-        return tot.add_subtotals(
+        return totals.add_subtotals( # type: ignore
             self._obj,
             level = level,
             label = label,
             include_level_name = include_level_name,
             ignore_keys = ignore_keys,
+            skip_single_rows = skip_single_rows,
             _fill = _fill,
         )
 
     def sort_totals(
         self,
-        axis: int = 0,
-        level: int = 0,
-        **kwargs
-    ):
-        return tool.sort_totals(
+        axis: Axis = 0,
+        level: Level|list[Level]|None = None,
+        labels: list[str]|None = None,
+        totals_last: bool = True,
+        sort_remaining: bool = True,
+    ) -> pd.Series:
+        """
+        Sort index/columns to position totals and subtotals at start or end within groups.
+
+        Convenience function that sorts common aggregate labels (totals, subtotals) to
+        their appropriate positions, while leaving other items in their existing order.
+        Uses default labels from flatbread configuration unless custom labels are provided.
+
+        Parameters
+        ----------
+        axis : Axis, default 0
+            Axis to sort along:
+            - 0 or 'index': sort the index (rows)
+            - 1 or 'columns': sort the columns
+        level : Level | list[Level] | None, default None
+            Index level(s) to sort. Can be level number(s), level name(s), or None for all levels.
+        labels : list[str] | None, default None
+            Custom labels to treat as totals/subtotals. If None, uses default labels from
+            flatbread configuration ('Totals', 'Subtotals').
+        totals_last : bool, default True
+            Whether to place totals/subtotals at the end (True) or beginning (False) of each group.
+        sort_remaining : bool, default True
+            Whether to sort non-target levels alphabetically.
+
+        Returns
+        -------
+        pd.Series
+            Series with totals/subtotals repositioned according to the specified parameters.
+        """
+        return axes.sort_totals( # type: ignore
             self._obj,
             axis = axis,
             level = level,
-            **kwargs,
+            labels = labels,
+            totals_last = totals_last,
+            sort_remaining = sort_remaining,
+        )
+
+    # region io
+    def export_excel(
+        self,
+        filepath: str | Path,
+        title: str | None = None,
+        number_formats: dict | None = None,
+        border_specs: dict | None = None,
+        **kwargs
+    ) -> None:
+        """
+        Export Series to Excel with automatic formatting based on flatbread configuration.
+
+        Parameters
+        ----------
+        filepath : str | Path
+            Path to save the Excel file
+        title : str, optional
+            Title for the worksheet
+        number_formats : dict, optional
+            Custom number formats (overrides auto-detected ones)
+        border_specs : dict, optional
+            Custom border specifications (merged with margin borders)
+        **kwargs
+            Additional arguments passed to pandasxl WorksheetManager
+        """
+        from flatbread.output.excel import export_excel
+        return export_excel(
+            self._obj,
+            filepath,
+            title=title,
+            number_formats=number_formats,
+            border_specs=border_specs,
+            **kwargs
         )
 
     # region tooling
@@ -307,7 +392,7 @@ class PitaSeries(PitaDisplayMixin):
         value: Any,
         level: int = 0,
         level_name: Any = None,
-        axis: int = 0,
+        axis: Axis = 0,
     ):
         """
         Add a level containing the specified value to a Series index.
@@ -322,7 +407,7 @@ class PitaSeries(PitaDisplayMixin):
             Position to insert the new level. Defaults to 0 (start).
         level_name (Any, optional):
             Name for the new level. Defaults to None.
-        axis (Axis):
+        axis (int | Literal["index", "columns", "both"]):
             Added for symmetry with DataFrame method.
 
         Returns
@@ -330,7 +415,7 @@ class PitaSeries(PitaDisplayMixin):
         pd.Series:
             Series with the new level added to the specified axis.
         """
-        return tool.add_level(
+        return axes.add_level(
             self._obj,
             value = value,
             level = level,