Skip to content

Commit 6eaa8c7

Browse files
millerjpmillerjp
committed
examples
1 parent 1c4a51b commit 6eaa8c7

15 files changed

+1859
-54
lines changed

‎Makefile‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ help:
66
@echo "Installation:"
77
@echo " install Install the package"
88
@echo " install-dev Install with development dependencies"
9+
@echo " install-examples Install example dependencies (e.g., pyarrow)"
910
@echo ""
1011
@echo "Quick Test Commands:"
1112
@echo " test-quick Run quick validation tests (~30s)"
@@ -43,6 +44,17 @@ help:
4344
@echo " build Build distribution packages"
4445
@echo " clean Clean build artifacts"
4546
@echo ""
47+
@echo "Examples:"
48+
@echo " example-streaming Run streaming basic example"
49+
@echo " example-export-csv Run CSV export example"
50+
@echo " example-export-parquet Run Parquet export example"
51+
@echo " example-realtime Run real-time processing example"
52+
@echo " example-metrics Run metrics collection example"
53+
@echo " example-non-blocking Run non-blocking demo"
54+
@echo " example-context Run context manager safety demo"
55+
@echo " example-fastapi Run FastAPI example app"
56+
@echo " examples-all Run all examples sequentially"
57+
@echo ""
4658
@echo "Environment variables:"
4759
@echo " CASSANDRA_CONTACT_POINTS Cassandra contact points (default: localhost)"
4860
@echo " SKIP_INTEGRATION_TESTS=1 Skip integration tests"
@@ -56,6 +68,10 @@ install-dev:
5668
pip install -r requirements-lint.txt
5769
pre-commit install
5870

71+
install-examples:
72+
@echo "Installing example dependencies..."
73+
pip install -r examples/requirements.txt
74+
5975
# Environment setup
6076
CONTAINER_RUNTIME ?= $(shell command -v podman >/dev/null 2>&1 && echo podman || echo docker)
6177
CASSANDRA_CONTACT_POINTS ?= 127.0.0.1
@@ -322,3 +338,89 @@ clean:
322338

323339
clean-all: clean cassandra-stop
324340
@echo "All cleaned up"
341+
342+
# Example targets
343+
.PHONY: example-streaming example-export-csv example-export-parquet example-realtime example-metrics example-non-blocking example-context example-fastapi examples-all
344+
345+
# Ensure examples can connect to Cassandra
346+
EXAMPLES_ENV = CASSANDRA_CONTACT_POINTS=$(CASSANDRA_CONTACT_POINTS)
347+
348+
example-streaming: cassandra-wait
349+
@echo "=== Running Streaming Basic Example ==="
350+
@echo "This example demonstrates memory-efficient streaming of large result sets"
351+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
352+
@$(EXAMPLES_ENV) python examples/streaming_basic.py
353+
354+
example-export-csv: cassandra-wait
355+
@echo "=== Running CSV Export Example ==="
356+
@echo "This example exports a large Cassandra table to CSV format"
357+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
358+
@echo "Output will be saved to ./exports/ directory"
359+
@$(EXAMPLES_ENV) python examples/export_large_table.py
360+
361+
example-export-parquet: cassandra-wait
362+
@echo "=== Running Parquet Export Example ==="
363+
@echo "This example exports Cassandra tables to Parquet format with streaming"
364+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
365+
@echo "Output will be saved to ./parquet_exports/ directory"
366+
@echo "Installing pyarrow if needed..."
367+
@pip install pyarrow >/dev/null 2>&1 || echo "PyArrow already installed"
368+
@$(EXAMPLES_ENV) python examples/export_to_parquet.py
369+
370+
example-realtime: cassandra-wait
371+
@echo "=== Running Real-time Processing Example ==="
372+
@echo "This example demonstrates real-time streaming analytics on sensor data"
373+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
374+
@$(EXAMPLES_ENV) python examples/realtime_processing.py
375+
376+
example-metrics: cassandra-wait
377+
@echo "=== Running Metrics Collection Examples ==="
378+
@echo "Running simple metrics example..."
379+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
380+
@$(EXAMPLES_ENV) python examples/metrics_simple.py
381+
@echo ""
382+
@echo "Running advanced metrics example..."
383+
@$(EXAMPLES_ENV) python examples/metrics_example.py
384+
385+
example-non-blocking: cassandra-wait
386+
@echo "=== Running Non-Blocking Streaming Demo ==="
387+
@echo "This demonstrates that streaming doesn't block the event loop"
388+
@echo "Watch for heartbeat indicators showing continuous operation!"
389+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
390+
@$(EXAMPLES_ENV) python examples/streaming_non_blocking_demo.py
391+
392+
example-context: cassandra-wait
393+
@echo "=== Running Context Manager Safety Demo ==="
394+
@echo "This demonstrates proper resource management with context managers"
395+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
396+
@$(EXAMPLES_ENV) python examples/context_manager_safety_demo.py
397+
398+
example-fastapi:
399+
@echo "=== Running FastAPI Example App ==="
400+
@echo "This starts a full REST API with async Cassandra integration"
401+
@echo "The app includes Docker Compose for easy setup"
402+
@echo "See examples/fastapi_app/README.md for details"
403+
@cd examples/fastapi_app && $(MAKE) run
404+
405+
examples-all: cassandra-wait
406+
@echo "=== Running All Examples ==="
407+
@echo "This will run each example in sequence"
408+
@echo "Contact points: $(CASSANDRA_CONTACT_POINTS)"
409+
@echo ""
410+
@$(MAKE) example-streaming
411+
@echo "\n----------------------------------------\n"
412+
@$(MAKE) example-export-csv
413+
@echo "\n----------------------------------------\n"
414+
@$(MAKE) example-export-parquet
415+
@echo "\n----------------------------------------\n"
416+
@$(MAKE) example-realtime
417+
@echo "\n----------------------------------------\n"
418+
@$(MAKE) example-metrics
419+
@echo "\n----------------------------------------\n"
420+
@$(MAKE) example-non-blocking
421+
@echo "\n----------------------------------------\n"
422+
@$(MAKE) example-context
423+
@echo "\n✅ All examples completed!"
424+
@echo ""
425+
@echo "Note: FastAPI example not included as it starts a server"
426+
@echo "Run 'make example-fastapi' separately to start the FastAPI app"

