ansible-core 2.16.7rc1__py3-none-any.whl → 2.17.0__py3-none-any.whl

ansible/modules/set_fact.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2013, Dag Wieers (@dagwieers) <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/set_stats.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2016, Ansible RedHat, Inc
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/setup.py

@@ -3,8 +3,7 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''

ansible/modules/shell.py

@@ -7,8 +7,7 @@
 # it runs the 'command' module with special arguments and it behaves differently.
 # See the command source and the comment "#USE_SHELL".
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/slurp.py

@@ -3,8 +3,7 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/stat.py

@@ -2,8 +2,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/subversion.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -142,7 +141,7 @@ from ansible.module_utils.compat.version import LooseVersion
 class Subversion(object):
 
     # Example text matched by the regexp:
-    #  Révision : 1889134
+    #  Révision : 1889134
     #  版本: 1889134
     #  Revision: 1889134
     REVISION_RE = r'^\w+\s?:\s+\d+$'

ansible/modules/systemd.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2016, Brian Coca <bcoca@ansible.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -15,6 +14,8 @@ version_added: "2.2"
 short_description:  Manage systemd units
 description:
     - Controls systemd units (services, timers, and so on) on remote hosts.
+    - M(ansible.builtin.systemd) is renamed to M(ansible.builtin.systemd_service) to better reflect the scope of the module.
+      M(ansible.builtin.systemd) is kept as an alias for backward compatibility.
 options:
     name:
         description:
@@ -28,11 +29,13 @@ options:
             - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
               V(restarted) will always bounce the unit.
               V(reloaded) will always reload and if the service is not running at the moment of the reload, it is started.
+            - If set, requires O(name).
         type: str
         choices: [ reloaded, restarted, started, stopped ]
     enabled:
         description:
             - Whether the unit should start on boot. B(At least one of state and enabled are required.)
+            - If set, requires O(name).
         type: bool
     force:
         description:
@@ -41,7 +44,8 @@ options:
         version_added: 2.6
     masked:
         description:
-            - Whether the unit should be masked or not, a masked unit is impossible to start.
+            - Whether the unit should be masked or not. A masked unit is impossible to start.
+            - If set, requires O(name).
         type: bool
     daemon_reload:
         description:
@@ -64,7 +68,7 @@ options:
             - "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
             - "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
               Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
-            - The user must have access, normally given via setting the C(XDG_RUNTIME_DIR) variable, see example below.
+            - The user must have access, normally given via setting the C(XDG_RUNTIME_DIR) variable, see the example below.
 
         type: str
         choices: [ system, user, global ]
@@ -86,12 +90,11 @@ attributes:
     platform:
         platforms: posix
 notes:
-    - Since 2.4, one of the following options is required O(state), O(enabled), O(masked), O(daemon_reload), (O(daemon_reexec) since 2.8),
-      and all except O(daemon_reload) and (O(daemon_reexec) since 2.8) also require O(name).
+    - O(state), O(enabled), O(masked) requires O(name).
     - Before 2.4 you always required O(name).
-    - Globs are not supported in name, i.e C(postgres*.service).
-    - The service names might vary by specific OS/distribution
-    - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with service state.
+    - Globs are not supported in name, in other words, C(postgres*.service).
+    - The service names might vary by specific OS/distribution.
+    - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with the service state.
       It has been reported that systemctl can behave differently depending on the order of operations if you do the same manually.
 requirements:
     - A system managed by systemd.

ansible/modules/systemd_service.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2016, Brian Coca <bcoca@ansible.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -15,6 +14,8 @@ version_added: "2.2"
 short_description:  Manage systemd units
 description:
     - Controls systemd units (services, timers, and so on) on remote hosts.
+    - M(ansible.builtin.systemd) is renamed to M(ansible.builtin.systemd_service) to better reflect the scope of the module.
+      M(ansible.builtin.systemd) is kept as an alias for backward compatibility.
 options:
     name:
         description:
@@ -28,11 +29,13 @@ options:
             - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
               V(restarted) will always bounce the unit.
               V(reloaded) will always reload and if the service is not running at the moment of the reload, it is started.
+            - If set, requires O(name).
         type: str
         choices: [ reloaded, restarted, started, stopped ]
     enabled:
         description:
             - Whether the unit should start on boot. B(At least one of state and enabled are required.)
+            - If set, requires O(name).
         type: bool
     force:
         description:
@@ -41,7 +44,8 @@ options:
         version_added: 2.6
     masked:
         description:
-            - Whether the unit should be masked or not, a masked unit is impossible to start.
+            - Whether the unit should be masked or not. A masked unit is impossible to start.
+            - If set, requires O(name).
         type: bool
     daemon_reload:
         description:
