will/thechart
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add quick test runner and enhance run_tests script
Some checks failed
Build and Push Docker Image / build-and-push (push) Has been cancelled
Details

Browse Source 
- Introduced `quick_test.py` for running specific test categories (unit, integration, theme, all).
- Updated `run_tests.py` to improve test execution and reporting, including coverage.
- Removed outdated test scripts for keyboard shortcuts, menu theming, note saving, and entry updating.
- Added new test script `test_theme_changing.py` to verify theme changing functionality.
- Consolidated integration tests into `test_integration.py` for comprehensive testing of TheChart application.
- Updated theme manager to ensure color retrieval works correctly.
- Modified test constants to import from the correct module path.
This commit is contained in:
William Valentin
2025-08-05 15:09:13 -07:00
parent df9738ab17
commit a521ed6e9a
46 changed files with 8325 additions and 1131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

594
README.md
View File

@@ -9,532 +9,152 @@ make install
# Run the application
make run
# Run tests
# Run tests (consolidated test suite)
make test
```
## 📚 Documentation
- **[Features Guide](docs/FEATURES.md)** - Complete feature documentation with UI/UX improvements
- **[Keyboard Shortcuts](docs/KEYBOARD_SHORTCUTS.md)** - Comprehensive keyboard shortcuts for efficiency
- **[Export System](docs/EXPORT_SYSTEM.md)** - Data export functionality (JSON, XML, PDF)
- **[Development Guide](docs/DEVELOPMENT.md)** - Testing, development, and architecture
- **[Changelog](docs/CHANGELOG.md)** - Version history and recent UI improvements
- **[Documentation Index](docs/README.md)** - Complete documentation navigation guide
> 💡 **Quick Start**: New users should start with this README, then explore the [Features Guide](docs/FEATURES.md) for detailed functionality. The [Documentation Index](docs/README.md) provides comprehensive navigation.
### 🎯 **For Users**
- **[User Guide](USER_GUIDE.md)** - Complete features, keyboard shortcuts, and usage guide
- **[Changelog](CHANGELOG.md)** - Version history and recent improvements
## ✨ Recent Major Updates (v1.9.5)
- **🎨 Modern UI/UX**: Professional themes with ttkthemes integration
- **⌨️ Keyboard Shortcuts**: Comprehensive shortcut system for all operations
- **💡 Smart Tooltips**: Context-sensitive help throughout the application
- **🎭 8 Professional Themes**: Arc, Equilux, Adapta, Yaru, Ubuntu, Plastik, Breeze, Elegance
- **⚙️ Settings System**: Advanced configuration with theme persistence
- **📊 Enhanced Tables**: Improved selection highlighting and alternating row colors
### 🛠️ **For Developers**
- **[Developer Guide](DEVELOPER_GUIDE.md)** - Development setup, testing, and architecture
- **[API Reference](API_REFERENCE.md)** - Technical documentation and system APIs
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Application](#running-the-application)
- [Key Features](#key-features)
- [Development](#development)
- [Deployment](#deployment)
- [Docker Usage](#docker-usage)
- [Troubleshooting](#troubleshooting)
- [Quick Reference](#quick-reference)
### 📖 **Complete Navigation**
- **[Documentation Index](docs/README.md)** - Comprehensive documentation navigation
## Prerequisites
> 💡 **Getting Started**: New users should start with the [User Guide](USER_GUIDE.md), while developers should check the [Developer Guide](DEVELOPER_GUIDE.md).
Before installing Thechart, ensure you have the following installed on your system:
## ✨ Recent Major Updates (v1.9.5+)
### Required Software
- **Python 3.13 or higher** - The application requires Python 3.13+
- **uv** - For fast dependency management and virtual environment handling
- **Git** - For version control (if cloning from repository)
### 🎨 UI/UX Improvements
- **8 Professional Themes**: Arc, Equilux, Adapta, Yaru, Ubuntu, Plastik, Breeze, Elegance
- **Smart Tooltips**: Context-sensitive help throughout the application
- **Enhanced Keyboard Shortcuts**: Comprehensive shortcut system for all operations
- **Modern Styling**: Card-style frames, professional form controls, responsive design
### Installing Prerequisites
### 🧪 Testing Improvements
- **Consolidated Test Suite**: Unified pytest-based testing structure
- **Quick Test Categories**: Unit, integration, and theme-specific tests
- **Enhanced Coverage**: Comprehensive test coverage with automated reporting
- **Developer-Friendly**: Fast feedback cycles and targeted testing
#### Install Python 3.13
**Ubuntu/Debian:**
```shell
sudo apt update
sudo apt install python3.13 python3.13-venv python3.13-dev
```
### 🚀 Performance & Quality
- **Optimized Data Management**: Enhanced CSV handling and caching
- **Improved Export System**: JSON, XML, and PDF export with graph integration
- **Code Quality**: Enhanced linting, formatting, and type checking
- **CI/CD Ready**: Streamlined testing and deployment pipeline
**macOS (using Homebrew):**
```shell
brew install python@3.13
```
## 🎯 Key Features
**Windows:**
Download and install from [python.org](https://www.python.org/downloads/)
### Core Functionality
- **📊 Medication Tracking**: Log daily medication intake with dose tracking
- **📈 Symptom Monitoring**: Track pathologies on customizable scales
- **📋 Data Management**: Comprehensive entry editing, validation, and organization
- **📤 Export System**: Multiple export formats (CSV, JSON, XML, PDF)
#### Install uv
**All Platforms:**
```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Advanced Features
- **🎨 Theme System**: 8 professional themes with complete UI integration
- **⌨️ Keyboard Shortcuts**: Full keyboard navigation and shortcuts
- **📊 Visualization**: Interactive graphs and charts with matplotlib
- **💡 Smart Tooltips**: Context-aware help and guidance
- **⚙️ Settings Management**: Persistent configuration and preferences
**macOS (using Homebrew):**
```shell
brew install uv
```
## 🛠️ Installation
**Windows (using PowerShell):**
```shell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Prerequisites
- Python 3.11+
- UV package manager (recommended) or pip
- Virtual environment support
**Alternative (using pip):**
```shell
pip install uv
```
Add uv to your PATH (usually done automatically by the installer):
```shell
export PATH="$HOME/.local/bin:$PATH"
```
#### Verify Installation
```shell
python3.13 --version
uv --version
```
## Installation
### Quick Setup (Recommended)
The Makefile is configured to use the fish shell by default. For other shells, see the [shell-specific instructions](#shell-specific-activation) below.
**Note:** The current Makefile still uses Poetry commands. If you've switched to uv, you may need to update the Makefile or use the manual installation method below.
```shell
make install
```
This command will:
- Set up the Python virtual environment using uv
- Install all required dependencies
- Install development dependencies
- Set up pre-commit hooks for code quality
- Run initial code formatting and linting
### Manual Installation
If you prefer to set up the environment manually:
1. **Clone the repository** (if not already done):
```shell
### Setup
```bash
# Clone the repository
git clone <repository-url>
cd thechart
```
2. **Create and activate virtual environment:**
```shell
uv venv --python 3.13
# Install with UV (recommended)
uv sync
```
3. **Install pre-commit hooks** (for development):
```shell
uv run pre-commit install --install-hooks --overwrite
uv run pre-commit autoupdate
```
# Or install with pip
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
### Migrating from Poetry to uv
If you have an existing Poetry setup and want to migrate to uv:
1. **Remove Poetry environment** (optional):
```shell
poetry env remove python
```
2. **Create new uv environment:**
```shell
uv venv --python 3.13
uv sync
```
3. **Update your workflow:** Replace `poetry run` with `uv run` in your commands.
The `pyproject.toml` file remains compatible between Poetry and uv, so no changes are needed there.
### Shell-Specific Activation
If the automatic environment activation doesn't work or you're using a different shell, manually activate the environment:
#### fish shell (default)
```shell
source .venv/bin/activate.fish
```
or use the convenience command:
```shell
make shell
```
#### bash/zsh
```shell
source .venv/bin/activate
```
#### PowerShell (Windows)
```shell
.venv\Scripts\Activate.ps1
```
#### Using uv run (recommended)
For any command, you can use `uv run` to automatically use the virtual environment:
```shell
uv run python src/main.py
uv run pre-commit run --all-files
```
## Running the Application
### Quick Start
After installation, run the application with:
```shell
make run
```
### Manual Run
Alternatively, you can run the application directly:
```shell
uv run python src/main.py
```
or if you have activated the virtual environment:
```shell
# Run the application
python src/main.py
```
### First-Time Setup
On first run, the application will:
- Create a default CSV data file (`thechart_data.csv`) if it doesn't exist
- Set up logging in the `logs/` directory
- Initialize medicine and pathology configuration files (`medicines.json`, `pathologies.json`)
- Create necessary directory structure
## Key Features
### 🏥 Modular Medicine System
- **Dynamic Medicine Management**: Add, edit, and remove medicines through the UI
- **Configurable Properties**: Customize names, dosages, colors, and quick-dose options
- **JSON Configuration**: Easy management through `medicines.json`
- **Automatic UI Updates**: All components update when medicines change
### 💊 Advanced Dose Tracking
- **Precise Timestamps**: Record exact time and dose amounts
- **Multiple Daily Doses**: Track multiple doses of the same medicine
- **Comprehensive Interface**: Dedicated dose management in edit windows
- **Historical Data**: Complete dose history with CSV persistence
### 📊 Enhanced Visualizations
- **Interactive Graphs**: Toggle visibility of symptoms and medicines
- **Dose Bar Charts**: Visual representation of daily medication intake
- **Enhanced Legends**: Multi-column layout with average dosage information
- **Professional Styling**: Clean, informative chart design
### 📈 Data Management
- **Robust CSV Storage**: Human-readable and portable data format
- **Automatic Backups**: Data protection during updates
- **Backward Compatibility**: Seamless upgrades without data loss
- **Dynamic Columns**: Adapts to new medicines and pathologies
### 📋 Data Export System
- **Multiple Formats**: Export to JSON, XML, and PDF formats
- **Comprehensive Reports**: PDF exports with optional graph visualization
- **Metadata Inclusion**: Export includes date ranges, pathologies, and medicines
- **User-Friendly Interface**: Easy access through File menu with format selection
- **Data Portability**: Structured exports for analysis or backup purposes
For complete feature documentation, see **[docs/FEATURES.md](docs/FEATURES.md)**.
## Development
### Testing Framework
TheChart includes a comprehensive testing suite with **93% code coverage**:
## 🧪 Testing
### Quick Testing (Development)
```bash
# Run all tests
# Fast unit tests
.venv/bin/python scripts/quick_test.py unit
# Theme functionality tests
.venv/bin/python scripts/quick_test.py theme
# Integration tests
.venv/bin/python scripts/quick_test.py integration
```
### Comprehensive Testing
```bash
# Full test suite with coverage
.venv/bin/python scripts/run_tests.py
# Or use make
make test
# Run tests with coverage report
uv run pytest --cov=src --cov-report=html
# Run specific test file
uv run pytest tests/test_graph_manager.py -v
```
**Testing Statistics:**
- **112 total tests** across 6 test modules
- **93% overall coverage** (482 statements, 33 missed)
- **Pre-commit testing** prevents broken commits
## 🚀 Usage
### Code Quality
```bash
# Format code
make format
# Check code quality
make lint
# Run pre-commit checks
pre-commit run --all-files
```
### Package Management with uv
```bash
# Add dependencies
uv add package-name
# Add development dependencies
uv add --dev package-name
# Update dependencies
uv sync --upgrade
# Remove dependencies
uv remove package-name
```
For detailed development information, see **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.
## Deployment
### Creating a Standalone Executable
#### Linux/Unix Deployment
Deploy the application as a standalone executable that can run without Python installed:
```shell
make deploy
```
This command will:
1. **Create a standalone executable** using PyInstaller
2. **Install the executable** to `~/Applications/`
3. **Copy data file** to `~/Documents/thechart_data.csv`
4. **Create desktop entry** for easy access from the applications menu
5. **Validate desktop file** to ensure proper integration
#### Manual Deployment Steps
If you prefer to deploy manually:
1. **Build the executable:**
```shell
pyinstaller --name thechart \
--optimize 2 \
--onefile \
--windowed \
--hidden-import='PIL._tkinter_finder' \
--icon='chart-671.png' \
--add-data="./.env:." \
--add-data='./chart-671.png:.' \
--add-data='./thechart_data.csv:.' \
src/main.py
```
2. **Install files:**
```shell
# Copy executable
cp ./dist/thechart ~/Applications/
# Copy data file
cp ./thechart_data.csv ~/Documents/
# Install desktop entry (Linux)
cp ./deploy/thechart.desktop ~/.local/share/applications/
desktop-file-validate ~/.local/share/applications/thechart.desktop
```
#### macOS/Windows Deployment
**Note:** macOS and Windows deployment is planned for future releases. Currently, you can run the application using Python directly on these platforms.
For now, use:
```shell
python src/main.py
```
### Deployment Requirements
- **PyInstaller** (included in dev dependencies)
- **Icon file** (`chart-671.png`)
- **Desktop file** (`deploy/thechart.desktop` for Linux)
## Docker Usage
### Quick Start with Docker
```bash
# Build and start the application
make build
make start
# Stop the application
make stop
# Access container shell
make attach
```
### Manual Docker Commands
```bash
# Build image
docker build -t thechart .
# Run container with X11 forwarding (Linux)
docker run -it --rm \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix:rw \
thechart
```
**Note:** Docker support is primarily for development. For production use, consider the standalone executable deployment.
## Troubleshooting
### Common Issues
#### Python Version Conflicts
**Problem:** `uv sync` fails with Python version errors.
**Solution:** Ensure Python 3.13+ is installed and specify the correct version:
```shell
uv venv --python 3.13
uv sync
```
#### Permission Denied During Deployment
**Problem:** Cannot copy files to `~/Applications/` or `~/Documents/`.
**Solution:** Ensure directories exist and have proper permissions:
```shell
mkdir -p ~/Applications ~/Documents
chmod 755 ~/Applications ~/Documents
```
#### Missing System Dependencies
**Problem:** Application fails to start due to missing system libraries.
**Solution:** Install required system packages:
**Ubuntu/Debian:**
```shell
sudo apt install python3-tk python3-dev build-essential
```
**macOS:**
```shell
brew install tcl-tk
```
#### Virtual Environment Issues
**Problem:** Environment activation fails or commands not found.
**Solution:** Rebuild the virtual environment:
```shell
rm -rf .venv
uv venv --python 3.13
uv sync
```
### Logs and Debugging
Application logs are stored in the `logs/` directory:
- `app.log` - General application logs
- `app.error.log` - Error messages
- `app.warning.log` - Warning messages
To enable debug logging, modify the logging configuration in `src/logger.py`.
### Getting Help
If you encounter issues not covered here:
1. Check the application logs in the `logs/` directory
2. Ensure all prerequisites are properly installed
3. Try rebuilding the virtual environment
4. Verify file permissions for deployment directories
## Quick Reference
### Essential Commands
```bash
# Development workflow
make install # One-time setup
make run # Run application
make test # Run tests
make format # Format code
make lint # Check code quality
# Deployment
make deploy # Create standalone executable
# Docker
make build # Build container image
make start # Start containerized app
make stop # Stop containerized app
```
### Project Structure
```
src/ # Main application source code
├── main.py # Application entry point
├── ui_manager.py # User interface management
├── data_manager.py # CSV data operations
├── graph_manager.py # Visualization and plotting
├── medicine_manager.py # Medicine system
└── pathology_manager.py # Symptom tracking
docs/ # Documentation
├── FEATURES.md # Complete feature guide
└── DEVELOPMENT.md # Development guide
logs/ # Application logs
deploy/ # Deployment configuration
tests/ # Test suite
medicines.json # Medicine configuration
pathologies.json # Pathology configuration
thechart_data.csv # User data (created on first run)
```
### Key Files
- **`medicines.json`**: Configure available medicines
- **`pathologies.json`**: Configure tracked symptoms
- **`thechart_data.csv`**: Your medication and symptom data
- **`pyproject.toml`**: Project configuration and dependencies
- **`uv.lock`**: Dependency lock file
### Basic Workflow
1. **Launch**: Run `python src/main.py` or use the desktop file
2. **Configure**: Set up medicines and pathologies via the Tools menu
3. **Track**: Add daily entries with medication and symptom data
4. **Visualize**: View graphs and trends in the main interface
5. **Export**: Export data in your preferred format
### Keyboard Shortcuts
```bash
# File Operations
Ctrl+S # Save/Add new entry
Ctrl+Q # Quit application
Ctrl+E # Export data
- **Ctrl+S**: Save/Add entry
- **Ctrl+Q**: Quit application
- **Ctrl+E**: Export data
- **F1**: Show help
- **F2**: Open settings
# Data Management
Ctrl+N # Clear entries
Ctrl+R / F5 # Refresh data
> 📖 See the [User Guide](USER_GUIDE.md) for complete usage instructions and advanced features.
# Window Management
Ctrl+M # Manage medicines
Ctrl+P # Manage pathologies
## 🤝 Contributing
# Table Operations
Delete # Delete selected entry
Escape # Clear selection
Double-click # Edit entry
### Development Setup
See the [Developer Guide](DEVELOPER_GUIDE.md) for:
- Development environment setup
- Testing procedures and best practices
- Code quality standards
- Architecture overview
# Help
F1 # Show keyboard shortcuts help
```
### Code Quality
This project maintains high code quality standards:
- **Testing**: Comprehensive test suite with >90% coverage
- **Linting**: Ruff for code formatting and style
- **Type Checking**: MyPy for type safety
- **Documentation**: Comprehensive documentation and examples
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- **Documentation**: Complete guides in the [Documentation Index](docs/README.md)
- **Testing**: Consolidated testing guide in [Developer Guide](DEVELOPER_GUIDE.md)
- **Changelog**: Version history in [CHANGELOG.md](CHANGELOG.md)
---
## Why uv?
**uv** is a fast Python package installer and resolver, written in Rust. It offers several advantages over Poetry:
- **Speed**: 10-100x faster than pip and Poetry
- **Compatibility**: Drop-in replacement for pip with Poetry-like project management
- **Simplicity**: Unified tool for package management and virtual environments
- **Standards**: Follows Python packaging standards (PEP 621, etc.)
### Key uv Commands vs Poetry
| Task | uv Command | Poetry Equivalent |
|------|------------|-------------------|
| Create virtual environment | `uv venv` | `poetry env use` |
| Install dependencies | `uv sync` | `poetry install` |
| Add package | `uv add package` | `poetry add package` |
| Run command | `uv run command` | `poetry run command` |
| Activate environment | `source .venv/bin/activate` | `poetry shell` |
**TheChart** - Professional medication tracking with modern UI/UX