# MASTER ROUTER GENERATOR
CreateRouterFromResources
# RESOURCE AND REGISTRY
Resource
ResourceRegistry
CruddyResourceRegistry
# CONTROLLER / CONTROLLER HELPERS
Actions
CruddyController
ControllerConfigurator
# REPOSITORY
AbstractRepository
# DATABASE ADAPTERS
BaseAdapter
SqliteAdapter
MysqlAdapter
PostgresqlAdapter
# CONSTANTS
BROADCAST_EVENT
CONTROL_EVENT
ROOM_EVENT
CLIENT_EVENT
KILL_SOCKET_BY_ID
KILL_SOCKET_BY_CLIENT
KILL_ROOM_BY_ID
JOIN_SOCKET_BY_ID
JOIN_SOCKET_BY_CLIENT
LEAVE_SOCKET_BY_ID
LEAVE_SOCKET_BY_CLIENT
CLIENT_MESSAGE_EVENT
DISCONNECT_EVENT
OPENAPI_WHERE_OVERRIDE
# TYPES / MODELS / SCHEMAS
T
UUID
RelationshipConfig
CruddyGenericModel
BulkDTO,
MetaObject
PageResponse
ResponseSchema
CruddyModel
CruddyCreatedUpdatedSignature
CruddyCreatedUpdatedMixin
CruddyIntIDModel
CruddyUUIDModel
CruddyStringIDModel
SocketMessage
SocketRoomConfiguration
ExampleUpdate
ExampleCreate
ExampleView
Example
# EXCEPTIONS
# CruddyNoMatchingRowException will be thrown if a database operation that should have succeeded didn't (typically due to row-level DB policies)
CruddyNoMatchingRowException
# WEBSOCKET MODULES
PubSub
WebsocketConnectionManager
RedisAdapter
# MODULE LOADER HELPERS
getModuleDir
getDirectoryModules
# HELPERS
pluralizer
uuid7
field_checkers
field_validators
field_errors
get_pk
possible_id_types
lifecycle_types
build_tz_aware_date
parse_datetime
coerce_to_utc_datetime
parse_and_coerce_to_utc_datetime
validate_utc_datetime
json_serial
to_json_string
to_json_object
get_state
set_state
# TEST HELPERS
BrowserTestClient
TestClient
WebSocketSession
# GRAPHQL EXPORTS
GraphQLController
GraphQLRequestCache
GraphQLResolverService
create_module_resolver
graphql_where_synthesizer
generate_gql_loader_and_type
GQL_WHERE_REPLACEMENT_CHARACTER
CruddyGQLDateTime
CruddyGQLObject
CruddyGQLArray
CruddyCreatedUpdatedGQLOverrides
CruddyGQLOverrides
# Security Exports
CruddyHTTPBearer

import my_app
from fastapi_cruddy_framework import CreateRouterFromResources
from fastapi import FastAPI, APIRouter


my_router: APIRouter = CreateRouterFromResources(
    # (REQUIRED) application_module is of "ModuleType" type, and should be a pointer to your main app module
    application_module=my_app,
    # (OPTIONAL) resource_path is of "str" type, and should specify a relative path from application_module
    # to the location of your "resources" that will be auto-loaded and bundled under this router
    # tree.
    resource_path="resources",
    # (OPTIONAL) common_resource_name is of "str" type, and should describe the common export value in each
    # resource file where the router factory can find your "Resource" instances. Use this if you want to name
    # all of your resource objects something other than "resource"
    common_resource_name="resource"
)

app = FastAPI(title="My App", version="1")

@app.on_event("startup")
async def bootstrap():
  app.include_router(my_router)

# fin!

