Le livre de

Que se passe-t’il lorsque vous enregistrez ?

Lorsque vous sauvegardez un objet, Django effectue les étapes suivantes:

1. Emission d’un signal pre_save. Ceci notifie qu’un objet est sur le point d’être enregistré. Vous pouvez enregistrer un «listener» qui sera invoqué à chaque fois que ce signal est émis. Ces signaux sont toujours en développement et n’étaient pas documentés lorsque ce livre a été mlis sous presse; vérifiez la documentation en ligne pour les dernières évolutions.

2. Prétraitement des données. Chaque champ de l’objet est appelé à faire toute modification automatique des données dont le champ pourrait avoir besoin d’effectuer. La plupart des champs ne font pas de pré traitement - le champ de donnée est laissé en l’état. Le pré traitement est utilisé seulement sur les champs qui ont un comportement spécial, comme par exemple les champs de fichier.

3. Preparation des données pour la base de données. Chaque champs est interrogé pour fournit sa valeur courante dans un type de donnée qui peut être écrit dans la base de données.

   La plupart des champs ne nécessitent pas de préparation des données. Les types de données simples, comme les entiers ou les chaînes, sont «prêts à l’emploi» en tant qu’objets Python. Cependant, les types de données plus complexes demandent souvent quelque modification. Par exemple, DateFields utilise un objet Python datetime pour stocker les données. Les bases de données ne stockant pas les objets datetime, la valeur du champ doit être converti en une chaîne de date respectueuse de la norme ISO avant insertion dans la base de données.

4. Insertion des données dans la base de données. Les données prétraitées et préparées composent ensuite une instruction SQL pour une insertion dans la base de données.

5. Émission d’un signal post_save. Comme pour le signal pre_save, ceci est utilisé pour notifier qu’un objet a été suavegardé avec succès. Ces signaux ne sont eux aussi pas encore documentés.

Auto incrémentation des clefs primaires

Pour des raisons pratiques, à chaque modèle est affecté un champ de clef primaire auto incrémenté appelé id à moins que vous ne précisiez explicitement primary_key=True sur un champ. (consultez la section intitulée «Autofield» de l’annexe B).

Si votre modèle possède un AutoField, cette valeur auto incrémentée sera calculée et enregistrée en tant qu’attribut de votre objet lors du premier appel à save():

>>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b2.id     # Returns None, because b doesn't have an ID yet.
None

>>> b2.save()
>>> b2.id     # Returns the ID of your new object.
14

Il n’y a aucun moyen de dire quelle sera la valeur d’un ID avant d’appeler save(), parce que cette valeur est calculée par votre base de données, et non pas par Django.

Si un modèle présente un AutoField mais que vous voulez définir explicitement un nouvel ID pour l’objet lors de l’enregistrement, il suffit simplement de le définir explicitement avant la sauvegarde, plutot que de compter sur l’assignation automatique de l’ID:

>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id
3
>>> b3.save()
>>> b3.id
3

Si vous assignez manuellement les valeurs des clefs primaires automatique, assurez vous de ne pas utiliser des valeurs de clef primaires déjà existantes ! Si vous créez un nouvel objet avec une valeur de clef primaire explicite déjà existante en base de données, Django considérera que vous être en train de modifier l’enregistrement existant plutôt que d’en créer un nouveau.

Considérant 'Cheddar Talk', l’exemple précédent du blog, cet exemple écrasera l’enregistrement précédent dans la base de données:

>>> b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')
>>> b4.save()  # Overrides the previous blog with ID=3!

Spécifier explicitement les valeurs de clef primaire automatique est surtout utile pour la sauvegarde massive d’objet, lorsque vous serez en confiance vous n’aurez pas de collision de clef primaire.

Chaîner les filtres

Le résutlat de l’affinage d’un QuerySet est lui même un QuerySet, il est donc possible de les chaîner, par exemple:

>>> qs = Entry.objects.filter(headline__startswith='What')
>>> qs = qs..exclude(pub_date__gte=datetime.datetime.now())
>>> qs = qs.filter(pub_date__gte=datetime.datetime(2005, 1, 1))

Ce code prends pour QuerySet initial toutes les entrées de la base de données, ajoute un filtre, puis une exclusion, et enfin un autre filtre. Le résultat final est un QuerySet contenant toutes les entrées ayant une en-tête commençant par «What» qui ont été publiées entre le premier janvier 2005 et la date actuelle.

