confluent-sql 0.3.0__tar.gz → 0.3.1__tar.gz

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/.semaphore/publish_to_codeartifact.yml

@@ -10,7 +10,7 @@ global_job_config:
       - checkout
       - . vault-setup
       - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
-      - uv sync
+      - uv sync --frozen
 
 blocks:
   - name: Publish `confluent_sql` to codeartifact

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/.semaphore/publish_to_pypi.yml

@@ -10,7 +10,7 @@ global_job_config:
       - checkout
       - . vault-setup
       - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
-      - uv sync
+      - uv sync --frozen
 
 blocks:
   - name: Publish `confluent_sql` to PyPi

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/.semaphore/semaphore.yml

@@ -21,7 +21,7 @@ global_job_config:
       - checkout
       - . vault-setup
       - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
-      - uv sync
+      - uv sync --frozen
       - export VERSION=$(grep '^version' pyproject.toml | cut -d'"' -f2)
 
 blocks:
@@ -31,7 +31,7 @@ blocks:
       jobs:
         - name: "Lint, Type Check, and Test"
           commands:
-            - uv run ruff check && uv run pyright && uv run pytest -m unit --junitxml=test-results.xml
+            - uv run --frozen ruff check && uv run --frozen pyright && uv run --frozen pytest -m unit --junitxml=test-results.xml
       epilogue:
         always:
           commands:

confluent_sql-0.3.1/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Change Log
+
+All notable changes to this dbapi driver will be documented in this file.
+
+## 0.3.1, 2026-05-21
+
+### Added
+
+- New `http_timeout_secs` parameter for `connect()` to let the caller control how long to wait in HTTP requests.
+
+## 0.3.0, 2026-04-09
+
+### Changed - Breaking
+
+- `connect()` / `Connection.__init__()`: Renamed `environment` parameter to `environment_id` to clarify that an environment ID (_not_ name) is expected. The internal attribute `Connection.environment` has also been renamed to `Connection.environment_id`. Update all calls from `connect(environment="env-123")` to `connect(environment_id="env-123")`. (#92)
+- `Cursor.execute()` and peers: Respelled and re-typed the `statement_label: str | None` parameter to be `statement_labels: list[str] | None` to allow multiple labels to be applied to a statement, including `HIDDEN_LABEL`.
+
+### Added
+
+- New `Connection.get_statement(statement)` method to retrieve statement metadata by name or refresh a Statement object with the latest server state. Accepts either a statement name (string) or a Statement object. Returns a Statement object with current phase, schema, and execution traits. (#86)
+- New `StatementNotFoundError` exception, a subclass of `OperationalError`, raised by `Connection.get_statement(statement)` when attempting to retrieve a statement that does not exist. Provides programmatic access to the statement name via the `statement_name` attribute.
+- New constant `confluent_sql.HIDDEN_LABEL` used for driving `Cursor.execute()` to indicate that the statement should be hidden in default listings in Confluent Cloud UIs. This feature is intended to be used for minor queries, such as when investigating `INFORMATION_SCHEMA`.
+- Added documentation regarding use of `connect(endpoint=)` parameter to make use of private networking endpoints (README.md, docstrings).
+
+## 0.2.0, 2026-03-26
+
+### Changed
+
+- Respelled the `connect()` parameter `dbname` to `database`. The old spelling `dbname` is deprecated and will be removed in after one release cycle.
+- Class `SqlNone` now gracefully strips trailing `NOT NULL` constraints from type names (case-insensitively), so that `str(SqlNone("DATE NOT NULL"))` returns valid FlinkSQL `"cast (null as DATE)"`.
+- `connect()` is now keyword-only callable.
+- The `host` parameter for `Connection.__init__()` has been renamed to `endpoint`.
+- Clarified and improved documentation around Flink region API key use.
+
+### Added
+
+- New optional keyword parameter `properties: PropertiesDict | None` on `Cursor.execute()` and related methods to allow callers to provide [statement execution properties](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html#table-options). Note: connection or cursor-level properties for default catalog, database, and execution mode cannot be overridden by this parameter.
+- New optional `endpoint` parameter on `connect()` and `Connection.__init__` to allow users to specify a custom Confluent Cloud API base endpoint (e.g., for private networking, staging, etc.). Mutually exclusive with (`cloud_provider`, `cloud_region`) -- either `endpoint` or (`cloud_provider`, `cloud_region`) must be provided. This replaces the `host` parameter in `Connection.__init__()`. (#66)
+
+### Removed
+
+- The unused control-plane `api_key` and `api_secret` `connect()` parameters have been removed. The Flink Region API key params `flink_api_key` and `flink_api_secret` remain.
+
+## 0.1.x
+
+Early access release of the driver.

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluent-sql
-Version: 0.3.0
+Version: 0.3.1
 Summary: DB-API v2 compliant driver for Confluent Cloud Flink SQL
 Project-URL: Repository, https://github.com/confluentinc/confluent-sql
 Project-URL: Documentation, https://github.com/confluentinc/confluent-sql?tab=readme-ov-file#confluent-sql

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "confluent-sql"
-version = "0.3.0"
+version = "0.3.1"
 description = "DB-API v2 compliant driver for Confluent Cloud Flink SQL"
 readme = "README.md"
 requires-python = ">=3.10"

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/src/confluent_sql/connection.py

@@ -48,6 +48,7 @@ def connect(  # noqa: PLR0913
     dbname: str | None = None,  # deprecated, use database parameter
     result_page_fetch_pause_millis: int = 100,
     http_user_agent: str | None = None,
+    http_timeout_secs: float | None = None,
 ) -> Connection:
     """
     Create a connection to a Confluent SQL service.
@@ -87,6 +88,9 @@ def connect(  # noqa: PLR0913
                        between 1-100 characters. Defaults to
                        "Confluent-SQL-Dbapi/v<version> (https://confluent.io; support@confluent.io)"
                        where version is from __version__.py
+        http_timeout_secs: Timeout in seconds for HTTP requests made by the underlying httpx
+                       client. Must be a positive number. If None (default), the httpx default
+                       of 5 seconds applies to connect, read, write, and pool operations.
 
     Returns:
         A Connection object representing the database connection
@@ -144,6 +148,7 @@ def connect(  # noqa: PLR0913
         database=database or dbname,  # dbname is deprecated.
         statement_results_page_fetch_pause_millis=result_page_fetch_pause_millis,
         http_user_agent=http_user_agent,
+        http_timeout_secs=http_timeout_secs,
     )
 
 
@@ -181,6 +186,7 @@ class Connection:
     _database: str | None
     _client: httpx.Client
     _http_user_agent: str
+    _http_timeout_secs: float | None
 
     _row_type_registry: RowTypeRegistry
     """Registry for user-defined row types, see register_row_type()."""
@@ -202,6 +208,7 @@ class Connection:
         database: str | None = None,
         statement_results_page_fetch_pause_millis: int = 100,
         http_user_agent: str | None = None,
+        http_timeout_secs: float | None = None,
     ):
         """
         Initialize a new connection to a Confluent SQL service.
@@ -231,6 +238,9 @@ class Connection:
             http_user_agent: User-Agent header for HTTP requests. String, 1-100 chars.
                            Defaults to the value of DEFAULT_USER_AGENT, which includes the
                            driver name/version, documentation URL, and support email.
+            http_timeout_secs: Timeout in seconds applied to the underlying httpx client.
+                           Must be a positive number. If None (default), the httpx default
+                           of 5 seconds applies.
         """
         self.environment_id = environment_id
         self.compute_pool_id = compute_pool_id
@@ -254,6 +264,22 @@ class Connection:
             http_user_agent if http_user_agent is not None else self.DEFAULT_USER_AGENT
         )
 
+        if http_timeout_secs is not None:
+            # Reject bool explicitly: bool is a subclass of int in Python, but a True/False
+            # value here is almost certainly a programming error rather than a valid timeout.
+            if isinstance(http_timeout_secs, bool) or not isinstance(
+                http_timeout_secs, (int, float)
+            ):
+                raise InterfaceError(
+                    f"http_timeout_secs must be a number, "
+                    f"got {type(http_timeout_secs).__name__}"
+                )
+            if http_timeout_secs <= 0:
+                raise InterfaceError(
+                    f"http_timeout_secs must be positive, got {http_timeout_secs}"
+                )
+        self._http_timeout_secs = http_timeout_secs
+
         if not endpoint and not (cloud_provider and cloud_region):
             raise InterfaceError(
                 "cloud_provider and cloud_region are required when endpoint is not provided"
@@ -274,14 +300,17 @@ class Connection:
 
         # Create httpx client for making API calls
         basic_auth = httpx.BasicAuth(username=flink_api_key, password=flink_api_secret)
-        self._client = httpx.Client(
-            auth=basic_auth,
-            base_url=base_url,
-            headers={
+        client_kwargs: dict[str, Any] = {
+            "auth": basic_auth,
+            "base_url": base_url,
+            "headers": {
                 "Content-Type": "application/json",
                 "User-Agent": self._http_user_agent,
             },
-        )
+        }
+        if self._http_timeout_secs is not None:
+            client_kwargs["timeout"] = self._http_timeout_secs
+        self._client = httpx.Client(**client_kwargs)
 
         self._row_type_registry = RowTypeRegistry()
 
@@ -784,7 +813,9 @@ class Connection:
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
             if e.response.status_code != 404:
-                raise OperationalError("Error deleting statement") from e
+                raise OperationalError(
+                    "Error deleting statement", http_status_code=e.response.status_code
+                ) from e
             # If the response is 404, it means we don't need to delete the statement.
             logger.info(f"Statement '{statement_name}' not found while deleting, ignoring")
 
@@ -803,6 +834,14 @@ class Connection:
         """
         return self._closed
 
+    @property
+    def http_timeout_secs(self) -> float | None:
+        """
+        Get the configured timeout (in seconds) for HTTP requests, or None if the
+        httpx default (5 seconds) is in effect.
+        """
+        return self._http_timeout_secs
+
     @property
     def http_user_agent(self) -> str:
         """

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/tests/conftest.py

@@ -59,6 +59,7 @@ def connection_factory() -> Generator[ConnectionFactory, None, None]:
         database: str | None = None,
         result_page_fetch_pause_millis: int = 100,
         http_user_agent: str | None = None,
+        http_timeout_secs: float | None = None,
         endpoint: str | None = None,
     ) -> Connection:
         if flink_api_key is None:
@@ -92,6 +93,7 @@ def connection_factory() -> Generator[ConnectionFactory, None, None]:
             database=database,
             result_page_fetch_pause_millis=result_page_fetch_pause_millis,
             http_user_agent=http_user_agent,
+            http_timeout_secs=http_timeout_secs,
             endpoint=endpoint,
         )
 

{confluent_sql-0.3.0 → confluent_sql-0.3.1}/tests/unit/test_connection_unit.py

@@ -153,8 +153,9 @@ class TestConnectionDeleteStatementErrors:
         response_mock.raise_for_status = raise_internal_server_error
         request_mock.return_value = response_mock
 
-        with pytest.raises(OperationalError, match="Error deleting statement"):
+        with pytest.raises(OperationalError, match="Error deleting statement") as exc_info:
             invalid_credential_connection.delete_statement("statement-with-error")
+        assert exc_info.value.http_status_code == 500
 
 
 @pytest.mark.unit
@@ -1490,6 +1491,94 @@ class TestHttpUserAgentProperty:
             http_agent_connection_factory(http_user_agent=invalid_value)
 
 
+@pytest.mark.unit
+class TestHttpTimeoutSecs:
+    """Tests for the http_timeout_secs constructor parameter and property."""
+
+    def test_default_is_none_and_httpx_default_applies(
+        self, invalid_credential_connection: Connection
+    ):
+        """When not provided, the property is None and the httpx default (5s) is used."""
+        assert invalid_credential_connection.http_timeout_secs is None
+        # httpx's default Timeout(timeout=5.0) is wrapped in a Timeout object on the client.
+        assert invalid_credential_connection._client.timeout == httpx.Timeout(5.0)
+
+    @pytest.mark.parametrize("timeout_value", [0.5, 1, 10, 30.0, 120])
+    def test_custom_timeout_via_constructor(
+        self, connection_factory: ConnectionFactory, timeout_value
+    ):
+        """A custom timeout is stored on the connection and applied to the httpx client."""
+        conn = connection_factory(
+            environment_id="env-id",
+            organization_id="org-id",
+            compute_pool_id="cp-id",
+            cloud_provider="aws",
+            cloud_region="us-east-1",
+            flink_api_key="key",
+            flink_api_secret="secret",
+            http_timeout_secs=timeout_value,
+        )
+        assert conn.http_timeout_secs == timeout_value
+        # httpx wraps the timeout into a Timeout(connect, read, write, pool) object.
+        assert conn._client.timeout == httpx.Timeout(timeout_value)
+
+    @pytest.mark.parametrize(
+        "invalid_value,expected_error",
+        [
+            (0, "http_timeout_secs must be positive, got 0"),
+            (-1, "http_timeout_secs must be positive, got -1"),
+            (-0.5, "http_timeout_secs must be positive, got -0.5"),
+        ],
+    )
+    def test_rejects_non_positive(
+        self,
+        connection_factory: ConnectionFactory,
+        invalid_value,
+        expected_error,
+    ):
+        """Zero and negative values are rejected."""
+        with pytest.raises(InterfaceError, match=expected_error):
+            connection_factory(
+                environment_id="env-id",
+                organization_id="org-id",
+                compute_pool_id="cp-id",
+                cloud_provider="aws",
+                cloud_region="us-east-1",
+                flink_api_key="key",
+                flink_api_secret="secret",
+                http_timeout_secs=invalid_value,
+            )
+
+    @pytest.mark.parametrize(
+        "invalid_value,expected_error",
+        [
+            ("5", "http_timeout_secs must be a number, got str"),
+            ([5], "http_timeout_secs must be a number, got list"),
+            ({"secs": 5}, "http_timeout_secs must be a number, got dict"),
+            (True, "http_timeout_secs must be a number, got bool"),
+            (False, "http_timeout_secs must be a number, got bool"),
+        ],
+    )
+    def test_rejects_non_numeric(
+        self,
+        connection_factory: ConnectionFactory,
+        invalid_value,
+        expected_error,
+    ):
+        """Non-numeric types (including bool) are rejected."""
+        with pytest.raises(InterfaceError, match=expected_error):
+            connection_factory(
+                environment_id="env-id",
+                organization_id="org-id",
+                compute_pool_id="cp-id",
+                cloud_provider="aws",
+                cloud_region="us-east-1",
+                flink_api_key="key",
+                flink_api_secret="secret",
+                http_timeout_secs=invalid_value,
+            )
+
+
 @pytest.mark.unit
 class TestComputePoolIdParameter:
     """Test the compute_pool_id parameter for Connection methods."""