Référence des instances de modèlesLien vers cette rubrique#

Personnalisation du chargement des modèlesLien vers cette rubrique#

classmethod Model.from_db(db, field_names, values)Lien vers cette définition#

La méthode from_db() peut être utilisée pour personnaliser la création des instances de modèles lors de leur chargement à partir de la base de données.

Le paramètre db contient l’alias de la base de données à partir de laquelle le modèle est chargé, field_names contient les noms de tous les champs chargés et values contient les valeurs chargées pour chaque champ de field_names. L’ordre des champs dans field_names est le même que dans values. Si tous les champs du modèle sont présents, values est toujours dans l’ordre attendu par __init__(). Cela signifie que l’instance peut être créée par cls(*values). Si certains champs sont différés, ils n’apparaissent pas dans field_names. Dans ce cas, attribuez une valeur django.db.models.DEFERRED à chacun des champs manquants.

En plus de créer le nouveau modèle, la méthode from_db() doit définir les drapeaux adding et db de l’attribut _state de la nouvelle instance.

Dans l’exemple ci-dessous, on voit comment mémoriser les valeurs des champs telles que chargées à partir de la base de données :

from django.db.models import DEFERRED


@classmethod
def from_db(cls, db, field_names, values):
    # Default implementation of from_db() (subject to change and could
    # be replaced with super()).
    if len(values) != len(cls._meta.concrete_fields):
        values = list(values)
        values.reverse()
        values = [
            values.pop() if f.attname in field_names else DEFERRED
            for f in cls._meta.concrete_fields
        ]
    instance = cls(*values)
    instance._state.adding = False
    instance._state.db = db
    # customization to store the original field values on the instance
    instance._loaded_values = dict(
        zip(field_names, (value for value in values if value is not DEFERRED))
    )
    return instance


def save(self, **kwargs):
    # Check how the current values differ from ._loaded_values. For example,
    # prevent changing the creator_id of the model. (This example doesn't
    # support cases where 'creator_id' is deferred).
    if not self._state.adding and (
        self.creator_id != self._loaded_values["creator_id"]
    ):
        raise ValueError("Updating the value of creator isn't allowed")
    super().save(**kwargs)

L’exemple ci-dessus montre une implémentation complète de from_db() pour clarifier son fonctionnement. Dans ce cas, il aurait été possible de faire appel à super() dans la méthode from_db().

Incrémentation automatique des clés primairesLien vers cette rubrique#

Si un modèle contient un champ AutoField – une clé primaire avec incrémentation automatique – la valeur incrémentée automatiquement sera calculée et enregistrée comme attribut de l’objet lors de son premier enregistrement avec save():

>>> b2 = Blog(name="Cheddar Talk", tagline="Thoughts on cheese.")
>>> b2.id  # Returns None, because b2 doesn't have an ID yet.
>>> b2.save()
>>> b2.id  # Returns the ID of your new object.

Il n’est pas possible de connaître la valeur future de l’identifiant avant d’appeler save(), car cette valeur est calculée par la base de données, et non par Django.

Par commodité, chaque modèle possède par défaut un champ AutoField nommé id, sauf dans le cas où vous ajoutez explicitement le paramètre primary_key=True à l’un des champs du modèle. Consultez la documentation de AutoField pour plus de détails.

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

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

Que se passe-t-il lors de l’enregistrement ?Lien vers cette rubrique#

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

1. Émission d’un signal avant enregistrement. Le signal django.db.models.signals.pre_save est envoyé, permettant à toute fonction à l’écoute de ce signal d’accomplir une action.

2. Préparation des données. La méthode pre_save() de chaque champ est appelée pour effectuer toute éventuelle modification automatique de données. Par exemple, les champs date/heure surchargent pre_save() pour implémenter auto_now_add et auto_now.

3. Préparation des données pour la base de données. La méthode get_db_prep_save() de chaque champ doit fournir sa valeur actuelle dans un type de données qui peut être écrit dans la base de données.

   La plupart des champs ne nécessitent aucune préparation de données. Les types de données simples, comme les entiers ou les chaînes de caractères, sont « prêtes à l’écriture » en tant qu’objet Python. Cependant, les types de données plus complexes ont souvent besoin de certaines modifications.

   Par exemple, les champs DateField utilisent un objet Python datetime pour stocker leurs données. Les bases de données ne peuvent pas stocker d’objet datetime, il faut donc que la valeur du champ soit convertie dans une chaîne date au format ISO pour être insérée 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 sont converties en instruction SQL en vue de leur insertion dans la base de données.

5. Émission d’un signal après enregistrement. Le signal django.db.models.signals.post_save est envoyé, permettant à toute fonction à l’écoute de ce signal d’accomplir une action.

Comment Django distingue UPDATE de INSERTLien vers cette rubrique#

