grabowski/Northern-Thailand-Ping-River-Monitor

Files

grabowski 6c7c128b4d Major refactor: Migrate to uv, add PostgreSQL support, and comprehensive tooling

- **Migration to uv package manager**: Replace pip/requirements with modern pyproject.toml
  - Add pyproject.toml with complete dependency management
  - Update all scripts and Makefile to use uv commands
  - Maintain backward compatibility with existing workflows

- **PostgreSQL integration and migration tools**:
  - Enhanced config.py with automatic password URL encoding
  - Complete PostgreSQL setup scripts and documentation
  - High-performance SQLite to PostgreSQL migration tool (91x speed improvement)
  - Support for both connection strings and individual components

- **Executable distribution system**:
  - PyInstaller integration for standalone .exe creation
  - Automated build scripts with batch file generation
  - Complete packaging system for end-user distribution

- **Enhanced data management**:
  - Fix --fill-gaps command with proper method implementation
  - Add gap detection and historical data backfill capabilities
  - Implement data update functionality for existing records
  - Add comprehensive database adapter methods

- **Developer experience improvements**:
  - Password encoding tools for special characters
  - Interactive setup wizards for PostgreSQL configuration
  - Comprehensive documentation and migration guides
  - Automated testing and validation tools

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-09-26 15:10:10 +07:00

3.9 KiB

Raw Blame History

Migration to uv

This document describes the migration from traditional Python package management (pip + requirements.txt) to uv, a fast Python package installer and resolver.

What Changed

Files Added

pyproject.toml - Modern Python project configuration combining dependencies and metadata
.python-version - Specifies Python version for uv
scripts/setup_uv.sh - Unix setup script for uv environment
scripts/setup_uv.bat - Windows setup script for uv environment
This migration guide

Files Modified

Makefile - Updated all commands to use uv run instead of direct Python execution

Files That Can Be Removed (Optional)

requirements.txt - Dependencies now in pyproject.toml
requirements-dev.txt - Dev dependencies now in pyproject.toml
setup.py - Configuration now in pyproject.toml

Installation

Install uv

Unix/macOS:

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

Windows (PowerShell):

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

Setup Project

Unix/macOS:

# Run the setup script
chmod +x scripts/setup_uv.sh
./scripts/setup_uv.sh

# Or manually:
uv sync
uv run pre-commit install

Windows:

REM Run the setup script
scripts\setup_uv.bat

REM Or manually:
uv sync
uv run pre-commit install

New Workflow

Common Commands

Old Command	New Command	Description
`pip install -r requirements.txt`	`uv sync --no-dev`	Install production dependencies
`pip install -r requirements-dev.txt`	`uv sync`	Install all dependencies (including dev)
`python run.py`	`uv run python run.py`	Run the application
`pytest`	`uv run pytest`	Run tests
`black src/`	`uv run black src/`	Format code

Using the Makefile

The Makefile has been updated to use uv, so all existing commands work the same:

make install-dev    # Install dev dependencies with uv
make test          # Run tests with uv
make run-api       # Start API server with uv
make lint          # Lint code with uv
make format        # Format code with uv

Adding Dependencies

Production dependency:

uv add requests

Development dependency:

uv add --dev pytest

Specific version:

uv add "fastapi==0.104.1"

Managing Python Versions

uv can automatically manage Python versions:

# Install and use Python 3.11
uv python install 3.11
uv sync

# Use specific Python version
uv sync --python 3.11

Benefits of uv

Speed - 10-100x faster than pip
Reliability - Better dependency resolution
Simplicity - Single tool for packages and Python versions
Reproducibility - Lock file ensures consistent environments
Modern - Built-in support for pyproject.toml

Troubleshooting

Command not found

Make sure uv is in your PATH after installation. Restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

Lock file conflicts

If you encounter lock file issues:

rm uv.lock
uv sync

Python version issues

Ensure the Python version in .python-version is available:

uv python list
uv python install 3.11  # if needed

Rollback (if needed)

If you need to rollback to the old system:

Use the original requirements files:

pip install -r requirements.txt
pip install -r requirements-dev.txt

Revert the Makefile changes to use python instead of uv run python

Remove uv-specific files:

rm pyproject.toml .python-version uv.lock
rm -rf .venv  # if created by uv

3.9 KiB Raw Blame History