[Sqlalchemy-tickets] Issue #3517: Inconsistencies in documentation and code regarding strong referencing guidance (zzzeek/sqlalchemy)

[Allan C. <iss...@bi...>]

New issue 3517: Inconsistencies in documentation and code regarding strong referencing guidance
https://bitbucket.org/zzzeek/sqlalchemy/issues/3517/inconsistencies-in-documentation-and-code

Allan Crooks:

My use case: I recently upgraded a project, which was built using SQLAlchemy 0.3, to SQLAlchemy 1.0. I went from version to version making changes where required. One of the features that the project made use of from SQLA 0.3 was the "objectstore" extension, that provided (amongst other things) object caching.

As part of the update process, I moved to using sessions, and explicitly disabled the weak reference identity map to keep my code compatible. When I started to get warnings because  *weak_identity_map=False*, I stopped passing that parameter. I then realised that it was causing performance issues, as now multiple calls were being made to the database to retrieve the same object, whereas only one call was made previously.

So, I want to be able to have sessions which will persist objects until they are explicitly cleared. The problem is, I see inconsistent advice offered when it comes to object caching.

---

* The documentation [here](http://docs.sqlalchemy.org/rel_1_0/latest/orm/session_state_management.html#session-attributes) explicitly suggests how you should disable weak references if that's your preferred option:
 *"To disable the weak referencing behavior and force all objects within the session to remain until explicitly expunged, configure sessionmaker with the weak_identity_map=False setting.*"
 
The use of it is not discouraged at all.

* The documentation [here](http://docs.sqlalchemy.org/rel_1_0/latest/orm/session_basics.html#is-the-session-a-cache) indicates that, although the Session object is capable of being used as a cache, it's not designed for it.
 
This gives the impression that, while SQLAlchemy does provide an implementation of a cache, alternative options may work better. However, it does not discourage the use of it.

* [This](http://docs.sqlalchemy.org/en/rel_1_0/orm/session_api.html#sqlalchemy.orm.session.Session.params.weak_identity_map) indicates that the option is obsolete.
 
"Obsolete" would indicate that, regardless of the value passed to the flag, it would result in the same behaviour. This isn't true in my case.

* The [generated warning](https://github.com/zzzeek/sqlalchemy/blob/a43b106aa717587f85d0d88c88b7c442104fac24/lib/sqlalchemy/orm/session.py#L492) indicates that the feature isn't needed.
 
As a message, that's unclear what that's saying. Is it saying that SQLAlchemy doesn't need that feature? Perhaps. Is it implying that I don't need that feature? That would be incorrect.

* [This](http://comments.gmane.org/gmane.comp.python.sqlalchemy.user/22960) discussion thread contains more enthusiastic advice that people should avoid using strong identity maps, and maintain a local cache of objects themselves.

This is a strong indication that we should strongly move away from using strong identity maps.

* There is issue #1473, which specifies the deprecation of StrongInstanceDict.
 
However, there aren't any deprecation warnings in the direct usage of StrongInstanceDict itself - so I might infer from that the use of the classes in sqlalchemy.orm.identity are intended for internal use only, and that the *weak_identity_map* flag is meant to be the only way to make use of them.

---

These inconsistencies make it unclear on how to proceed (especially in terms of expectations on how future versions will change the API):
 * Is the caching feature of SQLAlchemy going to be removed altogether?
 * Am I allowed to use StrongInstanceDict, or write my own IdentityMap class?
 * Is SQLAlchemy correct in asserting that the flag is obsolete?
 * Is SQLAlchemy indicating that the feature is unnecessary for its own internal use, or for my intended use?
 * Shouldn't SQLAlchemy generate a warning which suggests to clients how they should make changes to achieve the same effect for future versions?

My ideal solution would be that I could continue using StrongInstanceDict - even if future versions of SQLAlchemy only supported this by allowing a class or factory function to return an instance of an object to use as an identity map (so allow any identity map implementation to be used, rather than only talking in terms of weak vs strong references).