Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/sqlalchemy/orm/state.py: 37%

1# orm/state.py 

2# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors 

3# <see AUTHORS file> 

4# 

5# This module is part of SQLAlchemy and is released under 

6# the MIT License: https://www.opensource.org/licenses/mit-license.php 

7 

8"""Defines instrumentation of instances. 

9 

10This module is usually not directly visible to user applications, but 

11defines a large part of the ORM's interactivity. 

12 

13""" 

14 

15from __future__ import annotations 

16 

17from typing import Any 

18from typing import Callable 

19from typing import Dict 

20from typing import Generic 

21from typing import Iterable 

22from typing import Literal 

23from typing import Optional 

24from typing import Protocol 

25from typing import Set 

26from typing import Tuple 

27from typing import TYPE_CHECKING 

28from typing import Union 

29import weakref 

30 

31from . import base 

32from . import exc as orm_exc 

33from . import interfaces 

34from ._typing import _O 

35from ._typing import is_collection_impl 

36from .base import ATTR_WAS_SET 

37from .base import INIT_OK 

38from .base import LoaderCallableStatus 

39from .base import NEVER_SET 

40from .base import NO_VALUE 

41from .base import PASSIVE_NO_INITIALIZE 

42from .base import PASSIVE_NO_RESULT 

43from .base import PASSIVE_OFF 

44from .base import SQL_OK 

45from .path_registry import PathRegistry 

46from .. import exc as sa_exc 

47from .. import inspection 

48from .. import util 

49from ..util.typing import TupleAny 

50from ..util.typing import Unpack 

51 

52if TYPE_CHECKING: 

53 from ._typing import _IdentityKeyType 

54 from ._typing import _InstanceDict 

55 from ._typing import _LoaderCallable 

56 from .attributes import _AttributeImpl 

57 from .attributes import History 

58 from .base import PassiveFlag 

59 from .collections import _AdaptedCollectionProtocol 

60 from .identity import IdentityMap 

61 from .instrumentation import ClassManager 

62 from .interfaces import ORMOption 

63 from .mapper import Mapper 

64 from .session import Session 

65 from ..engine import Row 

66 from ..ext.asyncio.session import async_session as _async_provider 

67 from ..ext.asyncio.session import AsyncSession 

68 

69if TYPE_CHECKING: 

70 _sessions: weakref.WeakValueDictionary[int, Session] 

71else: 

72 # late-populated by session.py 

73 _sessions = None 

74 

75 

76if not TYPE_CHECKING: 

77 # optionally late-provided by sqlalchemy.ext.asyncio.session 

78 

79 _async_provider = None # noqa 

80 

81 

82class _InstanceDictProto(Protocol): 

83 def __call__(self) -> Optional[IdentityMap]: ... 

84 

85 

86class _InstallLoaderCallableProto(Protocol[_O]): 

87 """used at result loading time to install a _LoaderCallable callable 

88 upon a specific InstanceState, which will be used to populate an 

89 attribute when that attribute is accessed. 

90 

91 Concrete examples are per-instance deferred column loaders and 

92 relationship lazy loaders. 

93 

94 """ 

95 

96 def __call__( 

97 self, 

98 state: InstanceState[_O], 

99 dict_: _InstanceDict, 

100 row: Row[Unpack[TupleAny]], 

101 ) -> None: ... 

102 

103 

104@inspection._self_inspects 

105class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): 

106 """Tracks state information at the instance level. 

107 

108 The :class:`.InstanceState` is a key object used by the 

109 SQLAlchemy ORM in order to track the state of an object; 

110 it is created the moment an object is instantiated, typically 

111 as a result of :term:`instrumentation` which SQLAlchemy applies 

112 to the ``__init__()`` method of the class. 

113 

114 :class:`.InstanceState` is also a semi-public object, 

115 available for runtime inspection as to the state of a 

116 mapped instance, including information such as its current 

117 status within a particular :class:`.Session` and details 

118 about data on individual attributes. The public API 

119 in order to acquire a :class:`.InstanceState` object 

120 is to use the :func:`_sa.inspect` system:: 

121 

122 >>> from sqlalchemy import inspect 

123 >>> insp = inspect(some_mapped_object) 

124 >>> insp.attrs.nickname.history 

125 History(added=['new nickname'], unchanged=(), deleted=['nickname']) 

126 

127 .. seealso:: 

128 

129 :ref:`orm_mapper_inspection_instancestate` 

130 

131 """ 

