Automated TODO tracking and notifications for your codebase
Never forget a TODO again! Automatically parse, track, and get notified about TODO items in your code.
Installation • Quick Start • Documentation • Contributing
- Smart TODO Detection - Automatically discovers TODO items across your entire codebase
- Date-based Tracking - Set completion dates and get notified about overdue items
- User Assignment - Assign TODOs to specific team members
- Multiple Report Types - Module-wise, user-wise, and deadline-based summaries
- Email Notifications - Automated email reports with HTML formatting
- Flexible Configuration - Extensive customization options for different workflows
- Multiple Integration Methods - Works with Git repositories, local directories, or single files
- Export Options - Save reports as HTML files for sharing and archiving
pip install todonotifierfrom todonotifier.config import DefaultConfig
from todonotifier.connect import ConnectMethod, Connect
from todonotifier.driver import run as driver_run
# Configure for a Git repository
git_url = "https://github.com/your-username/your-repo.git"
# Suggested to keep same as project name
project_name = "your-project"
connect = Connect(
connect_method=ConnectMethod.GIT_CLONE,
project_dir_name=project_name,
url=git_url,
branch_name="main"
)
config = DefaultConfig(
save_html_reports=True,
ignore_todo_case=True
)
# Generate TODO reports
# It will generate 3 files by default in folder .report under the current working directory.
driver_run(connect=connect, config=config)from todonotifier.notifier import EmailNotifier
# Set up email notifications
notifier = EmailNotifier(
sender_email="your-email@gmail.com",
password="your-app-password",
host="smtp.gmail.com",
port=465,
receivers=["team@company.com"]
)
config = DefaultConfig(
save_html_reports=True,
ignore_todo_case=True,
notifier=notifier
)from todonotifier.config import DefaultConfig
from todonotifier.connect import ConnectMethod, Connect
from todonotifier.driver import run as driver_run
# Scan a local project directory
connect = Connect(
connect_method=ConnectMethod.DRY_RUN_DIR,
project_dir_name="my-project",
url="/path/to/your/project"
)
driver_run(connect=connect, config=DefaultConfig())from todonotifier.connect import ConnectMethod, Connect
# Analyze a single file
connect = Connect(
connect_method=ConnectMethod.DRY_RUN_FILE,
project_dir_name="single-file",
url="/path/to/your/file.py"
)from todonotifier.config import DefaultConfig
# Import it from where it's implemented
from my_summary import CustomSummaryGenerator
config = DefaultConfig(
# Exclude specific directories
exclude_dirs={"regex": [r".*/__pycache__/.*", r".*/\.git/.*"]},
# Exclude specific files
exclude_files={"regex": [r".*\.pyc$", r".*\.log$"]},
# Custom settings
ignore_todo_case=True,
save_html_reports=True,
generate_html=True,
# Add custom summary generators
summary_generators=[CustomSummaryGenerator()],
flag_default_summary_generators=True
)TODO Notifier generates three types of reports as .html files by default if
save_html_reports=True was set in configuration. All reports generated are stored in
the .report directory in the current working directory.
Lists all TODO items organized by file/module for easy code navigation.
Highlights overdue TODO items assigned to each team member.
Shows TODO items due within the next 7 days.
# After running driver_run(), access the generated data
summary_generators = config.summary_generators
for generator in summary_generators:
print(f"Report: {generator.name}")
print(f"HTML: {generator.html}")
print(f"Data: {generator.container}")- HTML Files: Saved to
.report/directory whensave_html_reports=True - Email: Automatically sent when
notifieris configured - Programmatic Access: Available through summary generator objects
TODO Notifier supports a flexible format for TODO items in your code:
# Full format with all components
# TODO {2024-12-31} @john_doe Implement user authentication
# Date only
# TODO {2024-12-31} Add error handling
# User only
# TODO @jane_smith Review this logic
# Simple TODO
# TODO Fix this bugFormat Components:
TODO- The keyword (case-insensitive option available){YYYY-MM-DD}- Optional completion date@username- Optional assigneemessage- Optional description
Supported Languages: Works with any programming language that supports comments (Python, JavaScript, Java, C++, etc.)
- Repository Access: Safely clones/accesses your repository in a temporary location
- File Scanning: Recursively scans all files for TODO patterns using regex
- Data Processing: Parses TODO items extracting dates, assignees, and messages
- Report Generation: Creates customizable HTML reports and data structures
- Notifications: Sends email notifications with formatted reports
- Connect Layer: Handles different source types (Git, local directory, single file)
- Configuration System: Flexible settings for scanning, filtering, and reporting
- Summary Generators: Pluggable report generators with HTML output
- Notification System: Extensible notification framework (Email included)
Users can write their own summary generators and add pass the same in variable
summary_generators in configuration. Each summary generator is a child of
BaseSummaryGenerator in summary_generators.py.
from todonotifier.summary_generators import BaseSummaryGenerator
from todonotifier.models import TODO
class CustomGenerator(BaseSummaryGenerator):
def __init__(self):
super().__init__("Custom Summary", {})
def generate_summary(self, all_todos_objs: dict[str, list[TODO]]):
# Your custom logic here
pass
def generate_html(self):
# Generate HTML representation
passfrom todonotifier.notifier import BaseNotifier
class SlackNotifier(BaseNotifier):
def notify(self, summary):
# Send to Slack webhook
passTODO Notifier allows excluding specific folders of the project via absolute address,
relative address or regular expression from being scanned. It has a default list of
folders that are not scanned: DEFAULT_EXCLUDE_DIRS in constants.py. But the same can
be controlled using the flag flag_default_exclude_dirs in configuration.
It also allows excluding specific files of the project via absolute address, relative
address or regular expression from being scanned. It has a default list of files that
are not scanned: DEFAULT_EXCLUDE_FILES in constants.py. But the same can be
controlled using the flag flag_default_exclude_files in configuration.
from todonotifier.config import DefaultConfig
config = DefaultConfig(
exclude_dirs={
"absolute": ["/path/to/exclude"],
"relative": ["node_modules", ".git"],
"regex": [r".*__pycache__.*"]
},
exclude_files={
"regex": [r".*\.pyc$", r".*\.log$"]
}
)Most of the features are configurable while instantiating configuration class. But users
are free to write another configuration class or simply inherit from DefaultConfig.
However, configuration class should be a child of BaseConfig in
todonotifier/config.py.
from todonotifier.config import BaseConfig
class CustomConfig(BaseConfig):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
# Further Custom configuration codeWe welcome contributions! Here's how you can help:
# Clone the repository
git clone https://github.com/ashu-tosh-kumar/todo_notifier.git
cd todo_notifier
# Setup a virtual environment
pyenv virtualenv 3.9 todonotifier
# Install dependencies
pip install poetry # not limited poetry version as of now
poetry install --with dev
# Set pre-commit hook
pre-commit install
# Run tests
pytest tests- Bug Reports: Open an issue with details and reproduction steps
- Feature Requests: Suggest new features or improvements
- Documentation: Improve docs, examples, or tutorials
- Code: Submit pull requests for bug fixes or features
- Follow the existing code style (Black, isort, flake8)
- Add tests for new functionality
- Update documentation for new features
- Keep commits focused and descriptive
This project is licensed under the MIT License - see the LICENSE file for details.
- Breaking Change: Renamed
CONNECT_METHODin intodonotifier.connecttoConnectMethod. - Added accessibility captions to HTML reports
- Security improvements and package upgrades
- Code quality improvements
- Updated minimum Python version to 3.9+
- Migrated from setup.py to Poetry
- Package dependency updates
- Critical bug fixes (recommended minimum version)
Unfortunately, didn't maintain that.
Made with ❤️ for developers who care about their TODOs