Feat: add export functionality with GUI for data and graphs

- Implemented ExportWindow class for exporting data and graphs in various formats (JSON, XML, PDF). - Integrated ExportManager to handle export logic. - Added export option in the main application menu. - Enhanced user interface with data summary and export options. - Included error handling and success messages for export operations. - Updated dependencies in the lock file to include reportlab and lxml for PDF generation.
2025-08-02 10:00:24 -07:00
parent 156dcd1651
commit b7a22524d7
11 changed files with 1135 additions and 3 deletions
--- a/docs/EXPORT_SYSTEM.md
+++ b/docs/EXPORT_SYSTEM.md
@@ -0,0 +1,215 @@
+# TheChart Export System Documentation
+
+## Overview
+
+The TheChart application now includes a comprehensive data export system that allows users to export their medication tracking data and visualizations to multiple formats:
+
+- **JSON** - Structured data format with metadata
+- **XML** - Hierarchical data format
+- **PDF** - Formatted report with optional graph visualization
+
+## Features
+
+### Export Formats
+
+#### JSON Export
+- Exports all CSV data to structured JSON format
+- Includes metadata about the export (date, total entries, date range)
+- Lists all pathologies and medicines being tracked
+- Data is exported as an array of entry objects
+
+#### XML Export
+- Exports data to hierarchical XML format
+- Includes comprehensive metadata section
+- All entries are properly structured with XML tags
+- Column names are sanitized for valid XML element names
+
+#### PDF Export
+- Creates a formatted report document
+- Includes export metadata and summary information
+- Optional graph visualization inclusion
+- Data table with all entries
+- Proper pagination and styling
+- Notes are truncated for better table formatting
+
+### User Interface
+
+The export functionality is accessible through:
+1. **File Menu** - "Export Data..." option in the main menu bar
+2. **Export Window** - Modal dialog with export options
+3. **Format Selection** - Radio buttons for JSON, XML, or PDF
+4. **Graph Option** - Checkbox to include graph in PDF exports
+5. **File Dialog** - Standard save dialog for choosing export location
+
+### Export Manager Architecture
+
+The export system consists of three main components:
+
+#### ExportManager Class (`src/export_manager.py`)
+- Core export functionality
+- Handles data transformation and file generation
+- Integrates with existing data and graph managers
+- Supports all three export formats
+
+#### ExportWindow Class (`src/export_window.py`)
+- GUI interface for export operations
+- Modal dialog with export options
+- File save dialog integration
+- Progress feedback and error handling
+
+#### Integration in MedTrackerApp (`src/main.py`)
+- Export manager initialization
+- Menu integration
+- Seamless integration with existing managers
+
+## Technical Implementation
+
+### Dependencies Added
+- `reportlab` - PDF generation library
+- `lxml` - XML processing (added for future enhancements)
+- `charset-normalizer` - Character encoding support
+
+### Data Flow
+1. User selects export format and options
+2. ExportManager loads data from DataManager
+3. Data is transformed according to selected format
+4. Graph image is optionally generated for PDF
+5. Output file is created and saved
+6. User receives success/failure feedback
+
+### Error Handling
+- Graceful handling of missing data
+- File system error management
+- User-friendly error messages
+- Logging of export operations
+
+## Usage Examples
+
+### Basic Export Process
+1. Open TheChart application
+2. Go to File → Export Data...
+3. Select desired format (JSON/XML/PDF)
+4. For PDF: choose whether to include graph
+5. Click "Export..." button
+6. Choose save location and filename
+7. Confirm successful export
+
+### Export File Examples
+
+#### JSON Structure
+```json
+{
+  "metadata": {
+    "export_date": "2025-08-02T09:03:22.580489",
+    "total_entries": 32,
+    "date_range": {
+      "start": "07/02/2025",
+      "end": "08/02/2025"
+    },
+    "pathologies": ["depression", "anxiety", "sleep", "appetite"],
+    "medicines": ["bupropion", "hydroxyzine", "gabapentin", "propranolol", "quetiapine"]
+  },
+  "entries": [
+    {
+      "date": "07/02/2025",
+      "depression": 8,
+      "anxiety": 5,
+      "sleep": 3,
+      "appetite": 1,
+      "bupropion": 0,
+      "bupropion_doses": "",
+      "note": "Starting medication tracking"
+    }
+  ]
+}
+```
+
+#### XML Structure
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<thechart_data>
+  <metadata>
+    <export_date>2025-08-02T09:03:22.613013</export_date>
+    <total_entries>32</total_entries>
+    <date_range>
+      <start>07/02/2025</start>
+      <end>08/02/2025</end>
+    </date_range>
+  </metadata>
+  <entries>
+    <entry>
+      <date>07/02/2025</date>
+      <depression>8</depression>
+      <anxiety>5</anxiety>
+      <note>Starting medication tracking</note>
+    </entry>
+  </entries>
+</thechart_data>
+```
+
+## Testing
+
+### Automated Tests
+- Export functionality is tested through `simple_export_test.py`
+- Creates sample exports in all three formats
+- Validates file creation and basic content structure
+
+### Manual Testing
+- GUI testing available through `test_export_gui.py`
+- Opens export window for interactive testing
+- Allows testing of all user interface components
+
+### Test Files Location
+Exported test files are created in the `test_exports/` directory:
+- `export.json` - JSON format export
+- `export.xml` - XML format export
+- `export.csv` - CSV format copy
+- `test_export.pdf` - PDF format with graph
+
+## File Locations
+
+### Source Files
+- `src/export_manager.py` - Core export functionality
+- `src/export_window.py` - GUI export interface
+
+### Test Files
+- `simple_export_test.py` - Basic export functionality test
+- `test_export_gui.py` - GUI testing interface
+- `scripts/test_export_functionality.py` - Comprehensive export tests
+
+### Dependencies
+- Added to `requirements.txt` and managed by `uv`
+- PDF generation requires `reportlab`
+- XML processing enhanced with `lxml`
+
+## Future Enhancements
+
+Potential improvements for the export system:
+1. **Additional Formats** - Excel, CSV with formatting
+2. **Export Filtering** - Date range selection, specific pathologies/medicines
+3. **Batch Exports** - Multiple formats at once
+4. **Email Integration** - Direct email export
+5. **Cloud Storage** - Export to cloud services
+6. **Export Scheduling** - Automated periodic exports
+7. **Advanced PDF Styling** - Charts, graphs, custom layouts
+
+## Troubleshooting
+
+### Common Issues
+1. **No Data to Export** - Ensure CSV file has entries before exporting
+2. **PDF Generation Fails** - Check ReportLab installation and permissions
+3. **File Save Errors** - Verify write permissions to selected directory
+4. **Large File Exports** - PDF exports may take longer for large datasets
+
+### Debugging
+- Check application logs for detailed error messages
+- Export operations are logged with DEBUG level information
+- File system errors are captured and reported to user
+
+## Integration Notes
+
+The export system integrates seamlessly with existing TheChart functionality:
+- Uses same data validation and loading mechanisms
+- Respects existing pathology and medicine configurations
+- Maintains data integrity and formatting consistency
+- Follows existing logging and error handling patterns