Merge "Add raise/raiseload relationship loading strategy"

4 files changed, 67 insertions, 5 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 426b552e2..959bf9ee4 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -861,6 +861,20 @@
             :ref:`change_2528`
 
     .. change::
+        :tags: feature, orm
+        :tickets: 3512
+        :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 instead of returning ``None`` it raises an
+        InvalidRequestError.  Pull request courtesy Adrian Moennich.
+
+        .. seealso::
+
+            :ref:`change_3512`
+
+    .. change::
         :tags: bug, mssql
         :tickets: 3504
 
diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index fffdc4a9d..2991d1414 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -880,6 +880,26 @@ added to the :ref:`mutable_toplevel` extension, to complement the existing
 
 :ticket:`3297`
 
+.. _change_3512:
+
+New "raise" loader strategy
+---------------------------
+
+To assist with the use case of preventing unwanted lazy loads from occurring
+after a series of objects are loaded, the new "lazy='raise'" strategy and
+corresponding loader option :func:`.orm.raiseload` may be applied to a
+relationship attribute which will cause it to raise ``InvalidRequestError``
+when a non-eagerly-loaded attribute is accessed for read::
+
+    >>> from sqlalchemy.orm import raiseload
+    >>> a1 = s.query(A).options(raiseload(A.bs)).first()
+    >>> a1.bs
+    Traceback (most recent call last):
+    ...
+    sqlalchemy.exc.InvalidRequestError: 'A.bs' is not available due to lazy='raise'
+
+:ticket:`3512`
+
 New Features and Improvements - Core
 ====================================
 
diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index 577cd233e..f37a36b40 100644
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -91,8 +91,10 @@ Note that eager/lazy loading options cannot be used in conjunction dynamic relat
    relationships.   Newer versions of SQLAlchemy emit warnings or exceptions
    in these cases.
 
-Setting Noload
----------------
+.. _collections_noload_raiseload:
+
+Setting Noload, RaiseLoad
+-------------------------
 
 A "noload" relationship never loads from the database, even when
 accessed.   It is configured using ``lazy='noload'``::
@@ -105,7 +107,31 @@ accessed.   It is configured using ``lazy='noload'``::
 Above, the ``children`` collection is fully writeable, and changes to it will
 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.
+from the database, the ``children`` collection stays empty.   The noload
+strategy is also available on a query option basis using the
+:func:`.orm.noload` loader option.
+
+Alternatively, a "raise"-loaded relationship will raise an
+:exc:`~sqlalchemy.exc.InvalidRequestError` where the attribute would normally
+emit a lazy load::
+
+    class MyClass(Base):
+        __tablename__ = 'some_table'
+
+        children = relationship(MyOtherClass, lazy='raise')
+
+Above, attribute access on the ``children`` collection will raise an exception
+if it was not previously eagerloaded.  This includes read access but for
+collections will also affect write access, as collections can't be mutated
+without first loading them.  The rationale for this is to ensure that an
+application is not emitting any unexpected lazy loads within a certain context.
+Rather than having to read through SQL logs to determine that all necessary
+attributes were eager loaded, the "raise" strategy will cause unloaded
+attributes to raise immediately if accessed.  The raise strategy is
+also available on a query option basis using the :func:`.orm.raiseload`
+loader option.
+
+.. versionadded:: 1.1 added the "raise" loader strategy.
 
 .. _passive_deletes:
 
diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst
index 3a0026bbe..941edce2c 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
@@ -661,6 +661,8 @@ Relationship Loader API
 
 .. autofunction:: noload
 
+.. autofunction:: raiseload
+
 .. autofunction:: subqueryload
 
 .. autofunction:: subqueryload_all