skip to navigation
skip to content

Not Logged In

sqla_helpers 0.5.1

Provide some methods for getting objects with SQLAlchemy

('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 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 declared 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 used 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` needs 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\nRegistering a session maker can be dangerous. Because, technically, we change dynamically a class method. To prevent errors, an exception , :exc:`sqla_helpers.base_model.SessionMakerExists`, is raised if a session maker is already registered.\n\nBut sometimes, perhaps you need to change it while application is running. So, you can force a new record even if 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 >>> MyModel.count(id=2)\n 1\n\n\n* :meth:`sqla_helpers.base_model.BaseModel.all` returns all the database objects\n* :meth:`sqla_helpers.base_model.BaseModel.filter` returns a list of matching objects.\n* :meth:`sqla_helpers.base_model.BaseModel.get` returns an uniq matching object.\n* :meth:`sqla_helpers.base_model.BaseModel.count` returns the number of matching objects.\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 querying criterions for a class are defined by the class attributes.\nIE : in case of `MyOtherModel`, criterions can be `id`, `name` and `model_id`.\n\nThis is still true for a Sqlachemy relation.\n\nIE: querying 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\nQuerying 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 relations attributes can be done recursively.\nIf `MyOtherObject` has an `other_attr` attribute which is in relation with a `MyOtherOtherObject` object.\n\nQuerying 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 operators 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 querying\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 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 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 objects 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 >>> 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',)  
File Type Py Version Uploaded on Size
sqla_helpers-0.5.1.tar.gz (md5) Source 2014-02-21 14KB
  • Downloads (All Versions):
  • 23 downloads in the last day
  • 169 downloads in the last week
  • 569 downloads in the last month