thechart/README.md

Thechart

App to manage medication and see the evolution of its effects.

Table of Contents

• Prerequisites
• Installation
• Running the Application
• Development
• Deployment
• Docker Usage
• Troubleshooting
• Make Commands Reference

Prerequisites

Before installing Thechart, ensure you have the following installed on your system:

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)

Installing Prerequisites

Install Python 3.13

Ubuntu/Debian:

sudo apt update
sudo apt install python3.13 python3.13-venv python3.13-dev

macOS (using Homebrew):

brew install python@3.13

Windows: Download and install from python.org

Install uv

All Platforms:

curl -LsSf https://astral.sh/uv/install.sh | sh

macOS (using Homebrew):

brew install uv

Windows (using PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (using pip):

pip install uv

Add uv to your PATH (usually done automatically by the installer):

export PATH="$HOME/.local/bin:$PATH"

Verify Installation

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 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.

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):

git clone <repository-url>
cd thechart

2. Create and activate virtual environment:

uv venv --python 3.13
uv sync

3. Install pre-commit hooks (for development):

uv run pre-commit install --install-hooks --overwrite
uv run pre-commit autoupdate

Migrating from Poetry to uv

If you have an existing Poetry setup and want to migrate to uv:

1. Remove Poetry environment (optional):

poetry env remove python

2. Create new uv environment:

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)

source .venv/bin/activate.fish

or use the convenience command:

make shell

bash/zsh

source .venv/bin/activate

PowerShell (Windows)

.venv\Scripts\Activate.ps1

Using uv run (recommended)

For any command, you can use uv run to automatically use the virtual environment:

uv run python src/main.py
uv run pre-commit run --all-files

Running the Application

Quick Start

After installation, run the application with:

make run

Manual Run

Alternatively, you can run the application directly:

uv run python src/main.py

or if you have activated the virtual environment:

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
• Create necessary configuration files

Development

Code Quality Tools

The project includes several code quality tools that are automatically set up:

Formatting and Linting

make format  # Format code with ruff
make lint    # Run linter checks

With uv directly:

uv run ruff format .  # Format code
uv run ruff check .   # Check for issues

Running Tests

make test    # Run unit tests

With uv directly:

uv run pytest  # Run tests with pytest

Package Management with uv

Adding Dependencies

# Add a runtime dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

# Add specific version
uv add "package-name>=1.0.0"

Removing Dependencies

uv remove package-name

Updating Dependencies

# Update all dependencies
uv sync --upgrade

# Update specific package
uv add "package-name>=new-version"

Pre-commit Hooks

Pre-commit hooks are automatically installed and will run on every commit to ensure code quality. They include:

• Code formatting with ruff
• Linting checks
• Import sorting
• Basic file checks

Development Dependencies

The following development tools are included:

• ruff - Fast Python linter and formatter
• pre-commit - Git hook management
• pyinstaller - For creating standalone executables

Deployment

Creating a Standalone Executable

Linux/Unix Deployment

Deploy the application as a standalone executable that can run without Python installed:

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:

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:

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

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

Docker Usage

Building the Container Image

Build a multi-platform Docker image:

make build

Running with Docker Compose

The project includes Docker Compose configuration for easy container management:

1. Start the application:

make start

2. Stop the application:

make stop

3. Access container shell:

make attach

Manual Docker Commands

If you prefer using Docker directly:

# Build image
docker build -t thechart .

# Run container
docker run -it --rm thechart

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:

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:

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:

sudo apt install python3-tk python3-dev build-essential

macOS:

brew install tcl-tk

Virtual Environment Issues

Problem: Environment activation fails or commands not found. Solution: Rebuild the virtual environment:

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

Make Commands Reference

The project uses a Makefile to simplify common development and deployment tasks.

Show Help Menu

make help

Available Commands

Command	Description
install	Set up the development environment
run	Run the application
shell	Open a shell in the local environment
format	Format the code with ruff
lint	Run the linter
test	Run the tests
requirements	Export the requirements to a file
build	Build the Docker image
start	Start the app (Docker)
stop	Stop the app (Docker)
attach	Open a shell in the container
deploy	Deploy standalone app executable
help	Show this help

Quick Reference

# 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

---

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

Project Structure:

• src/ - Main application source code
• logs/ - Application log files
• deploy/ - Deployment configuration files
• build/ - Build artifacts (created during deployment)
• .venv/ - Virtual environment (created by uv)
• uv.lock - Lock file with exact dependency versions
• pyproject.toml - Project configuration and dependencies
• thechart_data.csv - Application data file