id_type: Type[int] | Type[UUID] = int,
# You SHOULD pass in 'adapter'
adapter: BaseAdapter | SqliteAdapter | MysqlAdapter | PostgresqlAdapter | None = None,
# The following adapter specific options will probably get removed. You don't need to pass them in.
# They exist solely in the event you are defining disparate resources and want the resources to
# automatically build their own adapters. This is probably not a great idea.
adapter_type: Literal["mysql", "postgresql"] = "postgresql",
db_mode: Literal["memory", "file"] = "memory",
db_path: str | None = None,
connection_uri="",
pool_size=4,
max_overflow=64,
# link_prefix will be applied at the beginning of each relationship link on each record.
# This can help with things like sub-domains, or CORS with your API, and will allow you
# to point your relationships endpoints at a complete URL. You could pass in something like
# https://api.mydomain.com, which would make a relationship link look like
# https://api.mydomain.com/resource/{id}/relationship
link_prefix="",
# Path specifies where this resource resides within the API. This is generated for you by
# default. Only change if you know what you are doing. Ember.js would expect a resource path
# to be the pluralized name of its base model. So a 'user' resource should be accessible at
# '/users', and all of its sub-routes and actions are nested under that route.
path: str = None,
# The "tags" list corresponds with the fastapi "tags" list. You can alter this if needed.
# It is defined for you initially as the singular name of your resource model. User -> 'user'
tags: list[str] = None,
# The next four options are mandatory. 'create_model' specifies the inner schema that is
# allowed to be sent to the create endpoint by a user. It will be auto-wrapped in a REST
# envelope schema. 'update_model ' specifies the inner schema that is allowed to be sent
# to the update endpoint by a user. It too will be auto-wrappted in a REST envelope schema.
# 'resource_model' is your base model, which includes all possible fields of your model and
# has table=True specified. 'response_schema' defines the fields of your model to return
# to the client during all CRUD transactions. 'response_schema' will be wrapped in REST
# envelope in both single and many responses. Only 'resource_model' should have a table!!
# All of your models should descend from CruddyModel, which is a simple SQLModel class.
resource_create_model: CruddyModel = ExampleCreate,
resource_update_model: CruddyModel = ExampleUpdate,
resource_model: CruddyModel = Example,
response_schema: CruddyModel = ExampleView,
# 'response_meta_schema' allows you to remap the "meta" values returned to the client for
# any paginated routes. You shouldn't NEED to change this, but you can if you want.
response_meta_schema: CruddyGenericModel = MetaObject,
# 'protected_relationships' will ban-hammer relationship fields specified from gaining
# an auto-magic create or update property. This will prevent users from creating or updating
# these relationships via the default CRUD actions. You will need to build other business logic
# to manage creating or changing protected relationships elsewhere in your application.
# Protected relationships will still be viewable at their designated GET routes.
# 'protected_create_relationships' and 'protected_update_relationships' only prevent embedded
# relational changes at the CREATE and UPDATE routes, respectively.
protected_relationships: list[str] = [],
protected_create_relationships: list[str] = [],
protected_update_relationships: list[str] = [],
# 'artificial_relationship_paths' will add an arbitrary list of sub-paths to each CRUD object's
# relationship "links" attribute. For example, adding "artificial_relationship_paths": ["fake"]
# would cause each object's "links" attribute to contain a key-value pair of:
# "fake": "<link_prefix>/<model>/{id}/fake"
# within its links object. This can be used to create arbitrarily complicated controller GET
# actions (that can handle nested or complex relationships) and then have those actions
# successfully mapped into the RestAdapter compliant links specification for each object instance.
artificial_relationship_paths: list[str] = [],
# The following options allow you to pass in your Sails.js-like policy chains, which will
# run before all of your endpoints (in the case of universal), or in front of only specific
# endpoints that match the action specified. These policies can be used for nearly any purpose,
# from triggering other APIs and services, protecting endpoints to ensure only the correct
# users can alter data, or to intercept and even modify data before it gets to a default CRUD
# action! (Like hashing a user's password based on the plain-text password they send to register)
policies_universal: Sequence[Callable] = [],
policies_create: Sequence[Callable] = [],
policies_update: Sequence[Callable] = [],
policies_delete: Sequence[Callable] = [],
policies_get_one: Sequence[Callable] = [],
policies_get_many: Sequence[Callable] = [],
# The disable_<endpoint> options allow app developers to simply abort automatic generation of select
# CRUD endpoints on the resource's controller. For instance, to make a write-once collection a
# developercould set disable_update to True, which would cause the resource to abort building a route
# for PATCH resource/{id}. Be aware of the overall impact of endpoints you totally disable!
disable_create: bool = False,
disable_update: bool = False,
disable_delete: bool = False,
disable_get_one: bool = False,
disable_get_many: bool = False,
# The disable_relationship_getters list allow app developers to instruct the framework to NOT hoist
# an automatic GET route for a list of specific named relationships. Note, that any relationship name
# you disable will also cause the corresponding "link" entry that would point out that relationship
# to be removed from Swagger documentation, as well as from any returned link objects in real-world
# response payloads. This would effectively make a relationship invisble in GET routing.
disable_relationship_getters: list[str] = [],
# The disable_nested_objects flag prevents users from sending dictionaries inside of relationship arrays
# which the server will automatically unpack by default into an attempted create or update of the related
# resource. Any nested objects sent will still flow through the entire policy chain of the target resource!
# Any dictionary send with a primary key field will be handled as if it is an update. To create a new
# object via an embedded relationship, send the nested object without a primary key set!
disable_nested_objects: bool = False,
# Default limit will only set a limit on incoming queries if the user DOES NOT specify one. You should
# implement POLICIES to enforce a MAX limit, as you will ultimately have to re-use any max limit
# policies in your own custom controller functions for consistency. Max limit policies can be implemented
# by overriding any limit query parameter sent by the user with a maximum number if the user value is
# above whatever the max limit should be.
default_limit: int = 10,
# 'controller_extension' is the mount point for user-defined actions to-be-added to this resource's
# controller/router. Pass in your class definition and it will be instantiated at the appropriate
# time! See "CruddyController" example below!
controller_extension: CruddyController = None,
# 'custom_sql_identity_function' is an insertion point where you can pass in a lambda function or
# other SYNCHRONOUS callable that will return some sqlalchemy query segment that determines the identity
# of the resource in question. This is used for any CRUD actions that need to determine the identity
# of a single record. Your lambda function / callable will be passed the {id} param from the controller.
# You can use this to enable things like composite keys, and use {id} to capture <part a>.<part b>.
custom_sql_identity_function: Callable[..., Any] | None = None,
# 'custom_link_identity' is similar to custom_sql_identity_function, but is used specifically for building
# the {id} segment of a 'link' value in the response JSON. The custom_link_identity function you pass in
# will receive a record's value dictionary, which you can use to build a custom link {id} segment if needed.
# You can use this to enable things like composite keys, and format {id} as <record value a>.<record value b>.
custom_link_identity: Callable[..., str] | None = None,
# 'use_model_defaults' will wrap any record values sent to the `create` action with ANY added defaults from
# the base `model` for a resource. Setting this value to `false` would only propagate values contained in the
# actual POST body to the database level. If you use this feature, by setting this flag to `false`, you MUST
# have all required values generate their own defaults INSIDE the database.
use_model_defaults: bool = True,
# The following REPOSITORY lifecycle hooks can each recieve an async function which will be invoked
# before or after the target lifecycle event. Generally, whatever values are passed to the lifecycle
# hook are alterable WITHIN the hook so that userspace code can alter the behavior of the lifecycle
# based on app level concerns. This allows apps to do things like: hash a user password, force certain
# relationships to always exist, force "many" queries to obey sensible limits, commit log entries,
# send messages to queues for processing based on CRUD events, or generally handle unforseen
# circumstances.
lifecycle_before_create: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_create: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_update: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_update: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_delete: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_delete: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_get_one: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_get_one: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_get_all: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_get_all: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_set_relations: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_set_relations: Callable[..., Coroutine[Any, Any, Any]] | None = None,
# The following CONTROLLER lifecycle hooks can each recieve an async function which will be invoked
# before or after the target lifecycle event. Generally, whatever values are passed to the lifecycle
# hook are alterable WITHIN the hook so that userspace code can alter the behavior of the lifecycle
# based on app level concerns. CONTROLLER lifecycles hooks will also receive the REQUEST context,
# allowing the hook to take actions that consider the user and their priveleges, while still
# interleaving that logic within the cruddy action.
lifecycle_before_controller_create: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_controller_create: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_controller_update: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_controller_update: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_controller_delete: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_controller_delete: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_controller_get_one: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_controller_get_one: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_before_controller_get_all: Callable[..., Coroutine[Any, Any, Any]] | None = None,
lifecycle_after_controller_get_all: Callable[..., Coroutine[Any, Any, Any]] | None = None,