132 

133 __slots__ = ( 

134 "__dict__", 

135 "__weakref__", 

136 "class_", 

137 "manager", 

138 "obj", 

139 "committed_state", 

140 "expired_attributes", 

141 ) 

142 

143 manager: ClassManager[_O] 

144 session_id: Optional[int] = None 

145 key: Optional[_IdentityKeyType[_O]] = None 

146 runid: Optional[int] = None 

147 load_options: Tuple[ORMOption, ...] = () 

148 load_path: PathRegistry = PathRegistry.root 

149 insert_order: Optional[int] = None 

150 _strong_obj: Optional[object] = None 

151 obj: weakref.ref[_O] 

152 

153 committed_state: Dict[str, Any] 

154 

155 modified: bool = False 

156 """When ``True`` the object was modified.""" 

157 expired: bool = False 

158 """When ``True`` the object is :term:`expired`. 

159 

160 .. seealso:: 

161 

162 :ref:`session_expire` 

163 """ 

164 _deleted: bool = False 

165 _load_pending: bool = False 

166 _orphaned_outside_of_session: bool = False 

167 is_instance: bool = True 

168 identity_token: object = None 

169 _last_known_values: Optional[Dict[str, Any]] = None 

170 

171 _instance_dict: _InstanceDictProto 

172 """A weak reference, or in the default case a plain callable, that 

173 returns a reference to the current :class:`.IdentityMap`, if any. 

174 

175 """ 

176 if not TYPE_CHECKING: 

177 

178 def _instance_dict(self): 

179 """default 'weak reference' for _instance_dict""" 

180 return None 

181 

182 expired_attributes: Set[str] 

183 """The set of keys which are 'expired' to be loaded by 

184 the manager's deferred scalar loader, assuming no pending 

185 changes. 

186 

187 See also the ``unmodified`` collection which is intersected 

188 against this set when a refresh operation occurs. 

189 """ 

190 

191 callables: Dict[str, Callable[[InstanceState[_O], PassiveFlag], Any]] 

192 """A namespace where a per-state loader callable can be associated. 

193 

194 In SQLAlchemy 1.0, this is only used for lazy loaders / deferred 

195 loaders that were set up via query option. 

196 

197 Previously, callables was used also to indicate expired attributes 

198 by storing a link to the InstanceState itself in this dictionary. 

199 This role is now handled by the expired_attributes set. 

200 

201 """ 

202 

203 if not TYPE_CHECKING: 

204 callables = util.EMPTY_DICT 

205 

206 def __init__(self, obj: _O, manager: ClassManager[_O]): 

207 self.class_ = obj.__class__ 

208 self.manager = manager 

209 self.obj = weakref.ref(obj, self._cleanup) 

210 self.committed_state = {} 

211 self.expired_attributes = set() 

212 

213 @util.memoized_property 

214 def attrs(self) -> util.ReadOnlyProperties[AttributeState]: 

215 """Return a namespace representing each attribute on 

216 the mapped object, including its current value 

217 and history. 

218 

219 The returned object is an instance of :class:`.AttributeState`. 

220 This object allows inspection of the current data 

221 within an attribute as well as attribute history 

222 since the last flush. 

223 

224 """ 

225 return util.ReadOnlyProperties( 

226 {key: AttributeState(self, key) for key in self.manager} 

227 ) 

228 

229 @property 

230 def transient(self) -> bool: 

231 """Return ``True`` if the object is :term:`transient`. 

232 

233 .. seealso:: 

234 

235 :ref:`session_object_states` 

236 

237 """ 

238 return self.key is None and not self._attached 

239 

240 @property 

241 def pending(self) -> bool: 

242 """Return ``True`` if the object is :term:`pending`. 

243 

244 .. seealso:: 

245 

246 :ref:`session_object_states` 

247 

248 """ 

249 return self.key is None and self._attached 

250 

251 @property 

252 def deleted(self) -> bool: 

