Metadata-Version: 1.0
Name: lymph-sqlalchemy
Version: 0.7.0
Summary: UNKNOWN
Home-page: http://github.com/deliveryhero/lymph-sqlalchemy/
Author: Dushyant Rijhwani
Author-email: dushyant.rijhwani@deliveryhero.com
License: Apache License (2.0)
Description: lymph-sqlalchemy
        ================
        
        This is a library is a basic wrapper around sqlalchemy that provides an easy
        way to write an interface, integrate logging and helps in testing.
        
        Store
        -----
        
        The ``lymph.sqlalchemy.store.Store`` class is a basic wrapper around sqlalchemy,
        it configures the engine and gives an interface to sessions.
        
        
        .. code-block:: python
        
            from lymph.sqlalchemy.store import Store
            store = Store('postgresql://postgres/lymph-test-sqlalchemy')
            # Access the engine
            engine = store.engine
            engine.execute('SELECT 1')
        
            # The sessions are context managers
            with store.get_session() as session:
                session.add(user)
        
        
        You can pass all of the engine args to the ``Store``, they would be passed on
        when creating the engine.
        
        
        Defining Models
        --------------
        
        The recommended way of defining your models is by first creating an sqlalchemy declarative base class and then
        define your models like any normal sqlalchemy models:
        
        .. code-block:: python
        
            from sqlalchemy import Column, Integer, String
            from sqlalchemy.ext.declarative import declarative_base
        
            Base = declarative_base()
        
            class User(Base):
                 __tablename__ = 'users'
        
                 id = Column(Integer, primary_key=True)
                 name = Column(String)
        
        
        **IMPORTANT**: Please put the ``Base`` class in the same python module as the models, else you may
        have some import problems.
        
        Interface
        ---------
        
        The ``lymph.sqlalchemy.interface.StoreInterface`` class uses the the lymph config to
        configure a store instance.
        
        An example config for a ``StoreInterface`` looks like this, it has a dependency
        on store.
        
        .. code-block:: python
        
            import lymph
            from lymph.sqlalchemy.interface import StoreInterface
        
            class UserInterface(StoreInterface):
        
                @lymph.rpc()
                def create_user(self, data):
                    user = User(**data)
                    with self.store.get_session() as session:
                        session.add(user)
        
        
        .. code-block:: yaml
        
            dependencies:
                store:
                    class: lymph.sqlalchemy.store:Store
                    uri: postgresql://postgres/users
                    pool_size: 5
                    max_overflow: 10
                    pool_timeout: 30
                    base: dhh.users.models:Base
        
            interfaces:
                restaurants:
                    class: UserInterface
                    store: dep:store
        
        Testing
        -------
        
        The library provides a ``lymph.sqlalchemy.testing.StorageInterfaceTest`` to help
        you write your unittests. You would extend this class by providing it your own
        database config and your service interface.
        
        The class would create the database on ``setupClass`` and it would create the
        tables and the models that you provided as fixtures in ``setUp`` method of the
        test case.
        
        In the ``teardown`` this class would drop all the tables.
        
        .. code-block:: python
        
            from lymph.sqlalchemy.testing import StorageInterfaceTest
        
        
            class UserInterfaceTest(StorageInterfaceTest):
        
                def get_fixtures(self):
                    self.user = User(name='Test')
                    self.user_2 = User(name='Test 2')
                    return [self.user, self.user_2]
        
                def test_get_user(self):
                    user = self.client.get(pk=self.user.id)
                    user_2 = self.client.get(pk=self.user_2.id)
                    self.assertEqual(user.id, self.user.id)
                    self.assertEqual(user_2.id, self.user_2.id)
        
        
        Command Line Interfaces
        -----------------------
        
        This library provides a couple of cli to make the workflow easiers.
        
        
        ``init-db`` command would create all the tables for all models that are defined
        using the library's `Base`
        
        .. code-block:: bash
        
            $lymph init-db -c <config>.yml
        
        
        .. code-block:: yaml
        
            dependencies:
                store:
                      class: lymph.sqlalchemy.store:Store
                      base: dhh.users.models:Base
        
        
        ``sql-shell`` command would give you a shell with a `store` instance already
        configured.
        
        .. code-block:: bash
        
             $LYMPH_NODE_CONFIG=`pwd`/.lymph.yml lymph sql-shell -c <config>.yml
        
Platform: UNKNOWN
