ohmyapi 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

ohmyapi/builtin/auth/routes.py

@@ -11,7 +11,7 @@ from pydantic import BaseModel
 from ohmyapi.builtin.auth.models import Group, User
 
 # Router
-router = APIRouter(prefix="/auth", tags=["auth"])
+router = APIRouter(prefix="/auth", tags=["Auth"])
 
 # Secrets & config (should come from settings/env in real projects)
 JWT_SECRET = getattr(settings, "JWT_SECRET", "changeme")

ohmyapi/builtin/demo/__init__.py

@@ -1,2 +1 @@
-from . import models
-from . import routes
+from . import models, routes

ohmyapi/builtin/demo/models.py

@@ -1,10 +1,11 @@
-from ohmyapi.db import Model, field
-from ohmyapi_auth.models import User
-
 from datetime import datetime
 from decimal import Decimal
 from uuid import UUID
 
+from ohmyapi_auth.models import User
+
+from ohmyapi.db import Model, field
+
 
 class Team(Model):
     id: UUID = field.data.UUIDField(primary_key=True)

ohmyapi/builtin/demo/routes.py

@@ -1,19 +1,17 @@
-from ohmyapi.router import APIRouter, HTTPException, HTTPStatus
+from typing import List
+
 from ohmyapi.db.exceptions import DoesNotExist
+from ohmyapi.router import APIRouter, HTTPException, HTTPStatus
 
 from . import models
 
-from typing import List
-
 # Expose your app's routes via `router = fastapi.APIRouter`.
 # Use prefixes wisely to avoid cross-app namespace-collisions.
 # Tags improve the UX of the OpenAPI docs at /docs.
 router = APIRouter(prefix="/tournament")
 
 
-@router.get(
-    "/", tags=["tournament"], response_model=List[models.Tournament.Schema()]
-)
+@router.get("/", tags=["tournament"], response_model=List[models.Tournament.Schema()])
 async def list():
     """List all tournaments."""
     return await models.Tournament.Schema().from_queryset(models.Tournament.all())
@@ -30,9 +28,7 @@ async def post(tournament: models.Tournament.Schema(readonly=True)):
 @router.get("/{id}", tags=["tournament"], response_model=models.Tournament.Schema())
 async def get(id: str):
     """Get tournament by id."""
-    return await models.Tournament.Schema().from_queryset(
-        models.Tournament.get(id=id)
-    )
+    return await models.Tournament.Schema().from_queryset(models.Tournament.get(id=id))
 
 
 @router.put(

ohmyapi/core/runtime.py

@@ -1,12 +1,13 @@
 # ohmyapi/core/runtime.py
-import copy
 import importlib
 import importlib.util
 import json
 import pkgutil
 import sys
+from http import HTTPStatus
 from pathlib import Path
-from typing import Any, Dict, Generator, List, Optional
+from types import ModuleType
+from typing import Any, Dict, Generator, List, Optional, Type
 
 import click
 from aerich import Command as AerichCommand
@@ -21,8 +22,9 @@ class Project:
     """
     Project runtime loader + Tortoise/Aerich integration.
 
-    - injects builtin apps as ohmyapi_<name>
-    - builds unified tortoise config for runtime
+    - aliases builtin apps as ohmyapi_<name>
+    - loads all INSTALLED_APPS into scope
+    - builds unified tortoise config for ORM runtime
     - provides makemigrations/migrate methods using Aerich Command API
     """
 
@@ -34,8 +36,8 @@ class Project:
         if str(self.project_path) not in sys.path:
             sys.path.insert(0, str(self.project_path))
 
-        # Pre-register builtin apps as ohmyapi_<name>.
-        # This makes all builtin apps easily loadable via f"ohmyapi_{app_name}".
+        # Alias builtin apps as ohmyapi_<name>.
+        # We need this, because Tortoise app-names may not include dots `.`.
         spec = importlib.util.find_spec("ohmyapi.builtin")
         if spec and spec.submodule_search_locations:
             for _, modname, _ in pkgutil.iter_modules(spec.submodule_search_locations):
@@ -107,7 +109,7 @@ class Project:
         }
 
         for app_name, app in self._apps.items():
