praiselul 0.1.0__tar.gz

praiselul-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: praiselul
+Version: 0.1.0
+Summary: Overtime management for Praise
+Author-email: guillaume@pafin.com
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LysanderGG/praiselul
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests~=2.31
+Requires-Dist: plotly~=5.18
+Provides-Extra: dev
+Requires-Dist: pytest~=8.0; extra == "dev"
+Requires-Dist: ruff~=0.4; extra == "dev"
+
+# praiselul
+
+Overtime management CLI for [Praise](https://github.com/Cryptact/praise).
+
+Mirrors [RecoLul](https://github.com/Maerig/recolul)'s interface, powered by Praise's REST API.
+
+## Install
+
+```bash
+pip install praiselul
+```
+
+## Setup
+
+```bash
+praiselul config
+```
+
+Prompts for Praise server URL, email, password, and hours per day.
+
+## Commands
+
+```bash
+praiselul balance                # Monthly overtime balance + workplace breakdown
+praiselul balance --exclude-last-day
+praiselul when                   # When to leave to avoid overtime
+praiselul graph                  # Plotly overtime progression chart
+praiselul graph --exclude-last-day
+```
+
+## Config
+
+Stored in `~/.praiselul/config.ini`. Also supports environment variables:
+
+- `PRAISE_URL`
+- `PRAISE_EMAIL`
+- `PRAISE_PASSWORD`
+- `PRAISE_HOURS_PER_DAY` (default: 8)

praiselul-0.1.0/README.md

@@ -0,0 +1,38 @@
+# praiselul
+
+Overtime management CLI for [Praise](https://github.com/Cryptact/praise).
+
+Mirrors [RecoLul](https://github.com/Maerig/recolul)'s interface, powered by Praise's REST API.
+
+## Install
+
+```bash
+pip install praiselul
+```
+
+## Setup
+
+```bash
+praiselul config
+```
+
+Prompts for Praise server URL, email, password, and hours per day.
+
+## Commands
+
+```bash
+praiselul balance                # Monthly overtime balance + workplace breakdown
+praiselul balance --exclude-last-day
+praiselul when                   # When to leave to avoid overtime
+praiselul graph                  # Plotly overtime progression chart
+praiselul graph --exclude-last-day
+```
+
+## Config
+
+Stored in `~/.praiselul/config.ini`. Also supports environment variables:
+
+- `PRAISE_URL`
+- `PRAISE_EMAIL`
+- `PRAISE_PASSWORD`
+- `PRAISE_HOURS_PER_DAY` (default: 8)

praiselul-0.1.0/praiselul/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

praiselul-0.1.0/praiselul/cli.py

@@ -0,0 +1,150 @@
+import argparse
+import sys
+from getpass import getpass
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from praiselul import __version__, plotting, time
+from praiselul.config import Config, DEFAULT_HOURS_PER_DAY
+from praiselul.duration import Duration
+from praiselul.errors import NoClockInError
+from praiselul.praise.praise_session import PraiseSession
+
+
+def _get_tz(timesheet: dict[str, Any]) -> ZoneInfo:
+    return ZoneInfo(timesheet.get("timezone", "UTC"))
+
+
+def balance(config: Config, exclude_last_day: bool) -> None:
+    timesheet = _get_timesheet(config)
+    tz = _get_tz(timesheet)
+    days = time.until_today(timesheet["days"], tz)
+    if exclude_last_day and len(days) > 1:
+        days = days[:-1]
+
+    overtime_balance = time.get_overtime_balance(days, config, tz)
+    print(f"Monthly overtime balance: {overtime_balance}")
+
+    workplace_times = time.get_workplace_times(timesheet["summary"])
+    if workplace_times:
+        print("Total time per workplace:")
+        for workplace, total_work_time in workplace_times.items():
+            print(f"  {workplace}: {total_work_time}")
+
+    summary = timesheet["summary"]
+    if summary.get("hasRemoteAllowance"):
+        remote_budget = Duration.from_minutes(summary.get("requiredMinutes", 0) - summary.get("requiredOnSiteMinutes", 0))
+        print(f"Maximum WFH time this month: {remote_budget}")
+
+    if exclude_last_day:
+        return
+
+    today = time.get_today_record(days, tz)
+    if today:
+        label = time.day_label(today["date"])
+        print(f"\nLast day {label}")
+        clock_in_time = time.get_clock_in_time(today, tz)
+        if clock_in_time:
+            print(f"  Clock-in: {clock_in_time}")
+        actual_mins = time._day_actual_minutes(today, tz)
+        print(f"  Working hours: {Duration.from_minutes(actual_mins)}")
+        break_mins = Duration.from_minutes(today.get("breakMinutes"))
+        if break_mins:
+            print(f"  Break: {break_mins}")
+
+
+def when_to_leave(config: Config) -> None:
+    try:
+        timesheet = _get_timesheet(config)
+        tz = _get_tz(timesheet)
+        leave_times = time.get_leave_time(timesheet["days"], config, tz)
+    except NoClockInError:
+        print("You have already clocked out.")
+        return
+
+    if len(leave_times) == 1:
+        break_msg = "(break time included)" if leave_times[0].includes_break else "(break time not included)"
+        print(f"Leave at {leave_times[0].min_time} to avoid overtime {break_msg}.")
+    else:
+        print(
+            f"Leave between {leave_times[0].min_time} and {leave_times[0].max_time}, or "
+            f"after {leave_times[1].min_time}."
+        )
+
+
+def update_config() -> None:
+    praise_url = input("praise.url: ")
+    praise_email = input("praise.email: ")
+    praise_password = getpass("praise.password: ")
+    hours_per_day = input(f"praise.hoursPerDay [{DEFAULT_HOURS_PER_DAY}]: ") or str(DEFAULT_HOURS_PER_DAY)
+    config = Config(
+        praise_url=praise_url,
+        praise_email=praise_email,
+        praise_password=praise_password,
+        hours_per_day=int(hours_per_day),
+    )
+    config.save()
+
+
+def graph(config: Config, exclude_last_day: bool) -> None:
+    timesheet = _get_timesheet(config)
+    tz = _get_tz(timesheet)
+    days = time.until_today(timesheet["days"], tz)
+    if exclude_last_day and len(days) > 1:
+        days = days[:-1]
+    labels, history = time.get_overtime_history(days, config, tz)
+    plotting.plot_overtime_balance_history(labels, history)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="praiselul")
+    parser.add_argument("-v", "--version", action="version", version=__version__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    balance_parser = subparsers.add_parser("balance", help="Calculate overtime balance")
+    balance_parser.add_argument(
+        "--exclude-last-day",
+        action="store_true",
+        help="Exclude last/current day from the calculation",
+    )
+
+    subparsers.add_parser("when", help="Calculate at which time to leave to avoid overtime this month")
+
+    subparsers.add_parser("config", help="Init or update config")
+
+    graph_parser = subparsers.add_parser("graph", help="Display a graph of overtime balance over the month")
+    graph_parser.add_argument(
+        "--exclude-last-day",
+        action="store_true",
+        help="Exclude last/current day from the graph",
+    )
+
+    args = parser.parse_args(sys.argv[1:])
+    if args.command == "config":
+        update_config()
+        return
+
+    config = Config.from_env() or Config.load()
+    if not config:
+        raise RuntimeError("No config found. Run: praiselul config")
+
+    match args.command:
+        case "balance":
+            balance(config, exclude_last_day=args.exclude_last_day)
+        case "when":
+            when_to_leave(config)
+        case "graph":
+            graph(config, exclude_last_day=args.exclude_last_day)
+
+
+def _get_timesheet(config: Config) -> dict[str, Any]:
+    with PraiseSession(
+        base_url=config.praise_url,
+        email=config.praise_email,
+        password=config.praise_password,
+    ) as session:
+        return session.get_timesheet()
+
+
+if __name__ == "__main__":
+    main()

praiselul-0.1.0/praiselul/config.py

@@ -0,0 +1,55 @@
+import configparser
+import os
+import os.path
+from dataclasses import dataclass
+
+DEFAULT_CONFIG_DIR = os.path.expanduser("~/.praiselul")
+DEFAULT_CONFIG_PATH = os.path.join(DEFAULT_CONFIG_DIR, "config.ini")
+
+DEFAULT_HOURS_PER_DAY = 8
+
+
+@dataclass
+class Config:
+    praise_url: str
+    praise_email: str
+    praise_password: str
+    hours_per_day: int = DEFAULT_HOURS_PER_DAY
+
+    @classmethod
+    def from_env(cls):
+        try:
+            return cls(
+                praise_url=os.environ["PRAISE_URL"],
+                praise_email=os.environ["PRAISE_EMAIL"],
+                praise_password=os.environ["PRAISE_PASSWORD"],
+                hours_per_day=int(os.getenv("PRAISE_HOURS_PER_DAY", DEFAULT_HOURS_PER_DAY)),
+            )
+        except KeyError:
+            return None
+
+    @classmethod
+    def load(cls, path: str = DEFAULT_CONFIG_PATH):
+        if not os.path.isfile(path):
+            return None
+
+        config = configparser.ConfigParser(interpolation=None)
+        config.read(path)
+        return cls(
+            praise_url=config["praise"]["url"],
+            praise_email=config["praise"]["email"],
+            praise_password=config["praise"]["password"],
+            hours_per_day=int(config["praise"].get("hoursPerDay", str(DEFAULT_HOURS_PER_DAY))),
+        )
+
+    def save(self, path: str = DEFAULT_CONFIG_PATH):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        config = configparser.ConfigParser(interpolation=None)
+        config["praise"] = {
+            "url": self.praise_url,
+            "email": self.praise_email,
+            "password": self.praise_password,
+            "hoursPerDay": str(self.hours_per_day),
+        }
+        with open(path, "w") as config_file:
+            config.write(config_file)

praiselul-0.1.0/praiselul/duration.py

@@ -0,0 +1,67 @@
+from datetime import datetime
+
+
+class Duration:
+    @classmethod
+    def parse(cls, duration: str):
+        if duration == "":
+            return cls(0)
+        hours, minutes = duration.split(":")
+        total_minutes = 60 * int(hours) + int(minutes)
+        return cls(total_minutes)
+
+    @classmethod
+    def now(cls):
+        return cls.parse(datetime.now().strftime("%H:%M"))
+
+    @classmethod
+    def from_minutes(cls, minutes: int | float | None):
+        if minutes is None:
+            return cls(0)
+        return cls(int(minutes))
+
+    def __init__(self, minutes: int = 0):
+        self.minutes: int = minutes
+
+    def __repr__(self) -> str:
+        return f"{'-' if self.minutes < 0 else ''}{abs(self.minutes) // 60:02}:{abs(self.minutes) % 60:02}"
+
+    __str__ = __repr__
+
+    def __eq__(self, other):
+        if other is None:
+            return False
+        return self.minutes == other.minutes
+
+    def __neq__(self, other):
+        return self.minutes != other.minutes
+
+    def __add__(self, other):
+        return Duration(self.minutes + other.minutes)
+
+    def __sub__(self, other):
+        return Duration(self.minutes - other.minutes)
+
+    def __neg__(self):
+        return Duration(-self.minutes)
+
+    def __mul__(self, other):
+        return Duration(other * self.minutes)
+
+    def __lt__(self, other):
+        return self.minutes < other.minutes
+
+    def __gt__(self, other):
+        return self.minutes > other.minutes
+
+    def __le__(self, other):
+        return self.minutes <= other.minutes
+
+    def __ge__(self, other):
+        return self.minutes >= other.minutes
+
+    def __abs__(self):
+        return Duration(abs(self.minutes))
+
+    def __bool__(self):
+        return self.minutes > 0

praiselul-0.1.0/praiselul/errors.py

@@ -0,0 +1,8 @@
+class InvalidPraiseLoginError(Exception):
+    """Invalid Praise login information"""
+    def __init__(self):
+        super().__init__("Invalid Praise login information. Run praiselul config")
+
+
+class NoClockInError(Exception):
+    """A clock-in time was expected but wasn't found"""

praiselul-0.1.0/praiselul/plotting.py

@@ -0,0 +1,27 @@
+import plotly.graph_objects as go
+
+from praiselul.duration import Duration
+
+
+def plot_overtime_balance_history(days: list[str], overtime_history: list[Duration]) -> None:
+    cumulative_overtime_history = []
+    for overtime in overtime_history:
+        last_cumulative_overtime = (
+            cumulative_overtime_history[-1] if cumulative_overtime_history
+            else Duration()
+        )
+        cumulative_overtime_history.append(last_cumulative_overtime + overtime)
+
+    fig = go.Figure(
+        data=go.Scatter(
+            x=days,
+            y=[duration.minutes for duration in cumulative_overtime_history],
+            text=[str(duration) for duration in cumulative_overtime_history],
+            hovertemplate="%{x} %{text}<extra></extra>",
+            mode="lines+markers",
+        )
+    )
+    fig.update_layout(
+        yaxis_title="Overtime balance (minutes)",
+    )
+    fig.show()

praiselul-0.1.0/praiselul/praise/praise_session.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import requests
+
+from praiselul.errors import InvalidPraiseLoginError
+
+
+class PraiseSession:
+    def __init__(self, base_url: str, email: str, password: str):
+        if not base_url.startswith(("http://", "https://")):
+            base_url = f"https://{base_url}"
+        self._base_url: str = base_url.rstrip("/")
+        self._email: str = email
+        self._password: str = password
+        self._session: requests.Session | None = None
+
+    def __enter__(self):
+        self._session = requests.Session()
+        self._fetch_build_version()
+        self._login()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._session.close()
+        self._session = None
+
+    @property
+    def session(self) -> requests.Session:
+        assert self._session, "PraiseSession should be used as a context manager"
+        return self._session
+
+    def get_timesheet(self, year: int | None = None, month: int | None = None) -> dict[str, Any]:
+        now = datetime.now()
+        year = year or now.year
+        month = month or now.month
+        response = self.session.get(
+            f"{self._base_url}/api/time/my-timesheet",
+            params={"year": year, "month": month, "locale": "en"},
+        )
+        response.raise_for_status()
+        data = response.json()
+        if not data.get("success"):
+            raise RuntimeError(f"API error: {data.get('error', {}).get('code', 'unknown')}")
+        return data["data"]
+
+    def get_clock_status(self) -> dict[str, Any]:
+        response = self.session.get(
+            f"{self._base_url}/api/time/clock/status",
+            params={"locale": "en"},
+        )
+        response.raise_for_status()
+        data = response.json()
+        if not data.get("success"):
+            raise RuntimeError(f"API error: {data.get('error', {}).get('code', 'unknown')}")
+        return data["data"]
+
+    def _fetch_build_version(self):
+        """Fetch the server's build version from /api/health (no version check on that route)
+        and set it as a default header for all subsequent requests."""
+        response = self.session.get(f"{self._base_url}/api/health")
+        response.raise_for_status()
+        version = response.json().get("version")
+        if version:
+            self.session.headers["X-Build-Version"] = version
+
+    def _login(self):
+        response = self.session.post(
+            f"{self._base_url}/api/auth/login",
+            json={"email": self._email, "password": self._password},
+        )
+        if response.status_code == 401:
+            raise InvalidPraiseLoginError()
+        response.raise_for_status()
+        data = response.json()
+        if not data.get("success"):
+            raise InvalidPraiseLoginError()

praiselul-0.1.0/praiselul/time.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime, timezone, timedelta
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from praiselul.config import Config
+from praiselul.duration import Duration
+from praiselul.errors import NoClockInError
+
+_MIN_HOURS_FOR_MANDATORY_BREAK = Duration(6 * 60)
+
+# Japanese weekday abbreviations (Mon=0 .. Sun=6)
+_WEEKDAYS_JA = ["月", "火", "水", "木", "金", "土", "日"]
+
+
+def day_label(date_str: str) -> str:
+    """Convert YYYY-MM-DD to 'M/D(曜)' format like RecoLul."""
+    dt = datetime.strptime(date_str, "%Y-%m-%d")
+    weekday = _WEEKDAYS_JA[dt.weekday()]
+    return f"{dt.month}/{dt.day}({weekday})"
+
+
+def until_today(days: list[dict[str, Any]], tz: ZoneInfo | None = None) -> list[dict[str, Any]]:
+    """Return only days up to and including today."""
+    if tz:
+        today = datetime.now(tz).strftime("%Y-%m-%d")
+    else:
+        today = datetime.now().strftime("%Y-%m-%d")
+    return [d for d in days if d["date"] <= today]
+
+
+_NON_WORKING_DAY_TYPES = {"scheduled_rest_day", "statutory_rest_day", "holiday"}
+
+
+def _is_working_day(day: dict[str, Any]) -> bool:
+    return day.get("dayType") not in _NON_WORKING_DAY_TYPES
+
+
+def _day_expected_minutes(day: dict[str, Any], config: Config) -> int:
+    """Expected minutes for overtime calculation.
+
+    Uses config.hours_per_day for working days (matching RecoLul's behavior)
+    and 0 for non-working days (rest days, holidays).
+    """
+    if not _is_working_day(day):
+        return 0
+    return config.hours_per_day * 60
+
+
+def _has_activity(day: dict[str, Any], config: Config) -> bool:
+    """Whether this day has work or expected work."""
+    actual = day.get("actualWorkMinutes") or 0
+    expected = _day_expected_minutes(day, config)
+    return actual > 0 or expected > 0
+
+
+def _get_current_work_minutes(day: dict[str, Any], tz: ZoneInfo) -> int:
+    """For an open session (clocked in, no clock out), compute minutes worked so far."""
+    clock_in = _parse_iso_to_local(day.get("clockIn"), tz)
+    if not clock_in:
+        return 0
+    now = datetime.now(tz)
+    diff = int((now - clock_in).total_seconds() / 60)
+    return max(0, diff)
+
+
+def _day_actual_minutes(day: dict[str, Any], tz: ZoneInfo) -> int:
+    """Get actual work minutes for a day, computing live value for open sessions."""
+    actual = day.get("actualWorkMinutes")
+    if actual is not None:
+        return int(actual)
+    # Open session — compute from clock-in to now
+    if _is_open_session(day):
+        return _get_current_work_minutes(day, tz)
+    return 0
+
+
+def get_overtime_history(
+    days: list[dict[str, Any]], config: Config, tz: ZoneInfo,
+) -> tuple[list[str], list[Duration]]:
+    """Compute per-day overtime from Praise daily records.
+
+    Returns (day_labels, daily_overtime_list).
+    """
+    labels = []
+    overtime_history = []
+    for day in days:
+        actual = _day_actual_minutes(day, tz)
+        expected = _day_expected_minutes(day, config)
+
+        if not (actual or expected):
+            continue
+
+        labels.append(day_label(day["date"]))
+        overtime_history.append(Duration(actual - expected))
+
+    return labels, overtime_history
+
+
+def get_overtime_balance(days: list[dict[str, Any]], config: Config, tz: ZoneInfo) -> Duration:
+    """Sum of daily overtime across all provided days."""
+    _, history = get_overtime_history(days, config, tz)
+    return sum(history, Duration())
+
+
+def get_workplace_times(summary: dict[str, Any]) -> dict[str, Duration]:
+    """Extract workplace breakdown from the timesheet summary."""
+    result = {}
+    on_site = summary.get("onSiteMinutes", 0)
+    remote = summary.get("remoteMinutes", 0)
+    if on_site:
+        result["On-site"] = Duration.from_minutes(on_site)
+    if remote:
+        result["Remote"] = Duration.from_minutes(remote)
+    return result
+
+
+def get_today_record(days: list[dict[str, Any]], tz: ZoneInfo) -> dict[str, Any] | None:
+    """Get today's daily record if it exists."""
+    today = datetime.now(tz).strftime("%Y-%m-%d")
+    for day in days:
+        if day["date"] == today:
+            return day
+    return None
+
+
+def _parse_iso_to_local(iso_str: str | None, tz: ZoneInfo) -> datetime | None:
+    """Parse an ISO datetime string and convert to the given timezone."""
+    if not iso_str:
+        return None
+    dt = datetime.fromisoformat(iso_str)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(tz)
+
+
+def get_clock_in_time(day: dict[str, Any], tz: ZoneInfo) -> Duration | None:
+    """Extract clock-in time as a Duration (local time) from a daily record."""
+    dt = _parse_iso_to_local(day.get("clockIn"), tz)
+    if not dt:
+        return None
+    return Duration(dt.hour * 60 + dt.minute)
+
+
+@dataclasses.dataclass
+class LeaveTime:
+    includes_break: bool
+    min_time: Duration
+    max_time: Duration | None = None
+
+
+def get_leave_time(days: list[dict[str, Any]], config: Config, tz: ZoneInfo) -> list[LeaveTime]:
+    """Calculate when to leave to reach zero monthly overtime.
+
+    Uses the same 3-scenario break logic as RecoLul.
+    """
+    today_days = until_today(days, tz)
+    if not today_days:
+        raise NoClockInError()
+
+    today = today_days[-1]
+    clock_in = get_clock_in_time(today, tz)
+
+    # If no clock-in or already clocked out, raise
+    if not clock_in:
+        raise NoClockInError()
+    if today.get("clockOut") and not _is_open_session(today):
+        raise NoClockInError()
+
+    # Compute overtime balance from all days before today
+    previous_days = today_days[:-1]
+    overtime_balance = get_overtime_balance(previous_days, config, tz)
+
+    day_base_hours = Duration(config.hours_per_day * 60)
+    required_today = day_base_hours - overtime_balance
+
+    leave_time_without_break = clock_in + required_today
+    leave_time_with_break = clock_in + required_today + Duration(60)
+
+    if required_today > _MIN_HOURS_FOR_MANDATORY_BREAK:
+        return [
+            LeaveTime(
+                includes_break=True,
+                min_time=leave_time_with_break,
+            )
+        ]
+    if required_today > _MIN_HOURS_FOR_MANDATORY_BREAK - Duration(60):
+        # Between 5 and 6 hours: two windows
+        first_leave_time = LeaveTime(
+            includes_break=False,
+            min_time=leave_time_without_break,
+            max_time=clock_in + _MIN_HOURS_FOR_MANDATORY_BREAK,
+        )
+        second_leave_time = LeaveTime(
+            includes_break=True,
+            min_time=leave_time_with_break,
+        )
+        return [first_leave_time, second_leave_time]
+    return [
+        LeaveTime(
+            includes_break=False,
+            min_time=leave_time_without_break,
+        )
+    ]
+
+
+def _is_open_session(day: dict[str, Any]) -> bool:
+    """Check if the day has an open (not yet clocked out) session."""
+    sessions = day.get("sessions", [])
+    return any(s.get("clockOut") is None for s in sessions)

praiselul-0.1.0/praiselul.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: praiselul
+Version: 0.1.0
+Summary: Overtime management for Praise
+Author-email: guillaume@pafin.com
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LysanderGG/praiselul
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests~=2.31
+Requires-Dist: plotly~=5.18
+Provides-Extra: dev
+Requires-Dist: pytest~=8.0; extra == "dev"
+Requires-Dist: ruff~=0.4; extra == "dev"
+
+# praiselul
+
+Overtime management CLI for [Praise](https://github.com/Cryptact/praise).
+
+Mirrors [RecoLul](https://github.com/Maerig/recolul)'s interface, powered by Praise's REST API.
+
+## Install
+
+```bash
+pip install praiselul
+```
+
+## Setup
+
+```bash
+praiselul config
+```
+
+Prompts for Praise server URL, email, password, and hours per day.
+
+## Commands
+
+```bash
+praiselul balance                # Monthly overtime balance + workplace breakdown
+praiselul balance --exclude-last-day
+praiselul when                   # When to leave to avoid overtime
+praiselul graph                  # Plotly overtime progression chart
+praiselul graph --exclude-last-day
+```
+
+## Config
+
+Stored in `~/.praiselul/config.ini`. Also supports environment variables:
+
+- `PRAISE_URL`
+- `PRAISE_EMAIL`
+- `PRAISE_PASSWORD`
+- `PRAISE_HOURS_PER_DAY` (default: 8)

praiselul-0.1.0/praiselul.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+praiselul/__init__.py
+praiselul/cli.py
+praiselul/config.py
+praiselul/duration.py
+praiselul/errors.py
+praiselul/plotting.py
+praiselul/time.py
+praiselul.egg-info/PKG-INFO
+praiselul.egg-info/SOURCES.txt
+praiselul.egg-info/dependency_links.txt
+praiselul.egg-info/entry_points.txt
+praiselul.egg-info/requires.txt
+praiselul.egg-info/top_level.txt
+praiselul/praise/__init__.py
+praiselul/praise/praise_session.py
+tests/test_time.py

praiselul-0.1.0/praiselul.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

praiselul-0.1.0/praiselul.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+praiselul = praiselul.cli:main

praiselul-0.1.0/praiselul.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests~=2.31
+plotly~=5.18
+
+[dev]
+pytest~=8.0
+ruff~=0.4

praiselul-0.1.0/praiselul.egg-info/top_level.txt

@@ -0,0 +1 @@
+praiselul

praiselul-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools >= 68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "praiselul"
+version = "0.1.0"
+description = "Overtime management for Praise"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { email = "guillaume@pafin.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "requests~=2.31",
+    "plotly~=5.18",
+]
+
+[project.urls]
+Repository = "https://github.com/LysanderGG/praiselul"
+
+[project.scripts]
+praiselul = "praiselul.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest~=8.0",
+    "ruff~=0.4",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.setuptools.packages.find]
+include = ["praiselul", "praiselul.*"]

praiselul-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

praiselul-0.1.0/tests/test_time.py

@@ -0,0 +1,233 @@
+from zoneinfo import ZoneInfo
+
+from praiselul.config import Config
+from praiselul.duration import Duration
+from praiselul.time import LeaveTime, get_leave_time, get_overtime_balance, get_overtime_history, get_workplace_times
+
+DEFAULT_CONFIG = Config(praise_url="", praise_email="", praise_password="")  # 8h/day
+PART_TIME_CONFIG = Config(praise_url="", praise_email="", praise_password="", hours_per_day=6)
+
+# Use UTC in tests so clock-in timestamps don't need offset adjustment
+TZ = ZoneInfo("UTC")
+
+
+def _make_day(
+    date: str,
+    day_type: str = "working_day",
+    actual_work_minutes: int | None = None,
+    clock_in: str | None = None,
+    clock_out: str | None = None,
+    break_minutes: int | None = None,
+    sessions: list | None = None,
+) -> dict:
+    return {
+        "date": date,
+        "dayType": day_type,
+        "actualWorkMinutes": actual_work_minutes,
+        "expectedMinutes": 480,  # Praise always sends this; we ignore it for overtime calc
+        "clockIn": clock_in,
+        "clockOut": clock_out,
+        "breakMinutes": break_minutes,
+        "sessions": sessions or [],
+    }
+
+
+# --- get_overtime_history ---
+
+
+def test_overtime_history_normal_days():
+    days = [
+        _make_day("2026-04-07", actual_work_minutes=525),  # 8:45 worked, 8:00 expected → +45
+        _make_day("2026-04-08", actual_work_minutes=505),  # 8:25 → +25
+        _make_day("2026-04-09", actual_work_minutes=432),  # 7:12 → -48
+    ]
+    labels, history = get_overtime_history(days, DEFAULT_CONFIG, TZ)
+    assert labels == ["4/7(火)", "4/8(水)", "4/9(木)"]
+    assert history == [Duration(45), Duration(25), Duration(-48)]
+
+
+def test_overtime_history_skips_rest_days_with_no_activity():
+    days = [
+        _make_day("2026-04-07", actual_work_minutes=480),
+        _make_day("2026-04-08", day_type="statutory_rest_day", actual_work_minutes=None),
+        _make_day("2026-04-09", actual_work_minutes=480),
+    ]
+    labels, history = get_overtime_history(days, DEFAULT_CONFIG, TZ)
+    assert labels == ["4/7(火)", "4/9(木)"]
+    assert history == [Duration(0), Duration(0)]
+
+
+def test_overtime_history_worked_holiday():
+    """Working on a holiday (expected=0 via dayType) counts all hours as overtime."""
+    days = [
+        _make_day("2026-04-08", actual_work_minutes=480),
+        _make_day("2026-04-09", day_type="holiday", actual_work_minutes=203),  # 3:23 worked, 0 expected
+    ]
+    labels, history = get_overtime_history(days, DEFAULT_CONFIG, TZ)
+    assert labels == ["4/8(水)", "4/9(木)"]
+    assert history == [Duration(0), Duration(203)]
+
+
+def test_overtime_history_worked_rest_day():
+    """Working on a rest day counts all hours as overtime (expected=0)."""
+    days = [
+        _make_day("2026-04-07", actual_work_minutes=480),
+        _make_day("2026-04-08", day_type="scheduled_rest_day", actual_work_minutes=180),  # 3h worked
+    ]
+    _, history = get_overtime_history(days, DEFAULT_CONFIG, TZ)
+    assert history == [Duration(0), Duration(180)]
+
+
+def test_overtime_history_part_time():
+    """Part-time: config.hours_per_day=6 means expected=360 per working day."""
+    days = [
+        _make_day("2026-04-07", actual_work_minutes=494),  # 8:14 - 6:00 = +134
+        _make_day("2026-04-08", actual_work_minutes=488),  # 8:08 - 6:00 = +128
+    ]
+    _, history = get_overtime_history(days, PART_TIME_CONFIG, TZ)
+    assert history == [Duration(134), Duration(128)]
+
+
+# --- get_overtime_balance ---
+
+
+def test_overtime_balance():
+    days = [
+        _make_day("2026-04-07", actual_work_minutes=525),  # +45
+        _make_day("2026-04-08", actual_work_minutes=505),  # +25
+        _make_day("2026-04-09", actual_work_minutes=432),  # -48
+    ]
+    assert get_overtime_balance(days, DEFAULT_CONFIG, TZ) == Duration(22)
+
+
+# --- get_workplace_times ---
+
+
+def test_workplace_times():
+    summary = {"onSiteMinutes": 2400, "remoteMinutes": 600}
+    result = get_workplace_times(summary)
+    assert result == {"On-site": Duration(2400), "Remote": Duration(600)}
+
+
+def test_workplace_times_no_remote():
+    summary = {"onSiteMinutes": 2400, "remoteMinutes": 0}
+    result = get_workplace_times(summary)
+    assert result == {"On-site": Duration(2400)}
+
+
+# --- get_leave_time ---
+
+
+def _make_open_day(date: str, clock_in: str) -> dict:
+    """Make a day with an open session (clocked in, not yet clocked out)."""
+    return _make_day(
+        date=date,
+        actual_work_minutes=None,
+        clock_in=clock_in,
+        sessions=[{"clockIn": clock_in, "clockOut": None}],
+    )
+
+
+def test_leave_time_with_break():
+    """Required > 6h → single window with break."""
+    days = [
+        # Previous day: 9 min overtime → required_today = 480-9 = 471 (>360) → break
+        _make_day("2026-04-07", actual_work_minutes=489),
+        _make_open_day("2026-04-08", clock_in="2026-04-08T09:00:00Z"),
+    ]
+    leave_times = get_leave_time(days, DEFAULT_CONFIG, TZ)
+    # leave = 09:00 + 471min + 60min break = 17:51
+    assert leave_times == [
+        LeaveTime(includes_break=True, min_time=Duration.parse("17:51")),
+    ]
+
+
+def test_leave_time_no_break():
+    """Required < 5h → single window without break."""
+    days = [
+        # Previous days: +200min overtime → required_today = 480-200 = 280 (<300) → no break
+        _make_day("2026-04-07", actual_work_minutes=680),
+        _make_open_day("2026-04-08", clock_in="2026-04-08T09:00:00Z"),
+    ]
+    leave_times = get_leave_time(days, DEFAULT_CONFIG, TZ)
+    # leave = 09:00 + 280min = 13:40
+    assert leave_times == [
+        LeaveTime(includes_break=False, min_time=Duration.parse("13:40")),
+    ]
+
+
+def test_double_leave_time():
+    """Required 5-6h → two windows."""
+    days = [
+        # Previous days: +150min overtime → required_today = 480-150 = 330 (between 300 and 360)
+        _make_day("2026-04-07", actual_work_minutes=630),
+        _make_open_day("2026-04-08", clock_in="2026-04-08T09:00:00Z"),
+    ]
+    leave_times = get_leave_time(days, DEFAULT_CONFIG, TZ)
+    assert leave_times == [
+        LeaveTime(includes_break=False, min_time=Duration.parse("14:30"), max_time=Duration.parse("15:00")),
+        LeaveTime(includes_break=True, min_time=Duration.parse("15:30")),
+    ]
+
+
+def test_leave_time_negative_overtime():
+    """Negative overtime balance means more hours required today."""
+    days = [
+        # Previous day: -30min overtime → required_today = 480+30 = 510 (>360) → break
+        _make_day("2026-04-07", actual_work_minutes=450),
+        _make_open_day("2026-04-08", clock_in="2026-04-08T09:00:00Z"),
+    ]
+    leave_times = get_leave_time(days, DEFAULT_CONFIG, TZ)
+    # leave = 09:00 + 510min + 60min = 18:30
+    assert leave_times == [
+        LeaveTime(includes_break=True, min_time=Duration.parse("18:30")),
+    ]
+
+
+def test_leave_time_already_clocked_out():
+    """Already clocked out → NoClockInError caught by CLI."""
+    from praiselul.errors import NoClockInError
+    import pytest
+
+    days = [
+        _make_day(
+            "2026-04-08",
+            actual_work_minutes=480,
+            clock_in="2026-04-08T09:00:00Z",
+            clock_out="2026-04-08T18:00:00Z",
+            sessions=[{"clockIn": "2026-04-08T09:00:00Z", "clockOut": "2026-04-08T18:00:00Z"}],
+        ),
+    ]
+    with pytest.raises(NoClockInError):
+        get_leave_time(days, DEFAULT_CONFIG, TZ)
+
+
+def test_leave_time_part_time():
+    """Part-time config: hours_per_day=6 changes the target."""
+    days = [
+        # Previous day: exactly 6h → 0 overtime → required_today = 360
+        _make_day("2026-04-07", actual_work_minutes=360),
+        _make_open_day("2026-04-08", clock_in="2026-04-08T09:00:00Z"),
+    ]
+    leave_times = get_leave_time(days, PART_TIME_CONFIG, TZ)
+    # required_today = 360 = 6h exactly → 5-6h range (double window)
+    assert leave_times == [
+        LeaveTime(includes_break=False, min_time=Duration.parse("15:00"), max_time=Duration.parse("15:00")),
+        LeaveTime(includes_break=True, min_time=Duration.parse("16:00")),
+    ]
+
+
+def test_leave_time_with_timezone():
+    """Clock-in in UTC should be converted to local time for departure calc."""
+    jst = ZoneInfo("Asia/Tokyo")
+    days = [
+        _make_day("2026-04-07", actual_work_minutes=480),  # 0 overtime
+        # Clock-in at 2026-04-08T00:00:00Z = 09:00 JST
+        _make_open_day("2026-04-08", clock_in="2026-04-08T00:00:00Z"),
+    ]
+    leave_times = get_leave_time(days, DEFAULT_CONFIG, jst)
+    # required_today = 480 (>360) → break
+    # leave = 09:00 JST + 480min + 60min = 18:00
+    assert leave_times == [
+        LeaveTime(includes_break=True, min_time=Duration.parse("18:00")),
+    ]