sqla_helpers 0.3.5

('Helpers SQLAlchemy - :class:`sqla_helpers.base_model.BaseModel`\n===============================================================\nInstallation\n-------------\n\n.. rubric:: Git\n\nInstallation from git\n\n.. code-block:: console\n\n $> git clone git@github.com:moumoutte/sqla_helpers.git\n $> cd sqla_helpers\n $> sudo python2.7 setup.py install\n\n.. rubric:: Eggs\n\nInstallation from pypi `eggs`\n\n.. code-block:: console\n\n $> sudo pip install sqla_helpers\n\n\nGetting Started\n----------------\n\nThe purpose :class:`sqla_helpers.base_model.BaseModel` is to implement the `SQLAlchemy` syntax with simplified methods for querying.\n\n\n:class:`sqla_helpers.base_model.BaseModel` is to be use in a mixin class. this class inherits from nothing and shouldn\'t be inherited.\nFor access method from model, Table need to be implement as bellow:\n\n.. code-block:: python\n\n from somewhere import DeclarativeBase\n from sqla_helpers.base_model import BaseModel\n\n class MyModel(DeclarativeBase, BaseModel):\n id = ... # Clef primaire , l\'identifiant sous forme d\'entier\n awesome_attr = ... # Attribut quelconque du mod\xc3\xa8le\n other_model = relationship(\'MyOtherModel\', backref=\'mymodel\')\n\n\n class MyOtherModel(DeclarativeBase, BaseModel):\n id = ... # Clef primaire\n name = ...\n model_id = ... # Clef \xc3\xa9trang\xc3\xa8re sur MyModel\n\n\nThe :class:`DeclarativeBase` class if generated by :func:`declarative_base` function from `SQLAlchemy`.\n\n:class:`sqla_helpers.base_model.BaseModel` class can be use as `cls` parameter in :func:`declarative_base`\nfunction. This prevents the mixin use of the class.\n\n.. code-block:: python\n\n from sqlalchemy.ext.declarative import declarative_base\n from sqla_helpers.base_model import BaseModel\n DeclarativeBase = declarative_base(cls=BaseModel)\n\n\n.. code-block:: python\n\n class MyModel(DeclarativeBase):\n # ...\n\n\n:class:`sqla_helpers.base_model.BaseModel` need a to have a method for getting a session when querying is done.\nFor this purpose, the class use the stored function in :attr:`sqla_helpers.base_model.BaseModel.sessionmaker`.:\nSo a sessionmaker is need to be stored using the `sqla_helpers.base_model.BaseModel.register_sessionmaker` method\n\n.. code-block:: python\n\n # Application\'s initialization\n def main():\n # ...\n BaseModel.register_sessionmaker(scoped_session(sessionmaker(bind=engine)))\n # ...\n\nFor a global session, the function set in :attr:`sqla_helpers.base_model.BaseModel.sessionmaker` should return\na reference to a global session.\n\n.. code-block:: python\n\n from somwhere import DBSession\n\n # Application\'s initialization\n def main():\n # ...\n BaseModel.register_sessionmaker(lambda: DBSession)\n # ...\n\n\nBasic use case :\n\n.. code-block:: python\n\n >>> MyModel.all()\n [<MyModel object at 0x2c19d90>]\n >>> MyModel.get(id=2)\n <MyModel object at 0x2c19d90>\n >>> MyModel.get(id=3)\n *** NoResultFound: No row was found for one()\n >>> MyModel.filter(id=2)\n [<MyModel object at 0x2c19d90>]\n >>> MyModel.filter(id=3)\n []\n\n\n* :meth:`sqla_helpers.base_model.BaseModel.all` returns all database objects\n* :meth:`sqla_helpers.base_model.BaseModel.filter` returns a list of matching objects.\n* :meth:`sqla_helpers.base_model.BaseModel.get` return an uniq maching object.\n\nQuerying criterions can be chained with an `&&` (logical and) operator.\n\n.. code-block:: python\n\n >>> MyOtherModel.filter(name=\'toto\')\n [<MyOtherModel object at 0x2c19d90>, <MyOtherModel object at 0x2e27e08>]\n >>> MyOtherModel.filter(name=\'toto\', id=2)\n [<MyOtherModel object at 0x2c19d90>]\n\n\nQuerying for criterions on relations\n------------------------------------\n\nValid quering criterions for a class ared definied by the class attributes.\nIE : in case of `MyOtherModel`, criterions can be `id`, `name` and `model_id`.\n\nThis still true for a Sqlachemy relation.\n\nIE: quering all `MyModel` witch `MyOtherModel` have a name \'foo\'.\n\n.. code-block:: python\n\n >>> MyModel.filter(awesome_attr__name=\'foo\')\n [<MyModel object at 0x2c19d90>]\n\n\nQuering a with entire object.\n\n.. code-block:: python\n\n >>> otherModel = MyOtherModel.get(name=\'foo\')\n >>> MyModel.filter(awesome_attr=otherModel)\n [<MyModel object at 0x2c19d90>]\n\n\nThe `__` separator (double underscore) permits to split between the differents entities.\n\nQuering with relation`s attributes can be recursive.\nIf `MyOtherObject` have an `other_attr` attribute which is in relation with a `MyOtherOtherObject` object.\n\nQuering all `MyModel` which a `MyOtherObject` has `MyOtherOtherObject` has a `name` attribute is \'foo\'.\n\n.. code-block:: python\n\n >>> MyModel.filter(awesome_attr__other_attr__name=\'foo\')\n [<MyModel object at 0x2c19d90>]\n\n\n\nOperators\n---------\n\nOthers criterions than equality can be used. These criterions sould be writen\nwith the attribute name following \'__\' (double underscore) and name of the operator.\n\nIE: if all `MyModel` which `id` is different from 2 are wanted:\n\n.. code-block:: python\n\n >>> MyModel.filter(id__not=2)\n []\n\nAvailable operatores are:\n\n* \'not\': Non-equal,\n* \'lt\': letter than,\n* \'le\': letter or equals than,\n* \'gt\': gretter than,\n* \'gte\': gretter or equal than,\n* \'in\': in a list,\n* \'like\': SQL `LIKE` operator,\n* \'ilike\': SQL `ILIKE` operator.\n\n\nMore complex quering\n--------------------\n\nIn the Django spirit, :mod:`sqla_helpers` provide a :class:`sqla_helpers.logical.Q` object for more complex quering.\nThe :class:`sqla_helpers.logical.Q` object can use the :mod:`sqla_helpers\' syntax.\n\n.. code-block:: python\n\n >>> from sqla_helpers.logical import Q\n >>> Q(status__name=\'test\')\n <sqla_helpers.logical.Q at 0x2376cd0>\n\n\nThese objects are usable as criterions for query.\n\n:class:`sqla_helpers.base_model.BaseModel`\n\n.. code-block:: python\n\n >>> Treatment.get(Q(id=2))\n >>> <sqlalchemy_test.models.Treatment at 0x2388690>\n\nThe purpose of these objects is to permit SQL logical conditions in a python syntax.\n\nIf all `Treatment` objects which have an `id` == 2 or a `Status` name == \'KO\' are wanted.\n\n.. code-block:: python\n\n >>> Treatment.filter(Q(id=2) | Q(status__name=\'KO\'))\n [<sqlalchemy_test.models.Treatment at 0x2388690>, <sqlalchemy_test.models.Treatment at 0x23837d0>]\n\n\nFor getting, all `Treatment` objects with an `id\' attribute different than 2 :\n\n.. code-block:: python\n\n >>> Treatment.filter(~Q(id=2))\n [<sqlalchemy_test.models.Treatment at 0x2383450>, <sqlalchemy_test.models.Treatment at 0x23837d0>,\n <sqlalchemy_test.models.Treatment at 0x23886d0> ]\n\nLogical operators can be chained :\n\n.. code-block:: python\n\n >>> Treatment.filter((Q(id=2) | Q(name=\'toto\')) & (Q(name=\'OK\') | ~Q(status__id=3)))\n 2013-02-10 16:39:49,485 INFO sqlalchemy.engine.base.Engine SELECT\n treatment.id AS treatment_id, treatment.name AS treatment_name,\n treatment.status_id AS treatment_status_id\n FROM treatment JOIN status ON status.id = treatment.status_id\n WHERE (treatment.id = ? OR treatment.name = ?) AND (treatment.name = ? OR\n status.id != ?)\n 2013-02-10 16:39:49,485 INFO sqlalchemy.engine.base.Engine (2, \'toto\', \'OK\',\n 3)\n >>> [<sqlalchemy_test.models.Treatment at 0x2388690>]\n\n\nJSON\n----\n\nOften in web oriented applications, client and server exchange with JSON format.\nIn a purpose of easier loading, :mod:`sqla_helpers` furnish methods for loading from a regular python dictionary or a SQLAlchemy model object.\n\nThe :meth:`sqla_helpers.base_model.BaseModel.dump` method permit a JSON compatible dictionnary.\n\n.. code-block:: python\n\n >>> print json.dumps(t.dump(), indent=4)\n {\n "status": {\n "id": 1,\n "name": "Ok"\n },\n "status_id": 1,\n "id": 1,\n "name": "Great Treatment"\n }\n\n\nThe method `sqla_helpers.base_model.BaseModel.load` can construct object from a dictionnary.\nThe meaning of use a dictionnary is to facillitate access to data in JSON or generate JSON frpm dictionnary.\n\nObjects are getting from database if primary key attributes are found on the dictionnary. Otherwise new object\nare created.\n\n.. code-block:: python\n\n >>> t = Treatment.get(id=7)\n >>> t.name\n \'YEAH \\\\o/\'\n >>> t.id\n 7\n >>> t.status.name\n \'Holy status !\'\n >>> t.status.id\n 7\n >>> t = Treatment.load({\'id\': 7, \'name\': \'hello\'})\n >>> t.name, t.id\n (\'hello\', 7)\n >>> session.commit()\n >>> t.dump()\n {\n \'id\': 7,\n \'name\': u\'hello\',\n \'status\': {\'id\': 7, \'name\': u\'Holy status !\'},\n \'status_id\': 7\n }\n >>> tr = Treatment.load(t.dump())\n >>> tr == t\n True\n >>> tr.status == t.status\n True\n >>> Treatment.load(tr.dump()).dump()\n {\n \'id\': 7,\n \'name\': u\'hello\',\n \'status\': {\'id\': 7, \'name\': u\'Holy status !\'},\n \'status_id\': 7\n }\n >>> tr = Treatment.load({\'name\': \'new treatment\', \'status\': {\'name\': \'new status\'}})\n >>> tr.id\n None\n >>> tr.status.id\n None\n >>> session.add(tr)\n >>> session.commit()\n >>> tr.id\n 10\n >>> tr.status.id\n 8\n\n\n:class:`sqla_helpers.base_model.BaseModel` class\n================================================\n\n.. automodule:: sqla_helpers.base_model\n',)