-            modules = list(dict.fromkeys(app.model_modules))
+            modules = list(app.models.keys())
             if modules:
                 config["apps"][app_name] = {
                     "models": modules,
@@ -119,11 +121,20 @@ class Project:
     def build_aerich_command(
         self, app_label: str, db_url: Optional[str] = None
     ) -> AerichCommand:
+        """
+        Build Aerich command for app with given app_label.
+
+        Aerich needs to see only the app of interest, but with the extra model
+        "aerich.models".
+        """
         if app_label not in self._apps:
             raise RuntimeError(f"App '{app_label}' is not registered")
 
         # Get a fresh copy of the config (without aerich.models anywhere)
-        tortoise_cfg = copy.deepcopy(self.build_tortoise_config(db_url=db_url))
+        tortoise_cfg = self.build_tortoise_config(db_url=db_url)
+
+        # Prevent leaking other app's models to Aerich.
+        tortoise_cfg["apps"] = {app_label: tortoise_cfg["apps"][app_label]}
 
         # Append aerich.models to the models list of the target app only
         tortoise_cfg["apps"][app_label]["models"].append("aerich.models")
@@ -199,33 +210,18 @@ class App:
         self.project = project
         self.name = name
 
-        # The list of module paths (e.g. "ohmyapi_auth.models") for Tortoise and Aerich
-        self.model_modules: List[str] = []
+        # Reference to this app's models modules. Tortoise needs to know the
+        # modules where to lookup models for this app.
+        self._models: Dict[str, ModuleType] = {}
 
-        # The APIRouter
-        self.router: APIRouter = APIRouter()
+        # Reference to this app's routes modules.
+        self._routers: Dict[str, ModuleType] = {}
 
         # Import the app, so its __init__.py runs.
-        importlib.import_module(self.name)
-
-        # Load the models
-        try:
-            models_mod = importlib.import_module(f"{self.name}.models")
-            self.model_modules.append(f"{self.name}.models")
-        except ModuleNotFoundError:
-            pass
+        mod: ModuleType = importlib.import_module(name)
 
-        # Locate the APIRouter
-        try:
-            routes_mod = importlib.import_module(f"{self.name}.routes")
-            for attr_name in dir(routes_mod):
-                if attr_name.startswith("__"):
-                    continue
-                attr = getattr(routes_mod, attr_name)
-                if isinstance(attr, APIRouter):
-                    self.router.include_router(attr)
-        except ModuleNotFoundError:
-            pass
+        self.__load_models(f"{self.name}.models")
+        self.__load_routes(f"{self.name}.routes")
 
     def __repr__(self):
         return json.dumps(self.dict(), indent=2)
@@ -233,42 +229,127 @@ class App:
     def __str__(self):
         return self.__repr__()
 
-    def _serialize_route(self, route):
-        """Convert APIRoute to JSON-serializable dict."""
+    def __load_models(self, mod_name: str):
+        """
+        Recursively scan through a module and collect all models.
+        If the module is a package, iterate through its submodules.
+        """
+
+        # An app may come without any models.
+        try:
+            importlib.import_module(mod_name)
+        except ModuleNotFoundError:
+            print(f"no models detected: {mod_name}")
+            return
+
+        # Acoid duplicates.
+        visited: set[str] = set()
+
+        def walk(mod_name: str):
+            mod = importlib.import_module(mod_name)
+            if mod_name in visited:
+                return
+            visited.add(mod_name)
+
+            for name, value in vars(mod).copy().items():
+                if (
+                    isinstance(value, type)
+                    and issubclass(value, Model)
+                    and not name == Model.__name__
+                ):
+                    self._models[mod_name] = self._models.get(mod_name, []) + [value]
+
+            # if it's a package, recurse into submodules
+            if hasattr(mod, "__path__"):
+                for _, subname, _ in pkgutil.iter_modules(
+                    mod.__path__, mod.__name__ + "."
+                ):
+                    walk(subname)
+
+        # Walk the walk.
+        walk(mod_name)
+
+    def __load_routes(self, mod_name: str):
+        """
+        Recursively scan through a module and collect all APIRouters.
+        If the module is a package, iterate through all its submodules.
+        """
+
+        # An app may come without any routes.
+        try:
+            importlib.import_module(mod_name)
+        except ModuleNotFound:
+            print(f"no routes detected: {mod_name}")
+            return
+
+        # Avoid duplicates.
+        visited: set[str] = set()
+
+        def walk(mod_name: str):
+            mod = importlib.import_module(mod_name)
+            if mod.__name__ in visited:
+                return
+            visited.add(mod.__name__)
+
+            for name, value in vars(mod).copy().items():
+                if isinstance(value, APIRouter) and not name == APIRouter.__name__:
+                    self._routers[mod_name] = self._routers.get(mod_name, []) + [value]
+
+            # if it's a package, recurse into submodules
+            if hasattr(mod, "__path__"):
+                for _, subname, _ in pkgutil.iter_modules(
+                    mod.__path__, mod.__name__ + "."
+                ):
+                    submod = importlib.import_module(subname)
+                    walk(submod)
+
+        # Walk the walk.
+        walk(mod_name)
+
+    def __serialize_route(self, route):
+        """
+        Convert APIRoute to JSON-serializable dict.
+        """
         return {
             "path": route.path,
-            "name": route.name,
-            "methods": list(route.methods),
-            "endpoint": route.endpoint.__name__,  # just the function name
-            "response_model": (
-                getattr(route, "response_model", None).__name__
-                if getattr(route, "response_model", None)
-                else None
-            ),
-            "tags": getattr(route, "tags", None),
+            "method": list(route.methods)[0],
+            "endpoint": f"{route.endpoint.__module__}.{route.endpoint.__name__}",
         }
 
-    def _serialize_router(self):
-        return [self._serialize_route(route) for route in self.routes]
+    def __serialize_router(self):
+        return [self.__serialize_route(route) for route in self.routes]
 
-    def dict(self) -> Dict[str, Any]:
+    @property
+    def models(self) -> List[ModuleType]:
+        """
+        Return a list of all loaded models.
+        """
+        out = []
+        for module in self._models:
+            for model in self._models[module]:
+                out.append(model)
         return {
-            "models": [m.__name__ for m in self.models],
-            "routes": self._serialize_router(),
+            module: out,
         }
 
-    @property
-    def models(self) -> Generator[Model, None, None]:
-        for mod in self.model_modules:
-            models_mod = importlib.import_module(mod)
-            for obj in models_mod.__dict__.values():
-                if (
-                    isinstance(obj, type)
-                    and getattr(obj, "_meta", None) is not None
-                    and obj.__name__ != "Model"
-                ):
-                    yield obj
-
     @property
     def routes(self):
-        return self.router.routes
+        """
+        Return an APIRouter with all loaded routes.
+        """
+        router = APIRouter()
+        for routes_mod in self._routers:
+            for r in self._routers[routes_mod]:
+                router.include_router(r)
+        return router.routes
+
+    def dict(self) -> Dict[str, Any]:
+        """
+        Convenience method for serializing the runtime data.
+        """
+        return {
+            "models": [
+                f"{self.name}.{m.__name__}" for m in self.models[f"{self.name}.models"]
+            ],
+            "routes": self.__serialize_router(),
+        }

ohmyapi/db/model/model.py

@@ -30,16 +30,16 @@ UUID.__get_pydantic_core_schema__ = classmethod(__uuid_schema_monkey_patch)
 
 
 class ModelMeta(type(TortoiseModel)):
-    def __new__(cls, name, bases, attrs):
-        new_cls = super().__new__(cls, name, bases, attrs)
+    def __new__(mcls, name, bases, attrs):
+        # Grab the Schema class for further processing.
+        schema_opts = attrs.get("Schema", None)
 
-        schema_opts = getattr(new_cls, "Schema", None)
+        # Let Tortoise's Metaclass do it's thing.
+        new_cls = super().__new__(mcls, name, bases, attrs)
 
         class BoundSchema:
             def __call__(self, readonly: bool = False):
-                if readonly:
-                    return self.readonly
-                return self.model
+                return self.get(readonly)
 
             @property
             def model(self):
@@ -66,6 +66,11 @@ class ModelMeta(type(TortoiseModel)):
                     exclude_readonly=True,
                 )
 
