Bulk DOcs (#10)

Author: millerjp

CONTRIBUTING.md

@@ -114,6 +114,10 @@ Your PR description should include:
 
 For detailed development instructions, see our [Developer Documentation](developerdocs/).
 
+This is a monorepo containing two packages:
+- **async-cassandra** - The main async wrapper library (in `libs/async-cassandra/`)
+- **async-cassandra-bulk** - Bulk operations extension (in `libs/async-cassandra-bulk/`)
+
 Here's how to set up `async-python-cassandra-client` for local development:
 
 1. Fork the `async-python-cassandra-client` repo on GitHub.
@@ -127,6 +131,13 @@ Here's how to set up `async-python-cassandra-client` for local development:
    cd async-python-cassandra-client/
    python -m venv venv
    source venv/bin/activate  # On Windows use `venv\Scripts\activate`
+
+   # Install the main library
+   cd libs/async-cassandra
+   pip install -e ".[dev,test]"
+
+   # Optionally install the bulk operations library
+   cd ../async-cassandra-bulk
    pip install -e ".[dev,test]"
    ```
 
@@ -139,13 +150,16 @@ Here's how to set up `async-python-cassandra-client` for local development:
 
 6. When you're done making changes, check that your changes pass the tests:
    ```bash
+   # Navigate to the library you're working on
+   cd libs/async-cassandra  # or libs/async-cassandra-bulk
+
    # Run linting
    ruff check src tests
    black --check src tests
    isort --check-only src tests
    mypy src
 
-   # Run tests
+   # Run tests (from the library directory)
    make test-unit  # Unit tests only (no Cassandra needed)
    make test-integration  # Integration tests (starts Cassandra automatically)
    make test  # All tests except stress tests
@@ -177,6 +191,9 @@ Before you submit a pull request, check that it meets these guidelines:
 ### Running Tests Locally
 
 ```bash
+# Navigate to the library you want to test
+cd libs/async-cassandra  # or libs/async-cassandra-bulk
+
 # Install test dependencies
 pip install -e ".[test]"
 
@@ -190,14 +207,15 @@ make test-integration
 pytest tests/unit/test_session.py -v
 
 # Run with coverage
-pytest --cov=src/async_cassandra --cov-report=html
+pytest --cov=async_cassandra --cov-report=html  # or --cov=async_cassandra_bulk
 ```
 
 ### Cassandra Management for Testing
 
 Integration tests require a running Cassandra instance. The test infrastructure handles this automatically:
 
 ```bash
+# From the library directory (libs/async-cassandra or libs/async-cassandra-bulk)
 # Automatically handled by test commands:
 make test-integration  # Starts Cassandra if needed
 make test             # Starts Cassandra if needed
@@ -226,6 +244,7 @@ This project uses several tools to maintain code quality and consistency:
 Before submitting a PR, ensure your code passes all checks:
 
 ```bash
+# From the library directory (libs/async-cassandra or libs/async-cassandra-bulk)
 # Format code
 black src tests
 isort src tests

README.md

@@ -9,8 +9,16 @@
 
 > 📢 **Early Release**: This is an early release of async-cassandra. While it has been tested extensively, you may encounter edge cases. We welcome your feedback and contributions! Please report any issues on our [GitHub Issues](https://github.com/axonops/async-python-cassandra-client/issues) page.
 
+## 📦 Repository Structure
+
+This is a monorepo containing two related Python packages:
+
+- **[async-cassandra](libs/async-cassandra/)** - The main async wrapper for the Cassandra Python driver, enabling async/await operations with Cassandra
+- **[async-cassandra-bulk](libs/async-cassandra-bulk/)** - (🚧 Active Development) High-performance bulk operations extension for async-cassandra
+
 ## 📑 Table of Contents
 
+- [📦 Repository Structure](#-repository-structure)
 - [✨ Overview](#-overview)
 - [🏗️ Why create this framework?](#️-why-create-this-framework)
   - [Understanding Async vs Sync](#understanding-async-vs-sync)
@@ -40,7 +48,7 @@
 
 ## ✨ Overview
 
-A Python library that enables the Cassandra driver to work seamlessly with async frameworks like FastAPI, aiohttp, and Quart. It provides an async/await interface that prevents blocking your application's event loop while maintaining full compatibility with the DataStax Python driver.
+**async-cassandra** is a Python library that enables the Cassandra driver to work seamlessly with async frameworks like FastAPI, aiohttp, and Quart. It provides an async/await interface that prevents blocking your application's event loop while maintaining full compatibility with the DataStax Python driver.
 
 When using the standard Cassandra driver in async applications, blocking operations can freeze your entire service. This wrapper solves that critical issue by bridging the gap between Cassandra's thread-based I/O and Python's async ecosystem, ensuring your web services remain responsive under load.
 
@@ -248,14 +256,21 @@ We understand this requirement may be inconvenient for some users, but it allows
 
 ## 🔧 Installation
 
+### async-cassandra (Main Library)
+
 ```bash
 # From PyPI
 pip install async-cassandra
 
-# From source
+# From source (for development)
+cd libs/async-cassandra
 pip install -e .
 ```
 
+### async-cassandra-bulk (Coming Soon)
+
+> 🚧 **In Active Development**: async-cassandra-bulk is currently under development and not yet available on PyPI. It will provide high-performance bulk operations for async-cassandra.
+
 ## 📚 Quick Start
 
 ```python
@@ -313,16 +328,21 @@ We welcome contributions! Please see:
 - [Metrics and Monitoring](docs/metrics-monitoring.md) - Track performance and health
 
 ### Examples
-- [FastAPI Integration](examples/fastapi_app/README.md) - Complete REST API example
-- [More Examples](examples/) - Additional usage patterns
+- [FastAPI Integration](libs/async-cassandra/examples/fastapi_app/README.md) - Complete REST API example
+- [More Examples](libs/async-cassandra/examples/) - Additional usage patterns
 
 ## 🎯 Running the Examples
 
-The project includes comprehensive examples demonstrating various features and use cases. Each example can be run using the provided Makefile, which automatically handles Cassandra setup if needed.
+The async-cassandra library includes comprehensive examples demonstrating various features and use cases. Examples are located in the `libs/async-cassandra/examples/` directory.
 
-### Available Examples
+### Running Examples
 
-Run any example with: `make example-<name>`
+First, navigate to the async-cassandra directory:
+```bash
+cd libs/async-cassandra
+```
+
+Then run any example with: `make example-<name>`
 
 - **`make example-basic`** - Basic connection and query execution
 - **`make example-streaming`** - Memory-efficient streaming of large result sets with True Async Paging
@@ -339,6 +359,9 @@ Run any example with: `make example-<name>`
 If you have Cassandra running elsewhere:
 
 ```bash
+# From the libs/async-cassandra directory:
+cd libs/async-cassandra
+
 # Single node
 CASSANDRA_CONTACT_POINTS=10.0.0.1 make example-streaming
 

docs/architecture.md

@@ -92,7 +92,7 @@ The DataStax driver's `execute_async()` returns a `ResponseFuture` that will be
 
 ### 2. The Bridge: AsyncResultHandler
 
-The magic happens in `AsyncResultHandler` ([src/async_cassandra/result.py](../src/async_cassandra/result.py)):
+The magic happens in `AsyncResultHandler` ([src/async_cassandra/result.py](../libs/async-cassandra/src/async_cassandra/result.py)):
 
 ```python
 class AsyncResultHandler:
@@ -153,7 +153,7 @@ async def get_result(self, timeout: Optional[float] = None) -> "AsyncResultSet":
 
 ### 5. Driver Thread Pool Configuration
 
-The driver's thread pool size is configurable ([src/async_cassandra/cluster.py](../src/async_cassandra/cluster.py)):
+The driver's thread pool size is configurable ([src/async_cassandra/cluster.py](../libs/async-cassandra/src/async_cassandra/cluster.py)):
 
 ```python
 def __init__(self, ..., executor_threads: int = 2, ...):

docs/getting-started.md

@@ -505,4 +505,4 @@ except ConfigurationError as e:
 - [Connection Pooling](connection-pooling.md) - Understanding connection behavior
 - [Streaming](streaming.md) - Handling large result sets
 - [Performance](performance.md) - Optimization tips
-- [FastAPI Example](../examples/fastapi_app/) - Full production example
+- [FastAPI Example](../libs/async-cassandra/examples/fastapi_app/) - Full production example

docs/thread-pool-configuration.md

@@ -88,9 +88,9 @@ if __name__ == "__main__":
 
 For more examples of thread pool configuration:
 
-- **Unit Tests**: [`tests/unit/test_thread_pool_configuration.py`](../tests/unit/test_thread_pool_configuration.py) - Demonstrates configuration options and verifies behavior
-- **Integration Tests**: [`tests/integration/test_thread_pool_configuration.py`](../tests/integration/test_thread_pool_configuration.py) - Shows real-world usage patterns
-- **Example Script**: [`examples/thread_pool_configuration.py`](../examples/thread_pool_configuration.py) - Interactive examples comparing different thread pool sizes
+- **Unit Tests**: [`tests/unit/test_thread_pool_configuration.py`](../libs/async-cassandra/tests/unit/test_thread_pool_configuration.py) - Demonstrates configuration options and verifies behavior
+- **Integration Tests**: [`tests/integration/test_thread_pool_configuration.py`](../libs/async-cassandra/tests/integration/test_thread_pool_configuration.py) - Shows real-world usage patterns
+- **Example Script**: [`examples/thread_pool_configuration.py`](../libs/async-cassandra/examples/thread_pool_configuration.py) - Interactive examples comparing different thread pool sizes
 
 ## Official Documentation
 

docs/why-async-wrapper.md

@@ -113,7 +113,7 @@ session = await cluster.connect()
 # Reuse session for all requests - DO NOT close after each use
 ```
 
-**Note**: While async-cassandra provides context manager support for convenience in scripts and tests, production applications should create clusters and sessions once at startup and reuse them throughout the application lifetime. See the [FastAPI example](../examples/fastapi_app/main.py) for the correct pattern.
+**Note**: While async-cassandra provides context manager support for convenience in scripts and tests, production applications should create clusters and sessions once at startup and reuse them throughout the application lifetime. See the [FastAPI example](../libs/async-cassandra/examples/fastapi_app/main.py) for the correct pattern.
 
 ## 4. Lack of Async-First API Design
 
@@ -344,7 +344,7 @@ def _asyncio_future_from_response_future(response_future):
    - Clean async/await syntax
    - Natural error handling with try/except
    - Integration with async frameworks (FastAPI, aiohttp)
-   - See our [FastAPI example](../examples/fastapi_app/README.md) for a complete implementation
+   - See our [FastAPI example](../libs/async-cassandra/examples/fastapi_app/README.md) for a complete implementation
 
 2. **Event Loop Compatibility**:
    - Prevents blocking the event loop with synchronous calls

libs/async-cassandra-bulk/README_PYPI.md

@@ -1,16 +1,16 @@
-# async-cassandra-bulk
+# async-cassandra-bulk (🚧 Active Development)
 
 [![PyPI version](https://badge.fury.io/py/async-cassandra-bulk.svg)](https://badge.fury.io/py/async-cassandra-bulk)
 [![Python versions](https://img.shields.io/pypi/pyversions/async-cassandra-bulk.svg)](https://pypi.org/project/async-cassandra-bulk/)
 [![License](https://img.shields.io/pypi/l/async-cassandra-bulk.svg)](https://github.com/axonops/async-python-cassandra-client/blob/main/LICENSE)
 
-High-performance bulk operations for Apache Cassandra, built on [async-cassandra](https://pypi.org/project/async-cassandra/).
+High-performance bulk operations extension for Apache Cassandra, built on [async-cassandra](https://pypi.org/project/async-cassandra/).
 
-> 📢 **Early Development**: This package is in early development. Features are being actively added.
+> 🚧 **Active Development**: This package is currently under active development and not yet feature-complete. The API may change as we work towards a stable release. For production use, we recommend using [async-cassandra](https://pypi.org/project/async-cassandra/) directly.
 
 ## 🎯 Overview
 
-async-cassandra-bulk provides high-performance data import/export capabilities for Apache Cassandra databases. It leverages token-aware parallel processing to achieve optimal throughput while maintaining memory efficiency.
+**async-cassandra-bulk** will provide high-performance data import/export capabilities for Apache Cassandra databases. Once complete, it will leverage token-aware parallel processing to achieve optimal throughput while maintaining memory efficiency.
 
 ## ✨ Key Features (Coming Soon)
 
@@ -29,7 +29,20 @@ pip install async-cassandra-bulk
 
 ## 🚀 Quick Start
 
-Coming soon! This package is under active development.
+```python
+import asyncio
+from async_cassandra_bulk import hello
+
+async def main():
+    # This is a placeholder function for testing
+    message = await hello()
+    print(message)  # "Hello from async-cassandra-bulk!"
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+> **Note**: Full functionality is coming soon! This is currently a skeleton package in active development.
 
 ## 📖 Documentation
 

libs/async-cassandra/README_PYPI.md

@@ -6,11 +6,11 @@
 
 > 📢 **Early Release**: This is an early release of async-cassandra. While it has been tested extensively, you may encounter edge cases. We welcome your feedback and contributions! Please report any issues on our [GitHub Issues](https://github.com/axonops/async-python-cassandra-client/issues) page.
 
-> 🚀 **Looking for bulk operations?** Check out [async-cassandra-bulk](https://pypi.org/project/async-cassandra-bulk/) for high-performance data import/export capabilities.
+> 🚀 **Looking for bulk operations?** [async-cassandra-bulk](https://pypi.org/project/async-cassandra-bulk/) is currently in active development and will provide high-performance data import/export capabilities.
 
 ## 🎯 Overview
 
-A Python library that enables true async/await support for Cassandra database operations. This package wraps the official DataStax™ Cassandra driver to make it compatible with async frameworks like **FastAPI**, **aiohttp**, and **Quart**.
+**async-cassandra** is the core library that enables true async/await support for Cassandra database operations. This package wraps the official DataStax™ Cassandra driver to make it compatible with async frameworks like **FastAPI**, **aiohttp**, and **Quart**.
 
 When using the standard Cassandra driver in async applications, blocking operations can freeze your entire service. This wrapper solves that critical issue by bridging Cassandra's thread-based operations with Python's async ecosystem.
 

libs/async-cassandra/examples/README.md

@@ -2,13 +2,28 @@
 
 This directory contains working examples demonstrating various features and use cases of async-cassandra.
 
+## 📍 Important: Directory Context
+
+All examples must be run from the `libs/async-cassandra` directory, not from this examples directory:
+
+```bash
+# Navigate to the async-cassandra library directory first
+cd libs/async-cassandra
+
+# Then run examples using make
+make example-streaming
+```
+
 ## Quick Start
 
 ### Running Examples with Make
 
-The easiest way to run examples is using the provided Make targets:
+The easiest way to run examples is using the provided Make targets from the `libs/async-cassandra` directory:
 
 ```bash
+# From the libs/async-cassandra directory:
+cd libs/async-cassandra
+
 # Run a specific example (automatically starts Cassandra if needed)
 make example-streaming
 make example-export-csv
@@ -30,6 +45,9 @@ CASSANDRA_CONTACT_POINTS=node1.example.com,node2.example.com make example-stream
 Some examples require additional dependencies:
 
 ```bash
+# From the libs/async-cassandra directory:
+cd libs/async-cassandra
+
 # Install all example dependencies (including pyarrow for Parquet export)
 make install-examples
 
@@ -77,6 +95,10 @@ Demonstrates streaming functionality for large result sets:
 
 **Run:**
 ```bash
+# From libs/async-cassandra directory:
+make example-streaming
+
+# Or run directly (from this examples directory):
 python streaming_basic.py
 ```
 
@@ -91,6 +113,10 @@ Shows how to export large Cassandra tables to CSV:
 
 **Run:**
 ```bash
+# From libs/async-cassandra directory:
+make example-export-large-table
+
+# Or run directly (from this examples directory):
 python export_large_table.py
 # Exports will be saved in examples/exampleoutput/ directory (default)
 

libs/async-cassandra/examples/exampleoutput/README.md

@@ -12,13 +12,17 @@ All files in this directory (except .gitignore and README.md) are ignored by git
 You can override the output directory using the `EXAMPLE_OUTPUT_DIR` environment variable:
 
 ```bash
+# From the libs/async-cassandra directory:
+cd libs/async-cassandra
 EXAMPLE_OUTPUT_DIR=/tmp/my-output make example-export-csv
 ```
 
 ## Cleaning Up
 
 To remove all generated files:
 ```bash
+# From the libs/async-cassandra directory:
+cd libs/async-cassandra
 rm -rf examples/exampleoutput/*
 # Or just remove specific file types
 rm -f examples/exampleoutput/*.csv