ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/plugins/cache/__init__.py

@@ -22,14 +22,15 @@ import errno
 import os
 import tempfile
 import time
+import typing as t
 
 from abc import abstractmethod
-from collections.abc import MutableMapping
+from collections import abc as c
 
 from ansible import constants as C
 from ansible.errors import AnsibleError
 from ansible.module_utils.common.file import S_IRWU_RG_RO
-from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.module_utils.common.text.converters import to_bytes
 from ansible.plugins import AnsiblePlugin
 from ansible.plugins.loader import cache_loader
 from ansible.utils.collection_loader import resource_from_fqcr
@@ -42,37 +43,36 @@ class BaseCacheModule(AnsiblePlugin):
 
     # Backwards compat only.  Just import the global display instead
     _display = display
+    _persistent = True
+    """Plugins that do not persist data between runs can set False to bypass schema-version key munging and JSON serialization wrapper."""
 
-    def __init__(self, *args, **kwargs):
-        super(BaseCacheModule, self).__init__()
-        self.set_options(var_options=args, direct=kwargs)
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__()
 
-    @abstractmethod
-    def get(self, key):
-        pass
+        self.set_options(var_options=args, direct=kwargs)
 
     @abstractmethod
-    def set(self, key, value):
+    def get(self, key: str) -> dict[str, object]:
         pass
 
     @abstractmethod
-    def keys(self):
+    def set(self, key: str, value: dict[str, object]) -> None:
         pass
 
     @abstractmethod
-    def contains(self, key):
+    def keys(self) -> t.Sequence[str]:
         pass
 
     @abstractmethod
-    def delete(self, key):
+    def contains(self, key: object) -> bool:
         pass
 
     @abstractmethod
-    def flush(self):
+    def delete(self, key: str) -> None:
         pass
 
     @abstractmethod
-    def copy(self):
+    def flush(self) -> None:
         pass
 
 
@@ -116,7 +116,7 @@ class BaseFileCacheModule(BaseCacheModule):
                     raise AnsibleError("error in '%s' cache, configured path (%s) does not have necessary permissions (rwx), disabling plugin" % (
                         self.plugin_name, self._cache_dir))
 
-    def _get_cache_file_name(self, key):
+    def _get_cache_file_name(self, key: str) -> str:
         prefix = self.get_option('_prefix')
         if prefix:
             cachefile = "%s/%s%s" % (self._cache_dir, prefix, key)
@@ -144,11 +144,10 @@ class BaseFileCacheModule(BaseCacheModule):
                 self.delete(key)
                 raise AnsibleError("The cache file %s was corrupt, or did not otherwise contain valid data. "
                                    "It has been removed, so you can re-run your command now." % cachefile)
-            except (OSError, IOError) as e:
-                display.warning("error in '%s' cache plugin while trying to read %s : %s" % (self.plugin_name, cachefile, to_bytes(e)))
+            except FileNotFoundError:
                 raise KeyError
-            except Exception as e:
-                raise AnsibleError("Error while decoding the cache file %s: %s" % (cachefile, to_bytes(e)))
+            except Exception as ex:
+                raise AnsibleError(f"Error while accessing the cache file {cachefile!r}.") from ex
 
         return self._cache.get(key)
 
@@ -245,14 +244,8 @@ class BaseFileCacheModule(BaseCacheModule):
         for key in self.keys():
             self.delete(key)
 
-    def copy(self):
-        ret = dict()
-        for key in self.keys():
-            ret[key] = self.get(key)
-        return ret
-
     @abstractmethod
-    def _load(self, filepath):
+    def _load(self, filepath: str) -> object:
         """
         Read data from a filepath and return it as a value
 
@@ -271,7 +264,7 @@ class BaseFileCacheModule(BaseCacheModule):
         pass
 
     @abstractmethod
-    def _dump(self, value, filepath):
+    def _dump(self, value: object, filepath: str) -> None:
         """
         Write data to a filepath
 
@@ -281,19 +274,13 @@ class BaseFileCacheModule(BaseCacheModule):
         pass
 
 
-class CachePluginAdjudicator(MutableMapping):
-    """
-    Intermediary between a cache dictionary and a CacheModule
-    """
+class CachePluginAdjudicator(c.MutableMapping):
+    """Batch update wrapper around a cache plugin."""
+
     def __init__(self, plugin_name='memory', **kwargs):
         self._cache = {}
         self._retrieved = {}
-
         self._plugin = cache_loader.get(plugin_name, **kwargs)
-        if not self._plugin:
-            raise AnsibleError('Unable to load the cache plugin (%s).' % plugin_name)
-
-        self._plugin_name = plugin_name
 
     def update_cache_if_changed(self):
         if self._retrieved != self._cache:
@@ -302,6 +289,7 @@ class CachePluginAdjudicator(MutableMapping):
     def set_cache(self):
         for top_level_cache_key in self._cache.keys():
             self._plugin.set(top_level_cache_key, self._cache[top_level_cache_key])
