EAV-Django 1.4.2

EAV-Django is a reusable Django app that provides an implementation of the Entity-Attribute-Value data model.<br /><br /> Entity-Attribute-Value model (EAV), also known as object-attribute-value model and open schema which is used in circumstances where the number of attributes (properties, parameters) that can be used to describe a thing (an "entity" or "object") is potentially very vast, but the number that will actually apply to a given entity is relatively modest.<br /><br />EAV-Django works fine with traditional RDBMS (tested on SQLite and MySQL).<br />Priorities<br /><br />The application grew from an online shop project, so it is pretty practical and not just an academic exercise. The main priorities were:<br /><br /> 1. flexibility of data,<br /> 2. efficiency of queries, and<br /> 3. maximum maintainability without editing the code.<br /><br />Of course this implies trade-offs, and the goal was to find the least harmful combination for the general case.<br />Features<br /><br />All provided models are abstract, i.e. EAV-Django does not store any information in its own tables. Instead, it provides a basis for your own models which will have support for EAV out of the box.<br /><br />The EAV API includes:<br /><br /> * Create/update/access: model instances provide standart API for both "real" fields and EAV attributes. The abstraction, however, does not stand in your way and provides means to deal with the underlying stuff.<br /> * Query: BaseEntityManager includes uniform approach in filter() and exclude() to query "real" and EAV attributes.<br /> * Customizable schemata for attributes.<br /> * Admin: all dynamic attributes can be represented and modified in the Django admin with no or little effort (using eav.admin.BaseEntityAdmin). Schemata can be edited separately, as ordinary Django model objects.<br /> * Facets: facet search is an important feature of online shops, catalogues, etc. Basically you will need a form representing a certain subset of model attributes with appropriate widgets and choices so that the user can choose desirable values of some properties, submit the form and get a list of matching items. In general case django-filter would do, but it won't work with EAV, so EAV-Django provides a complete set of tools for that.<br /><br />Examples<br /><br />Let's define an EAV-friendly model, create an EAV attribute and see how it behaves. By "EAV attributes" I mean those stored in the database as separate objects but accessed and searched in such a way as if they were columns in the entity's table:<br /><br />from django.db import models<br />from eav.models import BaseEntity, BaseSchema, BaseAttribute<br /><br />class Fruit(BaseEntity):<br /> title = models.CharField(max_length=50)<br /><br />class Schema(BaseSchema):<br /> pass<br /><br />class Attr(BaseAttribute):<br /> schema = models.ForeignKey(Schema, related_name='attrs')<br /><br /># in Python shell:<br /><br /># define attribute named "colour"<br />>>> colour = Schema.objects.create(<br />... title = 'Colour',<br />... name = 'colour', # omit to populate/slugify from title<br />... datatype = Schema.TYPE_TEXT<br />... )<br /><br /># create an entity<br />>>> e = Fruit.objects.create(title='Apple', colour='green')<br /><br /># define "real" and EAV attributes the same way<br />>>> e.title<br />'Apple'<br />>>> e.colour<br />'green'<br /><br />>>> e.save() # deals with EAV attributes automatically<br /><br /># list EAV attributes as Attr instances<br />>>> e.attrs.all()<br />[]<br /><br /># search by an EAV attribute as if it was an ordinary field<br />>>> Fruit.objects.filter(colour='yellow')<br />[]<br /><br /># all compound lookups are supported<br />>>> Fruit.objects.filter(colour__contains='yell')<br />[]<br /><br />Note that we can access, modify and query colour as if it was a true Entity field, but at the same time its name, type and even existance are completely defined by a Schema instance. A Schema object can be understood as a class, and related Attr objects are its instances. In other words, Schema objects are like CharField, IntegerField and such, only defined on data level, not hard-coded in Python. And they can be "instantiated" for any Entity (unless you put custom constraints which are outside of EAV-Django's area of responsibility).<br /><br />The names of attributes are defined in related schemata. This can lead to fears that once a name is changed, the code is going to break. Actually this is not the case as names are only directly used for manual lookups. In all other cases the lookups are constructed without hard-coded names, and the EAV objects are interlinked by primary keys, not by names. The names are present if forms, but the forms are generated depending on current state of metadata, so you can safely rename the schemata. What you can break from the admin interface is the types. If you change the data type of a schema, all its attributes will remain the same but will use another column to store their values. When you restore the data type, previously stored values are visible again.<br /><br />See tests for more examples.<br />Data types<br /><br />Metadata-driven structure extends flexibility but implies some trade-offs. One of them is increased number of JOINs (and, therefore, slower queries). Another is fewer data types. Theoretically, we can support all data types available for a storage, but in practice it would mean creating many columns per attribute with just a few being used -- exactly what we were trying to avoid by using EAV. This is why EAV-Django only supports some basic types (though you can extend this list if needed):<br /><br /> * Schema.TYPE_TEXT, a TextField;<br /> * Schema.TYPE_FLOAT, a FloatField;<br /> * Schema.TYPE_DATE, a DateField;<br /> * Schema.TYPE_BOOL, a NullBooleanField;<br /> * Schema.TYPE_MANY for multiple choices (i.e. lists of values).<br /><br />All EAV attributes are stored as records in a table with unique combinations of references to entities and schemata. (Entity is referenced through the contenttypes framework, schema is referenced via foreign key.) In other words, there can be only one attribute with given entity and schema. The schema is a definition of attribute. The schema defines name, title, data type and a number of other properties which apply to any attribute of this schema. When we access or search EAV attributes, the EAV machinery always uses schemata as attributes metadata. Why? Because the attribute's name is stored in related schema, and the value is stored in a column of the attributes table. We don't know which column it is until we look at metadata.<br /><br />In the example provided above we've only played with a text attribute. All other types behave exactly the same except for TYPE_MANY. The many-to-many is a special case as it involves an extra model for choices. EAV-Django provides an abstract model but requires you to define a concrete model (e.g. Choice), and point to it from the attribute model (i.e. put foreign key named "choice"). The Choice model will also have to point at Schema. Check the tests for an example.<br /><br />#md5=d0a4d63b44e3be7278ed66c8a2906b72

Requirements:	No special requirements
Platforms:	*nix, Linux
Keyword:	Attribute,  Attributes,  Define,  Defined,  Eavdjango,  Lookups,  Model,  Names,  Number,  Objects,  Related,  Schema,  Schemata,  Stored,  Title,  Types
Users rating:	0/10