Merged in chrisw/sqlalchemy/more_range_docs (pull request #20)

more docs for using psycopg2 range types, specifically instantiating models with them

fixes #3046

2 files changed, 31 insertions, 1 deletions

diff --git a/doc/build/conf.py b/doc/build/conf.py
index 60eca29e4..fa69abfac 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 05b63506e..c466f0377 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())