TaskFlow

A command-line task manager built in Python to practice and demonstrate modern backend fundamentals: clean OOP design, full type hints, structural typing with Protocol, and async I/O — all wired together in a small, real, working tool.

$ python -m taskflow add "Ship TaskFlow" --priority high --motivate
Added: [ ] (high) Ship TaskFlow

"The only way to do great work is to love what you do." — Steve Jobs

$ python -m taskflow list
[ ] (high) Ship TaskFlow
[x] (medium) Buy milk

Features

• Add, complete, and list tasks, each with a priority level (low / medium / high)
• Pluggable storage — a TaskStorage Protocol defines the storage contract; the included JSONFileStorage backend satisfies it with zero inheritance, so a database or in-memory backend can be swapped in later without touching TaskManager
• Optional async enrichment — --motivate fetches a short quote from a public API while the task is being added, using httpx and asyncio
• Graceful degradation — if the network call fails or times out, the task is still saved; a non-critical feature never crashes a critical one

Why this project exists

This is the capstone exercise for Phase 1 of a backend developer learning roadmap, built to move past reading about Python fundamentals into using them under real constraints — including the debugging that comes with running real projects (package structure, imports, empty files, network timeouts).

Tech stack

Concern	Tool
Language	Python 3.11+
Data modeling	dataclasses, enum.Enum
Structural typing	typing.Protocol
CLI parsing	argparse
Async HTTP	httpx.AsyncClient
Concurrency	asyncio
Storage	JSON file (swappable via Protocol)

Project structure

taskflow/
├── __init__.py
├── __main__.py      # entry point for `python -m taskflow`
├── models.py         # Task, Priority
├── storage.py         # TaskStorage Protocol + JSONFileStorage
├── manager.py         # TaskManager — business logic
└── cli.py             # argparse commands + async quote fetch

Setup

git clone https://github.com/Mohammadalijafari/taskflow.git
cd taskflow
python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install httpx

Usage

# Add a task
python -m taskflow add "Buy milk" --priority high

# Add a task and fetch a motivational quote asynchronously
python -m taskflow add "Ship feature" --motivate

# List all tasks (incomplete first)
python -m taskflow list

# Mark a task complete (exact title match)
python -m taskflow complete "Buy milk"

Design notes

• TaskManager depends on TaskStorage, not JSONFileStorage directly. Because TaskStorage is a Protocol rather than an abstract base class, any object with matching load() / save() methods satisfies it — no inheritance, no registration. This is structural typing: the shape of the object is the contract.
• @dataclass with field(default_factory=...) generates Task's constructor and equality checks for free, while correctly giving every instance its own UUID and timestamp rather than sharing one across all instances.
• The async quote fetch is wrapped in error handling so that a slow or unreachable network never prevents a task from being saved — the core feature (saving a task) is never allowed to fail because of an optional one (fetching a quote).

Possible next steps

• Swap JSONFileStorage for a SQLite or PostgreSQL-backed implementation of TaskStorage
• Add pytest coverage for TaskManager and both storage paths
• Package as an installable CLI with pipx / setup.py entry points

License

MIT