Mike Bayer committed 41cf1df

- globally renamed refresh_instance to refresh_state
- removed 'instance' arg from session.get_bind() and friends, this is not a public API
- renamed 'state' arg on same to '_state'
- fixes [ticket:1055]

  • Participants
  • Parent commits 19dab01

Comments (0)

Files changed (5)

File lib/sqlalchemy/orm/

             if self.eager_defaults:
                 state.key = self._identity_key_from_state(state)
-                    state.key, refresh_instance=state,
+                    state.key, refresh_state=state,
                 _expire_state(state, deferred_props)
             except StopIteration:
-    def _instance_processor(self, context, path, adapter, polymorphic_from=None, extension=None, only_load_props=None, refresh_instance=None):
+    def _instance_processor(self, context, path, adapter, polymorphic_from=None, extension=None, only_load_props=None, refresh_state=None):
         pk_cols = self.primary_key
-        if polymorphic_from or refresh_instance:
+        if polymorphic_from or refresh_state:
             polymorphic_on = None
             polymorphic_on = self.polymorphic_on
                         return _instance(row, result)
             # determine identity key
-            if refresh_instance:
-                # TODO: refresh_instance seems to be named wrongly -- it is always an instance state.
-                refresh_state = refresh_instance
+            if refresh_state:
                 identitykey = refresh_state.key
                 if identitykey is None:
                     # super-rare condition; a refresh is being called
                 if not currentload and version_id_col and context.version_check and self._get_state_attr_by_column(state, self.version_id_col) != row[version_id_col]:
                     raise exc.ConcurrentModificationError("Instance '%s' version of %s does not match %s" % (state_str(state), self._get_state_attr_by_column(state, self.version_id_col), row[version_id_col]))
-            elif refresh_instance:
-                # out of band refresh_instance detected (i.e. its not in the session.identity_map)
+            elif refresh_state:
+                # out of band refresh_state detected (i.e. its not in the session.identity_map)
                 # honor it anyway.  this can happen if a _get() occurs within save_obj(), such as
                 # when eager_defaults is True.
-                state = refresh_instance
+                state = refresh_state
                 instance = state.obj()
                 isnew = state.runid != context.runid
                 currentload = True
     if mapper.inherits and not mapper.concrete:
         statement = mapper._optimized_get_statement(state, attribute_names)
         if statement:
-            result = session.query(mapper).from_statement(statement)._get(None, only_load_props=attribute_names, refresh_instance=state)
+            result = session.query(mapper).from_statement(statement)._get(None, only_load_props=attribute_names, refresh_state=state)
     if result is False:
         if has_key:
             identity_key = state.key
             identity_key = mapper._identity_key_from_state(state)
-        result = session.query(mapper)._get(identity_key, refresh_instance=state, only_load_props=attribute_names)
+        result = session.query(mapper)._get(identity_key, refresh_state=state, only_load_props=attribute_names)
     # if instance is pending, a refresh operation may not complete (even if PK attributes are assigned)
     if has_key and result is None:

File lib/sqlalchemy/orm/

         self._attributes = {}
         self._current_path = ()
         self._only_load_props = None
-        self._refresh_instance = None
+        self._refresh_state = None
         self._from_obj = None
         self._entities = []
         self._polymorphic_adapters = {}
         """generate a Query with no criterion, warn if criterion was present"""
     __no_criterion = _generative(__no_criterion_condition)(__no_criterion)
-    def __get_options(self, populate_existing=None, version_check=None, only_load_props=None, refresh_instance=None):
+    def __get_options(self, populate_existing=None, version_check=None, only_load_props=None, refresh_state=None):
         if populate_existing:
             self._populate_existing = populate_existing
         if version_check:
             self._version_check = version_check
-        if refresh_instance:
-            self._refresh_instance = refresh_instance
+        if refresh_state:
+            self._refresh_state = refresh_state
         if only_load_props:
             self._only_load_props = util.Set(only_load_props)
         return self
         return self._execute_and_instances(context)
     def _execute_and_instances(self, querycontext):
-        result = self.session.execute(querycontext.statement, params=self._params, mapper=self._mapper_zero_or_none(), instance=self._refresh_instance)
+        result = self.session.execute(querycontext.statement, params=self._params, mapper=self._mapper_zero_or_none(), _state=self._refresh_state)
         return self.iterate_instances(result, querycontext)
     def instances(self, cursor, __context=None):
             if filter:
                 rows = filter(rows)
-            if context.refresh_instance and self._only_load_props and context.refresh_instance in context.progress:
-                context.refresh_instance.commit(self._only_load_props)
-                context.progress.remove(context.refresh_instance)
+            if context.refresh_state and self._only_load_props and context.refresh_state in context.progress:
+                context.refresh_state.commit(self._only_load_props)
+                context.progress.remove(context.refresh_state)
             if not self._yield_per:
-    def _get(self, key=None, ident=None, refresh_instance=None, lockmode=None, only_load_props=None):
+    def _get(self, key=None, ident=None, refresh_state=None, lockmode=None, only_load_props=None):
         lockmode = lockmode or self._lockmode
-        if not self._populate_existing and not refresh_instance and not self._mapper_zero().always_refresh and lockmode is None:
+        if not self._populate_existing and not refresh_state and not self._mapper_zero().always_refresh and lockmode is None:
                 instance = self.session.identity_map[key]
                 state = attributes.instance_state(instance)
             ident = util.to_list(ident)
-        if refresh_instance is None:
+        if refresh_state is None:
             q = self.__no_criterion()
             q = self._clone()
         if lockmode is not None:
             q._lockmode = lockmode
