e6data-python-connector 2.3.15__tar.gz → 3.0.1__tar.gz

{e6data_python_connector-2.3.15/e6data_python_connector.egg-info → e6data_python_connector-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: e6data-python-connector
-Version: 2.3.15
+Version: 3.0.1
 Summary: Client for the e6data distributed SQL Engine.
 Home-page: https://github.com/e6x-labs/e6data-python-connector
 Author: e6data, Inc.
@@ -27,6 +27,11 @@ Requires-Dist: pytz>=2024.1
 Requires-Dist: thrift>=0.20.0
 Requires-Dist: grpcio>=1.65.1
 Requires-Dist: grpcio-tools>=1.65.1
+Provides-Extra: async
+Requires-Dist: httpx<1,>=0.28.1; extra == "async"
+Provides-Extra: async-sqlalchemy
+Requires-Dist: httpx<1,>=0.28.1; extra == "async-sqlalchemy"
+Requires-Dist: SQLAlchemy[asyncio]<2.1,>=2.0; extra == "async-sqlalchemy"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -34,16 +39,38 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: summary
 
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.15-blue.svg)
+Package version and extras are defined in `setup.py`.
 
 ## Introduction
 
-The e6data Connector for Python provides an interface for writing Python applications that can connect to e6data and perform operations. It includes automatic support for blue-green deployments, ensuring seamless failover during server updates without query interruption.
+The e6data Connector for Python provides an interface for writing Python applications that can connect to e6data and perform operations. It includes routing support for blue-green deployments. Active query handles remain tied to the engine that accepted them; failover does not guarantee uninterrupted results.
+
+## Optional native asyncio API
+
+This branch adds native async connection, cursor, pooling and SQLAlchemy support for Python 3.11+. Release qualification remains incomplete. Install this branch's built package with `[async]` or `[async-sqlalchemy]`; these instructions do not assert that the feature is published.
+
+```python
+from e6data_python_connector.aio import AsyncConnection
+
+async def query(config, sql):
+    async with AsyncConnection(**config) as connection:
+        async with connection.cursor() as cursor:
+            await cursor.execute(sql)
+            return await cursor.fetchall()
+```
+
+`config` is application-supplied connection configuration. OAuth requires verified TLS. Native `fetchone()` preserves the one-row outer list, while SQLAlchemy `e6data+asyncio` adapts it to a normal row. Ambiguous submission and incomplete result errors must not be handled by blindly retrying the query. Use context managers for bounded cleanup.
+
+See [Async API](docs/ASYNC_API.md) for the complete API map, deadlines, pooling, SQLAlchemy and test configuration, [OAuth lifecycle](docs/OAUTH_LIFECYCLE.md) for renewal and failure behavior, and [the application example](examples/async_query.py).
+
+The new CI keeps the full-package coverage denominator and a greater-than-80% gate. The initial baseline was about 19%, so focused async test success is not a release pass. Real-service tests require explicit configuration and are qualified separately.
 
 ### Dependencies
 Make sure to install below dependencies and wheel before install e6data-python-connector.
@@ -120,8 +147,8 @@ The `Connection` class supports the following parameters:
 |-----------|------|----------|---------|-------------|
 | `host` | str | Yes | - | IP address or hostname of the e6data cluster |
 | `port` | int | Yes | - | Port of the e6data engine (typically 80) |
-| `username` | str | Yes | - | Your e6data Email ID |
-| `password` | str | Yes | - | Access Token generated in the e6data console |
+| `username` | str | Conditional | None | Your e6data Email ID. Required unless authenticating with OAuth |
+| `password` | str | Conditional | None | Access Token generated in the e6data console. Required unless authenticating with OAuth |
 | `database` | str | No | None | Database to perform queries on |
 | `catalog` | str | No | None | Catalog name |
 | `cluster_name` | str | No | None | Name of the cluster for cluster-specific operations |
@@ -131,6 +158,76 @@ The `Connection` class supports the following parameters:
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
 | `debug` | bool | No | False | Enable debug logging for troubleshooting |
 | `require_fastbinary` | bool | No | True | Require fastbinary module for Thrift deserialization. Set to False to use pure Python implementation if system dependencies cannot be installed |
