Metadata-Version: 2.4
Name: lhw_dbframe
Version: 0.3.1
Summary: Interner DB-Zugriff für Bestand-Daten (Postgres -> DataFrame)
Author: Ömer Kutsal
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: pandas
Requires-Dist: SQLAlchemy
Requires-Dist: psycopg2-binary
Dynamic: license-file

# dbframe

Internes Python-Paket für den direkten Zugriff auf Postgres-Daten des Amts für
Statistik und Stadtforschung. Liefert Bestand-, Ortsbezirk- und
Planungsraum-Daten direkt als `pandas.DataFrame` — ohne dass Nutzer:innen sich
um Verbindungsdaten, Schema-Namen oder SQL kümmern müssen.


## Schnellstart

```python
from dbframe import get_table, all_tables, get_ortsbezirk, get_planungsraum

# Bestand-Tabelle für Mai 2026 (Standard: table="bestand", schema="bevölkerung")
df = get_table(2026, 5)

# Anderes Präfix / anderes Schema, per Jahr/Monat
df = get_table(2026, 1, table="wohngeld", schema="wohngeld")

# Direkt per vollständigem Tabellennamen (ohne year/month)
df = get_table(table="bestand_202607", schema="bevölkerung")
df = get_table(table="bestand_data_dictionary", schema="bevölkerung")
df = get_table(table="regobz", schema="entwicklung")

# Alle vorhandenen Tabellen über alle Schemas hinweg
df_tabellen = all_tables()

# Ortsbezirk-Referenztabelle
df_ortsbezirk = get_ortsbezirk()

# Planungsraum-Referenztabelle
df_planungsraum = get_planungsraum()
```

## Funktionen

### `get_table(year=None, month=None, table="bestand", schema="bevölkerung")`

Lädt eine Tabelle als DataFrame. Zwei Anwendungsfälle:

**1. Mit year und month** — der Tabellenname wird als
`{table}_{Jahr}{Monat:02d}` zusammengesetzt, z. B. `bestand_202605`:

```python
df = get_table(2026, 5)
print(df.shape)   # (303987, 113)

df = get_table(2026, 5, table="bestand", schema="wohngeld")
```

**2. Ohne year/month** — `table` wird als vollständiger, exakter
Tabellenname verwendet. Praktisch für Tabellen ohne Jahr/Monat-Suffix oder
wenn der genaue Name schon bekannt ist (z. B. aus `all_tables()`):

```python
df = get_table(table="bestand_202607", schema="bevölkerung")
df = get_table(table="bestand_data_dictionary", schema="bevölkerung")
df = get_table(table="regobz", schema="entwicklung")
```

Wirft einen `ValueError` mit verständlicher Meldung, falls die Tabelle nicht
existiert. In dem Fall hilft `all_tables()`, um die tatsächlich vorhandenen
Schema/Tabelle-Kombinationen zu prüfen.

### `all_tables()`

Listet alle vorhandenen Tabellen **über alle Schemas hinweg** auf
(Systemschemas ausgenommen) und gibt sie als DataFrame mit den Spalten
`table_schema` und `table_name` zurück.

```python
from dbframe import all_tables

df_tabellen = all_tables()
print(df_tabellen.head())
#   table_schema        table_name
# 0  bevölkerung   bestand_202512
# 1  bevölkerung   bestand_202601
# 2   entwicklung          regobz
# 3      wohngeld  wohngeld_202601
```

### `get_ortsbezirk()`

Lädt die Ortsbezirk-Referenztabelle (`regobz_code`, `regobz_name`) aus dem
Schema `entwicklung`. `regobz_code` wird als String zurückgegeben (z. B.
`"01"`), damit führende Nullen nicht verloren gehen.

```python
df = get_ortsbezirk()
print(df.head())
#   regobz_code   regobz_name
# 0          01         Mitte
# 1          02       Nordost
```

### `get_planungsraum()`

Lädt die Planungsraum-Referenztabelle (`regplr_code`, `regplr_name`) aus dem
Schema `entwicklung`. `regplr_code` wird ebenfalls als String zurückgegeben
(z. B. `"111"`).

```python
df = get_planungsraum()
```

### `get_ortsbezirk_planungsraum()`

Lädt beide Referenztabellen gleichzeitig — praktisch, wenn beide gebraucht
werden.

```python
df_ortsbezirk, df_planungsraum = get_ortsbezirk_planungsraum()
```

## Hilfe zu einer Funktion anzeigen

```python
from dbframe import get_table
help(get_table)
```

In Jupyter/IPython genügt auch:

```python
get_table?
```

## Für Paket-Maintainer: neue Version bauen

Bei Änderungen an Verbindungsdaten, Funktionen oder Parametern:

1. `src/dbframe/config.toml` bzw. den betroffenen Code anpassen
2. Version in `pyproject.toml` erhöhen (z. B. `0.2.0` → `0.3.0`)
3. Alte Build-Artefakte entfernen und neu bauen:
   ```bash
   rmdir /s /q dist
   python -m build --no-isolation
   ```
4. Neue `.whl`-Datei ins gemeinsame Verzeichnis kopieren:
   ```bash
   copy dist\dbframe-0.3.0-py3-none-any.whl P:\Python\pakete\
   ```
5. Team informieren, insbesondere bei Änderungen an der Parameterreihenfolge
   bestehender Funktionen (kann bei alten Aufrufen zu stillen Fehlern führen,
   ohne dass eine Fehlermeldung erscheint). **Achtung — Breaking Changes:**
   - Version 0.2.0: `get_bestand()` wurde durch `get_table()` ersetzt.
   - Version 0.3.0: `get_table()` akzeptiert year/month jetzt optional
     (bei Weglassen wird `table` als vollständiger Tabellenname verwendet);
     `list_bestand_tables()` wurde durch `all_tables()` ersetzt und listet
     jetzt alle Tabellen (nicht nur das YYYYMM-Muster) über alle Schemas.

## Voraussetzungen

- Python ≥ 3.11
- pandas, SQLAlchemy, psycopg2-binary (werden bei der Installation über
  `--find-links` mitinstalliert, sofern im gemeinsamen Verzeichnis vorhanden)
