datedict 1.0.4__py3-none-any.whl

datedict/DateDict.py

@@ -0,0 +1,46 @@
+from datetime import date, timedelta
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .TimeDict import TimeDict
+
+from .common import ZERO
+
+if TYPE_CHECKING:
+    from .YearDict import YearDict
+
+DateKey = str | date
+
+
+class DateDict(TimeDict[DateKey]):
+    @classmethod
+    def _next_key(cls, key: DateKey) -> DateKey:
+        if isinstance(key, str):
+            key_date = date.fromisoformat(key)
+        else:
+            key_date = key
+        next_date = key_date + timedelta(days=1)
+        return next_date.strftime("%Y-%m-%d")
+
+    @classmethod
+    def _inclusive_range(cls, start: DateKey, end: DateKey) -> list[DateKey]:
+        start_date: str = (
+            str(start) if isinstance(start, str) else start.strftime("%Y-%m-%d")
+        )
+        end_date: str = str(end) if isinstance(end, str) else end.strftime("%Y-%m-%d")
+        return super()._inclusive_range(start_date, end_date)
+
+    def to_yeardict(self) -> "YearDict":
+        """
+        Convert the DateDict to a YearDict by summing values for each year.
+        """
+        from .YearDict import YearDict
+
+        year_data: dict[int, Decimal] = {}
+        for k, v in self.data.items():
+            year = int(k[:4]) if isinstance(k, str) else k.year
+            year_data[year] = year_data.get(year, ZERO) + v
+        return YearDict(year_data)
+
+    def to_dict(self) -> dict[str, Decimal]:
+        return {str(k): v for k, v in self.data.items()}

datedict/TimeDict.py

