Clarify that declarative string resolution does not imply imports are implicit

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Closes: #4545
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4545
Pull-request-sha: c25221838d726f316dc04102b6b2002cec6b3a6c

Change-Id: Ic38621f7deb3cb25e250aab61c5b2b02d633b187

diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index b00d72d64ced92a2a21f39786ab71d0ec7b5c460..6e3db9d718a0a2874bbd37dfd7f6fab26679633c 100644 (file)
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -182,7 +182,14 @@ class RelationshipProperty(StrategizedProperty):
         callables that evaluate the string as Python code, using the
         Declarative class-registry as a namespace.  This allows the lookup of
         related classes to be automatic via their string name, and removes the
-        need to import related classes at all into the local module space::
+        need for related classes to be imported into the local module space
+        before the dependent classes have been declared.  It is still required
+        that the modules in which these related classes appear are imported
+        anywhere in the application at some point before the related mappings
+        are actually used, else a lookup error will be raised when the
+        :func:`.relationship` attempts to resolve the string reference to the
+        related class.    An example of a string- resolved class is as
+        follows::
 
             from sqlalchemy.ext.declarative import declarative_base