-        q.__get_options(populate_existing=bool(refresh_instance), version_check=(lockmode is not None), only_load_props=only_load_props, refresh_instance=refresh_instance)
+        q.__get_options(populate_existing=bool(refresh_state), version_check=(lockmode is not None), only_load_props=only_load_props, refresh_state=refresh_state)
         q._order_by = None
             # call using all() to avoid LIMIT compilation complexity
         if self.primary_entity:
             _instance = self.mapper._instance_processor(context, (self.path_entity,), adapter, 
-                extension=self.extension, only_load_props=query._only_load_props, refresh_instance=context.refresh_instance
+                extension=self.extension, only_load_props=query._only_load_props, refresh_state=context.refresh_state
             _instance = self.mapper._instance_processor(context, (self.path_entity,), adapter)
         self.session = query.session
         self.populate_existing = query._populate_existing
         self.version_check = query._version_check
-        self.refresh_instance = query._refresh_instance
+        self.refresh_state = query._refresh_state
         self.primary_columns = []
         self.secondary_columns = []
         self.eager_order_by = []

File lib/sqlalchemy/orm/

-    def connection(self, mapper=None, clause=None, instance=None):
+    def connection(self, mapper=None, clause=None, _state=None):
         """Return the active Connection.
         Retrieves the ``Connection`` managing the current transaction.  Any
           Optional, an instance of a mapped class
-        return self.__connection(self.get_bind(mapper, clause, instance))
+        return self.__connection(self.get_bind(mapper, clause, _state))
     def __connection(self, engine, **kwargs):
         if self.transaction is not None:
             return engine.contextual_connect(**kwargs)
-    def execute(self, clause, params=None, mapper=None, instance=None):
+    def execute(self, clause, params=None, mapper=None, _state=None):
         """Execute a clause within the current transaction.
         Returns a ``ResultProxy`` of execution results.  `autocommit` Sessions
           Optional, a ``mapper`` or mapped class
-        instance
+        _state
           Optional, an instance of a mapped class
         clause = expression._literal_as_text(clause)
-        engine = self.get_bind(mapper, clause=clause, instance=instance)
+        engine = self.get_bind(mapper, clause=clause, _state=_state)
         return self.__connection(engine, close_with_result=True).execute(
             clause, params or {})
-    def scalar(self, clause, params=None, mapper=None, instance=None):
+    def scalar(self, clause, params=None, mapper=None, _state=None):
         """Like execute() but return a scalar result."""
-        engine = self.get_bind(mapper, clause=clause, instance=instance)
+        engine = self.get_bind(mapper, clause=clause, _state=_state)
         return self.__connection(engine, close_with_result=True).scalar(
             clause, params or {})
         self.__binds[table] = bind
-    def get_bind(self, mapper=None, clause=None, instance=None, state=None):
-        """Resolve and return a configured database bind or raise.
+    def get_bind(self, mapper, clause=None, _state=None):
+        """Return an engine corresponding to the given arguments.
         All arguments are optional.
           Optional, A ClauseElement (i.e. select(), text(), etc.)
-        instance
-          Optional, an instance of a mapped class
-        state
+        _state
           Optional, SA internal representation of a mapped instance
-        if mapper is clause is instance is state is None:
+        if mapper is clause is _state is None:
             if self.bind:
                 return self.bind
                     "Connection, and no context was provided to locate "
                     "a binding.")
-        # fixme: fix internal callers, we're bork3n here
-        if isinstance(instance, attributes.InstanceState):
-            state, instance = instance, None
         mappers = []
-        if state is not None:
-            mappers.append(_state_mapper(state))
-        if instance is not None:
-            mappers.append(_object_mapper(instance))
+        if _state is not None:
+            mappers.append(_state_mapper(_state))
         if mapper is not None:
             context.append('mapper %s' % _class_to_mapper(mapper))
         if clause is not None:
             context.append('SQL expression')
-        if instance is not None:
-            context.append('instance %s' % mapperutil.instance_str(instance))
-        if state is not None:
-            context.append('state %r' % state)
+        if _state is not None:
+            context.append('state %r' % _state)
         raise sa_exc.UnboundExecutionError(
             "Could not locate a bind configured on %s or this Session" % (
             raise exc.UnmappedInstanceError(instance)
         if self.query(_object_mapper(instance))._get(
-                state.key, refresh_instance=state,
+                state.key, refresh_state=state,
                 only_load_props=attribute_names) is None:
             raise sa_exc.InvalidRequestError(
                 "Could not refresh instance '%s'" %

File lib/sqlalchemy/orm/

         query = session.query(localparent)
         ident = state.key[1]
-        query._get(None, ident=ident, only_load_props=group, refresh_instance=state)
+        query._get(None, ident=ident, only_load_props=group, refresh_state=state)
         return attributes.ATTR_WAS_SET
 class DeferredOption(StrategizedOption):

File test/orm/

     def _public_session_methods(self):
         Session = sa.orm.session.Session
-        blacklist = set(('begin', 'query'))
+        blacklist = set(('begin', 'query', 'connection', 'execute', 'get_bind', 'scalar'))
         ok = set()
         for meth in Session.public_methods:
         raises_('add_all', (user_arg,))
-        raises_('connection', instance=user_arg)
         raises_('delete', user_arg)
-        raises_('execute', 'SELECT 1', instance=user_arg)
         raises_('expire', user_arg)
         raises_('expunge', user_arg)
             x_raises_(s, 'flush', (user_arg,))
-        raises_('get_bind', instance=user_arg)
         raises_('is_modified', user_arg)
         raises_('merge', user_arg)
         raises_('save_or_update', user_arg)
-        raises_('scalar', 'SELECT 1', instance=user_arg)
         raises_('update', user_arg)
         instance_methods = self._public_session_methods() - self._class_methods