Vous avez peut-être remarqué que les objets de base de données de Django utilisent la même méthode save() pour créer ou modifier des objets. La couche d’abstraction de Django évite de devoir différencier les instructions SQL INSERT ou UPDATE. Plus concrètement, lors de l’appel à save() et que l’attribut clé primaire de l’objet ne définit pas de valeur default ou db_default, Django suit l’algorithme suivant :

• Si l’attribut de clé primaire de l’objet est défini à tout autre chose que None, Django exécute une instruction UPDATE.

• Si l’attribut de clé primaire de l’objet n’est pas défini où si l’instruction UPDATE n’a rien mis à jour (par ex. si la clé primaire est définie à une valeur qui n’existe pas en base de données), Django exécute une requête INSERT.

Si l’attribut clé primaire de l’objet définit une valeur par défaut default ou db_default, Django exécute une instruction UPDATE s’il s’agit d’une instance de modèle existante et que sa clé primaire est définie à une valeur qui existe dans la base de données. Sinon, Django exécute une instruction INSERT.

Le point délicat ici est de faire attention à ne pas indiquer explicitement de valeur de clé primaire lors de l’enregistrement de nouveaux objets, si vous ne pouvez garantir que cette clé primaire est libre. Pour plus de détails sur cette nuance, consultez Définition explicite des valeurs de clés primaires ci-dessus et Contrainte d’insertion ou de mise à jour ci-dessous.

Jusqu’à Django 1.5, Django faisait un SELECT lorsque l’attribut de clé primaire était défini. Si le SELECT trouvait un objet, Django effectuait ensuite un UPDATE, sinon il procédait à un INSERT. Cet ancien algorithme produisait une requête supplémentaire dans le cas UPDATE. Il peut arriver dans certains cas que la base de données ne signale pas qu’une ligne a été mise à jour même quand il existe une ligne de base de données correspondant à la clé primaire de l’objet. Un exemple est le déclencheur ON UPDATE de PostgreSQL qui renvoie NULL. Dans de tels cas, il est possible de revenir à l’algorithme précédent en définissant l’option select_on_save à True.

Restaurant(pk=1, name="Bob's Cafe").save(force_insert=(Place,))

Restaurant(pk=1, name="Bob's Cafe", rating=4).save(force_insert=(Place, Rating))

Mise à jour d’attributs basés sur des champs existantsLien vers cette rubrique#

Il est parfois nécessaire d’effectuer une tâche arithmétique simple sur un champ, comme l’incrémentation ou la décrémentation de la valeur actuelle. Une façon de faire cela serait d’effectuer l’arithmétique en Python comme ceci :

>>> product = Product.objects.get(name="Venezuelan Beaver Cheese")
>>> product.number_sold += 1
>>> product.save()

Si la valeur number_sold existante dans la base de données est 10, c’est la valeur 11 qui sera écrite comme nouvelle valeur en base de données.

The process can be made robust, avoiding a race condition, as well as slightly faster by expressing the update relative to the original field value, rather than as an explicit assignment of a new value. Django provides Expressions F() for performing this kind of relative update. Using Expressions F(), the previous example is expressed as:

>>> from django.db.models import F
>>> product = Product.objects.get(name="Venezuelan Beaver Cheese")
>>> product.number_sold = F("number_sold") + 1
>>> product.save()

For more details, see the documentation on Expressions F() and their use in update queries.

Indication des champs à enregistrerLien vers cette rubrique#

En transmettant une liste de noms de champs dans le paramètre update_fields de save(), seuls les champs figurant dans cette liste sont mis à jour. Cela peut être judicieux lorsque un petit sous-ensemble des champs d’un objet doivent être mis à jour. Un léger gain de performances peut être espéré en évitant de mettre à jour tous les champs du modèle en base de données. Par exemple :

product.name = "Name changed again"
product.save(update_fields=["name"])

Le paramètre update_fields peut être n’importe quel objet itérable contenant des chaînes de caractères. Si ce dernier est vide, l’enregistrement n’a pas lieu. La valeur None provoque la mise à jour de tous les champs.

L’utilisation de update_fields force une mise à jour.

Lors de l’enregistrement d’un modèle obtenu par chargement différé de modèle (only() ou defer()), seuls les champs chargés à partir de la base de données sont mis à jour. Dans ce cas, l’effet est semblable à un update_fields automatique. Si vous attribuez ou que vous modifiez l’une des valeurs de champ différé, le champ est ajouté aux champs à mettre à jour.

__str__()Lien vers cette rubrique#

Model.__str__()Lien vers cette définition#

