Metadata-Version: 2.4
Name: schedulr
Version: 0.0.3
Summary: A smart terminal scheduler with natural language input and ASCII calendar visualization.
Author-email: madushnaka rajapakshe <your@email.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: rich
Requires-Dist: typer
Requires-Dist: dateparser
Requires-Dist: schedule
Requires-Dist: plyer
Requires-Dist: pystray
Requires-Dist: Pillow

# Schedulr - Smart Terminal Task Scheduler

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform: Windows](https://img.shields.io/badge/Platform-Windows-lightgrey.svg)]()

> A beautiful, feature-rich terminal-based task scheduler with natural language input, calendar visualization, system tray integration, and desktop notifications.

## Features

### Core Functionality
- **Natural Language Input**: Create tasks using human-friendly date/time expressions
- **Beautiful Terminal Interface**: Rich, colorful TUI built with Textual framework
- **SQLite Database**: Persistent storage for all your tasks
- **Calendar View**: Visual monthly calendar with task indicators
- **Search & Filter**: Quickly find tasks by title
- **Task Statistics**: Overview of pending, completed, and recurring tasks

### Advanced Features
- **System Tray Integration**: Run in background with tray icon
- **Desktop Notifications**: Get notified when tasks are due
- **Auto-start Support**: Automatically launch on Windows startup
- **Settings Management**: Customizable preferences and themes
- **Responsive Design**: Adaptive layout for different terminal sizes

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Command Line Options](#command-line-options)
- [Configuration](#configuration)
- [Task Management](#task-management)
- [Calendar View](#calendar-view)
- [Settings](#settings)
- [System Tray Mode](#system-tray-mode)
- [Auto-start Setup](#auto-start-setup)
- [Development](#development)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Installation

### Prerequisites

- Python 3.8 or higher
- Windows operating system
- Terminal with color support (recommended)

### Install from PyPI (Recommended)

```bash
pip install schedulr
```

### Install from Source

```bash
# Clone the repository
git clone https://github.com/MadushankaRajapaksha/-Schedulr- 
cd schedulr

# Install in development mode
pip install -e .
```

### Verify Installation

```bash
schedulr --help
```

## Quick Start

### Launch the Application

```bash
# Launch the main interface
schedulr

# Or run as Python module
python -m schedulr
```

### Create Your First Task

1. Launch Schedulr
2. Click the **➕ Add Task** button or press the navigation button
3. Fill in the task details:
   - **Task Title**: What needs to be done
   - **Date**: When it should happen (YYYY-MM-DD format)
   - **Time**: Hour, minute, and AM/PM
4. Click **✅ Save Task**

### Example: Add a Meeting Task

```
📝 Task Title: Team Meeting
📅 Date: 2024-01-15
⏰ Hour: 14
⏰ Minute: 30
🕐 Time Format: PM
```

## Usage

### Basic Navigation

- **🏠 Home**: View all tasks with search and statistics
- **➕ Add Task**: Create new tasks with the modal form
- **📅 Calendar**: Monthly calendar view with task indicators
- **⚙️ Settings**: Configure application preferences

### Keyboard Shortcuts

- **Tab**: Navigate between interface elements
- **Enter**: Activate buttons and submit forms
- **Escape**: Close modals or go back
- **Arrow Keys**: Navigate in calendar view

### Search Functionality

Use the search bar in the Home view to filter tasks by title:

```bash
Search by task title: meeting
```

Shows all tasks containing "meeting" in their title.

## Command Line Options

```bash
# Show help information
schedulr --help

# Run in system tray mode (recommended for notifications)
schedulr --tray

# Manage auto-start on Windows
schedulr --autostart add     # Enable auto-start
schedulr --autostart remove  # Disable auto-start
schedulr --autostart check   # Check auto-start status
```

### System Tray Mode

```bash
# Start in background with notifications
schedulr --tray
```

Features in tray mode:
- Application runs in background
- Desktop notifications for due tasks
- System tray icon for quick access
- Right-click menu for basic controls

## Configuration

### Settings Options

Access settings through the ⚙️ button in the Calendar view:

#### Notification Settings
- **Enable Notifications**: Desktop alerts for due tasks
- **Default Reminder Time**: Minutes before due time to notify
- **Sound Notifications**: Audio alerts (when supported)

#### Display Settings
- **Theme**: Light, dark, or auto theme selection
- **Time Format**: 12-hour or 24-hour format
- **Week Start**: Monday or Sunday as week start
- **Show Completed Tasks**: Display finished tasks in lists

#### Task Settings
- **Default Task Duration**: Default time allocation for tasks
- **Working Hours**: Define your typical work schedule
- **Auto-start**: Launch application on system startup

### Configuration File

Settings are stored in the application's database and persist between sessions.

## Task Management

### Creating Tasks

Tasks can be created through the **➕ Add Task** modal with the following fields:

- **Title**: Task description (required)
- **Date**: Target date in YYYY-MM-DD format
- **Time**: Hour (0-23) and minute (0-59)
- **AM/PM**: Time period for 12-hour format

### Task Status

Tasks have the following status levels:
- **⏳ Pending**: Not yet completed
- **✅ Completed**: Finished tasks
- **🔄 Recurring**: Repeating tasks (future feature)

### Task Operations

- **View**: Click on task cards to see details
- **Edit**: Modify task details (planned feature)
- **Delete**: Remove tasks (planned feature)
- **Mark Complete**: Change status to completed

## Calendar View

### Monthly Overview

The calendar view displays:
- **Month Navigation**: Previous/Next month buttons
- **Task Indicators**: Days with tasks are highlighted
- **Today Highlighting**: Current date is specially marked
- **Task Preview**: Brief task list on each calendar day

### Calendar Navigation

- **◀ Prev**: Go to previous month
- **Next ▶**: Go to next month
- **Keyboard**: Use arrow keys for quick navigation
- **Click Days**: Click on calendar days to view tasks

### Task Indicators

- **Highlighted Days**: Days containing tasks
- **Task Count**: Shows number of tasks per day
- **Task Preview**: First 2 tasks shown, with "+X more" indicator

## System Tray Mode

### Background Operation

```bash
schedulr --tray
```

Tray mode features:
- **Minimized Operation**: Runs without visible window
- **Background Monitoring**: Continuously checks for due tasks
- **Desktop Notifications**: Alerts when tasks are due
- **Quick Access**: Right-click tray icon for menu options

### Tray Menu Options

- **Open Schedulr**: Show the main application window
- **Exit**: Close the application and stop notifications

### Notification System

- **Due Task Alerts**: Notified when tasks reach their scheduled time
- **Customizable Timing**: Set reminder time in settings
- **Persistent Notifications**: Remain visible for 10 seconds
- **Task Context**: Shows task title and type in notifications

## Auto-start Setup

### Windows Auto-start

Enable Schedulr to launch automatically when Windows starts:

```bash
# Enable auto-start
schedulr --autostart add

# Disable auto-start
schedulr --autostart remove

# Check status
schedulr --autostart check
```

### Auto-start Process

1. Creates a batch file in Windows startup folder
2. Uses `pythonw.exe` to run without console window
3. Automatically starts in system tray mode
4. Begins monitoring for due tasks immediately

## Development

### Development Setup

```bash
# Clone repository
git clone <repository-url>
cd schedulr

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run in development mode
python -m schedulr
```

### Project Structure

```
schedulr/
├── __main__.py          # Entry point and CLI argument parsing
├── cli.py              # Main Textual TUI application
├── core.py             # Database operations and task management
├── screens.py          # Calendar screen and modal screens
├── notifier.py         # Background notification system
├── tray.py            # System tray integration
└── autostart.py       # Windows auto-start management

data.db                # SQLite database (created automatically)
README.md             # This file
pyproject.toml        # Project configuration and dependencies
```

### Key Components

#### Database Layer (`core.py`)
- SQLite database management
- Task CRUD operations
- Data validation and error handling

#### User Interface (`cli.py`)
- Textual-based terminal interface
- Task display and management
- Search functionality
- Modal forms for task creation

#### Calendar System (`screens.py`)
- Monthly calendar visualization
- Task indicators and previews
- Navigation and date selection

#### Notification Engine (`notifier.py`)
- Background task monitoring
- Desktop notification delivery
- Configurable check intervals

### Dependencies

```toml
[project]
dependencies = [
    "rich",           # Beautiful terminal formatting
    "typer",          # CLI framework
    "dateparser",     # Natural language date parsing
    "schedule",       # Task scheduling
    "plyer",         # Desktop notifications
    "pystray",       # System tray icon
    "Pillow",        # Image processing for icons
    "textual"        # Terminal user interface framework
]
```

## API Reference

### Core Classes

#### Database

```python
from schedulr.core import Database

# Initialize database connection
db = Database(db_path="data.db")

# Create a new task
result = db.create_task(
    title="Team Meeting",
    date_time="2024-01-15 14:30:00",
    status="Pending"
)

# Get all tasks
tasks = db.get_all_tasks()

# Update task status
db.update_task(task_id=1, status="Completed")

# Delete a task
db.delete_task(task_id=1)
```

#### Notifier

```python
from schedulr.notifier import Notifier

# Create notifier instance
notifier = Notifier(check_interval=60)  # Check every 60 seconds

# Start background monitoring
notifier.start()

# Stop monitoring
notifier.stop()
```

#### System Tray

```python
from schedulr.tray import SystemTrayApp

# Create and run tray application
tray_app = SystemTrayApp()
tray_app.run()
```

### Textual App Structure

#### Home Screen

Main application interface with:
- Navigation sidebar
- Task statistics
- Search functionality
- Task cards display
- Modal screens for task creation

#### Calendar Screen

Monthly calendar view featuring:
- Month navigation
- Day highlighting
- Task indicators
- Click-to-view task details

## Troubleshooting

### Common Issues

#### Application Won't Start
```bash
# Check Python version
python --version  # Should be 3.8+

# Verify installation
pip show schedulr

# Check for missing dependencies
pip install -r requirements.txt
```

#### No Notifications
```bash
# Check if running in tray mode
schedulr --tray

# Verify notification permissions
# Check Windows notification settings
```

#### Database Issues
```bash
# Reset database (WARNING: Deletes all tasks)
del data.db
schedulr
```

#### Display Problems
- Ensure terminal supports colors
- Try resizing terminal window
- Check font supports Unicode characters

### Debug Mode

Run with verbose output for troubleshooting:

```bash
# Enable debug logging (if available)
set SCHEDULR_DEBUG=1
schedulr
```

### Getting Help

1. Check the Issues page for known problems
2. Create a new issue with:
   - Python version (`python --version`)
   - Operating system
   - Steps to reproduce the problem
   - Full error messages

## Contributing

We welcome contributions! Please see our Contributing Guide for details.

### Development Workflow

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

### Code Style

- Follow PEP 8 for Python code
- Use type hints for function parameters and return values
- Add docstrings to all public functions and classes
- Keep line length under 88 characters

## License

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

## Acknowledgments

- [Textual](https://textual.textualize.io/) for the beautiful TUI framework
- [Rich](https://rich.readthedocs.io/) for enhanced terminal formatting
- [PyStray](https://github.com/moses-palmer/pystray) for system tray functionality
- [Plyer](https://plyer.readthedocs.io/) for cross-platform desktop notifications

## Support

- **Documentation**: This README and inline code documentation
- **Issues**: Bug reports and feature requests via Issues
- **Discussions**: Community discussions via Discussions

---

<div align="center">

**Made with ❤️ for developers who love terminal applications**

[⭐ Star this project](https://github.com/your-username/schedulr/stargazers) | [🐛 Report Bug](https://github.com/your-username/schedulr/issues) | [💡 Request Feature](https://github.com/your-username/schedulr/issues)

</div>
