duckgresql 1.4.4.0__tar.gz

duckgresql-1.4.4.0/.env.example

@@ -0,0 +1,21 @@
+# DuckGresQL Python SDK — example environment variables
+# Copy to .env and set values. Do not commit .env.
+
+# -----------------------------------------------------------------------------
+# Runtime (used by the SDK when connecting to a server)
+# -----------------------------------------------------------------------------
+DUCKGRESQL_HOST=localhost
+DUCKGRESQL_FLIGHT_PORT=47470
+DUCKGRESQL_REST_PORT=3100
+DUCKGRESQL_USE_TLS=false
+DUCKGRESQL_REST_SCHEME=http
+
+# -----------------------------------------------------------------------------
+# Release build (only for `make py-sdk-inject-defaults` / building for PyPI)
+# Set in GitHub repo variables for CI, or here for local release testing.
+# -----------------------------------------------------------------------------
+# DUCKGRESQL_RELEASE_HOST=api.duckgresql.com
+# DUCKGRESQL_RELEASE_FLIGHT_PORT=47470
+# DUCKGRESQL_RELEASE_REST_PORT=3100
+# DUCKGRESQL_RELEASE_USE_TLS=true
+# DUCKGRESQL_RELEASE_REST_SCHEME=https

duckgresql-1.4.4.0/.env.prod.example

@@ -0,0 +1,11 @@
+# Production release defaults — used by `make test-pypi-install-prod`
+# Copy to .env.prod and fill in values. Do not commit .env.prod.
+
+DUCKGRESQL_RELEASE_HOST=api.duckgresql.io
+DUCKGRESQL_RELEASE_FLIGHT_PORT=47470
+DUCKGRESQL_RELEASE_REST_PORT=443
+DUCKGRESQL_RELEASE_USE_TLS=false
+DUCKGRESQL_RELEASE_REST_SCHEME=https
+
+DUCKGRESQL_TOKEN=dkgql_your_token_here
+DUCKGRESQL_DATABASE=your_database_name_or_uuid

duckgresql-1.4.4.0/.github/workflows/check.yml

@@ -0,0 +1,50 @@
+name: Python SDK
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: sdk-python-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,all]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/duckgresql/
+
+      - name: Test
+        run: pytest tests/ -v --tb=short
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*