@@ -0,0 +1,236 @@
+from decimal import Decimal
+from typing import Callable, Generic, Mapping, Protocol, Self, TypeVar
+from .common import NAN, ONE, ZERO, Decimable, to_decimal
+
+
+K = TypeVar("K", bound="SupportsLe")
+
+
+class SupportsLe(Protocol):
+    def __le__(self: K, other: K, /) -> bool: ...
+    def __lt__(self: K, other: K, /) -> bool: ...
+
+
+class TimeDict(Generic[K]):
+
+    @classmethod
+    def _next_key(cls, key: K) -> K:
+        _ = key
+        raise NotImplementedError("_next_key must be implemented in subclasses")
+
+    @classmethod
+    def _inclusive_range(cls, start: K, end: K) -> list[K]:
+        keys = []
+        current = start
+        while current <= end:
+            keys.append(current)
+            current = cls._next_key(current)
+        return keys
+
+    def __init__(
+        self,
+        data: Mapping[K, Decimable] = dict(),
+        strict: bool = True,
+        cumulative: bool = False,
+    ) -> None:
+        keys = sorted(data.keys())
+        if not keys:
+            raise ValueError("Data cannot be empty.")
+        if strict:
+            # enforce contiguous coverage
+            if keys != self._inclusive_range(keys[0], keys[-1]):
+                raise ValueError(
+                    "Data must cover all keys in the contiguous range. "
+                    "To disable this check, set strict=False."
+                )
+        self.start, self.end = keys[0], keys[-1]
+        self.data = {k: to_decimal(v) for k, v in data.items()}
+        self.cumulative = cumulative
+
+    @classmethod
+    def fill(cls, start: K, end: K, value: Decimable) -> "Self":
+        """
+        Create a new graph with a specified range and value.
+        The range is defined by start and end.
+        """
+        v = to_decimal(value)
+        return cls({k: v for k in cls._inclusive_range(start, end)})
+
+    def get(self, key: K, default: Decimal = NAN) -> Decimal:
+        """
+        Get the value for a specific key.
+        If the key does not exist, return the default value.
+        If the value is None, return the default value.
+        """
+        temp = self.data.get(key, NAN)
+        if temp.is_nan():
+            return default
+        return temp
+
+    def __getitem__(self, key: K) -> Decimal:
+        return self.data[key]
+
+    def __setitem__(self, key: K, value) -> None:
+        self.data[key] = to_decimal(value)
+
+    def crop(
+        self,
+        start: K | None = None,
+        end: K | None = None,
+        initial_value: Decimable = NAN,
+    ) -> "Self":
+        if start is None and end is None:
+            return self
+        return type(self)(
+            {
+                k: (self.get(k, to_decimal(initial_value)))
+                for k in self._inclusive_range(
+                    start if start is not None else self.start,
+                    end if end is not None else self.end,
+                )
+            }
+        )
+
+    def non_negative(self) -> "Self":
+        """
+        Return a new TimeDict with all negative values set to zero.
+        """
+        return type(self)(
+            {
+                k: (v if (not v.is_nan() and v >= ZERO) else ZERO)
+                for k, v in self.data.items()
+            }
+        )
+
+    def sum(self, start: K | None = None, end: K | None = None) -> Decimal:
+        total = ZERO
+        for k in self._inclusive_range(
+            start if start is not None else self.start,
+            end if end is not None else self.end,
+        ):
+            v = self.data.get(k, NAN)
+            if not v.is_nan():
+                total += v
+        return total
+
+    def _binary_op(
+        self,
+        other: "Decimable | Self",
+        op: Callable[[Decimal, Decimal], Decimal],
+        neutral: Decimal,
+    ) -> "Self":
+        if isinstance(other, Decimable):
+            other_value = to_decimal(other)
+            return type(self)({k: op(v, other_value) for k, v in self.data.items()})
+        elif isinstance(other, type(self)):
+            return type(self)(
+                {
+                    k: op(
+                        self[k],
+                        other.get(k, neutral),
+                    )
+                    for k in self.data.keys()
+                }
+            )
+        else:
+            raise TypeError(
+                "Unsupported operand type(s) for operation: "
+                f"'TimeDict' and '{type(other)}'"
+            )
+
+    def __mul__(self, other: "Decimable | Self") -> "Self":
+        return self._binary_op(other, lambda x, y: x * y, ONE)
+
+    def __rmul__(self, other):
+        return self.__mul__(other)
+
+    def __neg__(self) -> "Self":
+        return self * Decimal("-1")
+
+    def __add__(self, other: "Decimable | Self") -> "Self":
+        return self._binary_op(other, lambda x, y: x + y, ZERO)
+
+    def __radd__(self, other: "Decimable | Self") -> "Self":
+        return self.__add__(other)
+
+    def __sub__(self, other: "Decimable | Self") -> "Self":
+        return self._binary_op(other, lambda x, y: x - y, ZERO)
+
+    def __rsub__(self, other: "Decimable | Self") -> "Self":
+        return (-self).__add__(other)
+
+    def __truediv__(self, other: "Decimable | Self") -> "Self":
+        return self._binary_op(other, lambda x, y: x / y, ONE)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, type(self)):
+            return False
+        for k in set(self.data.keys()).union(other.data.keys()):
+            s = self.get(k)
+            o = other.get(k)
+            if s.is_nan() and o.is_nan():
+                continue
+            if s != o:
+                return False
+        return True
+
+    def __str__(self) -> str:
+        return "\n".join(f"{k}: {v}" for k, v in sorted(self.data.items()))
+
+    def __repr__(self) -> str:
+        return f"{self.data!r}"
+
+    def to_array(self) -> list[Decimal]:
+        return [self.data[k] for k in self.data.keys()]
+
+    def to_dict(self) -> dict:
+        return self.data.copy()
+
+    def average(self) -> Decimal:
+        """
+        Return the average of the values in the TimeDict.
+        If there are no valid (non-NaN) values, return ZERO.
+        """
+        valid_values = [v for v in self.data.values() if not v.is_nan()]
+        if not valid_values:
+            return ZERO
+        return sum(valid_values) / Decimal(len(valid_values))
+
+    def to_cumulative(self) -> "Self":
+        """
+        Convert the TimeDict to a cumulative TimeDict.
+        Each value is the sum of all previous values up to that key.
+        NaN values are ignored and left as NaN in the cumulative result.
+        """
+        if self.cumulative:
+            raise ValueError("TimeDict is already cumulative.")
+        running_total = ZERO
+        cumulative_data = {}
+        for k in sorted(self.data.keys()):
+            current_value = self.data[k]
+            if current_value.is_nan():
+                cumulative_data[k] = NAN
+            else:
+                running_total += current_value
+                cumulative_data[k] = running_total
+        return type(self)(cumulative_data, cumulative=True)
+
+    def to_incremental(self) -> "Self":
+        """
+        Convert the TimeDict to an incremental TimeDict.
+        Each value is the difference between the current cumulative value
+        and the previous cumulative value.
+        NaN values are ignored and left as NaN in the incremental result.
+        """
+        if not self.cumulative:
+            raise ValueError("TimeDict is not cumulative.")
+        previous_value = ZERO
+        incremental_data = {}
+        for k in sorted(self.data.keys()):
+            current_value = self.data[k]
+            if current_value.is_nan():
+                incremental_data[k] = NAN
+            else:
+                incremental_data[k] = current_value - previous_value
+                previous_value = current_value
+        return type(self)(incremental_data, cumulative=False)

