taskcheck 0.1.3__tar.gz → 0.2.0__tar.gz

taskcheck-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.1
+Name: taskcheck
+Version: 0.2.0
+Summary: Automatic scheduler for taskwarrior
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: icalendar>=6.0.1
+Requires-Dist: requests>=2.32.3
+
+
+> _A non-AI automatic scheduler for taskwarrior (i.e. alternative to skedpal/timehero/flowsavvy/reclaim/trevor/motion)_
+
+This is a taskwarrior extension checks if tasks can be completed on time, considering estimated time and working hours.
+
+## Features
+
+- [x] Use arbitrarily complex time maps
+- [x] Use ical to block time from scheduling (e.g. for meetings, vacations, etc.)
+- [x] Implement scheduling algorithm for parallely working on multiple tasks
+- [ ] Use Google/Microsoft/Apple API to access calendars
+
+## Install
+
+1. `pipx install taskcheck`
+2. `taskcheck --install`
+
+## How does it work
+
+This extension parses your pending and waiting tasks sorted decreasingly by urgency and tries to schedule them in the future.
+It considers their estimated time to schedule all tasks starting from the most urgent one.
+
+You will need to add the `estimated` and `time_map` UDAs to your tasks. The `estimated` attribute is
+the expected time to complete the task in hours. The `time_map` is a comma-separated list of strings
+that indicates the hours per day in which you will work on a task (e.g. `work`, `weekend`, etc.).
+The exact correspondence between the `time_map` and the hours of the day is defined in the configuration
+file of taskcheck.
+
+`taskcheck` will modify the Taskwarrior tasks by adding the `completion_date` attribute with the expected
+date of completion and the `scheduled` attribute with the date in which the task is expected to
+start.
+
+It will also print a red line for every task whose `completion_date` is after its `due_date`.
+
+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.
+
+You can see the schedule for a task in the `scheduling` UDA, e.g. `task scheduling:$(task calc
+tomorrow)` will show you the tasks that include a scheduling for tomorrow.
+
+In general, it is recommended to run taskcheck rather frequently and at least once at the beginning
+of your working day.
+
+### Algorithms
+
+Taskcheck provides two scheduling algorithms: `parallel` and `sequential`.
+
+#### Sequential
+
+The `sequential` algorithm schedules tasks one after the other. It is the simplest algorithm.
+It looks at your tasks one by one, computes the time slots available for that task, and fills them
+as soon as possible.
+
+While it sounds logical, it has a problem.
+While you're working on a task, its remaining estimated time is decreasing, and if your urgency
+depends on the estimated time left, the urgency of the task will decrease as well.
+This is especially problematic for long tasks: imagine if you block your whole week for a single
+task and all the other small tasks, even if urgent, don't get scheduled. After a few days, the
+urgency of the first long task should have decreased.
+
+#### Parallel
+
+The `parallel` algorithm tries to solve the problem of the `sequential` algorithm.
+
+Instead of allocating all the available time for a task until the task is finished, the `parallel`
+algorithm allocates a fixed amount of time for each task (e.g. 1 hour) and then recomputes the
+urgency and restart the allocation procedure.
+
+If after 1 hour the long task has decreased urgency, that will be noticed and the newer most urgent
+task will get scheduled in its place.
+
+The minimum time for a task is by default 2 hours, but you can change it by tuning the `min_block`
+taskwarrior UDA.
+
+The `parallel` algorithm is the default algorithm.
+
+## Configuration
+
+`taskcheck --install` allows you to create required and recommended configurations for
+   taskwarrior. It will also generate a default configuration file for taskcheck.
+
+Below is an example of taskcheck configuration file:
+
+```toml
+[time_maps]
+# in which hours you will work in each day (in 24h format, if you use e.g. 25.67 you will likely 
+# get an error)
+[time_maps.work]
+monday = [[9, 12.30], [14, 17]]
+tuesday = [[9, 12.30], [14, 17]]
+wednesday = [[9, 12.30], [14, 17]]
+thursday = [[9, 12.30], [14, 17]]
+friday = [[9, 12.30], [14, 17]]
+
+[time_maps.weekend]
+saturday = [[9, 12.30], ]
+sunday = [[9, 12.30], ]
+
+[scheduler]
+algorithm = "parallel" # or "sequential", see above
+days_ahead = 1000 # how far go with the schedule (lower values make the computation faster)
+
+[calendars]
+# ical calendars can be used to block your time and make the scheduling more precise
+[calendars.1]
+url = "https://your/url/to/calendar.ics"
+expiration = 0.08 # in hours (0.08 hours =~ 5 minutes)
+timezone = "Europe/Rome" # if set, force timezone for this calendar; timezone values are TZ identifiers (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+
+[calendars.holidays]
+url = "https://www.officeholidays.com/ics-clean/italy/milan"
+event_all_day_is_blocking = true
+expiration = 720 # in hours (720 hours = 30 days)
+```
+
+## CLI Options
+
+```
+-v, --verbose: increase output verbosity
+-i, --install: install taskcheck configuration
+```

