Opened 4 years ago

Last modified 4 years ago

#17007 new New feature

Fixture documentation should include non-numeric PK information

Reported by: Tim Chase <django.ticket@…> Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords: fixture, initial data
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The documentation at https://docs.djangoproject.com/en/dev/howto/initial-data/#providing-initial-data-with-fixtures only describes the general/default case where the PK/id is numeric. It would be nice to include documentation for the cases where this is non-numeric. E.g

class MyModel(Model):
  id = CharField(primary=True, max_length=3)
  desc = CharField(max_length=50)

The fixture should be

[
{"pk": "BLU",
 "model": "myapp.mymodel",
 "fields": {"description": "Blue"}
}
]

instead of

[
{"pk": 0,
 "model": "myapp.mymodel",
 "fields": {"id"="BLU", "description": "Blue"}
}
]

I had to figure this out through trial & error, and documenting it here may save others the trouble.

Change History (3)

comment:1 Changed 4 years ago by aaugustin

  • Easy pickings unset
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

Django special-cases the primary key field in the models because it's the identifier of each instance. This implementation detail shows up in the serialization format.

As mentioned at the beginning of the page you link to, the canonical way of creating fixtures is dumpdata. However, a quick explanation of the serialization format couldn't hurt. I think it should go in the serialization docs, not in the initial data howto.

In short, I'd say that each instance is represented by a dictionary with three keys:

  • "model" => the name of the model, including the application label,
  • "pk" => the value of primary key of the instance,
  • "fields" => a dictionary of the values of the other fields of the instance.

comment:2 Changed 4 years ago by Tim Chase <django.ticket@…>

Part of the complication is the behind-the-scenes twiddling that Django does between named fields and the automatically-generated "pk" field. Something like your "whatever is declared as the primary key is stored under 'pk' regardless of the field's actual name, and everything else is stored in 'fields'" text makes it pretty clear. While mucking in this section of the docs, it might be nice to explicitly mention that the model-name is lower-cased (something that can be inferred from the examples, but not explicitly stated like it is in the the initial-SQL section).

I don't feel strongly regarding where the documentation resides (whether at my link or your suggestion of the serialization docs) as long as there's commentary/linking between the locations.

comment:3 Changed 4 years ago by aaugustin

In fact, pk is just an alias for the primary key field. The new text could link to https://docs.djangoproject.com/en/dev/topics/db/queries/#the-pk-lookup-shortcut.

Note: See TracTickets for help on using tickets.
Back to Top