Merge pull request #33 from jpwhite3/master

Adding pre-reqs and registration decorator. Resolves issues #23 and #39

Author: jpwhite3

README.rst

@@ -35,12 +35,29 @@ You can install django-eav directly from guthub::
 
     pip install -e git+git://github.com/mvpdev/django-eav.git#egg=django-eav
 
+Prerequisites
+-------------
+
+Django Sites Framework
+~~~~~~~~~~~~~~~~~~~~~~
+As of Django 1.7, the `Sites framework <https://docs.djangoproject.com/en/1.8/ref/contrib/sites/#enabling-the-sites-framework>`_ is not enabled by default; Django-EAV requires this framework.
+To enable the sites framework, follow these steps:
+
+Add ``django.contrib.sites`` to your INSTALLED_APPS setting. Be sure to add sites to the installed apps list BEFORE eav!
+
+Define a ``SITE_ID`` setting::
+
+    SITE_ID = 1
+
+Run ``migrate``
+
+
 Usage
 -----
 
 Edit settings.py
 ~~~~~~~~~~~~~~~~
-Add ``eav`` to your ``INSTALLED_APPS`` in your project's ``settings.py`` file.
+Add ``eav`` to your ``INSTALLED_APPS`` in your project's ``settings.py`` file. Be sure to add eav to the installed apps list AFTER the sites framework!
 
 Register your model(s)
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -51,7 +68,12 @@ model with eav::
     >>> eav.register(MyModel)
 
 Generally you would do this in your ``models.py`` immediate after your model
-declarations.
+declarations. Alternatively, you can use the registration decorator provided::
+
+    from eav.decorators import register_eav
+    @register_eav()
+    class MyModel(models.Model):
+        ...
 
 Create some attributes
 ~~~~~~~~~~~~~~~~~~~~~~

eav/decorators.py

@@ -0,0 +1,19 @@
+def register_eav(**kwargs):
+    """
+    Registers the given model(s) classes and wrapped Model class with
+    django-eav:
+
+    @register_eav
+    class Author(models.Model):
+        pass
+    """
+    from . import register
+    from django.db.models import Model
+
+    def _model_eav_wrapper(model_class):
+        if not issubclass(model_class, Model):
+            raise ValueError('Wrapped class must subclass Model.')
+        register(model_class, **kwargs)
+        return model_class
+
+    return _model_eav_wrapper

eav/tests/models.py

@@ -1,4 +1,5 @@
 from django.db import models
+from ..decorators import register_eav
 
 class Patient(models.Model):
     class Meta:
@@ -19,3 +20,12 @@ class Meta:
     def __unicode__(self):
         return '%s: encounter num %d' % (self.patient, self.num)
 
+@register_eav()
+class ExampleModel(models.Model):
+    class Meta:
+        app_label = 'eav'
+
+    name = models.CharField(max_length=12)
+
+    def __unicode__(self):
+        return self.name

eav/tests/registry.py

@@ -5,7 +5,7 @@
 from ..managers import EntityManager
 from ..models import Attribute
 
-from .models import Patient, Encounter
+from .models import Patient, Encounter, ExampleModel
 
 
 class RegistryTests(TestCase):
@@ -56,6 +56,11 @@ def test_registering_overriding_defaults(self):
         eav.unregister(Patient)
         eav.unregister(Encounter)
 
+    def test_registering_via_decorator_with_defaults(self):
+        self.assertTrue(hasattr(ExampleModel, '_eav_config_cls'))
+        self.assertEqual(ExampleModel._eav_config_cls.manager_attr, 'objects')
+        self.assertEqual(ExampleModel._eav_config_cls.eav_attr, 'eav')
+
     def test_unregistering(self):
         old_mgr = Patient.objects
         eav.register(Patient)
@@ -65,6 +70,12 @@ def test_unregistering(self):
         self.assertEqual(Patient.objects, old_mgr)
         self.assertFalse(hasattr(Patient, '_eav_config_cls'))
 
+    def test_unregistering_via_decorator(self):
+        self.assertTrue(ExampleModel.objects.__class__.__name__ == 'EntityManager')
+        eav.unregister(ExampleModel)
+        e = ExampleModel()
+        self.assertFalse(ExampleModel.objects.__class__.__name__ == 'EntityManager')
+
     def test_unregistering_unregistered_model_proceeds_silently(self):
         eav.unregister(Patient)