+| `client_id` | str | No | None | OAuth 2.0 client id. Use with `client_secret` and `token_url` |
+| `client_secret` | str | No | None | OAuth 2.0 client secret |
+| `token_url` | str | No | None | Token endpoint of the authorization server |
+| `oauth_scope` | str | No | None | Space-delimited scopes to request. Omit for the client's full registered set |
+| `access_token` | str | No | None | A previously obtained access token, for callers that mint their own |
+| `client_auth_method` | str | No | `'basic'` | How client credentials reach the token endpoint: `'basic'` or `'post'` |
+
+#### Authenticating with OAuth 2.0
+
+As an alternative to username and password, a connection can authenticate with an OAuth 2.0 access
+token. The connector obtains a token using the client-credentials grant, caches it, and refreshes it
+shortly before it expires.
+
+Matching client-credentials configurations share one token cache and concurrent
+refresh across sync and async connections, separate pools and threads in the same
+process. Connection and transport ownership remain local. See the
+[OAuth lifecycle](docs/OAUTH_LIFECYCLE.md) for matching settings and expiry behavior.
+
+```python
+conn = Connection(
+    host=host,
+    port=443,
+    database=database,
+    cluster_name='<cluster-name>',
+    secure=True,
+    client_id='<client_id>',
+    client_secret='<client_secret>',
+    token_url='https://<your-workspace>/oauth2/token',
+)
+```
+
+If you mint tokens yourself, pass one directly instead. The connector will not refresh it, so a
+long-lived connection may outlive the token:
+
+```python
+conn = Connection(
+    host=host, port=443, database=database, cluster_name='<cluster-name>',
+    secure=True, access_token='<token>',
+)
+```
+
+**Supply exactly one authentication method.** Passing both username/password and OAuth settings
+raises a `ValueError` rather than picking one, so a stale value left in a config file cannot quietly
+win.
+
+OAuth sends `authorization: Bearer <token>` on every RPC. It does not create an
+authentication session; protobuf username, password and session ID fields remain
+empty. The server stack must support and enable this bearer-only flow.
+
+Use `secure=True` with your TLS endpoint and an HTTPS `token_url` to protect tokens
+and client credentials. OAuth does not enable TLS automatically; `secure` defaults
+to `False`. Set `cluster_name` to identify the target cluster explicitly.
+
+With `auto_resume=True` (the default), OAuth can recover an initial query prepare
+that returns the exact suspended-cluster response. This requires compatible,
+enabled server components that authorize resume and report readiness. The connector
+performs one recovery sequence and retries prepare after readiness. It never
+replays query execution, metadata retrieval or result fetching, and it does not
+treat generic connection failures as suspension.
+
+Recovery has a shared 300-second default deadline covering lock waits, token
+acquisition, status/resume calls, polling and the resumed prepare. Configure it with
+`grpc_options={'grpc_auto_resume_timeout_seconds': 300}`. The deadline starts after
+the suspended response; initial prepare has its own timeout. A dispatched resume
+may still complete after the client times out.
+
+Set `auto_resume=False` to disable recovery. Invalid credentials, denied permissions,
+unsupported servers and failed or unknown cluster states stop recovery without
+falling back to username/password authentication. Externally supplied access tokens
+are not refreshed.
 
 #### Secure Connection Example
 
