taskpulse-24 0.1.0__py3-none-any.whl

taskpulse/__init__.py

@@ -0,0 +1,8 @@
+"""TaskPulse: turn a task list into a practical daily plan."""
+
+from .models import Priority, Task
+from .planner import prioritize, schedule
+
+__all__ = ["Priority", "Task", "prioritize", "schedule"]
+__version__ = "0.1.0"
+

taskpulse/cli.py

@@ -0,0 +1,51 @@
+"""Command-line interface for quick planning from CSV input."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+from datetime import date
+from pathlib import Path
+
+from .models import Priority, Task
+from .planner import schedule
+
+
+def _read_tasks(path: Path) -> list[Task]:
+    with path.open(newline="", encoding="utf-8") as source:
+        rows = csv.DictReader(source)
+        required = {"title", "minutes", "priority"}
+        if not required.issubset(rows.fieldnames or set()):
+            raise ValueError("CSV must contain title, minutes, and priority columns")
+        tasks = []
+        for row in rows:
+            due = date.fromisoformat(row["due"]) if row.get("due") else None
+            tasks.append(
+                Task(
+                    title=row["title"],
+                    minutes=int(row["minutes"]),
+                    priority=Priority(int(row["priority"])),
+                    due=due,
+                )
+            )
+    return tasks
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build a focused task schedule.")
+    parser.add_argument("csv_file", type=Path, help="CSV with title, minutes, priority, due")
+    parser.add_argument("--daily-minutes", type=int, default=120)
+    args = parser.parse_args()
+
+    for day, tasks in schedule(
+        _read_tasks(args.csv_file),
+        daily_minutes=args.daily_minutes,
+    ).items():
+        print(day.isoformat())
+        for task in tasks:
+            print(f"  - {task.title} ({task.minutes} min, priority {task.priority.name})")
+
+
+if __name__ == "__main__":
+    main()
+

taskpulse/models.py

@@ -0,0 +1,41 @@
+"""Public data models for TaskPulse."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from enum import IntEnum
+
+
+class Priority(IntEnum):
+    """User-facing priority levels."""
+
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    """A task that can be ranked and scheduled.
+
+    Args:
+        title: Short, human-readable task name.
+        minutes: Expected focused work time; must be positive.
+        priority: Importance from 1 (low) to 3 (high).
+        due: Optional due date. Earlier dates receive more urgency.
+    """
+
+    title: str
+    minutes: int
+    priority: Priority = Priority.MEDIUM
+    due: date | None = None
+
+    def __post_init__(self) -> None:
+        if not self.title.strip():
+            raise ValueError("title must not be empty")
+        if self.minutes <= 0:
+            raise ValueError("minutes must be greater than zero")
+        if not isinstance(self.priority, Priority):
+            raise TypeError("priority must be a Priority value")
+

taskpulse/planner.py

