From b41e09f4efc96d6b08092d726c3fac90cd5be9fd Mon Sep 17 00:00:00 2001
From: Chris Withers <chris@withers.org>
Date: Sun, 25 May 2014 15:46:31 +0100
Subject: [PATCH] more docs for using psycopg2 range types, specifically
 instantiating models with them

---
 doc/build/conf.py                 |  1 +
 doc/build/dialects/postgresql.rst | 31 ++++++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/doc/build/conf.py b/doc/build/conf.py
index b714fc579d..5f9fa36606 100644
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -326,4 +326,5 @@ epub_copyright = u'2007-2014, SQLAlchemy authors'
 
 intersphinx_mapping = {
     'alembic': ('http://alembic.readthedocs.org/en/latest/', None),
+    'psycopg2': ('http://pythonhosted.org/psycopg2', None),
 }
diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst
index 05b63506ee..c466f03771 100644
--- a/doc/build/dialects/postgresql.rst
+++ b/doc/build/dialects/postgresql.rst
@@ -126,6 +126,33 @@ mixin:
   ``psycopg2``, it's recommended to upgrade to version 2.5 or later
   before using these column types.
 
+When instantiating models that use these column types, you should pass
+whatever data type is expected by the DBAPI driver you're using for
+the column type. For :mod:`psycopg2` these are
+:class:`~psycopg2.extras.NumericRange`,
+:class:`~psycopg2.extras.DateRange`,
+:class:`~psycopg2.extras.DateTimeRange` and
+:class:`~psycopg2.extras.DateTimeTZRange` or the class you've
+registered with :func:`~psycopg2.extras.register_range`.
+
+For example:
+
+.. code-block:: python
+
+  from psycopg2.extras import DateTimeRange
+  from sqlalchemy.dialects.postgresql import TSRANGE
+    
+  class RoomBooking(Base):
+
+      __tablename__ = 'room_booking'
+
+      room = Column(Integer(), primary_key=True)
+      during = Column(TSRANGE())
+
+  booking = RoomBooking(
+      room=101, 
+      during=DateTimeRange(datetime(2013, 3, 23), None
+  )
 
 PostgreSQL Constraint Types
 ---------------------------
@@ -140,7 +167,9 @@ For example::
 
   from sqlalchemy.dialects.postgresql import ExcludeConstraint, TSRANGE
 
-  class RoomBookings(Base):
+  class RoomBooking(Base):
+
+      __tablename__ = 'room_booking'
 
       room = Column(Integer(), primary_key=True)
       during = Column(TSRANGE())
-- 
2.47.3