Merge branch 'docs' into release

[philo.git] / docs / models / entities.rst

diff --git a/docs/models/entities.rst b/docs/models/entities.rst
index f381ead..fee27c1 100644 (file)
--- a/docs/models/entities.rst
+++ b/docs/models/entities.rst
@@ -1,2 +1,72 @@
-Entities: the base class
-========================
\ No newline at end of file
+Entities and Attributes
+=======================
+
+One of the core concepts in philo is the relationship between the :class:`Entity` and :class:`Attribute` classes. :class:`Attribute`\ s represent an arbitrary key/value pair by having one :class:`GenericForeignKey` to an :class:`Entity` and another to an :class:`AttributeValue`.
+
+Functions
+---------
+
+.. function:: register_value_model(model)
+.. function:: unregister_value_model(model)
+
+   Helper functions to register/unregister a model as a valid content type for a :class:`ForeignKeyValue` or :class:`ManyToManyValue`.
+
+
+Classes
+-------
+
+.. class:: AttributeValue
+
+   This is an abstract base class for models that can be used as values for :class:`Attribute`\ s. See the code for examples of implementations.
+
+   .. attribute:: attribute_set
+
+      :class:`GenericRelation` back to :class:`Attribute`
+
+   .. method:: set_value(value)
+
+      Interpret ``value`` and set the appropriate fields so that the value displayed to the world is equivalent to ``value``.
+
+   .. method:: value_formfields(**kwargs)
+
+      Define any formfields that would be used to construct an instance of this value.
+
+   .. method:: construct_instance(**kwargs)
+
+      Apply cleaned data from the formfields generated by valid_formfields to oneself.
+
+.. class:: Attribute
+
+   Represents an arbitrary key/value pair attached to a model.
+
+   .. attribute:: entity
+
+      :class:`GenericForeignKey` to anything.
+
+   .. attribute:: value
+
+      :class:`GenericForeignKey` to a subclass of :class:`AttributeValue`.
+
+   .. attribute:: key
+
+      :class:`CharField` containing a key (up to 255 characters) consisting of alphanumeric characters and underscores.
+
+.. class:: Entity
+
+   A class that simplifies access to related attributes.
+
+   .. attribute:: attribute_set
+
+      :class:`GenericRelation` back to :class:`Attribute`.
+
+   .. attribute:: attributes
+
+      Property that returns a dictionary-like object which can be used to retrieve :class:`Attribute`\ s values directly.
+
+      Example::
+
+         >>> attr = entity.attribute_set.get(key='spam')
+         >>> attr.value.value
+         u'eggs'
+         >>> entity.attributes['spam']
+         u'eggs'
\ No newline at end of file