@@ -0,0 +1,50 @@
+"""Task ranking and schedule generation."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+
+from .models import Task
+
+
+def _score(task: Task, today: date) -> tuple[int, int, int]:
+    """Return a sortable score; larger values represent more urgency."""
+    due_score = 0 if task.due is None else max(0, 30 - (task.due - today).days)
+    return (int(task.priority) * 100 + due_score, -task.minutes, -len(task.title))
+
+
+def prioritize(tasks: list[Task], *, today: date | None = None) -> list[Task]:
+    """Return tasks from most to least urgent without mutating the input."""
+    reference = today or datetime.now().astimezone().date()
+    return sorted(tasks, key=lambda task: _score(task, reference), reverse=True)
+
+
+def schedule(
+    tasks: list[Task],
+    *,
+    daily_minutes: int,
+    start: date | None = None,
+) -> dict[date, list[Task]]:
+    """Pack prioritized tasks into consecutive workdays.
+
+    A task is never split. If one task exceeds ``daily_minutes``, it receives
+    a day of its own so the function always makes progress.
+    """
+    if daily_minutes <= 0:
+        raise ValueError("daily_minutes must be greater than zero")
+
+    start_date = start or datetime.now().astimezone().date()
+    result: dict[date, list[Task]] = {}
+    remaining = daily_minutes
+    day = start_date
+
+    for task in prioritize(tasks, today=start_date):
+        if result.get(day) and task.minutes > remaining:
+            day += timedelta(days=1)
+            remaining = daily_minutes
+        result.setdefault(day, []).append(task)
+        remaining -= task.minutes
+        if remaining <= 0:
+            day += timedelta(days=1)
+            remaining = daily_minutes
+    return result

taskpulse_24-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: taskpulse-24
+Version: 0.1.0
+Summary: A small, dependency-free task prioritizer and daily planner.
+Author: TaskPulse contributors
+License: MIT License
+        
+        Copyright (c) 2026 TaskPulse contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        
+Project-URL: Homepage, https://github.com/OttoHui/taskpulse
+Project-URL: Repository, https://github.com/OttoHui/taskpulse
+Project-URL: Documentation, https://github.com/OttoHui/taskpulse#readme
+Keywords: productivity,planning,tasks,scheduling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# TaskPulse
+
+TaskPulse is a small, dependency-free Python package that turns a task list
+into a focused daily plan. It is designed for students and small project teams
+who want transparent prioritization without sending personal data to a service.
+
+## Project team
+
+**Group 24 (6/6 members)**
+
+- Tsz Hei CHUI
+- Fong Kwan HUI
+- David KWONG
+- Sik Man LAM
+- Hong Shing WONG
+- Chun Hin YIU
+
+## Why it exists
+
+Most task apps either require a hosted account or hide prioritization behind a
+complex interface. TaskPulse keeps the algorithm inspectable:
+
+1. importance is explicit (`LOW`, `MEDIUM`, or `HIGH`);
+2. approaching due dates add urgency;
+3. shorter tasks win ties, making plans easier to finish;
+4. tasks are packed into days without splitting a task across sessions.
+
+The result is useful for study plans, sprint preparation, and a one-minute
+project demonstration.
+
+## Install
+
+```bash
+pip install taskpulse-24
+```
+
+For local development:
+
+```bash
+git clone https://github.com/OttoHui/taskpulse.git
+cd taskpulse
+pip install -e ".[dev]"  # or: pip install -e .
+pytest
+```
+
+## Python API
+
+```python
+from datetime import date
+from taskpulse import Priority, Task, schedule
+
+tasks = [
+    Task("Write project abstract", 45, Priority.HIGH, date(2026, 10, 10)),
+    Task("Review references", 30, Priority.MEDIUM),
+]
+
+plan = schedule(tasks, daily_minutes=60, start=date(2026, 10, 7))
+for day, items in plan.items():
+    print(day, [item.title for item in items])
+```
+
+## Command line
+
+Create `tasks.csv`:
+
+```csv
+title,minutes,priority,due
+Write project abstract,45,3,2026-10-10
+Review references,30,2,
+```
+
+Then run:
+
+```bash
+taskpulse tasks.csv --daily-minutes 60
+```
+
+## Project and collaboration
+
+Suggested team split for Group 24:
+
+- **Tsz Hei CHUI:** project coordination, requirements, and final integration.
+- **Fong Kwan HUI:** core models, prioritization, and scheduling logic.
+- **David KWONG:** command-line interface and user experience.
+- **Sik Man LAM:** tests, edge cases, and quality checks.
+- **Hong Shing WONG:** documentation, examples, and PyPI metadata.
+- **Chun Hin YIU:** demo, presentation wiki, and release verification.
+
+Make small commits by feature and review each other's pull requests. The
+published distribution is named `taskpulse-24`; its import name remains
+`taskpulse`.
+
+## One-minute demonstration
+
+1. Show the two-row CSV (10 seconds).
+2. Run `taskpulse tasks.csv --daily-minutes 60` (15 seconds).
+3. Explain that priority and due date determine order, while capacity determines
+   the day (20 seconds).
+4. Show the equivalent Python API and mention that no external service or
+   dependency is required (15 seconds).
+
+## Roadmap
+
+- optional weekend skipping;
+- JSON input/output;
+- calendar export;
+- configurable scoring strategies.

taskpulse_24-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+taskpulse/__init__.py,sha256=pqMkZ2VhM76IVkdqX6HelgF78veo2DKXWOmFtFYtTjc,222
+taskpulse/cli.py,sha256=PlV3mIOak2DMcCZTFWYONdki8FddP8uD8AvOtU4WChE,1595
+taskpulse/models.py,sha256=83TR0Iig8LzkoBxwHEC7BkOcd8lRq0qVpJs41jOxo3w,1065
+taskpulse/planner.py,sha256=Sl_ctNFO-Lq9IBlMseY6MTnQp9EJGFmGvM7w5QylfLg,1722
+taskpulse_24-0.1.0.dist-info/licenses/LICENSE,sha256=jweqFtKfuouBWmwQ4nfklb9PZkUSScQ5amnvQvRSiz0,1080
+taskpulse_24-0.1.0.dist-info/METADATA,sha256=gEVqs8XafUBY26hTuTJC_AcJ0hYWxPBfFjVONaMaqrs,4934
+taskpulse_24-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+taskpulse_24-0.1.0.dist-info/entry_points.txt,sha256=dPyNr4a6m5jIak-Fs84CHUGhge-qdCOKTOaXXTwBkUI,49
+taskpulse_24-0.1.0.dist-info/top_level.txt,sha256=QONlJ8x0qyDyaGCiNuEg4IBDtm68HD3GLCQ98RCuxKE,10
+taskpulse_24-0.1.0.dist-info/RECORD,,

taskpulse_24-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taskpulse_24-0.1.0.dist-info/entry_points.txt

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

taskpulse_24-0.1.0.dist-info/licenses/LICENSE

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

taskpulse_24-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+taskpulse