Skip to content

Python PEP-249 Conformity

Note

Conformance is a work in progress. This page reflects the current implementation status to provide transparent insight into Opteryx’s capabilities and development progress.

Opteryx is not a full DBMS and therefore aims only for conformance with PEP-249 (Python Database API Specification v2.0) for the subset of features it supports—primarily those related to querying data. The opteryx.dbapi shim exposes the conventional DB-API surface on top of the existing Connection and Cursor classes while re-exporting the mandatory globals and exception hierarchy.

Overview

The implementation prioritizes compatibility with data analysis workflows, providing a familiar Python database interface for data scientists and analysts working with distributed data sources. As a read-only query engine, Opteryx does not support transactional operations like inserts, updates, or deletes.

Current module settings:

  • apilevel = "1.0" (DB-API 2.0 semantics with extensions omitted)
  • threadsafety = 0 (connections and cursors must remain on the creating thread)
  • paramstyle = "named" (placeholders are expressed as :name)

Conformance Status

Feature Imperative Supported Notes
Module Interface
connect constructor must yes opteryx.connect() (and opteryx.dbapi.connect) return the read-only Connection class.
apilevel global must yes Set to "1.0".
threadsafety global must yes Set to 0 meaning objects are not thread-safe.
paramstyle global must yes Named parameters using :param markers.
Warning exception should yes Alias of SecurityError.
Error exception should yes Root of the Opteryx DB-API hierarchy.
InterfaceError exception should yes Alias of ProgrammingError.
DatabaseError exception should yes Provided via opteryx.exceptions.
DataError exception should yes Raised for data issues.
OperationalError exception should yes Alias of ExecutionError (a ProgrammingError subclass).
IntegrityError exception should partial Currently aliased to DataError; a dedicated referential-integrity subtype is not implemented.
InternalError exception should yes Alias of InvalidInternalStateError.
ProgrammingError exception should yes Used extensively for SQL issues.
NotSupportedError exception should yes Signalled for unsupported SQL/operations.
Connection Object
close method should yes Closes the connection and any tracked cursors.
commit method should partial Present but a no-op because the engine never mutates state.
rollback method should n/a Raises AttributeError per PEP-249 guidance for engines without transactions.
cursor method should yes Returns an opteryx.cursor.Cursor instance.
messages attribute optional no Use cursor.messages for runtime warnings.
errorhandler attribute optional no Connection-level overrides are not provided.
Cursor Object
description attribute should yes Tuple of (name, type_code, ...) built from the Orso schema.
rowcount attribute should yes Reflects rows read or affected (for SET statements).
callproc method optional no Stored procedures are out of scope.
close method should yes Releases resources and optionally closes the owning connection.
execute method should yes Supports named parameters and visibility filters.
executemany method should no Multi-row parameter binding is not implemented.
fetchone method should yes Provided by the inherited orso.DataFrame implementation.
fetchmany method should yes Honors arraysize.
fetchall method should yes Materializes the remaining result rows.
nextset method optional n/a Planner returns a single result set per cursor.
arraysize attribute should yes Defaults to 1 and can be tuned before fetchmany.
setinputsizes method should no Parameter typing hints are not consumed.
setoutputsize method should no Output buffer sizing is not exposed.
rownumber attribute optional no Not surfaced; use iteration counters if required.
connection attribute optional no _connection exists but remains private.
scroll method optional no Random access cursors are not supported.
messages attribute optional yes Returns warnings collected in QueryStatistics.
next method optional no Use iter(cursor)/next(iterator) instead.
__iter__ method optional yes Delegates to the orso row iterator.
lastrowid attribute optional no Engine is read-only and never assigns row identifiers.
errorhandler attribute optional no Cursor-level overrides are not provided.
Type Constructors
Date optional no Use datetime.date when needed.
Time optional no Use datetime.time directly.
Timestamp optional no Use datetime.datetime directly.
DateFromTicks optional no Conversion helpers are not implemented.
TimeFromTicks optional no Conversion helpers are not implemented.
TimestampFromTicks optional no Conversion helpers are not implemented.
Binary optional yes Helper converts incoming values to bytes.
STRING optional yes DBAPISet covering VARCHAR and JSONB.
BINARY optional yes DBAPISet of BLOB types.
NUMBER optional yes DBAPISet for numeric Orso types.
DATETIME optional yes Alias of TIMESTAMP DBAPISet.
ROWID optional yes Empty DBAPISet placeholder (engine never returns row ids).
Two-Phase Commit Extensions n/a Transactions and TPC flows are out of scope for Opteryx.

Support statuses in this table:

  • yes The feature is supported and conformance is part of the test suite.
  • no The feature is not supported.
  • partial Some features are supported.
  • n/a The feature relates to functionality not supported by Opteryx (e.g., transactional operations).

Key Supported Features

Opteryx implements the core features needed for read-only data analysis:

  • DB-API entry point – opteryx.dbapi re-exports connect, Connection, Cursor, globals, and exceptions.
  • Named parameter binding – cursor.execute() accepts dictionaries (or sequences for simple statements) with :name placeholders.
  • Cursor fetching semantics – fetchone, fetchmany, fetchall, iteration, and rowcount behave as specified (see tests/unit/core/test_cursor.py).
  • Result metadata – cursor.description and Arrow conversion helpers (execute_to_arrow / query_to_arrow) expose schema details.
  • Runtime diagnostics – cursor.messages delivers warnings and other notices collected via QueryStatistics.

Features Not Supported

As a read-only query engine, Opteryx does not support:

  • Mutation-oriented workflows – commit, rollback, two-phase commit, lastrowid, and executemany are intentionally absent or inert.
  • Stored procedures and cursor navigation – callproc, scroll, nextset, setinputsizes, and setoutputsize are not implemented.
  • DB-API type constructors – apart from Binary and the classification constants, applications should use the standard datetime module.
  • Custom error handlers – the errorhandler attribute is not surfaced on connections or cursors; rely on the provided exception hierarchy.

These limitations align with Opteryx's design as an analytical engine focused on reading and processing data rather than managing database state.