skip to navigation
skip to content

sqla_helpers 0.4.1

Provide some methods for getting objects with SQLAlchemy

Latest Version: 0.5.1

('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\n $> cd sqla_helpers\n $> sudo python2.7 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 goal of :class:`sqla_helpers.base_model.BaseModel` is to provide syntactic sugar for :mod:`SQLAlchemy`.\n\n\n:class:`sqla_helpers.base_model.BaseModel` is to use as mixin class. This class inherits from nothing and shouldn\'t be inherited.\nFor access method from model, models need to be declare 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 is generated by :func:`declarative_base` function from `SQLAlchemy`.\n\nTo avoid mixin uses, :class:`sqla_helpers.base_model.BaseModel` class can be use as `cls` parameter in :func:`declarative_base`\nfunction. \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 to build a session when queries are done.\nIn order to access a session when needing, the class uses the stored function :attr:`sqla_helpers.base_model.BaseModel.sessionmaker`. \nThis function will be called each time a session is needed.\nSo we need to store a session_maker by calling `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, you can just give a Session which is not a `callable`\n\n.. code-block:: python\n\n from somwhere import DBSession\n\n # Application\'s initialization\n def main():\n # ...\n BaseModel.register_sessionmaker(DBSession)\n # ...\n\nRegister a session maker can be dangerous. Because, technically, we change dynamically a classemethod. To prevent errors, an exception , :exc:`sqla_helpers.base_model.SessionMakerExists`, is raised if a session maker is already registered.\n\nBut sometimes, may be you need to change it while application is running. So, you can force an new record even a session maker is already registered\n\n.. code-block:: python\n\n >>> BaseModel.register_sessionmaker(db_session)\n >>> new_db_session = amazing_function()\n >>> BaseModel.register_sessionmaker(new_db_session)\n Traceback (most recent call last):\n File "<stdin>", line 1, in <module>\n SessionMakerExists: A session maker is already registered.\n >>> BaseModel.register_sessionmaker(new_db_session, force=True)\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) allows to split between the differents entities.\n\nQuering with relation`s attributes can be done recursively.\nIf `MyOtherObject` has an `other_attr` attribute which is in relation with a `MyOtherOtherObject` object.\n\nQuering all `MyModel` with 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 operators than equality can be used. Those operators should be written\nwith the attribute name following \'__\' (double underscore) and operator\'s name.\n\nIE: if all `MyModel` with `id` different than 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* \'ge\': 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\nAs the Django way, :mod:`sqla_helpers` provides a :class:`sqla_helpers.logical.Q` object for more complex queries.\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 goal of those objects is to allow SQL logical conditions in a python syntax.\n\nIf all `Treatment` objects wih 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 AS treatment_id, AS treatment_name,\n treatment.status_id AS treatment_status_id\n FROM treatment JOIN status ON = treatment.status_id\n WHERE ( = ? OR = ?) AND ( = ? OR\n != ?)\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 order to have easier loading, :mod:`sqla_helpers` provides methods for loading from a regular python dictionary or a SQLAlchemy model object.\n\nThe :meth:`sqla_helpers.base_model.BaseModel.dump` method allows a JSON compatible dictionary.\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 build object from a dictionary.\nThe meaning of use a dictionary is to facilitate access to data in JSON or generate JSON from dictionary.\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 >>>\n \'YEAH \\\\o/\'\n >>>\n 7\n >>>\n \'Holy status !\'\n >>>\n 7\n >>> t = Treatment.load({\'id\': 7, \'name\': \'hello\'})\n >>>,\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 >>>\n None\n >>>\n None\n >>> session.add(tr)\n >>> session.commit()\n >>>\n 10\n >>>\n 8\n\n\n:class:`sqla_helpers.base_model.BaseModel` class\n================================================\n\n.. automodule:: sqla_helpers.base_model\n',)  
File Type Py Version Uploaded on Size
sqla_helpers-0.4.1.tar.gz (md5) Source 2013-09-29 13KB