ansible-core 2.19.2rc1__py3-none-any.whl → 2.20.0b1__py3-none-any.whl

ansible/utils/plugin_docs.py

@@ -11,13 +11,14 @@ import yaml
 from ansible import constants as C
 from ansible.release import __version__ as ansible_version
 from ansible.errors import AnsibleError, AnsibleParserError, AnsiblePluginNotFound
-from ansible.module_utils.six import string_types
+from ansible.module_utils._internal import _no_six
 from ansible.module_utils.common.text.converters import to_native
 from ansible.parsing.plugin_docs import read_docstring
 from ansible.parsing.yaml.loader import AnsibleLoader
 from ansible.utils.display import Display
 from ansible._internal._datatag import _tags
 
+_FRAGMENTABLE = ('DOCUMENTATION', 'RETURN')
 display = Display()
 
 
@@ -125,23 +126,30 @@ def remove_current_collection_from_versions_and_dates(fragment, collection_name,
     _process_versions_and_dates(fragment, is_module, return_docs, remove)
 
 
-def add_fragments(doc, filename, fragment_loader, is_module=False):
+class AnsibleFragmentError(AnsibleError):
+    pass
+
+
+def add_fragments(doc, filename, fragment_loader, is_module=False, section='DOCUMENTATION'):
+
+    if section not in _FRAGMENTABLE:
+        raise AnsibleError(f"Invalid fragment section ({section}) passed to render {filename}, it can only be one of {_FRAGMENTABLE!r}")
 
     fragments = doc.pop('extends_documentation_fragment', [])
 
-    if isinstance(fragments, string_types):
+    if isinstance(fragments, str):
         fragments = fragments.split(',')
 
     unknown_fragments = []
 
-    # doc_fragments are allowed to specify a fragment var other than DOCUMENTATION
+    # doc_fragments are allowed to specify a fragment var other than DOCUMENTATION or RETURN
     # with a . separator; this is complicated by collections-hosted doc_fragments that
     # use the same separator. Assume it's collection-hosted normally first, try to load
     # as-specified. If failure, assume the right-most component is a var, split it off,
     # and retry the load.
     for fragment_slug in fragments:
         fragment_name = fragment_slug.strip()
-        fragment_var = 'DOCUMENTATION'
+        fragment_var = section
 
         fragment_class = fragment_loader.get(fragment_name)
         if fragment_class is None and '.' in fragment_slug:
@@ -157,7 +165,7 @@ def add_fragments(doc, filename, fragment_loader, is_module=False):
         # trust-tagged source propagates to loaded values; expressions and templates in config require trust
         fragment_yaml = _tags.TrustedAsTemplate().tag(getattr(fragment_class, fragment_var, None))
         if fragment_yaml is None:
-            if fragment_var != 'DOCUMENTATION':
+            if fragment_var not in _FRAGMENTABLE:
                 # if it's asking for something specific that's missing, that's an error
                 unknown_fragments.append(fragment_slug)
                 continue
@@ -168,44 +176,40 @@ def add_fragments(doc, filename, fragment_loader, is_module=False):
 
         real_fragment_name = getattr(fragment_class, 'ansible_name')
         real_collection_name = '.'.join(real_fragment_name.split('.')[0:2]) if '.' in real_fragment_name else ''
-        add_collection_to_versions_and_dates(fragment, real_collection_name, is_module=is_module)
-
-        if 'notes' in fragment:
-            notes = fragment.pop('notes')
-            if notes:
-                if 'notes' not in doc:
-                    doc['notes'] = []
-                doc['notes'].extend(notes)
-
-        if 'seealso' in fragment:
-            seealso = fragment.pop('seealso')
-            if seealso:
-                if 'seealso' not in doc:
-                    doc['seealso'] = []
-                doc['seealso'].extend(seealso)
-
-        if 'options' not in fragment and 'attributes' not in fragment:
-            raise Exception("missing options or attributes in fragment (%s), possibly misformatted?: %s" % (fragment_name, filename))
-
-        # ensure options themselves are directly merged
-        for doc_key in ['options', 'attributes']:
-            if doc_key in fragment:
-                if doc_key in doc:
-                    try:
-                        merge_fragment(doc[doc_key], fragment.pop(doc_key))
-                    except Exception as e:
-                        raise AnsibleError("%s %s (%s) of unknown type: %s" % (to_native(e), doc_key, fragment_name, filename))
-                else:
-                    doc[doc_key] = fragment.pop(doc_key)
+        add_collection_to_versions_and_dates(fragment, real_collection_name, is_module=is_module, return_docs=(section == 'RETURN'))
+
+        if section == 'DOCUMENTATION':
+            # notes, seealso, options and attributes entries are specificly merged, but only occur in documentation section
+            for doc_key in ['notes', 'seealso']:
+                if doc_key in fragment:
+                    entries = fragment.pop(doc_key)
+                    if entries:
+                        if doc_key not in doc:
+                            doc[doc_key] = []
+                        doc[doc_key].extend(entries)
+
+            if 'options' not in fragment and 'attributes' not in fragment:
+                raise AnsibleFragmentError("missing options or attributes in fragment (%s), possibly misformatted?: %s" % (fragment_name, filename))
+
+            # ensure options themselves are directly merged
+            for doc_key in ['options', 'attributes']:
+                if doc_key in fragment:
+                    if doc_key in doc:
+                        try:
+                            merge_fragment(doc[doc_key], fragment.pop(doc_key))
+                        except Exception as e:
+                            raise AnsibleFragmentError("%s %s (%s) of unknown type: %s" % (to_native(e), doc_key, fragment_name, filename))
+                    else:
+                        doc[doc_key] = fragment.pop(doc_key)
 
         # merge rest of the sections
         try:
             merge_fragment(doc, fragment)
         except Exception as e:
-            raise AnsibleError("%s (%s) of unknown type: %s" % (to_native(e), fragment_name, filename))
+            raise AnsibleFragmentError("%s (%s) of unknown type: %s" % (to_native(e), fragment_name, filename))
 
     if unknown_fragments:
-        raise AnsibleError('unknown doc_fragment(s) in file {0}: {1}'.format(filename, to_native(', '.join(unknown_fragments))))
+        raise AnsibleFragmentError('unknown doc_fragment(s) in file {0}: {1}'.format(filename, to_native(', '.join(unknown_fragments))))
 
 
 def get_docstring(filename, fragment_loader, verbose=False, ignore_errors=False, collection_name=None, is_module=None, plugin_type=None):
@@ -230,13 +234,16 @@ def get_docstring(filename, fragment_loader, verbose=False, ignore_errors=False,
             add_collection_to_versions_and_dates(data['doc'], collection_name, is_module=is_module)
 
         # add fragments to documentation
-        add_fragments(data['doc'], filename, fragment_loader=fragment_loader, is_module=is_module)
+        add_fragments(data['doc'], filename, fragment_loader=fragment_loader, is_module=is_module, section='DOCUMENTATION')
 
     if data.get('returndocs', False):
         # add collection name to versions and dates
         if collection_name is not None:
             add_collection_to_versions_and_dates(data['returndocs'], collection_name, is_module=is_module, return_docs=True)
 
+        # add fragments to return
+        add_fragments(data['returndocs'], filename, fragment_loader=fragment_loader, is_module=is_module, section='RETURN')
+
     return data['doc'], data['plainexamples'], data['returndocs'], data['metadata']
 
 
@@ -352,3 +359,7 @@ def get_plugin_docs(plugin, plugin_type, loader, fragment_loader, verbose):
     docs[0]['plugin_name'] = context.resolved_fqcn
 
     return docs
+
+
+def __getattr__(importable_name):
+    return _no_six.deprecate(importable_name, __name__, "string_types")

ansible/utils/ssh_functions.py

@@ -20,9 +20,7 @@ from __future__ import annotations
 
 import subprocess
 
-from ansible import constants as C
 from ansible.module_utils.common.text.converters import to_bytes
-from ansible.module_utils.compat.paramiko import _paramiko as paramiko
 from ansible.utils.display import Display
 
 display = Display()
@@ -50,20 +48,3 @@ def check_for_controlpersist(ssh_executable):
 
     _HAS_CONTROLPERSIST[ssh_executable] = has_cp
     return has_cp
-
-
-def set_default_transport():
-
-    # deal with 'smart' connection .. one time ..
-    if C.DEFAULT_TRANSPORT == 'smart':
-        display.deprecated(
-            msg="The `smart` option for connections is deprecated.",
-            version="2.20",
-            help_text="Set the connection plugin directly instead.",
-        )
-
-        # see if SSH can support ControlPersist if not use paramiko
-        if not check_for_controlpersist('ssh') and paramiko is not None:
-            C.DEFAULT_TRANSPORT = "paramiko"
-        else:
-            C.DEFAULT_TRANSPORT = "ssh"

ansible/utils/unsafe_proxy.py

@@ -7,17 +7,13 @@ from __future__ import annotations
 
 from collections.abc import Mapping, Set
 
+from ansible.module_utils._internal import _no_six
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.module_utils.common.collections import is_sequence
 from ansible._internal._datatag._tags import TrustedAsTemplate
-from ansible.module_utils.six import binary_type, text_type
-
-import typing as t
 
 __all__ = ['AnsibleUnsafe', 'wrap_var']
 
-T = t.TypeVar('T')
-
 
 class AnsibleUnsafe:
     def __new__(cls, value):
@@ -66,9 +62,9 @@ def wrap_var(v):
         v = _wrap_set(v)
     elif is_sequence(v):
         v = _wrap_sequence(v)
-    elif isinstance(v, binary_type):
+    elif isinstance(v, bytes):
         v = AnsibleUnsafeBytes(v)
-    elif isinstance(v, text_type):
+    elif isinstance(v, str):
         v = AnsibleUnsafeText(v)
 
     return v
@@ -80,3 +76,7 @@ def to_unsafe_bytes(*args, **kwargs):
 
 def to_unsafe_text(*args, **kwargs):
     return wrap_var(to_text(*args, **kwargs))
+
+
+def __getattr__(importable_name):
+    return _no_six.deprecate(importable_name, __name__, "binary_type", "text_type")

ansible/vars/clean.py

@@ -10,7 +10,6 @@ from collections.abc import MutableMapping, MutableSequence
 
 from ansible import constants as C
 from ansible.errors import AnsibleError
-from ansible.module_utils import six
 from ansible.plugins.loader import connection_loader
 from ansible.utils.display import Display
 
@@ -48,7 +47,7 @@ def module_response_deepcopy(v):
     """
     if isinstance(v, dict):
         ret = v.copy()
-        items = six.iteritems(ret)
+        items = ret.items()
     elif isinstance(v, list):
         ret = v[:]
         items = enumerate(ret)
@@ -80,7 +79,7 @@ def strip_internal_keys(dirty, exceptions=None):
 
         # listify to avoid updating dict while iterating over it
         for k in list(dirty.keys()):
-            if isinstance(k, six.string_types):
+            if isinstance(k, str):
                 if k.startswith('_ansible_') and k not in exceptions:
                     del dirty[k]
                     continue

ansible/vars/manager.py

@@ -33,7 +33,6 @@ from ansible.inventory.host import Host
 from ansible.inventory.helpers import sort_groups, get_group_vars
 from ansible.inventory.manager import InventoryManager
 from ansible.module_utils.datatag import native_type_name
-from ansible.module_utils.six import text_type
 from ansible.parsing.dataloader import DataLoader
 from ansible._internal._templating._engine import TemplateEngine
 from ansible.plugins.loader import cache_loader
@@ -50,13 +49,18 @@ if t.TYPE_CHECKING:
 
 display = Display()
 
-# deprecated: description='enable top-level facts deprecation' core_version='2.20'
-# _DEPRECATE_TOP_LEVEL_FACT_TAG = _tags.Deprecated(
-#     msg='Top-level facts are deprecated.',
-#     version='2.24',
-#     deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
-#     help_text='Use `ansible_facts` instead.',
-# )
+_DEPRECATE_TOP_LEVEL_FACT_TAG = _tags.Deprecated(
+    msg='INJECT_FACTS_AS_VARS default to `True` is deprecated, top-level facts will not be auto injected after the change.',
+    version='2.24',
+    deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+    help_text='Use `ansible_facts["fact_name"]` (no `ansible_` prefix) instead.',
+)
+_DEPRECATE_VARS = _tags.Deprecated(
+    msg='The internal "vars" dictionary is deprecated.',
+    version='2.24',
+    deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+    help_text='Use the `vars` and `varnames` lookups instead.',
+)
 
 
 def _deprecate_top_level_fact(value: t.Any) -> t.Any:
@@ -65,9 +69,7 @@ def _deprecate_top_level_fact(value: t.Any) -> t.Any:
     The inner values are shared to aid in message de-duplication across hosts/values, and reduce intra-process memory usage.
     Unique tag instances are required to achieve the correct de-duplication within a top-level templating operation.
     """
-    # deprecated: description='enable top-level facts deprecation' core_version='2.20'
-    # return _DEPRECATE_TOP_LEVEL_FACT_TAG.tag(value)
-    return value
+    return _DEPRECATE_TOP_LEVEL_FACT_TAG.tag(value)
 
 
 def preprocess_vars(a):
@@ -285,8 +287,7 @@ class VariableManager:
             all_vars = _combine_and_track(all_vars, _plugins_inventory([host]), "inventory host_vars for '%s'" % host)
             all_vars = _combine_and_track(all_vars, _plugins_play([host]), "playbook host_vars for '%s'" % host)
 
-            # finally, the facts caches for this host, if it exists
-            # TODO: cleaning of facts should eventually become part of taskresults instead of vars
+            # finally, the facts caches for this host, if they exist
             try:
                 try:
                     facts = self._fact_cache.get(host.name)
@@ -295,12 +296,16 @@ class VariableManager:
 
                 all_vars |= namespace_facts(facts)
 
+                inject, origin = C.config.get_config_value_and_origin('INJECT_FACTS_AS_VARS')
                 # push facts to main namespace
-                if C.INJECT_FACTS_AS_VARS:
-                    deprecated_facts_vars = {k: _deprecate_top_level_fact(v) for k, v in clean_facts(facts).items()}
-                    all_vars = _combine_and_track(all_vars, deprecated_facts_vars, "facts")
+                if inject:
+                    if origin == 'default':
+                        clean_top = {k: _deprecate_top_level_fact(v) for k, v in clean_facts(facts).items()}
+                    else:
+                        clean_top = clean_facts(facts)
+                    all_vars = _combine_and_track(all_vars, clean_top, "facts")
                 else:
-                    # always 'promote' ansible_local
+                    # always 'promote' ansible_local, even if empty
                     all_vars = _combine_and_track(all_vars, {'ansible_local': facts.get('ansible_local', {})}, "facts")
             except KeyError:
                 pass
@@ -419,8 +424,10 @@ class VariableManager:
 
         # 'vars' magic var
         if task or play:
-            # has to be copy, otherwise recursive ref
-            all_vars['vars'] = all_vars.copy()
+            all_vars['vars'] = _DEPRECATE_VARS.tag({})
+            for k, v in all_vars.items():
+                # has to be copy, otherwise recursive ref
+                all_vars['vars'][k] = _DEPRECATE_VARS.tag(v)
 
         display.debug("done with get_vars()")
         return all_vars
@@ -467,7 +474,7 @@ class VariableManager:
             if task._role:
                 variables['role_name'] = task._role.get_name(include_role_fqcn=False)
                 variables['role_path'] = task._role._role_path
-                variables['role_uuid'] = text_type(task._role._uuid)
+                variables['role_uuid'] = str(task._role._uuid)
                 variables['ansible_collection_name'] = task._role._role_collection
                 variables['ansible_role_name'] = task._role.get_name()
 

ansible/vars/plugins.py

@@ -8,8 +8,6 @@ import os
 from functools import lru_cache
 
 from ansible import constants as C
-from ansible.errors import AnsibleError
-from ansible.inventory.group import InventoryObjectType
 from ansible.plugins.loader import vars_loader
 from ansible.utils.display import Display
 from ansible.utils.vars import combine_vars
@@ -26,34 +24,6 @@ def _prime_vars_loader():
         vars_loader.get(plugin_name)
 
 
-def get_plugin_vars(loader, plugin, path, entities):
-
-    data = {}
-    try:
-        data = plugin.get_vars(loader, path, entities)
-    except AttributeError:
-        if hasattr(plugin, 'get_host_vars') or hasattr(plugin, 'get_group_vars'):
-            display.deprecated(
-                msg=f"The vars plugin {plugin.ansible_name} from {plugin._original_path} is relying "
-                    "on the deprecated entrypoints `get_host_vars` and `get_group_vars`.",
-                version="2.20",
-                help_text="This plugin should be updated to inherit from `BaseVarsPlugin` and define "
-                          "a `get_vars` method as the main entrypoint instead.",
-            )
-        try:
-            for entity in entities:
-                if entity.base_type is InventoryObjectType.HOST:
-                    data |= plugin.get_host_vars(entity.name)
-                else:
-                    data |= plugin.get_group_vars(entity.name)
-        except AttributeError:
-            if hasattr(plugin, 'run'):
-                raise AnsibleError("Cannot use v1 type vars plugin %s from %s" % (plugin._load_name, plugin._original_path))
-            else:
-                raise AnsibleError("Invalid vars plugin %s from %s" % (plugin._load_name, plugin._original_path))
-    return data
-
-
 # optimized for stateless plugins; non-stateless plugin instances will fall out quickly
 @lru_cache(maxsize=10)
 def _plugin_should_run(plugin, stage):
@@ -99,7 +69,7 @@ def get_vars_from_path(loader, path, entities, stage):
         if not _plugin_should_run(plugin, stage):
             continue
 
-        if (new_vars := get_plugin_vars(loader, plugin, path, entities)) != {}:
+        if (new_vars := plugin.get_vars(loader, path, entities)) != {}:
             data = combine_vars(data, new_vars)
 
     return data

{ansible_core-2.19.2rc1.dist-info → ansible_core-2.20.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ansible-core
-Version: 2.19.2rc1
+Version: 2.20.0b1
 Summary: Radically simple IT automation
 Author: Ansible Project
 Project-URL: Homepage, https://ansible.com/
@@ -18,14 +18,14 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 or later (G
 Classifier: Natural Language :: English
 Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: System :: Installation/Setup
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: COPYING
 License-File: licenses/Apache-License.txt