diff --git a/msal_extensions/token_cache.py b/msal_extensions/token_cache.py index e3bbea3..ecd66f0 100644 --- a/msal_extensions/token_cache.py +++ b/msal_extensions/token_cache.py @@ -15,7 +15,30 @@ logger = logging.getLogger(__name__) class PersistedTokenCache(msal.SerializableTokenCache): - """A token cache using given persistence layer, coordinated by a file lock.""" + """A token cache backed by a persistence layer, coordinated by a file lock, + to sustain a certain level of multi-process concurrency for a desktop app. + + The scenario is that multiple instances of same desktop app + (or even multiple different apps) + create their own ``PersistedTokenCache`` instances, + which are all backed by the same token cache file on disk + (known as a persistence). The goal is to have Single Sign On (SSO). + + Each instance of ``PersistedTokenCache`` holds a snapshot of the token cache + in memory. + Each :func:`~find` call will + automatically reload token cache from the persistence when necessary, + so that it will have fresh data. + Each :func:`~modify` call will + automatically reload token cache from the persistence when necessary, + so that new writes will be appended on top of latest token cache data, + and then the new data will be immediately flushed back to the persistence. + + Note: :func:`~deserialize` and :func:`~serialize` remain the same + as their counterparts in the parent class ``msal.SerializableTokenCache``. + In other words, they do not have the "reload from persistence if necessary" + nor the "flush back to persistence" behavior. + """ def __init__(self, persistence, lock_location=None): super(PersistedTokenCache, self).__init__()