Permalink
Browse files

translation of doc/sqla_helpers.rst done

  • Loading branch information...
1 parent 9527589 commit bafc7513dc66cab02d1cdb2c7bcfd1fd1fbbd157 @cyplp cyplp committed Mar 24, 2013
Showing with 72 additions and 89 deletions.
  1. +72 −89 doc/sqla_helpers.rst
View
@@ -25,14 +25,11 @@ Installation from pypi `eggs`
Getting Started
----------------
-:class:`sqla_helpers.base_model.BaseModel` a pour but d'instrumenter la syntaxe d'SQLAlchemy pour
-fournir à l'utiliseur final, des méthodes simplifiées permettant la récupération
-d'objets en base.
+The purpose :class:`sqla_helpers.base_model.BaseModel` is to implement the `SQLAlchemy` syntax with simplified methods for querying.
-:class:`sqla_helpers.base_model.BaseModel` est une classe qui est utilisable en tant que Mixin, elle
-n'hérite d'aucune classe et elle n'est pas à sous-classer.
-Pour avoir accès aux méthodes dans un modèle, il faut alors déclarer une table
-comme ceci:
+
+:class:`sqla_helpers.base_model.BaseModel` is to be use in a mixin class. this class inherits from nothing and shouldn't be inherited.
+For access method from model, Table need to be implement as bellow:
.. code-block:: python
@@ -51,12 +48,10 @@ comme ceci:
model_id = ... # Clef étrangère sur MyModel
-La classe :class:`DeclarativeBase` est la classe générée par la fonction
-:func:`declarative_base` d'SQLAlchemy.
-
-Il est également possible d'utiliser :class:`sqla_helpers.base_model.BaseModel` comme paramètre `cls` de la fonction :func:`declarative_base`.
-Et ainsi on peut se passer de l'utilisation de la classe comme Mixin.
+The :class:`DeclarativeBase` class if generated by :func:`declarative_base` function from `SQLAlchemy`.
+:class:`sqla_helpers.base_model.BaseModel` class can be use as `cls` parameter in :func:`declarative_base`
+function. This prevents the mixin use of the class.
.. code-block:: python
@@ -71,36 +66,33 @@ Et ainsi on peut se passer de l'utilisation de la classe comme Mixin.
# ...
-:class:`sqla_helpers.base_model.BaseModel` attend une manière de récupérer une session quand une requête est effectuée.
-Pour ce faire, elle fait appel à la fonction stockée dans l'attribut :attr:`sqla_helpers.base_model.BaseModel.sessionmaker`.
-Ainsi, lors de l'initialisation de l'application, il faut stocker un
-sessionmaker dans la classe, grâce à la méthode
-`sqla_helpers.base_model.BaseModel.register_sessionmaker`
+:class:`sqla_helpers.base_model.BaseModel` need a to have a method for getting a session when querying is done.
+For this purpose, the class use the stored function in :attr:`sqla_helpers.base_model.BaseModel.sessionmaker`.:
+So a sessionmaker is need to be stored using the `sqla_helpers.base_model.BaseModel.register_sessionmaker` method
.. code-block:: python
- # Initialisation de l'application
+ # Application's initialization
def main():
# ...
BaseModel.register_sessionmaker(scoped_session(sessionmaker(bind=engine)))
# ...
-
-Pour passer une session globale, il suffit simplement que la fonction passée à :attr:`sqla_helpers.base_model.BaseModel.sessionmaker`
-renvoie la référence sur la session globale
+For a global session, the function set in :attr:`sqla_helpers.base_model.BaseModel.sessionmaker` should return
+a reference to a global session.
.. code-block:: python
from somwhere import DBSession
- # Initialisation de l'application
+ # Application's initialization
def main():
# ...
BaseModel.register_sessionmaker(lambda: DBSession)
# ...
-Cas d'utilisation simple :
+Basic use case :
.. code-block:: python
@@ -116,12 +108,11 @@ Cas d'utilisation simple :
[]
-* :meth:`sqla_helpers.base_model.BaseModel.all` ramène l'ensemble des objets en base.
-* :meth:`sqla_helpers.base_model.BaseModel.filter` ramène les objets correspondants aux critères donnés sous forme de liste.
-* :meth:`sqla_helpers.base_model.BaseModel.get` ramène un unique élément correspond aux critères données.
+* :meth:`sqla_helpers.base_model.BaseModel.all` returns all database objects
+* :meth:`sqla_helpers.base_model.BaseModel.filter` returns a list of matching objects.
+* :meth:`sqla_helpers.base_model.BaseModel.get` return an uniq maching object.
-On peut bien évidemment enchaîner les critères de recherche qui seront pris en
-compte avec un opérateur `&&` (ET) logique.
+Querying criterions can be chained with an `&&` (logical and) operator.
.. code-block:: python
@@ -131,81 +122,75 @@ compte avec un opérateur `&&` (ET) logique.
[<MyOtherModel object at 0x2c19d90>]
-Recherche sur critères de relation
-----------------------------------
+Querying for criterions on relations
+------------------------------------
-Les critères de recherche valides pour une classe sont définies par ses
-attributs (Pour MyOtherModel ça sera `id`, `name`, `model_id`).
+Valid quering criterions for a class ared definied by the class attributes.
+IE : in case of `MyOtherModel`, criterions can be `id`, `name` and `model_id`.
-Cela est également valable pour le relation SQLAlchemy.
+This still true for a Sqlachemy relation.
-Par exemple, on peut rechercher tous les MyModel dont le MyOtherModel a pour nom
-'toto'
+IE: quering all `MyModel` witch `MyOtherModel` have a name 'foo'.
.. code-block:: python
- >>> MyModel.filter(awesome_attr__name='toto')
+ >>> MyModel.filter(awesome_attr__name='foo')
[<MyModel object at 0x2c19d90>]
-On peut même rechercher suivant un objet complet.
+Quering a with entire object.
.. code-block:: python
- >>> otherModel = MyOtherModel.get(name='toto')
+ >>> otherModel = MyOtherModel.get(name='foo')
>>> MyModel.filter(awesome_attr=otherModel)
[<MyModel object at 0x2c19d90>]
-Le séparateur `__` (double underscore) permet de faire la séparation entre les
-différentes entités sollicitées.
+The `__` separator (double underscore) permits to split between the differents entities.
-La recherche par les attributs des relations peut se faire en profondeur.
-Imaginons que `MyOtherObject` est un attribut `other_attr` qui est en relation
-avec un objet MyOtherOtherObject.
+Quering with relation`s attributes can be recursive.
+If `MyOtherObject` have an `other_attr` attribute which is in relation with a `MyOtherOtherObject` object.
-Il est alors possible de rechercher tous les MyModel dont le MyOtherObject a un
-MyOtherOtherObject dont le nom est 'toto'.
+Quering all `MyModel` which a `MyOtherObject` has `MyOtherOtherObject` has a `name` attribute is 'foo'.
.. code-block:: python
- >>> MyModel.filter(awesome_attr__other_attr__name='toto')
+ >>> MyModel.filter(awesome_attr__other_attr__name='foo')
[<MyModel object at 0x2c19d90>]
-Des opérateurs
---------------
+Operators
+---------
-Il est possible de spécifier d'autres critères que ceux d'égalités. En séparant
-encore une fois, avec des '__' (doubles underscores) et en mettant le nom de
-l'opérateur à la fin du critère.
+Others criterions than equality can be used. These criterions sould be writen
+with the attribute name following '__' (double underscore) and name of the operator.
-Par exemple, si l'on veut tous les MyModel qui n'ont PAS pour id la valeur 2.
+IE: if all `MyModel` which `id` is different from 2 are wanted:
.. code-block:: python
>>> MyModel.filter(id__not=2)
[]
-Les opérateurs disponibles sont :
+Available operatores are:
-* 'not': Non-égal
-* 'lt': inférieur
-* 'le': Inférieur ou égal
-* 'gt': Plus grand
-* 'gte': Plus grand ou égal
-* 'in': Contenu dans (Le paramètre de recherche doit-être une liste)
-* 'like': opérateur SQL LIKE
-* 'ilike': opérateur SQL ILIKE
+* 'not': Non-equal,
+* 'lt': letter than,
+* 'le': letter or equals than,
+* 'gt': gretter than,
+* 'gte': gretter or equal than,
+* 'in': in a list,
+* 'like': SQL `LIKE` operator,
+* 'ilike': SQL `ILIKE` operator.
-Requêtes plus complexes
------------------------
+More complex quering
+--------------------
-Toujours sur le modèle de Django, :mod:`sqla_helpers` fournit un :class:`sqla_helpers.logical.Q` object afin de pouvoir réaliser des opération un peu plus complexes
-Le :class:`sqla_helpers.logical.Q` object est capable de prendre ne compte la
-syntaxe sqla_helpers.
+In the Django spirit, :mod:`sqla_helpers` provide a :class:`sqla_helpers.logical.Q` object for more complex quering.
+The :class:`sqla_helpers.logical.Q` object can use the :mod:`sqla_helpers' syntax.
.. code-block:: python
@@ -214,34 +199,34 @@ syntaxe sqla_helpers.
<sqla_helpers.logical.Q at 0x2376cd0>
-Ces objets sont transmissibles aux méthodes de recherches de la classe
+These objects are usable as criterions for query.
+
:class:`sqla_helpers.base_model.BaseModel`
.. code-block:: python
>>> Treatment.get(Q(id=2))
>>> <sqlalchemy_test.models.Treatment at 0x2388690>
-L'avantage de ces objets, c'est qu'ils permettent de décrire des conditions
-logiques SQL à travers une syntaxe python.
+The purpose of these objects is to permit SQL logical conditions in a python syntax.
-Si l'on veut les traitments qui ont pour id 2 OU le status à pour nom 'KO'
+If all `Treatment` objects which have an `id` == 2 or a `Status` name == 'KO' are wanted.
.. code-block:: python
>>> Treatment.filter(Q(id=2) | Q(status__name='KO'))
[<sqlalchemy_test.models.Treatment at 0x2388690>, <sqlalchemy_test.models.Treatment at 0x23837d0>]
-Si l'on veut tous les traitments qui n'ont pas pour id 2
+For getting, all `Treatment` objects with an `id' attribute different than 2 :
.. code-block:: python
>>> Treatment.filter(~Q(id=2))
[<sqlalchemy_test.models.Treatment at 0x2383450>, <sqlalchemy_test.models.Treatment at 0x23837d0>,
<sqlalchemy_test.models.Treatment at 0x23886d0> ]
-Mais on peut également enchainer les opérations logiques
+Logical operators can be chained :
.. code-block:: python
@@ -257,14 +242,13 @@ Mais on peut également enchainer les opérations logiques
>>> [<sqlalchemy_test.models.Treatment at 0x2388690>]
-Du JSON
--------
+JSON
+----
-Souvent dans les applications web, le client et le serveur communique par l'intermédiaire du format JSON.
-Pour faciliter les opérations de chargement, :mod:`sqla_helpers` fournit des
-méthodes permettant de charger des objets modèles depuis un dictionnaire python ou bien de générer un dictionnaire depuis un objet modèle SQLALchemy.
+Often in web oriented applications, client and server exchange with JSON format.
+In a purpose of easier loading, :mod:`sqla_helpers` furnish methods for loading from a regular python dictionary or a SQLAlchemy model object.
-La méthode :meth:`sqla_helpers.base_model.BaseModel.dump` permet la génération d'un dictionnaire qui est transformable en JSON.
+The :meth:`sqla_helpers.base_model.BaseModel.dump` method permit a JSON compatible dictionnary.
.. code-block:: python
@@ -280,12 +264,11 @@ La méthode :meth:`sqla_helpers.base_model.BaseModel.dump` permet la génératio
}
-Et la méthode de classe `sqla_helpers.base_model.BaseModel.load` qui permet d'instancier des objets à partir d'un dictionnaire.
-Le passage par dictionnaire est sensé faciliter l'accès aux données en JSON ou bien générer du JSON depuis le
-dictionnaire.
+The method `sqla_helpers.base_model.BaseModel.load` can construct object from a dictionnary.
+The meaning of use a dictionnary is to facillitate access to data in JSON or generate JSON frpm dictionnary.
-Pour le chargement d'un objet, les objets sont récupérés en base si les attributs composant la clef primaire
-sont trouvés dans le dictionnaire. Sinon, une nouvelle instance est créée.
+Objects are getting from database if primary key attributes are found on the dictionnary. Otherwise new object
+are created.
.. code-block:: python
@@ -295,7 +278,7 @@ sont trouvés dans le dictionnaire. Sinon, une nouvelle instance est créée.
>>> t.id
7
>>> t.status.name
- 'Sacre status !'
+ 'Holy status !'
>>> t.status.id
7
>>> t = Treatment.load({'id': 7, 'name': 'hello'})
@@ -306,7 +289,7 @@ sont trouvés dans le dictionnaire. Sinon, une nouvelle instance est créée.
{
'id': 7,
'name': u'hello',
- 'status': {'id': 7, 'name': u'Sacre status !'},
+ 'status': {'id': 7, 'name': u'Holy status !'},
'status_id': 7
}
>>> tr = Treatment.load(t.dump())
@@ -318,10 +301,10 @@ sont trouvés dans le dictionnaire. Sinon, une nouvelle instance est créée.
{
'id': 7,
'name': u'hello',
- 'status': {'id': 7, 'name': u'Sacre status !'},
+ 'status': {'id': 7, 'name': u'Holy status !'},
'status_id': 7
}
- >>> tr = Treatment.load({'name': 'nouveau traitmente', 'status': {'name': 'nouveau status'}})
+ >>> tr = Treatment.load({'name': 'new treatment', 'status': {'name': 'new status'}})
>>> tr.id
None
>>> tr.status.id
@@ -334,7 +317,7 @@ sont trouvés dans le dictionnaire. Sinon, une nouvelle instance est créée.
8
-La classe :class:`sqla_helpers.base_model.BaseModel`
-====================================================
+:class:`sqla_helpers.base_model.BaseModel` class
+================================================
.. automodule:: sqla_helpers.base_model

0 comments on commit bafc751

Please sign in to comment.