253 """Return ``True`` if the object is :term:`deleted`. 

254 

255 An object that is in the deleted state is guaranteed to 

256 not be within the :attr:`.Session.identity_map` of its parent 

257 :class:`.Session`; however if the session's transaction is rolled 

258 back, the object will be restored to the persistent state and 

259 the identity map. 

260 

261 .. note:: 

262 

263 The :attr:`.InstanceState.deleted` attribute refers to a specific 

264 state of the object that occurs between the "persistent" and 

265 "detached" states; once the object is :term:`detached`, the 

266 :attr:`.InstanceState.deleted` attribute **no longer returns 

267 True**; in order to detect that a state was deleted, regardless 

268 of whether or not the object is associated with a 

269 :class:`.Session`, use the :attr:`.InstanceState.was_deleted` 

270 accessor. 

271 

272 .. seealso:: 

273 

274 :ref:`session_object_states` 

275 

276 """ 

277 return self.key is not None and self._attached and self._deleted 

278 

279 @property 

280 def was_deleted(self) -> bool: 

281 """Return True if this object is or was previously in the 

282 "deleted" state and has not been reverted to persistent. 

283 

284 This flag returns True once the object was deleted in flush. 

285 When the object is expunged from the session either explicitly 

286 or via transaction commit and enters the "detached" state, 

287 this flag will continue to report True. 

288 

289 .. seealso:: 

290 

291 :attr:`.InstanceState.deleted` - refers to the "deleted" state 

292 

293 :func:`.orm.util.was_deleted` - standalone function 

294 

295 :ref:`session_object_states` 

296 

297 """ 

298 return self._deleted 

299 

300 @property 

301 def persistent(self) -> bool: 

302 """Return ``True`` if the object is :term:`persistent`. 

303 

304 An object that is in the persistent state is guaranteed to 

305 be within the :attr:`.Session.identity_map` of its parent 

306 :class:`.Session`. 

307 

308 .. seealso:: 

309 

310 :ref:`session_object_states` 

311 

312 """ 

313 return self.key is not None and self._attached and not self._deleted 

314 

315 @property 

316 def detached(self) -> bool: 

317 """Return ``True`` if the object is :term:`detached`. 

318 

319 .. seealso:: 

320 

321 :ref:`session_object_states` 

322 

323 """ 

324 return self.key is not None and not self._attached 

325 

326 @util.non_memoized_property 

327 @util.preload_module("sqlalchemy.orm.session") 

328 def _attached(self) -> bool: 

329 return ( 

330 self.session_id is not None 

331 and self.session_id in util.preloaded.orm_session._sessions 

332 ) 

333 

334 def _track_last_known_value(self, key: str) -> None: 

335 """Track the last known value of a particular key after expiration 

336 operations. 

337 

338 """ 

339 

340 lkv = self._last_known_values 

341 if lkv is None: 

342 self._last_known_values = lkv = {} 

343 if key not in lkv: 

344 lkv[key] = NO_VALUE 

345 

346 @property 

347 def session(self) -> Optional[Session]: 

348 """Return the owning :class:`.Session` for this instance, 

349 or ``None`` if none available. 

350 

351 Note that the result here can in some cases be *different* 

352 from that of ``obj in session``; an object that's been deleted 

353 will report as not ``in session``, however if the transaction is 

354 still in progress, this attribute will still refer to that session. 

355 Only when the transaction is completed does the object become 

356 fully detached under normal circumstances. 

357 

358 .. seealso:: 

359 

360 :attr:`_orm.InstanceState.async_session` 

361 

362 """ 

363 if self.session_id: 

364 try: 

365 return _sessions[self.session_id] 

366 except KeyError: 

367 pass 

368 return None 

369 

370 @property 

371 def async_session(self) -> Optional[AsyncSession]: 

372 """Return the owning :class:`_asyncio.AsyncSession` for this instance, 

373 or ``None`` if none available. 

374 

375 This attribute is only non-None when the :mod:`sqlalchemy.ext.asyncio` 

376 API is in use for this ORM object. The returned 

377 :class:`_asyncio.AsyncSession` object will be a proxy for the 

378 :class:`_orm.Session` object that would be returned from the 

379 :attr:`_orm.InstanceState.session` attribute for this 

380 :class:`_orm.InstanceState`. 

381 

382 .. versionadded:: 1.4.18 

383 

384 .. seealso:: 

385 

386 :ref:`asyncio_toplevel` 

387 

388 """ 

389 if _async_provider is None: 

390 return None 

391 

392 sess = self.session 

393 if sess is not None: 

394 return _async_provider(sess) 

395 else: 

396 return None 

397 

398 @property 

399 def object(self) -> Optional[_O]: 

400 """Return the mapped object represented by this 

401 :class:`.InstanceState`. 

402 

403 Returns None if the object has been garbage collected 

404 

405 """ 

