Added code sample and fixed failing tests

Author: eadwinCode

.github/workflows/test_full.yml

@@ -11,12 +11,8 @@ jobs:
     strategy:
       matrix:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
-        django-version: ['<3.2', '<3.3', '<4.2', '<4.3', '<5.1']
+        django-version: ['<3.2', '<3.3', '<4.2', '<4.3']
         exclude:
-          - python-version: '3.8'
-            django-version: '<5.1'
-          - python-version: '3.9'
-            django-version: '<5.1'
           - python-version: '3.12'
             django-version: '<3.2'
           - python-version: '3.12'

README.md

@@ -205,6 +205,7 @@ MIDDLEWARE = [
     "whitenoise.middleware.WhiteNoiseMiddleware",
     ...
 ]
+WHITENOISE_STATIC_PREFIX = '/static/'
 ...
 ```
 So when you visit [http://localhost:8000/-django-example/admin](http://localhost:8000/-django-example/admin) again, the page should be functional.

ellar_django/commands.py

@@ -1,31 +1,156 @@
 import sys
+import typing as t
 
-import click
+import django
+import ellar_cli.click as click
 
-HELP_MESSAGE = """
-Ellar will always intercept and command with '--help'.
 
-So if you want to get help on any django command,
-simply wrap the command and --help in quotes
+class _CommandItem(t.NamedTuple):
+    name: str
+    description: str
 
-For example: ellar django 'migrate --help' or python manage.py django 'migrate --help'
-"""
 
+_django_support_commands: t.List[_CommandItem] = [
+    _CommandItem(
+        name="migrate",
+        description="Synchronizes the database state with the current set of models and migrations",
+    ),
+    _CommandItem(
+        name="makemigrations",
+        description="Creates new migrations based on the changes detected to your models.",
+    ),
+    _CommandItem(
+        name="check",
+        description="inspects the entire Django project for common problems",
+    ),
+    _CommandItem(
+        name="createcachetable",
+        description="Creates the cache tables for use with the database cache backend",
+    ),
+    _CommandItem(
+        name="dbshell",
+        description="Runs the command-line client for the database engine",
+    ),
+    _CommandItem(
+        name="diffsettings",
+        description="Displays differences between the current settings and default settings",
+    ),
+    _CommandItem(
+        name="dumpdata",
+        description="Outputs to standard output all data in the database",
+    ),
+    _CommandItem(
+        name="flush",
+        description="Removes all data from the database and re-executes any post-synchronization handlers",
+    ),
+    _CommandItem(
+        name="inspectdb", description="Introspects the database tables in the database"
+    ),
+    _CommandItem(
+        name="loaddata",
+        description="Searches for and loads the contents into the database.",
+    ),
+    _CommandItem(
+        name="optimizemigration",
+        description="Optimizes the operations for the named migration and overrides the existing file",
+    ),
+    _CommandItem(
+        name="showmigrations", description="Shows all migrations in a project."
+    ),
+    _CommandItem(
+        name="sqlflush",
+        description="Prints the SQL statements that would be executed for the flush command",
+    ),
+    _CommandItem(
+        name="sqlmigrate", description="Prints the SQL for the named migration."
+    ),
+    _CommandItem(
+        name="sqlsequencereset",
+        description="Prints the SQL statements for resetting sequences for the given app name(s)",
+    ),
+    _CommandItem(
+        name="squashmigrations", description="Squashes the migrations for app_label"
+    ),
+    _CommandItem(
+        name="startapp", description="Creates a Django app directory structure"
+    ),
+    _CommandItem(
+        name="changepassword",
+        description="This command is only available if Django’s authentication system",
+    ),
+    _CommandItem(
+        name="createsuperuser",
+        description="Creates a superuser account (a user who has all permissions)",
+    ),
+    _CommandItem(
+        name="collectstatic", description="Expose static files to STATIC_ROOT folder"
+    ),
+    _CommandItem(name="findstatic", description="Search for a static file location"),
+    _CommandItem(
+        name="clearsessions",
+        description="Can be run as a cron job or directly to clean out expired sessions.",
+    ),
+]
 
-@click.command(
+
+def version_callback(ctx: click.Context, _: t.Any, value: bool) -> None:
+    if value:
+        click.echo(f"Django Version: {django.__version__}")
+        raise click.Exit(0)
+
+
+@click.group(
     name="django",
-    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
-    help=HELP_MESSAGE,
+    help="- Ellar Django Commands",
 )
-def django_command_wrapper() -> None:
-    from django.core.management import execute_from_command_line
+@click.option(
+    "-v",
+    "--version",
+    callback=version_callback,
+    help="Show the version and exit.",
+    is_flag=True,
+    expose_value=False,
+    is_eager=True,
+)
+@click.pass_context
+def django_command(ctx: click.Context) -> None:
+    pass
+
+
+def _add_django_command(command_item: _CommandItem) -> None:
+    def help_callback(ctx: click.Context, _: t.Any, value: bool) -> None:
+        from django.core.management import execute_from_command_line
+
+        if value:
+            args = ["manage.py", command_item.name, "--help"]
+
+            execute_from_command_line(args)
+            raise click.Exit(0)
+
+    @django_command.command(
+        name=command_item.name,
+        help=command_item.description,
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+        add_help_option=False,
+    )
+    @click.option(
+        "-h",
+        "--help",
+        callback=help_callback,
+        help="Show the version and exit.",
+        is_flag=True,
+        expose_value=False,
+        is_eager=True,
+    )
+    @click.with_app_context
+    def _command() -> None:
+        from django.core.management import execute_from_command_line
+
+        args = ["manage.py", command_item.name]
 
-    args = []
-    skip = 1
+        for item in sys.argv[3:]:
+            args.extend(item.split(" "))
+        execute_from_command_line(args)
 
-    if "manage.py" in sys.argv:  # pragma: no cover
-        skip = 2
 
-    for item in sys.argv[skip:]:
-        args.extend(item.split(" "))
-    execute_from_command_line(args)
+list(map(_add_django_command, _django_support_commands))

ellar_django/module.py

@@ -7,7 +7,7 @@
 from starlette.responses import RedirectResponse
 from starlette.routing import Mount
 
-from .commands import django_command_wrapper
+from .commands import django_command
 from .middleware import DjangoAdminRedirectMiddleware
 
 _router = ModuleRouter()
@@ -18,7 +18,7 @@ async def _redirect_route(req: Request) -> RedirectResponse:
     return RedirectResponse(url=str(req.base_url))
 
 
-@Module(commands=[django_command_wrapper])
+@Module(commands=[django_command])
 class DjangoModule(IModuleSetup):
     @classmethod
     def setup(cls, settings_module: str, path_prefix: str = "/dj") -> "DynamicModule":

sample/ellar-and-django-orm/README.md

@@ -0,0 +1,17 @@
+## Introduction
+This is an illustration of using DjangoORM within your Ellar Project.
+
+## Project setup
+```
+pip install -r requirements.txt
+```
+
+## Apply Migrations
+```shell
+python manage.py django migrate
+```
+
+## Development Server
+```
+python manage.py runserver --reload
+```

sample/ellar-and-django-orm/ellar_and_django_orm/__init__.py

@@ -0,0 +1,32 @@
+"""
+Define endpoints routes in python class-based fashion
+example:
+
+@Controller("/dogs", tag="Dogs", description="Dogs Resources")
+class MyController(ControllerBase):
+    @get('/')
+    def index(self):
+        return {'detail': "Welcome Dog's Resources"}
+"""
+
+import typing as t
+
+from ellar.common import Controller, ControllerBase, get, post
+
+from ...interfaces.events_repository import IEventRepository
+from .schemas import EventSchema, EventSchemaOut
+
+
+@Controller("/event")
+class EventController(ControllerBase):
+    def __init__(self, event_repo: IEventRepository):
+        self.event_repo = event_repo
+
+    @post("/", response={201: EventSchemaOut})
+    def create_event(self, event: EventSchema):
+        event = self.event_repo.create_event(**event.dict())
+        return 201, event
+
+    @get("/", response=t.List[EventSchema], name="event-list")
+    def list_events(self):
+        return list(self.event_repo.list_events())

sample/ellar-and-django-orm/ellar_and_django_orm/apps/__init__.py

@@ -0,0 +1,39 @@
+"""
+@Module(
+    controllers=[MyController],
+    providers=[
+        YourService,
+        ProviderConfig(IService, use_class=AService),
+        ProviderConfig(IFoo, use_value=FooService()),
+    ],
+    routers=(routerA, routerB)
+    statics='statics',
+    template='template_folder',
+    # base_directory -> default is the `event` folder
+)
+class MyModule(ModuleBase):
+    def register_providers(self, container: Container) -> None:
+        # for more complicated provider registrations
+        pass
+
+"""
+
+from ellar.common import Module
+from ellar.core import ModuleBase
+from ellar.di import Container
+
+from .controllers import EventController
+
+
+@Module(
+    controllers=[EventController],
+    providers=[],
+    routers=[],
+)
+class EventModule(ModuleBase):
+    """
+    Event Module
+    """
+
+    def register_providers(self, container: Container) -> None:
+        """for more complicated provider registrations, use container.register_instance(...)"""