parch 0.1.0__py3-none-any.whl

parch/__init__.py

@@ -0,0 +1,17 @@
+"""parch: Python port of kudrykv/LYP yearly e-ink planner."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+
+class Error(Exception):
+    """Base package error."""
+
+
+class InternalError(Error):
+    """Programming / invariant error."""
+
+
+class ConfigError(Error):
+    """Invalid or incomplete planner configuration."""

parch/__main__.py

@@ -0,0 +1,4 @@
+from parch.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

parch/calendar/__init__.py

@@ -0,0 +1,39 @@
+"""Calendar entities (Day / Week / Month / Quarter) with Ruby-style succ ranges."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Protocol, TypeVar
+
+from parch.calendar.day import WEEKDAYS, Day
+from parch.calendar.month import Month
+from parch.calendar.quarter import Quarter
+from parch.calendar.week import Week
+from parch.calendar.dated_note import DatedNote
+
+T = TypeVar("T", bound="ComparableSucc")
+
+
+class ComparableSucc(Protocol):
+    def succ(self) -> T: ...  # type: ignore[misc]
+
+    def __le__(self, other: object) -> bool: ...
+
+
+def walk(start: T, end: T) -> Iterator[T]:
+    """Inclusive range ``start..end`` using ``succ``, like Ruby."""
+    current = start
+    while current <= end:
+        yield current
+        current = current.succ()  # type: ignore[assignment]
+
+
+__all__ = [
+    "WEEKDAYS",
+    "Day",
+    "Week",
+    "Month",
+    "Quarter",
+    "DatedNote",
+    "walk",
+]

parch/calendar/dated_note.py

