From 93cd3c971273678d8714237b65763f700479cef8 Mon Sep 17 00:00:00 2001 From: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com> Date: Fri, 23 Oct 2026 09:54:47 +0500 Subject: [PATCH] docs: document all Connection parameters in docstring and README Document every parameter of trino.dbapi.Connection (and trino.dbapi.connect) in the class docstring, and add a matching "Connection parameters" reference table to the README. Defaults and None semantics were verified against the actual implementation. Signed-off-by: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com> --- README.md | 33 +++++++++++++++++++++++++++ trino/dbapi.py | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) diff --git a/README.md b/README.md index d9c7477a..ef3797dd 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,39 @@ rows for example `Cursor.fetchone()` or `Cursor.fetchmany()`. By default `Cursor.fetchmany()` fetches one row. Please set `trino.dbapi.Cursor.arraysize` accordingly. +**Connection parameters** + +`trino.dbapi.connect()` accepts the same arguments as `trino.dbapi.Connection`. +All parameters are optional except `host`. A parameter left as `None` means +"not set" (its server-side default applies), except where noted below. + +| Parameter | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `host` | `str` | — | The hostname or IP address of the Trino coordinator. May be a URL; a scheme and port in the URL take precedence over `http_scheme` and `port`. | +| `port` | `int` | `443` for https, `8080` for http | The port number of the Trino coordinator. | +| `user` | `str` | `None` | The username for the session, sent as the `X-Trino-User` header. | +| `source` | `str` | `'trino-python-client'` | The client name shown for queries in the Trino Web UI. | +| `catalog` | `str` | `None` | The default catalog to use for queries. | +| `schema` | `str` | `None` | The default schema to use for queries. | +| `session_properties` | `dict` | `None` | A dictionary of session properties, e.g. `{'query_max_run_time': '10m'}`. | +| `http_headers` | `dict` | `None` | A dictionary of additional custom HTTP headers to send with requests. | +| `http_scheme` | `str` | auto-detected | Protocol to use: `'http'` or `'https'`. Resolved from the host URL scheme when present, otherwise from this argument, otherwise from the port (`443` → `'https'`, `8080` → `'http'`), defaulting to `'http'`. | +| `auth` | `object` | `None` | An authentication instance, e.g. `BasicAuthentication`, `JWTAuthentication` or `KerberosAuthentication`. `None` means no authentication. | +| `extra_credential` | `list` of `(name, value)` tuples | `None` | Extra credentials sent as `X-Trino-Extra-Credential` headers. | +| `max_attempts` | `int` | `3` | Maximum number of attempts for each HTTP request, including retries. | +| `request_timeout` | `float` | `30.0` | Client-side timeout (in seconds) for each HTTP request. | +| `isolation_level` | `trino.transaction.IsolationLevel` | `IsolationLevel.AUTOCOMMIT` | Transaction isolation level. | +| `verify` | `bool` \| `str` | `True` | Controls TLS certificate verification. Set to `False` to disable, or provide a path to a CA bundle. | +| `http_session` | `requests.Session` | `None` | A custom HTTP session. `None` creates a new default session. | +| `client_tags` | `list[str]` | `None` | A list of tags sent as the `X-Trino-Client-Tags` header. | +| `legacy_primitive_types` | `bool` | `False` | When `True`, query results are not converted to the corresponding Python types. | +| `legacy_prepared_statements` | `bool` | auto-detected | Force the use (`True`) or not (`False`) of legacy prepared statements. When not given, the client probes the coordinator once per host and port and caches the result. | +| `roles` | `dict[str, str]` \| `str` | `None` | Authorization roles: a dict mapping catalog names to roles, or a single string used as the role for the `system` catalog. | +| `timezone` | `str` | client's local time zone | The time zone for the session, e.g. `'US/Pacific'`. | +| `encoding` | `str` \| `list[str]` | all supported encodings | Spooled protocol encodings in order of preference, e.g. `'json+zstd'` or `['json+zstd', 'json']`. | +| `heartbeat_interval` | `float` | `30.0` | Interval in seconds between heartbeat requests for long-running queries. | +| `allow_insecure_auth` | `bool` | `False` | Allow authentication over plain `http`. The coordinator must also be configured with `http-server.authentication.allow-insecure-over-http=true`. | + **Monitoring query progress** Since queries can take a while to complete, it is useful to be able to monitor diff --git a/trino/dbapi.py b/trino/dbapi.py index 35d576e3..8daafd04 100644 --- a/trino/dbapi.py +++ b/trino/dbapi.py @@ -139,6 +139,68 @@ class Connection: statement, can also be cancelled. Transactions are not supported by this client implementation yet. + :param host: the hostname or IP address of the Trino coordinator. It may + be a plain hostname or a URL; a scheme and port given in the + URL take precedence over the ``http_scheme`` and ``port`` + arguments. + :param port: the coordinator port. Defaults to 443 for ``https`` and + 8080 for ``http`` once ``http_scheme`` is resolved. + :param user: the session user, sent as the ``X-Trino-User`` header. + :param source: the client name shown for queries in the Trino Web UI. + Defaults to ``"trino-python-client"``. + :param catalog: the default catalog used by SQL statements. + :param schema: the default schema used by SQL statements. + :param session_properties: a dict of session properties for the session, + e.g. ``{'query_max_run_time': '10m'}``. + :param http_headers: additional HTTP headers sent with each request. + :param http_scheme: ``"http"`` or ``"https"``. Resolved from the host URL + scheme when present, otherwise from this argument, + otherwise from the port (443 maps to ``https``, + 8080 maps to ``http``), defaulting to ``"http"``. + :param auth: an authentication instance (e.g. ``BasicAuthentication``, + ``JWTAuthentication``); ``None`` means no authentication. + Authentication requires TLS unless ``allow_insecure_auth`` + is set. + :param extra_credential: extra credentials as a list of + ``(name, value)`` tuples, sent as + ``X-Trino-Extra-Credential`` headers. + :param max_attempts: maximum attempts for each HTTP request, including + retries. Defaults to 3. + :param request_timeout: client-side timeout in seconds for each HTTP + request. Defaults to 30.0. + :param isolation_level: the transaction isolation level, one of + ``trino.transaction.IsolationLevel``. Defaults to + ``IsolationLevel.AUTOCOMMIT``. + :param verify: controls TLS certificate verification. ``True`` (default) + verifies against the system CA bundle, ``False`` disables + verification, and a string is treated as the path to a CA + bundle. + :param http_session: a custom ``requests.Session`` to use for HTTP; + a new default session is created when not given. + :param client_tags: a list of tags sent as the ``X-Trino-Client-Tags`` + header. + :param legacy_primitive_types: when ``True``, query results are not + converted to the corresponding Python + types. See "Legacy Primitive types" below. + :param legacy_prepared_statements: forces the use (``True``) or not + (``False``) of legacy prepared + statements. When not given, the client + probes the coordinator once per + host and port and caches the result. + :param roles: authorization roles as a dict mapping catalog names to + roles, or a single string which is used as the role for + the ``system`` catalog. + :param timezone: the session time zone, e.g. ``"US/Pacific"``. When not + given, the client's local time zone is used. + :param encoding: the spooling protocol encodings in order of preference, + e.g. ``"json+zstd"`` or ``["json+zstd", "json"]``. + Defaults to every encoding supported by the installed + codecs. See "Spooled protocol" below. + :param heartbeat_interval: interval in seconds between heartbeat requests + for long-running queries. Defaults to 30.0. + :param allow_insecure_auth: allows authentication over plain ``http``. + The coordinator must also be configured with + ``http-server.authentication.allow-insecure-over-http=true``. """ def __init__(