406 return self.obj() 

407 

408 @property 

409 def identity(self) -> Optional[Tuple[Any, ...]]: 

410 """Return the mapped identity of the mapped object. 

411 This is the primary key identity as persisted by the ORM 

412 which can always be passed directly to 

413 :meth:`_query.Query.get`. 

414 

415 Returns ``None`` if the object has no primary key identity. 

416 

417 .. note:: 

418 An object which is :term:`transient` or :term:`pending` 

419 does **not** have a mapped identity until it is flushed, 

420 even if its attributes include primary key values. 

421 

422 """ 

423 if self.key is None: 

424 return None 

425 else: 

426 return self.key[1] 

427 

428 @property 

429 def identity_key(self) -> Optional[_IdentityKeyType[_O]]: 

430 """Return the identity key for the mapped object. 

431 

432 This is the key used to locate the object within 

433 the :attr:`.Session.identity_map` mapping. It contains 

434 the identity as returned by :attr:`.identity` within it. 

435 

436 

437 """ 

438 return self.key 

439 

440 @util.memoized_property 

441 def parents(self) -> Dict[int, Union[Literal[False], InstanceState[Any]]]: 

442 return {} 

443 

444 @util.memoized_property 

445 def _pending_mutations(self) -> Dict[str, PendingCollection]: 

446 return {} 

447 

448 @util.memoized_property 

449 def _empty_collections(self) -> Dict[str, _AdaptedCollectionProtocol]: 

450 return {} 

451 

452 @util.memoized_property 

453 def mapper(self) -> Mapper[_O]: 

454 """Return the :class:`_orm.Mapper` used for this mapped object.""" 

455 return self.manager.mapper 

456 

457 @property 

458 def has_identity(self) -> bool: 

459 """Return ``True`` if this object has an identity key. 

460 

461 This should always have the same value as the 

462 expression ``state.persistent`` or ``state.detached``. 

463 

464 """ 

465 return bool(self.key) 

466 

467 @classmethod 

468 def _detach_states( 

469 self, 

470 states: Iterable[InstanceState[_O]], 

471 session: Session, 

472 to_transient: bool = False, 

473 ) -> None: 

474 persistent_to_detached = ( 

475 session.dispatch.persistent_to_detached or None 

476 ) 

477 deleted_to_detached = session.dispatch.deleted_to_detached or None 

478 pending_to_transient = session.dispatch.pending_to_transient or None 

479 persistent_to_transient = ( 

480 session.dispatch.persistent_to_transient or None 

481 ) 

482 

483 for state in states: 

484 deleted = state._deleted 

485 pending = state.key is None 

486 persistent = not pending and not deleted 

487 

488 state.session_id = None 

489 

490 if to_transient and state.key: 

491 del state.key 

492 if persistent: 

493 if to_transient: 

494 if persistent_to_transient is not None: 

495 persistent_to_transient(session, state) 

496 elif persistent_to_detached is not None: 

497 persistent_to_detached(session, state) 

498 elif deleted and deleted_to_detached is not None: 

499 deleted_to_detached(session, state) 

500 elif pending and pending_to_transient is not None: 

501 pending_to_transient(session, state) 

502 

503 state._strong_obj = None 

504 

505 def _detach(self, session: Optional[Session] = None) -> None: 

506 if session: 

507 InstanceState._detach_states([self], session) 

508 else: 

509 self.session_id = self._strong_obj = None 

510 

511 def _dispose(self) -> None: 

512 # used by the test suite, apparently 

513 self._detach() 

514 

515 def _cleanup(self, ref: weakref.ref[_O]) -> None: 

516 """Weakref callback cleanup. 

517 

518 This callable cleans out the state when it is being garbage 

519 collected. 

520 

521 this _cleanup **assumes** that there are no strong refs to us! 

522 Will not work otherwise! 

523 

524 """ 

525 

526 # Python builtins become undefined during interpreter shutdown. 

527 # Guard against exceptions during this phase, as the method cannot 

528 # proceed in any case if builtins have been undefined. 

529 if dict is None: 

530 return 

531 

532 instance_dict = self._instance_dict() 

533 if instance_dict is not None: 

534 instance_dict._fast_discard(self) 

535 del self._instance_dict 

536 

537 # we can't possibly be in instance_dict._modified 

538 # b.c. this is weakref cleanup only, that set 

