koleo-izochrona/UV_GUIDE.md

# Przewodnik po uv

## Czym jest uv?

[uv](https://docs.astral.sh/uv/) to niezwykle szybki menedżer pakietów i środowisk Pythona, napisany w Rust przez Astral (twórców Ruff). Jest on **10-100x szybszy** od pip i pip-tools.

## Instalacja uv

### Linux/macOS:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Przez pip:
```bash
pip install uv
```

### Sprawdź instalację:
```bash
uv --version
```

## ⚠️ Ważne: Flaga --no-project w projekcie Izochrona

W tym projekcie używamy `uv run --no-project` zamiast `uv run`:

```bash
# Zamiast: uv run app.py
uv run --no-project app.py
```

**Dlaczego?**
- Projekt Izochrona nie jest pakietem Pythona przeznaczonym do instalacji
- `--no-project` mówi uv aby **nie próbował instalować** projektu jako editable package
- Tylko uruchamiamy skrypty, korzystając ze środowiska wirtualnego i zainstalowanych zależności

**Bez `--no-project`:** uv próbuje zbudować i zainstalować cały projekt używając `pyproject.toml`, co może powodować błędy.

## Podstawowe komendy

### Tworzenie środowiska wirtualnego:
```bash
cd backend
uv venv
```

### Instalacja zależności:
```bash
# Z requirements.txt
uv pip install -r requirements.txt

# Z pyproject.toml (w katalogu głównym projektu)
uv sync

# Pojedynczy pakiet
uv pip install flask
```

### Uruchamianie skryptów:
```bash
# uv automatycznie używa środowiska wirtualnego
uv run --no-project app.py
uv run --no-project download_gtfs.py

# Lub z katalogu głównego
uv run --no-project backend/app.py
```

### Aktualizacja pakietów:
```bash
uv pip install --upgrade flask
uv pip install --upgrade -r requirements.txt
```

### Lista zainstalowanych pakietów:
```bash
uv pip list
uv pip freeze
```

## Dlaczego uv?

### Szybkość:
- **Instalacja pakietów**: 10-100x szybsza niż pip
- **Rozwiązywanie zależności**: bardzo szybkie
- **Cache**: globalny cache pakietów (oszczędność miejsca)

### Wygoda:
- **Automatyczna aktywacja venv**: `uv run` automatycznie używa środowiska
- **Brak `source venv/bin/activate`**: nie musisz ręcznie aktywować środowiska
- **Kompatybilność z pip**: używa tych samych formatów (requirements.txt, pyproject.toml)

### Przykład - porównanie:

**Tradycyjnie (pip):**
```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt  # ~30-60s
python app.py
```

**Z uv:**
```bash
uv venv
uv pip install -r requirements.txt  # ~2-5s
uv run --no-project app.py
```

## Użycie w projekcie Izochrona

### Pierwsze uruchomienie:
```bash
./setup.sh  # Używa uv
```

### Codzienne użycie:
```bash
# Uruchomienie serwera
./run.sh  # lub: uv run --no-project backend/app.py

# Pobranie danych
uv run --no-project backend/download_gtfs.py

# Przykłady API
uv run --no-project examples/api_examples.py
```

### Dodawanie nowych pakietów:

**Opcja A** - requirements.txt:
```bash
cd backend
echo "matplotlib>=3.8.0" >> requirements.txt
uv pip install -r requirements.txt
```

**Opcja B** - pyproject.toml (zalecane):
```bash
# Edytuj pyproject.toml, dodaj do dependencies:
# "matplotlib>=3.8.0",

# Następnie:
uv sync
```

## Porady

### 1. Nie musisz aktywować środowiska:
```bash
# Zamiast:
source venv/bin/activate
python app.py

# Użyj:
uv run --no-project app.py
```

### 2. Global cache:
uv przechowuje pakiety globalnie, więc instalacja w nowych projektach jest ultra-szybka.

### 3. Lock file (opcjonalnie):
```bash
uv pip compile requirements.txt -o requirements.lock
uv pip sync requirements.lock  # Deterministyczna instalacja
```

### 4. Różne wersje Pythona:
```bash
# uv może zarządzać wersjami Pythona
uv python install 3.11
uv venv --python 3.11
```

## Migracja z pip do uv

Jeśli masz istniejący projekt z pip:

```bash
# 1. Usuń stare venv (opcjonalnie)
rm -rf venv/

# 2. Stwórz nowe z uv
uv venv

# 3. Zainstaluj zależności
uv pip install -r requirements.txt

# 4. Gotowe! Używaj uv run zamiast python
uv run --no-project app.py
```

## Zasoby

- Dokumentacja: https://docs.astral.sh/uv/
- GitHub: https://github.com/astral-sh/uv
- Blog: https://astral.sh/blog

## FAQ

**Q: Czy uv jest kompatybilne z pip?**
A: Tak! uv używa tych samych formatów (requirements.txt, pyproject.toml, wheel).

**Q: Czy mogę używać uv i pip jednocześnie?**
A: Technicznie tak, ale nie jest to zalecane. Wybierz jedno.

**Q: Co jeśli pakiet nie działa z uv?**
A: Bardzo rzadki przypadek. Zawsze możesz wrócić do pip w konkretnym środowisku.

**Q: Czy uv obsługuje editable installs?**
A: Tak! `uv pip install -e .`

**Q: Gdzie jest cache pakietów?**
A: `~/.cache/uv/` (Linux/macOS) lub `%LOCALAPPDATA%\uv\cache` (Windows)