some comments, pragma no cover on some deprecated query methods

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index ca602b58cd8541874a6c380790b3ccac66896592..3e89c44dd7e45389d4f865b26cf3b5d8ff67d683 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -395,7 +395,7 @@ class ExecutionContext(object):
 
     def postfetch_cols(self):
         """return a list of Column objects for which a 'passive' server-side default
-        value was fired off"""
+        value was fired off.  applies to inserts and updates."""
 
         raise NotImplementedError()
 

diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py
index 655ad4aa694e6b9e0505f5d00374cfa73cd364e1..eba8384c6b0a09305de02869b682014c983bb75a 100644 (file)
--- a/lib/sqlalchemy/orm/interfaces.py
+++ b/lib/sqlalchemy/orm/interfaces.py
@@ -450,7 +450,9 @@ class LoaderStack(object):
     def snapshot(self):
         """return an 'snapshot' of this stack.
         
-        this is a tuple form of the stack which can be used as a hash key."""
+        this is a tuple form of the stack which can be used as a hash key.
+        """
+        
         return tuple(self.__stack)
         
     def __str__(self):
@@ -621,11 +623,11 @@ class LoaderStrategy(object):
       list of selected columns, *eager loading* properties may add
       ``LEFT OUTER JOIN`` clauses to the statement.
 