datedict/YearDict.py

@@ -0,0 +1,24 @@
+from typing import TYPE_CHECKING
+from .TimeDict import TimeDict
+from .common import NAN
+
+if TYPE_CHECKING:
+    from .DateDict import DateDict
+
+
+class YearDict(TimeDict[int]):
+    @classmethod
+    def _next_key(cls, key: int) -> int:
+        return key + 1
+
+    def to_datedict(self) -> "DateDict":
+        from .DateDict import DateDict
+
+        """
+        Convert the YearDict to a DateDict.
+        Each year in the YearDict is expanded to cover all dates in that year.
+        """
+        dd: DateDict = DateDict.fill(f"{self.start}-01-01", f"{self.end}-12-31", NAN)
+        for k in dd.data.keys():
+            dd.data[k] = self.get(int(k[:4]) if isinstance(k, str) else k.year, NAN)
+        return dd

datedict/__init__.py

@@ -0,0 +1,6 @@
+from .DateDict import DateDict
+from .YearDict import YearDict
+from .common import ZERO, ONE, NAN, Decimable
+
+__all__ = ["DateDict", "YearDict", "ZERO", "ONE", "NAN", "Decimable"]
+__version__ = "1.0.4"

datedict/common.py

@@ -0,0 +1,19 @@
+from decimal import Decimal
+from typing import Union
+
+Decimable = Union[Decimal, str, int, float, None]
+
+ZERO = Decimal("0")
+ONE = Decimal("1")
+NAN = Decimal("NaN")
+
+
+def to_decimal(x: Decimable) -> Decimal:
+    if x is None:
+        return Decimal("NaN")
+    if isinstance(x, Decimal):
+        return x
+    if isinstance(x, (int, str)):
+        return Decimal(x)
+    if isinstance(x, float):
+        return Decimal(str(x))

datedict-1.0.4.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: datedict
+Version: 1.0.4
+Summary: DateDict and YearDict: date-aware dictionary structures
+Project-URL: Homepage, https://gitlab.com/grisus/datedict
+Project-URL: Issues, https://gitlab.com/grisus/datedict/-/issues
+Author-email: Lorenzo Guideri <lorenzo.guideri@dec-energy.ch>
+License: MIT License
+        
+        Copyright (c) 2025 DEC Energy SA
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# datedict
+
+`datedict` bundles two data structures: `DateDict` and `YearDict`.
+
+## Install
+```bash
+pip install datedict
+```
+
+## Usage
+
+```python
+from datedict import DateDict, YearDict
+```

datedict-1.0.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+datedict/DateDict.py,sha256=nJsE2m8aPfYdPzOs61Jg7uvykDQd4o0YwrTfJkx5dtI,1441
+datedict/TimeDict.py,sha256=20jUsuEZ2rW0XCJZF1h3scYDfu80rXWT69qN2VvQXqA,7831
+datedict/YearDict.py,sha256=xEJYxAFY3zhR8wKejlac976jMwJfkKsak9t4DHTmMKM,707
+datedict/__init__.py,sha256=XB30NC1fBiG4DAswy7JcmIiisDPqgiDGiHxoNQU7bMk,201
+datedict/common.py,sha256=aUCsMV6roKGQIQXSFIJIN0cxAXIlK_YyRDWS1EIBu8E,424
+datedict-1.0.4.dist-info/METADATA,sha256=eDzXvzTdBdlX2I8tRUnMaCK8jlN3kVyZRijsoKX8Aaw,1991
+datedict-1.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+datedict-1.0.4.dist-info/licenses/LICENSE,sha256=GMmiaNfJSsljmGtIp9lCY6V-Dkc9NDZn0jSZuAbFe7Y,1070
+datedict-1.0.4.dist-info/RECORD,,

datedict-1.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

datedict-1.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DEC Energy SA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.