‎examples/README.md‎

Lines changed: 102 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,48 @@
22

33
This directory contains working examples demonstrating various features and use cases of async-cassandra.
44

5+
## Quick Start
6+
7+
### Running Examples with Make
8+
9+
The easiest way to run examples is using the provided Make targets:
10+
11+
```bash
12+
# Run a specific example (automatically starts Cassandra if needed)
13+
make example-streaming
14+
make example-export-csv
15+
make example-export-parquet
16+
make example-realtime
17+
make example-metrics
18+
make example-non-blocking
19+
make example-context
20+
21+
# Run all examples in sequence
22+
make examples-all
23+
24+
# Use external Cassandra cluster
25+
CASSANDRA_CONTACT_POINTS=node1.example.com,node2.example.com make example-streaming
26+
```
27+
28+
### Installing Example Dependencies
29+
30+
Some examples require additional dependencies:
31+
32+
```bash
33+
# Install all example dependencies (including pyarrow for Parquet export)
34+
make install-examples
35+
36+
# Or manually
37+
pip install -r examples/requirements.txt
38+
```
39+
40+
### Environment Variables
41+
42+
All examples support these environment variables:
43+
- `CASSANDRA_CONTACT_POINTS`: Comma-separated list of contact points (default: localhost)
44+
- `CASSANDRA_PORT`: Port number (default: 9042)
45+
- `EXAMPLE_OUTPUT_DIR`: Directory for output files like CSV and Parquet exports (default: examples/exampleoutput)
46+
547
## Available Examples
648

749
### 1. [FastAPI Integration](fastapi_app/)
@@ -50,10 +92,38 @@ Shows how to export large Cassandra tables to CSV:
5092
**Run:**
5193
```bash
5294
python export_large_table.py
53-
# Exports will be saved in ./exports/ directory
95+
# Exports will be saved in examples/exampleoutput/ directory (default)
96+
97+
# Or with custom output directory:
98+
EXAMPLE_OUTPUT_DIR=/tmp/my-exports python export_large_table.py
5499
```
55100

56-
### 4. [Real-time Data Processing](realtime_processing.py)
101+
### 4. [Export to Parquet Format](export_to_parquet.py)
102+
103+
Advanced example of exporting large Cassandra tables to Parquet format:
104+
- Memory-efficient streaming with page-by-page processing
105+
- Automatic schema inference from Cassandra data types
106+
- Multiple compression options (snappy, gzip, lz4)
107+
- Progress tracking during export
108+
- Handles all Cassandra data types including collections
109+
- Configurable row group sizes for optimization
110+
- Export statistics and performance metrics
111+
112+
**Run:**
113+
```bash
114+
python export_to_parquet.py
115+
# Exports will be saved in examples/exampleoutput/ directory (default)
116+
117+
# Or with custom output directory:
118+
EXAMPLE_OUTPUT_DIR=/tmp/my-parquet-exports python export_to_parquet.py
119+
```
120+
121+
**Note:** Requires PyArrow to be installed:
122+
```bash
123+
pip install pyarrow
124+
```
125+
126+
### 5. [Real-time Data Processing](realtime_processing.py)
57127

58128
Example of processing time-series data in real-time:
59129
- Sliding window analytics
@@ -67,7 +137,7 @@ Example of processing time-series data in real-time:
67137
python realtime_processing.py
68138
```
69139

70-
### 5. [Metrics Collection](metrics_simple.py)
140+
### 6. [Metrics Collection](metrics_simple.py)
71141

72142
Simple example of metrics collection:
73143
- Query performance tracking
@@ -80,7 +150,7 @@ Simple example of metrics collection:
80150
python metrics_simple.py
81151
```
82152

