flask_more_smorest.protocols

Protocol definitions for Flask-More-Smorest.

These protocols define the interfaces that components expect, allowing for loose coupling between modules and better type safety.

Protocols provide structural typing (duck typing with type checking), enabling components to work with any object that has the required attributes and methods, without requiring inheritance.

Example

>>> from flask_more_smorest.protocols import Identifiable, PermissionAware
>>>
>>> def process_item(item: Identifiable & PermissionAware) -> None:
...     if item.can_read():
...         print(f"Processing item {item.id}")

Classes

CRUDModel(*args, **kwargs)	Full CRUD model interface.
Identifiable(*args, **kwargs)	Object with an ID attribute.
PermissionAware(*args, **kwargs)	Object with permission checking methods.
Saveable(*args, **kwargs)	Object that can be persisted to a database.
Timestamped(*args, **kwargs)	Object with automatic timestamp tracking.
Updatable(*args, **kwargs)	Object that can be updated with new field values.
UserLike(*args, **kwargs)	User-like object for permission checking.

class flask_more_smorest.protocols.Identifiable(*args, **kwargs)

Object with an ID attribute.

Any object that has an id attribute can satisfy this protocol, making it useful for generic functions that work with identified resources.

Example

>>> def get_resource_id(resource: Identifiable) -> UUID | Any:
...     return resource.id

property id: UUID | Any

Return the object’s identifier.

__init__(*args, **kwargs)

class flask_more_smorest.protocols.PermissionAware(*args, **kwargs)

Object with permission checking methods.

Defines the interface for objects that support permission-based access control. Any object implementing these methods can be used in permission-aware contexts.

Example

>>> def safe_update(obj: PermissionAware, **kwargs: Any) -> None:
...     if obj.can_write():
...         obj.update(**kwargs)

can_read()

Check if current user can read this object.

Return type:

bool

can_write()

Check if current user can write this object.

Return type:

bool

can_create()

Check if current user can create this object.

Return type:

bool

__init__(*args, **kwargs)

class flask_more_smorest.protocols.Saveable(*args, **kwargs)

Object that can be persisted to a database.

Defines the interface for objects with CRUD operations.

Example

>>> def persist(obj: Saveable) -> None:
...     obj.save(commit=True)

save(commit=True)

Save the object to the database.

Parameters:

commit (bool) – Whether to commit the transaction immediately

Return type:

Self

Returns:

The saved object (for method chaining)

delete(commit=True)

Delete the object from the database.

Parameters:

commit (bool) – Whether to commit the transaction immediately

Return type:

None

__init__(*args, **kwargs)

class flask_more_smorest.protocols.Updatable(*args, **kwargs)

Object that can be updated with new field values.

Example

>>> def apply_changes(obj: Updatable, changes: dict[str, Any]) -> None:
...     obj.update(**changes)

update(commit=True, **kwargs)

Update the object with new field values.

Parameters:

• commit (bool) – Whether to commit the transaction immediately

• **kwargs (Any) – Field values to update

Return type:

None

__init__(*args, **kwargs)

class flask_more_smorest.protocols.CRUDModel(*args, **kwargs)

Full CRUD model interface.

Combines all the basic protocols to define a complete model interface with identification, permissions, and persistence operations.

This is the most complete protocol and represents what most model classes in Flask-More-Smorest should implement.

Example

>>> def process_model(model: CRUDModel) -> None:
...     if model.can_write():
...         model.update(status='processed')
...         model.save()

classmethod get_by(**kwargs)

Get instance by field values.

Parameters:

**kwargs (Any) – Field name/value pairs to filter by

Return type:

Optional[Self]

Returns:

Instance if found, None otherwise

classmethod get_by_or_404(**kwargs)

Get instance by field values or raise 404.

Parameters:

**kwargs (Any) – Field name/value pairs to filter by

Return type:

Self

Returns:

Instance if found

Raises:

NotFoundError – If no instance is found

class flask_more_smorest.protocols.UserLike(*args, **kwargs)

User-like object for permission checking.

This protocol defines the minimal interface that permission checking code expects from user objects. Any user class (built-in or custom) that implements these methods can be used with the permissions system.

Example

>>> def check_access(user: UserLike, resource: str) -> bool:
...     return user.has_role('admin') or user.has_role('superadmin')

property id: UUID | Any

User identifier.

property is_admin: bool

Whether user has admin privileges.

has_role(role)

Check if user has a specific role.

Parameters:

role (str) – Role name to check

Return type:

bool

Returns:

True if user has the role, False otherwise

list_roles()

List all roles the user has.

Return type:

list[str]

Returns:

List of role names as strings

__init__(*args, **kwargs)

class flask_more_smorest.protocols.Timestamped(*args, **kwargs)

Object with automatic timestamp tracking.

Example

>>> def get_creation_time(obj: Timestamped) -> Any:
...     return obj.created_at

property created_at: Any

Timestamp of creation.

property updated_at: Any

Timestamp of last update.

__init__(*args, **kwargs)