mergeron 2024.738949.1__py3-none-any.whl → 2024.738949.6__py3-none-any.whl

mergeron/__init__.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+import enum
 from importlib.metadata import version
 from pathlib import Path
 
@@ -14,3 +17,29 @@ If the subdirectory doesn't exist, it is created on package invocation.
 
 if not DATA_DIR.is_dir():
     DATA_DIR.mkdir(parents=False)
+
+
+@enum.unique
+class RECConstants(enum.StrEnum):
+    """Recapture rate - derivation methods."""
+
+    INOUT = "inside-out"
+    OUTIN = "outside-in"
+    FIXED = "proportional"
+
+
+@enum.unique
+class UPPAggrSelector(enum.Enum):
+    """
+    Aggregator selection for GUPPI and diversion ratio
+
+    """
+
+    AVG = "average"
+    CPA = "cross-product-share weighted average"
+    CPD = "cross-product-share weighted distance"
+    DIS = "symmetrically-weighted distance"
+    MAX = "max"
+    MIN = "min"
+    OSA = "own-share weighted average"
+    OSD = "own-share weighted distance"

mergeron/core/__init__.py

@@ -1,5 +1,69 @@
+from __future__ import annotations
+
 from importlib.metadata import version
+from multiprocessing import Value
+
+from attrs import Attribute, define, field, validators
 
-from .. import _PKG_NAME  # noqa: TID252
+from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
 
 __version__ = version(_PKG_NAME)
+
+
+def _delta_value_validator(
+    _instance: UPPBoundarySpec, _attribute: Attribute[float], _value: float, /
+) -> None:
+    if not 0 <= _value <= 1:
+        raise ValueError(
+            "Margin-adjusted benchmark share ratio must lie between 0 and 1."
+        )
+
+
+def _rec_spec_validator(
+    _instance: UPPBoundarySpec,
+    _attribute: Attribute[RECConstants],
+    _value: RECConstants,
+    /,
+) -> None:
+    if _value == RECConstants.OUTIN:
+        raise ValueError(
+            f"Invalid recapture specification, {_value!r}. "
+            "You may consider specifying RECConstants.INOUT here, and "
+            "assigning the recapture rate for the merging-firm with "
+            'the smaller market-share to the attribue, "rec" of '
+            "the UPPBoundarySpec object you pass."
+        )
+    if _value is None and _instance.agg_method != UPPAggrSelector.MAX:
+        raise ValueError(
+            f"Specified aggregation method, {_instance.agg_method} requires a recapture specification."
+        )
+
+
+@define(slots=True, frozen=True)
+class UPPBoundarySpec:
+    share_ratio: float = field(
+        kw_only=False,
+        default=0.075,
+        validator=(validators.instance_of(float), _delta_value_validator),
+    )
+    rec: float = field(
+        kw_only=False, default=0.80, validator=validators.instance_of(float)
+    )
+
+    agg_method: UPPAggrSelector = field(
+        kw_only=True,
+        default=UPPAggrSelector.MAX,
+        validator=validators.instance_of(UPPAggrSelector),
+    )
+    recapture_spec: RECConstants | None = field(
+        kw_only=True,
+        default=RECConstants.INOUT,
+        validator=(
+            validators.optional(validators.instance_of(RECConstants)),  # type: ignore
+            _rec_spec_validator,
+        ),
+    )
+
+    precision: int = field(
+        kw_only=False, default=5, validator=validators.instance_of(int)
+    )

mergeron/core/excel_helper.py

@@ -24,18 +24,11 @@ __version__ = version(_PKG_NAME)
 
 
 @enum.unique
-class CFmtParent(dict[str, Any], enum.ReprEnum):
-    def merge(self, _other) -> CFmtParent:
-        if isinstance(_other, CFmtParent):
-            return self.value | _other.value
-        else:
-            raise RuntimeWarning(
-                f"Object {_other!r} not valid for merge(), returned original."
-            )
-            return self.value
+class CFmtParent(dict[str, Any], enum.ReprEnum):  # type: ignore
+    """Unique mappings defining xlsxwirter Workbook formats"""
 
 
-class CFmt(CFmtParent):  # type: ignore
+class CFmt(CFmtParent):
     """
     Initialize cell formats for xlsxwriter.
 
@@ -140,7 +133,7 @@ def matrix_to_sheet(
     elif isinstance(cell_format, CFmt):
         _cell_format = (cell_format,) * len(_data_array[0])
     else:
-        _cell_format = (CFmt.XL_DEFAULT,) * len(_data_array[0])  # type: ignore
+        _cell_format = (CFmt.XL_DEFAULT,) * len(_data_array[0])
 
     for _cell_row in range(_row_id, _bottom_row_id):
         for _cell_col in range(_col_id, _right_column_id):
@@ -236,7 +229,7 @@ def xl_fmt(
     elif isinstance(_cell_fmt, CFmt):
         _cell_fmt_dict = _cell_fmt.value
     else:
-        _cell_fmt_dict = CFmt.XL_DEFAULT.value  # type: ignore
+        _cell_fmt_dict = CFmt.XL_DEFAULT.value
 
     return _xl_book.add_format(_cell_fmt_dict)