from fastapi_cruddy_framework import Resource, UUID
from my_app.adapters import sqlite
from my_app.models.user import (
    User,
    UserCreate,
    UserUpdate,
    UserView,
)
from my_app.schemas.response import MetaObject
from my_app.policies.verify_session import verify_session
from my_app.policies.hash_user_password import (
    hash_user_password,
)


resource = Resource(
    id_type=UUID,
    adapter=sqlite,
    resource_update_model=UserUpdate,
    resource_create_model=UserCreate,
    resource_model=User,
    response_schema=UserView,
    response_meta_schema=MetaObject,
    protected_relationships=["posts"],
    policies_universal=[verify_session],
    policies_create=[hash_user_password]
)

# fin!

# This is an example policy file that could live in your project at policies/load_user_into_session.py
from fastapi import Request
from fastapi_cruddy_framework import AbstractRepository, CruddyResourceRegistry, BulkDTO

async def load_user_into_session(request: Request):
    some_value = "that identifies a user"
    user_repository: AbstractRepository = CruddyResourceRegistry.get_repository_by_name(model_name="User")
    repo_dto: BulkDTO = await user_repository.get_all(limit=1, where={"some_field": some_value})
    if len(repo_dto.data) == 0:
        raise Exception("User not found!")
    request.session.update({"user": repo_dto.data.pop()})

