jps-effort-tracker-utils 0.5.0

A command-line task and effort tracking utility for managing daily tasks with priorities, effort estimates, and status tracking.

jps-effort-tracker-utils

A command-line task and effort tracking utility for managing daily tasks with priorities, effort estimates, and status tracking.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage
  • Add Task
  • View Tasks
  • Delete Task
  • Update Task
• Task Properties
• Configuration
• Development
• Testing
• Contributing
• License

Overview

jps-effort-tracker-utils is a Python package that provides command-line tools for tracking tasks and effort. It helps you organize your daily work by managing tasks with detailed attributes including priority levels, effort estimates, due dates, status tracking, and integration with issue trackers.

Tasks are stored in YAML files organized by date, making it easy to track your work history and transfer incomplete tasks between days automatically.

Features

✅ Task Management: Add, view, delete, and update tasks via simple CLI commands

✅ Rich Task Attributes:

• Task ID (auto-generated timestamps)
• Title and description
• Priority levels (1-5)
• Due dates
• Status tracking (pending, in-progress, completed, deleted, not started)
• Effort estimates (in minutes)
• Level of effort categories (Easy, Medium, Hard, Complex)
• Issue tracker integration
• Issue types (enhancement, bugfix, documentation, etc.)

✅ Smart Features:

• Automatic transfer of incomplete tasks to the next day
• Date-based task file organization
• Colored console output for better readability
• YAML-based storage for easy inspection and editing
• Configurable task storage directory

✅ Developer-Friendly:

• Comprehensive test suite (65+ tests)
• Type hints throughout
• Rich console output
• Detailed logging

Installation

For detailed installation instructions, see INSTALL.md.

Quick Install

pip install jps-effort-tracker-utils

From Source

git clone https://github.com/jai-python3/effort-tracker-utils.git
cd effort-tracker-utils
pip install -e .

Quick Start

# Add a new task
add-task

# View tasks for today
view-tasks

# Delete a task
delete-task

# Update a task (if implemented)
update-task

Usage

Add Task

Interactively add a new task with all properties:

add-task

With options:

add-task --config_file /path/to/config.yaml --verbose

Options:

• --config_file: Configuration file path (default: built-in config)
• --task_file: Specific task file to use (default: today's file)
• --logfile: Log file path
• --outdir: Output directory for logs
• --verbose: Enable verbose output

View Tasks

View and browse your tasks:

view-tasks

Select a task number to view full details, or quit to exit.

Delete Task

Remove a task from the list:

delete-task

Select the task number you want to delete.

Update Task

Update an existing task (if implemented):

update-task

Task Properties

Each task includes:

Property	Type	Description
task_id	string	Auto-generated timestamp ID (YYYY.MM.DD.HH.MM.SS)
title	string	Short task title
description	string	Detailed task description
priority	int	Priority level (1-5)
due_date	datetime	When the task is due
date_created	datetime	When the task was created
status	string	Current status (pending, in-progress, completed, etc.)
completed	bool	Whether the task is completed
issue_tracker_id	string	External issue tracker reference
issue_type	string	Type of work (enhancement, bugfix, etc.)
effort_estimate	int	Estimated duration in minutes
level_of_effort	string	Complexity category (Easy, Medium, Hard, Complex)

Configuration

Default configuration is stored at src/jps_effort_tracker_utils/conf/config.yaml. You can provide a custom configuration:

tasks_dir: /path/to/your/tasks

By default, tasks are stored in: ~/effort-tracker-utils/tasks/

Each day gets its own YAML file: YYYY-MM-DD.yaml

Development

Setup Development Environment

git clone https://github.com/jai-python3/effort-tracker-utils.git
cd effort-tracker-utils
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Code Quality Tools

The project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking
• pylint for additional linting
• pytest for testing

# Format code
black src tests

# Sort imports
isort src tests

# Run linters
flake8 src
mypy src

# Run tests
pytest tests/

Testing

The project has a comprehensive test suite with 65+ tests covering:

• Console helper functions
• Constants and configuration
• File utilities (MD5, file validation, binary detection)
• System command execution
• Task manager and Task model
• Package metadata

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/jps_effort_tracker_utils --cov-report=term-missing

# Run specific test file
pytest tests/test_manager.py -v

Current Coverage: ~42% overall, with 100% coverage on utility modules

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linters
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.