taskcheck-0.2.0/README.md

@@ -0,0 +1,122 @@
+
+> _A non-AI automatic scheduler for taskwarrior (i.e. alternative to skedpal/timehero/flowsavvy/reclaim/trevor/motion)_
+
+This is a taskwarrior extension checks if tasks can be completed on time, considering estimated time and working hours.
+
+## Features
+
+- [x] Use arbitrarily complex time maps
+- [x] Use ical to block time from scheduling (e.g. for meetings, vacations, etc.)
+- [x] Implement scheduling algorithm for parallely working on multiple tasks
+- [ ] Use Google/Microsoft/Apple API to access calendars
+
+## Install
+
+1. `pipx install taskcheck`
+2. `taskcheck --install`
+
+## How does it work
+
+This extension parses your pending and waiting tasks sorted decreasingly by urgency and tries to schedule them in the future.
+It considers their estimated time to schedule all tasks starting from the most urgent one.
+
+You will need to add the `estimated` and `time_map` UDAs to your tasks. The `estimated` attribute is
+the expected time to complete the task in hours. The `time_map` is a comma-separated list of strings
+that indicates the hours per day in which you will work on a task (e.g. `work`, `weekend`, etc.).
+The exact correspondence between the `time_map` and the hours of the day is defined in the configuration
+file of taskcheck.
+
+`taskcheck` will modify the Taskwarrior tasks by adding the `completion_date` attribute with the expected
+date of completion and the `scheduled` attribute with the date in which the task is expected to
+start.
+
+It will also print a red line for every task whose `completion_date` is after its `due_date`.
+
+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.
+
+You can see the schedule for a task in the `scheduling` UDA, e.g. `task scheduling:$(task calc
+tomorrow)` will show you the tasks that include a scheduling for tomorrow.
+
+In general, it is recommended to run taskcheck rather frequently and at least once at the beginning
+of your working day.
+
+### Algorithms
+
+Taskcheck provides two scheduling algorithms: `parallel` and `sequential`.
+
+#### Sequential
+
+The `sequential` algorithm schedules tasks one after the other. It is the simplest algorithm.
+It looks at your tasks one by one, computes the time slots available for that task, and fills them
+as soon as possible.
+
+While it sounds logical, it has a problem.
+While you're working on a task, its remaining estimated time is decreasing, and if your urgency
+depends on the estimated time left, the urgency of the task will decrease as well.
+This is especially problematic for long tasks: imagine if you block your whole week for a single
+task and all the other small tasks, even if urgent, don't get scheduled. After a few days, the
+urgency of the first long task should have decreased.
+
+#### Parallel
+
+The `parallel` algorithm tries to solve the problem of the `sequential` algorithm.
+
+Instead of allocating all the available time for a task until the task is finished, the `parallel`
+algorithm allocates a fixed amount of time for each task (e.g. 1 hour) and then recomputes the
+urgency and restart the allocation procedure.
+
+If after 1 hour the long task has decreased urgency, that will be noticed and the newer most urgent
+task will get scheduled in its place.
+
+The minimum time for a task is by default 2 hours, but you can change it by tuning the `min_block`
+taskwarrior UDA.
+
+The `parallel` algorithm is the default algorithm.
+
+## Configuration
+
+`taskcheck --install` allows you to create required and recommended configurations for
+   taskwarrior. It will also generate a default configuration file for taskcheck.
+
+Below is an example of taskcheck configuration file:
+
+```toml
+[time_maps]
+# in which hours you will work in each day (in 24h format, if you use e.g. 25.67 you will likely 
+# get an error)
+[time_maps.work]
+monday = [[9, 12.30], [14, 17]]
+tuesday = [[9, 12.30], [14, 17]]
+wednesday = [[9, 12.30], [14, 17]]
+thursday = [[9, 12.30], [14, 17]]
+friday = [[9, 12.30], [14, 17]]
+
+[time_maps.weekend]
+saturday = [[9, 12.30], ]
+sunday = [[9, 12.30], ]
+
+[scheduler]
+algorithm = "parallel" # or "sequential", see above
+days_ahead = 1000 # how far go with the schedule (lower values make the computation faster)
+
+[calendars]
+# ical calendars can be used to block your time and make the scheduling more precise
+[calendars.1]
+url = "https://your/url/to/calendar.ics"
+expiration = 0.08 # in hours (0.08 hours =~ 5 minutes)
+timezone = "Europe/Rome" # if set, force timezone for this calendar; timezone values are TZ identifiers (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+
+[calendars.holidays]
+url = "https://www.officeholidays.com/ics-clean/italy/milan"
+event_all_day_is_blocking = true
+expiration = 720 # in hours (720 hours = 30 days)
+```
+
+## CLI Options
+
+```
+-v, --verbose: increase output verbosity
+-i, --install: install taskcheck configuration
+```

