Metadata-Version: 2.1
Name: FastAPI-SQLModel
Version: 0.0.1
Summary: Adds simple SQLModel support to FastAPI
Home-page: https://github.com/hitman-gdg/fastapi-sqlmodel
Author: Shawn Martin
Author-email: hitman.gdg@gmail.com
License: MIT
Project-URL: Code, https://github.com/hitman-gdg/fastapi-sqlmodel
Project-URL: Issue tracker, https://github.com/hitman-gdg/fastapi-sqlmodel/issues
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
License-File: LICENSE
Requires-Dist: starlette (>=0.12.9)
Requires-Dist: SQLAlchemy (>=1.2)

FastAPI-SQModel
==================

FastAPI-SQLModel provides a simple integration between FastAPI_ and SQLModel_ in your application. It gives access to useful helpers to facilitate the completion of common tasks.


Installing
----------

Install and update using pip_:

.. code-block:: text

  $ pip install fastapi-sqlmodel


Examples
--------

Usage inside of a route
^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from fastapi import FastAPI
    from fastapi_sqlmodel import DBSessionMiddleware  # middleware helper
    from fastapi_sqlmodel import db  # an object to provide global access to a database session

    from app.models import User

    app = FastAPI()

    app.add_middleware(DBSessionMiddleware, db_url="sqlite://")

    # once the middleware is applied, any route can then access the database session 
    # from the global ``db``

    @app.get("/users")
    def get_users():
        users = db.session.query(User).all()

        return users

Note that the session object provided by ``db.session`` is based on the Python3.7+ ``ContextVar``. This means that
each session is linked to the individual request context in which it was created.

Usage outside of a route
^^^^^^^^^^^^^^^^^^^^^^^^

Sometimes it is useful to be able to access the database outside the context of a request, such as in scheduled tasks which run in the background:

.. code-block:: python

    import pytz
    from apscheduler.schedulers.asyncio import AsyncIOScheduler  # other schedulers are available
    from fastapi import FastAPI
    from fastapi_sqlmodel import db

    from app.models import User, UserCount

    app = FastAPI()

    app.add_middleware(DBSessionMiddleware, db_url="sqlite://")


    @app.on_event('startup')
    async def startup_event():
        scheduler = AsyncIOScheduler(timezone=pytz.utc)
        scheduler.start()
        scheduler.add_job(count_users_task, "cron", hour=0)  # runs every night at midnight


    def count_users_task():
        """Count the number of users in the database and save it into the user_counts table."""

        # we are outside of a request context, therefore we cannot rely on ``DBSessionMiddleware``
        # to create a database session for us. Instead, we can use the same ``db`` object and 
        # use it as a context manager, like so:

        with db():
            user_count = db.session.query(User).count()

            db.session.add(UserCount(user_count))
            db.session.commit()
        
        # no longer able to access a database session once the db() context manager has ended

        return users


.. _FastAPI: https://github.com/tiangolo/fastapi
.. _SQLModel: https://github.com/tiangolo/sqlmodel
.. _pip: https://pip.pypa.io/en/stable/quickstart/

