mergeron 2024.739087.0__tar.gz → 2024.739088.0__tar.gz

{mergeron-2024.739087.0 → mergeron-2024.739088.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mergeron
-Version: 2024.739087.0
+Version: 2024.739088.0
 Summary: Merger Policy Analysis using Python
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI

{mergeron-2024.739087.0 → mergeron-2024.739088.0}/pyproject.toml

@@ -13,7 +13,7 @@ keywords = [
     "upward pricing pressure",
     "GUPPI",
 ]
-version = "2024.739087.0"
+version = "2024.739088.0"
 
 # Classifiers list: https://pypi.org/classifiers/
 classifiers = [

{mergeron-2024.739087.0 → mergeron-2024.739088.0}/src/mergeron/__init__.py

@@ -11,7 +11,7 @@ from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739087.0"
+VERSION = "2024.739088.0"
 
 __version__ = VERSION
 

{mergeron-2024.739087.0/src/mergeron/core → mergeron-2024.739088.0/src/mergeron/ext}/xlsxw_helper.py

@@ -21,12 +21,14 @@ from typing import Any, ClassVar
 import numpy as np
 import numpy.typing as npt
 import xlsxwriter  # type: ignore
-from aenum import Enum, unique  # type: ignore
+from aenum import Enum, extend_enum, unique  # type: ignore
 
 from .. import VERSION  # noqa: TID252
 
 __version__ = VERSION
 
+Workbook = xlsxwriter.Workbook
+
 
 @unique
 class CFmt(dict, Enum):  # type: ignore
@@ -34,7 +36,7 @@ class CFmt(dict, Enum):  # type: ignore
     Initialize cell formats for xlsxwriter.
 
     The mappings included here, and unions, etc. of them
-    and any others added at runtime, will be rendered
+    and any others added at runtime, are rendered
     as xlsxWriter.Workbook.Format objects for writing
     cell values to formatted cells in a spreadsheet.
 
@@ -43,6 +45,7 @@ class CFmt(dict, Enum):  # type: ignore
 
     For more information about xlsxwriter's cell formats,
     see, https://xlsxwriter.readthedocs.io/format.html
+
     """
 
     XL_DEFAULT: ClassVar = {"font_name": "Calibri", "font_size": 11}
@@ -52,28 +55,35 @@ class CFmt(dict, Enum):  # type: ignore
     A_CTR_ACROSS: ClassVar = {"align": "center_across"}
     A_LEFT: ClassVar = {"align": "left"}
     A_RIGHT: ClassVar = {"align": "right"}
+    V_TOP: ClassVar = {"align": "top"}
+    V_BOTTOM: ClassVar = {"align": "bottom"}
+    V_CTR: ClassVar = {"align": "vcenter"}
+
+    TEXT_WRAP: ClassVar = {"text_wrap": True}
+    TEXT_ROTATE: ClassVar = {"rotation": 90}
+    IND_1: ClassVar = {"indent": 1}
 
     BOLD: ClassVar = {"bold": True}
     BOLD_ITALIC: ClassVar = {"bold": True, "italic": True}
     ITALIC: ClassVar = {"italic": True}
     ULINE: ClassVar = {"underline": True}
+    SOUT: ClassVar = {"font_strikeout": True}
+    # Useful with write_rich_text()
+    SUPERSCRIPT: ClassVar = {"font_script": 1}
+    SUBSCRIPT: ClassVar = {"font_script": 2}
 
-    TEXT_WRAP: ClassVar = {"text_wrap": True}
-    TEXT_ROTATE: ClassVar = {"rotation": 90}
-    IND_1: ClassVar = {"indent": 1}
-
+    AREA_NUM: ClassVar = ({"num_format": "0.00000000"},)
     DOLLAR_NUM: ClassVar = {"num_format": "[$$-409]#,##0.00"}
     DT_NUM: ClassVar = {"num_format": "mm/dd/yyyy"}
-    QTY_NUM: ClassVar = {"num_format": "#,##0.0"}
     PCT_NUM: ClassVar = {"num_format": "##0%"}
     PCT2_NUM: ClassVar = {"num_format": "##0.00%"}
     PCT4_NUM: ClassVar = {"num_format": "##0.0000%"}
     PCT6_NUM: ClassVar = {"num_format": "##0.000000%"}
     PCT8_NUM: ClassVar = {"num_format": "##0.00000000%"}
-    AREA_NUM: ClassVar = {"num_format": "0.00000000"}
+    QTY_NUM: ClassVar = {"num_format": "#,##0.0"}
 
     BAR_FILL: ClassVar = {"pattern": 1, "bg_color": "dfeadf"}
-    HDR_FILL: ClassVar = {"pattern": 1, "bg_color": "999999"}
+    HDR_FILL: ClassVar = {"pattern": 1, "bg_color": "e9e9e9"}
 
     LEFT_BORDER: ClassVar = {"left": 1, "left_color": "000000"}
     RIGHT_BORDER: ClassVar = {"right": 1, "right_color": "000000"}
@@ -81,6 +91,115 @@ class CFmt(dict, Enum):  # type: ignore
     TOP_BORDER: ClassVar = {"top": 1, "top_color": "000000"}
     HDR_BORDER: ClassVar = TOP_BORDER | BOT_BORDER
 
+    @classmethod
+    def add_new(self, _fmt_name: str, _xlsx_fmt_dict: dict[str, Any], /) -> CFmt:
+        """
+        Add new CFmt object to instance.
+
+        Parameters
+        ----------
+        _fmt_name
+            Name of new member to be added to CFmt
+        _xlsx_fmt_dict
+            Any valid argument to xlsxwriter.Workbook.add_format(), or union of
+            same with one or more CFmt objects with same, e.g.,
+            CFmt.HDR_BORDER | CFmt.HDR_FILL  or
+            CFmt.HDR_BORDER | {"pattern": 1, "bg_color": "f2f2f2"}
+
+        Returns
+        -------
+            None
+
+        """
+
+        return extend_enum(self, _fmt_name, _xlsx_fmt_dict)  # type: ignore
+
+    @classmethod
+    def ensure_cell_format_spec_tuple(
+        self, _cell_formats: Sequence[CFmt | Sequence[CFmt]], /
+    ) -> bool:
+        """
+        Test that a given format specification is a tuple of CFmt enums
+
+        Parameters
+        ----------
+        _cell_formats
+            Format specification
+
+        Raises
+        ------
+        ValueError
+            If format specification is not tuple of CFmt enums
+
+        Returns
+        -------
+            True if format specification passes, else False
+
+        """
+
+        for _cell_format in _cell_formats:
+            if isinstance(_cell_format, tuple):
+                self.ensure_cell_format_spec_tuple(_cell_format)
+
+            if not (isinstance(_cell_format, CFmt),):
+                raise ValueError(
+                    "Improperly specified format tuple for writing array."
+                    "  Must be tuple of CFmt enums."
+                )
+
+        return True
+
+    @classmethod
+    def xl_fmt(
+        self,
+        _xl_book: xlsxwriter.Workbook,
+        _cell_fmt: Sequence[CFmt | Sequence[CFmt]] | CFmt | None,
+        /,
+    ) -> xlsxwriter.format.Format:
+        """
+        Return :code:`xlsxwriter` `Format` object given a CFmt aenum, or tuple thereof.
+
+        Parameters
+        ----------
+        _xl_book
+            :code:`xlsxwriter.Workbook` object
+
+        _cell_fmt
+            :code:`CFmt` aenum object, or tuple thereof
+
+        Raises
+        ------
+        ValueError
+            If format specification is not one of None, a CFmt aenum, or
+            a xlsxwriter.format.Format object
+
+        Returns
+        -------
+            :code:`xlsxwriter` `Format`  object
+
+        """
+
+        if isinstance(_cell_fmt, xlsxwriter.format.Format):
+            return _cell_fmt
+        elif _cell_fmt is None:
+            return _xl_book.add_format(CFmt.XL_DEFAULT.value)
+
+        _cell_fmt_dict: Mapping[str, Any] = {}
+        if isinstance(_cell_fmt, Sequence):
+            self.ensure_cell_format_spec_tuple(_cell_fmt)
+            for _cf in _cell_fmt:
+                _cell_fmt_dict = (
+                    (_cell_fmt_dict | _cfi.value for _cfi in _cf)
+                    if isinstance(_cf, Sequence)
+                    else _cell_fmt_dict | _cf.value
+                )
+        elif isinstance(_cell_fmt, CFmt):
+            _cell_fmt_dict = _cell_fmt.value
+        else:
+            raise ValueError("Improperly specified format specification.")
+
+        return _xl_book.add_format(_cell_fmt_dict)
+
 
 def write_header(
     _xl_sheet: xlsxwriter.worksheet.Worksheet,
@@ -235,6 +354,17 @@ def array_to_sheet(
     -------
         Tuple giving address of cell at right below and after range written
 
+
+    Notes
+    -----
+
+    The keyword argument cell_format may be passed a tuple of CFmt enums,
+    if, and only if, ragged_flag is False. If cell_format is a tuple, it must
+    have length equal to the number of cells in the range to be written. Further,
+    members of cell_format must each be a CFmt enum or a tuple of CFmt enums; in
+    other words, `CFmt.ensure_cell_format_spec_tuple(_c)` must return True for
+    any tuple `_c` passed as `cell_format`.
+
     """
 
     if not ragged_flag:
@@ -268,7 +398,7 @@ def array_to_sheet(
             )
         elif not len(cell_format) == len(_data_table[0]):
             raise ValueError("Format tuple does not match data in length.")
-        ensure_cell_format_spec_tuple(cell_format)
+        CFmt.ensure_cell_format_spec_tuple(cell_format)
         _cell_format: Sequence[CFmt | Sequence[CFmt]] = cell_format
     elif isinstance(cell_format, CFmt):
         _cell_format = (cell_format,) * len(_data_table[0])
@@ -276,21 +406,27 @@ def array_to_sheet(
         _cell_format = (CFmt.XL_DEFAULT,) * len(_data_table[0])
 
     # construct vector of xlslwrter.format.Format objects
-    _wbk_formats = tuple(xl_fmt(_xl_book, _cf) for _cf in _cell_format)
+    _wbk_formats = tuple(CFmt.xl_fmt(_xl_book, _cf) for _cf in _cell_format)
     if _num_rows > 1:
         _wbk_formats_greened = (
-            tuple(xl_fmt(_xl_book, (_cf, CFmt.BAR_FILL)) for _cf in _cell_format)
+            tuple(
+                CFmt.xl_fmt(
+                    _xl_book,
+                    (*_cf, CFmt.BAR_FILL)
+                    if isinstance(_cf, Sequence)
+                    else (_cf, CFmt.BAR_FILL),
+                )
+                for _cf in _cell_format
+            )
             if green_bar_flag
             else _wbk_formats
         )
 
     for _ri, _rv in enumerate(_data_table):
-        _fmt_tuple = _wbk_formats_greened if _ri % 2 else _wbk_formats
+        _wbk_fmt_tuple = _wbk_formats_greened if _ri % 2 else _wbk_formats
         for _ci, _cv in enumerate(_rv):
-            _cell_fmt = _fmt_tuple[_ci]
-            scalar_to_sheet(
-                _xl_book, _xl_sheet, _row_id + _ri, _col_id + _ci, _cv, _cell_fmt
-            )
+            _cf = _wbk_fmt_tuple[_ci]
+            scalar_to_sheet(_xl_sheet, _row_id + _ri, _col_id + _ci, _cv, _cf)
 
         _right_column_id = _col_id + _ci + 1 if _ci > _num_cols else _right_column_id
 
@@ -298,11 +434,11 @@ def array_to_sheet(
 
 
 def scalar_to_sheet(
-    _xl_book: xlsxwriter.workbook.Workbook,
     _xl_sheet: xlsxwriter.worksheet.Worksheet,
-    _cell_addr_0: str | int | float = "A1",
+    _cell_addr_0: str | int = "A1",
     /,
     *_s2s_args: Any,
+    empty_as_blank: bool = True,
 ) -> None:
     """
     Write to a single cell in a worksheet.
@@ -337,104 +473,41 @@ def scalar_to_sheet(
 
     """
 
+    _cell_addr: tuple[int | str, ...] = ()
+    _cell_val: Any = None
+    _cell_fmt: xlsxwriter.format.Format = CFmt.XL_DEFAULT
+
     if isinstance(_cell_addr_0, str):
         if len(_s2s_args) not in (1, 2):
-            raise ValueError("Too many or too few arguments.")
-        _cell_addr: tuple[int | str, ...] = (_cell_addr_0,)
-        _cell_val: Any = _s2s_args[0]
-        _cell_fmt: CFmt | Sequence[CFmt] = _s2s_args[1] if len(_s2s_args) == 2 else None  # type: ignore
+            raise ValueError("Incorrect number of arguments.")
+        _cell_addr = (_cell_addr_0,)
+        _cell_val = _s2s_args[0]
+        _cell_fmt = _s2s_args[1] if len(_s2s_args) == 2 else None  # type: ignore
     elif isinstance(_cell_addr_0, int):
-        if len(_s2s_args) not in (2, 3):
-            raise ValueError("Too many or too few arguments.")
+        if len(_s2s_args) not in (2, 3) or not isinstance(_s2s_args[0], int):
+            raise ValueError("Incorrect/incomplete specification for Excel cell data.")
         _cell_addr = (_cell_addr_0, _s2s_args[0])
         _cell_val = _s2s_args[1]
         _cell_fmt = _s2s_args[2] if len(_s2s_args) == 3 else None  # type: ignore
     else:
         raise ValueError("Incorrect/incomplete specification for Excel cell data.")
 
-    _xl_fmt = xl_fmt(_xl_book, _cell_fmt)
-    if isinstance(_cell_val, str):
-        _xl_sheet.write_string(*_cell_addr, _cell_val, _xl_fmt)
-    else:
-        _xl_sheet.write(
-            *_cell_addr, repr(_cell_val) if np.ndim(_cell_val) else _cell_val, _xl_fmt
-        )
-
-
-def xl_fmt(
-    _xl_book: xlsxwriter.Workbook,
-    _cell_fmt: Sequence[CFmt | Sequence[CFmt]] | CFmt | None,
-    /,
-) -> xlsxwriter.format.Format:
-    """
-    Return :code:`xlsxwriter` `Format` object given a CFmt aenum, or tuple thereof.
-
-    Parameters
-    ----------
-    _xl_book
-        :code:`xlsxwriter.Workbook` object
-
-    _cell_fmt
-        :code:`CFmt` aenum object, or tuple thereof
-
-    Raises
-    ------
-    ValueError
-        If format specification is not one of None, a CFmt aenum, or
-        a xlsxwriter.format.Format object
-
-    Returns
-    -------
-        :code:`xlsxwriter` `Format`  object
-
-    """
-
-    if isinstance(_cell_fmt, xlsxwriter.format.Format):
-        return _cell_fmt
-    elif _cell_fmt is None:
-        return _xl_book.add_format(CFmt.XL_DEFAULT.value)
-
-    _cell_fmt_dict: Mapping[str, Any] = {}
-    if isinstance(_cell_fmt, Sequence):
-        ensure_cell_format_spec_tuple(_cell_fmt)
-        for _cf in _cell_fmt:
-            _cell_fmt_dict = _cell_fmt_dict | _cf.value
-    elif isinstance(_cell_fmt, CFmt):
-        _cell_fmt_dict = _cell_fmt.value
+    _write_args = (
+        (*_cell_addr, repr(_cell_val))
+        if np.ndim(_cell_val) or _cell_val in (np.inf, -np.inf, np.nan)
+        else (*_cell_addr, _cell_val)
+    )
+    _write_args = (*_write_args, _cell_fmt) if _cell_fmt else _write_args
+
+    if empty_as_blank and (_cell_val is None or _cell_val == ""):
+        _xl_sheet.write_blank(*_write_args)
+    elif (
+        _cell_val is None
+        or _cell_val == ""
+        or isinstance(_cell_val, str)
+        or np.ndim(_cell_val)
+        or _cell_val in (np.inf, -np.inf, np.nan)
+    ):
+        _xl_sheet.write_string(*_write_args)
     else:
-        raise ValueError("Improperly specified format specification.")
-
-    return _xl_book.add_format(_cell_fmt_dict)
-
-
-def ensure_cell_format_spec_tuple(
-    _cell_formats: Sequence[CFmt | Sequence[CFmt]], /
-) -> None:
-    """
-    Test that a given format specification is tuple of CFmt enums
-
-    Parameters
-    ----------
-    _cell_formats
-        Format specification
-
-    Raises
-    ------
-    ValueError
-        If format specification is not tuple of CFmt enums
-
-    Returns
-    -------
-        True if format specification passes, else False
-
-    """
-
-    for _cell_format in _cell_formats:
-        if isinstance(_cell_format, tuple):
-            ensure_cell_format_spec_tuple(_cell_format)
-
-        if not (isinstance(_cell_format, CFmt),):
-            raise ValueError(
-                "Improperly specified format tuple for writing array."
-                "  Must be tuple of CFmt enums."
-            )
+        _xl_sheet.write(*_write_args)