improve NO_VALUE and CacheRegion.get()

Fixed the return type for :meth:`.CacheRegion.get`, which was inadvertently
hardcoded to use ``CacheReturnType`` that only resolved to ``CachedValue``
or ``NoValue``.   Fixed to return ``ValuePayload`` which resolves to
``Any``, as well as a new literal indicating an enum constant for
:data:`.api.NO_VALUE`.  The :data:`.api.NO_VALUE` constant remains
available as the single element of this enum.

References: 074cb77#r141358374
Change-Id: I5755736da6d2529c77edc29a0dafe3e67bc419e5

Author: zzzeek

docs/build/unreleased/fix_get_type.rst

@@ -0,0 +1,9 @@
+.. change::
+    :tags: bug, typing
+
+    Fixed the return type for :meth:`.CacheRegion.get`, which was inadvertently
+    hardcoded to use ``CacheReturnType`` that only resolved to ``CachedValue``
+    or ``NoValue``.   Fixed to return ``ValuePayload`` which resolves to
+    ``Any``, as well as a new literal indicating an enum constant for
+    :data:`.api.NO_VALUE`.  The :data:`.api.NO_VALUE` constant remains
+    available as the single element of this enum.

dogpile/cache/api.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import abc
+import enum
 import pickle
 import time
 from typing import Any
 from typing import Callable
 from typing import cast
+from typing import Literal
 from typing import Mapping
 from typing import NamedTuple
 from typing import Optional
@@ -15,7 +17,7 @@
 from ..util.typing import Self
 
 
-class NoValue:
+class NoValue(enum.Enum):
     """Describe a missing cache value.
 
     The :data:`.NO_VALUE` constant should be used.
@@ -33,12 +35,16 @@ def __repr__(self):
         """
         return "<dogpile.cache.api.NoValue object>"
 
-    def __bool__(self):  # pragma NO COVERAGE
+    def __bool__(self) -> Literal[False]:  # pragma NO COVERAGE
         return False
 
+    NO_VALUE = "NoValue"
 
-NO_VALUE = NoValue()
-"""Value returned from ``get()`` that describes
+
+NoValueType = Literal[NoValue.NO_VALUE]
+
+NO_VALUE = NoValue.NO_VALUE
+"""Value returned from :meth:`.CacheRegion.get` that describes
 a  key not present."""
 
 MetaDataType = Mapping[str, Any]
@@ -160,13 +166,13 @@ def age(self) -> float:
         return time.time() - self.cached_time
 
 
-CacheReturnType = Union[CachedValue, NoValue]
+CacheReturnType = Union[CachedValue, NoValueType]
 """The non-serialized form of what may be returned from a backend
 get method.
 
 """
 
-SerializedReturnType = Union[bytes, NoValue]
+SerializedReturnType = Union[bytes, NoValueType]
 """the serialized form of what may be returned from a backend get method."""
 
 BackendFormatted = Union[CacheReturnType, SerializedReturnType]

dogpile/cache/region.py

@@ -32,6 +32,7 @@
 from .api import KeyType
 from .api import MetaDataType
 from .api import NO_VALUE
+from .api import NoValueType
 from .api import SerializedReturnType
 from .api import Serializer
 from .api import ValuePayload
@@ -706,19 +707,20 @@ def get(
         key: KeyType,
         expiration_time: Optional[float] = None,
         ignore_expiration: bool = False,
-    ) -> CacheReturnType:
+    ) -> Union[ValuePayload, NoValueType]:
         """Return a value from the cache, based on the given key.
 
         If the value is not present, the method returns the token
-        ``NO_VALUE``. ``NO_VALUE`` evaluates to False, but is separate from
-        ``None`` to distinguish between a cached value of ``None``.
+        :data:`.api.NO_VALUE`. :data:`.api.NO_VALUE` evaluates to False, but is
+        separate from ``None`` to distinguish between a cached value of
+        ``None``.
 
         By default, the configured expiration time of the
         :class:`.CacheRegion`, or alternatively the expiration
         time supplied by the ``expiration_time`` argument,
         is tested against the creation time of the retrieved
         value versus the current time (as reported by ``time.time()``).
-        If stale, the cached value is ignored and the ``NO_VALUE``
+        If stale, the cached value is ignored and the :data:`.api.NO_VALUE`
         token is returned.  Passing the flag ``ignore_expiration=True``
         bypasses the expiration time check.
 
@@ -731,7 +733,7 @@ def get(
         of the current "invalidation" time as set by
         the :meth:`.invalidate` method.   If a value is present,
         but its creation time is older than the current
-        invalidation time, the ``NO_VALUE`` token is returned.
+        invalidation time, the :data:`.api.NO_VALUE` token is returned.
         Passing the flag ``ignore_expiration=True`` bypasses
         the invalidation time check.
 
@@ -1083,7 +1085,7 @@ def go():
                         return creator(*ca[0], **ca[1])
 
                 else:
-                    go = creator
+                    go = creator  # type: ignore
                 return acr(self, orig_key, go, mutex)
 
         else:

setup.cfg

@@ -2,7 +2,7 @@
 enable-extensions = G
 # E203 is due to https://github.com/PyCQA/pycodestyle/issues/373
 ignore =
-    A003,
+    A003,A005
     D,
     E203,E305,E711,E712,E721,E722,E741,
     N801,N802,N806,

tests/cache/test_region.py

@@ -30,7 +30,7 @@ def key_mangler(key):
 
 class APITest:
     def test_no_value_str(self):
-        eq_(str(NO_VALUE), "<dogpile.cache.api.NoValue object>")
+        eq_(str(NO_VALUE), "NoValue.NO_VALUE")
 
 
 class RegionTest: