# trinodb/trino-python-client architecture

> Architecture diagram of the GitHub repository trinodb/trino-python-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trinodb/trino-python-client
- Repository: https://github.com/trinodb/trino-python-client

## Overview

##### Main Components Identification

The system should be represented with these key components:

a) Core Client Layer:
- Base HTTP Client (trino/client.py)
- Authentication Handlers (trino/auth.py)
- Transaction Management (trino/transaction.py)

b) Interface Layers:
- DBAPI Implementation (trino/dbapi.py)
- SQLAlchemy Integration (trino/sqlalchemy/)

c) Type System:
- Data Type Mappings (trino/types.py)
- Type Conversion Layer (trino/mapper.py)

**┌─────────────────────────────────────────┐**
- Application Layer             │
- ┤
- Interface Layers                 │
- ┌──────────┐        ┌──────────┐    │
- DBAPI   │        │SQLAlchemy│    │
- ┘        └──────────┘    │
- ┤
- Core Client Layer             │
- ┌──────────┐  ┌──────────────┐      │
- HTTP    │  │Authentication│      │
- Client  │  │  Handlers    │      │
- ┘  └──────────────┘      │
- ┌──────────┐  ┌──────────────┐      │
- Transaction│  │Type System   │      │
- Management │  │              │      │
- ┘  └──────────────┘      │
- ┤
- Trino Server               │
- ┘

##### Additional Elements

Annotations for:
- Transaction isolation levels
- SSL/TLS configuration options
- Session properties (timezone, roles, etc.)
- Error handling paths

##### Implementation Details

- The modular nature of the authentication system
- The separation between DBAPI and SQLAlchemy interfaces
- The central role of the core client
- Type conversion system flexibility

Remember to include version compatibility notes and external dependencies where relevant to the architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Application Layer"
        AppCode["Application Code"]
    end

    subgraph "Interface Layer"
        DBAPI["DBAPI Interface"]
        SQLAlchemy["SQLAlchemy Integration"]
        
        subgraph "SQLAlchemy Components"
            SQLCompiler["SQL Compiler"]
            SQLDialect["Dialect Implementation"]
            SQLDataType["Data Type Handler"]
            SQLError["Error Handler"]
        end
    end

    subgraph "Core Client Layer"
        HTTPClient["HTTP Client"]
        AuthHandlers["Authentication Handlers"]
        TransactionMgmt["Transaction Management"]
        
        subgraph "Type System"
            TypeMapping["Data Type Mappings"]
            TypeConversion["Type Conversion Layer"]
        end
        
        subgraph "Core Utilities"
            Constants["Constants"]
            Exceptions["Exceptions"]
            Logging["Logging"]
        end
    end

    subgraph "Authentication Methods"
        BasicAuth["Basic Auth"]
        JWTAuth["JWT Auth"]
        OAuth2["OAuth2"]
        CertAuth["Certificate Auth"]
        Kerberos["Kerberos"]
        GSSAPI["GSSAPI"]
    end

    subgraph "External Layer"
        TrinoServer["Trino Server"]
    end

    %% Relationships
    AppCode --> DBAPI
    AppCode --> SQLAlchemy
    DBAPI --> HTTPClient
    SQLAlchemy --> HTTPClient
    
    SQLAlchemy --> SQLCompiler
    SQLAlchemy --> SQLDialect
    SQLAlchemy --> SQLDataType
    SQLAlchemy --> SQLError
    
    AuthHandlers --> HTTPClient
    TransactionMgmt --> HTTPClient
    
    TypeMapping --> TypeConversion
    TypeConversion --> DBAPI
    TypeConversion --> SQLAlchemy
    
    HTTPClient --> TrinoServer
    
    AuthHandlers --> BasicAuth
    AuthHandlers --> JWTAuth
    AuthHandlers --> OAuth2
    AuthHandlers --> CertAuth
    AuthHandlers --> Kerberos
    AuthHandlers --> GSSAPI

    %% Core Utilities Connections
    Constants --> HTTPClient
    Exceptions --> HTTPClient
    Logging --> HTTPClient

    %% Click Events
    click HTTPClient "https://github.com/trinodb/trino-python-client/blob/master/trino/client.py"
    click AuthHandlers "https://github.com/trinodb/trino-python-client/blob/master/trino/auth.py"
    click TransactionMgmt "https://github.com/trinodb/trino-python-client/blob/master/trino/transaction.py"
    click DBAPI "https://github.com/trinodb/trino-python-client/blob/master/trino/dbapi.py"
    click SQLAlchemy "https://github.com/trinodb/trino-python-client/tree/master/trino/sqlalchemy/"
    click SQLCompiler "https://github.com/trinodb/trino-python-client/blob/master/trino/sqlalchemy/compiler.py"
    click SQLDialect "https://github.com/trinodb/trino-python-client/blob/master/trino/sqlalchemy/dialect.py"
    click SQLDataType "https://github.com/trinodb/trino-python-client/blob/master/trino/sqlalchemy/datatype.py"
    click SQLError "https://github.com/trinodb/trino-python-client/blob/master/trino/sqlalchemy/error.py"
    click TypeMapping "https://github.com/trinodb/trino-python-client/blob/master/trino/types.py"
    click TypeConversion "https://github.com/trinodb/trino-python-client/blob/master/trino/mapper.py"
    click Constants "https://github.com/trinodb/trino-python-client/blob/master/trino/constants.py"
    click Exceptions "https://github.com/trinodb/trino-python-client/blob/master/trino/exceptions.py"
    click Logging "https://github.com/trinodb/trino-python-client/blob/master/trino/logging.py"

    %% Styling
    classDef interface fill:#a8d1ff
    classDef core fill:#90EE90
    classDef auth fill:#FFB347
    classDef external fill:#D3D3D3
    classDef util fill:#E6E6FA

    class DBAPI,SQLAlchemy,SQLCompiler,SQLDialect,SQLDataType,SQLError interface
    class HTTPClient,TransactionMgmt,TypeMapping,TypeConversion core
    class AuthHandlers,BasicAuth,JWTAuth,OAuth2,CertAuth,Kerberos,GSSAPI auth
    class TrinoServer external
    class Constants,Exceptions,Logging util
```