duckgresql-1.4.4.0/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Python SDK Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write   # create GitHub Release
+  id-token: write  # required for PyPI trusted publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/duckgresql
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          echo "version=$TAG_VERSION" >> $GITHUB_OUTPUT
+          echo "Releasing version: $TAG_VERSION"
+
+      - name: Verify version matches pyproject.toml
+        run: |
+          PACKAGE_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])" 2>/dev/null || python -c "exec(open('src/duckgresql/_version.py').read()); print(__version__)")
+          if [ "$PACKAGE_VERSION" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Error: Tag version (${{ steps.version.outputs.version }}) does not match package version ($PACKAGE_VERSION)"
+            exit 1
+          fi
+
+      - name: Install dependencies and run tests
+        run: |
+          pip install -e ".[dev,all]"
+          ruff check src/ tests/
+          mypy src/duckgresql/
+          pytest tests/ -v
+
+      - name: Inject release defaults
+        env:
+          DUCKGRESQL_RELEASE_HOST: ${{ vars.DUCKGRESQL_RELEASE_HOST }}
+          DUCKGRESQL_RELEASE_FLIGHT_PORT: ${{ vars.DUCKGRESQL_RELEASE_FLIGHT_PORT }}
+          DUCKGRESQL_RELEASE_REST_PORT: ${{ vars.DUCKGRESQL_RELEASE_REST_PORT }}
+          DUCKGRESQL_RELEASE_USE_TLS: ${{ vars.DUCKGRESQL_RELEASE_USE_TLS }}
+          DUCKGRESQL_RELEASE_REST_SCHEME: ${{ vars.DUCKGRESQL_RELEASE_REST_SCHEME }}
+        run: python scripts/inject_release_defaults.py
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: false
+          verbose: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: Python SDK v${{ steps.version.outputs.version }}
+          body: |
+            ## Python SDK v${{ steps.version.outputs.version }}
+
+            Install from PyPI:
+            ```bash
+            pip install duckgresql==${{ steps.version.outputs.version }}
+            ```
+
+            [View on PyPI](https://pypi.org/project/duckgresql/${{ steps.version.outputs.version }}/)
+          files: |
+            dist/*

duckgresql-1.4.4.0/.gitignore

@@ -0,0 +1,68 @@
+# Virtual environments
+.venv/
+.venv-pypi-test/
+venv/
+env/
+.env/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg
+*.egg-info/
+.eggs/
+dist/
+build/
+*.manifest
+*.spec
+
+# Hatch
+.hatch/
+
+# Installer
+*.whl
+*.tar.gz
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local env / secrets
+.env
+.env.prod
+.env.local
+.env.*.local
+*.local
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Distribution / packaging (keep dist out; built in CI)
+*.egg-info/
+*.egg

duckgresql-1.4.4.0/.python-version

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

duckgresql-1.4.4.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to the DuckGresQL Python SDK
+
+This document is for **developers of the SDK** (contributors and maintainers). For using the library, see [README.md](README.md).
+
+## Prerequisites
+
+- **Python 3.13+** (SDK development; end users can install with Python 3.11+)
+- [uv](https://docs.astral.sh/uv/) for installs and scripts
+- `.python-version` in the repo pins Python 3.13
+
+## Development Setup
+
+```bash
+make install    # uv sync (editable install + dev + all extras)
+make test       # pytest
+make lint       # ruff check
+make typecheck  # mypy
+make build      # build wheel + sdist
+```
+
+Other targets: `make format`, `make inject-defaults`, `make publish`, `make help`.
+
+## Testing the Package as if Installed from PyPI
+
+To verify the library works the same way end users get it (from a built wheel, not editable):
+
+1. **Install tools and build the package**
+   ```bash
+   make install
+   make build
+   ```
+
+2. **Create a clean environment and install only the wheel** (no repo code)
+   ```bash
+   uv venv .venv-pypi-test --python 3.13
+   uv pip install --python .venv-pypi-test/bin/python dist/duckgresql-*.whl
+   ```
+
+3. **Use it like a normal install**
+   ```bash
+   .venv-pypi-test/bin/python -c "
+   import duckgresql
+   print('Version:', duckgresql.__version__)
+   # Optional: connect if you have a running DuckGresQL server
+   # conn = duckgresql.connect(token='dkgql_...', database='mydb')
+   # print(conn.execute('SELECT 1').fetchone())
+   "
+   ```
+   Or run your own script: `.venv-pypi-test/bin/python your_script.py`
+
+4. **Optional: match production defaults before building**  
+   If you want the same defaults as the published package, set release env vars and inject before building:
+   ```bash
+   export DUCKGRESQL_RELEASE_HOST=api.duckgresql.com
+   export DUCKGRESQL_RELEASE_FLIGHT_PORT=47470
+   export DUCKGRESQL_RELEASE_REST_PORT=3100
+   make inject-defaults
+   make build
+   ```
+   Then repeat steps 2–3 with the new `dist/` wheel.
+
+You can also run **`make test-pypi-install`** to build, create `.venv-pypi-test`, install the wheel, and run a quick import/version check.
+
+## Version Scheme
+
+The SDK version (`1.4.4.0`) tracks DuckDB version `1.4.4`, with the last digit as the SDK patch version.
+
+## Publishing
+
+See [RELEASING.md](RELEASING.md) for instructions on publishing new versions to PyPI.

duckgresql-1.4.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DuckGresQL Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

duckgresql-1.4.4.0/Makefile

@@ -0,0 +1,55 @@
+.PHONY: help install test lint format typecheck inject-defaults build publish test-pypi-install
+
+# Default target
+.DEFAULT_GOAL := help
+
+# UV uses .python-version (3.13) and installs that Python if missing. No need to choose a version.
+UV ?= uv
+
+##@ Python SDK
+
+help: ## Display this help message
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+install: ## Sync deps with UV (editable install + dev + all extras; uses .python-version; UV installs Python 3.13 if needed)
+	$(UV) sync --extra dev --extra all
+
+test: ## Run unit tests
+	$(UV) run pytest tests/ -v
+
+lint: ## Lint code
+	$(UV) run ruff check src/ tests/
+
+format: ## Format code
+	$(UV) run ruff format src/ tests/
+
+typecheck: ## Type-check with mypy
+	$(UV) run mypy src/duckgresql/
+
+inject-defaults: ## Inject release defaults into _config.py (requires DUCKGRESQL_RELEASE_* env vars)
+	$(UV) run python scripts/inject_release_defaults.py
+
+build: ## Build package
+	$(UV) run python -m build
+
+publish: ## Publish to PyPI (requires TWINE_PASSWORD or trusted publishing)
+	$(UV) run python -m twine upload dist/*
+
+test-pypi-install: ## Build, install wheel into .venv-pypi-test, and verify (simulate PyPI install)
+	$(UV) run python -m build
+	$(UV) venv .venv-pypi-test --python 3.13
+	$(UV) pip install --python .venv-pypi-test/bin/python dist/duckgresql-*.whl
+	@echo "--- Done. Use: .venv-pypi-test/bin/python your_script.py <sql_query> ---"
+
+test-pypi-install-prod: ## Like test-pypi-install but with production defaults from .env.prod. Usage: make test-pypi-install-prod Q="SELECT 1"
+	@test -f .env.prod || { echo "Error: .env.prod not found. Copy .env.prod.example and fill in values."; exit 1; }
+	@test -n "$(Q)" || { echo "Error: query required. Usage: make test-pypi-install-prod Q=\"SELECT 1\""; exit 1; }
+	@# Load .env.prod, inject production config, build, restore dev config, then install
+	set -a && . ./.env.prod && set +a && $(UV) run python scripts/inject_release_defaults.py
+	$(UV) run python -m build
+	git checkout src/duckgresql/_config.py
+	rm -rf .venv-pypi-test
+	$(UV) venv .venv-pypi-test --python 3.13
+	$(UV) pip install --python .venv-pypi-test/bin/python dist/duckgresql-*.whl
+	$(UV) pip install --python .venv-pypi-test/bin/python python-dotenv
+	.venv-pypi-test/bin/python example/run_query.py --env .env.prod "$(Q)"

duckgresql-1.4.4.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: duckgresql
+Version: 1.4.4.0
+Summary: Python SDK for DuckGresQL — DuckDB-compatible API for remote databases
+Project-URL: Homepage, https://github.com/duckgresql/duckgresql
+Project-URL: Documentation, https://github.com/duckgresql/duckgresql/tree/main/sdk/python
+Project-URL: Repository, https://github.com/duckgresql/duckgresql
+Author: DuckGresQL Team
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: pyarrow>=18.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: all
+Requires-Dist: numpy>=1.26; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.26; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# DuckGresQL Python SDK
+
+Python client for [DuckGresQL](https://github.com/jjballano/duckgresql) — a DuckDB-compatible API for remote databases. Uses **Arrow Flight SQL** for fast query execution and a REST API for async job management.
+
+## Installation
+
+Requires Python 3.11+
+
+```bash
+pip install duckgresql
+```
+
+With optional extras:
+
+```bash
+pip install duckgresql[pandas]   # adds fetchdf() support
+pip install duckgresql[all]      # pandas + numpy
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+import duckgresql
+
+conn = duckgresql.connect(
+    token="dkgql_your_api_token",
+    database="my_database",
+)
+
+# Execute a query
+result = conn.execute("SELECT * FROM users LIMIT 10")
+print(result.fetchall())
+
+# Get a pandas DataFrame
+df = conn.execute("SELECT * FROM sales").fetchdf()
+
+# DML
+result = conn.execute("INSERT INTO users (name) VALUES ('Alice')")
+print(result.rowcount)  # affected rows
+
+conn.close()
+```
+
+### Async
+
+```python
+import asyncio
+import duckgresql
+
+async def main():
+    conn = await duckgresql.connect_async(
+        token="dkgql_your_api_token",
+        database="my_database",
+    )
+
+    result = await conn.execute("SELECT * FROM users")
+    print(result.fetchall())
+
+    await conn.close()
+
+asyncio.run(main())
+```
+
+### Context Manager
+
+```python
+with duckgresql.connect(token="...", database="...") as conn:
+    result = conn.execute("SELECT 1")
+    print(result.fetchone())
+```
+
+### Async Jobs (Long-Running Queries)
+
+```python
+conn = duckgresql.connect(token="...", database="...")
+
+job = conn.execute_async("SELECT * FROM very_large_table")
+print(f"Job submitted: {job.job_id}")
+
+# Poll until done (with exponential backoff)
+result = job.result(timeout=600)
+print(result.fetchall())
+```
+
+## Connection Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `token` | *required* | API token (`dkgql_…`) |
+| `database` | *required* | Database name or UUID |
+
+## Result Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `fetchone()` | `tuple \| None` | Next row |
+| `fetchmany(size)` | `list[tuple]` | Up to *size* rows |
+| `fetchall()` | `list[tuple]` | All remaining rows |
+| `fetchdf()` | `DataFrame` | Pandas DataFrame (requires `pandas`) |
+| `fetchnumpy()` | `dict[str, ndarray]` | NumPy arrays (requires `numpy`) |
+| `fetch_arrow_table()` | `pyarrow.Table` | Zero-copy Arrow table |
+
+## Result Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | `list \| None` | DB-API 2.0 column metadata |
+| `rowcount` | `int` | Row count or affected rows |
+| `columns` | `list[str]` | Column names |
+
+## Architecture
+
+- **Arrow Flight SQL (gRPC)** — Primary transport for `execute()`. Fast, columnar, zero-copy.
+- **REST API** — Used only for `execute_async()` (job submission/polling), since Flight SQL has no native job queue pattern.
+
+Both transports authenticate via the same API token. Flight SQL uses BasicAuth handshake; REST uses the `/connect` endpoint to exchange the token for a session token.
+
+---
+
+**Developing the SDK?** See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, building, and publishing.

duckgresql-1.4.4.0/README.md

@@ -0,0 +1,122 @@
+# DuckGresQL Python SDK
+
+Python client for [DuckGresQL](https://github.com/jjballano/duckgresql) — a DuckDB-compatible API for remote databases. Uses **Arrow Flight SQL** for fast query execution and a REST API for async job management.
+
+## Installation
+
+Requires Python 3.11+
+
+```bash
+pip install duckgresql
+```
+
+With optional extras:
+
+```bash
+pip install duckgresql[pandas]   # adds fetchdf() support
+pip install duckgresql[all]      # pandas + numpy
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+import duckgresql
+
+conn = duckgresql.connect(
+    token="dkgql_your_api_token",
+    database="my_database",
+)
+
+# Execute a query
+result = conn.execute("SELECT * FROM users LIMIT 10")
+print(result.fetchall())
+
+# Get a pandas DataFrame
+df = conn.execute("SELECT * FROM sales").fetchdf()
+
+# DML
+result = conn.execute("INSERT INTO users (name) VALUES ('Alice')")
+print(result.rowcount)  # affected rows
+
+conn.close()
+```
+
+### Async
+
+```python
+import asyncio
+import duckgresql
+
+async def main():
+    conn = await duckgresql.connect_async(
+        token="dkgql_your_api_token",
+        database="my_database",
+    )
+
+    result = await conn.execute("SELECT * FROM users")
+    print(result.fetchall())
+
+    await conn.close()
+
+asyncio.run(main())
+```
+
+### Context Manager
+
+```python
+with duckgresql.connect(token="...", database="...") as conn:
+    result = conn.execute("SELECT 1")
+    print(result.fetchone())
+```
+
+### Async Jobs (Long-Running Queries)
+
+```python
+conn = duckgresql.connect(token="...", database="...")
+
+job = conn.execute_async("SELECT * FROM very_large_table")
+print(f"Job submitted: {job.job_id}")
+
+# Poll until done (with exponential backoff)
+result = job.result(timeout=600)
+print(result.fetchall())
+```
+
+## Connection Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `token` | *required* | API token (`dkgql_…`) |
+| `database` | *required* | Database name or UUID |
+
+## Result Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `fetchone()` | `tuple \| None` | Next row |
+| `fetchmany(size)` | `list[tuple]` | Up to *size* rows |
+| `fetchall()` | `list[tuple]` | All remaining rows |
+| `fetchdf()` | `DataFrame` | Pandas DataFrame (requires `pandas`) |
+| `fetchnumpy()` | `dict[str, ndarray]` | NumPy arrays (requires `numpy`) |
+| `fetch_arrow_table()` | `pyarrow.Table` | Zero-copy Arrow table |
+
+## Result Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | `list \| None` | DB-API 2.0 column metadata |
+| `rowcount` | `int` | Row count or affected rows |
+| `columns` | `list[str]` | Column names |
+
+## Architecture
+
+- **Arrow Flight SQL (gRPC)** — Primary transport for `execute()`. Fast, columnar, zero-copy.
+- **REST API** — Used only for `execute_async()` (job submission/polling), since Flight SQL has no native job queue pattern.
+
+Both transports authenticate via the same API token. Flight SQL uses BasicAuth handshake; REST uses the `/connect` endpoint to exchange the token for a session token.
+
+---
+
+**Developing the SDK?** See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, building, and publishing.