Metadata-Version: 2.4
Name: jps-effort-tracker-utils
Version: 0.5.0
Summary: A command-line task and effort tracking utility for managing daily tasks with priorities, effort estimates, and status tracking.
Author-email: Jaideep Sundaram <jai.python3@gmail.com>
Project-URL: Homepage, https://github.com/jai-python3/jps-effort-tracker-utils
Project-URL: Repository, https://github.com/jai-python3/jps-effort-tracker-utils
Project-URL: Issues, https://github.com/jai-python3/jps-effort-tracker-utils/issues
Keywords: jps_effort_tracker_utils
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: colorama
Requires-Dist: Pydantic
Requires-Dist: PyYAML
Requires-Dist: Rich
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: coverage>=4.5.4; extra == "dev"
Requires-Dist: tox>=3.14.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: deadcode; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pydocstyle; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: rm_unneeded_f_str; extra == "dev"
Requires-Dist: vulture; extra == "dev"
Requires-Dist: bump-my-version>=1.0.1; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: watchdog; extra == "dev"
Requires-Dist: Sphinx; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: git-changelog>=2.0.0; extra == "dev"

# jps-effort-tracker-utils

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

[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Add Task](#add-task)
  - [View Tasks](#view-tasks)
  - [Delete Task](#delete-task)
  - [Update Task](#update-task)
- [Task Properties](#task-properties)
- [Configuration](#configuration)
- [Development](#development)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#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](docs/INSTALL.md).

### Quick Install

```bash
pip install jps-effort-tracker-utils
```

### From Source

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

## Quick Start

```bash
# 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:

```bash
add-task
```

With options:

```bash
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:

```bash
view-tasks
```

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

### Delete Task

Remove a task from the list:

```bash
delete-task
```

Select the task number you want to delete.

### Update Task

Update an existing task (if implemented):

```bash
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:

```yaml
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

```bash
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

```bash
# 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

```bash
# 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.
