|Build Status| |PyPi| |Documentation| |codecov.io|
Falcon Middleware: SQLAlchemy Integration
=========================================
The ``falcon-sqla`` package provides a middleware component for managing
`SQLAlchemy sessions <https://docs.sqlalchemy.org/orm/session_api.html#Session>`_.
The manager component can also serve as a base building block or a recipe for
more complex use cases, such as applications leveraging multiple database
binds.
Installation
------------
.. code:: bash
$ pip install falcon-sqla
Usage
-----
The ``falcon_sqla`` session ``Manager`` can be used in two ways:
* As a `Falcon middleware component
<https://falcon.readthedocs.io/en/stable/api/middleware.html>`_.
* As a context manager to explicitly provide a database session.
Configuration
^^^^^^^^^^^^^
* Create a SQLAlchemy engine.
* Pass the engine to the ``Manager()`` initializer as its first parameter.
* If using the manager as a middleware component, pass its ``middleware``
property to a
`falcon.App <https://falcon.readthedocs.io/en/stable/api/app.html>`__\'s
middleware list:
.. code:: python
engine = create_engine('dialect+driver://my/database')
manager = falcon_sqla.Manager(engine)
app = falcon.App(middleware=[manager.middleware])
# The database session will be available as req.context.session
Context Manager
^^^^^^^^^^^^^^^
A ``falcon_sqla.Manager`` can also explicitly provide a database session using
the ``session_scope()`` context manager:
.. code:: python
# Somewhere inside a responder
with self.manager.session_scope(req, resp) as session:
# Use the session
# <...>
``session_scope()`` can also be used as a standalone session context outside of
the request-response cycle:
.. code:: python
with self.manager.session_scope() as session:
# Use the session
# <...>
Custom Vertical Partitioning
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Simple random selection of read- and write- database replicas is supported
out of the box. Use the ``add_engine()`` method to instruct the ``Manager`` to
include the provided engines in the runtime bind selection logic:
.. code:: python
manager = falcon_sqla.Manager(engine)
read_replica = create_engine('dialect+driver://my/database.replica')
manager.add_engine(read_replica, 'r')
The ``Manager.get_bind()`` method can be overridden to implement custom engine
selection logic for more complex use cases.
See also this SQLAlchemy recipe:
`Custom Vertical Partitioning
<https://docs.sqlalchemy.org/orm/persistence_techniques.html#custom-vertical-partitioning>`_.
About Falcon
------------
`Falcon <https://falconframework.org/>`_ is the minimalist REST API and
microservices framework for Python developers, with a focus on reliability,
correctness, and performance at scale.
About SQLAlchemy
----------------
`SQLAlchemy <https://www.sqlalchemy.org/>`_ is the Python SQL toolkit and
Object Relational Mapper that gives application developers the full power and
flexibility of SQL.
.. |Build Status| image:: https://github.com/vytas7/falcon-sqla/workflows/tox/badge.svg
:target: https://github.com/vytas7/falcon-sqla/actions?query=workflow%3A%22tox%22
.. |PyPi| image:: https://img.shields.io/pypi/v/falcon-sqla.svg
:target: https://pypi.python.org/pypi/falcon-sqla
.. |Documentation| image:: https://readthedocs.org/projects/falcon-sqla/badge/?version=latest
:target: https://falcon-sqla.readthedocs.io/en/latest/
.. |codecov.io| image:: https://codecov.io/gh/vytas7/falcon-sqla/branch/master/graphs/badge.svg
:target: http://codecov.io/gh/vytas7/falcon-sqla
Raw data
{
"_id": null,
"home_page": "https://github.com/vytas7/falcon-sqla",
"name": "falcon-sqla",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "falcon,wsgi,database,middleware,orm,sqlalchemy",
"author": "Vytautas Liuolia",
"author_email": "vytautas.liuolia@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/09/c9/a8955f875857a91bb1d09bfbb8c5dd3cc8509a45535f6432a7ac508beb03/falcon-sqla-0.4.0.tar.gz",
"platform": null,
"description": "|Build Status| |PyPi| |Documentation| |codecov.io|\n\nFalcon Middleware: SQLAlchemy Integration\n=========================================\n\nThe ``falcon-sqla`` package provides a middleware component for managing\n`SQLAlchemy sessions <https://docs.sqlalchemy.org/orm/session_api.html#Session>`_.\nThe manager component can also serve as a base building block or a recipe for\nmore complex use cases, such as applications leveraging multiple database\nbinds.\n\n\nInstallation\n------------\n\n.. code:: bash\n\n $ pip install falcon-sqla\n\n\nUsage\n-----\n\nThe ``falcon_sqla`` session ``Manager`` can be used in two ways:\n\n* As a `Falcon middleware component\n <https://falcon.readthedocs.io/en/stable/api/middleware.html>`_.\n* As a context manager to explicitly provide a database session.\n\n\nConfiguration\n^^^^^^^^^^^^^\n\n* Create a SQLAlchemy engine.\n* Pass the engine to the ``Manager()`` initializer as its first parameter.\n* If using the manager as a middleware component, pass its ``middleware``\n property to a\n `falcon.App <https://falcon.readthedocs.io/en/stable/api/app.html>`__\\'s\n middleware list:\n\n.. code:: python\n\n engine = create_engine('dialect+driver://my/database')\n manager = falcon_sqla.Manager(engine)\n\n app = falcon.App(middleware=[manager.middleware])\n\n # The database session will be available as req.context.session\n\nContext Manager\n^^^^^^^^^^^^^^^\n\nA ``falcon_sqla.Manager`` can also explicitly provide a database session using\nthe ``session_scope()`` context manager:\n\n.. code:: python\n\n # Somewhere inside a responder\n with self.manager.session_scope(req, resp) as session:\n # Use the session\n # <...>\n\n``session_scope()`` can also be used as a standalone session context outside of\nthe request-response cycle:\n\n.. code:: python\n\n with self.manager.session_scope() as session:\n # Use the session\n # <...>\n\nCustom Vertical Partitioning\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nSimple random selection of read- and write- database replicas is supported\nout of the box. Use the ``add_engine()`` method to instruct the ``Manager`` to\ninclude the provided engines in the runtime bind selection logic:\n\n.. code:: python\n\n manager = falcon_sqla.Manager(engine)\n\n read_replica = create_engine('dialect+driver://my/database.replica')\n manager.add_engine(read_replica, 'r')\n\n\nThe ``Manager.get_bind()`` method can be overridden to implement custom engine\nselection logic for more complex use cases.\n\nSee also this SQLAlchemy recipe:\n`Custom Vertical Partitioning\n<https://docs.sqlalchemy.org/orm/persistence_techniques.html#custom-vertical-partitioning>`_.\n\n\nAbout Falcon\n------------\n\n`Falcon <https://falconframework.org/>`_ is the minimalist REST API and\nmicroservices framework for Python developers, with a focus on reliability,\ncorrectness, and performance at scale.\n\n\nAbout SQLAlchemy\n----------------\n\n`SQLAlchemy <https://www.sqlalchemy.org/>`_ is the Python SQL toolkit and\nObject Relational Mapper that gives application developers the full power and\nflexibility of SQL.\n\n\n.. |Build Status| image:: https://github.com/vytas7/falcon-sqla/workflows/tox/badge.svg\n :target: https://github.com/vytas7/falcon-sqla/actions?query=workflow%3A%22tox%22\n\n.. |PyPi| image:: https://img.shields.io/pypi/v/falcon-sqla.svg\n :target: https://pypi.python.org/pypi/falcon-sqla\n\n.. |Documentation| image:: https://readthedocs.org/projects/falcon-sqla/badge/?version=latest\n :target: https://falcon-sqla.readthedocs.io/en/latest/\n\n.. |codecov.io| image:: https://codecov.io/gh/vytas7/falcon-sqla/branch/master/graphs/badge.svg\n :target: http://codecov.io/gh/vytas7/falcon-sqla\n",
"bugtrack_url": null,
"license": "",
"summary": "Middleware for integrating Falcon applications with SQLAlchemy.",
"version": "0.4.0",
"split_keywords": [
"falcon",
"wsgi",
"database",
"middleware",
"orm",
"sqlalchemy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eeea255ddb9c3f49bc435adbebe1c91ac0011319700df6e2b5644a013c417950",
"md5": "2e3f9fbb8d1a4f23a424b1f15cab4fcd",
"sha256": "e3aa4c87ffcb7ce88137679ac9efa4d16b2e2cee9c11f43216b403001252cc3c"
},
"downloads": -1,
"filename": "falcon_sqla-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e3f9fbb8d1a4f23a424b1f15cab4fcd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14412,
"upload_time": "2023-01-27T13:08:54",
"upload_time_iso_8601": "2023-01-27T13:08:54.535503Z",
"url": "https://files.pythonhosted.org/packages/ee/ea/255ddb9c3f49bc435adbebe1c91ac0011319700df6e2b5644a013c417950/falcon_sqla-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "09c9a8955f875857a91bb1d09bfbb8c5dd3cc8509a45535f6432a7ac508beb03",
"md5": "bf0abfaa43f1f4d9893c6381ab42dc63",
"sha256": "b83be0b7b1a066d89ceae4b96445a601d2b290eaddf449970dc2bf9399585276"
},
"downloads": -1,
"filename": "falcon-sqla-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "bf0abfaa43f1f4d9893c6381ab42dc63",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12975,
"upload_time": "2023-01-27T13:08:56",
"upload_time_iso_8601": "2023-01-27T13:08:56.513755Z",
"url": "https://files.pythonhosted.org/packages/09/c9/a8955f875857a91bb1d09bfbb8c5dd3cc8509a45535f6432a7ac508beb03/falcon-sqla-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-27 13:08:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "vytas7",
"github_project": "falcon-sqla",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "falcon-sqla"
}
JSON