async def create(request: Request, data: create_model)

async def update(request: Request, id: id_type = Path(..., alias="id"), *, data: update_model)

async def delete(
    request: Request, id: id_type = Path(..., alias="id")
)

async def get_by_id(
    request: Request,
    id: id_type = Path(..., alias="id"),
    where: Json = Query(None, alias="where"),
)

async def get_all(
    request: Request,
    page: int = 1,
    limit: int = 10,
    columns: list[str] = Query(None, alias="columns"),
    sort: list[str] = Query(None, alias="sort"),
    where: Json = Query(None, alias="where"),
)

from pydantic.types import Json
from fastapi_cruddy_framework import CruddyController
from fastapi import Query, Path, HTTPException, status
from fastapi_cruddy_framework import CruddyController, dependency_list
from examples.fastapi_cruddy_sqlite.policies.verify_session import verify_session


class UserController(CruddyController):
    def setup(self):
        # You can extend controller actions here!
        # You can also access:
        # self.actions
        # self.resource
        # self.repository
        # self.adapter
        # self.controller
        id_type = self.resource._id_type
        many_schema = self.resource.schemas["many"]

        # You can tap into the controller's CRUD actions map in the following ways:
        # 1. Override the action key
        old_delete = self.actions.delete

        async def new_delete(id: id_type = Path(..., alias="id"), confirm: str = "N"):
            if confirm == "Y":
                return await old_delete(id=id)
            else:
                raise HTTPException(
                    status_code=status.HTTP_400_BAD_REQUEST,
                    detail="You must confirm you want to delete this record by setting the 'confirm' parameter to 'Y'",
                )

        self.actions.delete = new_delete

        # 2. Provide a new route to an existing function (notice, no @ symbol!)
        self.controller.get(
            "/all",
            description="Another way to get many users",
            response_model=many_schema,
            response_model_exclude_none=True,
            dependencies=dependency_list(verify_session),
        )(self.actions.get_all)

        # 3. Re-use within your own function
        @self.controller.get(
            "/everything",
            description="Yet another way to get many users",
            response_model=many_schema,
            response_model_exclude_none=True,
            dependencies=dependency_list(verify_session),
        )
        async def get_all_again(
            page: int = 1,
            limit: int = 10,
            columns: list[str] = Query(None, alias="columns"),
            sort: list[str] = Query(None, alias="sort"),
            where: Json = Query(None, alias="where"),
        ):
            return await self.actions.get_all(
                page=page, limit=limit, columns=columns, sort=sort, where=where
            )

