# API Reference

Complete reference documentation for PyCharter's Python API.

## Module Overview

```
pycharter
├── Pipeline              # ETL pipeline orchestration
├── Validator             # Data validation
├── QualityCheck          # Quality monitoring
├── etl_generator/        # ETL components
│   ├── extractors/       # Data extraction
│   ├── transformers/     # Data transformation
│   ├── loaders/          # Data loading
│   ├── state             # Incremental extraction state stores
│   └── testing           # Mock components and test harness
├── contract_parser/      # Contract parsing
├── contract_builder/     # Contract building
├── metadata_store/       # Schema registry
├── schema_evolution/     # Schema versioning
├── pydantic_generator/   # Model generation
├── json_schema_converter/ # Schema conversion
├── docs_generator/       # Contract documentation generation
├── domain/               # Lifecycle binding (FSM integration)
├── wiki/                 # Ontology, knowledge graph, governance
└── shared/               # Utilities and errors
```

## Quick Links

### Core Classes

| Class | Description |
|-------|-------------|
| [`Pipeline`](pipeline.md) | ETL pipeline orchestration |
| [`Validator`](validator.md) | Data validation |
| [`QualityCheck`](quality-check.md) | Quality monitoring |

### ETL Components

| Module | Description |
|--------|-------------|
| [`Extractors`](extractors.md) | HTTP, File, Database, Cloud |
| [`Transformers`](transformers.md) | Rename, Filter, AddField, etc. |
| [`Loaders`](loaders.md) | Postgres, File, Cloud |

### Contract Management

| Module | Description |
|--------|-------------|
| [`Contract Parser`](contract-parser.md) | Parse contract files |
| [`Contract Builder`](contract-builder.md) | Build contracts |

### Storage

| Module | Description |
|--------|-------------|
| [`Metadata Store`](metadata-store.md) | Schema registry |
| [`Schema Evolution`](schema-evolution.md) | Versioning & compatibility |

### Utilities & Extensions

| Module | Description |
|--------|-------------|
| [`Pydantic Generator`](pydantic-generator.md) | Generate Pydantic models from schemas |
| [`JSON Schema Converter`](json-schema-converter.md) | Convert Pydantic ↔ JSON Schema |
| [`Docs Generator`](docs-generator.md) | Generate Markdown docs from contracts |
| [`Domain`](domain.md) | Lifecycle binding for FSM engines |
| [`Wiki & Ontology`](wiki.md) | Semantic annotations, knowledge graph, governance |
| [`Testing Framework`](testing.md) | Mock components and pipeline test harness |
| [`Errors`](errors.md) | Exception hierarchy |

## Import Patterns

### Recommended Imports

```python
# Core classes
from pycharter import Pipeline, Validator, QualityCheck

# ETL components
from pycharter import (
    HTTPExtractor, FileExtractor, DatabaseExtractor, CloudStorageExtractor,
    Rename, Filter, AddField, Drop, Select, Convert, CustomFunction,
    PostgresLoader, FileLoader, CloudStorageLoader,
)

# Metadata stores
from pycharter import (
    InMemoryMetadataStore,
    SQLiteMetadataStore,
    PostgresMetadataStore,
    MongoDBMetadataStore,
    RedisMetadataStore,
)

# Convenience functions
from pycharter import (
    from_dict, from_file, from_json,
    to_dict, to_file, to_json,
    validate, validate_batch,
    parse_contract_file, build_contract,
)

# Errors
from pycharter.shared.errors import (
    PyCharterError,
    ConfigError,
    ConfigValidationError,
    ExpressionError,
)
```

## Type Annotations

PyCharter is fully typed with `py.typed` marker:

```python
from pycharter import Validator, ValidationResult

def process_data(validator: Validator, data: dict) -> ValidationResult:
    return validator.validate(data)
```

## Async Support

All pipeline operations are async:

```python
import asyncio
from pycharter import Pipeline

# From script
result = asyncio.run(pipeline.run())

# From async function
async def main():
    result = await pipeline.run()
    return result
```

See the [Async Execution Model guide](../guides/async-execution.md) for detailed guidance on running pipelines from scripts, FastAPI, notebooks, and Celery.
