Metadata-Version: 2.4
Name: fastapi-admin-sdk
Version: 0.1.0
Summary: A FastAPI admin SDK for building admin interfaces with resource management, permissions, and CRUD operations
Project-URL: Homepage, https://github.com/yourusername/fastapi-admin-sdk
Project-URL: Documentation, https://github.com/yourusername/fastapi-admin-sdk#readme
Project-URL: Repository, https://github.com/yourusername/fastapi-admin-sdk
Project-URL: Issues, https://github.com/yourusername/fastapi-admin-sdk/issues
Author-email: Your Name <your.email@example.com>
License: MIT
License-File: LICENSE
Keywords: admin,async,crud,fastapi,rest-api,sdk,sqlalchemy
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: fastapi[standard]>=0.128.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: sqlalchemy[asyncio]>=2.0.45
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# FastAPI Admin SDK

[![Coverage](https://codecov.io/gh/yourusername/fastapi-admin-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/fastapi-admin-sdk)
[![PyPI version](https://badge.fury.io/py/fastapi-admin-sdk.svg)](https://badge.fury.io/py/fastapi-admin-sdk)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/yourusername/fastapi-admin-sdk)

A FastAPI admin SDK for building admin interfaces with resource management, permissions, and CRUD operations.

## Installation

Install the package using pip:

```bash
pip install fastapi-admin-sdk
```

Or using uv:

```bash
uv add fastapi-admin-sdk
```

## Quick Start

### 1. Configure Settings

Set up your environment variables:

```bash
export ADMIN_DB_URL="postgresql+asyncpg://user:password@localhost/dbname"
export ORM_TYPE="sqlalchemy"
```

Or create a `.env` file:

```env
ADMIN_DB_URL=postgresql+asyncpg://user:password@localhost/dbname
ORM_TYPE=sqlalchemy
```

### 2. Define Your Model

```python
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    email: Mapped[str]
```

### 3. Create a Resource

```python
from fastapi_admin_sdk import Resource, SQLAlchemyResource
from fastapi_admin_sdk.db import get_session_factory

session_factory = get_session_factory()
user_resource = SQLAlchemyResource(
    model=User,
    session_factory=session_factory,
    lookup_field="id"
)
```

### 4. Create an Admin Class

```python
from fastapi import Request
from pydantic import BaseModel
from fastapi_admin_sdk import BaseAdmin, register

class UserCreateSchema(BaseModel):
    name: str
    email: str

class UserUpdateSchema(BaseModel):
    name: str | None = None
    email: str | None = None

@register(user_resource)
class UserAdmin(BaseAdmin):
    list_display = ["id", "name", "email"]
    list_filter = ["name"]
    search_fields = ["name", "email"]
    ordering = ["id"]
    
    create_form_schema = UserCreateSchema
    update_form_schema = UserUpdateSchema
    lookup_field = "id"
    
    async def has_create_permission(self, request: Request):
        # Add your permission logic here
        return True
```

### 5. Add Routes to Your FastAPI App

```python
from fastapi import FastAPI
from fastapi_admin_sdk import router

app = FastAPI()
app.include_router(router, prefix="/admin")
```

## Features

- **Resource Management**: Define resources with CRUD operations
- **Permission System**: Customizable permission checks for create, read, update, delete, and list operations
- **Filtering & Pagination**: Built-in support for filtering and pagination
- **SQLAlchemy Support**: First-class support for SQLAlchemy async models
- **Type Safety**: Built with Pydantic for data validation

## API Endpoints

Once you've registered your admin classes and included the router, the following endpoints will be available:

- `POST /admin/{resource_name}/create` - Create a new resource instance
- `GET /admin/{resource_name}/list` - List resource instances with filtering and pagination
- `GET /admin/{resource_name}/{lookup}/retrieve` - Retrieve a specific resource instance
- `PATCH /admin/{resource_name}/{lookup}/update` - Update an existing resource instance
- `DELETE /admin/{resource_name}/{lookup}/delete` - Delete a resource instance

## Development

### Running Tests

```bash
# Install dev dependencies
uv sync --all-groups --all-extras

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=fastapi_admin_sdk --cov-report=term
```

### Building the Package

```bash
python -m build
```

### Publishing to PyPI

The package is automatically published to PyPI when a git tag is pushed. Make sure to set up the `PYPI_API_TOKEN` secret in your GitHub repository.

## License

MIT License - see [LICENSE](LICENSE) file for details.
