From 1b4ab2d3e08b9fe606bf723299f815207dacceaa Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 19 Feb 2019 13:02:16 -0500
Subject: [PATCH] Note that get/get_or_create expiration_time is transitory

Also add some new seealso links, fix formatting.

Fixes: #143
Change-Id: Iedb48561ba7c9e9059b66279dd77c14223528b59
---
 dogpile/cache/region.py | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/dogpile/cache/region.py b/dogpile/cache/region.py
index 261a8db..7a8d610 100644
--- a/dogpile/cache/region.py
+++ b/dogpile/cache/region.py
@@ -650,6 +650,13 @@ def get(self, key, expiration_time=None, ignore_expiration=False):
          which will supersede that configured on the :class:`.CacheRegion`
          itself.
 
+         .. note:: The :paramref:`.CacheRegion.get.expiration_time`
+            argument is **not persisted in the cache** and is relevant
+            only to **this specific cache retrieval operation**, relative to
+            the creation time stored with the existing cached value.
+            Subsequent calls to :meth:`.CacheRegion.get` are **not** affected
+            by this value.
+
          .. versionadded:: 0.3.0
 
         :param ignore_expiration: if ``True``, the value is returned
@@ -659,6 +666,17 @@ def get(self, key, expiration_time=None, ignore_expiration=False):
 
          .. versionadded:: 0.3.0
 
+        .. seealso::
+
+            :meth:`.CacheRegion.get_multi`
+
+            :meth:`.CacheRegion.get_or_create`
+
+            :meth:`.CacheRegion.set`
+
+            :meth:`.CacheRegion.delete`
+
+
         """
 
         if self.key_mangler:
@@ -790,6 +808,13 @@ def get_or_create(
          the expiration time already configured on this :class:`.CacheRegion`
          if not None.   To set no expiration, use the value -1.
 
+         .. note:: The :paramref:`.CacheRegion.get_or_create.expiration_time`
+            argument is **not persisted in the cache** and is relevant
+            only to **this specific cache retrieval operation**, relative to
+            the creation time stored with the existing cached value.
+            Subsequent calls to :meth:`.CacheRegion.get_or_create` are **not**
+            affected by this value.
+
         :param should_cache_fn: optional callable function which will receive
          the value returned by the "creator", and will then return True or
          False, indicating if the value should actually be cached or not.  If
@@ -811,11 +836,13 @@ def dont_cache_none(value):
 
         .. seealso::
 
+            :meth:`.CacheRegion.get`
+
             :meth:`.CacheRegion.cache_on_arguments` - applies
             :meth:`.get_or_create` to any function using a decorator.
 
             :meth:`.CacheRegion.get_or_create_multi` - multiple key/value
-             version
+            version
 
         """
         orig_key = key