-    * it processes the SelectionContext at row-processing time.  This
-      may involve setting instance-level lazyloader functions on newly
-      constructed instances, or may involve recursively appending
-      child items to a list in response to additionally eager-loaded
-      objects in the query.
+    * it processes the ``SelectionContext`` at row-processing time.  This 
+      includes straight population of attributes corresponding to rows,
+      setting instance-level lazyloader callables on newly
+      constructed instances, and appending child items to scalar/collection 
+      attributes in response to eagerly-loaded relations.
     """
 
     def __init__(self, parent):

diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index f63d9fd2bbf07c7ac5c1830a6f5b9ec145212c4e..c96b3be2223ee5b96041ac80f5ffd3ae0b1a44f6 100644 (file)
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -1485,8 +1485,16 @@ class Mapper(object):
         """populate an instance from a result row."""
 
         selectcontext.stack.push_mapper(self)
+        # retrieve a set of "row population" functions derived from the MapperProperties attached
+        # to this Mapper.  These are keyed in the select context based primarily off the 
+        # "snapshot" of the stack, which represents a path from the lead mapper in the query to this one,
+        # including relation() names.  the key also includes "self", and allows us to distinguish between
+        # other mappers within our inheritance hierarchy
         populators = selectcontext.attributes.get(('instance_populators', self, selectcontext.stack.snapshot(), ispostselect), None)
         if populators is None:
+            # no populators; therefore this is the first time we are receiving a row for
+            # this result set.  issue create_row_processor() on all MapperProperty objects
+            # and cache in the select context.
             populators = []
             post_processors = []
             for prop in self.__props.values():

diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 5b0592dd6ea8533bd81afeee2137d9dfa6b2de12..d16b4b287e59e5d724adbf3631ca437906d2a498 100644 (file)
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -600,6 +600,25 @@ class PropertyLoader(StrategizedProperty):
         return self.parent.mapped_table is self.target or self.parent.select_table is self.target
 
     def get_join(self, parent, primary=True, secondary=True, polymorphic_parent=True):
+        """return a join condition from the given parent mapper to this PropertyLoader's mapper.
+        
+           The resulting ClauseElement object is cached and should not be modified directly.
+        
+            parent
+              a mapper which has a relation() to this PropertyLoader.  A PropertyLoader can 
+              have multiple "parents" when its actual parent mapper has inheriting mappers.
+              
+            primary
+              include the primary join condition in the resulting join.
+              
+            secondary
+              include the secondary join condition in the resulting join.  If both primary
+              and secondary are returned, they are joined via AND.
+              
+            polymorphic_parent
+              if True, use the parent's 'select_table' instead of its 'mapped_table' to produce the join.
+        """
+        
         try:
             return self._parent_join_cache[(parent, primary, secondary, polymorphic_parent)]
         except KeyError:

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 284653b5c5aaedc4b389690cd9687a49e67e5eb5..4e53270b2dfa9a0bdb4f7c5f5c10b26f1636ca47 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -926,26 +926,26 @@ class Query(object):
 
     # DEPRECATED LAND !
 
-    def list(self):
+    def list(self): #pragma: no cover
         """DEPRECATED.  use all()"""
 
         return list(self)
 
-    def scalar(self):
+    def scalar(self): #pragma: no cover
         """DEPRECATED.  use first()"""
 
         return self.first()
 
-    def _legacy_filter_by(self, *args, **kwargs):
+    def _legacy_filter_by(self, *args, **kwargs): #pragma: no cover
         return self.filter(self._legacy_join_by(args, kwargs, start=self._joinpoint))
 
-    def count_by(self, *args, **params):
+    def count_by(self, *args, **params): #pragma: no cover
         """DEPRECATED.  use query.filter_by(\**params).count()"""
 
         return self.count(self.join_by(*args, **params))
 
 
-    def select_whereclause(self, whereclause=None, params=None, **kwargs):
+    def select_whereclause(self, whereclause=None, params=None, **kwargs): #pragma: no cover
         """DEPRECATED.  use query.filter(whereclause).all()"""
 
         q = self.filter(whereclause)._legacy_select_kwargs(**kwargs)
@@ -953,7 +953,7 @@ class Query(object):
             q = q.params(**params)
         return list(q)
         
-    def _legacy_select_kwargs(self, **kwargs):
+    def _legacy_select_kwargs(self, **kwargs): #pragma: no cover
         q = self
         if "order_by" in kwargs and kwargs['order_by']:
             q = q.order_by(kwargs['order_by'])
@@ -972,7 +972,7 @@ class Query(object):
         return q
 
 
-    def get_by(self, *args, **params):
+    def get_by(self, *args, **params): #pragma: no cover
         """DEPRECATED.  use query.filter_by(\**params).first()"""
 
         ret = self._extension.get_by(self, *args, **params)
@@ -981,7 +981,7 @@ class Query(object):
 
         return self._legacy_filter_by(*args, **params).first()
 
-    def select_by(self, *args, **params):
+    def select_by(self, *args, **params): #pragma: no cover
         """DEPRECATED. use use query.filter_by(\**params).all()."""
 
         ret = self._extension.select_by(self, *args, **params)
@@ -990,28 +990,28 @@ class Query(object):
 
         return self._legacy_filter_by(*args, **params).list()
 
-    def join_by(self, *args, **params):
+    def join_by(self, *args, **params): #pragma: no cover
         """DEPRECATED. use join() to construct joins based on attribute names."""
 
         return self._legacy_join_by(args, params, start=self._joinpoint)
 
-    def _build_select(self, arg=None, params=None, **kwargs):
+    def _build_select(self, arg=None, params=None, **kwargs): #pragma: no cover
         if isinstance(arg, sql.FromClause) and arg.supports_execution():
             return self.from_statement(arg)
         else:
             return self.filter(arg)._legacy_select_kwargs(**kwargs)
 
-    def selectfirst(self, arg=None, **kwargs):
+    def selectfirst(self, arg=None, **kwargs): #pragma: no cover
         """DEPRECATED.  use query.filter(whereclause).first()"""
 
         return self._build_select(arg, **kwargs).first()
 
-    def selectone(self, arg=None, **kwargs):
+    def selectone(self, arg=None, **kwargs): #pragma: no cover
         """DEPRECATED.  use query.filter(whereclause).one()"""
 
         return self._build_select(arg, **kwargs).one()
 
-    def select(self, arg=None, **kwargs):
+    def select(self, arg=None, **kwargs): #pragma: no cover
         """DEPRECATED.  use query.filter(whereclause).all(), or query.from_statement(statement).all()"""
 
         ret = self._extension.select(self, arg=arg, **kwargs)
@@ -1019,42 +1019,42 @@ class Query(object):
             return ret
         return self._build_select(arg, **kwargs).all()
 
-    def execute(self, clauseelement, params=None, *args, **kwargs):
+    def execute(self, clauseelement, params=None, *args, **kwargs): #pragma: no cover
         """DEPRECATED.  use query.from_statement().all()"""
 
         return self._select_statement(clauseelement, params, **kwargs)
 
-    def select_statement(self, statement, **params):
+    def select_statement(self, statement, **params): #pragma: no cover
         """DEPRECATED.  Use query.from_statement(statement)"""
         
         return self._select_statement(statement, params)
 
-    def select_text(self, text, **params):
+    def select_text(self, text, **params): #pragma: no cover
         """DEPRECATED.  Use query.from_statement(statement)"""
 
         return self._select_statement(text, params)
 
-    def _select_statement(self, statement, params=None, **kwargs):
+    def _select_statement(self, statement, params=None, **kwargs): #pragma: no cover
         q = self.from_statement(statement)
         if params is not None:
             q = q.params(**params)
         q._select_context_options(**kwargs)
         return list(q)
 
-    def _select_context_options(self, populate_existing=None, version_check=None):
+    def _select_context_options(self, populate_existing=None, version_check=None): #pragma: no cover
         if populate_existing is not None:
             self._populate_existing = populate_existing
         if version_check is not None:
             self._version_check = version_check
         return self
         
-    def join_to(self, key):
+    def join_to(self, key): #pragma: no cover
         """DEPRECATED. use join() to create joins based on property names."""
 
         [keys, p] = self._locate_prop(key)
         return self.join_via(keys)
 
-    def join_via(self, keys):
+    def join_via(self, keys): #pragma: no cover
         """DEPRECATED. use join() to create joins based on property names."""
 
         mapper = self._joinpoint
@@ -1069,7 +1069,7 @@ class Query(object):
 
         return clause
 
-    def _legacy_join_by(self, args, params, start=None):
+    def _legacy_join_by(self, args, params, start=None): #pragma: no cover
         import properties
 
         clause = None
@@ -1091,7 +1091,7 @@ class Query(object):
                 clause &= c
         return clause
 
-    def _locate_prop(self, key, start=None):
+    def _locate_prop(self, key, start=None): #pragma: no cover
         import properties
         keys = []
         seen = util.Set()
@@ -1120,12 +1120,12 @@ class Query(object):
             raise exceptions.InvalidRequestError("Can't locate property named '%s'" % key)
         return [keys, p]
 
-    def selectfirst_by(self, *args, **params):
+    def selectfirst_by(self, *args, **params): #pragma: no cover
         """DEPRECATED. Use query.filter_by(\**kwargs).first()"""
 
         return self._legacy_filter_by(*args, **params).first()
 
-    def selectone_by(self, *args, **params):
+    def selectone_by(self, *args, **params): #pragma: no cover
         """DEPRECATED. Use query.filter_by(\**kwargs).one()"""
 
         return self._legacy_filter_by(*args, **params).one()