py-flink-sql-gateway 0.1.0.dev0__tar.gz

py_flink_sql_gateway-0.1.0.dev0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run unit tests
+        run: uv run pytest tests/test_client.py tests/test_dbapi.py -v
+
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run integration tests
+        run: uv run pytest tests/test_integration.py -v -s -m integration

py_flink_sql_gateway-0.1.0.dev0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for hatch-vcs
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

py_flink_sql_gateway-0.1.0.dev0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.idea
+
+# Auto-generated version file
+src/flink_gateway/_version.py

py_flink_sql_gateway-0.1.0.dev0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+default_language_version:
+  python: python3.13
+fail_fast: false
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: debug-statements
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+  - repo: https://github.com/pre-commit/mirrors-isort
+    rev: v5.10.1
+    hooks:
+      - id: isort
+  - repo: https://github.com/ambv/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.0.272
+    hooks:
+      - id: ruff
+        args: [--no-cache]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.3.0
+    hooks:
+      - id: mypy
+      #  additional_dependencies: [types-all]

py_flink_sql_gateway-0.1.0.dev0/.python-version

@@ -0,0 +1 @@
+3.13

py_flink_sql_gateway-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: py-flink-sql-gateway
+Version: 0.1.0.dev0
+Summary: A Python client for the Apache Flink SQL Gateway REST API
+Author-email: Ilya Soin <ilya.soin@exness.com>
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# py-flink-sql-gateway
+
+A lightweight Python driver for the **Apache Flink SQL Gateway**, implementing [PEP 249 (DB-API 2.0)](https://peps.python.org/pep-0249/).
+
+## Installation
+
+```bash
+pip install py-flink-sql-gateway
+```
+
+## Quick start
+
+```python
+from flink_gateway import connect
+
+with connect("http://localhost:8083") as conn:
+    # Create a streaming source
+    with conn.cursor() as cur:
+        cur.execute("""
+            CREATE TABLE orders (
+                id INT NOT NULL,
+                item STRING NOT NULL,
+                created_at TIMESTAMP(6) NOT NULL,
+                customer ROW<
+                    first_name STRING NOT NULL,
+                    last_name STRING NOT NULL,
+                    age INT NOT NULL
+                > NOT NULL,
+                notes STRING
+            ) WITH (
+                'connector' = 'datagen',
+                'rows-per-second' = '5',
+                'fields.id.kind' = 'sequence',
+                'fields.id.start' = '1',
+                'fields.id.end' = '100',
+                'fields.item.length' = '12',
+                'fields.customer.first_name.length' = '8',
+                'fields.customer.last_name.length' = '10',
+                'fields.customer.age.min' = '21',
+                'fields.customer.age.max' = '65',
+                'fields.notes.length' = '12'
+            )
+        """)
+
+    # Query and iterate
+    with conn.cursor() as cur:
+        cur.execute("""
+            SELECT id, item, created_at, customer, notes AS note
+            FROM orders
+        """)
+        for i, row in enumerate(cur):
+            id_, item, created_at, customer, note = row
+            print(
+                f"{id_}\t{item}\t{created_at.isoformat()}\t"
+                f"{customer['first_name']} {customer['last_name']} ({customer['age']})\t"
+                f"{note or ''}"
+            )
+            if i >= 4:
+                break
+```
+
+> **Tip:** `ROW` and `MAP` types arrive as Python `dict`, `ARRAY` arrives as `list`. Binary data is passed through as-is.
+
+### Low-level REST access
+
+If you need features beyond DB-API, use the exported client directly:
+
+```python
+from flink_gateway import FlinkSqlGatewayClient
+
+with FlinkSqlGatewayClient("http://localhost:8083") as client:
+    status = client.get_operation_status("session-handle", "operation-handle")
+    print("current status:", status)
+```
+
+## Type mapping
+
+Python uses `None` for SQL NULLs natively — no wrapper types needed.
+
+| Flink Type                | Python Type        |
+|---------------------------|--------------------|
+| TINYINT / SMALLINT / INT  | `int`              |
+| BIGINT / INTERVAL         | `int`              |
+| FLOAT / DOUBLE            | `float`            |
+| BOOLEAN                   | `bool`             |
+| CHAR / VARCHAR / STRING   | `str`              |
+| DECIMAL                   | `decimal.Decimal`  |
+| DATE                      | `datetime.date`    |
+| TIME                      | `datetime.time`    |
+| TIMESTAMP / TIMESTAMP_LTZ | `datetime.datetime`|
+| BINARY / VARBINARY        | raw (passthrough)  |
+| ROW                       | `dict`             |
+| MAP                       | `dict`             |
+| ARRAY                     | `list`             |
+
+---
+
+## Development & tests
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install dependencies
+uv sync
+
+# Run unit tests (no Docker needed)
+uv run pytest tests/test_client.py tests/test_dbapi.py -v
+
+# Run all tests including integration (requires Docker)
+uv run pytest tests/ -v
+```
+
+Integration tests spin up a Flink cluster (JobManager + TaskManager + SQL Gateway) via [testcontainers-python](https://testcontainers-python.readthedocs.io/).
+
+---
+
+## License
+
+MIT (see LICENSE)

py_flink_sql_gateway-0.1.0.dev0/README.md

@@ -0,0 +1,119 @@
+# py-flink-sql-gateway
+
+A lightweight Python driver for the **Apache Flink SQL Gateway**, implementing [PEP 249 (DB-API 2.0)](https://peps.python.org/pep-0249/).
+
+## Installation
+
+```bash
+pip install py-flink-sql-gateway
+```
+
+## Quick start
+
+```python
+from flink_gateway import connect
+
+with connect("http://localhost:8083") as conn:
+    # Create a streaming source
+    with conn.cursor() as cur:
+        cur.execute("""
+            CREATE TABLE orders (
+                id INT NOT NULL,
+                item STRING NOT NULL,
+                created_at TIMESTAMP(6) NOT NULL,
+                customer ROW<
+                    first_name STRING NOT NULL,
+                    last_name STRING NOT NULL,
+                    age INT NOT NULL
+                > NOT NULL,
+                notes STRING
+            ) WITH (
+                'connector' = 'datagen',
+                'rows-per-second' = '5',
+                'fields.id.kind' = 'sequence',
+                'fields.id.start' = '1',
+                'fields.id.end' = '100',
+                'fields.item.length' = '12',
+                'fields.customer.first_name.length' = '8',
+                'fields.customer.last_name.length' = '10',
+                'fields.customer.age.min' = '21',
+                'fields.customer.age.max' = '65',
+                'fields.notes.length' = '12'
+            )
+        """)
+
+    # Query and iterate
+    with conn.cursor() as cur:
+        cur.execute("""
+            SELECT id, item, created_at, customer, notes AS note
+            FROM orders
+        """)
+        for i, row in enumerate(cur):
+            id_, item, created_at, customer, note = row
+            print(
+                f"{id_}\t{item}\t{created_at.isoformat()}\t"
+                f"{customer['first_name']} {customer['last_name']} ({customer['age']})\t"
+                f"{note or ''}"
+            )
+            if i >= 4:
+                break
+```
+
+> **Tip:** `ROW` and `MAP` types arrive as Python `dict`, `ARRAY` arrives as `list`. Binary data is passed through as-is.
+
+### Low-level REST access
+
+If you need features beyond DB-API, use the exported client directly:
+
+```python
+from flink_gateway import FlinkSqlGatewayClient
+
+with FlinkSqlGatewayClient("http://localhost:8083") as client:
+    status = client.get_operation_status("session-handle", "operation-handle")
+    print("current status:", status)
+```
+
+## Type mapping
+
+Python uses `None` for SQL NULLs natively — no wrapper types needed.
+
+| Flink Type                | Python Type        |
+|---------------------------|--------------------|
+| TINYINT / SMALLINT / INT  | `int`              |
+| BIGINT / INTERVAL         | `int`              |
+| FLOAT / DOUBLE            | `float`            |
+| BOOLEAN                   | `bool`             |
+| CHAR / VARCHAR / STRING   | `str`              |
+| DECIMAL                   | `decimal.Decimal`  |
+| DATE                      | `datetime.date`    |
+| TIME                      | `datetime.time`    |
+| TIMESTAMP / TIMESTAMP_LTZ | `datetime.datetime`|
+| BINARY / VARBINARY        | raw (passthrough)  |
+| ROW                       | `dict`             |
+| MAP                       | `dict`             |
+| ARRAY                     | `list`             |
+
+---
+
+## Development & tests
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install dependencies
+uv sync
+
+# Run unit tests (no Docker needed)
+uv run pytest tests/test_client.py tests/test_dbapi.py -v
+
+# Run all tests including integration (requires Docker)
+uv run pytest tests/ -v
+```
+
+Integration tests spin up a Flink cluster (JobManager + TaskManager + SQL Gateway) via [testcontainers-python](https://testcontainers-python.readthedocs.io/).
+
+---
+
+## License
+
+MIT (see LICENSE)

py_flink_sql_gateway-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "py-flink-sql-gateway"
+dynamic = ["version"]
+description = "A Python client for the Apache Flink SQL Gateway REST API"
+readme = "README.md"
+authors = [
+    { name = "Ilya Soin", email = "ilya.soin@exness.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "testcontainers>=4.14.1",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { version_scheme = "guess-next-dev" }
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/flink_gateway/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flink_gateway"]
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: end-to-end tests requiring Docker (Flink cluster)",
+]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["E402"]

py_flink_sql_gateway-0.1.0.dev0/src/flink_gateway/__init__.py

@@ -0,0 +1,104 @@
+"""Flink SQL Gateway — Python client library.
+
+Implements PEP 249 (DB-API 2.0) on top of the Flink SQL Gateway REST API.
+"""
+
+from flink_gateway.client import FlinkSqlGatewayClient
+from flink_gateway.connection import Connection, connect
+from flink_gateway.cursor import Cursor
+from flink_gateway.exceptions import (
+    DatabaseError,
+    Error,
+    FlinkSqlGatewayError,
+    InterfaceError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+)
+from flink_gateway.models import (
+    ColumnInfo,
+    CompleteStatementRequest,
+    ConfigureSessionRequest,
+    ExecuteStatementRequest,
+    FetchResultsResponse,
+    InfoResponse,
+    LogicalType,
+    OpenSessionRequest,
+    RefreshMaterializedTableRequest,
+    ResultKind,
+    ResultSet,
+    ResultType,
+    RowData,
+)
+from flink_gateway.types import (
+    BINARY,
+    DATETIME,
+    NUMBER,
+    ROWID,
+    STRING,
+    Binary,
+    Date,
+    DateFromTicks,
+    DBAPITypeObject,
+    FlinkType,
+    Time,
+    TimeFromTicks,
+    Timestamp,
+    TimestampFromTicks,
+)
+
+# PEP 249 module-level globals
+apilevel = "2.0"
+threadsafety = 1  # Threads may share the module but not connections.
+paramstyle = "qmark"
+
+__all__ = [
+    # PEP 249
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    "connect",
+    "Connection",
+    "Cursor",
+    # Exceptions
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "OperationalError",
+    "FlinkSqlGatewayError",
+    "ProgrammingError",
+    "NotSupportedError",
+    # Type objects
+    "STRING",
+    "BINARY",
+    "NUMBER",
+    "DATETIME",
+    "ROWID",
+    "DBAPITypeObject",
+    "FlinkType",
+    # PEP 249 constructors
+    "Date",
+    "Time",
+    "Timestamp",
+    "DateFromTicks",
+    "TimeFromTicks",
+    "TimestampFromTicks",
+    "Binary",
+    # Low-level client
+    "FlinkSqlGatewayClient",
+    "FlinkSqlGatewayError",
+    # Models
+    "ColumnInfo",
+    "CompleteStatementRequest",
+    "ConfigureSessionRequest",
+    "ExecuteStatementRequest",
+    "FetchResultsResponse",
+    "InfoResponse",
+    "LogicalType",
+    "OpenSessionRequest",
+    "RefreshMaterializedTableRequest",
+    "ResultKind",
+    "ResultSet",
+    "ResultType",
+    "RowData",
+]

py_flink_sql_gateway-0.1.0.dev0/src/flink_gateway/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0.dev0'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev0')
+
+__commit_id__ = commit_id = None