Package: fastapi-cruddy-framework
FastAPI - Cruddy FrameworkAbout Cruddy Frameworkfastapi-cruddy-frameworkis a companion library toFastAPIdesigned to bring the development productivity ofRuby on Rails,Ember.jsorSails.jsto theFastAPIecosystem. Many of the design patterns base themselves onSails.js"policies,"Sails.jsmodel lifecycle events,sails-ember-restautomatic CRUD routing, andEmber.jsREST-Adapterfeature sets. By default, data sent to and from the auto-magic CRUD routes are expected to conform to theEmber.jsRest Envelope and Linked-data relationship specification. This specification is highly readable for front-end developers, allows for an expressive over-the-wire query syntax, and embeds self-describing relationship URL links in each over-the-wire record to help data stores automatically generate requests to fetch or update related records. This library is still in an alpha/beta phase, so use at your own risk. All CRUD actions and relationship types are currently supported, though there may be unexpected bugs. Please report any bugs under "issues."TODO: Additional documentation and tests. (General features covered by tests) Maybe more comments. Maybe more features.See the examples folder for a quick reference of high level setup. It currently contains a fully functional fastapi server which uses fastapi-cruddy-framework and the sqlite adapter. It even shows how to override incoming post data to do things like hash a user's password during initial registration using a simple drop-in policy function.Come for the websocket manager, stay for the CRUD!(back to top)Front-end LibrariesIf you are a front-end developer, you may be interested in using the following modules to help with making a UI that may communicate with a back-end server built withfastapi-cruddy-framework.cruddy-typesnpm,Github(back to top)FastAPI, SQLModel, Pydantic and SQL Alchemy Compatibility:fastapi-cruddy-frameworkwas originally developed against FastAPI <= 0.99.1, sqlmodel <= 0.0.12, pydantic < 2.0.0, and sqlalchemy < 2.0.0. However, beginning withfastapi-cruddy-frameworkversion 1.x.x+, all major dependencies have been shifted forward to target FastAPI 0.100.0+, sqlmodel 0.0.14+, pydantic 2.0.0+, and sqlalchemy 2.0.0+. Therefore, when using this library, please note the following library compatibility chart:fastapi-cruddy-framework@0.x.x:FastAPI <= 0.99.1SQLModel <= 0.0.12pydantic < 2.0.0sqlalchemy < 2.0.0fastapi-cruddy-framework@1.x.x:FastAPI >= 0.100.0SQLModel >= 0.0.14pydantic >= 2.0.0sqlalchemy >= 2.0.0Moving betweenfastapi-cruddy-frameworkversions? See themigration guides.(back to top)InstallationThe fastapi-cruddy-framework module can be installed using poetry...poetry add fastapi-cruddy-frameworkOr pip.pip install fastapi-cruddy-frameworkAfter that, you can import and use all of the classes outlined below.(back to top)Cruddy Exports/ImportsCruddy-framework provides users the following classes and helper functions to scaffold out a project. (For recommended project structure, see the "examples" folder in the Github repo)# MASTER ROUTER GENERATORCreateRouterFromResources# RESOURCE AND REGISTRYResourceResourceRegistryCruddyResourceRegistry# CONTROLLER / CONTROLLER HELPERSActionsCruddyControllerControllerConfigurator# REPOSITORYAbstractRepository# DATABASE ADAPTERSBaseAdapterSqliteAdapterMysqlAdapterPostgresqlAdapter# CONSTANTSBROADCAST_EVENTCONTROL_EVENTROOM_EVENTCLIENT_EVENTKILL_SOCKET_BY_IDKILL_SOCKET_BY_CLIENTKILL_ROOM_BY_IDJOIN_SOCKET_BY_IDJOIN_SOCKET_BY_CLIENTLEAVE_SOCKET_BY_IDLEAVE_SOCKET_BY_CLIENTCLIENT_MESSAGE_EVENTDISCONNECT_EVENT# TYPES / MODELS / SCHEMASTUUIDRelationshipConfigCruddyGenericModelBulkDTO,MetaObjectPageResponseResponseSchemaCruddyModelCruddyCreatedUpdatedSignatureCruddyCreatedUpdatedMixinCruddyIntIDModelCruddyUUIDModelSocketMessageSocketRoomConfigurationExampleUpdateExampleCreateExampleViewExample# WEBSOCKET MODULESPubSubWebsocketConnectionManagerRedisAdapter# MODULE LOADER HELPERSgetModuleDirgetDirectoryModules# HELPERSpluralizeruuid7field_checkersfield_validatorsfield_errorsget_pkpossible_id_typeslifecycle_typesbuild_tz_aware_dateparse_datetimecoerce_to_utc_datetimeparse_and_coerce_to_utc_datetimevalidate_utc_datetimejson_serialto_json_stringto_json_objectget_stateset_state# TEST HELPERSBrowserTestClientTestClientWebSocketSession(back to top)CreateRouterFromResourcesThis instance factory creates and returns a fully-wired fastapiAPIRouterwhich sub-routes allResourceinstances created in your project. Theoretically, you can create and mount multiple routers this way, but each router needs to be provided all of theResourceinstances required to fully resolve the relationships it may care about. The recommended way to structure your project is to keep all resources required for a route set contained within a single folder. This factory is then provided the relative path to a resource set folder, starting with your application'smainmodule, and will return the fully interconnected route set while also instantiating all of your resource modules. Typically, it is a good idea to import all of your router instances in your main module, as they will need to be "connected" to your fastapi serverWITHINthestartuphook. This is critical, as the resource registry (discussed below) cannot fully resolve relationships until after SQLAlchemy is aware of all models. This occurs in-between launching your main module and thestartuphook.Example:importmy_appfromfastapi_cruddy_frameworkimportCreateRouterFromResourcesfromfastapiimportFastAPI,APIRoutermy_router:APIRouter=CreateRouterFromResources(# (REQUIRED) application_module is of "ModuleType" type, and should be a pointer to your main app moduleapplication_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")asyncdefbootstrap():app.include_router(my_router)# fin!(back to top)ResourceTheResourceclass is the fundamental building block of fastapi-cruddy-framework. Your resource instances define the union of your models, resource "controller" (which is a fastapi router with baked-in CRUD logic), business policies, repository abstraction layer, any resource lifecycle hook, and database adapter. Fortunately for you, the user, everything is essentially ready-to-go out of the box. Likesails-ember-restorRuby on Rails, you can now focus all of your development time on creating reusable policies (which contain your business logic that lies just above your CRUD endpoints), defining your models, and extending your resource controllers to add one-off actions like "login" or "change password". Lifecycle actions allow you to alter query configurations or record data before or after it is persisted to a database, or perform some other task before replying to the user. All of your resources should be loaded by the router factory (above) to ensure that relationships and routes are resolved in the correct order. Don't forget,only plug the master router into your application in the fastapistartuphook!Resource Nuances:Defining your policies is done at definition time!Lifecycle actions occur immediately before and after any database interaction your CRUD controllers makeLifecycle actions passed into the Resource constructor to interact with your queries or dataMUSTbeasyncfunctions.Policies are run in the exact order in which they are included in thelistsent to the resource definition.policies_universalapply to ALL CRUD routes, and always runBEFOREaction specific policy chains.Action specific policies runAFTERallpolicies_universalhave resolved successfully.Each endpoint is protected bypolicies_universal+policies_<action>.One-to-Many and Many-to-Many sub-routes (like /users/{id}/posts) will be protected by the policy chain:user.policies_universal+user.policies_get_one+posts.policies_get_many. Security, security, security!Blocking user REST modification of certain relationships via the default CRUD controller is also done at definition time!protected_relationshipsis alist[str]with each string indicating a one-to-many or many-to-many relationship that should not be allowed to update via the default CRUD actions.You should define your application-wide adapter elsewhere and pass it into the resource instance.Resources cannot span different databases.Available Policy Chain Definitions:policies_universalpolicies_createpolicies_updatepolicies_deletepolicies_get_onepolicies_get_manyAvailable ASYNC Lifecycle Hooks:lifecycle_before_createlifecycle_after_createlifecycle_before_updatelifecycle_after_updatelifecycle_before_deletelifecycle_after_deletelifecycle_before_get_onelifecycle_after_get_onelifecycle_before_get_alllifecycle_after_get_alllifecycle_before_set_relationslifecycle_after_set_relationsAvailable Relationship Blocks:protected_relationshipsUpdating Relationships:You can update relationships via either CREATE or UPDATE actions against each base resource!As you will discover, your resource's create and update models will automatically gain "shadow" properties where one-to-many and many-to-many relationships exist. These properties expect a client to send a list of IDs that specify the foreign records that relate to the target record. So - if a user is a member of many groups, and a group can have many users, you could update the users in a group by sending a property"users": [1,2,3,4,5]within thegrouppayload object you send to thePOST /groupsorPATCH /groupsroutes/actions. It will all be clear when you look at the SWAGGER docs generated for your API.Lifecycle hooksThe following lifecycle hook methods, which can be defined in user-space code, receive the following information from fastapi-cruddy-framework:lifecycle_before_create- Record without an ID. Values altered on this record in the lifecycle hook will be persisted to the DB.lifecycle_after_create- Record with an ID, as returned from the database.lifecycle_before_update- A key-values dictionary to be applied to the database, and the primary key id of the record which will be updated. Values altered in the dictionary will be applied to the DB update.lifecycle_after_update- Record with an ID, as returned from the databaselifecycle_before_delete- Record with an ID, as returned from the database.lifecycle_after_delete- Record with an ID, as returned from the database. This record no longer exists in the database.lifecycle_before_get_one- A primary key value that will be used to fetch the record from the database, and a secondary where filter if one was used.lifecycle_after_get_one- Record with an ID, as returned from the database.lifecycle_before_get_all- Recieves a query configuration object. Any user-space modifications to this object will impact the query made by fastapi-cruddy-framework. This method is also invoked when a foreign Resource queries a relationship that affects the Resource where you plug in this hook.lifecycle_after_get_all- Receives a BulkDTO object, containing the database objects retrieved by a get_all query, as well as the query metadata. This method is also invoked when a foreign Resource queries a relationship that affects the Resource where you plug in this hook.lifecycle_before_set_relations- Receives a relationship configuration object which containts information about the record id affected, the relationship being altered, and the new list of relations for this relationship type.{
    "id": id, # The database id whos relationship are about to be altered (of your defined PK type)
    "relation": relation, # The relationship that is about to change (string)
    "relations": relations # An array of foreign ids that will now define this relationship (Framework will attempt to discard old relations)
}lifecycle_after_set_relations- Receives a completed mapping of the affected relational change, which can be used to echo changes to other databases or services.{
    "model": model, # The CruddyModel affected by this relationship change
    "relation_conf": relation_conf, # The configuration object from lifecycle_before_set_relations
    "relation_type": MANYTOMANY, # An SQL Alchemy relationship-type identifier (MANYTOMANY or ONETOMANY)
    "related_table": foreign_table, # The table that ultimately represents the far-side of this relationship (not the join table!)
    "related_field": field_name, # The field on the related_table that represents the far side of the relationship
    "updated_db_count": result # The number of records now in the database associated with this relationship. If the number is different than the length of relation_conf.relations, you probably have a non-nullable field on the far-side of this relationship.
}Resource Definition Options (And Defaults!):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}/relationshiplink_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 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_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:list[Callable]=[],policies_create:list[Callable]=[],policies_update:list[Callable]=[],policies_delete:list[Callable]=[],policies_get_one:list[Callable]=[],policies_get_many:list[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,# 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,# The following 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,Below is an example for creating auserresource. The best way to organize your app would be to place the definition for your user resource in a folder likemy_app/resources/user.py, where the name of your application ismy_app. As you saw earlier in the description forCreateRouterFromResourcesyou would then load this user resource file by simply specifyingapplication_module=my_appandresource_path="resources". Yourfastapi-cruddy-frameworkproject would then auto-magically load your resource file(s), create dynamic routes to create, read, update, and delete this resource, and further create sub-routes within this resource to browse, query and update all of the relationships for your resource.Example:fromfastapi_cruddy_frameworkimportResource,UUIDfrommy_app.adaptersimportsqlitefrommy_app.models.userimport(User,UserCreate,UserUpdate,UserView,)frommy_app.schemas.responseimportMetaObjectfrommy_app.policies.verify_sessionimportverify_sessionfrommy_app.policies.hash_user_passwordimport(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!Easy, right?(back to top)ResourceRegistryTheResourceRegistryclass should be invisible to the average user. There are no input parameters when creating a registry, and by default Cruddy defines its own library-internal registry. The registry exists to perform the following functions:Maintain a map of all resources available tofastapi-cruddy-frameworkTriggerresolvefor all resources after SQL Alchemy finishes computing the relationship properties on each SQLModel.Plugin to theResourceclass, so that eachResourceyou define can automatically callResourceRegistry.register()when you define it. This is all "under the hood".(back to top)CruddyResourceRegistryTheCruddyResourceRegistryis a framework-created instance of theResourceRegistryclass, exposed as an export so that application builders can acquire framework component instance references dynamically. It manages all of the resources and other subordinate components the active Cruddy framework is aware of. This framework internal registry instance is extremely helpful for looking up resource, controller, and model classes and instanceswithoutcausing a litany of circular import issues in app code. Due to the asynchronous nature of how cruddy framework must initialize, application developers should use theCruddyResourceRegistryto "lookup" objects in any app code that needs to use a fully functional framework instance. What's a good example of where this is useful? Acquiring a resource's repository instance from within a policy so you can run database checksbeforea CRUD action occurs. There are many other applicable scenarios. See example, below.# This is an example policy file that could live in your project at policies/load_user_into_session.pyfromfastapiimportRequestfromfastapi_cruddy_frameworkimportAbstractRepository,CruddyResourceRegistry,BulkDTOasyncdefload_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=awaituser_repository.get_all(limit=1,where={"some_field":some_value})iflen(repo_dto.data)==0:raiseException("User not found!")request.session.update({"user":repo_dto.data.pop()})The available registry lookup function signatures are:get_model_by_name(model_name: str) -> CruddyModel | None]get_relationships_by_name(model_name: str) -> dict | Noneget_resource_by_name(model_name: str) -> Resource | Noneget_repository_by_name(model_name: str) -> AbstractRepository | Noneget_controller_by_name(model_name: str) -> APIRouter | Noneget_controller_extension_by_name(model_name: str) -> CruddyController | NoneMake sure that themodel_namestring you pass to the registry EXACTLY mirrors the class name for your base tableCruddyModel. So for a model with a class ofUseryou would pass inmodel_name="User". Pay attention to the capitalization!(back to top)ActionsTheActionsclass contains all the business logic for thebaseCRUD actions that are wired into a controller's route tree based on the framework options used. Each resource / controller will generate its own unique CRUD actions instance, and make this object available to user-spaceCruddyControllerinstance, which are described in more detail below. Actions that are deferred from routing automatically (using option flags such asdisable_create) are still generated for reach resource's actions map, which makes those functions available in theCruddyControllersetup function.Available actions:asyncdefcreate(data:create_model)asyncdefupdate(id:id_type=Path(...,alias="id"),*,data:update_model)asyncdefdelete(id:id_type=Path(...,alias="id"),)asyncdefget_by_id(id:id_type=Path(...,alias="id"),where:Json=Query(None,alias="where"),)asyncdefget_all(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"),)You can re-use CRUD actions in your controllers as follows:frompydantic.typesimportJsonfromfastapi_cruddy_frameworkimportCruddyControllerfromfastapiimportQuery,Path,HTTPException,statusfromfastapi_cruddy_frameworkimportCruddyControllerfromexamples.fastapi_cruddy_sqlite.policies.verify_sessionimportverify_sessionfromexamples.fastapi_cruddy_sqlite.utils.dependency_listimportdependency_listclassUserController(CruddyController):defsetup(self):# You can extend controller actions here!# You can also access:# self.actions# self.resource# self.repository# self.adapter# self.controllerid_type=self.resource._id_typemany_schema=self.resource.schemas["many"]# You can tap into the controller's CRUD actions map in the following ways:# 1. Override the action keyold_delete=self.actions.deleteasyncdefnew_delete(id:id_type=Path(...,alias="id"),confirm:str="N"):ifconfirm=="Y":returnawaitold_delete(id=id)else:raiseHTTPException(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),)asyncdefget_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"),):returnawaitself.actions.get_all(page=page,limit=limit,columns=columns,sort=sort,where=where)(back to top)CruddyControllerTheCruddyControlleris a base class with a single methodsetupthat applications can leverage to "extend" the default CRUD route controllers as needed. This class is needed to control application flow during the resolution boot cycle, and to allow you to share methods between resources like a mixin. Controllers should generally be placed within a project folder named "controllers". Controller classes can be imported in your resource file, and passed to the resource at definition time. Don't worry, theResourceclass will create a controller instance for you!Examplemy_app/controllers/User.py:fromfastapiimportDependsfromfastapi_cruddy_frameworkimportCruddyController,CruddyGenericModelfrommy_app.policies.verify_sessionimportverify_sessionclassHelloSchema(CruddyGenericModel):hello:str="world"classUserController(CruddyController):defsetup(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)])asyncdefhello():returnHelloSchema(hello="world")Example Continuedmy_app/resources/User.py:fromfastapi_cruddy_frameworkimportResource,UUIDfrommy_app.adaptersimportsqlitefrommy_app.models.userimport(User,UserCreate,UserUpdate,UserView,)frommy_app.schemas.responseimportMetaObjectfrommy_app.controllers.userimportUserControllerfrommy_app.policies.verify_sessionimportverify_sessionfrommy_app.policies.hash_user_passwordimport(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)Notice that you don't need to instantiate your controller!CruddyControllerextension classes passed to theResourcedefinition will besetup()BEFOREthe auto-generated CRUD routes butAFTERSQL Alchemy has resolved model relationships. This ensures that your user-defined routes receive priority for incoming HTTP requests. If extension classes were not loaded first, then the CRUD handlers would almost always intercept the incoming request first.(back to top)ControllerConfiguratorTheControllerConfiguratoris a configuration function invoked by theResourceclass after SQL Alchemy has resolved all model relationships. You shouldn't need to interact with this function, but if you're a super advanced user, or wunderkind, maybe you will find a reason to need this. In essence, this function builds out all of the basic CRUD logic for a resource, after the resource has constructed a repository and generated the shadow schemas for your models. This is where your CRUD routes and sub-routes are auto-magically configured.The controller/router configured by each of yourResourceobjects will allow the base resource or its relationships to be queried from the client via an arbitrarily complexwhereobject (JSON encoded query parameter).Invalid attributes or ops are just dropped. (May change in the future)Improvements that will be made in the near future:Conditional table joins for relationships to...Make resources searchable with joined relationships via dot notation in thewhereobject!Maybe throw an error if a bad search field is sent? (Will help UI devs)Clients can build an arbitrarily deep query with a JSON dictionary, sent via a query parameter in a JSON object that generally contains all possible filter operators along with "and," "or," and "not" conditions.Field level and boolean operators begin with a * character. This will nearly always translate down to the sqlalchemy level, where it is up to the model class to determine what operations are possible on each model attribute. The top level query of awhereobject is an implicit AND. To do an OR, the base key of the search must be*or, as in the below examples:/resource?where={"*or":{"first_name":"bilbo","last_name":"baggins"}}/resource/{id}/relationship?where={"*or":{"first_name":{"*contains":"bilbo"},"last_name":"baggins"}}/resource?where={"*or":{"first_name":{"*endswith":"bilbo"},"last_name":"baggins","*and":{"email":{"*contains":"@"},"first_name":{"*contains":"helga"}}}}/resource?where={"*or":{"first_name":{"*endswith":"bilbo"},"last_name":"baggins","*and":[{"email":{"*contains":"@"}},{"email":{"*contains":"helga"}}]}}The following query would be an implicit *and:/resource?where=[{"first_name":{"*endswith":"bilbo"}},{"last_name":"baggins"}]As would the following query:/resource/{id}/relationship?where={"first_name":{"*endswith":"bilbo"},"last_name":"baggins"}"Dot" notation is currently supported for JSON or JSON-like columns. The following queries showcase this:/resource?where={"user.config.favoriteColor":{"*eq":"black"}}/resource?where={"favorites.":{"*contained_by":{"tags":["foo","bar","baz]}}}/resource?where={"favorites.tags":{"*contains":["foo"]}}(back to top)AbstractRepositoryTheAbstractRepositoryis a helpful way to interact with the data layer of your models. It contains all of the underlying functions that theResourceandControllerobjects use to query, create, update, and delete your database information. EachResourceyou define will automatically create anAbstractRepositoryinstance that manages it. This can be accessed in your application atyour_resource_instance.repository. The methods available to you via this repository instance are:# User functions accessible from any resource's 'AbstractRepository'asyncdefcreate(data:CruddyModel)asyncdefget_by_id(id:UUID|int|str)asyncdefupdate(id:UUID|int|str,data:CruddyModel)asyncdefdelete(id:UUID|int|str)asyncdefget_all(page:int=1,limit:int=10,columns:list[str]=None,sort:list[str]=None,where:Json=None)asyncdefget_all_relations(id:UUID|int|str=...,relation:str=...,relation_model:CruddyModel=...,page:int=1,limit:int=10,columns:list[str]=None,sort:list[str]=None,where:Json=None)asyncdefset_many_many_relations(id:UUID|int|str,relation:str=...,relations:list[UUID|int|str]=...)asyncdefset_one_many_relations(id:UUID|int|str,relation:str=...,relations:list[UUID|int|str]=...)Generally, these functions do about what you would expect them to do. More documentation will be added to describe their function soon. Please read nuances below, however, as it applies to how x-to-Many relationships are managed via the automatic CRUD routes.Important AbstractRepository Nuancesset_many_many_relationsandset_one_many_relationsboth destroy and then re-create the x-to-Many relationships they target. If auserwith the id of 1 was a member ofgroups1, 2, and 3, then callingawait user_repository.set_many_many_relations(1, 'groups', [4,5,6])would result inuser1 being a member of only groups 4,5, and 6 after execution. Client applications should be aware of this functionality, and always send ALL relationships that should still exist during any relational updates.(back to top)Validators / Checkersfastapi-cruddy-frameworkincludes validators and checkers useful to enrich your model definitions by exportingfield_checkers,field_validators, andfield_errorsobjects. These objects are all simple re-exports of the corevalidators,checkersanderrorsfromvalidator-collection. For additional documentation on what is available, see that project's README.(back to top)WebsocketConnectionManagerfastapi-cruddy-frameworkincludes a relatively full-featuredWebsocketConnectionManagerthat offers many of the same features as other great websocket libraries, such assocket.io. The easiest way to see the full capabilities of the websocket manager is to look at the example server used to test this library! For instance,hereandhereyou can see how to instantiate aWebsocketConnectionManager. You can then bind an instance of aWebsocketConnectionManagerto yourApplicationRoute, as seenhere, using the async context manager's.connect()function to initiate a bidirectional websocket context that supports broadcasts, rooms, direct socket-to-socket messages, kill commands, a custom socket identity hook (to identify or kill many sockets owned by the same user), and a horizontally scaling control plane where you can even plugin your own custom commands! Note that you need to.startup()and.dispose()of aWebsocketConnectionManagerin your application'slifespanhook, as seenhere.TheWebsocketConnectionManagerwill receive more thorough documentation in the future when it becomes more stable, but it is fully tested in it's current state and is very reliable!Note that currently theWebsocketConnectionManagerrequiresredisto function. In the future, other broker types may be added as well! The pub/sub aspect is delegated to a separate class under the hood.(back to top)BrowserTestClientTheBrowserTestClientis a useful helper class to enable test suites to "boot" a Cruddy based app, and then use different virtual "browsers" to execute API tests against the app at the same time, against the same app instance. For usage examples, seetests/conftest.pyandtests/crud/*.py.BrowserTestClientis designed to use the async ASGI server runnerTestClient, which is re-exported fromasync-asgi-testclient. Assuming your app has some level of authentication present you could setup your own conftest.py to look like:fromloggingimportgetLoggerfromasyncioimportget_event_loop_policy,sleepfrompytestimportfixture,markfromfastapiimportFastAPIfromfastapi_cruddy_frameworkimportTestClient,BrowserTestClientlogger=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)defevent_loop():loop=get_event_loop_policy().new_event_loop()yieldlooploop.close()@fixture(scope="session",autouse=True)@mark.asyncioasyncdefapp():# Don't move this import!fromyour_app.mainimportappyieldapp@fixture(scope="session",autouse=True)@mark.asyncioasyncdefclient(app:FastAPI):# By using "with" the FastAPI app launch hook is run, connecting the application routerasyncwithTestClient(app,use_cookies=False)asclient:while(awaitclient.get("/health")).json()!=True:awaitsleep(0.5)yieldclient@fixture(scope="session",autouse=True)@mark.asyncioasyncdefunauthenticated_client(client:TestClient):blank_client=BrowserTestClient(client=client,cookies=None,headers=None)yieldblank_client@fixture(scope="session",autouse=True)@mark.asyncioasyncdefauthenticated_client(client:TestClient):sessioned_client=BrowserTestClient(client=client,cookies=None,headers=FAKE_AUTH_HEADERS)awaitsessioned_client.get(f"/users/authorization{FAKE_AUTH_QP}")yieldsessioned_client@fixture(scope="function")@mark.asyncioasyncdefauthenticated_websocket(authenticated_client:BrowserTestClient):asyncwithauthenticated_client.websocket_connect("/ws")aswebsocket:# 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 testsyieldwebsocket(back to top)Where QueriesAdditional documentation will be added soon on complete functionality supported via the CRUD endpoint / AbstractRepositorywhereparameter.NEW QUERY FEATURESColumn casting!To cast a column to a different type during a query, send a where payload like one of the examples below.Atsvectorcast:where={"column_name:tsvector:english":{"*websearch_to_tsquery":"foo or bar -baz"}}The query stage's casting key name fortsvectorshould match the format<column_name>:tsvector:<vector language>.tsvectoris the most complicated form of casting, as it requires the cast type (tsvector) as well as the tsvector language (english, or another langauge) in the key definition.tsvectorthen supports the following query operators at the next level:*websearch_to_tsqueryand*match, both of which mirror the sqlalchemy docs regarding functionality.To add atsvectorfield to your cruddy data model, complete with proper indexing for performance, add the following to your table model class:# models/example.pyfromtypingimportAnyfromsqlmodelimportField,cast,func,TextfromsqlalchemyimportColumn,Index,literal_columnfromsqlalchemy.dialects.postgresqlimportJSONB,UUIDaspsqlUUIDfromfastapi_cruddy_frameworkimportCruddyModel,CruddyCreatedUpdatedMixin,UUID,uuid7classExampleUpdate(CruddyModel):data:Any=Field(schema_extra={"examples":[{"some":{"key":"value"}}]})classExampleCreate(ExampleUpdate):passclassExample(CruddyCreatedUpdatedMixin(),ExampleCreate,table=True):# type: ignoreid: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"),)AText(or any other) cast:where={"a_json_column_name:Text":{"*icontains":"some substring"}}The query stage's casting key name should match the format<column_name>:<cast type>.Generally cast types are straightforward and expect a query operator and input type that can be mapped to the column's casted type. Supported column cast types are:arraytsvectorBigIntegerBooleanDateDateTimeDoubleEnumFloatIntegerIntervalLargeBinaryMatchTypeNumericSmallIntegerStringTextTimeUnicodeUnicodeTextUuidARRAYBIGINTBINARYBLOBBOOLEANCHARCLOBDATEDATETIMEDECIMALDOUBLEDOUBLE_PRECISIONFLOATINTINTEGERJSONNCHARNUMERICNVARCHARREALSMALLINTTEXTTIMETIMESTAMPUUIDVARBINARYVARCHARValue casting!Datetime value with timezone:where={"datetime_column":{"*gt":{"*datetime":"2024-02-14T19:17:40.860657Z"}}}Datetime value without timezone:where={"datetime_column":{"*gt":{"*datetime_naive":"2024-02-14T19:17:40.860657Z"}}}(back to top)ContributingTo work on this repository, you need to take the following steps first:Use python 3.10+ for your local python environment. (library relies on alternative union syntax)Installpre-commitglobally by using the commandpip install pre-commit(This will be used to manage pre-commit git hooks)Clone this projectgit clone https://github.com/mdconaway/fastapi-cruddy-framework.gitorgit clone git@github.com:mdconaway/fastapi-cruddy-framework.gitcdinto this project directory.Runmake installto install all dependencies and setup git pre-commit hooks!Usemake run-example-sqliteto hoist an example server while operating on the framework.Usemake testto confirm functionality and ensure there are no regressions after modification.Submitpullrequests for new feature additions.(back to top)LicenseDistributed under the MIT License. SeeLICENSEfor more information.(back to top)