from fastapi import Depends
from fastapi_cruddy_framework import CruddyController, CruddyGenericModel
from my_app.policies.verify_session import verify_session

class HelloSchema(CruddyGenericModel):
    hello: str = "world"

class UserController(CruddyController):
    def setup(self):
        # You can extend controller actions here!
        # You can also access:
        # self.actions
        # self.resource
        # self.repository
        # self.adapter
        # self.controller
        @self.controller.get(
            "/hello", response_model=HelloSchema, dependencies=[Depends(verify_session)]
        )
        async def hello():
            return HelloSchema(hello="world")

from fastapi_cruddy_framework import Resource, UUID
from my_app.adapters import sqlite
from my_app.models.user import (
    User,
    UserCreate,
    UserUpdate,
    UserView,
)
from my_app.schemas.response import MetaObject
from my_app.controllers.user import UserController
from my_app.policies.verify_session import verify_session
from my_app.policies.hash_user_password import (
    hash_user_password,
)


resource = Resource(
    adapter=sqlite,
    response_schema=UserView,
    response_meta_schema=MetaObject,
    resource_update_model=UserUpdate,
    resource_create_model=UserCreate,
    resource_model=User,
    protected_relationships=["posts"],
    id_type=UUID,
    policies_universal=[verify_session],
    policies_create=[hash_user_password],
    controller_extension=UserController
)

# User functions accessible from any resource's 'AbstractRepository'
async def create(data: CruddyModel, request: Request = None)

async def get_by_id(id: UUID | int | str, request: Request = None)

async def update(id: UUID | int | str, data: CruddyModel, request: Request = None)

async def delete(id: UUID | int | str, request: Request = None)

async def get_all(page: int = 1, limit: int = 10, columns: list[str] = None, sort: list[str] = None, where: Json = None, request: Request = None)

async def get_all_relations(id: UUID | int | str = ..., relation: str = ..., relation_model: CruddyModel = ..., relation_view: CruddyModel = ..., page: int = 1, limit: int = 10, columns: list[str] = None, sort: list[str] = None, where: Json = None, request: Request = None)

async def set_many_many_relations(id: UUID | int | str, relation: str = ..., relations: list[UUID | int | str] = ..., request: Request = None)

async def set_one_many_relations(id: UUID | int | str, relation: str = ..., relations: list[UUID | int | str] = ..., request: Request = None)

from logging import getLogger
from asyncio import get_event_loop_policy, sleep
from pytest import fixture, mark
from fastapi import FastAPI
from fastapi_cruddy_framework import TestClient, BrowserTestClient

logger = getLogger(__name__)

FAKE_AUTH_TOKEN = "somefaketokenvalue"
FAKE_AUTH_QP = f"?auth_token={FAKE_AUTH_TOKEN}"
FAKE_AUTH_HEADERS = {"Authorization": f"Bearer {FAKE_AUTH_TOKEN}"}