Il est important de remarquer que les QuerySets sont fainéant - le fait de créer un QueySet n’implqie pas un activité de la base de données. En fait, les trois ligne de code précédentes ne font aucun appels en base de données; vous pouvez chaîner des filtres ensembles toute la journée sans que Django ne lance de requête jusqu’à ce que le QuerySet ne soit évalué.

Vous pouvez évaluer un QuerySet selon n’importe laquelle des méthodes suivantes:

• En l’itérant: Un QuerySet est itérable, et execute ses requêtes en base de données lors de la première itération. Par exemple, le QuerySet qui suit n’est évalué que lorsqu’il est itéré dans la boucle for:

  qs = Entry.objects.filter(pub_date__year=2006)
  qs = qs.filter(headline__icontains="bill")
  for e in qs:
      print e.headline
  

  Cela affiche toutes les en-têtes de l’année 2006 qui contiennent «bill» mais n’effectue qu’une opération en base de données.

• En l’affichant: Un QuerySet est évalué lorsque vous appelez repr(). Ceci est une commodité de l’interpréteur interactif Python, vous pouvez donc voir immédiatement vos résultats lorsque vous utilisez l’API interactivement.

• En le segmentant: Comme cela est expliqué dans la section «Limiter les QuerySets» à venir, un QuerySet peut être segmenté en utilisant la syntaxe de segmentation de tableau en Python. Habituellement, segmenter un QuerySet renvoie un autre QuerySet (non évalué), mais Django executera la requête en base de données si vous utilisez le paramètre «step» de la syntaxe de segmentation.

• En le convertissant en liste: Vous pouvez forcer l’évaluation d’un QuerySet en appelant list(), par exemple:

  >>> entry_list = list(Entry.objects.all())
  

  Prenez averti, cependant, que cela peut engendrer une grosse surcharge de la mémoire, parce que Django chargera chaque élément de la liste en mémoire. À l’inverse, itérer un QuerySet ménagera votre base de données en ne chargeantles données et en n’instanciant les objets au fur et à mesure de vos besoins.

q1 = Entry.objects.filter(headline__startswith="What")
q2 = q1.exclude(pub_date__gte=datetime.now())
q3 = q1.filter(pub_date__gte=datetime.now())

Limiter les QuerySets

Utilisez la syntaxe Python de segmentation de tableau pour limiter votre QuerySet à un certain nombre de résultats. Ceci est équivalent aux clauses LIMIT et OFFSET du SQL.

Par exemple, ceci renvoie les cinq premières entrées (LIMIT 5):

>>> Entry.objects.all()[:5]

Ceci renvoie la sixième entrée et suivantes, jusqu’à la dixième (OFFSET 5 LIMIT 5):

>>> Entry.objects.all()[5:10]

Généralement, la segmentation d’un QuerySet renvoie un nouveau QuerySet - cela n’évalue pas la requête. Une exception à la règle se présente si vous utilisez le paramètre «step» de la syntaxe Pytohn de segmentation. Par exemple, ce code executera en fait la requête de façon à retourner une liste du deuxième objet parmis les dix premiers:

>>> Entry.objects.all()[:10:2]

Pour récupérer un unique objet plutot qu’une liste (par exemple, SELECT foo FROM bar LIMIT 1), utilisez un simple index au lieu d’un segment. Par exemple, ce code retourne la première Entry de la base de données, après avoir ordonné les entrées alphabétiquement selon l’en-tête:

>>> Entry.objects.order_by('headline')[0]

Ceci est à peu près équivalent au code suivant:

>>> Entry.objects.order_by('headline')[0:1].get()

Notez, cependant, que le premier lévera une IndexError alors que le second lévera un DoesNotExist si aucun objet correspond au critère donné.

Les méthodes de requête qui retournent de nouveaux QuerySets

Django fournit tout une gamme de méthode d’affinage d’un QuerySet qui modifie à la fois les types de résultats renvoyés par le QuerySet ou la manière dont sa requête SQL est executé. Ces méthodes sont décrites dans les sections qui suivent. Certaines de ces méthodes acceptent des arguments de recharche de champ, qui sont abordés en détail un peu plus tard.

>> Entry.objects.filter(pub_date__year=2005).order_by('-pub_date','headline')

>>> Entry.objects.order_by('?')

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith='Beatles')
[Beatles Blog]

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith='Beatles').values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles
news.'}]