539 # is strong referencing! 

540 # assert self not in instance_dict._modified 

541 

542 self.session_id = self._strong_obj = None 

543 

544 @property 

545 def dict(self) -> _InstanceDict: 

546 """Return the instance dict used by the object. 

547 

548 Under normal circumstances, this is always synonymous 

549 with the ``__dict__`` attribute of the mapped object, 

550 unless an alternative instrumentation system has been 

551 configured. 

552 

553 In the case that the actual object has been garbage 

554 collected, this accessor returns a blank dictionary. 

555 

556 """ 

557 o = self.obj() 

558 if o is not None: 

559 return base.instance_dict(o) 

560 else: 

561 return {} 

562 

563 def _initialize_instance(*mixed: Any, **kwargs: Any) -> None: 

564 self, instance, args = mixed[0], mixed[1], mixed[2:] # noqa 

565 manager = self.manager 

566 

567 manager.dispatch.init(self, args, kwargs) 

568 

569 try: 

570 manager.original_init(*mixed[1:], **kwargs) 

571 except: 

572 with util.safe_reraise(): 

573 manager.dispatch.init_failure(self, args, kwargs) 

574 

575 def get_history(self, key: str, passive: PassiveFlag) -> History: 

576 return self.manager[key].impl.get_history(self, self.dict, passive) 

577 

578 def get_impl(self, key: str) -> _AttributeImpl: 

579 return self.manager[key].impl 

580 

581 def _get_pending_mutation(self, key: str) -> PendingCollection: 

582 if key not in self._pending_mutations: 

583 self._pending_mutations[key] = PendingCollection() 

584 return self._pending_mutations[key] 

585 

586 def __getstate__(self) -> Dict[str, Any]: 

587 state_dict: Dict[str, Any] = { 

588 "instance": self.obj(), 

589 "class_": self.class_, 

590 "committed_state": self.committed_state, 

591 "expired_attributes": self.expired_attributes, 

592 } 

593 state_dict.update( 

594 (k, self.__dict__[k]) 

595 for k in ( 

596 "_pending_mutations", 

597 "modified", 

598 "expired", 

599 "callables", 

600 "key", 

601 "parents", 

602 "load_options", 

603 "class_", 

604 "expired_attributes", 

605 "info", 

606 ) 

607 if k in self.__dict__ 

608 ) 

609 if self.load_path: 

610 state_dict["load_path"] = self.load_path.serialize() 

611 

612 state_dict["manager"] = self.manager._serialize(self, state_dict) 

613 

614 return state_dict 

615 

616 def __setstate__(self, state_dict: Dict[str, Any]) -> None: 

617 inst = state_dict["instance"] 

618 if inst is not None: 

619 self.obj = weakref.ref(inst, self._cleanup) 

620 self.class_ = inst.__class__ 

621 else: 

622 self.obj = lambda: None # type: ignore 

623 self.class_ = state_dict["class_"] 

624 

625 self.committed_state = state_dict.get("committed_state", {}) 

626 self._pending_mutations = state_dict.get("_pending_mutations", {}) 

627 self.parents = state_dict.get("parents", {}) 

628 self.modified = state_dict.get("modified", False) 

629 self.expired = state_dict.get("expired", False) 

630 if "info" in state_dict: 

631 self.info.update(state_dict["info"]) 

632 if "callables" in state_dict: 

633 self.callables = state_dict["callables"] 

634 

635 self.expired_attributes = state_dict["expired_attributes"] 

636 else: 

637 if "expired_attributes" in state_dict: 

638 self.expired_attributes = state_dict["expired_attributes"] 

639 else: 

640 self.expired_attributes = set() 

641 

642 self.__dict__.update( 

643 [ 

644 (k, state_dict[k]) 

645 for k in ("key", "load_options") 

646 if k in state_dict 

647 ] 

648 ) 

649 if self.key: 

650 self.identity_token = self.key[2] 

651 

652 if "load_path" in state_dict: 

653 self.load_path = PathRegistry.deserialize(state_dict["load_path"]) 

654 

655 state_dict["manager"](self, inst, state_dict) 

656 

657 def _reset(self, dict_: _InstanceDict, key: str) -> None: 

658 """Remove the given attribute and any 

659 callables associated with it.""" 

660 

661 old = dict_.pop(key, None) 

662 manager_impl = self.manager[key].impl 

663 if old is not None and is_collection_impl(manager_impl): 

