Skip to content

2.0.0

Choose a tag to compare

@Dresdn Dresdn released this 16 Oct 23:30

Breaking Changes

  • EAV2_PRIMARY_KEY_FIELD accepts only django.db.models.BigAutoField (the default) and django.db.models.UUIDField. django.db.models.CharField, django.db.models.AutoField and any other value now raise ImproperlyConfigured instead of being ignored. A CharField key never worked on its own, because nothing generates the ids; it only existed as the middle step of a conversion described in the README.
  • Migrations 0001 and 0010 use the configured key type, so a new project with UUIDField gets UUID keys from its first migrate; this fixes cannot cast type bigint to uuid on PostgreSQL (#455). Existing databases are unaffected. The README's two-step conversion, which generated migration files inside the installed package, is gone: converting the keys of existing tables is not supported.
  • order_by("eav__<enum attribute>") now sorts by the text of the choice, so it does not depend on how the database orders keys. It used to sort by the choice's id.

Deprecations

  • The json, csv, and object attribute datatypes are deprecated and django-eav2 3.0 removes them, along with their value columns. Saving an attribute of one of these types, or writing a value to one (including bulk_create() and bulk_update()), emits eav.exceptions.RemovedInEav3Warning, a FutureWarning that points at your own code. Use a JSONField, a ForeignKey, a ManyToManyField, or a related model on your own model instead, and move existing data out of EAV before 3.0. If you have a use case that those do not cover, open an issue.

Performance

  • instance.eav.<slug> loads an entity's attributes and values once and reuses them, so reading three attributes takes 2 queries instead of 6. The values are held in the instance's prefetch_related cache, so refresh_from_db() and save() clear them; use instance.eav.clear_cache() after changing values elsewhere.
  • Saving an entity loads its attributes and values once and writes only assigned values: creating an entity with three attributes takes 6 queries instead of 39, and saving one changed attribute takes 4 instead of 11.
  • prefetch_related("eav_values__attribute") is now used when reading attributes, and entities from one queryset (including .iterator()) share a single attribute lookup. Reading one attribute across 10 prefetched entities takes 3 queries instead of 23.
  • EavConfig.cache_values = False turns the value cache off for a model, so every read queries the database. Use it, or instance.eav.clear_cache(), when values are written outside instance.eav and save(), such as with Value.objects.bulk_create: cached reads do not see those writes.
  • New Attribute.store_value, Value.save_checked, Entity.clear_cache and EavConfig.shares_attributes; Attribute.save_value keeps its behaviour.
  • Migration 0013 adds indexes on (attribute, value_int), (attribute, value_float), (attribute, value_date) and (attribute, value_enum), so filters such as eav__age__gt=5 and eav__score=500 read the matching rows instead of every value of the attribute. On a table of 500,000 values an equality filter took 0.3 ms instead of 6.5 ms and a range filter 7 ms instead of 13 ms. Text values are not indexed.

Features

  • bulk_create() and bulk_update() on EAV managers store EAV values in about one query per 1000 rows instead of one or more per entity: Patient.objects.bulk_create(patients) writes the values assigned with patient.eav.<slug> = ..., and bulk_update(patients, ["name", "eav__age"]) updates them. Instances are validated first, written in chunks inside one transaction, and no signals are sent. Creating entities needs primary keys, so integer keys are not supported on MySQL.
  • EavConfig.bulk_batch_size (1000 by default) sets how many entities bulk_create() and bulk_update() write at a time; the batch_size argument overrides it.
  • Attribute.enum_choices, Attribute.validate_assignment, Entity.assigned_values and Value.clean_own_fields. Saving an enum attribute no longer queries the choices more than once.

Bug Fixes

  • ~Q() on an attribute inside a larger Q removes whole entities, as exclude() does. It used to negate single value rows, so filter(Q(eav__age__gt=30) & ~Q(eav__city="Nice")) could return entities that live in Nice. Every condition on an attribute, in a Q or as a keyword argument, is now an independent EXISTS subquery, which also stops OR conditions from returning an entity more than once.
  • eav__<slug>__isnull=True finds the entities that have no value for the attribute. It used to find nothing.
  • Lookups chained after an attribute slug, such as eav__born__year__gt=2000 or eav__extras__chills__iexact="yes", are applied. They used to be dropped, which returned no rows.
  • filter() no longer changes the Q objects you pass to it, so you can reuse them, and a Q that contains an expression such as Exists(...) no longer fails.
  • A lookup other than equality on an object attribute raises FieldError. It used to be ignored, which returned wrong rows.
  • Unregistering a model removes its generic relation, and the matching reverse relation on Value. It used to leave the relation behind, and every register() after an unregister() added another copy of it to the model.
  • BaseEntityInline works: it used to fail with AttributeError when the inline had no form, and with FieldError when it had a BaseDynamicEntityForm. The inline now defaults to BaseDynamicEntityForm, shows the attributes of its own model, saves them, and honors fields. An attribute named like a reverse relation of the inline's model no longer fails.
  • The change page of a model that uses BaseEntityAdmin opens for users who only have the view permission. It used to fail with KeyError.
  • Filtering on several EAV attributes in one filter() call works on UUID-keyed entities.
  • The Indonesian translation is compiled and ships with the package; its .mo file was missing. A test now fails if any compiled catalog differs from its .po source.
  • validate_enum and validate_object use Django's _state.adding to detect unsaved instances, because a model with a UUID default key always has a primary key, so an unsaved EnumValue was accepted and then failed with an integrity error.
  • Value.entity_id and Value.generic_value_id are now BigIntegerField, so entities with primary keys above 2,147,483,647 can store values (migration 0014). On PostgreSQL and MySQL this rewrites the eav_value table, which takes a lock for as long as the rewrite runs on a large table, so plan the upgrade accordingly.
  • Assigning a plain date to a date attribute stores midnight in the default timezone, as before, but no longer emits Django's "naive datetime" RuntimeWarning when USE_TZ is on, and saving the same date again no longer rewrites the value.
  • order_by("eav__<slug>") no longer fails on UUID-keyed entities or empty querysets, no longer mixes in values of other models that share a primary key, and now accepts -eav__<slug> for descending order. Ordering by an object attribute raises NotSupportedError (it was a FieldError). Ordering by a related field such as order_by("example__name") now sorts by that field; it used to sort by the foreign key column only.
  • validate_int and validate_float raise ValidationError instead of TypeError for None and other non-numeric types.
  • An empty CSV value is read back as [] instead of [''].
  • BaseEntityInline.get_fieldsets no longer recurses infinitely, and honours fieldsets.
  • EAV2_PRIMARY_KEY_FIELD defaults to BigAutoField when it is not set, instead of raising AttributeError.
  • Unknown attribute slugs raise Attribute.DoesNotExist with the same message from filter, exclude, get and order_by.
  • Entity.get_values names the related fields it loads, which removes a Django 6.1 deprecation warning.

Full Changelog: 1.8.2...2.0.0