@@ -0,0 +1,34 @@
+"""Dated extra-note page — port of LYP::Entities::DatedNote."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from parch.calendar.day import Day
+
+
+class DatedNote:
+    def __init__(self, weekday_start: str, day: Day, page: int = 1) -> None:
+        self.weekday_start = weekday_start
+        self.day = day
+        self.page = page
+
+    @property
+    def id(self) -> str:
+        return f"daily-note-{self.day.strftime('%Y-%m-%d')}-page-{self.page}"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, DatedNote):
+            return False
+        return (
+            self.weekday_start == other.weekday_start
+            and self.day == other.day
+            and self.page == other.page
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.weekday_start, self.day, self.page))
+
+    def __repr__(self) -> str:
+        return f"DatedNote({self.id})"

parch/calendar/day.py

@@ -0,0 +1,181 @@
+"""Day entity — port of LYP::Entities::Calendar::Day."""
+
+from __future__ import annotations
+
+import calendar as pycal
+from datetime import date, timedelta
+from typing import TYPE_CHECKING
+
+from parch import InternalError
+
+if TYPE_CHECKING:
+    from parch.calendar.month import Month
+    from parch.calendar.quarter import Quarter
+    from parch.calendar.week import Week
+
+WEEKDAYS = (
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+)
+
+_WEEKDAY_INDEX = {name: i for i, name in enumerate(WEEKDAYS)}
+_MONTH_NAMES = (
+    "january",
+    "february",
+    "march",
+    "april",
+    "may",
+    "june",
+    "july",
+    "august",
+    "september",
+    "october",
+    "november",
+    "december",
+)
+
+
+def normalize_weekday(value: str) -> str:
+    name = str(value).strip().lower()
+    if name not in _WEEKDAY_INDEX:
+        raise ValueError(f"Bad weekday {value!r}, allowed values are {list(WEEKDAYS)}")
+    return name
+
+
+def add_months(d: date, months: int) -> date:
+    """ActiveSupport-style month arithmetic (clamp to last day of target month)."""
+    month_index = d.month - 1 + months
+    year = d.year + month_index // 12
+    month = month_index % 12 + 1
+    last = pycal.monthrange(year, month)[1]
+    return date(year, month, min(d.day, last))
+
+
+class Day:
+    def __init__(self, weekday_start: str, day: date) -> None:
+        if type(day) is not date:
+            raise TypeError("day must be datetime.date")
+        self.weekday_start = normalize_weekday(weekday_start)
+        self.day = day
+
+    @property
+    def year(self) -> int:
+        return self.day.year
+
+    def strftime(self, fmt: str) -> str:
+        # Ruby %e is space-padded day-of-month; Python's %e is not portable.
+        if "%e" in fmt:
+            fmt = fmt.replace("%e", f"{self.day.day:2d}")
+        if "%k" in fmt:
+            # not used on Day, but keep for completeness
+            pass
+        return self.day.strftime(fmt)
+
+    @property
+    def id(self) -> str:
+        return self.day.strftime("%Y-%m-%d")
+
+    def beginning_of_month(self) -> Day:
+        return Day(weekday_start=self.weekday_start, day=self.day.replace(day=1))
+
+    def end_of_month(self) -> Day:
+        last = pycal.monthrange(self.day.year, self.day.month)[1]
+        return Day(weekday_start=self.weekday_start, day=self.day.replace(day=last))
+
+    def next_month(self) -> Day:
+        return Day(weekday_start=self.weekday_start, day=add_months(self.day, 1))
+
+    def month(self) -> Month:
+        from parch.calendar.month import Month
+
+        return Month(weekday_start=self.weekday_start, day=self)
+
+    def quarter(self) -> Quarter:
+        from parch.calendar.quarter import Quarter
+
+        return Quarter(weekday_start=self.weekday_start, day=self)
+
+    def week(self) -> Week:
+        from parch.calendar.week import Week
+
+        return Week(weekday_start=self.weekday_start, day=self.beginning_of_week())
+
+    @property
+    def quarter_number(self) -> int:
+        return (self.day.month - 1) // 3 + 1
+
+    def next_quarter(self) -> Day:
+        return Day(weekday_start=self.weekday_start, day=add_months(self.day, 3))
+
+    def beginning_of_week(self) -> Day:
+        start = _WEEKDAY_INDEX[self.weekday_start]
+        delta = (self.day.weekday() - start) % 7
+        return Day(weekday_start=self.weekday_start, day=self.day - timedelta(days=delta))
+
+    def end_of_week(self) -> Day:
+        return self.beginning_of_week() + 6
+
+    @property
+    def month_day(self) -> int:
+        return self.day.day
+
+    @property
+    def weekday_name(self) -> str:
+        return WEEKDAYS[self.day.weekday()]
+
+    def succ(self) -> Day:
+        return Day(weekday_start=self.weekday_start, day=self.day + timedelta(days=1))
+
+    def beginning_of_quarter(self) -> Day:
+        start_month = (self.quarter_number - 1) * 3 + 1
+        return Day(weekday_start=self.weekday_start, day=date(self.day.year, start_month, 1))
+
+    def __add__(self, other: object) -> Day:
+        if not isinstance(other, int):
+            return NotImplemented
+        return Day(weekday_start=self.weekday_start, day=self.day + timedelta(days=other))
+
+    def __radd__(self, other: object) -> Day:
+        return self.__add__(other)
+
+    def _require_same(self, other: object, kind: str) -> Day:
+        if not isinstance(other, Day):
+            raise TypeError(f"must be {kind}")
+        if other.weekday_start != self.weekday_start:
+            raise ValueError("weekday start must match")
+        return other
+
+    def __lt__(self, other: object) -> bool:
+        other_day = self._require_same(other, "Day")
+        return self.day < other_day.day
+
+    def __le__(self, other: object) -> bool:
+        other_day = self._require_same(other, "Day")
+        return self.day <= other_day.day
+
+    def __gt__(self, other: object) -> bool:
+        other_day = self._require_same(other, "Day")
+        return self.day > other_day.day
+
+    def __ge__(self, other: object) -> bool:
+        other_day = self._require_same(other, "Day")
+        return self.day >= other_day.day
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Day):
+            return False
+        return self.weekday_start == other.weekday_start and self.day == other.day
+
+    def __hash__(self) -> int:
+        return hash((self.weekday_start, self.day))
+
+    def __repr__(self) -> str:
+        return f"Day({self.day} wd={self.weekday_start})"
+
+    def __str__(self) -> str:
+        return f"{self.day} (wd: {self.weekday_start}, {self.weekday_name})"

parch/calendar/month.py

@@ -0,0 +1,83 @@
+"""Month entity — port of LYP::Entities::Calendar::Month."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from parch import InternalError
+
+if TYPE_CHECKING:
+    from parch.calendar.day import Day
+    from parch.calendar.quarter import Quarter
+
+_MONTH_NAMES = (
+    "january",
+    "february",
+    "march",
+    "april",
+    "may",
+    "june",
+    "july",
+    "august",
+    "september",
+    "october",
+    "november",
+    "december",
+)
+
+
+class Month:
+    def __init__(self, weekday_start: str, day: Day) -> None:
+        from parch.calendar.day import Day as DayCls
+
+        if not isinstance(day, DayCls):
+            raise InternalError("Month.day must be a Day")
+        self.weekday_start = weekday_start
+        self.day = day.beginning_of_month()
+
+    @property
+    def id(self) -> str:
+        return f"month-{self.day.id}"
+
+    @property
+    def name(self) -> str:
+        return _MONTH_NAMES[self.day.day.month - 1]
+
+    def succ(self) -> Month:
+        return Month(weekday_start=self.weekday_start, day=self.day.next_month())
+
+    def quarter(self) -> Quarter:
+        return self.day.quarter()
+
+    def _require_same(self, other: object) -> Month:
+        if not isinstance(other, Month):
+            raise TypeError("must be Month")
+        if self.weekday_start != other.weekday_start:
+            raise ValueError("weekday start must match")
+        return other
+
+    def __lt__(self, other: object) -> bool:
+        return self.day < self._require_same(other).day
+
+    def __le__(self, other: object) -> bool:
+        return self.day <= self._require_same(other).day
+
+    def __gt__(self, other: object) -> bool:
+        return self.day > self._require_same(other).day
+
+    def __ge__(self, other: object) -> bool:
+        return self.day >= self._require_same(other).day
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Month):
+            return False
+        return self.weekday_start == other.weekday_start and self.day == other.day
+
+    def __hash__(self) -> int:
+        return hash((self.weekday_start, self.day))
+
+    def __repr__(self) -> str:
+        return f"Month({self.day.strftime('%Y-%m')} wd={self.weekday_start})"
+
+    def __str__(self) -> str:
+        return f"{self.day.strftime('%Y, %B')} (wd: {self.weekday_start})"

