todonotifier

  1"""
  2TODO Notifier - Automated TODO tracking and notifications for your codebase
  3
  4Never forget a TODO again! Automatically parse, track, and get notified about TODO items
  5in your code.
  6
  7## Features
  8
  9- **Smart TODO Detection** - Automatically discovers TODO items across your entire
 10  codebase
 11- **Date-based Tracking** - Set completion dates and get notified about overdue items
 12- **User Assignment** - Assign TODOs to specific team members
 13- **Multiple Report Types** - Module-wise, user-wise, and deadline-based summaries
 14- **Email Notifications** - Automated email reports with HTML formatting
 15- **Flexible Configuration** - Extensive customization options for different workflows
 16- **Multiple Integration Methods** - Works with Git repositories, local directories, or
 17  single files
 18- **Export Options** - Save reports as HTML files for sharing and archiving
 19
 20## Quick Start
 21
 22```python
 23from todonotifier.config import DefaultConfig
 24from todonotifier.connect import ConnectMethod, Connect
 25from todonotifier.driver import run as driver_run
 26
 27# Configure for a Git repository
 28git_url = "https://github.com/your-username/your-repo.git"
 29project_name = "your-project"
 30
 31connect = Connect(
 32    connect_method=ConnectMethod.GIT_CLONE,
 33    project_dir_name=project_name,
 34    url=git_url,
 35    branch_name="main"
 36)
 37
 38config = DefaultConfig(
 39    save_html_reports=True,
 40    ignore_todo_case=True
 41)
 42
 43# Generate TODO reports
 44driver_run(connect=connect, config=config)
 45```
 46
 47## TODO Format
 48
 49TODO Notifier supports a flexible format for TODO items:
 50
 51```python
 52# Full format with all components
 53# TODO {2024-12-31} @john_doe Implement user authentication
 54
 55# Date only
 56# TODO {2024-12-31} Add error handling
 57
 58# User only
 59# TODO @jane_smith Review this logic
 60
 61# Simple TODO
 62# TODO Fix this bug
 63```
 64
 65**Format Components:**
 66- `TODO` - The keyword (case-insensitive option available)
 67- `{YYYY-MM-DD}` - Optional completion date
 68- `@username` - Optional assignee
 69- `message` - Optional description
 70
 71## Architecture
 72
 73The system consists of several key components:
 74
 75- **todo_notifier.py** - Main parsing logic that extracts TODO items using regex
 76  patterns
 77- **models.py** - Core data models (`TODO`, `USER`, `POSITION`) with date parsing and
 78  validation
 79- **config.py** - Configuration system with `BaseConfig` and `DefaultConfig` classes
 80- **driver.py** - Main orchestration layer that coordinates parsing, summary generation,
 81  and notifications
 82- **connect.py** - Repository connection handlers for git repos, local directories, and
 83  files
 84- **summary_generators.py** - Pluggable summary generators (by module, expired TODOs,
 85  upcoming TODOs)
 86- **notifier.py** - Notification system with email support and extensible base classes
 87
 88## Generated Reports
 89
 90TODO Notifier generates three types of reports by default:
 91
 921. **Module-wise Summary** - Lists all TODO items organized by file/module
 932. **Expired TODOs by User** - Highlights overdue TODO items assigned to each team
 94   member
 953. **Upcoming Week TODOs** - Shows TODO items due within the next 7 days
 96
 97All reports can be saved as HTML files and/or sent via email notifications.
 98
 99## Installation
100
101```bash
102pip install todonotifier
103```
104
105For more examples and advanced usage, see the individual module documentation.
106"""