@@ -64,7 +68,7 @@ options:
             - "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
             - "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
               Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
-            - The user must have access, normally given via setting the C(XDG_RUNTIME_DIR) variable, see example below.
+            - The user must have access, normally given via setting the C(XDG_RUNTIME_DIR) variable, see the example below.
 
         type: str
         choices: [ system, user, global ]
@@ -86,12 +90,11 @@ attributes:
     platform:
         platforms: posix
 notes:
-    - Since 2.4, one of the following options is required O(state), O(enabled), O(masked), O(daemon_reload), (O(daemon_reexec) since 2.8),
-      and all except O(daemon_reload) and (O(daemon_reexec) since 2.8) also require O(name).
+    - O(state), O(enabled), O(masked) requires O(name).
     - Before 2.4 you always required O(name).
-    - Globs are not supported in name, i.e C(postgres*.service).
-    - The service names might vary by specific OS/distribution
-    - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with service state.
+    - Globs are not supported in name, in other words, C(postgres*.service).
+    - The service names might vary by specific OS/distribution.
+    - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with the service state.
       It has been reported that systemctl can behave differently depending on the order of operations if you do the same manually.
 requirements:
     - A system managed by systemd.

ansible/modules/sysvinit.py

@@ -4,8 +4,7 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -87,6 +86,12 @@ EXAMPLES = '''
       state: started
       enabled: yes
 
+- name: Sleep for 5 seconds between stop and start command of badly behaving service
+  ansible.builtin.sysvinit:
+    name: apache2
+    state: restarted
+    sleep: 5
+
 - name: Make sure apache2 is started on runlevels 3 and 5
   ansible.builtin.sysvinit:
       name: apache2

ansible/modules/tempfile.py

@@ -4,8 +4,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -68,6 +67,12 @@ EXAMPLES = """
     suffix: temp
   register: tempfile_1
 
+- name: Create a temporary file with a specific prefix
+  ansible.builtin.tempfile:
+     state: file
+     suffix: txt
+     prefix: myfile_
+
 - name: Use the registered var and the file module to remove the temporary file
   ansible.builtin.file:
     path: "{{ tempfile_1.path }}"

ansible/modules/template.py

@@ -5,8 +5,7 @@
 
 # This is a virtual module that is entirely implemented as an action plugin and runs on the controller
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -86,7 +85,7 @@ EXAMPLES = r'''
     dest: /etc/named.conf
     group: named
     setype: named_conf_t
-    mode: 0640
+    mode: '0640'
 
 - name: Create a DOS-style text file from a template
   ansible.builtin.template:

ansible/modules/unarchive.py

