taskcheck 1.1.2__tar.gz → 1.3.0__tar.gz

taskcheck-1.3.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: taskcheck
+Version: 1.3.0
+Summary: Automatic scheduler for taskwarrior
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: google-api-python-client>=2.198.0
+Requires-Dist: google-auth>=2.56.2
+Requires-Dist: google-auth-oauthlib>=1.2.2
+Requires-Dist: icalendar>=6.0.1
+Requires-Dist: random-unicode-emoji>=2.8
+Requires-Dist: requests>=2.32.3
+Requires-Dist: rich>=13.9.4
+
+![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
+
+A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
+It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
+
+Use it if you want to:
+- stop guessing what to do next
+- fit tasks into real availability
+- be sure your long-time plan won't go overdue
+- keep Taskwarrior as the source of truth
+
+> [!IMPORTANT]
+> This repo is actively maintained again
+
+## Features
+
+- ✨ Auto-schedule tasks from working hours + calendar blocks
+- 🧭 Support complex working-hour maps
+- ⏱️ Consider urgency, due dates, and dependencies
+- 🧪 Dry-run mode to preview changes
+- 🧠 Auto-adjust urgency when deadlines cannot be met
+- 🔄 Force-refresh iCal calendars
+- 📊 Custom reports for planned and unplanned tasks
+- 🎨 Report styling with emoji and extra attributes
+- 🗓️ Block time with iCal or Google Calendar, including all-day events
+
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only
+3. add `estimated` + `time_map` UDAs
+4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+5. `taskcheck --schedule`
+
+## How it works
+
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
+It respects:
+- your working hours
+- task duration estimates
+- calendar events and vacations from iCal / Google Calendar
+- task urgency and due dates
+
+It updates Taskwarrior with:
+- `scheduled` → when work should start
+- `completion_date` → when work is expected to finish
+- a warning when a task will miss its due date
+
+### Required UDAs
+
+- `estimated`: expected duration in hours
+- `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+
+Example:
+
+```toml
+[time_maps.work]
+monday = [[9, 12.30], [14, 17]]
+tuesday = [[9, 12.30], [14, 17]]
+```
+
+### Reports
+
+- `taskcheck -r today` → tasks planned for today
+- `taskcheck -r 1w` → tasks planned for the next week
+
+## Reference
+
+📚 Full reference: [REFERENCE.md](REFERENCE.md)
+
+In short:
+- `taskcheck --install` is interactive
+- it installs required Taskwarrior settings if you confirm the first prompt
+- it installs optional urgency/report tuning if you confirm the second prompt
+- it can also create the default config file if you confirm the third prompt
+- it does **not** schedule tasks or fetch calendars
+- scheduling happens with `taskcheck --schedule`
+- all flags/config keys/settings are documented in `REFERENCE.md`
+
+## Algorithm
+
+The algorithm simulates a workday one chunk at a time.
+
+For each day starting from today, it sorts tasks by urgency and picks the most urgent task that fits the available time.
+It assigns a small block of work, then recomputes urgency exactly as Taskwarrior would on that day.
+If urgency changes, the next task choice can change too.
+
+For `today`, taskcheck skips past hours.
+
+The default work chunk is 2 hours (or less if the task is shorter); you can tune it with the Taskwarrior UDA `min_block`.
+
+If a task would finish after its `due_date`, taskcheck retries. It keeps that task's current non-due urgency weight, then lowers the weight by 0.1 only for tasks that have not missed a deadline. Due urgency is never reduced. Retries stop when deadlines are respected or unflagged tasks reach a weight of 0.
+
+## Tips and Tricks
+
+- You can exclude a task from being scheduled by removing the `time_map` or `estimated` attributes.
+- You can see tasks that you can execute now with the `task ready` report.
+
+See the reference section above for flags, config keys, and installed Taskwarrior settings.

taskcheck-1.3.0/README.md

@@ -0,0 +1,99 @@
+![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
+
+A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
+It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
+
+Use it if you want to:
+- stop guessing what to do next
+- fit tasks into real availability
+- be sure your long-time plan won't go overdue
+- keep Taskwarrior as the source of truth
+
+> [!IMPORTANT]
+> This repo is actively maintained again
+
+## Features
+
+- ✨ Auto-schedule tasks from working hours + calendar blocks
+- 🧭 Support complex working-hour maps
+- ⏱️ Consider urgency, due dates, and dependencies
+- 🧪 Dry-run mode to preview changes
+- 🧠 Auto-adjust urgency when deadlines cannot be met
+- 🔄 Force-refresh iCal calendars
+- 📊 Custom reports for planned and unplanned tasks
+- 🎨 Report styling with emoji and extra attributes
+- 🗓️ Block time with iCal or Google Calendar, including all-day events
+
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only
+3. add `estimated` + `time_map` UDAs
+4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+5. `taskcheck --schedule`
+
+## How it works
+
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
+It respects:
+- your working hours
+- task duration estimates
+- calendar events and vacations from iCal / Google Calendar
+- task urgency and due dates
+
+It updates Taskwarrior with:
+- `scheduled` → when work should start
+- `completion_date` → when work is expected to finish
+- a warning when a task will miss its due date
+
+### Required UDAs
+
+- `estimated`: expected duration in hours
+- `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+
+Example:
+
+```toml
+[time_maps.work]
+monday = [[9, 12.30], [14, 17]]
+tuesday = [[9, 12.30], [14, 17]]
+```
+
+### Reports
+
+- `taskcheck -r today` → tasks planned for today
+- `taskcheck -r 1w` → tasks planned for the next week
+
+## Reference
+
+📚 Full reference: [REFERENCE.md](REFERENCE.md)
+
+In short:
+- `taskcheck --install` is interactive
+- it installs required Taskwarrior settings if you confirm the first prompt
+- it installs optional urgency/report tuning if you confirm the second prompt
+- it can also create the default config file if you confirm the third prompt
+- it does **not** schedule tasks or fetch calendars
+- scheduling happens with `taskcheck --schedule`
+- all flags/config keys/settings are documented in `REFERENCE.md`
+
+## Algorithm
+
+The algorithm simulates a workday one chunk at a time.
+
+For each day starting from today, it sorts tasks by urgency and picks the most urgent task that fits the available time.
+It assigns a small block of work, then recomputes urgency exactly as Taskwarrior would on that day.
+If urgency changes, the next task choice can change too.
+
+For `today`, taskcheck skips past hours.
+
+The default work chunk is 2 hours (or less if the task is shorter); you can tune it with the Taskwarrior UDA `min_block`.
+
+If a task would finish after its `due_date`, taskcheck retries. It keeps that task's current non-due urgency weight, then lowers the weight by 0.1 only for tasks that have not missed a deadline. Due urgency is never reduced. Retries stop when deadlines are respected or unflagged tasks reach a weight of 0.
+
+## Tips and Tricks
+
+- You can exclude a task from being scheduled by removing the `time_map` or `estimated` attributes.
+- You can see tasks that you can execute now with the `task ready` report.
+
+See the reference section above for flags, config keys, and installed Taskwarrior settings.

{taskcheck-1.1.2 → taskcheck-1.3.0}/pyproject.toml

@@ -1,11 +1,14 @@
 [project]
 name = "taskcheck"
-version = "1.1.2"
+version = "1.3.0"
 description = "Automatic scheduler for taskwarrior"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
   "appdirs>=1.4.4",
+  "google-api-python-client>=2.198.0",
+  "google-auth>=2.56.2",
+  "google-auth-oauthlib>=1.2.2",
   "icalendar>=6.0.1",
   "random-unicode-emoji>=2.8",
   "requests>=2.32.3",

{taskcheck-1.1.2 → taskcheck-1.3.0}/taskcheck/__main__.py

@@ -52,7 +52,12 @@ arg_parser.add_argument(
     dest="auto_adjust_urgency",
     action="store_false",
     default=True,
-    help="Disable automatic reduction of urgency weight when tasks cannot be completed on time. (Enabled by default, meaning automatic reduction will occur.)",
+    help="Disable automatic per-task urgency adjustment when tasks cannot be completed on time.",
+)
+arg_parser.add_argument(
+    "--add-google-calendar",
+    action="store_true",
+    help="Authenticate with Google, list calendars, and print a config section for the selected calendar.",
 )
 
 
@@ -100,6 +105,12 @@ def main():
         install()
         return
 
+    if getattr(args, "add_google_calendar", False) is True:
+        from taskcheck.google_calendar import add_google_calendar
+
+        add_google_calendar(taskrc=args.taskrc)
+        return
+
     if args.schedule:
         config = load_config()
         check_tasks_kwargs = dict(

{taskcheck-1.1.2 → taskcheck-1.3.0}/taskcheck/common.py

@@ -211,16 +211,31 @@ def mark_end_date(
 def get_calendars(config, verbose=False, force_update=False):
     calendars = []
     for calname in config["calendars"]:
-        calendar = config["calendars"][calname]
-        calendar = ical_to_dict(
-            calendar["url"],
-            config["scheduler"]["days_ahead"],
-            all_day=calendar["event_all_day_is_blocking"],
-            expiration=calendar["expiration"],
-            verbose=verbose,
-            tz_name=calendar.get("timezone"),
-            force_update=force_update,
-        )
+        calendar_config = config["calendars"][calname]
+        if (
+            calendar_config.get("provider") == "google"
+            or calendar_config["url"].startswith("google://")
+        ):
+            from taskcheck.google_calendar import google_calendar_to_dict
+
+            calendar = google_calendar_to_dict(
+                calendar_config.get(
+                    "calendar_id", calendar_config["url"].removeprefix("google://")
+                ),
+                calendar_config["token_path"],
+                config["scheduler"]["days_ahead"],
+                all_day=calendar_config["event_all_day_is_blocking"],
+            )
+        else:
+            calendar = ical_to_dict(
+                calendar_config["url"],
+                config["scheduler"]["days_ahead"],
+                all_day=calendar_config["event_all_day_is_blocking"],
+                expiration=calendar_config["expiration"],
+                verbose=verbose,
+                tz_name=calendar_config.get("timezone"),
+                force_update=force_update,
+            )
         calendar.sort(key=lambda e: e["start"])
         calendars.append(calendar)
     if verbose:

taskcheck-1.3.0/taskcheck/google_calendar.py

@@ -0,0 +1,172 @@
+import json
+import warnings
+from datetime import datetime, time, timedelta
+from pathlib import Path
+from urllib.parse import urlparse
+
+import requests
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+from taskcheck.common import config_dir, get_task_env
+
+SCOPES = [
+    "openid",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "https://www.googleapis.com/auth/userinfo.profile",
+    "https://www.googleapis.com/auth/calendar.readonly",
+]
+
+
+def get_google_data_dir(taskrc=None):
+    env = get_task_env(taskrc)
+    base = Path(env.get("TASKDATA", config_dir))
+    return base / "google"
+
+
+def get_client_secrets_path(taskrc=None):
+    repo_secret = Path.cwd() / "client_secret.json"
+    if repo_secret.exists():
+        return repo_secret
+    return get_google_data_dir(taskrc) / "client_secret.json"
+
+
+def get_token_path(account_id, taskrc=None):
+    return get_google_data_dir(taskrc) / f"{account_id}.token.json"
+
+
+def _safe_account_id(email):
+    return email.replace("@", "_").replace(".", "_")
+
+
+def load_credentials(taskrc=None):
+    secrets_path = get_client_secrets_path(taskrc)
+    if not secrets_path.exists():
+        raise FileNotFoundError(f"Missing Google OAuth client secrets: {secrets_path}")
+
+    token_dir = get_google_data_dir(taskrc)
+    token_dir.mkdir(parents=True, exist_ok=True)
+    token_path = token_dir / "current.token.json"
+    creds = None
+    if token_path.exists():
+        creds = Credentials.from_authorized_user_file(token_path, SCOPES)
+    if creds and creds.expired and creds.refresh_token:
+        creds.refresh(Request())
+    if not creds or not creds.valid:
+        flow = InstalledAppFlow.from_client_secrets_file(str(secrets_path), SCOPES)
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", message=r'^Scope has changed from .*')
+            creds = flow.run_local_server(port=0)
+        token_path.write_text(creds.to_json())
+    return creds
+
+
+def get_google_user_email(credentials):
+    response = requests.get(
+        "https://openidconnect.googleapis.com/v1/userinfo",
+        headers={"Authorization": f"Bearer {credentials.token}"},
+        timeout=30,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    return payload["email"], payload.get("name", payload["email"])
+
+
+def list_calendars(credentials):
+    service = build("calendar", "v3", credentials=credentials, cache_discovery=False)
+    result = service.calendarList().list().execute()
+    return result.get("items", [])
+
+
+def google_calendar_to_dict(calendar_id, token_path, days_ahead, all_day=True):
+    token_path = Path(token_path).expanduser()
+    if not token_path.exists():
+        raise FileNotFoundError(f"Missing Google OAuth token: {token_path}")
+
+    credentials = Credentials.from_authorized_user_file(str(token_path), SCOPES)
+    if credentials.expired and credentials.refresh_token:
+        credentials.refresh(Request())
+        token_path.write_text(credentials.to_json())
+    if not credentials.valid:
+        raise RuntimeError(f"Invalid Google OAuth token: {token_path}")
+
+    service = build("calendar", "v3", credentials=credentials, cache_discovery=False)
+    timezone = datetime.now().astimezone().tzinfo
+    start = datetime.combine(datetime.now().date(), time.min, timezone)
+    end = start + timedelta(days=days_ahead + 1)
+    params = {
+        "calendarId": calendar_id,
+        "timeMin": start.isoformat(),
+        "timeMax": end.isoformat(),
+        "singleEvents": True,
+        "orderBy": "startTime",
+    }
+    events = []
+    while True:
+        result = service.events().list(**params).execute()
+        for item in result.get("items", []):
+            event_start = item.get("start", {})
+            event_end = item.get("end", {})
+            if "dateTime" in event_start and "dateTime" in event_end:
+                events.append(
+                    {"start": event_start["dateTime"], "end": event_end["dateTime"]}
+                )
+            elif all_day and "date" in event_start and "date" in event_end:
+                events.append(
+                    {
+                        "start": datetime.fromisoformat(event_start["date"]).isoformat(),
+                        "end": datetime.fromisoformat(event_end["date"]).isoformat(),
+                    }
+                )
+        page_token = result.get("nextPageToken")
+        if not page_token:
+            break
+        params["pageToken"] = page_token
+    return events
+
+
+def select_from_list(items, title_key="summary"):
+    for idx, item in enumerate(items, start=1):
+        print(f"{idx}. {item.get(title_key, item.get('id'))}")
+    while True:
+        choice = input("Select one calendar: ").strip()
+        if choice.isdigit() and 1 <= int(choice) <= len(items):
+            return items[int(choice) - 1]
+        print("Invalid selection")
+
+
+def render_calendar_config(account_id, calendar, taskrc=None):
+    token_path = get_token_path(account_id, taskrc)
+    return f'''[calendars."{account_id}.{calendar["id"]}"]
+url = "google://{calendar["id"]}"
+provider = "google"
+account = "{account_id}"
+calendar_id = "{calendar["id"]}"
+token_path = "{token_path}"
+event_all_day_is_blocking = true
+expiration = 0.25
+'''
+
+
+def add_google_calendar(taskrc=None):
+    credentials = load_credentials(taskrc)
+    email, name = get_google_user_email(credentials)
+    account_id = _safe_account_id(email)
+    token_path = get_token_path(account_id, taskrc)
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+    token_path.write_text(credentials.to_json())
+
+    calendars = list_calendars(credentials)
+    if not calendars:
+        raise RuntimeError("No Google calendars found for this account")
+    calendar = select_from_list(calendars)
+    print(render_calendar_config(account_id, calendar, taskrc=taskrc))
+    return {
+        "account_id": account_id,
+        "email": email,
+        "name": name,
+        "calendar": calendar,
+        "token_path": str(token_path),
+    }

{taskcheck-1.1.2 → taskcheck-1.3.0}/taskcheck/parallel.py

@@ -111,6 +111,7 @@ def check_tasks_parallel(
     urgency_coefficients = get_urgency_coefficients(taskrc=taskrc)
 
     current_weight = initial_weight_urgency
+    frozen_weights = {}
 
     # Always re-initialize task_info inside the loop to avoid mutated state
     task_info_original = initialize_task_info(
@@ -132,6 +133,7 @@ def check_tasks_parallel(
                 urgency_coefficients,
                 verbose,
                 current_weight,
+                frozen_weights,
             )
 
         # Check if any tasks cannot be completed on time
@@ -159,7 +161,9 @@ def check_tasks_parallel(
         if not tasks_overdue or not auto_adjust_urgency:
             break
 
-        # If we have overdue tasks and auto-adjust is enabled, reduce weight and try again
+        for task in tasks_overdue:
+            frozen_weights.setdefault(task["uuid"], current_weight)
+
         if verbose:
             console.print(
                 f"[red]{len(tasks_overdue)} task(s) cannot be completed on time[/red]"
@@ -175,12 +179,12 @@ def check_tasks_parallel(
         if tasks_overdue:
             # We tried to adjust but still have overdue tasks
             console.print(
-                "[red]Warning: cannot find a solution even with urgency weight 0.0[/red]"
+                "[red]Warning: cannot find a solution after per-task urgency adjustment[/red]"
             )
         else:
             # We successfully resolved overdue tasks by adjusting weight
             console.print(
-                f"[green]Final urgency weight: {max(current_weight, 0.0):.1f}[/green]"
+                f"[green]Resolved deadlines with per-task urgency adjustment[/green]"
             )
 
     if dry_run:
@@ -275,6 +279,7 @@ def allocate_time_for_day(
     urgency_coefficients,
     verbose,
     weight_urgency,
+    frozen_weights=None,
 ):
     date = datetime.today().date() + timedelta(days=day_offset)
     total_available_hours = compute_total_available_hours(task_info, day_offset)
@@ -287,7 +292,13 @@ def allocate_time_for_day(
     tasks_remaining = prepare_tasks_remaining(task_info, day_offset)
 
     while day_remaining_hours > 0 and tasks_remaining:
-        recompute_urgencies(tasks_remaining, urgency_coefficients, date, weight_urgency)
+        recompute_urgencies(
+            tasks_remaining,
+            urgency_coefficients,
+            date,
+            weight_urgency,
+            frozen_weights,
+        )
         sorted_task_ids = sorted(
             tasks_remaining.keys(),
             key=lambda x: tasks_remaining[x]["urgency"],
@@ -423,8 +434,11 @@ def update_urgency(info, urgency_key, urgency_compute_fn, urgency_coefficients,
     info["urgency"] = info["urgency"] - old_urgency + urgency_value
 
 
-def recompute_urgencies(tasks_remaining, urgency_coefficients, date, weight_urgency):
-    """Recompute urgency simulating that today is `date`"""
+def recompute_urgencies(
+    tasks_remaining, urgency_coefficients, date, weight_urgency, frozen_weights=None
+):
+    """Recompute urgency simulating that today is `date`."""
+    frozen_weights = frozen_weights or {}
     # Recompute estimated urgencies as before
     for info in tasks_remaining.values():
         # Update estimated urgency
@@ -438,7 +452,8 @@ def recompute_urgencies(tasks_remaining, urgency_coefficients, date, weight_urge
 
         # Apply weights to create a combined score
         base_urgency = info["urgency"] - info["due_urgency"]
-        base_urgency *= weight_urgency
+        task_weight = frozen_weights.get(info["task"]["uuid"], weight_urgency)
+        base_urgency *= task_weight
         # Always add due_urgency, only weight estimated and age
         weighted_urgency = base_urgency + info["due_urgency"]
         info["urgency"] = weighted_urgency

{taskcheck-1.1.2 → taskcheck-1.3.0}/taskcheck/report.py

@@ -187,7 +187,7 @@ def get_tasks(config, tasks, year, month, day):
             if m:
                 due = task.get("due", "")
                 if due:
-                    due = datetime.strptime(due, "%Y%m%dT%H%M%SZ")
+                    due = parse_taskwarrior_timestamp(due)
                     due = due - datetime.today()
                 valid_tasks.append(
                     {
@@ -219,7 +219,7 @@ def get_taskwarrior_date(date, _retry=True, taskrc=None):
     )
     date = date.stdout.strip()
     try:
-        date = datetime.strptime(date, "%Y-%m-%dT%H:%M:%S")
+        date = parse_taskwarrior_timestamp(date)
     except Exception as _:
         if _retry:
             return get_taskwarrior_date("today+" + date, False, taskrc)
@@ -247,7 +247,7 @@ def tostring(value):
         return value.strftime("%Y-%m-%d %H:%M")
     elif isinstance(value, str):
         try:
-            date = datetime.strptime(value, "%Y%m%dT%H%M%SZ")
+            date = parse_taskwarrior_timestamp(value)
             return date.strftime("%Y-%m-%d %H:%M")
         except ValueError:
             return value
@@ -275,7 +275,7 @@ def get_unplanned_tasks(config, tasks, taskrc=None):
         task
         for task in tasks
         if not task.get("due")
-        or datetime.strptime(task["due"], "%Y%m%dT%H%M%SZ") <= due_limit
+        or parse_taskwarrior_timestamp(task["due"]) <= due_limit
     ]
 
 
@@ -298,6 +298,15 @@ def generate_report(config, constraint, verbose=False, force_update=False, taskr
         display_tasks_table(console, config, this_day_tasks)
 
 
+def parse_taskwarrior_timestamp(value):
+    for fmt in ("%Y%m%dT%H%M%SZ", "%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S"):
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            pass
+    raise ValueError(value)
+
+
 def fetch_tasks(taskrc=None):
     """Fetch tasks from the task manager and return them as a JSON object."""
     from taskcheck.common import get_task_env