Metadata-Version: 2.4
Name: kuonen-ksql
Version: 2.0.0
Summary: Treiber für den KSQL-Zugang von KuonenSQL (TDS 7.4, DB-API 2.0, Schnittstelle wie mssql-python)
Author: Marc Kuonen
License: Proprietär (Marc Kuonen)
Keywords: kuonensql,ksql,tds,dbapi,sql
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Front-Ends
Classifier: License :: Other/Proprietary License
Classifier: Private :: Do Not Upload
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ksql – Python-Treiber für den KSQL-Zugang (D36.7)

Eigenbau ohne Fremdabhängigkeiten (Python 3.10+, nur Standardbibliothek, TLS über `ssl`). Er spricht TDS 7.4 mit dem
KSQL-Profil (`KuonenSQL/docs/ksql-protokollprofil.md`) und arbeitet auch an SQL Server. Die Schnittstelle folgt PEP 249 und
`mssql-python`; übernommen sind nur Schnittstelle und gemessenes Verhalten, kein Code (Vorgabe Meilenstein 36).

```python
import ksql

conn = ksql.connect("Server=localhost,1333;UID=sa;PWD=…;Encrypt=yes;TrustServerCertificate=yes", autocommit=True)
cur = conn.cursor()
cur.execute("SELECT ? AS a, ? AS b", (42, "Grüezi"))
print(cur.fetchall())
```

| | |
|---|---|
| `connect(connection_str, autocommit=False, timeout=0, **schlüssel)` | Schlüssel wie „ODBC Driver 18 for SQL Server“: `Server` (`host,port`, Vorgabeport 1333, oder `host\instanz`: dann nennt der SQL Browser den Port), `Database`, `UID`, `PWD`, `Encrypt` (`yes`/`no`/`strict`), `TrustServerCertificate`, `HostNameInCertificate`, `Connect Timeout`, `APP`, `WSID`, `Packet Size`, `ApplicationIntent` |
| `paramstyle` | `qmark` (`?`); dazu `@name` mit einer Zuordnung oder `ksql.Param(name=…)` |
| `ksql.Param(value, sqltype, direction, name)` | Parameter mit SQL-Typ (`decimal(9,2)`, `nvarchar(max)` …) und Richtung `ksql.IN`/`OUT`/`INOUT`; Ausgaben stehen nach dem Lesen aller Mengen in `value` |
| `Cursor.callproc(name, params)` | RPC auf eine Prozedur; Rückgabestatus in `return_value` |
| `ksql.TableValue(type_name, columns, rows)` | Tabellenwertparameter: der Tabellentyp (`dbo.Liste`), die SQL-Typen der Spalten (`["int", "nvarchar(20)"]`), die Zeilen; als Wert für `?` oder in `callproc` (dort darf der Name fehlen, dann gilt der Tabellentyp des Prozedurparameters) |
| `Cursor.bulkcopy(table, rows, columns)` | Massenkopie (INSERT BULK und BULK LOAD) |
| `Cursor.cancel()` | Abbruch mit ATTENTION, auch aus einem anderen Faden (`OperationalError`, SQLSTATE `HY008`) |
| `Cursor.timeout`, `connect(timeout=…)` | Befehlsfrist; nach Ablauf ATTENTION, dann `OperationalError` mit SQLSTATE `HYT00` |
| `Cursor.column_types` | die SQL-Typen der Spalten (`nvarchar(20)`, `decimal(9,2)`, KSQL-Typen mit ihrem Namen auf der Leitung, `BOOLEAN` für bit mit dem Benutzertyp 16) |
| `Connection.begin()`, `.savepoint(name)`, `.rollback(savepoint=…)` | Transaktion über die Transaction-Manager-Anfrage |

**Fehler** nach PEP 249 (`DataError`, `IntegrityError`, `ProgrammingError`, `OperationalError` …) mit `number`, `severity`,
`state`, `message`, `sqlstate` und `server_sqlstate`. Am KSQL-Port ist `sqlstate` der Zustand der Norm vom Meldungsende; an
SQL Server bildet der Treiber ihn aus der Nummer wie die ODBC-Treiber von Microsoft (`server_sqlstate` ist dort `None`).

**KSQL-Typen:** `BOOLEAN` → `bool`, `DECFLOAT` → `decimal.Decimal`, `INTERVAL`/`ROW`/`ARRAY`/`MULTISET` → die Textklassen
`ksql.Interval`, `ksql.Row`, `ksql.Array`, `ksql.Multiset`. `time(7)`/`datetime2(7)` verlieren die siebte Stelle nicht: sie steht
in `nanosecond` (`ksql.Zeit`, `ksql.Zeitpunkt`).

**Umleitung:** nennt der Server nach der Anmeldung einen anderen (ENVCHANGE 20), meldet sich der Treiber dort neu an (höchstens 5 Mal).

**Nicht eingebaut:** Windows- und Entra-Anmeldung, MARS, Always Encrypted.

## Prüfen

```bash
python -m unittest discover -s tests                     # Robustheit gegen verfälschte Antworten, Einheiten
KSQL_KENNWORT=… python konformitaet.py --server host,1333 --ziel ksql --katalog ../../../KuonenSQL/tools/ksql-konformitaet/faelle.json
pwsh ../../../KuonenSQL/docker/ksql-treiber/pruefstand.ps1 -Sprache python -Server host.docker.internal,1333   # im Abbild python:3.12-slim
```
