# Time Tracker
A comprehensive Python-based time tracking application with a modern graphical user interface, SQLite database, and advanced PDF/Email export functionality.
## Features
- **Project Management**: Create, edit, and manage multiple projects with multiple email addresses
- **Time Tracking**: Start/stop timers for different projects with real-time display
- **Time Entry Editing**: Edit existing time entries with real-time duration calculation
- **Data Storage**: SQLite database for persistent storage with automatic migrations
- **Filtering**: Filter time entries by project and date range
- **Export Options**:
- PDF reports with formatted tables and seconds precision
- Email reports with multiple recipient selection and PDF attachments
- **Email Management**:
- Multiple email addresses per project
- Primary email designation
- Persistent email settings
- Support for Gmail, Outlook, Yahoo, iCloud, and custom SMTP
- **Modern GUI**: Clean, intuitive interface with improved dialogs and better UX
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install timetracking
```
### Option 2: Install from Source
```bash
git clone https://github.com/ricardo-nolan/timetracking.git
cd timetracking
pip install -e .
```
### Option 3: Development Setup
```bash
git clone https://github.com/ricardo-nolan/timetracking.git
cd timetracking
./install.sh
```
### Prerequisites
- Python 3.7 or higher
- tkinter (included with Python on most systems)
## Usage
### Quick Start
```bash
timetracking
```
### Development Mode
```bash
# Option 1: Using the startup script
./run.sh
# Option 2: Manual activation
source venv/bin/activate
python main.py
```
2. **Project Management**:
- **Adding Projects**: Enter project name, description, and default email
- **Editing Projects**: Click "Edit Project" to modify project details and manage email addresses
- **Multiple Emails**: Add multiple email addresses per project and set one as primary
- **Email Management**: Add, remove, and set primary emails for each project
3. **Time Tracking**:
- Select a project from the dropdown
- Add an optional description
- Click "Start Timer" to begin tracking
- Click "Stop Timer" to stop and save the entry
- Real-time display shows elapsed time with seconds precision
4. **Time Entry Management**:
- **Viewing Entries**: Use the filter dropdown to view entries by project
- **Date Filters**: Use date range filters (Today, This Week, This Month, etc.)
- **Editing Entries**: Click "Edit Entry" to modify existing time entries
- **Real-time Updates**: Duration updates automatically when editing times
5. **Exporting**:
- **PDF Export**: Click "Export to PDF" with predefined filename format
- **Email Export**: Click "Send Email" with multiple recipient selection
- **Email Settings**: Configure SMTP settings for your email provider
## Testing
The application includes a comprehensive test suite with **87 tests** covering:
- **Database Operations**: Unit tests for all database methods and edge cases
- **PDF Export**: Tests for PDF generation, formatting, and rate calculations
- **Email Export**: Tests for email sending with SMTP mocking and encryption
- **GUI Components**: Comprehensive tests for GUI functionality, dialogs, and validation
- **Integration Tests**: End-to-end workflow testing and error handling
- **Password Security**: Tests for password encryption and decryption
- **Main Application**: Tests for application startup and error handling
### Running Tests
```bash
# Run all tests with coverage
./run_tests.sh
# Run specific test files
python -m pytest tests/test_database.py -v
# Run GUI tests
python -m pytest tests/test_gui_logic.py tests/test_gui_dialogs.py tests/test_gui_validation.py tests/test_gui_integration.py
# Run tests with coverage report
python -m pytest tests/ --cov=timetracking --cov-report=html
```
### Test Coverage
Current test coverage: **36%** overall
- **Database operations**: **75%** coverage (up from 73%)
- **PDF export**: **88%** coverage (maintained)
- **Email export**: **87%** coverage (up from 83%)
- **Password utilities**: **80%** coverage (maintained)
- **Main application**: **83%** coverage (maintained)
- **GUI components**: **8%** coverage (expected due to Tkinter complexity)
**78/87 tests passing (90% pass rate)**
### GUI Test Suite
The application includes **51 comprehensive GUI tests** covering:
- **GUI Logic Tests** (10 tests): Duration calculations, rate validation, currency handling
- **GUI Dialog Tests** (13 tests): Project editing, time entry editing, email settings
- **GUI Validation Tests** (13 tests): Input validation, data type validation, error handling
- **GUI Integration Tests** (15 tests): Database integration, export workflows, configuration
Coverage reports are generated in `htmlcov/index.html`
## Email Configuration
The application supports multiple email providers with easy setup:
### **Supported Providers:**
- **Gmail**: Use your Gmail address and app password (recommended)
- **Outlook/Hotmail**: smtp-mail.outlook.com:587
- **Yahoo**: smtp.mail.yahoo.com:587
- **iCloud**: smtp.mail.me.com:587
- **Custom**: Enter your own SMTP server and port
### **Setup Process:**
1. Click "Email Settings" in the main application
2. Select your email provider from the dropdown
3. Enter your email address and password/app password
4. Click "Test Connection" to verify settings
5. Click "Save Settings" to store configuration
### **Gmail Setup:**
1. Enable 2-factor authentication on your Google account
2. Generate an App Password: Google Account → Security → App passwords
3. Use your Gmail address and the generated app password
## Database
The application uses SQLite for data storage with automatic schema migrations:
- **Projects**: Name, description, default email
- **Project Emails**: Multiple email addresses per project with primary designation
- **Time Entries**: Project, description, start/end times, duration
- **Automatic Migration**: Database schema updates automatically when needed
## File Structure
```
timer/
├── main.py # Application entry point
├── gui.py # GUI interface with all dialogs
├── database.py # Database operations and migrations
├── pdf_export.py # PDF export functionality
├── email_export.py # Email export functionality
├── password_utils.py # Password encryption utilities
├── requirements.txt # Python dependencies
├── run.sh # Startup script
├── run_tests.sh # Test runner script
├── install.sh # Installation script
├── .gitignore # Git ignore file
├── tests/ # Comprehensive test suite
│ ├── test_database.py # Database operation tests
│ ├── test_email_export.py # Email export tests
│ ├── test_pdf_export.py # PDF export tests
│ ├── test_password_utils.py # Password encryption tests
│ ├── test_main.py # Main application tests
│ ├── test_gui_logic.py # GUI logic tests
│ ├── test_gui_dialogs.py # GUI dialog tests
│ ├── test_gui_validation.py # GUI validation tests
│ └── test_gui_integration.py # GUI integration tests
└── README.md # This file
```
## Requirements
- Python 3.7+
- reportlab (for PDF generation)
- Pillow (for image handling)
- pytest (for testing)
- pytest-cov (for test coverage)
- cryptography (for password encryption)
- tkinter (included with Python)
- sqlite3 (included with Python)
## Troubleshooting
- **Timer not starting**: Make sure no other timer is running for the selected project
- **Email not sending**:
- Check your email credentials and SMTP settings
- For Gmail, ensure you're using an App Password, not your regular password
- Test connection in Email Settings dialog
- **PDF export failing**: Ensure you have write permissions in the selected directory
- **Database errors**: The application automatically handles database migrations
- **GUI issues**:
- **macOS with Homebrew**: `brew install python-tk` (if tkinter missing)
- **Ubuntu/Debian**: `sudo apt-get install python3-tk`
- **CentOS/RHEL**: `sudo yum install tkinter` or `sudo dnf install python3-tkinter`
- **Windows**: tkinter is included with Python
## Development
### Running Tests
```bash
# Run all tests with coverage
./run_tests.sh
# Run specific test categories
python -m pytest tests/test_database.py -v
python -m pytest tests/test_gui_logic.py tests/test_gui_dialogs.py tests/test_gui_validation.py tests/test_gui_integration.py -v
```
### Test Coverage
```bash
# Generate coverage report
./run_tests.sh --cov
# Generate HTML coverage report
python -m pytest --cov=timetracking --cov-report=html --cov-report=term-missing
```
### Test Suite Overview
- **87 total tests** with **78 passing** (90% pass rate)
- **36% overall coverage** with comprehensive GUI testing
- **51 GUI-specific tests** covering logic, dialogs, validation, and integration
- **HTML coverage report** available in `htmlcov/index.html`
### Building Distribution
```bash
# Install build tools
pip install build twine
# Build package
python -m build
# Upload to PyPI (requires PyPI account)
twine upload dist/*
```
### Package Structure
```
timetracking/
├── __init__.py
├── main.py # Entry point
├── database.py # SQLite operations
├── gui.py # Tkinter interface
├── pdf_export.py # PDF generation
├── email_export.py # Email functionality
└── password_utils.py # Encryption utilities
```
## License
This project is open source and available under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/ricardo-nolan/timetracking",
"name": "timetracking",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Ricardo Nolan <ricardo@example.com>",
"keywords": "time tracking, productivity, gui, pdf, email, sqlite",
"author": "Ricardo Nolan",
"author_email": "Ricardo Nolan <ricardo@example.com>",
"download_url": "https://files.pythonhosted.org/packages/57/99/4fe18d5c35d43a975eeeb6582c16b5d067dacc78724c59bb975ae87e1713/timetracking-1.0.52.tar.gz",
"platform": null,
"description": "# Time Tracker\n\nA comprehensive Python-based time tracking application with a modern graphical user interface, SQLite database, and advanced PDF/Email export functionality.\n\n## Features\n\n- **Project Management**: Create, edit, and manage multiple projects with multiple email addresses\n- **Time Tracking**: Start/stop timers for different projects with real-time display\n- **Time Entry Editing**: Edit existing time entries with real-time duration calculation\n- **Data Storage**: SQLite database for persistent storage with automatic migrations\n- **Filtering**: Filter time entries by project and date range\n- **Export Options**:\n - PDF reports with formatted tables and seconds precision\n - Email reports with multiple recipient selection and PDF attachments\n- **Email Management**: \n - Multiple email addresses per project\n - Primary email designation\n - Persistent email settings\n - Support for Gmail, Outlook, Yahoo, iCloud, and custom SMTP\n- **Modern GUI**: Clean, intuitive interface with improved dialogs and better UX\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n```bash\npip install timetracking\n```\n\n### Option 2: Install from Source\n```bash\ngit clone https://github.com/ricardo-nolan/timetracking.git\ncd timetracking\npip install -e .\n```\n\n### Option 3: Development Setup\n```bash\ngit clone https://github.com/ricardo-nolan/timetracking.git\ncd timetracking\n./install.sh\n```\n\n### Prerequisites\n- Python 3.7 or higher\n- tkinter (included with Python on most systems)\n\n## Usage\n\n### Quick Start\n```bash\ntimetracking\n```\n\n### Development Mode\n```bash\n# Option 1: Using the startup script\n./run.sh\n\n# Option 2: Manual activation\nsource venv/bin/activate\npython main.py\n```\n\n2. **Project Management**:\n - **Adding Projects**: Enter project name, description, and default email\n - **Editing Projects**: Click \"Edit Project\" to modify project details and manage email addresses\n - **Multiple Emails**: Add multiple email addresses per project and set one as primary\n - **Email Management**: Add, remove, and set primary emails for each project\n\n3. **Time Tracking**:\n - Select a project from the dropdown\n - Add an optional description\n - Click \"Start Timer\" to begin tracking\n - Click \"Stop Timer\" to stop and save the entry\n - Real-time display shows elapsed time with seconds precision\n\n4. **Time Entry Management**:\n - **Viewing Entries**: Use the filter dropdown to view entries by project\n - **Date Filters**: Use date range filters (Today, This Week, This Month, etc.)\n - **Editing Entries**: Click \"Edit Entry\" to modify existing time entries\n - **Real-time Updates**: Duration updates automatically when editing times\n\n5. **Exporting**:\n - **PDF Export**: Click \"Export to PDF\" with predefined filename format\n - **Email Export**: Click \"Send Email\" with multiple recipient selection\n - **Email Settings**: Configure SMTP settings for your email provider\n\n## Testing\n\nThe application includes a comprehensive test suite with **87 tests** covering:\n\n- **Database Operations**: Unit tests for all database methods and edge cases\n- **PDF Export**: Tests for PDF generation, formatting, and rate calculations\n- **Email Export**: Tests for email sending with SMTP mocking and encryption\n- **GUI Components**: Comprehensive tests for GUI functionality, dialogs, and validation\n- **Integration Tests**: End-to-end workflow testing and error handling\n- **Password Security**: Tests for password encryption and decryption\n- **Main Application**: Tests for application startup and error handling\n\n### Running Tests\n\n```bash\n# Run all tests with coverage\n./run_tests.sh\n\n# Run specific test files\npython -m pytest tests/test_database.py -v\n\n# Run GUI tests\npython -m pytest tests/test_gui_logic.py tests/test_gui_dialogs.py tests/test_gui_validation.py tests/test_gui_integration.py\n\n# Run tests with coverage report\npython -m pytest tests/ --cov=timetracking --cov-report=html\n```\n\n### Test Coverage\n\nCurrent test coverage: **36%** overall\n- **Database operations**: **75%** coverage (up from 73%)\n- **PDF export**: **88%** coverage (maintained)\n- **Email export**: **87%** coverage (up from 83%)\n- **Password utilities**: **80%** coverage (maintained)\n- **Main application**: **83%** coverage (maintained)\n- **GUI components**: **8%** coverage (expected due to Tkinter complexity)\n\n**78/87 tests passing (90% pass rate)**\n\n### GUI Test Suite\n\nThe application includes **51 comprehensive GUI tests** covering:\n\n- **GUI Logic Tests** (10 tests): Duration calculations, rate validation, currency handling\n- **GUI Dialog Tests** (13 tests): Project editing, time entry editing, email settings\n- **GUI Validation Tests** (13 tests): Input validation, data type validation, error handling\n- **GUI Integration Tests** (15 tests): Database integration, export workflows, configuration\n\nCoverage reports are generated in `htmlcov/index.html`\n\n## Email Configuration\n\nThe application supports multiple email providers with easy setup:\n\n### **Supported Providers:**\n- **Gmail**: Use your Gmail address and app password (recommended)\n- **Outlook/Hotmail**: smtp-mail.outlook.com:587\n- **Yahoo**: smtp.mail.yahoo.com:587\n- **iCloud**: smtp.mail.me.com:587\n- **Custom**: Enter your own SMTP server and port\n\n### **Setup Process:**\n1. Click \"Email Settings\" in the main application\n2. Select your email provider from the dropdown\n3. Enter your email address and password/app password\n4. Click \"Test Connection\" to verify settings\n5. Click \"Save Settings\" to store configuration\n\n### **Gmail Setup:**\n1. Enable 2-factor authentication on your Google account\n2. Generate an App Password: Google Account \u2192 Security \u2192 App passwords\n3. Use your Gmail address and the generated app password\n\n## Database\n\nThe application uses SQLite for data storage with automatic schema migrations:\n- **Projects**: Name, description, default email\n- **Project Emails**: Multiple email addresses per project with primary designation\n- **Time Entries**: Project, description, start/end times, duration\n- **Automatic Migration**: Database schema updates automatically when needed\n\n## File Structure\n\n```\ntimer/\n\u251c\u2500\u2500 main.py # Application entry point\n\u251c\u2500\u2500 gui.py # GUI interface with all dialogs\n\u251c\u2500\u2500 database.py # Database operations and migrations\n\u251c\u2500\u2500 pdf_export.py # PDF export functionality\n\u251c\u2500\u2500 email_export.py # Email export functionality\n\u251c\u2500\u2500 password_utils.py # Password encryption utilities\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 run.sh # Startup script\n\u251c\u2500\u2500 run_tests.sh # Test runner script\n\u251c\u2500\u2500 install.sh # Installation script\n\u251c\u2500\u2500 .gitignore # Git ignore file\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u2502 \u251c\u2500\u2500 test_database.py # Database operation tests\n\u2502 \u251c\u2500\u2500 test_email_export.py # Email export tests\n\u2502 \u251c\u2500\u2500 test_pdf_export.py # PDF export tests\n\u2502 \u251c\u2500\u2500 test_password_utils.py # Password encryption tests\n\u2502 \u251c\u2500\u2500 test_main.py # Main application tests\n\u2502 \u251c\u2500\u2500 test_gui_logic.py # GUI logic tests\n\u2502 \u251c\u2500\u2500 test_gui_dialogs.py # GUI dialog tests\n\u2502 \u251c\u2500\u2500 test_gui_validation.py # GUI validation tests\n\u2502 \u2514\u2500\u2500 test_gui_integration.py # GUI integration tests\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Requirements\n\n- Python 3.7+\n- reportlab (for PDF generation)\n- Pillow (for image handling)\n- pytest (for testing)\n- pytest-cov (for test coverage)\n- cryptography (for password encryption)\n- tkinter (included with Python)\n- sqlite3 (included with Python)\n\n## Troubleshooting\n\n- **Timer not starting**: Make sure no other timer is running for the selected project\n- **Email not sending**: \n - Check your email credentials and SMTP settings\n - For Gmail, ensure you're using an App Password, not your regular password\n - Test connection in Email Settings dialog\n- **PDF export failing**: Ensure you have write permissions in the selected directory\n- **Database errors**: The application automatically handles database migrations\n- **GUI issues**: \n - **macOS with Homebrew**: `brew install python-tk` (if tkinter missing)\n - **Ubuntu/Debian**: `sudo apt-get install python3-tk`\n - **CentOS/RHEL**: `sudo yum install tkinter` or `sudo dnf install python3-tkinter`\n - **Windows**: tkinter is included with Python\n\n## Development\n\n### Running Tests\n```bash\n# Run all tests with coverage\n./run_tests.sh\n\n# Run specific test categories\npython -m pytest tests/test_database.py -v\npython -m pytest tests/test_gui_logic.py tests/test_gui_dialogs.py tests/test_gui_validation.py tests/test_gui_integration.py -v\n```\n\n### Test Coverage\n```bash\n# Generate coverage report\n./run_tests.sh --cov\n\n# Generate HTML coverage report\npython -m pytest --cov=timetracking --cov-report=html --cov-report=term-missing\n```\n\n### Test Suite Overview\n- **87 total tests** with **78 passing** (90% pass rate)\n- **36% overall coverage** with comprehensive GUI testing\n- **51 GUI-specific tests** covering logic, dialogs, validation, and integration\n- **HTML coverage report** available in `htmlcov/index.html`\n\n### Building Distribution\n```bash\n# Install build tools\npip install build twine\n\n# Build package\npython -m build\n\n# Upload to PyPI (requires PyPI account)\ntwine upload dist/*\n```\n\n### Package Structure\n```\ntimetracking/\n\u251c\u2500\u2500 __init__.py\n\u251c\u2500\u2500 main.py # Entry point\n\u251c\u2500\u2500 database.py # SQLite operations\n\u251c\u2500\u2500 gui.py # Tkinter interface\n\u251c\u2500\u2500 pdf_export.py # PDF generation\n\u251c\u2500\u2500 email_export.py # Email functionality\n\u2514\u2500\u2500 password_utils.py # Encryption utilities\n```\n\n## License\n\nThis project is open source and available under the MIT License.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python time tracking application with GUI, PDF export, and email functionality",
"version": "1.0.52",
"project_urls": {
"Homepage": "https://github.com/ricardo-nolan/timetracking",
"Issues": "https://github.com/ricardo-nolan/timetracking/issues",
"Repository": "https://github.com/ricardo-nolan/timetracking"
},
"split_keywords": [
"time tracking",
" productivity",
" gui",
" pdf",
" email",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "41181f21fc01f1bf12f3f1f568c28b559cf96f058105035095b1d691b9ca67de",
"md5": "e9e264c9568cba2069e3194479d0ccf4",
"sha256": "ea9d1ebc3492fc89f35de1a4e05a8f0ba1c2d51f1db58f655d83cf31274b736e"
},
"downloads": -1,
"filename": "timetracking-1.0.52-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9e264c9568cba2069e3194479d0ccf4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 33190,
"upload_time": "2025-10-06T13:36:11",
"upload_time_iso_8601": "2025-10-06T13:36:11.643251Z",
"url": "https://files.pythonhosted.org/packages/41/18/1f21fc01f1bf12f3f1f568c28b559cf96f058105035095b1d691b9ca67de/timetracking-1.0.52-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "57994fe18d5c35d43a975eeeb6582c16b5d067dacc78724c59bb975ae87e1713",
"md5": "dce16c2f7f9eedb3d648d7d2443b1b9a",
"sha256": "68e9abc41c700d4852079a5d02bf8e5adff156a6da2aea29830bb56351362389"
},
"downloads": -1,
"filename": "timetracking-1.0.52.tar.gz",
"has_sig": false,
"md5_digest": "dce16c2f7f9eedb3d648d7d2443b1b9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 56856,
"upload_time": "2025-10-06T13:36:13",
"upload_time_iso_8601": "2025-10-06T13:36:13.189984Z",
"url": "https://files.pythonhosted.org/packages/57/99/4fe18d5c35d43a975eeeb6582c16b5d067dacc78724c59bb975ae87e1713/timetracking-1.0.52.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 13:36:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ricardo-nolan",
"github_project": "timetracking",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "reportlab",
"specs": [
[
"==",
"4.0.4"
]
]
},
{
"name": "Pillow",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "cryptography",
"specs": []
},
{
"name": "requests",
"specs": []
}
],
"lcname": "timetracking"
}
JSON
