Create Comprehensive Adapter Reference Guide

[ohdearquant]

Description

Create comprehensive documentation for all available adapters in pydapter. Each adapter should have its own dedicated page with consistent structure, examples, and best practices.

Rationale

The pydapter library includes numerous adapters for different data formats and databases, but users need clear documentation on how to use each one. According to the "Documentation Goldmine" file, successful libraries use a consistent documentation structure across components. Looking at popular Python libraries like SQLAlchemy and Pydantic, thorough reference documentation is critical for adoption.

Tasks

• Create a consistent template for adapter documentation with the following sections:

  • Overview and purpose
  • Installation (including optional dependencies)
  • Basic usage
  • Configuration options
  • Error handling
  • Advanced usage
  • Examples

• Document file format adapters:

  • JsonAdapter (src/pydapter/adapters/json_.py)
  • CsvAdapter (src/pydapter/adapters/csv_.py)
  • TomlAdapter (src/pydapter/adapters/toml_.py)

• Document database adapters:

  • PostgresAdapter (src/pydapter/extras/postgres_.py)
  • AsyncPostgresAdapter (src/pydapter/extras/async_postgres_.py)
  • MongoAdapter (src/pydapter/extras/mongo_.py)
  • AsyncMongoAdapter (src/pydapter/extras/async_mongo_.py)
  • Neo4jAdapter (src/pydapter/extras/neo4j_.py)
  • QdrantAdapter (src/pydapter/extras/qdrant_.py)
  • AsyncQdrantAdapter (src/pydapter/extras/async_qdrant_.py)

• Document data analysis adapters:

  • DataFrameAdapter (src/pydapter/extras/pandas_.py)
  • SeriesAdapter (src/pydapter/extras/pandas_.py)
  • ExcelAdapter (src/pydapter/extras/excel_.py)

• Create a comparison table showing features and use cases for different adapters

• Add common patterns and best practices for each adapter type

Example Adapter Documentation Template

# JsonAdapter

## Overview

The `JsonAdapter` provides conversion between Pydantic models and JSON format. It supports both serialization (model to JSON) and deserialization (JSON to model).

## Installation

The JsonAdapter is included in the core pydapter package:

```python
pip install pydapter

Basic Usage

from pydantic import BaseModel
from pydapter import Adaptable
from pydapter.adapters.json_ import JsonAdapter

class User(BaseModel, Adaptable):
    id: int
    name: str
    email: str

# Register the adapter
User.register_adapter(JsonAdapter)

# Create a user
user = User(id=1, name="Alice", email="alice@example.com")

# Convert to JSON
json_data = user.adapt_to(obj_key="json")
print(json_data)

# Convert back to model
loaded_user = User.adapt_from(json_data, obj_key="json")

Configuration Options

Option	Default	Description
indent	2	Number of spaces for indentation
sort_keys	True	Whether to sort keys alphabetically
ensure_ascii	False	Whether to escape non-ASCII characters

Error Handling

The JsonAdapter can raise the following exceptions:

• ParseError: When the JSON cannot be parsed
• ValidationError: When the parsed JSON doesn't match the model schema

try:
    User.adapt_from('{"invalid": "json"}', obj_key="json")
except ParseError as e:
    print(f"JSON parsing error: {e}")
except ValidationError as e:
    print(f"Validation error: {e}")

Advanced Usage

Handling Collections

# Convert a list of models to JSON
users = [
    User(id=1, name="Alice", email="alice@example.com"),
    User(id=2, name="Bob", email="bob@example.com")
]

# Serialize list (many=True)
json_data = JsonAdapter.to_obj(users, many=True)

# Deserialize list (many=True)
loaded_users = User.adapt_from(json_data, obj_key="json", many=True)

File Handling

from pathlib import Path

# Write to file
Path("users.json").write_text(json_data)

# Read from file
file_path = Path("users.json")
loaded_users = User.adapt_from(file_path, obj_key="json", many=True)

## References

- Pydantic documentation: https://docs.pydantic.dev/
- SQLAlchemy documentation: https://docs.sqlalchemy.org/
- FastAPI documentation: https://fastapi.tiangolo.com/
- JSON Schema: https://json-schema.org/

## Expected Outcome

Complete, consistent documentation for all adapters that:
1. Follows a unified structure
2. Provides clear examples for common use cases
3. Includes error handling guidance
4. Highlights advanced features
5. Shows integration with related adapters

This will make it easier for users to understand and effectively use all available adapters in the library.