From 7d7996e16d5c0060100fbad3f3cfdbf4eaf7db6b Mon Sep 17 00:00:00 2001
From: Ryan Leckey <rleckey@concordusapps.com>
Date: Mon, 9 Sep 2013 00:51:45 -0700
Subject: [PATCH] Add small documentation and example for generic_relationship.

---
 docs/index.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/index.rst b/docs/index.rst
index efe5d16..eacc165 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -209,6 +209,56 @@ TimezoneType saves timezone objects as strings on the way in and converts them b
         timezone = sa.Column(TimezoneType(backend='pytz'))
 
 
+Generic Relationship
+--------------------
+
+Generic relationship is a form of relationship that supports creating a 1 to many relationship to any target model.
+
+::
+
+    from sqlalchemy_utils import generic_relationship
+
+    class User(Base):
+        __tablename__ = 'user'
+        id = sa.Column(sa.Integer, primary_key=True)
+
+    class Customer(Base):
+        __tablename__ = 'customer'
+        id = sa.Column(sa.Integer, primary_key=True)
+
+    class Event(Base):
+        __tablename__ = 'event'
+        id = sa.Column(sa.Integer, primary_key=True)
+
+        # This is used to discriminate between the linked tables.
+        object_type = sa.Column(sa.Unicode(255))
+
+        # This is used to point to the primary key of the linked row.
+        object_id = sa.Column(sa.Integer)
+
+        object = generic_relationship(object_type, object_id)
+
+
+    # Some general usage to attach an event to a user.
+    us_1 = User()
+    cu_1 = Customer()
+
+    session.add_all([us_1, cu_1])
+    session.commit()
+
+    ev = Event()
+    ev.object = us_1
+
+    session.add(ev)
+    session.commit()
+
+    # Find the event we just made.
+    session.query(Event).filter_by(object=us_1).first()
+
+    # Find any events that are bound to users.
+    session.query(Event).filter(Event.object.is_type(User)).all()
+
+
 API Documentation
 -----------------