Add raise/raiseload relationship loading strategypr/193

- available via `lazy='raise'` or by setting the `raiseload` strategy
  via `options()`
- behaves almost like `lazy='noload'`, but instead of returning `None`
  it raises `InvalidRequestError`
- based on code from Mike Bayer that was posted to the sqlalchemy
  mailing list: https://groups.google.com/forum/#!topic/sqlalchemy/X_wA8K97smE

3 files changed, 18 insertions, 3 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index bb395a826..da6211d9e 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -22,6 +22,15 @@
     :version: 1.1.0b1
 
     .. change::
+        :tags: feature, orm
+        :pullreq: github:193
+
+        Added new relationship loading strategy :func:`.orm.raiseload` (also
+        accessible via ``lazy='raise'``).  This strategy behaves almost like
+        :func:`.orm.noload` but instaed of returning ``None`` it raises an
+        InvalidRequestError.  Pull request courtesy Adrian Moennich.
+
+    .. change::
         :tags: bug, mssql
         :tickets: 3504
 
@@ -37,4 +46,4 @@
 
         .. seealso::
 
-            :ref:`change_3504`
\ No newline at end of file
+            :ref:`change_3504`
diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index 7d474ce65..4ba50b28a 100644
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -107,6 +107,10 @@ be persisted to the database as well as locally available for reading at the
 time they are added. However when instances of ``MyClass`` are freshly loaded
 from the database, the ``children`` collection stays empty.
 
+If the application is expected to never access such an unloaded relationship,
+``lazy='raise'`` may be used.  Accessing such a relationship will raise an
+:exc:`~sqlalchemy.exc.InvalidRequestError`.
+
 .. _passive_deletes:
 
 Using Passive Deletes
diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst
index 297392f3e..8cb1f0e02 100644
--- a/doc/build/orm/loading_relationships.rst
+++ b/doc/build/orm/loading_relationships.rst
@@ -185,8 +185,8 @@ Default Loading Strategies
     Default loader strategies as a new feature.
 
 Each of :func:`.joinedload`, :func:`.subqueryload`, :func:`.lazyload`,
-and :func:`.noload` can be used to set the default style of
-:func:`.relationship` loading
+:func:`.noload`, and :func:`.raiseload` can be used to set the default
+style of :func:`.relationship` loading
 for a particular query, affecting all :func:`.relationship` -mapped
 attributes not otherwise
 specified in the :class:`.Query`.   This feature is available by passing
@@ -617,6 +617,8 @@ Relationship Loader API
 
 .. autofunction:: noload
 
+.. autofunction:: raiseload
+
 .. autofunction:: subqueryload
 
 .. autofunction:: subqueryload_all