+
         self._retrieved = copy.deepcopy(self._cache)
 
     def load_whole_cache(self):
@@ -309,7 +297,7 @@ class CachePluginAdjudicator(MutableMapping):
             self._cache[key] = self._plugin.get(key)
 
     def __repr__(self):
-        return to_text(self._cache)
+        return repr(self._cache)
 
     def __iter__(self):
         return iter(self.keys())
@@ -319,13 +307,10 @@ class CachePluginAdjudicator(MutableMapping):
 
     def _do_load_key(self, key):
         load = False
-        if all([
-            key not in self._cache,
-            key not in self._retrieved,
-            self._plugin_name != 'memory',
-            self._plugin.contains(key),
-        ]):
+
+        if key not in self._cache and key not in self._retrieved and self._plugin._persistent and self._plugin.contains(key):
             load = True
+
         return load
 
     def __getitem__(self, key):
@@ -336,16 +321,18 @@ class CachePluginAdjudicator(MutableMapping):
                 pass
             else:
                 self._retrieved[key] = self._cache[key]
+
         return self._cache[key]
 
     def get(self, key, default=None):
         if self._do_load_key(key):
             try:
                 self._cache[key] = self._plugin.get(key)
-            except KeyError as e:
+            except KeyError:
                 pass
             else:
                 self._retrieved[key] = self._cache[key]
+
         return self._cache.get(key, default)
 
     def items(self):
@@ -360,6 +347,7 @@ class CachePluginAdjudicator(MutableMapping):
     def pop(self, key, *args):
         if args:
             return self._cache.pop(key, args[0])
+
         return self._cache.pop(key)
 
     def __delitem__(self, key):
@@ -368,6 +356,9 @@ class CachePluginAdjudicator(MutableMapping):
     def __setitem__(self, key, value):
         self._cache[key] = value
 
+    def clear(self):
+        self.flush()
+
     def flush(self):
         self._plugin.flush()
         self._cache = {}

ansible/plugins/cache/base.py

@@ -18,3 +18,11 @@ from __future__ import annotations
 
 # moved actual classes to __init__ kept here for backward compat with 3rd parties
 from ansible.plugins.cache import BaseCacheModule, BaseFileCacheModule  # pylint: disable=unused-import
+
+from ansible.utils.display import Display as _Display
+
+_Display().deprecated(
+    msg="The `ansible.plugins.cache.base` Python module is deprecated.",
+    help_text="Import from `ansible.plugins.cache` instead.",
+    version="2.23",
+)

ansible/plugins/cache/jsonfile.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: jsonfile
     short_description: JSON formatted files.
     description:
@@ -38,25 +38,19 @@ DOCUMENTATION = '''
           - key: fact_caching_timeout
             section: defaults
         type: integer
-'''
+"""
 
-import codecs
 import json
+import pathlib
 
-from ansible.parsing.ajson import AnsibleJSONEncoder, AnsibleJSONDecoder
 from ansible.plugins.cache import BaseFileCacheModule
 
 
 class CacheModule(BaseFileCacheModule):
-    """
-    A caching module backed by json files.
-    """
-
-    def _load(self, filepath):
-        # Valid JSON is always UTF-8 encoded.
-        with codecs.open(filepath, 'r', encoding='utf-8') as f:
-            return json.load(f, cls=AnsibleJSONDecoder)
-
-    def _dump(self, value, filepath):
-        with codecs.open(filepath, 'w', encoding='utf-8') as f:
-            f.write(json.dumps(value, cls=AnsibleJSONEncoder, sort_keys=True, indent=4))
+    """A caching module backed by json files."""
+
+    def _load(self, filepath: str) -> object:
+        return json.loads(pathlib.Path(filepath).read_text())
+
+    def _dump(self, value: object, filepath: str) -> None:
+        pathlib.Path(filepath).write_text(json.dumps(value))

ansible/plugins/cache/memory.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: memory
     short_description: RAM backed, non persistent
     description:
@@ -14,18 +14,21 @@ DOCUMENTATION = '''
         - There are no options to configure.
     version_added: historical
     author: core team (@ansible-core)
-'''
+"""
 
 from ansible.plugins.cache import BaseCacheModule
 
 
 class CacheModule(BaseCacheModule):
+    _persistent = False  # prevent unnecessary JSON serialization and key munging
 
     def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
         self._cache = {}
 
     def get(self, key):
-        return self._cache.get(key)
+        return self._cache[key]
 
     def set(self, key, value):
         self._cache[key] = value
@@ -41,12 +44,3 @@ class CacheModule(BaseCacheModule):
 
     def flush(self):
         self._cache = {}
-
-    def copy(self):
-        return self._cache.copy()
-
-    def __getstate__(self):
-        return self.copy()
-
-    def __setstate__(self, data):
-        self._cache = data