Drivers Module

Driver interfaces.

This module defines the abstract base driver classes that form the foundation of the toolchain system:

• Driver: Base class for all drivers, defining input/output typing and sync/async flags.

• ILDriver: Converts internal intermediate representations (IL/IR) into SQL queries.

• ConnectionDriver: Manages database connections and executes SQL statements.

• Simplifier: Transforms low-level execution results into higher-level, simplified forms.

Each driver supports both synchronous and asynchronous methods, with subclasses required to implement at least one mode of operation.

class plugorm.drivers.ConnectionDriver

Abstract base class for database connection drivers.

A ConnectionDriver defines the low-level API for connecting to, interacting with, and closing a database connection. Subclasses must provide synchronous and/or asynchronous implementations of connection lifecycle methods and SQL execution.

async aclose() → None

Asynchronously close the database connection.

async aconnect() → None

Asynchronously establish a database connection.

async aexecute(statement: str) → Any

Asynchronously execute a SQL statement.

Parameters:

statement (str) – The SQL query or command to execute.

Returns:

The result returned by the database driver.

Return type:

Any

check_async() → None

Detect whether sync/async methods are implemented.

Updates the is_sync and is_async flags based on whether the subclass provides both connect/close/execute (sync) and aconnect/aclose/``aexecute` (async).

close() → None

Synchronously close the database connection.

connect() → None

Synchronously establish a database connection.

execute(statement: str) → Any

Synchronously execute a SQL statement.

Parameters:

statement (str) – The SQL query or command to execute.

Returns:

The result returned by the database driver.

Return type:

Any

class plugorm.drivers.Driver

Base class for all drivers.

Defines the required interface and core attributes for drivers, including their input/output domains and synchronous/asynchronous capabilities.

input_

Set of supported input types for this driver.

Type:

set[str]

output

Set of output types produced by this driver.

Type:

set[str]

is_sync

Indicates whether the driver supports synchronous execution.

Type:

bool

is_async

Indicates whether the driver supports asynchronous execution.

Type:

bool

input_: set[str]

is_async: bool

is_sync: bool

output: set[str]

class plugorm.drivers.ILDriver

Abstract base class for internal language (IL) drivers.

An ILDriver is responsible for converting the internal language of a dialect into an SQL-specific query. Subclasses must support either sync or async implementation

async aparse(internal_language: Any) → str

Asynchronously parse an internal language representation.

Parameters:

internal_language (Any) – The internal language object to be parsed.

Returns:

The SQL-specific query defined by the internal language.

Return type:

str

check_async() → None

Detect whether sync/async methods are implemented.

Updates the is_sync and is_async flags by checking if the subclass provides parse and/or aparse.

parse(internal_language: Any) → str

Synchronously parse an internal language representation.

Parameters:

internal_language (Any) – The internal language object to be parsed.

Returns:

The SQL-specific query defined by the internal language.

Return type:

str

class plugorm.drivers.Simplifier

Abstract base class for result simplifiers in the toolchain.

A Simplifier processes low-level results (e.g., raw database query results) into a higher-level, simplified representation. Subclasses must provide synchronous and/or asynchronous parsing methods.

aparse(low_level_result: Any) → Any

Asynchronously simplify a low-level result.

Parameters:

low_level_result (Any) – The raw result to be simplified.

Returns:

The simplified result.

Return type:

Any

check_async() → None

Detect whether sync/async parse methods are implemented.

Updates the is_sync and is_async flags by checking whether the subclass provides parse and/or aparse.

parse(low_level_result: Any) → Any

Synchronously simplify a low-level result.

Parameters:

low_level_result (Any) – The raw result to be simplified.

Returns:

The simplified result.

Return type:

Any

class plugorm.drivers.ToolchainDriver

Abstract base class for all drivers in the toolchain.

Automatically detect async and sync support

abstractmethod check_async() → None

Validate that asynchronous or synchronous behavior is correctly implemented.