# Installation

## Für End-User (mit pip)

### Basis-Installation

```bash
pip install questra-data
```

### Mit pandas-Unterstützung

```bash
# pandas als extra installieren (empfohlen)
pip install questra-data[pandas]

# Oder als separate Installation
pip install questra-data
pip install pandas>=2.0.0
```

## Für Entwickler (mit uv)

### 1. uv installieren

**Windows (PowerShell):**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

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

**PATH konfigurieren** (falls nicht automatisch geschehen):

```bash
# Bash/Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Oder für Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Verifizierung:**

```bash
uv --version
```

### 2. Projekt aufsetzen

```bash
# Repository klonen
git clone <repo-url>
cd questra-data

# Dependencies installieren (nutzt .python-version für Python 3.10)
uv sync --all-groups
```

**Hinweis:** `uv sync` installiert automatisch die korrekte Python-Version (3.10) und erstellt ein Virtual Environment in `.venv/`.

### 3. Arbeitsablauf

**Code ausführen:**

```bash
# Beispiele ausführen
uv run python example_highlevel_usage.py

# Tests
uv run pytest
uv run pytest --cov=questra_data  # Mit Coverage
uv run pytest tests/test_pandas_integration.py  # Nur pandas Tests

# Linting & Formatting
uv run ruff check src/
uv run ruff format src/
```

**Dependencies verwalten:**

```bash
# Package hinzufügen
uv add requests

# Dev-Dependency hinzufügen
uv add --group dev pytest

# Package entfernen
uv remove requests

# Dependencies aktualisieren
uv sync
```

**Publishing:**

```bash
# Build
uv build

# Publish zu TestPyPI
uv publish --index testpypi

# Publish zu PyPI
uv publish
```

### Dependency Groups

Das Projekt nutzt `[dependency-groups]` für optionale Dependencies:

```bash
# Basis-Installation
uv sync

# Mit spezifischen Groups
uv sync --group pandas           # pandas-Unterstützung
uv sync --group dev              # Jupyter, ipykernel, ruff
uv sync --group docs             # mkdocs, mkdocs-material
uv sync --group test             # pytest, pytest-cov

# Mehrere Groups
uv sync --group pandas --group dev

# Alle Groups (empfohlen für Entwicklung)
uv sync --all-groups
```

## Python-Version

**Supported:** Python >=3.10
**Development:** Python 3.10 (definiert in `.python-version`)

**Warum 3.10 als Standard?**

- Entwicklung gegen älteste unterstützte Version verhindert versehentliche Nutzung neuerer Features
- Code auf 3.10 läuft auf 3.11+, aber nicht umgekehrt
- CI/CD testet gegen alle Versionen (3.10-3.14)

### Python-Version wechseln (optional)

```bash
# Verfügbare Versionen anzeigen
uv python list

# Andere Version nutzen
uv python pin 3.11

# .venv neu erstellen
rm -rf .venv
uv sync --all-groups

# Version prüfen
uv run python --version
```

## pyproject.toml Konfiguration

Die `pyproject.toml` unterstützt beide Paketmanager:

**Für pip (optional-dependencies):**

```toml
[project.optional-dependencies]
pandas = ["pandas>=2.0.0"]
```

Installation: `pip install questra-data[pandas]`

**Für uv (dependency-groups):**

```toml
[dependency-groups]
pandas = ["pandas (>=2.0.0)"]
dev = [...]
docs = [...]
test = [...]
```

Installation: `uv sync --group pandas`

## Verifizierung

**pandas verfügbar?**

```python
from questra_data import QuestraData

try:
    df = client.list_timeseries_values_df(...)
    print("✓ pandas ist verfügbar")
except ImportError as e:
    print(f"✗ pandas fehlt: {e}")
    print("  Installation: uv sync --group pandas")
```

**Python-Version:**

```bash
uv run python --version
# Sollte ausgeben: Python 3.10.x (oder höher)
```

## Troubleshooting

### "uv: command not found"

Stelle sicher, dass `~/.local/bin` in deinem `PATH` ist:

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

Füge diese Zeile zu deiner Shell-Config hinzu (`.bashrc`, `.zshrc`, etc.).

### "Package nicht gefunden auf TestPyPI"

Das Projekt nutzt `questra-authentication` von TestPyPI. Die `pyproject.toml` ist konfiguriert mit:

```toml
[tool.uv]
index-strategy = "unsafe-best-match"

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
```

Dies erlaubt uv, Packages von mehreren Indizes zu laden.

### pandas wird nicht erkannt

```bash
# Verifizieren
uv run python -c "import pandas; print(pandas.__version__)"

# Installieren
uv sync --group pandas
```

### Virtual Environment Issues

```bash
# .venv neu erstellen
rm -rf .venv
uv sync --all-groups
```

### Python-Version Konflikte

```bash
# Python 3.11 nutzen (falls gewünscht)
uv python pin 3.11
rm -rf .venv
uv sync --all-groups
```

**Hinweis:** Entwicklung auf 3.10 empfohlen für maximale Kompatibilität.
