Metadata-Version: 2.4
Name: flask-more-smorest
Version: 0.2.2
Summary: Enhanced Flask-Smorest blueprints with automatic CRUD operations
License-File: LICENSE
Keywords: flask,api,rest,crud,smorest,blueprint,sqlalchemy
Author: Dave
Author-email: david@qualisero.com
Maintainer: Dave
Maintainer-email: david@qualisero.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: alembic (>=1.13.0,<2.0.0)
Requires-Dist: bcrypt (>=4.1.0,<5.0.0)
Requires-Dist: flask (>=3.0.0,<4.0.0)
Requires-Dist: flask-jwt-extended (>=4.6.0,<5.0.0)
Requires-Dist: flask-smorest
Requires-Dist: flask-sqlalchemy (>=3.1.1,<4.0.0)
Requires-Dist: marshmallow (>=3.20.0,<4.0.0)
Requires-Dist: marshmallow-sqlalchemy (>=1.4.2,<2.0.0)
Requires-Dist: sqlalchemy (>=2.0.25,<3.0.0)
Requires-Dist: werkzeug (>=3.0.0,<4.0.0)
Project-URL: Documentation, https://github.com/qualisero/flask-more-smorest#readme
Project-URL: Homepage, https://github.com/qualisero/flask-more-smorest
Project-URL: Repository, https://github.com/qualisero/flask-more-smorest
Description-Content-Type: text/markdown

# Flask-More-Smorest

[![PyPI version](https://badge.fury.io/py/flask-more-smorest.svg)](https://badge.fury.io/py/flask-more-smorest)
[![Python Support](https://img.shields.io/pypi/pyversions/flask-more-smorest.svg)](https://pypi.org/project/flask-more-smorest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Flask-More-Smorest extends **Flask-Smorest** with batteries-included CRUD blueprints, SQLAlchemy helpers, and an opinionated user/permission system.

## Highlights

- Automatic CRUD endpoints with filtering and pagination
- Blueprint mixins for public/admin annotations and operation IDs
- SQLAlchemy base model with Marshmallow schemas and permission hooks
- Optional JWT-powered user, role, and token models

## Quick Start

```python
from flask import Flask
from flask_more_smorest import init_db
from flask_more_smorest.perms import Api, CRUDBlueprint

app = Flask(__name__)
app.config.update(
    API_TITLE="Example API",
    API_VERSION="v1",
    OPENAPI_VERSION="3.0.2",
    SQLALCHEMY_DATABASE_URI="sqlite:///example.db",
    SECRET_KEY="change-me",
    JWT_SECRET_KEY="change-me-too",
)

init_db(app)          # sets up SQLAlchemy
api = Api(app)        # registers JWT + permission hooks

users = CRUDBlueprint(
    "users",
    __name__,
    model="User",        # resolved from your models module
    schema="UserSchema",  # resolved from your schemas module
    url_prefix="/api/users/",
)

api.register_blueprint(users)
```

The blueprint above exposes the usual REST operations (`GET`, `POST`, `PATCH`, `DELETE`) plus automatic filtering (`/api/users/?created_at__from=...`).

### Controlling generated endpoints

Control which CRUD routes are created using the `methods` parameter:

```python
from flask_more_smorest.crud.crud_blueprint import CRUDMethod

# All methods enabled by default
users = CRUDBlueprint(
    "users",
    __name__,
    model="User",
    schema="UserSchema",
)

# Enable only specific methods (whitelist)
users = CRUDBlueprint(
    "users",
    __name__,
    model="User",
    schema="UserSchema",
    methods=[CRUDMethod.INDEX, CRUDMethod.GET],
)

# Customize or disable specific methods (all enabled by default with dict)
users = CRUDBlueprint(
    "users",
    __name__,
    model="User",
    schema="UserSchema",
    methods={
        CRUDMethod.POST: {"schema": "UserWriteSchema"},  # Custom schema
        CRUDMethod.DELETE: {"admin_only": True},         # Admin-only endpoint
        CRUDMethod.PATCH: False,                         # Disable this method
        # INDEX and GET not mentioned → enabled with defaults
    },
)
```

**When using a dict, all methods are enabled by default.** Specify a method to customize it, or set it to `False` to disable.

## Working with models

Use `BaseModel` to get UUID keys, timestamp fields, and auto-generated Marshmallow schemas:

```python
from flask_more_smorest import BaseModel
from flask_more_smorest.sqla import db
from sqlalchemy.orm import Mapped, mapped_column

class Article(BaseModel):
    __tablename__ = "article"

    title: Mapped[str] = mapped_column(db.String(200), nullable=False)
    body: Mapped[str] = mapped_column(db.Text, nullable=False)

    def _can_write(self) -> bool:  # optional permission hook
        return self.is_current_user_admin()
```

`Article.Schema()` instantly provides a Marshmallow schema (including an `is_writable` field) ready for use in blueprints.

## Built-in user system

Import the ready-made models when you need authentication, roles, or tokens:

```python
from flask_more_smorest.perms import DefaultUserRole, User, UserRole

user = User(email="admin@example.com")
user.set_password("secret")
user.save()

UserRole(user=user, role=DefaultUserRole.ADMIN).save()
```

Extending the default user is straightforward—inherit from `User` and add your fields or mixins:

```python
from flask_more_smorest.perms import ProfileMixin, TimestampMixin, User
from flask_more_smorest.sqla import db
from sqlalchemy.orm import Mapped, mapped_column

class Employee(User, ProfileMixin, TimestampMixin):
    __tablename__ = "employee"
    employee_id: Mapped[str] = mapped_column(db.String(32), unique=True)
```

## Learn more

- API reference and guides: [project documentation](https://github.com/qualisero/flask-more-smorest#readme)
- Examples and tests under the `tests/` directory demonstrate filters, permissions, and pagination end-to-end.

Contributions and feedback are welcome—see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

