Metadata-Version: 2.4
Name: autoendpoint
Version: 0.4.0
Summary: Library to create basics endpoints from Models SQLModels
Requires-Python: >=3.14
Requires-Dist: fastapi>=0.129.0
Requires-Dist: sqlmodel>=0.0.33
Requires-Dist: strawberry-graphql[fastapi]>=0.312.0
Provides-Extra: postgresql
Requires-Dist: asyncpg>=0.31.0; extra == 'postgresql'
Requires-Dist: greenlet>=3.3.2; extra == 'postgresql'
Requires-Dist: psycopg2-binary>=2.9.11; extra == 'postgresql'
Description-Content-Type: text/markdown

# Auto Endpoint

`autoendpoint` is a lightweight library for FastAPI that automatically generates asynchronous RESTful API endpoints for your SQLModel classes. It simplifies the creation of CRUD operations by dynamically building Pydantic models for data validation and handling database interactions using SQLAlchemy's `AsyncSession`.

## Key Features

- **Full CRUD Endpoints**: Automatically generates `GET` (all), `POST` (create), `GET` (by ID), `PUT` (update), `PATCH` (partial update), `DELETE`, `GET` (by unique field), and `GET` (by any field filter) endpoints for any SQLModel.
- **Dynamic GraphQL Endpoint**: Automatically generates a GraphQL schema and adds a `/graphql` endpoint (powered by Strawberry) to query your models.
- **Model Consistency Check**: Optional feature to verify that your SQLModel classes match the actual database tables (existence and columns) during development. See [Model Consistency Check](#model-consistency-check) for more details.
- **Automatic Relationship Discovery**: Automatically identifies and maps `SQLModel` relationships into the GraphQL schema, enabling seamless nested queries (e.g., fetching a `Profile` or `Posts` through a `UserAccount`) with automatic pre-loading to prevent `MissingGreenlet` errors.
- **String Representation in GraphQL**: Automatically includes a `string_representation` field in GraphQL queries, which uses your model's `__str__` method for flexible object display.
- **Enhanced OpenAPI Documentation**: All generated endpoint parameters (Body, Path, Query) include clear, dynamic descriptions for better readability in tools like FastMCP and Swagger UI.
- **Asynchronous Support**: Built for high-performance async workflows using `AsyncSession`.
- **Smart Model Generation**: Dynamically creates schemas for creation, full updates, and partial updates (PATCH), excluding primary keys from request bodies.
- **Flexible Retrieval**: 
    - **Unique Retrieval**: Endpoint to fetch a single record by any unique field (e.g., email), with error handling for duplicates.
    - **Generic Filtering**: New endpoint to retrieve multiple records by any field and value.
- **FastAPI Integration**: Seamlessly integrates with existing FastAPI applications using an `APIRouter`.
- **Type Safety**: Leverages Python type hints and SQLModel/Pydantic for robust validation.
- **Google Style Docstrings**: Fully documented for Sphinx compatibility.

## Installation

You can install `autoendpoint` using `uv`. To include asynchronous database support (e.g., PostgreSQL), use the `postgresql` extra:

```bash
# Basic installation
uv add autoendpoint

# Installation with PostgreSQL support (asyncpg, greenlet, psycopg2-binary)
uv add "autoendpoint[postgresql]"
```

*Note: The library is designed to be driver-agnostic but requires `greenlet` and a compatible async driver (like `asyncpg` or `aiosqlite`) for SQLAlchemy's asynchronous operations.*

## Quick Start

Here's how to use `AutoEndpoint` in your FastAPI project:

### 1. Define your SQLModel

```python
import uuid
from sqlmodel import Field, SQLModel
from typing import Optional

class Hero(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    name: str
    secret_name: str
    age: Optional[int] = None
    email: str = Field(unique=True)

    def __str__(self):
        return f"{self.name} ({self.age or '?'})"
```

### 2. Set up the Async Engine and Session

```python
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "postgresql+asyncpg://user:password@localhost/dbname"
engine = create_async_engine(DATABASE_URL)
async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
```

### 3. Initialize and Register Endpoints

```python
from fastapi import FastAPI
from autoendpoint.core import AutoEndpoint

app = FastAPI()

@app.on_event("startup")
async def startup():
    async with async_session_maker() as session:
        # Create endpoints for the Hero model
        # Note: In a production app, you might want to manage the session differently
        # enable_graphql defaults to True
        # check_consistency=True checks if models match DB tables at startup
        my_endpoints = AutoEndpoint(
            db_session=session, 
            models=[Hero], 
            enable_graphql=True, 
            check_consistency=True
        )
        my_endpoints.init_app(app=app)
```

## Generated Endpoints

For a model named `Hero`, the following endpoints are automatically generated:

- **GET `/hero`**: List records. Supports pagination via query parameters:
    - `limit`: The maximum number of records to return (default: 10). Set `limit=0` to return all records.
    - `page`: The page number to return (default: 1).
- **POST `/hero`**: Create a new record. Primary key is excluded from the request body and expected to be server-side or factory generated.
- **POST `/hero/bulk/csv`**: Bulk create records from a CSV file. The file must be UTF-8 encoded and have a `.csv` extension. Supports:
    - `has_header` (default: `true`): Whether the CSV file has a header row. If `true`, columns are mapped by header names. If `false`, columns are mapped by the model's field order as defined in the creation schema.
- **GET `/hero/{id}`**: Retrieve a single record by its primary key.
- **PUT `/hero/{id}`**: Update all fields of a record (excluding primary key).
- **PATCH `/hero/{id}`**: Partially update fields of a record (excluding primary key).
- **DELETE `/hero/{id}`**: Delete a record by its primary key.
- **GET `/hero/unique/{field_name}?value=...`**: Retrieve a single record by any unique field (e.g., `/hero/unique/email?value=test@example.com`). Raises a 400 error if multiple records are found.
- **GET `/hero/filter/{field_name}?value=...`**: Retrieve all records matching a specific field and value (e.g., `/hero/filter/age?value=30`).
- **GET `/hero/{hero_id}/{relationship_name}`**: Retrieve related record(s) for a specific record:
    - Returns a list for **one-to-many (1:n)** relationships (e.g., `/user/{user_id}/posts`).
    - Returns a single object for **one-to-one (1:1)** relationships (e.g., `/user/{user_id}/profile`).
- **POST `/hero/{hero_id}/{relationship_name}/{target_id}`**: Link a record to another record in a many-to-many relationship (e.g., `/user/{user_id}/groups/{group_id}`).
- **PATCH `/hero/{hero_id}/{relationship_name}/{target_id}`**: Update the link record itself in a many-to-many relationship (useful if the link table has extra fields).
- **DELETE `/hero/{hero_id}/{relationship_name}/{target_id}`**: Unlink a record from another record in a many-to-many relationship.
- **POST `/graphql`**: The GraphQL endpoint (if enabled) for querying your models. Includes a `string_representation` field for each model that reflects its `__str__` output.

## FastMCP Compatibility

The generated endpoints are enhanced with `description` fields for all parameters, making them highly readable and easy to use with [FastMCP](https://github.com/jlowin/fastmcp) and other LLM-friendly tools. Each parameter explicitly describes its role (e.g., "The Hero data to create" or "The Hero record to retrieve by id"). In Swagger UI, you will see detailed descriptions for every path parameter, query parameter, and request body.

## Model Consistency Check

To ensure that your `SQLModel` definitions match the actual state of your database, `AutoEndpoint` includes an optional consistency check that runs at startup.

### What it checks:
- **Table Existence**: Verifies that the table for each model exists in the database.
- **Column Matching**: Compares the columns defined in your model with the columns present in the database table. It identifies:
    - Columns present in the model but missing in the database.
    - Columns present in the database but missing in the model.
- **Schema Support**: Handles models with specified database schemas.

### How it works:
- It runs as an asynchronous background task when the FastAPI application starts (inside `AutoEndpoint.init_app` logic).
- If any inconsistency is found, it will raise a `RuntimeError` and print a detailed error message to `stderr`, explaining exactly what is missing or extra. This helps catch schema mismatches early during development.

### How to use:
You can control the consistency check via the `check_consistency` parameter when initializing `AutoEndpoint`.

- **Enable**: Set `check_consistency=True` (useful during development).
- **Disable**: Set `check_consistency=False` (default, recommended for production).

```python
my_endpoints = AutoEndpoint(
    db_session=session, 
    models=[Hero], 
    check_consistency=True # Enable the check
)
```

## Documentation

The project includes Sphinx documentation and test coverage reports.

In GitLab CI, these are automatically generated and hosted via GitLab Pages:
- **Documentation**: ` https://autoendpoint-beaddd.gitlab.io/docs/`
- **Coverage Report**: ` https://autoendpoint-beaddd.gitlab.io/coverage/`

Methods are documented using the Google format.

## License

Under construction.