+            def get(self, readonly: bool = False):
+                if readonly:
+                    return self.readonly
+                return self.model
+
         new_cls.Schema = BoundSchema()
         return new_cls
 

ohmyapi/router.py

@@ -1,2 +1,3 @@
-from fastapi import APIRouter, Depends, HTTPException
 from http import HTTPStatus
+
+from fastapi import APIRouter, Depends, HTTPException

ohmyapi-0.2.2.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: ohmyapi
+Version: 0.2.2
+Summary: Django-flavored scaffolding and management layer around FastAPI, Pydantic, TortoiseORM and Aerich migrations
+License-Expression: MIT
+Keywords: fastapi,tortoise,orm,pydantic,async,web-framework
+Author: Brian Wiborg
+Author-email: me@brianwib.org
+Requires-Python: >=3.11
+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
+Provides-Extra: auth
+Requires-Dist: aerich (>=0.9.1,<0.10.0)
+Requires-Dist: argon2-cffi (>=25.1.0,<26.0.0)
+Requires-Dist: argon2-cffi ; extra == "auth"
+Requires-Dist: crypto (>=1.4.1,<2.0.0)
+Requires-Dist: crypto ; extra == "auth"
+Requires-Dist: fastapi (>=0.117.1,<0.118.0)
+Requires-Dist: ipython (>=9.5.0,<10.0.0)
+Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: passlib (>=1.7.4,<2.0.0)
+Requires-Dist: passlib ; extra == "auth"
+Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
+Requires-Dist: pyjwt ; extra == "auth"
+Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
+Requires-Dist: python-multipart ; extra == "auth"
+Requires-Dist: tortoise-orm (>=0.25.1,<0.26.0)
+Requires-Dist: typer (>=0.19.1,<0.20.0)
+Requires-Dist: uvicorn (>=0.36.0,<0.37.0)
+Description-Content-Type: text/markdown
+
+# OhMyAPI
+
+OhMyAPI is a web-application scaffolding framework and management layer built around `FastAPI`, `TortoiseORM` and `Aerich` migrations.
+
+> *Think: Django RestFramework, but less clunky and 100% async.*
+
+It is ***blazingly fast***, extremely ***fun to use*** and comes with ***batteries included***!
+
+**Features**
+
+- Django-like project structure and application directories
+- Django-like per-app migrations (makemigrations & migrate) via Aerich
+- Django-like CLI tooling (startproject, startapp, shell, serve, etc)
+- Customizable pydantic model serializer built-in
+- Various optional built-in apps you can hook into your project
+- Highly configurable and customizable
+- 100% async
+
+**Goals**
+
+- combine FastAPI, TortoiseORM, Aerich migrations and Pydantic into a high-productivity web-application framework
+- tie everything neatly together into a concise and straight-forward API
+- AVOID adding any abstractions on top, unless they make things extremely convenient
+
+## Installation
+
+```
+pipx install ohmyapi
+```
+
+
+## Docs
+
+See: `docs/`
+
+- [Projects](docs/projects.md)
+- [Apps](docs/apps.md)
+- [Models](docs/models.md)
+- [Migrations](docs/migrations.md)
+- [Routes](docs/routes.md)
+