>>> Blog.objects.values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles
news.'}],
>>> Blog.objects.values('id', 'name')
[{'id': 1, 'name': 'Beatles Blog'}]

>>> Entry.objects.dates('pub_date', 'year')
[datetime.datetime(2005, 1, 1)]

>>> Entry.objects.dates('pub_date', 'month')
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]

>>> Entry.objects.dates('pub_date', 'day')
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]

>>> Entry.objects.dates('pub_date', 'day', order='DESC')
[datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]

>>>
Entry.objects.filter(headline__contains='Lennon').dates('pub_date',
'day')
[datetime.datetime(2005, 3, 20)]

# Hits the database.
>>> e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
>>> b = e.blog

# Hits the database.
>>> e = Entry.objects.select_related().get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
>>> b = e.blog

class City(models.Model):
    # ...

class Person(models.Model):
    # ...
    hometown = models.ForeignKey(City)

class Book(models.Model):
    # ...
    author = models.ForeignKey(Person)

>>> b = Book.objects.select_related().get(id=4)
>>> p = b.author         # Doesn't hit the database.
>>> c = p.hometown       # Doesn't hit the database.

>>> b = Book.objects.get(id=4) # No select_related() in this example.
>>> p = b.author         # Hits the database.
>>> c = p.hometown       # Hits the database.

>>> Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})

>>> subq = 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
>>> Blog.objects.extra(select={'entry_count': subq})

>>> Entry.objects.extra(where=['id IN (3, 4, 5, 20)'])

>>> Entry.objects.extra(where=['headline=%s'], params=['Lennon'])

Entry.objects.extra(where=["headline='%s'" % name])

Entry.objects.extra(where=['headline=%s'], params=[name])

Les méthodes de QuerySet qui ne renvoient pas de QuerySets

Les méthodes de QuerySet suivantes évaluent le QuerySet et renvoient quelque chose d’autre qu’ un QuerySet - un objet unique, une valeur et ainsi de suite.

>>> Entry.objects.get(id='foo') # raises Entry.DoesNotExist

>>> from django.core.exceptions import ObjectDoesNotExist
>>> try:
...     e = Entry.objects.get(id=3)
...     b = Blog.objects.get(id=1)
... except ObjectDoesNotExist:
...     print "Either the entry or blog doesn't exist."

>>> p = Person(first_name="Bruce", last_name="Springsteen")
>>> p.save()

>>> p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

try:
    obj = Person.objects.get(first_name='John',
    last_name='Lennon')
except Person.DoesNotExist:
    obj = Person(first_name='John', last_name='Lennon',
    birthday=date(1940, 10, 9))
    obj.save()

obj, created = Person.objects.get_or_create(
    first_name = 'John',
    last_name  = 'Lennon',
    defaults   = {'birthday': date(1940, 10, 9)}
)

defaults = kwargs.pop('defaults', {})
params = dict([(k, v) for k, v in kwargs.items() if '__' not in k])
params.update(defaults)
obj = self.model(**params)
obj.save()

Foo.objects.get_or_create(
    defaults__exact = 'bar',
    defaults={'defaults': 'baz'}
)

# Returns the total number of entries in the database.
>>> Entry.objects.count()
4

# Returns the number of entries whose headline contains 'Lennon'
>>> Entry.objects.filter(headline__contains='Lennon').count()
1

>>> Blog.objects.in_bulk([1])
{1: Beatles Blog}
>>> Blog.objects.in_bulk([1, 2])
{1: Beatles Blog, 2: Cheddar Talk}
>>> Blog.objects.in_bulk([])
{}

>>> Entry.objects.latest('pub_date')

exact

Exécute une correspondance exacte:

>>> Entry.objects.get(headline__exact="Man bites dog")

Ce code retrouve tout objet dont le titre est exactement «Man bites dog». Si vous ne fournissez pas un type de recherche - autrement dit, si votre argument mot-clef ne contient pas de double soulignement - le type de recherche est considéré comme étant exact.

Par exemple, les deux instructions suivantes sont équivalentes:

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied

Cela par commodité, puisque les recherches exact sont les plus courantes.

iexact

Exécute une coorespondance exacte insensible à la casse:

>>> Blog.objects.get(name__iexact='beatles blog')

Elle retrouvera 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG', et ainsi de suite.

contains

Test un contenu sensible à la casse:

Entry.objects.get(headline__contains='Lennon')

Elle remontera le titre 'Today Lennon honored' mais pas 'today lennon honored'.