{taskcheck-0.1.3 → taskcheck-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskcheck"
-version = "0.1.3"
+version = "0.2.0"
 description = "Automatic scheduler for taskwarrior"
 readme = "README.md"
 requires-python = ">=3.11"

taskcheck-0.2.0/taskcheck/__main__.py

@@ -0,0 +1,48 @@
+import tomllib
+import argparse
+
+from taskcheck.parallel import check_tasks_parallel
+from taskcheck.sequential import check_tasks_sequentially
+from taskcheck.common import config_dir
+
+arg_parser = argparse.ArgumentParser()
+arg_parser.add_argument(
+    "-v", "--verbose", action="store_true", help="increase output verbosity"
+)
+arg_parser.add_argument(
+    "-i",
+    "--install",
+    action="store_true",
+    help="install the UDAs, required settings, and default config file",
+)
+
+args = arg_parser.parse_args()
+
+
+# Load working hours and exceptions from TOML file
+def load_config():
+    with open(config_dir / "taskcheck.toml", "rb") as f:
+        config = tomllib.load(f)
+    return config
+
+
+def main():
+    # Load data and check tasks
+    if args.install:
+        from taskcheck.install import install
+
+        install()
+        return
+
+    config = load_config()
+    algo = config["scheduler"].get("algorithm", "parallel")
+    if algo == "parallel":
+        check_tasks_parallel(config, verbose=args.verbose)
+    elif algo == "sequential":
+        check_tasks_sequentially(config, verbose=args.verbose)
+    else:
+        raise ValueError(f"Unknown algorithm: {algo}")
+
+
+if __name__ == "__main__":
+    main()

taskcheck-0.2.0/taskcheck/common.py

@@ -0,0 +1,184 @@
+import subprocess
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+import appdirs
+
+from taskcheck.ical import ical_to_dict
+
+config_dir = Path(appdirs.user_config_dir("task"))
+
+# Taskwarrior status to avoid
+AVOID_STATUS = ["completed", "deleted", "recurring"]
+
+long_range_time_map = {}
+
+
+# Get tasks from Taskwarrior and sort by urgency
+def get_tasks():
+    result = subprocess.run(["task", "export"], capture_output=True, text=True)
+    tasks = json.loads(result.stdout)
+    return sorted(
+        (task for task in tasks if "estimated" in task),
+        key=lambda t: -t.get("urgency", 0),
+    )
+
+
+def hours_to_decimal(hour):
+    return int(hour) + (hour - int(hour)) * 100 / 60
+
+
+def hours_to_time(hour):
+    hours = int(hour)
+    minutes = int((hour - hours) * 100)
+    return datetime.strptime(f"{hours}:{minutes}", "%H:%M").time()
+
+
+def time_to_decimal(time):
+    # round to 2 digits after the point
+    return time.hour + time.minute / 60
+
+
+def get_available_hours(time_map, date, calendars, verbose=False):
+    day_of_week = date.strftime("%A").lower()
+    schedule = time_map.get(day_of_week, [])
+    available_hours = sum(
+        hours_to_decimal(end) - hours_to_decimal(start) for start, end in schedule
+    )
+
+    blocked_hours = 0
+    for schedule_start, schedule_end in schedule:
+        # schedule_start and schedule_end are numbers, actually
+        # so let's convert them to datetime.time objects
+        schedule_start = hours_to_time(schedule_start)
+        schedule_end = hours_to_time(schedule_end)
+        schedule_blocked_hours = 0
+        for calendar in calendars:
+            for event in calendar:
+                # we use str to make object serializable as jsons
+                if isinstance(event["start"], str):
+                    event["start"] = datetime.fromisoformat(event["start"])
+                if isinstance(event["end"], str):
+                    event["end"] = datetime.fromisoformat(event["end"])
+
+                if event["start"].date() > date:
+                    break
+                elif event["end"].date() < date:
+                    continue
+
+                # check if the event overlaps with one of the working hours
+                event_start = event["start"].time()
+                event_end = event["end"].time()
+                if event["start"].date() < date:
+                    event_start = datetime(date.year, date.month, date.day, 0, 0).time()
+                if event["end"].date() > date:
+                    event_end = datetime(date.year, date.month, date.day, 23, 59).time()
+
+                if event_start < schedule_end and event_end > schedule_start:
+                    schedule_blocked_hours += time_to_decimal(
+                        min(schedule_end, event_end)
+                    ) - time_to_decimal(max(schedule_start, event_start))
+        if verbose and schedule_blocked_hours > 0:
+            print(
+                f"Blocked hours on {date} between {schedule_start} and {schedule_end}: {schedule_blocked_hours}"
+            )
+        blocked_hours += schedule_blocked_hours
+    available_hours -= blocked_hours
+    return available_hours
+
+
+def pdth_to_hours(duration_str):
+    # string format is P#DT#H
+    # with D and H optional
+    duration_str = duration_str[1:]  # Remove leading "P"
+    days, hours = 0, 0
+    if "D" in duration_str:
+        days, duration_str = duration_str.split("D")
+        days = int(days)
+    if "H" in duration_str:
+        hours = int(duration_str.split("T")[1].split("H")[0])
+    return days * 24 + hours
+
+
+def hours_to_pdth(hours):
+    days = hours // 24
+    hours = hours % 24
+    return f"P{days}DT{hours}H"
+
+
+def get_long_range_time_map(
+    time_maps, time_map_names, days_ahead, calendars, verbose=False
+):
+    key = ",".join(time_map_names)
+    if key in long_range_time_map:
+        task_time_map = long_range_time_map[key]
+    else:
+        if verbose:
+            print(f"Calculating long range time map for {key}")
+        task_time_map = []
+        for d in range(days_ahead):
+            date = datetime.today().date() + timedelta(days=d)
+            daily_hours = 0
+            for time_map_name in time_map_names:
+                if time_map_name not in time_maps:
+                    raise ValueError(f"Time map '{time_map_name}' does not exist.")
+                time_map = time_maps[time_map_name]
+                daily_hours += get_available_hours(time_map, date, calendars)
+            task_time_map.append(daily_hours)
+        long_range_time_map[key] = task_time_map
+
+    today_time = time_to_decimal(datetime.now().time())
+    today_weekday = datetime.today().strftime("%A").lower()
+    today_used_hours = 0
+    # compare with the time_maps of today
+    for time_map_name in time_map_names:
+        time_map = time_maps[time_map_name].get(today_weekday)
+        if time_map:
+            for schedule_start, schedule_end in time_map:
+                if schedule_start <= today_time <= schedule_end:
+                    today_used_hours += today_time - schedule_start
+                    break
+                elif today_time > schedule_end:
+                    today_used_hours += schedule_end - schedule_start
+    return task_time_map, today_used_hours
+
+
+def mark_end_date(
+    due_date, end_date, start_date, scheduling_note, id, description=None
+):
+    start_end_fields = [f"scheduled:{start_date}", f"completion_date:{end_date}"]
+
+    subprocess.run(
+        [
+            "task",
+            str(id),
+            "modify",
+            *start_end_fields,
+            f'scheduling:"{scheduling_note}"',
+        ],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    if due_date is not None and end_date > due_date:
+        # print in bold red using ANSI escape codes
+        description = "('" + description + "')" if description is not None else ""
+        print(f"\033[1;31mTask {id} {description} may not be completed on time\033[0m")
+
+
+def get_calendars(config, verbose=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"),
+        )
+        calendar.sort(key=lambda e: e["start"])
+        calendars.append(calendar)
+    if verbose:
+        print(f"Loaded {len(calendars)} calendars")
+    return calendars

taskcheck-0.2.0/taskcheck/install.py

@@ -0,0 +1,143 @@
+import subprocess
+from taskcheck.common import config_dir
+
+
+default_config = """
+[time_maps]
+[time_maps.work]
+monday = [[9, 12.30], [14, 17]]
+tuesday = [[9, 12.30], [14, 17]]
+wednesday = [[9, 12.30], [14, 17]]
+thursday = [[9, 12.30], [14, 17]]
+friday = [[9, 12.30], [14, 17]]
+
+[scheduler]
+algorithm = "parallel"
+days_ahead = 365
+"""
+
+
+def apply_config(key, value):
+    subprocess.run(["task", "config", key, value], stdout=subprocess.DEVNULL)
+
+
+def install():
+    """
+    Adds the required and optional settings explaining them to the user.
+    Also initialize the config file with some sane default.
+    """
+
+    # Define the required configurations
+    required_configs = [
+        ("uda.time_map.type", "string"),
+        ("uda.time_map.label", "Time Map"),
+        ("uda.time_map.default", "work"),
+        ("uda.estimated.type", "duration"),
+        ("uda.estimated.label", "Estimated Time"),
+        ("uda.completion_date.type", "date"),
+        ("uda.completion_date.label", "Expected Completion Date"),
+        ("uda.scheduling.type", "string"),
+        ("uda.scheduling.label", "Scheduling"),
+        ("uda.min_block.type", "numeric"),
+        ("uda.min_block.label", "Minimum Time Block"),
+        ("uda.min_block.default", "2"),
+        ("recurrence.confirmation", "no"),
+    ]
+
+    # Optional configurations
+    optional_configs = [
+        ("urgency.uda.estimated.PT1H.coefficient", "1"),
+        ("urgency.uda.estimated.PT2H.coefficient", "2.32"),
+        ("urgency.uda.estimated.PT3H.coefficient", "3.67"),
+        ("urgency.uda.estimated.PT4H.coefficient", "4.64"),
+        ("urgency.uda.estimated.PT5H.coefficient", "5.39"),
+        ("urgency.uda.estimated.PT6H.coefficient", "6.02"),
+        ("urgency.uda.estimated.PT7H.coefficient", "6.56"),
+        ("urgency.uda.estimated.PT8H.coefficient", "7.03"),
+        ("urgency.uda.estimated.PT9H.coefficient", "7.45"),
+        ("urgency.uda.estimated.PT10H.coefficient", "7.82"),
+        ("urgency.uda.estimated.PT11H.coefficient", "8.16"),
+        ("urgency.uda.estimated.PT12H.coefficient", "8.47"),
+        ("urgency.uda.estimated.PT13H.coefficient", "8.75"),
+        ("urgency.uda.estimated.PT14H.coefficient", "9.01"),
+        ("urgency.uda.estimated.PT15H.coefficient", "9.25"),
+        ("urgency.uda.estimated.PT16H.coefficient", "9.47"),
+        ("urgency.uda.estimated.PT17H.coefficient", "9.68"),
+        ("urgency.uda.estimated.PT18H.coefficient", "9.87"),
+        ("urgency.uda.estimated.PT19H.coefficient", "10.05"),
+        ("urgency.uda.estimated.PT20H.coefficient", "10.22"),
+        ("urgency.uda.estimated.PT21H.coefficient", "10.38"),
+        ("urgency.uda.estimated.PT22H.coefficient", "10.53"),
+        ("urgency.uda.estimated.PT23H.coefficient", "10.67"),
+        ("urgency.uda.estimated.PT24H.coefficient", "10.80"),
+        ("urgency.uda.estimated.PT25H.coefficient", "10.93"),
+        ("urgency.uda.estimated.PT26H.coefficient", "11.05"),
+        ("urgency.uda.estimated.PT27H.coefficient", "11.16"),
+        ("urgency.uda.estimated.PT28H.coefficient", "11.27"),
+        ("urgency.uda.estimated.PT29H.coefficient", "11.37"),
+        ("urgency.uda.estimated.PT30H.coefficient", "11.47"),
+        ("urgency.uda.estimated.PT31H.coefficient", "11.56"),
+        ("urgency.uda.estimated.PT32H.coefficient", "11.65"),
+        ("urgency.uda.estimated.PT33H.coefficient", "11.73"),
+        ("urgency.uda.estimated.PT34H.coefficient", "11.81"),
+        ("urgency.uda.estimated.PT35H.coefficient", "11.89"),
+        ("urgency.uda.estimated.PT36H.coefficient", "11.96"),
+        (
+            "report.ready.columns",
+            "id,start.age,entry.age,depends.indicator,priority,project,tags,recur.indicator,scheduled.relative,due.relative,until.remaining,description,urgency",
+        ),
+        ("journal.info", "0"),
+        ("urgency.inherit", "1"),
+    ]
+
+    answer = input(
+        """Required configuration for taskcheck includes:
+- 3 UDA fields 
+- turning off confirmation for recurring tasks 
+
+Do you want to continue? [y/N]"""
+    )
+    if answer.lower() not in ["y", "yes"]:
+        return
+
+    answer = input(
+        """Optional configuration for taskcheck includes:
+- urgency coefficients for estimated time (up to 36 hour duration)
+- better `ready` report columns
+- turning off printing journal logs in the task details
+- turning on urgency inheritance from dependant tasks 
+
+Do you want to apply optional configurations? [y/N]"""
+    )
+    if answer.lower() not in ["y", "yes"]:
+        configs = required_configs
+    else:
+        configs = required_configs + optional_configs
+
+    # Apply configurations using apply_config
+    try:
+        for key, value in configs:
+            apply_config(key, value)
+        print("Taskwarrior configurations have been applied successfully.")
+    except Exception as e:
+        print(f"Failed to apply configurations: {e}")
+
+    answer = input(
+        """Do you want to create a default config file for taskcheck? [y/N]"""
+    )
+    if answer.lower() not in ["y", "yes"]:
+        return
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_file = config_dir / "taskcheck.toml"
+    if config_file.exists():
+        print(f"Config file already exists at {config_file}")
+        return
+    with open(config_file, "w") as f:
+        f.write(default_config)
+
+    print(f"Default config file created at {config_file}")
+
+
+if __name__ == "__main__":
+    install()