@@ -7,8 +7,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -283,6 +282,7 @@ MISSING_FILE_RE = re.compile(r': Warning: Cannot stat: No such file or directory
 ZIP_FILE_MODE_RE = re.compile(r'([r-][w-][SsTtx-]){3}')
 INVALID_OWNER_RE = re.compile(r': Invalid owner')
 INVALID_GROUP_RE = re.compile(r': Invalid group')
+SYMLINK_DIFF_RE = re.compile(r': Symlink differs$')
 
 
 def crc32(path, buffer_size):
@@ -500,7 +500,8 @@ class ZipArchive(object):
                 continue
 
             # Check first and seventh field in order to skip header/footer
-            if len(pcs[0]) != 7 and len(pcs[0]) != 10:
+            # 7 or 8 are FAT, 10 is normal unix perms
+            if len(pcs[0]) not in (7, 8, 10):
                 continue
             if len(pcs[6]) != 15:
                 continue
@@ -552,6 +553,12 @@ class ZipArchive(object):
                 else:
                     permstr = 'rw-rw-rw-'
                 file_umask = umask
+            elif len(permstr) == 7:
+                if permstr == 'rwxa---':
+                    permstr = 'rwxrwxrwx'
+                else:
+                    permstr = 'rw-rw-rw-'
+                file_umask = umask
             elif 'bsd' in systemtype.lower():
                 file_umask = umask
             else:
@@ -880,6 +887,8 @@ class TgzArchive(object):
                 out += line + '\n'
             if INVALID_GROUP_RE.search(line):
                 out += line + '\n'
+            if SYMLINK_DIFF_RE.search(line):
+                out += line + '\n'
         if out:
             unarchived = False
         return dict(unarchived=unarchived, rc=rc, out=out, err=err, cmd=cmd)
@@ -969,6 +978,7 @@ class TarZstdArchive(TgzArchive):
 class ZipZArchive(ZipArchive):
     def __init__(self, src, b_dest, file_args, module):
         super(ZipZArchive, self).__init__(src, b_dest, file_args, module)
+        # NOTE: adds 'l', which is default on most linux but not all implementations
         self.zipinfoflag = '-Zl'
         self.binaries = (
             ('unzip', 'cmd_path'),

ansible/modules/uri.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2013, Romeo Theriault <romeot () hawaii.edu>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -109,13 +108,13 @@ options:
   follow_redirects:
     description:
       - Whether or not the URI module should follow redirects.
-      - V(all) Will follow all redirects.
-      - V(none) Will not follow any redirects.
-      - V(safe) Only redirects doing GET or HEAD requests will be followed.
-      - V(urllib2) Defer to urllib2 behavior (As of writing this follows HTTP redirects).
-      - V('no') (DEPRECATED, will be removed in the future version) alias of V(none).
-      - V('yes') (DEPRECATED, will be removed in the future version) alias of V(all).
-    choices: ['all', 'none', 'safe', 'urllib2', 'yes', 'no']
+    choices:
+      all: Will follow all redirects.
+      none: Will not follow any redirects.
+      safe: Only redirects doing GET or HEAD requests will be followed.
+      urllib2: Defer to urllib2 behavior (As of writing this follows HTTP redirects).
+      'no': (DEPRECATED, will be removed in the future version) alias of V(none).
+      'yes': (DEPRECATED, will be removed in the future version) alias of V(all).
     type: str
     default: safe
   creates:
@@ -445,11 +444,10 @@ import json
 import os
 import re
 import shutil
-import sys
 import tempfile
 
 from ansible.module_utils.basic import AnsibleModule, sanitize_keys
-from ansible.module_utils.six import PY2, PY3, binary_type, iteritems, string_types
+from ansible.module_utils.six import binary_type, iteritems, string_types
 from ansible.module_utils.six.moves.urllib.parse import urlencode, urlsplit
 from ansible.module_utils.common.text.converters import to_native, to_text
 from ansible.module_utils.compat.datetime import utcnow, utcfromtimestamp
@@ -587,7 +585,7 @@ def uri(module, url, dest, body, body_format, method, headers, socket_timeout, c
                            method=method, timeout=socket_timeout, unix_socket=module.params['unix_socket'],
                            ca_path=ca_path, unredirected_headers=unredirected_headers,
                            use_proxy=module.params['use_proxy'], decompress=decompress,
-                           ciphers=ciphers, use_netrc=use_netrc, **kwargs)
+                           ciphers=ciphers, use_netrc=use_netrc, force=module.params['force'], **kwargs)
 
     if src:
         # Try to close the open file handle
@@ -721,7 +719,7 @@ def main():
 
     if maybe_output:
         try:
-            if PY3 and (r.fp is None or r.closed):
+            if r.fp is None or r.closed:
                 raise TypeError
             content = r.read()
         except (AttributeError, TypeError):
@@ -772,8 +770,7 @@ def main():
                 js = json.loads(u_content)
                 uresp['json'] = js
             except Exception:
-                if PY2:
-                    sys.exc_clear()  # Avoid false positive traceback in fail_json() on Python 2
+                ...
     else:
         u_content = None
 

ansible/modules/user.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Stephen Fromm <sfromm@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -73,8 +72,8 @@ options:
             - Optionally set the user's shell.
             - On macOS, before Ansible 2.5, the default shell for non-system users was V(/usr/bin/false).
               Since Ansible 2.5, the default shell for non-system users on macOS is V(/bin/bash).
-            - See notes for details on how other operating systems determine the default shell by
-              the underlying tool.
+            - On other operating systems, the default shell is determined by the underlying tool
+              invoked by this module. See Notes for a per platform list of invoked tools.
         type: str
     home:
         description:
@@ -306,6 +305,11 @@ EXAMPLES = r'''
     uid: 1040
     group: admin
 
+- name: Create a user 'johnd' with a home directory
+  ansible.builtin.user:
+    name: johnd
+    create_home: yes
+
 - name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups
   ansible.builtin.user:
     name: james
@@ -632,6 +636,9 @@ class User(object):
                         # sha512
                         if fields[1] == '6' and len(fields[-1]) != 86:
                             maybe_invalid = True
+                        # yescrypt
+                        if fields[1] == 'y' and len(fields[-1]) != 43:
+                            maybe_invalid = True
                     else:
                         maybe_invalid = True
             if maybe_invalid:

ansible/modules/validate_argument_spec.py

@@ -3,8 +3,7 @@
 # Copyright 2021 Red Hat
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -52,32 +51,32 @@ attributes:
 EXAMPLES = r'''
 - name: verify vars needed for this task file are present when included
   ansible.builtin.validate_argument_spec:
-        argument_spec: '{{required_data}}'
+        argument_spec: '{{ required_data }}'
   vars:
     required_data:
-        # unlike spec file, just put the options in directly
-        stuff:
-            description: stuff
-            type: str
-            choices: ['who', 'knows', 'what']
-            default: what
-        but:
-            description: i guess we need one
-            type: str
-            required: true
+      # unlike spec file, just put the options in directly
+      stuff:
+        description: stuff
+        type: str
+        choices: ['who', 'knows', 'what']
+        default: what
+      but:
+        description: i guess we need one
+        type: str
+        required: true
 
 
 - name: verify vars needed for this task file are present when included, with spec from a spec file
   ansible.builtin.validate_argument_spec:
-        argument_spec: "{{(lookup('ansible.builtin.file', 'myargspec.yml') | from_yaml )['specname']['options']}}"
+    argument_spec: "{{ (lookup('ansible.builtin.file', 'myargspec.yml') | from_yaml )['specname']['options'] }}"
 
 
 - name: verify vars needed for next include and not from inside it, also with params i'll only define there
   block:
     - ansible.builtin.validate_argument_spec:
-        argument_spec: "{{lookup('ansible.builtin.file', 'nakedoptions.yml'}}"
+        argument_spec: "{{ lookup('ansible.builtin.file', 'nakedoptions.yml') }}"
         provided_arguments:
-            but: "that i can define on the include itself, like in it's `vars:` keyword"
+          but: "that i can define on the include itself, like in it's `vars:` keyword"
 
     - name: the include itself
       vars:

ansible/modules/wait_for.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Jeroen Hoekx <jeroen@hoekx.be>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/wait_for_connection.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/yum_repository.py

@@ -4,8 +4,7 @@
 #
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -67,7 +66,7 @@ options:
     type: str
   description:
     description:
-      - A human readable string describing the repository. This option corresponds to the "name" property in the repo file.
+      - A human-readable string describing the repository. This option corresponds to the "name" property in the repo file.
       - This parameter is only required if O(state) is set to V(present).
     type: str
   enabled:

ansible/parsing/__init__.py

@@ -15,6 +15,4 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations

ansible/parsing/ajson.py

@@ -1,9 +1,7 @@
 # Copyright: (c) 2018, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
 
 import json
 

ansible/parsing/dataloader.py

@@ -2,9 +2,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
 
 import copy
 import os
@@ -79,30 +77,43 @@ class DataLoader:
         '''Backwards compat for now'''
         return from_yaml(data, file_name, show_content, self._vault.secrets, json_only=json_only)
 
-    def load_from_file(self, file_name: str, cache: bool = True, unsafe: bool = False, json_only: bool = False) -> t.Any:
-        ''' Loads data from a file, which can contain either JSON or YAML.  '''
+    def load_from_file(self, file_name: str, cache: str = 'all', unsafe: bool = False, json_only: bool = False) -> t.Any:
+        '''
+        Loads data from a file, which can contain either JSON or YAML.
+
+        :param file_name: The name of the file to load data from.
+        :param cache: Options for caching: none|all|vaulted
+        :param unsafe: If True, returns the parsed data as-is without deep copying.
+        :param json_only: If True, only loads JSON data from the file.
+        :return: The loaded data, optionally deep-copied for safety.
+        '''
 
+        # Resolve the file name
         file_name = self.path_dwim(file_name)
+
+        # Log the file being loaded
         display.debug("Loading data from %s" % file_name)
 
-        # if the file has already been read in and cached, we'll
-        # return those results to avoid more file/vault operations
-        if cache and file_name in self._FILE_CACHE:
+        # Check if the file has been cached and use the cached data if available
+        if cache != 'none' and file_name in self._FILE_CACHE:
             parsed_data = self._FILE_CACHE[file_name]
         else:
-            # read the file contents and load the data structure from them
+            # Read the file contents and load the data structure from them
             (b_file_data, show_content) = self._get_file_contents(file_name)
 
             file_data = to_text(b_file_data, errors='surrogate_or_strict')
             parsed_data = self.load(data=file_data, file_name=file_name, show_content=show_content, json_only=json_only)
 
-            # cache the file contents for next time
-            self._FILE_CACHE[file_name] = parsed_data
+            # Cache the file contents for next time based on the cache option
+            if cache == 'all':
+                self._FILE_CACHE[file_name] = parsed_data
+            elif cache == 'vaulted' and not show_content:
+                self._FILE_CACHE[file_name] = parsed_data
 
+        # Return the parsed data, optionally deep-copied for safety
         if unsafe:
             return parsed_data
         else:
-            # return a deep copy here, so the cache is not affected
             return copy.deepcopy(parsed_data)
 
     def path_exists(self, path: str) -> bool: