skip to navigation
skip to content

Not Logged In

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 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 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    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 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        >>> 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.4.1.tar.gz (md5) Source 2013-09-29 13KB
  • Downloads (All Versions):
  • 30 downloads in the last day
  • 157 downloads in the last week
  • 829 downloads in the last month