{ohmyapi-0.2.0.dist-info → ohmyapi-0.2.2.dist-info}/RECORD

@@ -3,13 +3,13 @@ ohmyapi/__main__.py,sha256=wcCrL4PjG51r5wVKqJhcoJPTLfHW0wNbD31DrUN0MWI,28
 ohmyapi/builtin/auth/__init__.py,sha256=vOVCSJX8BALzs8h5ZW9507bjoscP37bncMjdMmBXcMM,42
 ohmyapi/builtin/auth/models.py,sha256=8az4TKdC6PUha3_HyslKinDT2-yAN-aBoYUQcjxm7Js,1728
 ohmyapi/builtin/auth/permissions.py,sha256=mxsnhF_UGesTFle7v1JHORkNODtQ0qanAL3FtOcMCEY,145
-ohmyapi/builtin/auth/routes.py,sha256=ZNtGUZahmUboTNT_LB2F9sbjpSPp86DtgkOOj73mKlc,6304
-ohmyapi/builtin/demo/__init__.py,sha256=k1rGtOmMPVZJ1fMPELY0v3k70WyzSp18pstJTkCdFr0,42
-ohmyapi/builtin/demo/models.py,sha256=N3LnHLEa5wYBvaQBImCR4SdZvRYGuwM_iyLCeh9QY8s,1403
-ohmyapi/builtin/demo/routes.py,sha256=JZbW_ZBirzNEO6PuJO_ZPV4k__cH8rvU9JN6CDhocWc,1821
+ohmyapi/builtin/auth/routes.py,sha256=r887BWea20vinX88QBuxGzQc9BrIi-LqyStM0V1cl1o,6304
+ohmyapi/builtin/demo/__init__.py,sha256=44Yo3mYmlKSKEwVp6O9urr-C_3qDQzCYLMn6B9i6wew,29
+ohmyapi/builtin/demo/models.py,sha256=r06rfuhPJaI2fYsQ24L1JCOd67f2GQNfGnkgKAptOX8,1404
+ohmyapi/builtin/demo/routes.py,sha256=1VTlEttrez6Qnhrz_9sTA-emtfXem0s0BkPVcLvg3k0,1801
 ohmyapi/cli.py,sha256=dJVNgpW5S4rCc619AEEKBKuEIAmQs153Ls0ZVaea48w,4173
 ohmyapi/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ohmyapi/core/runtime.py,sha256=tdFSOu9fV2BjcE5BIfGfm3jjeGw6Tw8jCM6-hk5Be2s,9264