@@ -372,6 +469,135 @@ database = '<new_database_name>'  # Replace with the new database.
 cursor = conn.cursor(database, catalog_name)
 ```
 
+### Opt in to multi-chunk result batches
+
+Set `enable_result_batch_v2=True` to enable V2 batches, continuous result downloading,
+and bounded parallel chunk decoding together. It defaults to `False`. There
+are no separate public prefetch or decoding switches. `arraysize` and
+`fetchmany(size)` only change the number of rows returned to the application.
+
+The planner must support V2 and have `ENABLE_GET_NEXT_RESULT_BATCH_V2` enabled.
+`ENABLE_GET_NEXT_CHUNK_V2` controls a separate executor-to-planner boundary.
+These flags do not extend the planner's query lifetime. Finishing a large result
+within 900 seconds still needs a measurement on the target deployment.
+
+The optimized path requires ordinary GIL-enabled CPython 3.11 through 3.13 and
+an import-safe application entry point. Put application startup inside
+`if __name__ == "__main__":`, including when using SQLAlchemy. Interactive,
+daemon and frozen applications are rejected before query submission. Two
+workers use the explicit `spawn` method; the application's global multiprocessing
+start method is unchanged. An unguarded main script can run its other import
+side effects, so keep all application startup inside the guard.
+
+Both APIs default to unlimited gRPC send and receive message sizes (`-1`).
+Explicit positive byte limits are still honored. For sync, set
+`max_receive_message_length` and `max_send_message_length` in `grpc_options`.
+For async, set the receive limit with `max_receive_message_bytes` or
+`max_receive_message_length` in `grpc_options`; if both are supplied, they must
+agree. Set `max_send_message_length` in `grpc_options` for the send limit.
+The receive limit applies to each message after transport decompression, not the
+total query result. Unlimited receiving does not limit client memory use;
+continuous downloading can retain serialized batches while decoding catches up.
+
+These examples use your existing `connection_options`, `sql`, and `consume`:
+
+```python
+from e6data_python_connector import Connection
+
+
+def main():
+    options = {**connection_options, "enable_result_batch_v2": True}
+    with Connection(**options) as connection:
+        with connection.cursor() as cursor:
+            cursor.execute(sql)
+            for rows in cursor.fetchall_buffer():
+                consume(rows)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+```python
+import asyncio
+from e6data_python_connector.aio import AsyncConnection
+
+
+async def main():
+    options = {**connection_options, "enable_result_batch_v2": True}
+    async with AsyncConnection(**options) as connection:
+        async with connection.cursor() as cursor:
+            await cursor.execute(sql)
+            async for rows in cursor.fetchall_buffer():
+                consume(rows)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+SQLAlchemy accepts the same flag through `connect_args`. Create and use engines
+inside the guarded application entry point:
+
+```python
+connect_args = {**connection_options, "enable_result_batch_v2": True}
+engine = create_engine("e6data://", connect_args=connect_args)
+async_engine = create_async_engine("e6data+asyncio://", connect_args=connect_args)
+```
+
+After the first V2 response, a download thread (sync) or task (async) keeps
+fetching serialized batches until the engine returns end-of-stream. Decoding
+runs concurrently and takes batches from the queue in order. Downloading does
+not wait for decoding or application row processing. There is no queue-size
+limit and no process-wide limit on active downloaders. Result RPCs for the same
+query never overlap.
+
+Each background RPC gets a fresh configured transport budget when it starts;
+that deadline never extends after dispatch. An empty nonterminal response uses
+backoff with a finite no-progress deadline. Completed responses can wait while
+the application is idle. Public fetch deadlines still cover waiting and decoding,
+and expiry or cancellation stops the downloader. Async `fetchall` keeps one
+deadline for its entire operation.
+
+Two shared worker processes can decode one multi-chunk envelope at a time.
+Other envelopes use the sequential path. Workers receive chunk bytes and column
+positions, not connections or credentials. Process startup and copying add cost,
+so parallel decoding is not a promise of better performance for every result.
+
+Fetch return shapes and row order stay the same. `fetchall_buffer()` yields the
+original decoded chunks. All chunks in an envelope must decode successfully
+before any are exposed. The serialized queue can hold the entire result when
+downloading is faster than decoding or application reads. Workers add Python
+objects and process copies; the receive limit is not a limit on total memory.
+`fetchall()` still retains the full result.
+
+If a decoder worker exits or its local pipe breaks, the connector stops the
+failed workers and decodes that complete serialized envelope once in the parent
+process. It uses the same deadline and makes no extra result RPC. Continuous
+downloading stays active and uncapped during this recovery. Later envelopes use
+sequential decoding until the decoder runtime is replaced through its normal
+lifecycle. Cancellation, expired deadlines, invalid worker replies, and errors
+reported while decoding data are still failures. Their original cause is kept
+on the first error delivered to the caller.
+
+Only a V2 `UNIMPLEMENTED` response switches that query to V1 and disables its
+optimizations. Other RPC failures reach the caller as the original
+`grpc.RpcError` or `grpc.aio.AioRpcError`. A failed pending RPC is raised when
+its envelope is needed, after current valid chunks have been consumed. Failed
+or cancelled queries are not replayed. Later fetches on an incomplete result
+raise `IncompleteResultError`. Clear, cancel, close and pool return retire
+pending work; unsafe connections must not be reused.
+
+Use `debug=True` for payload-free RPC, decode and worker diagnostics. Serialized
+Protobuf bytes are uncompressed payload size, not bytes sent over the network.
+
+For rollback, close old cursors and connections, then omit
+`enable_result_batch_v2` or set it to `False` on new connections. Closing the
+last V2 connection also stops its shared workers. See the
+[qualification instructions](test/README.md#result-batch-v2-qualification).
+Local synthetic results do not prove customer performance or the 900-second
+query requirement.
+
 ### Get Query Time Metrics
 ```python
 import json
