updated readme and added example project

Author: eadwinCode

README.md

@@ -8,6 +8,13 @@
 [![PyPI version](https://img.shields.io/pypi/v/ellar-sqlachemy.svg)](https://pypi.python.org/pypi/ellar-sqlachemy)
 [![PyPI version](https://img.shields.io/pypi/pyversions/ellar-sqlachemy.svg)](https://pypi.python.org/pypi/ellar-sqlachemy)
 
+## Project Status
+- 70% done
+- SQLAlchemy Table support with ModelSession
+- Migration custom revision directives
+- Documentation
+- File Field
+- Image Field
 
 ## Introduction
 Ellar SQLAlchemy Module simplifies the integration of SQLAlchemy and Alembic migration tooling into your ellar application.

examples/single-db/README.md

@@ -0,0 +1,26 @@
+## Ellar SQLAlchemy Single Database Example
+Project Description
+
+## Requirements
+Python >= 3.7
+Starlette
+Injector
+
+## Project setup
+```shell
+pip install poetry
+```
+then, 
+```shell
+poetry install
+```
+### Apply Migration
+```shell
+ellar db upgrade
+```
+
+### Development Server
+```shell
+ellar runserver --reload
+```
+then, visit [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)

examples/single-db/db/__init__.py

@@ -0,0 +1,47 @@
+"""
+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"}
+"""
+from ellar.common import Controller, ControllerBase, get, post, Body
+from pydantic import EmailStr
+from sqlalchemy import select
+
+from .models.users import User
+
+
+@Controller
+class DbController(ControllerBase):
+
+    @get("/")
+    def index(self):
+        return {"detail": "Welcome Db Resource"}
+
+    @post("/users")
+    def create_user(self, username: Body[str], email: Body[EmailStr]):
+        session = User.get_db_session()
+        user = User(username=username, email=email)
+
+        session.add(user)
+        session.commit()
+
+        return user.dict()
+
+    @get("/users/{user_id:int}")
+    def get_user_by_id(self, user_id: int):
+        session = User.get_db_session()
+        stmt = select(User).filter(User.id == user_id)
+        user = session.execute(stmt).scalar()
+        return user.dict()
+
+    @get("/users")
+    async def get_all_users(self):
+        session = User.get_db_session()
+        stmt = select(User)
+        rows = session.execute(stmt.offset(0).limit(100)).scalars()
+        return [row.dict() for row in rows]

examples/single-db/db/controllers.py

@@ -0,0 +1 @@
+Multi-database configuration for Flask.

examples/single-db/db/migrations/README

@@ -0,0 +1,50 @@
+# A generic, single database configuration.
+
+[alembic]
+# template used to generate migration files
+file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic,flask_migrate
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[logger_flask_migrate]
+level = INFO
+handlers =
+qualname = flask_migrate
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

examples/single-db/db/migrations/alembic.ini

@@ -0,0 +1,48 @@
+import asyncio
+import typing as t
+from logging.config import fileConfig
+
+from alembic import context
+from ellar.app import current_injector
+
+from ellar_sqlalchemy.migrations import (
+    MultipleDatabaseAlembicEnvMigration,
+    SingleDatabaseAlembicEnvMigration,
+)
+from ellar_sqlalchemy.services import EllarSQLAlchemyService
+
+db_service: EllarSQLAlchemyService = current_injector.get(EllarSQLAlchemyService)
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+fileConfig(config.config_file_name)  # type:ignore[arg-type]
+# logger = logging.getLogger("alembic.env")
+
+
+AlembicEnvMigrationKlass: t.Type[
+    t.Union[MultipleDatabaseAlembicEnvMigration, SingleDatabaseAlembicEnvMigration]
+] = (
+    MultipleDatabaseAlembicEnvMigration
+    if len(db_service.engines) > 1
+    else SingleDatabaseAlembicEnvMigration
+)
+
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+alembic_env_migration = AlembicEnvMigrationKlass(db_service)
+
+if context.is_offline_mode():
+    alembic_env_migration.run_migrations_offline(context)  # type:ignore[arg-type]
+else:
+    asyncio.get_event_loop().run_until_complete(
+        alembic_env_migration.run_migrations_online(context)  # type:ignore[arg-type]
+    )

examples/single-db/db/migrations/env.py

@@ -0,0 +1,63 @@
+<%!
+import re
+
+%>"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+<%!
+    from ellar.app import current_injector
+    from ellar_sqlalchemy.services import EllarSQLAlchemyService
+
+    db_service = current_injector.get(EllarSQLAlchemyService)
+    db_names = list(db_service.engines.keys())
+%>
+
+% if len(db_names) > 1:
+
+def upgrade(engine_name):
+    globals()["upgrade_%s" % engine_name]()
+
+
+def downgrade(engine_name):
+    globals()["downgrade_%s" % engine_name]()
+
+
+
+## generate an "upgrade_<xyz>() / downgrade_<xyz>()" function
+## for each database name in the ini file.
+
+% for db_name in db_names:
+
+def upgrade_${db_name}():
+    ${context.get("%s_upgrades" % db_name, "pass")}
+
+
+def downgrade_${db_name}():
+    ${context.get("%s_downgrades" % db_name, "pass")}
+
+% endfor
+
+% else:
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}
+
+% endif

examples/single-db/db/migrations/script.py.mako

@@ -0,0 +1,39 @@
+"""first migration
+
+Revision ID: b7712f83d45b
+Revises: 
+Create Date: 2023-12-30 20:53:37.393009
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'b7712f83d45b'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('user',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('username', sa.String(), nullable=False),
+        sa.Column('email', sa.String(), nullable=False),
+        sa.Column('created_date', sa.DateTime(), nullable=False),
+        sa.Column('time_updated', sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint('id', name=op.f('pk_user')),
+        sa.UniqueConstraint('username', name=op.f('uq_user_username'))
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table('user')
+    # ### end Alembic commands ###
+

examples/single-db/db/migrations/versions/2023_12_30_2053-b7712f83d45b_first_migration.py

@@ -0,0 +1,5 @@
+from .users import User
+
+__all__ = [
+    'User',
+]