83-
### 6. [Advanced Metrics](metrics_example.py)
153+
### 7. [Advanced Metrics](metrics_example.py)
84154

85155
Comprehensive metrics and observability example:
86156
- Multiple metrics collectors setup
@@ -94,7 +164,21 @@ Comprehensive metrics and observability example:
94164
python metrics_example.py
95165
```
96166

97-
### 7. [Context Manager Safety](context_manager_safety_demo.py)
167+
### 8. [Non-Blocking Streaming Demo](streaming_non_blocking_demo.py)
168+
169+
Visual demonstration that streaming doesn't block the event loop:
170+
- Heartbeat monitoring to detect event loop blocking
171+
- Concurrent queries during streaming
172+
- Visual feedback showing event loop responsiveness
173+
- Performance analysis of concurrent operations
174+
- Proves the async wrapper truly keeps the event loop free
175+
176+
**Run:**
177+
```bash
178+
python streaming_non_blocking_demo.py
179+
```
180+
181+
### 9. [Context Manager Safety](context_manager_safety_demo.py)
98182

99183
Demonstrates proper context manager usage:
100184
- Context manager isolation
@@ -119,6 +203,19 @@ Production-ready monitoring configurations:
119203
- Connection health status
120204
- Error rates and trends
121205

206+
## Output Files
207+
208+
Examples that generate output files (CSV exports, Parquet exports, etc.) save them to a configurable directory:
209+
210+
- **Default location**: `examples/exampleoutput/`
211+
- **Configure via environment variable**: `EXAMPLE_OUTPUT_DIR=/path/to/output`
212+
- **Git ignored**: All files in the default output directory are ignored by Git (except README.md and .gitignore)
213+
- **Cleanup**: Files are not automatically deleted; clean up manually when needed:
214+
```bash
215+
rm -f examples/exampleoutput/*.csv
216+
rm -f examples/exampleoutput/*.parquet
217+
```
218+
122219
## Prerequisites
123220

124221
All examples require:

‎examples/context_manager_safety_demo.py‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,29 @@
44
55
This example shows how context managers properly isolate resource cleanup,
66
ensuring that errors in one operation don't close shared resources.
7+
8+
How to run:
9+
-----------
10+
1. Using Make (automatically starts Cassandra if needed):
11+
make example-context-safety
12+
13+
2. With external Cassandra cluster:
14+
CASSANDRA_CONTACT_POINTS=10.0.0.1,10.0.0.2 make example-context-safety
15+
16+
3. Direct Python execution:
17+
python examples/context_manager_safety_demo.py
18+
19+
4. With custom contact points:
20+
CASSANDRA_CONTACT_POINTS=cassandra.example.com python examples/context_manager_safety_demo.py
21+
22+
Environment variables:
23+
- CASSANDRA_CONTACT_POINTS: Comma-separated list of contact points (default: localhost)
24+
- CASSANDRA_PORT: Port number (default: 9042)
725
"""
826

927
import asyncio
1028
import logging
29+
import os
1130
import uuid
1231

1332
from cassandra import InvalidRequest
@@ -168,8 +187,14 @@ async def main():
168187
"""Run all demonstrations."""
169188
logger.info("Starting Context Manager Safety Demonstration")
170189

190+
# Get contact points from environment or use localhost
191+
contact_points = os.environ.get("CASSANDRA_CONTACT_POINTS", "localhost").split(",")
192+
port = int(os.environ.get("CASSANDRA_PORT", "9042"))
193+
194+
logger.info(f"Connecting to Cassandra at {contact_points}:{port}")
195+
171196
# Use cluster in context manager for automatic cleanup
172-
async with AsyncCluster(["localhost"]) as cluster:
197+
async with AsyncCluster(contact_points, port=port) as cluster:
173198
await demonstrate_query_error_safety(cluster)
174199
await demonstrate_streaming_error_safety(cluster)
175200
await demonstrate_context_manager_isolation(cluster)

‎examples/exampleoutput/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Ignore all files in this directory
2+
*
3+
# Except this .gitignore file
4+
!.gitignore
5+
# And the README
6+
!README.md

‎examples/exampleoutput/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Example Output Directory
2+
3+
This directory is used by the async-cassandra examples to store output files such as:
4+
- CSV exports
5+
- Parquet exports
6+
- Any other generated files
7+
8+
All files in this directory (except .gitignore and README.md) are ignored by git.
9+
10+
## Configuring Output Location
11+
12+
You can override the output directory using the `EXAMPLE_OUTPUT_DIR` environment variable:
13+
14+
```bash
15+
EXAMPLE_OUTPUT_DIR=/tmp/my-output make example-export-csv
16+
```
17+
18+
## Cleaning Up
19+
20+
To remove all generated files:
21+
```bash
22+
rm -rf examples/exampleoutput/*
23+
# Or just remove specific file types
24+
rm -f examples/exampleoutput/*.csv
25+
rm -f examples/exampleoutput/*.parquet
26+
```

0 commit comments

Comments
 (0)