La méthode __str__() est appelée chaque fois que str() est appelée sur un objet. Django utilise str(obj) à plusieurs occasions. Plus particulièrement, pour afficher un objet dans le site d’administration de Django et pour produire la valeur insérée dans un gabarit lors de l’affichage d’un objet. Il est donc important de toujours renvoyer une représentation utile et intelligible du modèle en réponse à la méthode __str__().

Par exemple :

from django.db import models


class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)

    def __str__(self):
        return f"{self.first_name} {self.last_name}"

__eq__()Lien vers cette rubrique#

Model.__eq__()Lien vers cette définition#

La méthode d’égalité est définie telle que des instances avec la même valeur de clé primaire et la même classe concrète sont considérées comme égales, sauf pour les instances dont la valeur de clé primaire est None qui ne sont toujours égales qu’à elles-mêmes. Pour les modèles mandataires, la classe concrète est définie comme le premier parent non mandataire du modèle ; pour tous les autres modèles, c’est simplement la classe du modèle.

Par exemple :

from django.db import models


class MyModel(models.Model):
    id = models.AutoField(primary_key=True)


class MyProxyModel(MyModel):
    class Meta:
        proxy = True


class MultitableInherited(MyModel):
    pass


# Primary keys compared
MyModel(id=1) == MyModel(id=1)
MyModel(id=1) != MyModel(id=2)
# Primary keys are None
MyModel(id=None) != MyModel(id=None)
# Same instance
instance = MyModel(id=None)
instance == instance
# Proxy model
MyModel(id=1) == MyProxyModel(id=1)
# Multi-table inheritance
MyModel(id=1) != MultitableInherited(id=1)

__hash__()Lien vers cette rubrique#

Model.__hash__()Lien vers cette définition#

The __hash__() method is based on the instance’s primary key value. It is effectively hash(obj.pk). If the instance doesn’t have a primary key value then a TypeError will be raised (otherwise the __hash__() method would return different values before and after the instance is saved), but changing the __hash__() value of an instance is forbidden in Python.

get_absolute_url()Lien vers cette rubrique#

Model.get_absolute_url()Lien vers cette définition#

Définissez une méthode get_absolute_url() pour indiquer à Django la façon de calculer l’URL canonique d’un objet. Pour l’appelant, cette méthode doit renvoyer une chaîne pouvant être utilisée pour se référer à un objet par HTTP.

Par exemple :

def get_absolute_url(self):
    return "/people/%i/" % self.id

While this code is correct and simple, it may not be the most portable way to write this kind of method. The reverse() function is usually the best approach.

Par exemple :

def get_absolute_url(self):
    from django.urls import reverse

    return reverse("people-detail", kwargs={"pk": self.pk})

Un endroit où Django utilise get_absolute_url() est l’application d’administration. Si un objet définit cette méthode, la page d’édition d’objet présentera un lien « Voir sur le site » qui vous amène directement sur la page d’affichage public de l’objet, telle qu’indiquée par get_absolute_url().

De même, certaines autres parties de Django, comme le système de flux de syndication, utilisent get_absolute_url() lorsqu’elle est définie. Si le fait de posséder une URL unique pour chaque instance de modèle fait sens, vous devriez définir get_absolute_url().

L’utilisation de get_absolute_url() dans les gabarits est reconnu comme une bonne pratique, au lieu de figer les URL des objets à des chaînes fixes. Par exemple, ce code de gabarit est mauvais :

<!-- BAD template code. Avoid! -->
<a href="/people/{{ object.id }}/">{{ object.name }}</a>

Ce code de gabarit est bien meilleur :

<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>

Ici, la logique est que si vous modifiez la structure des URL de vos objets, même s’il ne s’agissait que d’une petite correction orthographique, il n’est pas acceptable de devoir rechercher tous les endroits où l’URL en question pourrait être écrite. On la définit une seule fois dans get_absolute_url() et tous les autres endroits du code peuvent alors référencer cette méthode.

_stateLien vers cette rubrique#

Model._stateLien vers cette définition#

L’attribut _state fait référence à un objet ModelState qui suit le cycle de vie de l’instance du modèle.

The ModelState object has three attributes: adding, a flag which is True if the model has not been saved to the database yet, db, a string referring to the database alias the instance was loaded from or saved to, and fetch_mode, the fetch mode to be used in subsequent field fetches.

Newly instantiated instances have adding=True and db=None, since they are yet to be saved, and fetch_mode=models.FETCH_ONE. Instances fetched from a QuerySet will have adding=False, db set to the alias of the associated database, and fetch_mode copied from the queryset’s fetch mode.

_is_pk_set()Lien vers cette rubrique#

Model._is_pk_set()Lien vers cette définition#

The _is_pk_set() method returns whether the model instance’s pk is set. It abstracts the model’s primary key definition, ensuring consistent behavior regardless of the specific pk configuration. A DatabaseDefault on an unsaved instance is considered unset.