SQLite ne supporte pas les instructions LIKE sensibles à la casse; lorsque vous utilisez SQLite, contains agit comme icontains.

Entry.objects.filter(headline__contains='%')

SELECT ... WHERE headline LIKE '%\%%';

icontains

Test un contenu insensible à la casse:

>>> Entry.objects.get(headline__icontains='Lennon')

Contrairement à contains, icontains remontera 'today lennon honored'.

gt, gte, lt, et lte

Ils représentent les caractères supérieur à, supérieur ou égal à, inférieur, et inférieur ou égal à:

>>> Entry.objects.filter(id__gt=4)
>>> Entry.objects.filter(id__lt=15)
>>> Entry.objects.filter(id__gte=0)

Ces requêtes renvoient tout objet dont l’ID est supérieur à 4, dont l’ID est inférieur à 15, et dont l’ID est supérieur ou égal à 1, respectivement.

Vous les utiliserez généralement sur des champs numériques. Soyez attentif avec les champs de caractère puisque l’ordre des caractères n’est pas toujours celui que vous pourriez attendre (c’est à dire que la chaîne «4» sort après la chaîne «10»).

in

Filtre selon les valeurs d’une liste donnée:

Entry.objects.filter(id__in=[1, 3, 4])

Ce code retourne tous les objets ayant l’ID 1, 3, ou 4.

startswith

Exécute un «commence par» insensible à la casse:

>>> Entry.objects.filter(headline__startswith='Will')

Ceci retournera les titres «Will he run ?» et «Willbur named judge», mais pas «Who is Will ?» ou «will found in crypt».

istartswith

Exécute un «commence par» insensible à la casse:

>>> Entry.objects.filter(headline__istartswith='will')

Ceci retournera les titres «Will he run ?», «Willbur named judge», et «will found in crypt», mais pas «Who is Will ?».

endswith et iendswith

Exécute un «se termine par» sensible et insensible à la casse:

>>> Entry.objects.filter(headline__endswith='cats')
>>> Entry.objects.filter(headline__iendswith='cats')

range

Exécute un contrôle de gamme inclusif:

::

>>> start_date = datetime.date(2005, 1, 1)
>>> end_date = datetime.date(2005, 3, 31)
>>> Entry.objects.filter(pub_date__range=(start_date, end_date))

Vous pouvez utilisez range là ou vous pouvez utiliser BETWEEN en SQL - pour les dates, les nombres, et même les caractères.

année, mois et jour

Pour les champs date/datetime, exécute une correspodance exacte sur l’année, le mois ou le jour:

# Recherche sur l'année
>>>Entry.objects.filter(pub_date__year=2005)

# Recherche sur le mois -- accepte les entiers
>>> Entry.objects.filter(pub_date__month=12)

# Recherche sur le jour
>>> Entry.objects.filter(pub_date__day=3)

# Combinaison: renvoie toutes les entrées de Noël pour n'importe quelle année
>>> Entry.objects.filter(pub_date__month=12, pub_date_day=25)

isnull

Accepte soit True ou False, ce qui correspond aux requêtes SQL de IS NULL et IS NOT NULL, respectivement:

>>> Entry.objects.filter(pub_date__isnull=True)

search

Une recherche Booléenne plein text qui tire partie de l’indexation . C’est identique à contains mais reste significativement plus rapide grâce à l’indexation plein texte.

Notez qui ceci est disponible uniquement pour MySQL et nécessite une manipulation directe de la base de donnée pour ajouter l’indexation plein texte.

Le raccourcis de recherche pk

Par commodité, Django fournit un type de recherche pk, pk correspondant à «primary_key» (clef primaire).

Dans l’exemple de modèle Blog, la clef primaire est le champ id, ces trois instructions sont donc équivalentes:

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied
>>> Blog.objects.get(pk=14) # pk implies id__exact

L’usage de pk n’est pas limité aux requêtes __exact - n’importe quel terme de requête peut être combiné avec pk pour effectuer une requête sur la clef primaire d’un modèle:

# Get blogs entries  with id 1, 4, and 7
>>> Blog.objects.filter(pk__in=[1,4,7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)

les recherches pk fonctionnent aussi sur les jointures. Par exemple, ces trois instrctions sont équivalentes:

>>> Entry.objects.filter(blog__id__exact=3) # Explicit form
>>> Entry.objects.filter(blog__id=3) # __exact is implied
>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact

Recherches étendue aux relations

Django offre une manière puissante et intuitive de «suivre» les relations au sein des recherches, en prenant automatiquement soin en coulisses du JOIN SQL à votre place. Pour étendre une relation, utilisez simplement le nom des champs liés parmis les modèles, séparés par des doubles soulignements, jusqu’à ce que vous obteniez le champ que vous désirez.

Cet exemple récupère tous les objets Entry du Blog dont le nom est Beatles Blog:

>>> Entry.objects.filter(blog__name__exact='Beatles Blog')

Cette étendue peut être aussi profonde que vous le désirez.

Cela fonctionne aussi à rebour. Pour «remonter» dans une relation, utilisez simplement le nom du modèle en bas de casse.

Cet exemple récupère tous les objets Blog qui ont au moin une Entry dont le titre contient 'Lennon':

>>> Blog.objects.filter(entry__headline__contains='Lennon')

Relations entre clefs étrangères

Si un modèle possède une ForeignKey, les instances de ce modèles auront accès au objets (étrangers) liés via un simple attribut de modèle, par exemple:

e = Entry.objects.get(id=2)
e.blog # Returns the related Blog object.

Vous pouvez utiliser «get» et «set» via un attribut de clef étrangère . Comme vous pouvez vous y attendre, les modifications apportées à la clef étrangère ne sont pas enregistré dans la base de données avant que vous n’appeliez save(), par exemple:

e = Entry.objects.get(id=2)
e.blog = some_blog
e.save()

Si un champ ForeignKey a un null=True initialisé (c’est à dire qu’il autorise les valeurs NULL), vous pouvez lui assigner None:

e = Entry.objects.get(id=2)
e.blog = None
e.save() # "UPDATE blog_entry SET blog_id = NULL ...;"

L’accès descendant aux relations un-à-plusieurs est mis en cache lors du premier accès à l’objet lié. Les accès ultérieurs à la clef étrangère d’une même instance d’objet sont mis en cache, par exemple:

e = Entry.objects.get(id=2)
print e.blog  # Hits the database to retrieve the associated Blog.
print e.blog  # Doesn't hit the database; uses cached version.

Notez que la méthode select_related du QuerySet garnit récursivement le cache de toutes les relations un-à-plusieurs à l’avance:

e = Entry.objects.select_related().get(id=2)
print e.blog  # Doesn't hit the database; uses cached version.
print e.blog  # Doesn't hit the database; uses cached version.

select_related() est documentée dans la section «Méthodes du QuerySet qui retournent un nouveau QuerySet»

Relations inverses des clefs étrangères

Les relations de clefs étrangères sont automatiquement symétriques - une relation inverse est déduite de la présence d’une ForeignKey pointant sur un autre modèle.

Si un modèle possède une ForeignKey, les instances de clef étrangère du modèle aurons accès à un Manager qui retournera toutes les instances du premier modèle. Par défaut, ce Manager est appelé FOO_set, où FOO est le nom du modèle source, converti en bas de casse. Ce Manager retourne les QuerySets, qui peuvent filtrés et manipulés comme décrit dans la section «Récupérer des objets».

Voici un exemple:

b = Blog.objects.get(id=1)
b.entry_set.all() # Returns all Entry objects related to Blog.

# b.entry_set is a Manager that returns QuerySets.
b.entry_set.filter(headline__contains='Lennon')
b.entry_set.count()

Vous pouvez outrepasser le nom du FOO_set en précisant le paramètre related_name dans la définition de ForeignKey(). Par exemple, si le modèle Entry à été modifié au profit de blog = ForeignKey(Blog, related_name='entries'), l’exemple de code précédent ressemblera à ceci:

b = Blog.objects.get(id=1)
b.entries.all() # Returns all Entry objects related to Blog.

# b.entries is a Manager that returns QuerySets.
b.entries.filter(headline__contains='Lennon')
b.entries.count()

Vous ne pouvez pas avoir accès à un Manager de ForeignKey inverse depuis la classe; il doit être accédé depuis une instance:

Blog.entry_set # Raises AttributeError: "Manager must be accessed via instance".

En complément des méthodes QuerySet définies dans la section «Récupérer des objets», le Manager de ForeignKey propose ces méthodes supplémentaires:

• add(obj1, obj2, ...): ajoute les objets du modèle spécifié au jeu de modèle lié, par exemple:

  b = Blog.objects.get(id=1)
  e = Entry.objects.get(id=234)
  b.entry_set.add(e) # Associates Entry e with Blog b.
  

• create(**kwargs): créé un nouvel objet, l’enregistre, et le place dans le jeu d’objet lié. Elle renvoie l’objet nouvellement créé:

  b = Blog.objects.get(id=1)
  e = b.entry_set.create(headline='Hello', body_text='Hi',
  pub_date=datetime.date(2005, 1, 1))
  # No need to call e.save() at this point -- it's already been
  saved.
  

  Cela équivaut (en beaucoup plus simple) au code suivant:

  b = Blog.objects.get(id=1)
  e = Entry(blog=b, headline='Hello', body_text='Hi',
  pub_date=datetime.date(2005, 1, 1))
  e.save()
  

  Notez qu’il n’y a pas besoin de préciser l’argument mot-clef du modèle qui définit la relation. Dans l’exemple précédent, nous ne transmettons pas le paramètre blog à create(). Django comprend que le nouveau champ Entry de l’objet blog doit prendre la valeur b.

• remove(obj1, obj2, ...): supprime les objets du modèle spécifié du jeu d’objet lié:

  b = Blog.objects.get(id=1)
  e = Entry.objects.get(id=234)
  b.entry_set.remove(e) # Disassociates Entry e from Blog b.
  

  De façon à prévenir des incohérence dans la base de données, cette méthode n’existe que pour les objets ForeignKey où null=True. Si le champ lié ne peut être fixé None (NULL), alors un objet ne peut être supprimé d’une relation sans avoir été ajouté à une autre. Dans l’exemple précédent, supprimer e de b.entry_set() équivaut à faire un e.blog = None, et puisque la ForeignKey du blog n’a pas de null=True, cela n’est pas valide.

• clear(): supprime tous les objets du jeu d’objet lié:

  b = Blog.objects.get(id=1)
  b.entry_set.clear()
  

  Notez que ceci n’efface pas les objets liés - il s’agit juste d’une dissociation.

  Tout comme remove(), clear() est disponible uniquement sur les ForeignKey où null=True.

Pour assigner les membres d’un jeu lié en une seule fois, assignez leurs simplement n’importe quel objet itérable, par exemple:

b = Blog.objects.get(id=1)
b.entry_set = [e1, e2]

Si la méthode clear() est diponible, tous les objets pré-existants seront supprimés de l’entry_set avant que tous les objets dans l’itérable (dans ce cas, une liste) soient ajoutés au jeu. Si la méthode clear() n’est pas disponible, tous les objets dans l’itérable seront ajouté sans supprimer les éléments existants.

Chaque opération «inverse» décrite dans cette section a un effet immédiat sur la base de données. Chaque ajout, création et suppression est immédiatement et automatiquement enregistré dans la base de données.

Relations plusieurs-à-plusieurs

Chaque terminaison d’une relation plusieurs-à-plusieurs ont automatiquement une API d’accès à l’autre. L’API fonctionne simplement comme une relation un-à-plusieur «inverse» (décrite dans la section précédente).

La seule différence se situe dans le nommage des attributs: le modèle qui défini le ManyToManyField utilise lui même le nom d’attribut de ce champ, alors que le modèle «inverse» utilise le nom du modèle converti en bas de casse du modèle d’origine, augmenté d’un '_set' (tout comme les relations un-à-plusieurs inverses).

Un exemple rends ce concept plus facile à comprendre:

e = Entry.objects.get(id=3)
e.authors.all() # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Returns all Entry objects for this Author.

Tout comme ForeignKey, ManyToManyField peut préciser un related_name. Dans l’exemple précédent, si le ManyToManyField dans Entry avait spécifiéa related_name='entries', alors chaque instance d’Author aurait eu un attribut entries à la place de entry_set.

Requêtes sur les objets liés

Les requêtes impliquant des objets liés suivent les mêmes règles que les requêtes impliquant des champs à valeur normale. En spécifiant la valeur auquel doit correspondre une requête, vous pouvez soit utiliser l’instance d’objet elle même ou la valeur de la clef primaire pour cet objet.

Par exemple, si vous avez un objet b de Blog avec un id=5, les trois requêtes suivantes seront identiques:

Entry.objects.filter(blog=b) # Query using object instance
Entry.objects.filter(blog=b.id) # Query using id from instance
Entry.objects.filter(blog=5) # Query using id directly

get_FOO_display()

Pour chaque champ qui proposant des choices, l’objet aura une méthode get_FOO_display(), où FOO est le nom du champ. Cette méthode renvoie la valeur «humainement lisible» du champ. Par exemple, dans le modèle suivant:

GENDER_CHOICES = (
    ('M', 'Male'),
    ('F', 'Female'),
)
class Person(models.Model):
    name = models.CharField(max_length=20)
    gender = models.CharField(max_length=1,
    choices=GENDER_CHOICES)

Chaque instance Person aura une méthode get_gender_display():

>>> p = Person(name='John', gender='M')
>>> p.save()
>>> p.gender
'M'
>>> p.get_gender_display()
'Male'

get_next_by_FOO(**kwargs) and get_previous_by_FOO(**kwargs)

Pour chaque DateField et chaque DateTimeField qui n’ont pas null=True, l’objet proposera les méthodes get_next_by_FOO() et get_previous_by_FOO(), où FOO est le nom du champ. Cela retourne l’objet précédent et l’objet suivant selon le champ de date, levant l’exception DoesNotExist appropriée si nécessaire.

Les deux méthodes acceptent des arguments mot-clef optionnels, qui doivent être au format décrit dans la section «Recherche de champ».

Notez que dans le cas de valeurs de date identiques, ces méthodes utiliserons en dernier recour l’ID pour contrôle. Ceci garantie qu’aucun enregistrement sera oublié ou dupliqué. Pour un exemple complet, consultez les exemples de l’API de recherche à l’adresse: http://www.djangoproject.com/documentation/0.96/models/lookup/.

get_FOO_filename()

Pour chaque FileField, l’objet aura une méthode get_FOO_filename() où FOO est le nom du champ. Ceci renvoie le chemin complet du système de fichier vers le fichier, conformément à votre paramètre MEDIA_ROOT.

Notez que ImageField est techniquement une sous classe de FileField, et qu’ainsi chaque modèle avec un ImageField aura aussi cette méthode.

get_FOO_url()

Pour chaque FileField, l’objet aura une méthode get_FOO_url(), où FOO est le nom du champ. Elle renvoie l’url complet du fichier, conformement à votre paramètre MEDIA_URL. Si la valeur est vide, cette méthode retourne une chaîne vide.

get_FOO_size()

Pour chaque FileField, l’objet aura une méthode get_FOO_size(), où FOO est le nom du champ. Elle renvoie la taille du fichier, en octets. (En coulisses, elle utilise os.path.getsize).

save_FOO_file(filename, raw_contents)

Pour chaque FileField, l’objet aura une méthode save_FOO_file(), où FOO est le nom du champ. Cela enregistre le fichier donné sur le système de fichier, en utilisant le nom de fichier précisé. Si un fichier du même nom existe déjà, Django ajoute un soulignement à la fin du nom de fichier (mais avant l’extension) jusqu’à ce que le nom de fichier soit disponible.

get_FOO_height() et get_FOO_width()

Pour chaque ImageField, l’objet aura les méthodes get_FOO_height() et get_FOO_width(), où FOO est le nom du champ. Elles retournent la largeur (ou la hauteur) de l’image, sous forme d’entier, en pixels.

get_object_or_404()

Un idiome courant est d’utiliser get() et de lever un Http404 si l’objet n’existe pas. Cette idiome est résumé par get_object_or_404(). Cette fonction prends un modèle Django pour premier argument et un nombre arbitraire d’arguments mot-clef, qui sont transmis à la fonction get() du manager par défaut. Il lève un Http404 si l’objet n’existe pas, par exemple:

# Get the Entry with a primary key of 3
e = get_object_or_404(Entry, pk=3)

Lorsque vous fournissez un modèle à cette fonction faisant office de raccourci, le manager par défaut est utilisé pour exécuter la requête get() sous jacente. Si vous ne voulez pas utiliser le manager par défaut, ou si vous voulez rechercher une liste d’objets liés, vous pouvez proposer get_objet_or_404() avec un objet Manager à la place:

# Get the author of blog instance e with a name of 'Fred'
a = get_object_or_404(e.authors, name='Fred')

# Use a custom manager 'recent_entries' in the search for an
# entry with a primary key of 3
e = get_object_or_404(Entry.recent_entries, pk=3)

get_list_or_404()

get_list_or_404 agit de la même façon que get_object_or_404(), sauf qu’elle utilise filter() à la place de get(). Elle lève un Http404 si la liste est vide.