parch/calendar/quarter.py

@@ -0,0 +1,67 @@
+"""Quarter entity — port of LYP::Entities::Calendar::Quarter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from parch.calendar.day import Day
+    from parch.calendar.month import Month
+
+
+class Quarter:
+    def __init__(self, weekday_start: str, day: Day) -> None:
+        self.weekday_start = weekday_start
+        self.day = day.beginning_of_quarter()
+
+    @property
+    def id(self) -> str:
+        return f"quarter-{self.day.year}-{self.number}"
+
+    @property
+    def number(self) -> int:
+        return self.day.quarter_number
+
+    def months(self) -> list[Month]:
+        from parch.calendar.month import Month
+
+        first = Month(weekday_start=self.weekday_start, day=self.day)
+        second = Month(weekday_start=self.weekday_start, day=self.day.next_month())
+        third = Month(weekday_start=self.weekday_start, day=self.day.next_month().next_month())
+        return [first, second, third]
+
+    def succ(self) -> Quarter:
+        return Quarter(weekday_start=self.weekday_start, day=self.day.next_quarter())
+
+    def _require_same(self, other: object) -> Quarter:
+        if not isinstance(other, Quarter):
+            raise TypeError("must be Quarter")
+        if other.weekday_start != self.weekday_start:
+            raise ValueError("weekday start must match")
+        return other
+
+    def __lt__(self, other: object) -> bool:
+        return self.day < self._require_same(other).day
+
+    def __le__(self, other: object) -> bool:
+        return self.day <= self._require_same(other).day
+
+    def __gt__(self, other: object) -> bool:
+        return self.day > self._require_same(other).day
+
+    def __ge__(self, other: object) -> bool:
+        return self.day >= self._require_same(other).day
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Quarter):
+            return False
+        return self.weekday_start == other.weekday_start and self.day == other.day
+
+    def __hash__(self) -> int:
+        return hash((self.weekday_start, self.day))
+
+    def __repr__(self) -> str:
+        return f"Quarter({self.id} wd={self.weekday_start})"
+
+    def __str__(self) -> str:
+        return f"Q{self.number} (wd: {self.weekday_start})"

parch/calendar/week.py

@@ -0,0 +1,71 @@
+"""Week entity — port of LYP::Entities::Calendar::Week."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from parch import InternalError
+
+if TYPE_CHECKING:
+    from parch.calendar.day import Day
+    from parch.calendar.month import Month
+    from parch.calendar.quarter import Quarter
+
+
+class Week:
+    def __init__(self, weekday_start: str, day: Day) -> None:
+        from parch.calendar.day import Day as DayCls
+
+        if not isinstance(day, DayCls):
+            raise InternalError("Week.day must be a Day")
+        self.weekday_start = weekday_start
+        self.day = day.beginning_of_week()
+
+    @property
+    def id(self) -> str:
+        return self._iso_label()
+
+    def _iso_label(self) -> str:
+        iso = self.day.day.isocalendar()
+        return f"{iso.year}W{iso.week:02d}"
+
+    @property
+    def number(self) -> int:
+        return self.day.day.isocalendar().week
+
+    def days(self) -> list[Day]:
+        return [self.day + i for i in range(7)]
+
+    def in_months(self) -> list[Month]:
+        first = self.days()[0]
+        last = self.days()[-1]
+        months = [first.month(), last.month()]
+        out: list[Month] = []
+        for month in months:
+            if month not in out:
+                out.append(month)
+        return out
+
+    def in_quarters(self) -> list[Quarter]:
+        first = self.days()[0]
+        last = self.days()[-1]
+        quarters = [first.quarter(), last.quarter()]
+        out: list[Quarter] = []
+        for quarter in quarters:
+            if quarter not in out:
+                out.append(quarter)
+        return out
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Week):
+            return False
+        return self.weekday_start == other.weekday_start and self.day == other.day
+
+    def __hash__(self) -> int:
+        return hash((self.weekday_start, self.day))
+
+    def __repr__(self) -> str:
+        return f"Week({self.id} wd={self.weekday_start})"
+
+    def __str__(self) -> str:
+        return self.id