@fixture(scope="session", autouse=True)
def event_loop():
    loop = get_event_loop_policy().new_event_loop()
    yield loop
    loop.close()


@fixture(scope="session", autouse=True)
async def app():
    # Don't move this import!
    from your_app.main import app

    yield app


@fixture(scope="session", autouse=True)
async def client(app: FastAPI):
    # By using "with" the FastAPI app launch hook is run, connecting the application router
    async with TestClient(app, use_cookies=False) as client:
        while (await client.get("/health")).json() != True:
            await sleep(0.5)
        yield client


@fixture(scope="session", autouse=True)
async def unauthenticated_client(client: TestClient):
    blank_client = BrowserTestClient(client=client, cookies=None, headers=None)
    yield blank_client


@fixture(scope="session", autouse=True)
async def authenticated_client(client: TestClient):
    sessioned_client = BrowserTestClient(
        client=client, cookies=None, headers=FAKE_AUTH_HEADERS
    )
    await sessioned_client.get(f"/users/authorization{FAKE_AUTH_QP}")
    yield sessioned_client


@fixture(scope="function")
async def authenticated_websocket(authenticated_client: BrowserTestClient):
    async with authenticated_client.websocket_connect("/ws") as websocket:
        # For example: data = await websocket.receive_json()
        # Or await websocket.send_json(data)
        # If your server sends any kind of "welcome" messages, make
        # sure you purge them here BEFORE yielding the socket back
        # to whatever function needs to run tests
        yield websocket

where = {"column_name:tsvector:english": {"*websearch_to_tsquery": "foo or bar -baz"}}

# models/example.py
from typing import Any
from sqlmodel import Field, cast, func, Text
from sqlalchemy import Column, Index, literal_column
from sqlalchemy.dialects.postgresql import JSONB, UUID as psqlUUID
from fastapi_cruddy_framework import  CruddyModel, CruddyCreatedUpdatedMixin, UUID, uuid7


class ExampleUpdate(CruddyModel):
    data: Any = Field(
        schema_extra={
            "json_schema_extra": {
                "example": {
                    "some": {
                        "key": "value"
                    }
                }
            }
        }
    )


class ExampleCreate(ExampleUpdate):
    pass


class Example(CruddyCreatedUpdatedMixin(), ExampleCreate, table=True):  # type: ignore
    id: UUID =  Field(
        sa_column=Column(
            psqlUUID(as_uuid=True),
            primary_key=True,
            index=True,
            nullable=False,
            default=uuid7,
        )
    )
    data: Any = Field(
        default=None,
        sa_column=Column(JSONB, nullable=True, default=None),
    )
    __table_args__ = (
        Index("ix_Example_data_gin", "data", postgresql_using="gin"),
        Index('ix_Example_data_tsvector', func.to_tsvector(literal_column("'english'"), cast(data.sa_column, Text)), postgresql_using="gin"),
    )

where = {"a_json_column_name:Text": {"*icontains": "some substring"}}

array
tsvector
BigInteger
Boolean
Date
DateTime
Double
Enum
Float
Integer
Interval
LargeBinary
MatchType
Numeric
SmallInteger
String
Text
Time
Unicode
UnicodeText
Uuid
ARRAY
BIGINT
BINARY
BLOB
BOOLEAN
CHAR
CLOB
DATE
DATETIME
DECIMAL
DOUBLE
DOUBLE_PRECISION
FLOAT
INT
INTEGER
JSON
NCHAR
NUMERIC
NVARCHAR
REAL
SMALLINT
TEXT
TIME
TIMESTAMP
UUID
VARBINARY
VARCHAR

where = {"datetime_column": {"*gt": {"*datetime": "2024-02-14T19:17:40.860657Z"}}}

where = {"datetime_column": {"*gt": {"*datetime_naive": "2024-02-14T19:17:40.860657Z"}}}