664 manager_impl._invalidate_collection(old) 

665 self.expired_attributes.discard(key) 

666 if self.callables: 

667 self.callables.pop(key, None) 

668 

669 def _copy_callables(self, from_: InstanceState[Any]) -> None: 

670 if "callables" in from_.__dict__: 

671 self.callables = dict(from_.callables) 

672 

673 @classmethod 

674 def _instance_level_callable_processor( 

675 cls, manager: ClassManager[_O], fn: _LoaderCallable, key: Any 

676 ) -> _InstallLoaderCallableProto[_O]: 

677 impl = manager[key].impl 

678 if is_collection_impl(impl): 

679 fixed_impl = impl 

680 

681 def _set_callable( 

682 state: InstanceState[_O], 

683 dict_: _InstanceDict, 

684 row: Row[Unpack[TupleAny]], 

685 ) -> None: 

686 if "callables" not in state.__dict__: 

687 state.callables = {} 

688 old = dict_.pop(key, None) 

689 if old is not None: 

690 fixed_impl._invalidate_collection(old) 

691 state.callables[key] = fn 

692 

693 else: 

694 

695 def _set_callable( 

696 state: InstanceState[_O], 

697 dict_: _InstanceDict, 

698 row: Row[Unpack[TupleAny]], 

699 ) -> None: 

700 if "callables" not in state.__dict__: 

701 state.callables = {} 

702 state.callables[key] = fn 

703 

704 return _set_callable 

705 

706 def _expire( 

707 self, dict_: _InstanceDict, modified_set: Set[InstanceState[Any]] 

708 ) -> None: 

709 self.expired = True 

710 if self.modified: 

711 modified_set.discard(self) 

712 self.committed_state.clear() 

713 self.modified = False 

714 

715 self._strong_obj = None 

716 

717 if "_pending_mutations" in self.__dict__: 

718 del self.__dict__["_pending_mutations"] 

719 

720 if "parents" in self.__dict__: 

721 del self.__dict__["parents"] 

722 

723 self.expired_attributes.update( 

724 [impl.key for impl in self.manager._loader_impls] 

725 ) 

726 

727 if self.callables: 

728 # the per state loader callables we can remove here are 

729 # LoadDeferredColumns, which undefers a column at the instance 

730 # level that is mapped with deferred, and LoadLazyAttribute, 

731 # which lazy loads a relationship at the instance level that 

732 # is mapped with "noload" or perhaps "immediateload". 

733 # Before 1.4, only column-based 

734 # attributes could be considered to be "expired", so here they 

735 # were the only ones "unexpired", which means to make them deferred 

736 # again. For the moment, as of 1.4 we also apply the same 

737 # treatment relationships now, that is, an instance level lazy 

738 # loader is reset in the same way as a column loader. 

739 for k in self.expired_attributes.intersection(self.callables): 

740 del self.callables[k] 

741 

742 for k in self.manager._collection_impl_keys.intersection(dict_): 

743 collection = dict_.pop(k) 

744 collection._sa_adapter.invalidated = True 

745 

746 if self._last_known_values: 

747 self._last_known_values.update( 

748 {k: dict_[k] for k in self._last_known_values if k in dict_} 

749 ) 

750 

751 for key in self.manager._all_key_set.intersection(dict_): 

752 del dict_[key] 

753 

754 self.manager.dispatch.expire(self, None) 

755 

756 def _expire_attributes( 

757 self, 

758 dict_: _InstanceDict, 

759 attribute_names: Iterable[str], 

760 no_loader: bool = False, 

761 ) -> None: 

762 pending = self.__dict__.get("_pending_mutations", None) 

763 

764 callables = self.callables 

765 

766 for key in attribute_names: 

767 impl = self.manager[key].impl 

768 if impl.accepts_scalar_loader: 

769 if no_loader and (impl.callable_ or key in callables): 

770 continue 

771 

772 self.expired_attributes.add(key) 

773 if callables and key in callables: 

774 del callables[key] 

775 old = dict_.pop(key, NO_VALUE) 

776 if is_collection_impl(impl) and old is not NO_VALUE: 

777 impl._invalidate_collection(old) 

778 

779 lkv = self._last_known_values 

780 if lkv is not None and key in lkv and old is not NO_VALUE: 

781 lkv[key] = old 

782 

783 self.committed_state.pop(key, None) 

784 if pending: 