+ohmyapi/core/runtime.py,sha256=6MejxdFxY9zfmAEcFMIly-R5JEhIlzf3hlx9dZWBZrY,11748
 ohmyapi/core/scaffolding.py,sha256=SA0SYFd7VcqkOn9xuXgj-yOoVqCZMJo68GGFbm34GE4,2663
 ohmyapi/core/templates/app/__init__.py.j2,sha256=QwVIQVUGZVhdH1d4NrvL7NTsK4-T4cihzYs8UVX2dt4,43
 ohmyapi/core/templates/app/models.py.j2,sha256=_3w-vFJ5fgsmncsCv34k_wyCMF78jufbSSglns4gbb0,119
@@ -20,9 +20,9 @@ ohmyapi/core/templates/project/settings.py.j2,sha256=So6w1OiL_jU-FyeT8IHueDjGNuE
 ohmyapi/db/__init__.py,sha256=5QKUycxnN83DOUD_Etoee9tEOYjnZ74deqrSOOx_MiQ,204
 ohmyapi/db/exceptions.py,sha256=vb4IIUoeYAY6sK42zRtjMy-39IFVi_Qb6mWySTY0jYw,34
 ohmyapi/db/model/__init__.py,sha256=k3StTNuKatpwZo_Z5JBFa-927eJrzibFE8U4SA82asc,32
-ohmyapi/db/model/model.py,sha256=MQAXVDYpCjGFWfn3u2XP4Q6OZzIJrJBWOWcg5sBDhlw,2581
-ohmyapi/router.py,sha256=6Exv6sVPVyiIYxxAQbxQhFRX74MKTUPWXIBwC7UZ-ww,82
-ohmyapi-0.2.0.dist-info/METADATA,sha256=vXWbYbDs2N51-xAToeAFj0hUDMtp6PMmU48JhRErBeg,10280
-ohmyapi-0.2.0.dist-info/WHEEL,sha256=M5asmiAlL6HEcOq52Yi5mmk9KmTVjY2RDPtO4p9DMrc,88
-ohmyapi-0.2.0.dist-info/entry_points.txt,sha256=wb3lw8-meAlpiv1mqcQ3m25ukL7djagU_w89GkrC37k,43
-ohmyapi-0.2.0.dist-info/RECORD,,
+ohmyapi/db/model/model.py,sha256=ui4g78c5xoS06Dj8Cdk7QgTjRnE68zKeL-AdmeYYPuQ,2776
+ohmyapi/router.py,sha256=5g0U59glu4hxxnIoTSFzb2S2offkOT3eE39aprzVxwo,83
+ohmyapi-0.2.2.dist-info/METADATA,sha256=73UvH4QOy4q4OgAom0k8d7dtSgeqYSG6VhYRGu0WXDA,2556
+ohmyapi-0.2.2.dist-info/WHEEL,sha256=M5asmiAlL6HEcOq52Yi5mmk9KmTVjY2RDPtO4p9DMrc,88
+ohmyapi-0.2.2.dist-info/entry_points.txt,sha256=wb3lw8-meAlpiv1mqcQ3m25ukL7djagU_w89GkrC37k,43
+ohmyapi-0.2.2.dist-info/RECORD,,