@@ -817,11 +1043,27 @@ conn = Connection(
 ```
 
 When `debug=True`, the following features are enabled:
-- Python logging at DEBUG level for all operations
+- Connector logging at DEBUG level, for both sync and async connections. Existing
+  application logging handlers and the root logger level are kept.
 - Blue-green strategy transition logging
 - Connection lifecycle logging
 - Query execution detailed logging
 
+Each result fetch writes a normal debug message with `protocol`, `rpc_seconds`,
+`decode_seconds`, `chunk_count`, `serialized_bytes`, and `status`. The timing values
+are seconds. `rpc_seconds` measures the client RPC call, including waiting for its
+response. `decode_seconds` measures client response processing. `serialized_bytes`
+is the protobuf response size, not the number of bytes on the network. A failed
+attempt reports zero response size and chunk count. The same values remain available
+as `result_batch_*` attributes for structured log handlers.
+
+These metrics do not add SQL, credentials, session IDs, result values, or raw metadata
+to logs. `debug=False` keeps the normal quiet default. Applications can also enable
+DEBUG on the `e6data_python_connector` logger themselves. `debug=True` adds a connector
+stream handler only when no existing handler in its logger path accepts DEBUG.
+As with normal Python logging, enabling the package logger also affects other open
+connector connections in that process.
+
 ### gRPC Network Tracing
 
 For low-level gRPC network debugging (HTTP/2 frames, TCP events), set environment variables **before** running your Python script:

{e6data_python_connector-2.3.15 → e6data_python_connector-3.0.1}/README.md

@@ -1,10 +1,30 @@
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.15-blue.svg)
+Package version and extras are defined in `setup.py`.
 
 ## Introduction
 
-The e6data Connector for Python provides an interface for writing Python applications that can connect to e6data and perform operations. It includes automatic support for blue-green deployments, ensuring seamless failover during server updates without query interruption.
+The e6data Connector for Python provides an interface for writing Python applications that can connect to e6data and perform operations. It includes routing support for blue-green deployments. Active query handles remain tied to the engine that accepted them; failover does not guarantee uninterrupted results.
+
+## Optional native asyncio API
+
+This branch adds native async connection, cursor, pooling and SQLAlchemy support for Python 3.11+. Release qualification remains incomplete. Install this branch's built package with `[async]` or `[async-sqlalchemy]`; these instructions do not assert that the feature is published.
+
+```python
+from e6data_python_connector.aio import AsyncConnection
+
+async def query(config, sql):
+    async with AsyncConnection(**config) as connection:
+        async with connection.cursor() as cursor:
+            await cursor.execute(sql)
+            return await cursor.fetchall()
+```
+
+`config` is application-supplied connection configuration. OAuth requires verified TLS. Native `fetchone()` preserves the one-row outer list, while SQLAlchemy `e6data+asyncio` adapts it to a normal row. Ambiguous submission and incomplete result errors must not be handled by blindly retrying the query. Use context managers for bounded cleanup.
+
+See [Async API](docs/ASYNC_API.md) for the complete API map, deadlines, pooling, SQLAlchemy and test configuration, [OAuth lifecycle](docs/OAUTH_LIFECYCLE.md) for renewal and failure behavior, and [the application example](examples/async_query.py).
+
+The new CI keeps the full-package coverage denominator and a greater-than-80% gate. The initial baseline was about 19%, so focused async test success is not a release pass. Real-service tests require explicit configuration and are qualified separately.
 
 ### Dependencies
 Make sure to install below dependencies and wheel before install e6data-python-connector.
@@ -81,8 +101,8 @@ The `Connection` class supports the following parameters:
 |-----------|------|----------|---------|-------------|
 | `host` | str | Yes | - | IP address or hostname of the e6data cluster |
 | `port` | int | Yes | - | Port of the e6data engine (typically 80) |
-| `username` | str | Yes | - | Your e6data Email ID |
-| `password` | str | Yes | - | Access Token generated in the e6data console |
+| `username` | str | Conditional | None | Your e6data Email ID. Required unless authenticating with OAuth |
+| `password` | str | Conditional | None | Access Token generated in the e6data console. Required unless authenticating with OAuth |
 | `database` | str | No | None | Database to perform queries on |
 | `catalog` | str | No | None | Catalog name |
 | `cluster_name` | str | No | None | Name of the cluster for cluster-specific operations |
@@ -92,6 +112,76 @@ The `Connection` class supports the following parameters:
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
 | `debug` | bool | No | False | Enable debug logging for troubleshooting |
 | `require_fastbinary` | bool | No | True | Require fastbinary module for Thrift deserialization. Set to False to use pure Python implementation if system dependencies cannot be installed |
+| `client_id` | str | No | None | OAuth 2.0 client id. Use with `client_secret` and `token_url` |
+| `client_secret` | str | No | None | OAuth 2.0 client secret |
+| `token_url` | str | No | None | Token endpoint of the authorization server |
+| `oauth_scope` | str | No | None | Space-delimited scopes to request. Omit for the client's full registered set |
+| `access_token` | str | No | None | A previously obtained access token, for callers that mint their own |
+| `client_auth_method` | str | No | `'basic'` | How client credentials reach the token endpoint: `'basic'` or `'post'` |
+
+#### Authenticating with OAuth 2.0
+
+As an alternative to username and password, a connection can authenticate with an OAuth 2.0 access
+token. The connector obtains a token using the client-credentials grant, caches it, and refreshes it
+shortly before it expires.
+
+Matching client-credentials configurations share one token cache and concurrent
+refresh across sync and async connections, separate pools and threads in the same
+process. Connection and transport ownership remain local. See the
+[OAuth lifecycle](docs/OAUTH_LIFECYCLE.md) for matching settings and expiry behavior.
+
+```python
+conn = Connection(
+    host=host,
+    port=443,
+    database=database,
+    cluster_name='<cluster-name>',
+    secure=True,
+    client_id='<client_id>',
+    client_secret='<client_secret>',
+    token_url='https://<your-workspace>/oauth2/token',
+)
+```
+
+If you mint tokens yourself, pass one directly instead. The connector will not refresh it, so a
+long-lived connection may outlive the token:
+
+```python
+conn = Connection(
+    host=host, port=443, database=database, cluster_name='<cluster-name>',
+    secure=True, access_token='<token>',
+)
+```
+
+**Supply exactly one authentication method.** Passing both username/password and OAuth settings
+raises a `ValueError` rather than picking one, so a stale value left in a config file cannot quietly
+win.
+
+OAuth sends `authorization: Bearer <token>` on every RPC. It does not create an
+authentication session; protobuf username, password and session ID fields remain
+empty. The server stack must support and enable this bearer-only flow.
+
+Use `secure=True` with your TLS endpoint and an HTTPS `token_url` to protect tokens
+and client credentials. OAuth does not enable TLS automatically; `secure` defaults
+to `False`. Set `cluster_name` to identify the target cluster explicitly.
+
+With `auto_resume=True` (the default), OAuth can recover an initial query prepare
+that returns the exact suspended-cluster response. This requires compatible,
+enabled server components that authorize resume and report readiness. The connector
+performs one recovery sequence and retries prepare after readiness. It never
+replays query execution, metadata retrieval or result fetching, and it does not
+treat generic connection failures as suspension.
+
+Recovery has a shared 300-second default deadline covering lock waits, token
+acquisition, status/resume calls, polling and the resumed prepare. Configure it with
+`grpc_options={'grpc_auto_resume_timeout_seconds': 300}`. The deadline starts after
+the suspended response; initial prepare has its own timeout. A dispatched resume
+may still complete after the client times out.
+
+Set `auto_resume=False` to disable recovery. Invalid credentials, denied permissions,
+unsupported servers and failed or unknown cluster states stop recovery without
+falling back to username/password authentication. Externally supplied access tokens
+are not refreshed.
 
 #### Secure Connection Example
 
@@ -333,6 +423,135 @@ database = '<new_database_name>'  # Replace with the new database.
 cursor = conn.cursor(database, catalog_name)
 ```
 
+### Opt in to multi-chunk result batches
+
+Set `enable_result_batch_v2=True` to enable V2 batches, continuous result downloading,
+and bounded parallel chunk decoding together. It defaults to `False`. There
+are no separate public prefetch or decoding switches. `arraysize` and
+`fetchmany(size)` only change the number of rows returned to the application.
+
+The planner must support V2 and have `ENABLE_GET_NEXT_RESULT_BATCH_V2` enabled.
+`ENABLE_GET_NEXT_CHUNK_V2` controls a separate executor-to-planner boundary.
+These flags do not extend the planner's query lifetime. Finishing a large result
+within 900 seconds still needs a measurement on the target deployment.
+
+The optimized path requires ordinary GIL-enabled CPython 3.11 through 3.13 and
+an import-safe application entry point. Put application startup inside
+`if __name__ == "__main__":`, including when using SQLAlchemy. Interactive,
+daemon and frozen applications are rejected before query submission. Two
+workers use the explicit `spawn` method; the application's global multiprocessing
+start method is unchanged. An unguarded main script can run its other import
+side effects, so keep all application startup inside the guard.
+
+Both APIs default to unlimited gRPC send and receive message sizes (`-1`).
+Explicit positive byte limits are still honored. For sync, set
+`max_receive_message_length` and `max_send_message_length` in `grpc_options`.
+For async, set the receive limit with `max_receive_message_bytes` or
+`max_receive_message_length` in `grpc_options`; if both are supplied, they must
+agree. Set `max_send_message_length` in `grpc_options` for the send limit.
+The receive limit applies to each message after transport decompression, not the
+total query result. Unlimited receiving does not limit client memory use;
+continuous downloading can retain serialized batches while decoding catches up.
+
+These examples use your existing `connection_options`, `sql`, and `consume`:
+
+```python
+from e6data_python_connector import Connection
+
+
+def main():
+    options = {**connection_options, "enable_result_batch_v2": True}
+    with Connection(**options) as connection:
+        with connection.cursor() as cursor:
+            cursor.execute(sql)
+            for rows in cursor.fetchall_buffer():
+                consume(rows)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+```python
+import asyncio
+from e6data_python_connector.aio import AsyncConnection
+
+
+async def main():
+    options = {**connection_options, "enable_result_batch_v2": True}
+    async with AsyncConnection(**options) as connection:
+        async with connection.cursor() as cursor:
+            await cursor.execute(sql)
+            async for rows in cursor.fetchall_buffer():
+                consume(rows)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+SQLAlchemy accepts the same flag through `connect_args`. Create and use engines
+inside the guarded application entry point:
+
+```python
+connect_args = {**connection_options, "enable_result_batch_v2": True}
+engine = create_engine("e6data://", connect_args=connect_args)
+async_engine = create_async_engine("e6data+asyncio://", connect_args=connect_args)
+```
+
+After the first V2 response, a download thread (sync) or task (async) keeps
+fetching serialized batches until the engine returns end-of-stream. Decoding
+runs concurrently and takes batches from the queue in order. Downloading does
+not wait for decoding or application row processing. There is no queue-size
+limit and no process-wide limit on active downloaders. Result RPCs for the same
+query never overlap.
+
+Each background RPC gets a fresh configured transport budget when it starts;
+that deadline never extends after dispatch. An empty nonterminal response uses
+backoff with a finite no-progress deadline. Completed responses can wait while
+the application is idle. Public fetch deadlines still cover waiting and decoding,
+and expiry or cancellation stops the downloader. Async `fetchall` keeps one
+deadline for its entire operation.
+
+Two shared worker processes can decode one multi-chunk envelope at a time.
+Other envelopes use the sequential path. Workers receive chunk bytes and column
+positions, not connections or credentials. Process startup and copying add cost,
+so parallel decoding is not a promise of better performance for every result.
+
+Fetch return shapes and row order stay the same. `fetchall_buffer()` yields the
+original decoded chunks. All chunks in an envelope must decode successfully
+before any are exposed. The serialized queue can hold the entire result when
+downloading is faster than decoding or application reads. Workers add Python
+objects and process copies; the receive limit is not a limit on total memory.
+`fetchall()` still retains the full result.
+
+If a decoder worker exits or its local pipe breaks, the connector stops the
+failed workers and decodes that complete serialized envelope once in the parent
+process. It uses the same deadline and makes no extra result RPC. Continuous
+downloading stays active and uncapped during this recovery. Later envelopes use
+sequential decoding until the decoder runtime is replaced through its normal
+lifecycle. Cancellation, expired deadlines, invalid worker replies, and errors
+reported while decoding data are still failures. Their original cause is kept
+on the first error delivered to the caller.
+
+Only a V2 `UNIMPLEMENTED` response switches that query to V1 and disables its
+optimizations. Other RPC failures reach the caller as the original
+`grpc.RpcError` or `grpc.aio.AioRpcError`. A failed pending RPC is raised when
+its envelope is needed, after current valid chunks have been consumed. Failed
+or cancelled queries are not replayed. Later fetches on an incomplete result
+raise `IncompleteResultError`. Clear, cancel, close and pool return retire
+pending work; unsafe connections must not be reused.
+
+Use `debug=True` for payload-free RPC, decode and worker diagnostics. Serialized
+Protobuf bytes are uncompressed payload size, not bytes sent over the network.
+
+For rollback, close old cursors and connections, then omit
+`enable_result_batch_v2` or set it to `False` on new connections. Closing the
+last V2 connection also stops its shared workers. See the
+[qualification instructions](test/README.md#result-batch-v2-qualification).
+Local synthetic results do not prove customer performance or the 900-second
+query requirement.
+
 ### Get Query Time Metrics
 ```python
 import json
@@ -778,11 +997,27 @@ conn = Connection(
 ```
 
 When `debug=True`, the following features are enabled:
-- Python logging at DEBUG level for all operations
+- Connector logging at DEBUG level, for both sync and async connections. Existing
+  application logging handlers and the root logger level are kept.
 - Blue-green strategy transition logging
 - Connection lifecycle logging
 - Query execution detailed logging
 
+Each result fetch writes a normal debug message with `protocol`, `rpc_seconds`,
+`decode_seconds`, `chunk_count`, `serialized_bytes`, and `status`. The timing values
+are seconds. `rpc_seconds` measures the client RPC call, including waiting for its
+response. `decode_seconds` measures client response processing. `serialized_bytes`
+is the protobuf response size, not the number of bytes on the network. A failed
+attempt reports zero response size and chunk count. The same values remain available
+as `result_batch_*` attributes for structured log handlers.
+
+These metrics do not add SQL, credentials, session IDs, result values, or raw metadata
+to logs. `debug=False` keeps the normal quiet default. Applications can also enable
+DEBUG on the `e6data_python_connector` logger themselves. `debug=True` adds a connector
+stream handler only when no existing handler in its logger path accepts DEBUG.
+As with normal Python logging, enabling the package logger also affects other open
+connector connections in that process.
+
 ### gRPC Network Tracing
 
 For low-level gRPC network debugging (HTTP/2 frames, TCP events), set environment variables **before** running your Python script:

e6data_python_connector-3.0.1/e6data_python_connector/aio.py

@@ -0,0 +1,26 @@
+"""Explicit optional native asyncio entry point (Python 3.11+)."""
+import sys
+
+if sys.version_info < (3, 11):
+    raise RuntimeError('The async API requires Python 3.11 or newer.')
+try:
+    import httpx as _httpx
+except ImportError:
+    raise ImportError('Install e6data-python-connector[async] for the async API.') from None
+
+from .async_connection import AsyncConnection
+
+__all__ = ['connect', 'AsyncConnection', 'AsyncCursor', 'AsyncConnectionPool', 'AsyncClusterManager']
+
+
+async def connect(*args, **kwargs):
+    return await AsyncConnection(*args, **kwargs).open()
+
+
+def __getattr__(name):
+    modules = {'AsyncCursor': 'async_cursor', 'AsyncConnectionPool': 'async_connection_pool',
+               'AsyncClusterManager': 'async_cluster_manager'}
+    if name not in modules:
+        raise AttributeError(name)
+    from importlib import import_module
+    return getattr(import_module('.' + modules[name], __package__), name)