785 pending.pop(key, None) 

786 

787 self.manager.dispatch.expire(self, attribute_names) 

788 

789 def _load_expired( 

790 self, state: InstanceState[_O], passive: PassiveFlag 

791 ) -> LoaderCallableStatus: 

792 """__call__ allows the InstanceState to act as a deferred 

793 callable for loading expired attributes, which is also 

794 serializable (picklable). 

795 

796 """ 

797 

798 if not passive & SQL_OK: 

799 return PASSIVE_NO_RESULT 

800 

801 toload = self.expired_attributes.intersection(self.unmodified) 

802 toload = toload.difference( 

803 attr 

804 for attr in toload 

805 if not self.manager[attr].impl.load_on_unexpire 

806 ) 

807 

808 self.manager.expired_attribute_loader(self, toload, passive) 

809 

810 # if the loader failed, or this 

811 # instance state didn't have an identity, 

812 # the attributes still might be in the callables 

813 # dict. ensure they are removed. 

814 self.expired_attributes.clear() 

815 

816 return ATTR_WAS_SET 

817 

818 @property 

819 def unmodified(self) -> Set[str]: 

820 """Return the set of keys which have no uncommitted changes""" 

821 

822 return set(self.manager).difference(self.committed_state) 

823 

824 def unmodified_intersection(self, keys: Iterable[str]) -> Set[str]: 

825 """Return self.unmodified.intersection(keys).""" 

826 

827 return ( 

828 set(keys) 

829 .intersection(self.manager) 

830 .difference(self.committed_state) 

831 ) 

832 

833 @property 

834 def unloaded(self) -> Set[str]: 

835 """Return the set of keys which do not have a loaded value. 

836 

837 This includes expired attributes and any other attribute that was never 

838 populated or modified. 

839 

840 """ 

841 return ( 

842 set(self.manager) 

843 .difference(self.committed_state) 

844 .difference(self.dict) 

845 ) 

846 

847 @property 

848 @util.deprecated( 

849 "2.0", 

850 "The :attr:`.InstanceState.unloaded_expirable` attribute is " 

851 "deprecated. Please use :attr:`.InstanceState.unloaded`.", 

852 ) 

853 def unloaded_expirable(self) -> Set[str]: 

854 """Synonymous with :attr:`.InstanceState.unloaded`. 

855 

856 This attribute was added as an implementation-specific detail at some 

857 point and should be considered to be private. 

858 

859 """ 

860 return self.unloaded 

861 

862 @property 

863 def _unloaded_non_object(self) -> Set[str]: 

864 return self.unloaded.intersection( 

865 attr 

866 for attr in self.manager 

867 if self.manager[attr].impl.accepts_scalar_loader 

868 ) 

869 

870 def _modified_event( 

871 self, 

872 dict_: _InstanceDict, 

873 attr: Optional[_AttributeImpl], 

874 previous: Any, 

875 collection: bool = False, 

876 is_userland: bool = False, 

877 ) -> None: 

878 if attr: 

879 if not attr.send_modified_events: 

880 return 

881 if is_userland and attr.key not in dict_: 

882 raise sa_exc.InvalidRequestError( 

883 "Can't flag attribute '%s' modified; it's not present in " 

884 "the object state" % attr.key 

885 ) 

886 if attr.key not in self.committed_state or is_userland: 

887 if collection: 

888 if TYPE_CHECKING: 

889 assert is_collection_impl(attr) 

890 if previous is NEVER_SET: 

891 if attr.key in dict_: 

892 previous = dict_[attr.key] 

893 

894 if previous not in (None, NO_VALUE, NEVER_SET): 

895 previous = attr.copy(previous) 

896 self.committed_state[attr.key] = previous 

897 

898 lkv = self._last_known_values 

899 if lkv is not None and attr.key in lkv: 

900 lkv[attr.key] = NO_VALUE 

901 

902 # assert self._strong_obj is None or self.modified 

903 

904 if (self.session_id and self._strong_obj is None) or not self.modified: 

905 self.modified = True 

906 instance_dict = self._instance_dict() 

907 if instance_dict: 

908 has_modified = bool(instance_dict._modified) 

909 instance_dict._modified.add(self) 

910 else: 

911 has_modified = False 

912 

913 # only create _strong_obj link if attached 

914 # to a session 

915 

916 inst = self.obj() 

917 if self.session_id: 

918 self._strong_obj = inst 

919