ohmyapi-0.2.0.dist-info/METADATA

@@ -1,436 +0,0 @@
-Metadata-Version: 2.4
-Name: ohmyapi
-Version: 0.2.0
-Summary: Django-flavored scaffolding and management layer around FastAPI, Pydantic, TortoiseORM and Aerich migrations
-License-Expression: MIT
-Keywords: fastapi,tortoise,orm,pydantic,async,web-framework
-Author: Brian Wiborg
-Author-email: me@brianwib.org
-Requires-Python: >=3.11
-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
-Provides-Extra: auth
-Requires-Dist: aerich (>=0.9.1,<0.10.0)
-Requires-Dist: argon2-cffi (>=25.1.0,<26.0.0)
-Requires-Dist: argon2-cffi ; extra == "auth"
-Requires-Dist: crypto (>=1.4.1,<2.0.0)
-Requires-Dist: crypto ; extra == "auth"
-Requires-Dist: fastapi (>=0.117.1,<0.118.0)
-Requires-Dist: ipython (>=9.5.0,<10.0.0)
-Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
-Requires-Dist: passlib (>=1.7.4,<2.0.0)
-Requires-Dist: passlib ; extra == "auth"
-Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
-Requires-Dist: pyjwt ; extra == "auth"
-Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
-Requires-Dist: python-multipart ; extra == "auth"
-Requires-Dist: tortoise-orm (>=0.25.1,<0.26.0)
-Requires-Dist: typer (>=0.19.1,<0.20.0)
-Requires-Dist: uvicorn (>=0.36.0,<0.37.0)
-Description-Content-Type: text/markdown
-
-# OhMyAPI
-
-> Think: Django RestFramework, but less clunky and 100% async.
-
-OhMyAPI is a Django-flavored web-application scaffolding framework and management layer,
-built around FastAPI and TortoiseORM and is thus 100% async.
-
-It is ***blazingly fast***, extremely ***fun to use*** and comes with ***batteries included***!
-
-**Features**
-
-- Django-like project structure and application directories
-- Django-like per-app migrations (`makemigrations` & `migrate`) via Aerich
-- Django-like CLI tooling (`startproject`, `startapp`, `shell`, `serve`, etc)
-- Customizable pydantic model serializer built-in 
-- Various optional built-in apps you can hook into your project
-- Highly configurable and customizable
-- 100% async
-
-**Goals**
-
-- combine `FastAPI`, `TortoiseORM`, `Aerich` migrations and `Pydantic` into a high-productivity web-application framework
-- tie everything neatly together into a concise and straight-forward API
-- ***AVOID*** adding any abstractions on top, unless they make things extremely convenient
-
----
-
-## Getting started
-
-**Creating a Project**
-
-```
-pipx install ohmyapi
-ohmyapi startproject myproject
-cd myproject
-```
-
-This will create the following directory structure:
-
-```
-myproject/
-  - pyproject.toml
-  - README.md
-  - settings.py
-```
-
-Run your project with:
-
-```
-ohmyapi serve
-```
-
-In your browser go to:
-- http://localhost:8000/docs
-
-**Creating an App**
-
-Create a new app by:
-
-```
-ohmyapi startapp tournament
-```
-
-This will create the following directory structure:
-
-```
-myproject/
-  - tournament/
-    - __init__.py
-    - models.py
-    - routes.py
-  - pyproject.toml
-  - README.md
-  - settings.py
-```
-
-Add 'tournament' to your `INSTALLED_APPS` in `settings.py`.
-
-### Models
-
-Write your first model in `turnament/models.py`:
-
-```python
-from ohmyapi.db import Model, field
-
-from datetime import datetime
-from decimal import Decimal
-from uuid import UUID
-
-
-class Tournament(Model):
-    id: UUID = field.data.UUIDField(primary_key=True)
-    name: str = field.TextField()
-    created: datetime = field.DatetimeField(auto_now_add=True)
-
-    def __str__(self):
-        return self.name
-
-
-class Event(Model):
-    id: UUID = field.data.UUIDField(primary_key=True)
-    name: str = field.TextField()
-    tournament: UUID = field.ForeignKeyField('tournament.Tournament', related_name='events')
-    participants: field.ManyToManyRelation[Team] = field.ManyToManyField('tournament.Team', related_name='events', through='event_team')
-    modified: datetime = field.DatetimeField(auto_now=True)
-    prize: Decimal = field.DecimalField(max_digits=10, decimal_places=2, null=True)
-
-    def __str__(self):
-        return self.name
-
-
-class Team(Model):
-    id: UUID = field.data.UUIDField(primary_key=True)
-    name: str = field.TextField()
-
-    def __str__(self):
-        return self.name
-```
-
-### API Routes
-
-Next, create your endpoints in `tournament/routes.py`:
-
-```python
-from ohmyapi.router import APIRouter, HTTPException, HTTPStatus
-from ohmyapi.db.exceptions import DoesNotExist
-
-from typing import List
-
-from .models import Tournament
-
-# OhMyAPI will automatically pick up all instances of `fastapi.APIRouter` and
-# add their routes to the main project router.
-#
-# Note:
-# Use prefixes wisely to avoid cross-app namespace-collisions!
-# Tags improve the UX of the OpenAPI docs at /docs.
-#
-tournament_router = APIRouter(prefix="/tournament", tags=['Tournament'])
-
-
-@tournament_router.get("/", response_model=List[Tournament.Schema()])
-async def list():
-    queryset = Tournament.all()
-    return await Tournament.Schema.model.from_queryset(queryset)
-
-
-@tournament_router.post("/", status_code=HTTPStatus.CREATED)
-async def post(tournament: Tournament.Schema(readonly=True)):
-    queryset = Tournament.create(**payload.model_dump())
-    return await Tournament.Schema().from_queryset(queryset)
-
-
-@tournament_router.get("/:id", response_model=Tournament.Schema())
-async def get(id: str):
-    try:
-        queryset = Tournament.get(id=id)
-        return await Tournament.Schema().from_queryset_single(tournament)
-    except DoesNotExist:
-        raise HTTPException(status_code=404, detail="not found")
-
-
-@tournament_router.delete("/:id")
-async def delete(id: str):
-    try:
-        tournament = await Tournament.get(id=id)
-        return await Tournament.Schema.model.from_queryset(tournament.delete())
-    except DoesNotExist:
-        raise HTTPException(status_code=404, detail="not found")
-
-
-...
-```
-
-## Migrations
-
-Before we can run the app, we need to create and initialize the database.
-
-Similar to Django, first run:
-
-```
-ohmyapi makemigrations [ <app> ]  # no app means all INSTALLED_APPS
-```
-
-This will create a `migrations/` folder in you project root.
-
-```
-myproject/
-  - tournament/
-    - __init__.py
-    - models.py
-    - routes.py
-  - migrations/
-    - tournament/
-  - pyproject.toml
-  - README.md
-  - settings.py
-```
-
-Apply your migrations via:
-
-```
-ohmyapi migrate [ <app> ]  # no app means all INSTALLED_APPS
-```
-
-Run your project:
-
-```
-ohmyapi serve
-```
-
-## Authentication
-
-A builtin auth app is available.
-
-Simply add `ohmyapi_auth` to your INSTALLED_APPS and define a JWT_SECRET in your `settings.py`.
-Remember to `makemigrations` and `migrate` for the necessary tables to be created in the database.
-
-`settings.py`:
-
-```
-INSTALLED_APPS = [
-    'ohmyapi_auth',
-    ...
-]
-
-JWT_SECRET = "t0ps3cr3t"
-```
-
-After restarting your project you will have access to the `ohmyapi_auth` app.
-It comes with a `User` and `Group` model, as well as endpoints for JWT auth.
-
-You can use the models as `ForeignKeyField` in your application models:
-
-```python
-from ohmyapi.db import Model, field
-from ohmyapi_auth.models import User
-
-
-class Team(Model):
-    [...]
-    members: field.ManyToManyRelation[User] = field.ManyToManyField('ohmyapi_auth.User', related_name='tournament_teams', through='tournament_teams')
-    [...]
-```
-
-Remember to run `makemigrations` and `migrate` in order for your model changes to take effect in the database.
-
-Create a super-user:
-
-```
-ohmyapi createsuperuser
-```
-
-## Permissions
-
-### API-Level Permissions
-
-Use FastAPI's `Depends` pattern to implement API-level access-control.
-
-
-In your `routes.py`:
-
-```python
-from ohmyapi.router import APIRouter, Depends
-from ohmyapi_auth import (
-    models as auth,
-    permissions,
-)
-
-from .models import Tournament
-
-router = APIRouter(prefix="/tournament", tags=["Tournament"])
-
-
-@router.get("/")
-async def list(user: auth.User = Depends(permissions.require_authenticated)):
-    queryset = Tournament.all()
-    return await Tournament.Schema().from_queryset(queryset)
-
-
-...
-```
-
-### Model-Level Permissions
-
-Use Tortoise's `Manager` to implement model-level permissions.
-
-```python
-from ohmyapi.db import Manager
-from ohmyapi_auth.models import User
-
-
-class TeamManager(Manager):
-    async def for_user(self, user: User):
-        return await self.filter(members=user).all()
-
-
-class Team(Model):
-    [...]
-
-    class Meta:
-        manager = TeamManager()
-```
-
-Use the custom manager in your FastAPI route handler:
-
-```python
-from ohmyapi.router import APIRouter
-from ohmyapi_auth import (
-    models as auth,
-    permissions,
-)
-
-router = APIRouter(prefix="/tournament", tags=["Tournament"])
-
-
-@router.get("/teams")
-async def teams(user: auth.User = Depends(permissions.require_authenticated)):
-    queryset = Team.for_user(user)
-    return await Tournament.Schema().from_queryset(queryset)
-```
-
-## Shell
-
-Similar to Django, you can attach to an interactive shell with your project already loaded inside.
-
-```
-ohmyapi shell
-
-Python 3.13.7 (main, Aug 15 2025, 12:34:02) [GCC 15.2.1 20250813]
-Type 'copyright', 'credits' or 'license' for more information
-IPython 9.5.0 -- An enhanced Interactive Python. Type '?' for help.
-
-OhMyAPI Shell | Project: {{ project_name }} [{{ project_path }}]
-Find your loaded project singleton via identifier: `p`
-```
-
-```python
-In [1]: p
-Out[1]: <ohmyapi.core.runtime.Project at 0x7f00c43dbcb0>
-
-In [2]: p.apps
-Out[2]:
-{'ohmyapi_auth': {
-   "models": [
-     "Group",
-     "User"
-   ],
-   "routes": [
-     {
-       "path": "/auth/login",
-       "name": "login",
-       "methods": [
-         "POST"
-       ],
-       "endpoint": "login",
-       "response_model": null,
-       "tags": [
-         "auth"
-       ]
-     },
-     {
-       "path": "/auth/refresh",
-       "name": "refresh_token",
-       "methods": [
-         "POST"
-       ],
-       "endpoint": "refresh_token",
-       "response_model": null,
-       "tags": [
-         "auth"
-       ]
-     },
-     {
-       "path": "/auth/introspect",
-       "name": "introspect",
-       "methods": [
-         "GET"
-       ],
-       "endpoint": "introspect",
-       "response_model": null,
-       "tags": [
-         "auth"
-       ]
-     },
-     {
-       "path": "/auth/me",
-       "name": "me",
-       "methods": [
-         "GET"
-       ],
-       "endpoint": "me",
-       "response_model": null,
-       "tags": [
-         "auth"
-       ]
-     }
-   ]
- }}
-```
-
-