cdata-connect 0.0.1__tar.gz

cdata_connect-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,146 @@
+name: Release to PyPI
+
+# Triggered when a GitHub Release is published (which also creates the git tag).
+# Flow: test → build → publish PyPI → verify
+on:
+  release:
+    types: [published]
+
+jobs:
+  # ──────────────────────────────────────────────────────────────────
+  # 1. Run unit tests before building
+  # ──────────────────────────────────────────────────────────────────
+  test:
+    name: Test (Python 3.11)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: connector
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install connector + test deps
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run non-integration tests
+        run: |
+          pytest tests/ \
+            -k "test_apilevel or test_threadsafety or test_paramstyle or test_Exceptions or test_Date or test_Time or test_Timestamp or test_Binary or test_STRING or test_BINARY or test_NUMBER or test_DATETIME or test_ROWID" \
+            -v --tb=short
+        env:
+          CDATA_BASE_URL: http://localhost:8080/api
+          SKIP_LIVE_TESTS: "1"
+
+  # ──────────────────────────────────────────────────────────────────
+  # 2. Build wheel + sdist
+  # ──────────────────────────────────────────────────────────────────
+  build:
+    name: Build Distribution
+    needs: test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: connector
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history to derive version
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Validate distribution
+        run: twine check dist/*
+
+      - name: Smoke-test the wheel in a clean venv
+        run: |
+          python -m venv /tmp/wheel_test_env
+          /tmp/wheel_test_env/bin/pip install dist/*.whl
+          /tmp/wheel_test_env/bin/python -c "
+          import cdata_connect
+          assert cdata_connect.apilevel == '2.0'
+          assert cdata_connect.threadsafety == 1
+          assert cdata_connect.paramstyle == 'pyformat'
+          from cdata_connect import Connection, Error, STRING, BINARY, NUMBER, DATETIME, ROWID
+          from cdata_connect.util.types import FIELD_TYPES
+          print('Wheel smoke test passed. Version:', cdata_connect.__version__)
+          "
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-packages
+          path: connector/dist/
+          retention-days: 7
+
+  # ──────────────────────────────────────────────────────────────────
+  # 3. Publish to production PyPI
+  # Gated by the 'pypi' GitHub Environment — add required reviewers in
+  # Settings > Environments > pypi > Required reviewers.
+  # Uses OIDC Trusted Publishing — no API token required.
+  # ──────────────────────────────────────────────────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/cdata-connect/
+    permissions:
+      id-token: write  # Required for Trusted Publishing
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-packages
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true
+
+  # ──────────────────────────────────────────────────────────────────
+  # 4. Post-release verification
+  # ──────────────────────────────────────────────────────────────────
+  verify:
+    name: Verify PyPI Publication
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Determine release version from tag
+        id: version
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Wait for PyPI propagation
+        run: sleep 60
+
+      - name: Install from PyPI and verify
+        run: |
+          pip install "cdata-connect==${{ steps.version.outputs.version }}"
+          python -c "
+          import cdata_connect
+          print('Installed version:', cdata_connect.__version__)
+          assert cdata_connect.apilevel == '2.0'
+          assert cdata_connect.threadsafety == 1
+          assert cdata_connect.paramstyle == 'pyformat'
+          print('Post-release verification passed.')
+          "

cdata_connect-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,57 @@
+name: Tests
+
+on:
+  push:
+    branches: ["main", "develop"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install connector
+        working-directory: connector
+        run: |
+          pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-cov requests
+
+      - name: Install mock server dependencies
+        run: |
+          pip install -r ../connect-ai-mock/requirements.txt
+        working-directory: connector
+        # conftest.py auto-discovers the mock server at ../connect-ai-mock relative to connector/
+
+      - name: Run tests against mock API
+        run: pytest tests/ -v --tb=short
+        env:
+          CDATA_BASE_URL: http://localhost:8080/api
+          CDATA_USERNAME: test@example.com
+          CDATA_PASSWORD: any_token
+          SKIP_LIVE_TESTS: "1"
+          # conftest.py auto-starts the mock server on localhost:8080
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: build/coverage/
+          retention-days: 7

cdata_connect-0.0.1/.gitignore

@@ -0,0 +1,51 @@
+# setuptools-scm generated version file (written at build time)
+cdata_connect/_version.py
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Distribution / packaging (produced by `python -m build`)
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Wheel / sdist archives
+*.whl
+*.tar.gz
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type checkers
+.mypy_cache/
+.pytype/
+.pyre/
+
+# Local pyhocon config (users may create this for local testing)
+config.conf
+*.conf
+
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS noise
+.DS_Store
+Thumbs.db

cdata_connect-0.0.1/CLAUDE.md

@@ -0,0 +1,51 @@
+# Connector — AI Context
+
+This is the installable `cdata-connect` Python package — a DB-API 2.0 (PEP 249) connector for CData Connect AI.
+
+## Source Layout
+
+```
+cdata_connect/
+├── __init__.py         # Module exports, connect() factory, apilevel/threadsafety/paramstyle
+├── connection.py       # Connection class — auth, config, lifecycle, cursor creation
+├── cursor.py           # Cursor class — execute, fetch, streaming (ijson), retry logic
+├── exceptions.py       # PEP 249 exception hierarchy + ConfigurationError
+├── util/types.py       # Type mapping (Connect API ↔ Python), Date/Time/Timestamp/Binary
+├── log.py              # Logger (NullHandler)
+└── version.py          # __version__
+```
+
+## Architecture
+
+1. `connect()` → creates a `Connection` (validates params or reads PyHOCON config)
+2. `Connection.cursor()` → creates a `Cursor` (holds reference to Connection for auth/base_url)
+3. `Cursor.execute(query)` → `_execute_request()` → HTTP POST to `/api/query` with retry
+4. Response is streamed: `ijson.parse()` extracts schema, then `ijson.items()` yields rows lazily
+5. `fetchone()`/`fetchall()`/`fetchmany()` consume from the row generator
+
+## Key Patterns
+
+- **Retry logic** lives in `Cursor._execute_request()` — exponential backoff on 5xx/ConnectionError
+- **Type conversion**: `util/types.py:convert_to_python_type()` maps API type names → Python types
+- **Thread safety**: Connection uses `threading.local()`, Cursor uses `threading.Lock()`
+- **No-ops**: `commit()`, `rollback()`, `setinputsizes()`, `setoutputsize()` are intentional no-ops
+- **Exception hierarchy**: Must match PEP 249 exactly. `ConfigurationError` extends `Error` (custom addition)
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit/ -v        # 140 tests, no server, ~0.1s
+pytest tests/integration/ -v # 49 tests, mock server auto-starts, ~1s
+```
+
+- **Unit**: `tests/unit/` — fixtures `mock_connection`/`mock_cursor` (mocked HTTP). Never hit network.
+- **Integration**: `tests/integration/` — fixtures `con`/`cursor` (real HTTP to mock server).
+- **Mock scenarios**: PAT-based. `any_token`=default, `error_pat`=401, `large_pat`=100+ rows. See `../connect-ai-mock/src/data/static/scenarios.json`.
+
+## Build
+
+```bash
+pip install build && python -m build
+# Produces dist/cdata_connect-1.0.0-py3-none-any.whl
+```

cdata_connect-0.0.1/EXAMPLES.md

@@ -0,0 +1,315 @@
+# cdata-connect Usage Examples
+
+## Installation
+
+```bash
+pip install cdata-connect
+```
+
+## Basic Connection
+
+```python
+import cdata_connect
+
+conn = cdata_connect.connect(
+    base_url="https://cloud.cdata.com/api",
+    username="you@example.com",
+    password="<your_personal_access_token>",
+)
+```
+
+## Using Context Managers (Recommended)
+
+Connections and cursors support `with` statements for automatic cleanup:
+
+```python
+import cdata_connect
+
+with cdata_connect.connect(
+    base_url="https://cloud.cdata.com/api",
+    username="you@example.com",
+    password="<your_pat>",
+) as conn:
+    with conn.cursor() as cur:
+        cur.execute("SELECT * FROM [Salesforce1].[Salesforce].[Account]")
+        for row in cur:
+            print(row)
+# Connection and cursor are automatically closed here
+```
+
+## Querying Data
+
+### Fetch All Rows
+
+```python
+with conn.cursor() as cur:
+    cur.execute("SELECT Id, Name, Industry FROM [Salesforce1].[Salesforce].[Account]")
+    rows = cur.fetchall()
+    for row in rows:
+        print(f"Id={row[0]}, Name={row[1]}, Industry={row[2]}")
+```
+
+### Fetch One Row at a Time
+
+```python
+with conn.cursor() as cur:
+    cur.execute("SELECT * FROM [Salesforce1].[Salesforce].[Contact]")
+    while True:
+        row = cur.fetchone()
+        if row is None:
+            break
+        print(row)
+```
+
+### Fetch in Batches
+
+```python
+with conn.cursor() as cur:
+    cur.execute("SELECT * FROM [Salesforce1].[Salesforce].[Contact]")
+    while True:
+        batch = cur.fetchmany(100)  # 100 rows at a time
+        if not batch:
+            break
+        for row in batch:
+            process(row)
+```
+
+### Iterate Directly (PEP 249 Iterator Protocol)
+
+```python
+with conn.cursor() as cur:
+    cur.execute("SELECT Name, Email FROM [Salesforce1].[Salesforce].[Contact]")
+    for row in cur:
+        print(f"{row[0]} — {row[1]}")
+```
+
+## Column Metadata
+
+```python
+with conn.cursor() as cur:
+    cur.execute("SELECT Id, Name, AnnualRevenue FROM [Salesforce1].[Salesforce].[Account]")
+
+    # cursor.description is a list of 7-tuples per PEP 249
+    for col in cur.description:
+        name, type_code, display_size, length, precision, scale, nullable = col
+        print(f"Column: {name}, Type: {type_code}")
+
+    rows = cur.fetchall()
+```
+
+## Parameterized Queries
+
+The driver uses `pyformat` parameter style (`%(name)s` placeholders):
+
+```python
+with conn.cursor() as cur:
+    cur.execute(
+        "SELECT * FROM [DB].[public].[users] WHERE city = %(city)s AND age > %(min_age)s",
+        {"city": "New York", "min_age": 25},
+    )
+    rows = cur.fetchall()
+```
+
+## Insert, Update, Delete
+
+```python
+with conn.cursor() as cur:
+    # Insert
+    cur.execute("INSERT INTO [DB].[public].[users] (name, email) VALUES ('Alice', 'alice@example.com')")
+
+    # Update
+    cur.execute("UPDATE [DB].[public].[users] SET email = 'alice@new.com' WHERE name = 'Alice'")
+
+    # Delete
+    cur.execute("DELETE FROM [DB].[public].[users] WHERE name = 'Alice'")
+```
+
+## Batch Insert (executemany)
+
+```python
+with conn.cursor() as cur:
+    cur.executemany(
+        "INSERT INTO [DB].[public].[cities] (city, id) VALUES (@city, @id)",
+        [
+            {"@city": {"dataType": 5, "value": "New York"}, "@id": {"dataType": 8, "value": 1}},
+            {"@city": {"dataType": 5, "value": "London"},   "@id": {"dataType": 8, "value": 2}},
+            {"@city": {"dataType": 5, "value": "Tokyo"},    "@id": {"dataType": 8, "value": 3}},
+        ],
+    )
+```
+
+## Stored Procedures
+
+```python
+with conn.cursor() as cur:
+    result_args = cur.callproc("[DB].[public].[my_procedure]", ("arg1", "arg2"))
+    rows = cur.fetchall()
+    print(f"Input args returned: {result_args}")
+    print(f"Result rows: {rows}")
+```
+
+## Configuration File
+
+Keep credentials out of code using a [PyHOCON](https://github.com/chimpler/pyhocon) config file:
+
+```hocon
+# config.conf
+cdata_api_db {
+    base_url = "https://cloud.cdata.com/api"
+    username = "you@example.com"
+    password = "<your_personal_access_token>"
+}
+```
+
+```python
+conn = cdata_connect.connect(config_path="config.conf")
+```
+
+## Workspaces
+
+Access a specific CData Connect AI workspace:
+
+```python
+conn = cdata_connect.connect(
+    base_url="https://cloud.cdata.com/api",
+    username="you@example.com",
+    password="<your_pat>",
+    workspace="production",
+)
+```
+
+## Connection Options
+
+```python
+conn = cdata_connect.connect(
+    base_url="https://cloud.cdata.com/api",
+    username="you@example.com",
+    password="<your_pat>",
+    timeout=60,          # HTTP timeout in seconds (default: 30)
+    max_retries=5,       # Retries on 5xx errors (default: 3)
+    retry_delay=2.0,     # Base delay between retries in seconds (default: 1.0)
+)
+```
+
+## Error Handling
+
+```python
+import cdata_connect
+from cdata_connect.exceptions import (
+    InterfaceError,
+    OperationalError,
+    ProgrammingError,
+    DatabaseError,
+)
+
+try:
+    conn = cdata_connect.connect(
+        base_url="https://cloud.cdata.com/api",
+        username="you@example.com",
+        password="<your_pat>",
+    )
+    with conn.cursor() as cur:
+        cur.execute("SELECT * FROM [Salesforce1].[Salesforce].[Account]")
+        rows = cur.fetchall()
+
+except InterfaceError as e:
+    print(f"Connection/interface problem: {e}")
+
+except OperationalError as e:
+    print(f"Server error, timeout, or connectivity issue: {e}")
+
+except ProgrammingError as e:
+    print(f"Query error or fetch before execute: {e}")
+
+except DatabaseError as e:
+    print(f"General database error: {e}")
+
+finally:
+    if conn.is_open:
+        conn.close()
+```
+
+## Using with pandas
+
+```bash
+pip install "cdata-connect[full]"
+```
+
+```python
+import pandas as pd
+import cdata_connect
+
+conn = cdata_connect.connect(
+    base_url="https://cloud.cdata.com/api",
+    username="you@example.com",
+    password="<your_pat>",
+)
+
+with conn.cursor() as cur:
+    cur.execute("SELECT Id, Name, Industry, AnnualRevenue FROM [Salesforce1].[Salesforce].[Account]")
+    columns = [desc[0] for desc in cur.description]
+    rows = cur.fetchall()
+
+df = pd.DataFrame(rows, columns=columns)
+print(df.head())
+print(df.describe())
+
+conn.close()
+```
+
+## Type Objects
+
+PEP 249 type objects for use with `cursor.description`:
+
+```python
+import cdata_connect
+
+# Check column types from cursor.description
+with conn.cursor() as cur:
+    cur.execute("SELECT Id, Name, AnnualRevenue, CreatedDate FROM [Salesforce1].[Salesforce].[Account]")
+    for col in cur.description:
+        name, type_code = col[0], col[1]
+        if type_code == cdata_connect.STRING:
+            print(f"{name} is a string")
+        elif type_code == cdata_connect.NUMBER:
+            print(f"{name} is a number")
+        elif type_code == cdata_connect.DATETIME:
+            print(f"{name} is a datetime")
+        elif type_code == cdata_connect.BINARY:
+            print(f"{name} is binary")
+```
+
+## Date/Time Constructors
+
+PEP 249 date/time helper constructors:
+
+```python
+import cdata_connect
+
+d = cdata_connect.Date(2025, 3, 15)
+t = cdata_connect.Time(14, 30, 0)
+ts = cdata_connect.Timestamp(2025, 3, 15, 14, 30, 0)
+b = cdata_connect.Binary(b"raw bytes")
+
+# From Unix timestamps
+import time
+d2 = cdata_connect.DateFromTicks(time.time())
+t2 = cdata_connect.TimeFromTicks(time.time())
+ts2 = cdata_connect.TimestampFromTicks(time.time())
+```
+
+## Exception Hierarchy
+
+```
+cdata_connect.Warning           — Important warnings (subclass of Exception)
+cdata_connect.Error             — Base error class
+├── InterfaceError              — Connection/interface issues
+├── ConfigurationError          — Bad config file or missing parameters
+└── DatabaseError               — Database-related errors
+    ├── DataError               — Data processing errors (bad JSON, etc.)
+    ├── OperationalError        — Server errors, timeouts, connectivity
+    ├── IntegrityError          — Constraint violations
+    ├── InternalError           — Internal database errors
+    ├── ProgrammingError        — Query errors, fetch before execute
+    └── NotSupportedError       — Unsupported operations
+```

cdata_connect-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CData Software, Inc.
+
+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.

cdata_connect-0.0.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include pyproject.toml
+prune dist
+prune build
+global-exclude *.py[cod]
+global-exclude .DS_Store
+global-exclude Thumbs.db