# apache/cassandra-python-driver architecture

> Architecture diagram of the GitHub repository apache/cassandra-python-driver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/cassandra-python-driver
- Repository: https://github.com/apache/cassandra-python-driver

## Overview

This repository is the Apache Cassandra Python Driver: applications issue CQL or graph requests and receive results through synchronous or asynchronous APIs. The main runtime path is Cluster/Session request handling, host selection and connection pooling, binary-protocol encoding and transport, then response decoding. The graph also preserves the documented object mapper, cloud connections, graph API, authentication, and concurrency capabilities. Several feature branches are documented or indexed but not fully sampled, so their uncertain internal call paths are omitted.

Main entry points: [`cassandra/cluster.py`](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cluster.py) (Cluster and Session), [`cassandra/connection.py`](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/connection.py) (Connections and IO), [`cassandra/protocol.py`](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/protocol.py) (Binary Protocol), [`cassandra/cqlengine/models.py`](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/models.py) (Mapper Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_driver["Driver Runtime"]
  node_cluster["Cluster and Session<br/>[cluster.py]"]
  node_statements["CQL Statements<br/>[query.py]"]
  node_policies["Routing Policies<br/>[policies.py]"]
  node_metadata["Cluster Metadata<br/>[metadata.py]"]
  node_pool["Connection Pools<br/>[pool.py]"]
  node_connection["Connections and IO<br/>[connection.py]"]
  node_reactors["Async Reactors"]
  node_protocol["Binary Protocol<br/>[protocol.py]"]
  node_encoding["CQL Encoding<br/>[encoder.py]"]
  node_types["CQL Types<br/>[cqltypes.py]"]
  node_marshal["Value Marshalling<br/>[marshal.py]"]
end

subgraph group_mapper["Object Mapper"]
  node_mapper_models["Mapper Models<br/>[models.py]"]
  node_mapper_columns["Mapper Columns<br/>[columns.py]"]
  node_mapper_query["Mapper QuerySets<br/>[query.py]"]
  node_mapper_connection["Mapper Connections<br/>[connection.py]"]
  node_mapper_management["Schema Management<br/>[management.py]"]
end

subgraph group_graph["Graph API"]
  node_graph_query["Graph Requests<br/>[query.py]"]
  node_graphson["GraphSON Serialization<br/>[graphson.py]"]
  node_fluent["Fluent Graph API<br/>[_query.py]"]
end

subgraph group_integrations["Integrations"]
  node_cloud["Astra Cloud Setup<br/>[__init__.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_concurrent["Concurrent Utilities<br/>[concurrent.py]"]
end

node_app(("Application"))
node_cassandra[("Cassandra Cluster")]

node_app -->|"opens session"| node_cluster
node_app -->|"submits CQL"| node_statements
node_cluster -->|"configures routing"| node_policies
node_cluster -->|"updates topology"| node_metadata
node_cluster -->|"manages pools"| node_pool
node_cluster -->|"dispatches requests"| node_connection
node_pool -->|"acquires connections"| node_connection
node_connection -->|"sends protocol frames"| node_protocol
node_connection -->|"uses IO reactor"| node_reactors
node_protocol -->|"encodes type values"| node_types
node_protocol -->|"marshals values"| node_marshal
node_cluster -->|"executes statements"| node_statements
node_statements -->|"encodes parameters"| node_encoding
node_encoding -->|"uses type codecs"| node_types
node_connection -->|"exchanges binary protocol"| node_cassandra
node_app -->|"defines mapped models"| node_mapper_models
node_mapper_models -->|"declares columns"| node_mapper_columns
node_mapper_models -->|"exposes queries"| node_mapper_query
node_mapper_query -->|"executes mapper queries"| node_mapper_connection
node_mapper_connection -->|"creates driver session"| node_cluster
node_app -->|"manages schema"| node_mapper_management
node_app -->|"submits graph traversal"| node_graph_query
node_graph_query -->|"serializes graph values"| node_graphson
node_fluent -->|"builds graph queries"| node_graph_query
node_app -->|"configures cloud access"| node_cloud
node_app -->|"provides credentials"| node_auth
node_cluster -->|"uses auth provider"| node_auth
node_app -->|"runs concurrent work"| node_concurrent

click node_cluster "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cluster.py"
click node_statements "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/query.py"
click node_policies "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/policies.py"
click node_metadata "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/metadata.py"
click node_pool "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/pool.py"
click node_connection "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/connection.py"
click node_reactors "https://github.com/apache/cassandra-python-driver/tree/trunk/cassandra/io"
click node_protocol "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/protocol.py"
click node_encoding "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/encoder.py"
click node_types "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqltypes.py"
click node_marshal "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/marshal.py"
click node_mapper_models "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/models.py"
click node_mapper_columns "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/columns.py"
click node_mapper_query "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/query.py"
click node_mapper_connection "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/connection.py"
click node_mapper_management "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/management.py"
click node_graph_query "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/graph/query.py"
click node_graphson "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/graph/graphson.py"
click node_fluent "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/graph/fluent/_query.py"
click node_cloud "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/cloud/__init__.py"
click node_auth "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/auth.py"
click node_concurrent "https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/concurrent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cluster,node_statements,node_policies,node_metadata,node_pool,node_connection,node_reactors,node_protocol,node_encoding,node_types,node_marshal toneBlue
class node_mapper_models,node_mapper_columns,node_mapper_query,node_mapper_connection,node_mapper_management,node_cassandra toneAmber
class node_graph_query,node_graphson,node_fluent toneMint
class node_cloud,node_auth,node_concurrent toneRose
class node_app toneIndigo
```

## Components

### Driver Runtime

- [Cluster and Session](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cluster.py): `cassandra/cluster.py`
- [CQL Statements](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/query.py): `cassandra/query.py`
- [Routing Policies](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/policies.py): `cassandra/policies.py`
- [Cluster Metadata](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/metadata.py): `cassandra/metadata.py`
- [Connection Pools](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/pool.py): `cassandra/pool.py`
- [Connections and IO](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/connection.py): `cassandra/connection.py`
- [Async Reactors](https://github.com/apache/cassandra-python-driver/tree/trunk/cassandra/io): `cassandra/io`
- [Binary Protocol](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/protocol.py): `cassandra/protocol.py`
- [CQL Encoding](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/encoder.py): `cassandra/encoder.py`
- [CQL Types](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqltypes.py): `cassandra/cqltypes.py`
- [Value Marshalling](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/marshal.py): `cassandra/marshal.py`

### Object Mapper

- [Mapper Models](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/models.py): `cassandra/cqlengine/models.py`
- [Mapper Columns](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/columns.py): `cassandra/cqlengine/columns.py`
- [Mapper QuerySets](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/query.py): `cassandra/cqlengine/query.py`
- [Mapper Connections](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/connection.py): `cassandra/cqlengine/connection.py`
- [Schema Management](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/cqlengine/management.py): `cassandra/cqlengine/management.py`

### Graph API

- [Graph Requests](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/graph/query.py): `cassandra/datastax/graph/query.py`
- [GraphSON Serialization](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/graph/graphson.py): `cassandra/datastax/graph/graphson.py`
- [Fluent Graph API](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/graph/fluent/_query.py): `cassandra/datastax/graph/fluent/_query.py`

### Integrations

- [Astra Cloud Setup](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/datastax/cloud/__init__.py): `cassandra/datastax/cloud/__init__.py`
- [Authentication](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/auth.py): `cassandra/auth.py`
- [Concurrent Utilities](https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/concurrent.py): `cassandra/concurrent.py`

### Other components

- **Application**
- **Cassandra Cluster**

## Connections

- Application → Cluster and Session: opens session
- Application → CQL Statements: submits CQL
- Cluster and Session → Routing Policies: configures routing (evidence: `cassandra/cluster.py`)
- Cluster and Session → Cluster Metadata: updates topology (evidence: `cassandra/cluster.py`)
- Cluster and Session → Connection Pools: manages pools (evidence: `cassandra/cluster.py`)
- Cluster and Session → Connections and IO: dispatches requests (evidence: `cassandra/cluster.py`)
- Connection Pools → Connections and IO: acquires connections (evidence: `cassandra/pool.py`)
- Connections and IO → Binary Protocol: sends protocol frames (evidence: `cassandra/connection.py`)
- Connections and IO → Async Reactors: uses IO reactor (evidence: `cassandra/connection.py`)
- Binary Protocol → CQL Types: encodes type values (evidence: `cassandra/protocol.py`)
- Binary Protocol → Value Marshalling: marshals values (evidence: `cassandra/protocol.py`)
- Cluster and Session → CQL Statements: executes statements (evidence: `cassandra/cluster.py`)
- CQL Statements → CQL Encoding: encodes parameters (evidence: `cassandra/query.py`)
- CQL Encoding → CQL Types: uses type codecs (evidence: `cassandra/encoder.py`)
- Connections and IO → Cassandra Cluster: exchanges binary protocol
- Application → Mapper Models: defines mapped models
- Mapper Models → Mapper Columns: declares columns (evidence: `cassandra/cqlengine/models.py`)
- Mapper Models → Mapper QuerySets: exposes queries (evidence: `cassandra/cqlengine/models.py`)
- Mapper QuerySets → Mapper Connections: executes mapper queries (evidence: `cassandra/cqlengine/query.py`)
- Mapper Connections → Cluster and Session: creates driver session (evidence: `cassandra/cqlengine/connection.py`)
- Application → Schema Management: manages schema
- Application → Graph Requests: submits graph traversal
- Graph Requests → GraphSON Serialization: serializes graph values (evidence: `cassandra/datastax/graph/query.py`)
- Fluent Graph API → Graph Requests: builds graph queries (evidence: `cassandra/datastax/graph/fluent/_query.py`)
- Application → Astra Cloud Setup: configures cloud access
- Application → Authentication: provides credentials
- Cluster and Session → Authentication: uses auth provider (evidence: `cassandra/cluster.py`)
- Application → Concurrent Utilities: runs concurrent work
