# Installation

This guide covers how to install PyCharter and its optional dependencies.

## Requirements

- **Python 3.11+** (3.12 or 3.13 recommended)
- **pip** or **uv** package manager

## Quick Install

### Core Library

The core library includes validation, contracts, and Pydantic generation:

```bash
pip install pycharter
```

### With ETL Support

For ETL pipelines with cloud storage support:

```bash
pip install pycharter[etl]
```

This adds:

- `boto3` - AWS S3 support
- `google-cloud-storage` - Google Cloud Storage support
- `azure-storage-blob` - Azure Blob Storage support
- `sshtunnel` - SSH tunnel for secure database connections
- `openpyxl` - Excel file support
- `lxml` - XML file support

### With API Server

For the REST API server:

```bash
pip install pycharter[api]
```

This adds:

- `fastapi` - Web framework
- `uvicorn` - ASGI server
- `pydantic-settings` - Settings management

### With Web UI

For the interactive web interface:

```bash
pip install pycharter[ui]
```

### With Streaming Support

For real-time streaming extractors (WebSocket, FileWatcher):

```bash
pip install pycharter[streaming]
```

This adds:

- `websockets` - WebSocket extractor
- `watchfiles` - Efficient file system monitoring

### With Messaging Support

For message queue extractors (Kafka, RabbitMQ):

```bash
pip install pycharter[messaging]   # Kafka + RabbitMQ
pip install pycharter[kafka]       # Kafka only
pip install pycharter[rabbitmq]    # RabbitMQ only
```

This adds:

- `aiokafka` - Apache Kafka consumer
- `aio-pika` - RabbitMQ consumer

!!! note
    SQS support uses `boto3`, which is included in the `[etl]` extra.

### Full Installation

Install everything:

```bash
pip install pycharter[all]
```

Or pick specific extras:

```bash
pip install pycharter[api,ui,etl,streaming,messaging]
```

## Development Installation

For contributing to PyCharter:

```bash
# Clone the repository
git clone https://github.com/optophi/pycharter.git
cd pycharter

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,api,ui,etl]"

# Run tests to verify installation
pytest
```

## Database Setup

PyCharter supports multiple database backends for the metadata store:

### SQLite (Default - No Setup Required)

```python
from pycharter import SQLiteMetadataStore

store = SQLiteMetadataStore("pycharter.db")
store.connect()
```

### PostgreSQL

1. Install PostgreSQL and create a database:

```bash
createdb pycharter
```

2. Install the PostgreSQL driver:

```bash
pip install psycopg2-binary
```

3. Connect:

```python
from pycharter import PostgresMetadataStore

store = PostgresMetadataStore("postgresql://user:pass@localhost/pycharter")
store.connect()
```

### MongoDB

1. Install MongoDB and start the server

2. Install the MongoDB driver:

```bash
pip install pymongo
```

3. Connect:

```python
from pycharter import MongoDBMetadataStore

store = MongoDBMetadataStore("mongodb://localhost:27017/pycharter")
store.connect()
```

### Redis

1. Install Redis and start the server

2. Install the Redis driver:

```bash
pip install redis
```

3. Connect:

```python
from pycharter import RedisMetadataStore

store = RedisMetadataStore("redis://localhost:6379/0")
store.connect()
```

## Verify Installation

Run the following to verify your installation:

```python
import pycharter
print(f"PyCharter version: {pycharter.__version__}")

# Test basic functionality
from pycharter import from_dict, validate

schema = {
    "type": "object",
    "version": "1.0.0",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name"]
}

Model = from_dict(schema, "TestModel")
result = validate(Model, {"name": "Test", "age": 25})
print(f"Validation passed: {result.is_valid}")
```

## CLI Verification

After installation, the `pycharter` CLI should be available:

```bash
# Check version
pycharter --version

# Start API server (if [api] installed)
pycharter api

# Start UI development server (if [ui] installed)
pycharter ui serve
```

## Troubleshooting

### Import Errors

If you get import errors, ensure you have the correct optional dependencies:

```bash
# Check what's installed
pip show pycharter

# Reinstall with extras
pip install --upgrade pycharter[api,ui,etl]
```

### Database Connection Issues

For PostgreSQL connection issues:

```bash
# Test connection
psql postgresql://user:pass@localhost/pycharter -c "SELECT 1"

# Check if psycopg2 is installed
python -c "import psycopg2; print('OK')"
```

### Permission Errors

On macOS/Linux, you may need to use `pip install --user` or a virtual environment.

## Next Steps

- [Quick Start Guide](quickstart.md) - Run your first pipeline
- [Core Concepts](concepts.md) - Understand PyCharter's architecture
- [ETL Tutorial](../tutorials/etl-pipelines.md) - Build data pipelines
