Commits

Mike Bayer committed 174e7c0

document the remote/foreign/remote_foreign functions

  • Participants
  • Parent commits e08da22

Comments (0)

Files changed (3)

File doc/build/orm/relationships.rst

 
 .. autofunction:: dynamic_loader
 
+.. autofunction:: foreign
 
+.. autofunction:: remote
+
+.. autofunction:: remote_foreign
+
+
+

File lib/sqlalchemy/orm/__init__.py

       which is evaluated at mapper initialization time, and may be passed as a 
       Python-evaluable string when using Declarative.
       
+      As of 0.8, the :func:`.foreign` annotation can also be applied
+      directly to the ``primaryjoin`` expression, which is an alternate,
+      more specific system of describing which columns in a particular
+      ``primaryjoin`` should be considered "foreign".
+      
     :param innerjoin=False:
       when ``True``, joined eager loads will use an inner join to join
       against related tables instead of an outer join.  The purpose
       which is evaluated at mapper initialization time, and may be passed as a 
       Python-evaluable string when using Declarative.
 
+      As of 0.8, the :func:`.remote` annotation can also be applied
+      directly to the ``primaryjoin`` expression, which is an alternate,
+      more specific system of describing which columns in a particular
+      ``primaryjoin`` should be considered "remote".
+
     :param query_class:
       a :class:`.Query` subclass that will be used as the base of the
       "appender query" returned by a "dynamic" relationship, that

File lib/sqlalchemy/orm/relationships.py

 from sqlalchemy.orm.interfaces import MANYTOMANY, MANYTOONE, ONETOMANY
 
 def remote(expr):
+    """Annotate a portion of a primaryjoin expression 
+    with a 'remote' annotation.
+    
+    :func:`.remote`, :func:`.foreign`, and :func:`.remote_foreign`
+    are intended to be used with 
+    :func:`.relationship` in conjunction with a 
+    ``primaryjoin`` expression which contains
+    indirect equality conditions, meaning the comparison
+    of mapped columns involves extraneous SQL functions
+    such as :func:`.cast`.  They can also be used in 
+    lieu of the ``foreign_keys`` and ``remote_side``
+    parameters to :func:`.relationship`, if a 
+    primaryjoin expression is also being sent explicitly.
+    
+    Below, a mapped class ``DNSRecord`` relates to the
+    ``DHCPHost`` class using a primaryjoin that casts
+    the ``content`` column to a string.  The :func:`.foreign`
+    and :func:`.remote` annotation functions are used 
+    to mark with full accuracy those mapped columns that
+    are significant to the :func:`.relationship`, in terms
+    of how they are joined::
+
+        from sqlalchemy import cast, String
+        from sqlalchemy.orm import remote, foreign
+        from sqlalchemy.dialects.postgresql import INET
+        
+        class DNSRecord(Base):
+            __tablename__ = 'dns'
+        
+            id = Column(Integer, primary_key=True)
+            content = Column(INET)
+            dhcphost = relationship(DHCPHost,
+                primaryjoin=cast(foreign(content), String) == 
+                                remote(DHCPHost.ip_address)
+            )
+
+    New in 0.8.
+
+    See also:
+    
+    * :func:`.foreign`
+    
+    * :func:`.remote_foreign`
+    
+    """
     return _annotate_columns(expr, {"remote":True})
 
 def foreign(expr):
+    """Annotate a portion of a primaryjoin expression 
+    with a 'foreign' annotation.
+
+    See the example at :func:`.remote`.
+
+    New in 0.8.
+
+    """
+
     return _annotate_columns(expr, {"foreign":True})
 
 def remote_foreign(expr):
+    """Annotate a portion of a primaryjoin expression 
+    with a 'remote' and 'foreign' annotation.
+    
+    See the example at :func:`.remote`.
+
+    New in 0.8.
+    
+    """
+
     return _annotate_columns(expr, {"foreign":True, 
                                 "remote":True})