ansible-core 2.19.3rc1__py3-none-any.whl → 2.20.0b2__py3-none-any.whl

ansible/plugins/shell/powershell.py

@@ -192,7 +192,7 @@ class ShellModule(ShellBase):
 
     def join_path(self, *args):
         # use normpath() to remove doubled slashed and convert forward to backslashes
-        parts = [ntpath.normpath(self._unquote(arg)) for arg in args]
+        parts = [ntpath.normpath(arg) for arg in args]
 
         # Because ntpath.join treats any component that begins with a backslash as an absolute path,
         # we have to strip slashes from at least the beginning, otherwise join will ignore all previous
@@ -210,7 +210,6 @@ class ShellModule(ShellBase):
 
     def path_has_trailing_slash(self, path):
         # Allow Windows paths to be specified using either slash.
-        path = self._unquote(path)
         return path.endswith('/') or path.endswith('\\')
 
     def chmod(self, paths, mode):
@@ -223,11 +222,11 @@ class ShellModule(ShellBase):
         raise NotImplementedError('set_user_facl is not implemented for Powershell')
 
     def remove(self, path, recurse=False):
-        path = self._escape(self._unquote(path))
+        quoted_path = self._escape(path)
         if recurse:
-            return self._encode_script("""Remove-Item '%s' -Force -Recurse;""" % path)
+            return self._encode_script("""Remove-Item '%s' -Force -Recurse;""" % quoted_path)
         else:
-            return self._encode_script("""Remove-Item '%s' -Force;""" % path)
+            return self._encode_script("""Remove-Item '%s' -Force;""" % quoted_path)
 
     def mkdtemp(
         self,
@@ -240,7 +239,6 @@ class ShellModule(ShellBase):
         # compatibility in case other action plugins outside Ansible calls this.
         if not basefile:
             basefile = self.__class__._generate_temp_dir_name()
-        basefile = self._escape(self._unquote(basefile))
         basetmpdir = self._escape(tmpdir if tmpdir else self.get_option('remote_tmp'))
 
         script = f"""
@@ -263,7 +261,6 @@ class ShellModule(ShellBase):
         if not basefile:
             basefile = self.__class__._generate_temp_dir_name()
 
-        basefile = self._unquote(basefile)
         basetmpdir = tmpdir if tmpdir else self.get_option('remote_tmp')
 
         script, stdin = _bootstrap_powershell_script("powershell_mkdtemp.ps1", {
@@ -283,7 +280,6 @@ class ShellModule(ShellBase):
     ) -> str:
         # This is not called in Ansible anymore but it is kept for backwards
         # compatibility in case other actions plugins outside Ansible called this.
-        user_home_path = self._unquote(user_home_path)
         if user_home_path == '~':
             script = 'Write-Output (Get-Location).Path'
         elif user_home_path.startswith('~\\'):
@@ -297,7 +293,6 @@ class ShellModule(ShellBase):
         user_home_path: str,
         username: str = '',
     ) -> _ShellCommand:
-        user_home_path = self._unquote(user_home_path)
         script, stdin = _bootstrap_powershell_script("powershell_expand_user.ps1", {
             'Path': user_home_path,
         })
@@ -308,7 +303,7 @@ class ShellModule(ShellBase):
         )
 
     def exists(self, path):
-        path = self._escape(self._unquote(path))
+        path = self._escape(path)
         script = """
             If (Test-Path '%s')
             {
@@ -329,7 +324,7 @@ class ShellModule(ShellBase):
             version="2.23",
             help_text="Use `ActionBase._execute_remote_stat()` instead.",
         )
-        path = self._escape(self._unquote(path))
+        path = self._escape(path)
         script = """
             If (Test-Path -PathType Leaf '%(path)s')
             {
@@ -364,7 +359,7 @@ class ShellModule(ShellBase):
             if arg_path:
                 # Running a module without the exec_wrapper and with an argument
                 # file.
-                script_path = self._unquote(cmd_parts[0])
+                script_path = cmd_parts[0]
                 if not script_path.lower().endswith('.ps1'):
                     script_path += '.ps1'
 
@@ -387,7 +382,6 @@ class ShellModule(ShellBase):
             cmd_parts.insert(0, shebang[2:])
         elif not shebang:
             # The module is assumed to be a binary
-            cmd_parts[0] = self._unquote(cmd_parts[0])
             cmd_parts.append(arg_path)
         script = """
             Try
@@ -428,19 +422,9 @@ class ShellModule(ShellBase):
         return self._encode_script(script, preserve_rc=False)
 
     def wrap_for_exec(self, cmd):
+        super().wrap_for_exec(cmd)
         return '& %s; exit $LASTEXITCODE' % cmd
 
-    def _unquote(self, value):
-        """Remove any matching quotes that wrap the given value."""
-        value = to_text(value or '')
-        m = re.match(r'^\s*?\'(.*?)\'\s*?$', value)
-        if m:
-            return m.group(1)
-        m = re.match(r'^\s*?"(.*?)"\s*?$', value)
-        if m:
-            return m.group(1)
-        return value
-
     def _escape(self, value):
         """Return value escaped for use in PowerShell single quotes."""
         # There are 5 chars that need to be escaped in a single quote.

ansible/plugins/strategy/__init__.py

@@ -53,6 +53,9 @@ from ansible.utils.sentinel import Sentinel
 from ansible.utils.vars import combine_vars
 from ansible.vars.clean import strip_internal_keys, module_response_deepcopy
 
+if t.TYPE_CHECKING:
+    from ansible.playbook.role_include import IncludeRole
+
 display = Display()
 
 __all__ = ['StrategyBase']
@@ -581,7 +584,7 @@ class StrategyBase:
                         self._variable_manager.set_nonpersistent_facts(
                             original_host.name,
                             dict(
-                                ansible_failed_task=original_task.serialize(),
+                                ansible_failed_task=original_task.dump_attrs(),
                                 ansible_failed_result=task_result._return_data,
                             ),
                         )
@@ -799,7 +802,7 @@ class StrategyBase:
 
         return ret_results
 
-    def _copy_included_file(self, included_file: IncludedFile) -> IncludedFile:
+    def _copy_included_file(self, included_file: IncludedFile) -> TaskInclude | IncludeRole:
         """
         A proven safe and performant way to create a copy of an included file
         """
@@ -900,7 +903,7 @@ class StrategyBase:
         display.warning("%s task does not support when conditional" % task_name)
 
     def _execute_meta(self, task: Task, play_context, iterator, target_host: Host):
-        task.resolved_action = 'ansible.builtin.meta'  # _post_validate_args is never called for meta actions, so resolved_action hasn't been set
+        task._resolved_action = 'ansible.builtin.meta'  # _post_validate_args is never called for meta actions, so resolved_action hasn't been set
 
         # meta tasks store their args in the _raw_params field of args,
         # since they do not use k=v pairs, so get that

ansible/plugins/test/core.py

@@ -142,6 +142,9 @@ def regex(value='', pattern='', ignorecase=False, multiline=False, match_type='s
         This is likely only useful for `search` and `match` which already
         have their own filters.
     """
+    valid_match_types = ('search', 'match', 'fullmatch')
+    if match_type not in valid_match_types:
+        raise errors.AnsibleTemplatePluginError(f"Invalid match_type specified. Expected one of: {', '.join(valid_match_types)}.", obj=match_type)
     value = to_text(value, errors='surrogate_or_strict')
     flags = 0
     if ignorecase:
@@ -149,7 +152,7 @@ def regex(value='', pattern='', ignorecase=False, multiline=False, match_type='s
     if multiline:
         flags |= re.M
     _re = re.compile(pattern, flags=flags)
-    return bool(getattr(_re, match_type, 'search')(value))
+    return bool(getattr(_re, match_type)(value))
 
 
 @accept_args_markers

ansible/plugins/test/falsy.yml

@@ -5,7 +5,7 @@ DOCUMENTATION:
   short_description: Pythonic false
   description:
     - This check is a more Python version of what is 'false'.
-    - It is the opposite of 'truthy'.
+    - It is the opposite of P(ansible.builtin.truthy#test).
   options:
     _input:
       description: An expression that can be expressed in a boolean context.

ansible/plugins/test/regex.yml

@@ -3,7 +3,7 @@ DOCUMENTATION:
   author: Ansible Core
   short_description: Does string match regular expression from the start
   description:
-    - Compare string against regular expression using Python's match or search functions.
+    - Compare string against regular expression using Python's match, fullmatch or search functions.
   options:
     _input:
       description: String to match.
@@ -22,14 +22,26 @@ DOCUMENTATION:
       type: boolean
       default: False
     match_type:
-      description: Decide which function to be used to do the matching.
+      description:
+        - Decide which function to be used to do the matching.
       type: string
-      choices: [match, search]
+      choices: [match, search, fullmatch]
       default: search
 
-EXAMPLES: |
-  url: "https://example.com/users/foo/resources/bar"
-  foundmatch: url is regex("example\.com/\w+/foo")
+EXAMPLES:
+  - name: check if string matches regex
+    assert:
+      that:
+        - 'url is regex("example\.com/\w+/foo")'
+    vars:
+      url: "https://example.com/users/foo/resources/bar"
+
+  - name: check if string matches regex ignoring case
+    assert:
+      that:
+        - 'url is regex("EXAMPLE\.COM/\w+/foo", ignorecase=True)'
+    vars:
+      url: "https://Example.com/users/foo/resources/bar"
 
 RETURN:
   _value:

ansible/plugins/test/truthy.yml

@@ -20,5 +20,5 @@ EXAMPLES: |
     thisisfalse: '{{ "" is truthy }}'
 RETURN:
   _value:
-    description: Returns V(True) if the condition is not "Python truthy", V(False) otherwise.
+    description: Returns V(True) if the condition is "Python truthy", V(False) otherwise.
     type: boolean

ansible/release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.19.3rc1'
+__version__ = '2.20.0b2'
 __author__ = 'Ansible, Inc.'
-__codename__ = "What Is and What Should Never Be"
+__codename__ = "Good Times Bad Times"

ansible/template/__init__.py

@@ -25,7 +25,6 @@ if _t.TYPE_CHECKING:  # pragma: nocover
 
 _display: _t.Final[_Display] = _Display()
 _UNSET = _t.cast(_t.Any, object())
-_TTrustable = _t.TypeVar('_TTrustable', bound=str | _io.IOBase | _t.TextIO | _t.BinaryIO)
 _TRUSTABLE_TYPES = (str, _io.IOBase)
 
 AnsibleUndefined = _jinja_common.UndefinedMarker
@@ -361,7 +360,7 @@ def generate_ansible_template_vars(
     return _template_vars.generate_ansible_template_vars(path=path, fullpath=fullpath, dest_path=dest_path, include_ansible_managed=True)
 
 
-def trust_as_template(value: _TTrustable) -> _TTrustable:
+def trust_as_template[T: str | _io.IOBase | _t.TextIO | _t.BinaryIO](value: T) -> T:
     """
     Returns `value` tagged as trusted for templating.
     Raises a `TypeError` if `value` is not a supported type.
@@ -385,10 +384,7 @@ def is_trusted_as_template(value: object) -> bool:
     return isinstance(value, _TRUSTABLE_TYPES) and _tags.TrustedAsTemplate.is_tagged_on(value)
 
 
-_TCallable = _t.TypeVar('_TCallable', bound=_t.Callable)
-
-
-def accept_args_markers(plugin: _TCallable) -> _TCallable:
+def accept_args_markers[T: _t.Callable](plugin: T) -> T:
     """
     A decorator to mark a Jinja plugin as capable of handling `Marker` values for its top-level arguments.
     Non-decorated plugin invocation is skipped when a top-level argument is a `Marker`, with the first such value substituted as the plugin result.
@@ -399,7 +395,7 @@ def accept_args_markers(plugin: _TCallable) -> _TCallable:
     return plugin
 
 
-def accept_lazy_markers(plugin: _TCallable) -> _TCallable:
+def accept_lazy_markers[T: _t.Callable](plugin: T) -> T:
     """
     A decorator to mark a Jinja plugin as capable of handling `Marker` values retrieved from lazy containers.
     Non-decorated plugins will trigger a `MarkerError` exception when attempting to retrieve a `Marker` from a lazy container.

ansible/utils/collection_loader/_collection_config.py

@@ -62,6 +62,11 @@ class _AnsibleCollectionConfig(type):
         cls._require_finder()
         return [_to_text(p) for p in cls._collection_finder._n_collection_paths]
 
+    @property
+    def _internal_collections(cls):
+        cls._require_finder()
+        return cls._collection_finder._internal_collections
+
     @property
     def default_collection(cls):
         return cls._default_collection

ansible/utils/collection_loader/_collection_finder.py

@@ -26,20 +26,16 @@ from . import _to_bytes, _to_text
 from ._collection_config import AnsibleCollectionConfig
 
 try:
-    try:
-        # Available on Python >= 3.11
-        # We ignore the import error that will trigger when running mypy with
-        # older Python versions.
-        from importlib.resources.abc import TraversableResources  # type: ignore[import]
-    except ImportError:
-        # Used with Python 3.9 and 3.10 only
-        # This member is still available as an alias up until Python 3.14 but
-        # is deprecated as of Python 3.12.
-        from importlib.abc import TraversableResources  # deprecated: description='TraversableResources move' python_version='3.10'
+    # Available on Python >= 3.11
+    # We ignore the import error that will trigger when running mypy with
+    # older Python versions.
+    from importlib.resources.abc import TraversableResources  # type: ignore[import]
 except ImportError:
-    # Python < 3.9
-    # deprecated: description='TraversableResources fallback' python_version='3.8'
-    TraversableResources = object  # type: ignore[assignment,misc]
+    # Used with Python 3.9 and 3.10 only
+    # This member is still available as an alias up until Python 3.14 but
+    # is deprecated as of Python 3.12.
+    # deprecated: description='TraversableResources move' python_version='3.10'
+    from importlib.abc import TraversableResources  # type: ignore[assignment,no-redef]
 
 # NB: this supports import sanity test providing a different impl
 try:
@@ -186,7 +182,7 @@ class _AnsibleTraversableResources(TraversableResources):
 
 
 class _AnsibleCollectionFinder:
-    def __init__(self, paths=None, scan_sys_paths=True):
+    def __init__(self, paths=None, scan_sys_paths=True, internal_collections=None):
         # TODO: accept metadata loader override
         self._ansible_pkg_path = _to_text(os.path.dirname(_to_bytes(sys.modules['ansible'].__file__)))
 
@@ -213,6 +209,7 @@ class _AnsibleCollectionFinder:
             if p not in good_paths and os.path.isdir(_to_bytes(os.path.join(p, 'ansible_collections'))):
                 good_paths.append(p)
 
+        self._internal_collections = internal_collections
         self._n_configured_paths = good_paths
         self._n_cached_collection_paths = None
         self._n_cached_collection_qualified_paths = None

ansible/utils/context_objects.py

@@ -9,14 +9,14 @@ from __future__ import annotations
 from abc import ABCMeta
 from collections.abc import Container, Mapping, Sequence, Set
 
+from ansible.module_utils._internal import _no_six
 from ansible.module_utils.common.collections import ImmutableDict
-from ansible.module_utils.six import add_metaclass, binary_type, text_type
 from ansible.utils.singleton import Singleton
 
 
 def _make_immutable(obj):
     """Recursively convert a container and objects inside of it into immutable data types"""
-    if isinstance(obj, (text_type, binary_type)):
+    if isinstance(obj, (str, bytes)):
         # Strings first because they are also sequences
         return obj
     elif isinstance(obj, Mapping):
@@ -79,11 +79,14 @@ class CLIArgs(ImmutableDict):
         return cls(vars(options))
 
 
-@add_metaclass(_ABCSingleton)
-class GlobalCLIArgs(CLIArgs):
+class GlobalCLIArgs(CLIArgs, metaclass=_ABCSingleton):
     """
     Globally hold a parsed copy of cli arguments.
 
     Only one of these exist per program as it is for global context
     """
     pass
+
+
+def __getattr__(importable_name):
+    return _no_six.deprecate(importable_name, __name__, "binary_type", "text_type", "add_metaclass")

ansible/utils/display.py

@@ -52,11 +52,10 @@ from ansible.constants import config
 from ansible.errors import AnsibleAssertionError, AnsiblePromptInterrupt, AnsiblePromptNoninteractive, AnsibleError
 from ansible._internal._errors import _error_utils, _error_factory
 from ansible._internal import _display_utils
-from ansible.module_utils._internal import _deprecator, _messages
+from ansible.module_utils._internal import _deprecator, _messages, _no_six
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.module_utils.datatag import deprecator_from_collection_name
 from ansible._internal._datatag._tags import TrustedAsTemplate
-from ansible.module_utils.six import text_type
 from ansible.module_utils._internal import _traceback, _errors
 from ansible.utils.color import stringc
 from ansible.utils.multiprocessing import context as multiprocessing_context
@@ -66,8 +65,6 @@ if t.TYPE_CHECKING:
     # avoid circular import at runtime
     from ansible.executor.task_queue_manager import FinalQueue
 
-P = t.ParamSpec('P')
-
 _LIBC = ctypes.cdll.LoadLibrary(ctypes.util.find_library('c'))
 # Set argtypes, to avoid segfault if the wrong type is provided,
 # restype is assumed to be c_int
@@ -118,7 +115,7 @@ def get_text_width(text: str) -> int:
     character and using wcwidth individually, falling back to a value of 0
     for non-printable wide characters.
     """
-    if not isinstance(text, text_type):
+    if not isinstance(text, str):
         raise TypeError('get_text_width requires text, not %s' % type(text))
 
     try:
@@ -398,7 +395,7 @@ class Display(metaclass=Singleton):
                     self.b_cowsay = b_cow_path
 
     @staticmethod
-    def _proxy(
+    def _proxy[**P](
         func: c.Callable[t.Concatenate[Display, P], None]
     ) -> c.Callable[..., None]:
         @wraps(func)
@@ -1144,3 +1141,7 @@ def _report_config_warnings(deprecator: _messages.PluginInfo) -> None:
 # emit any warnings or deprecations
 # in the event config fails before display is up, we'll lose warnings -- but that's OK, since everything is broken anyway
 _report_config_warnings(_deprecator.ANSIBLE_CORE_DEPRECATOR)
+
+
+def __getattr__(importable_name):
+    return _no_six.deprecate(importable_name, __name__, "text_type")

ansible/utils/encrypt.py

@@ -176,11 +176,6 @@ class PasslibHash(BaseHash):
         return to_text(result, errors='strict')
 
 
-def passlib_or_crypt(secret, algorithm, salt=None, salt_size=None, rounds=None, ident=None):
-    display.deprecated("passlib_or_crypt API is deprecated in favor of do_encrypt", version='2.20')
-    return do_encrypt(secret, algorithm, salt=salt, salt_size=salt_size, rounds=rounds, ident=ident)
-
-
 def do_encrypt(result, encrypt, salt_size=None, salt=None, ident=None, rounds=None):
     if PASSLIB_AVAILABLE:
         return PasslibHash(encrypt).hash(result, salt=salt, salt_size=salt_size, rounds=rounds, ident=ident)

ansible/utils/helpers.py

@@ -17,7 +17,7 @@
 
 from __future__ import annotations
 
-from ansible.module_utils.six import string_types
+from ansible.module_utils._internal import _no_six
 
 
 def pct_to_int(value, num_items, min_value=1):
@@ -25,7 +25,7 @@ def pct_to_int(value, num_items, min_value=1):
     Converts a given value to a percentage if specified as "x%",
     otherwise converts the given value to an integer.
     """
-    if isinstance(value, string_types) and value.endswith('%'):
+    if isinstance(value, str) and value.endswith('%'):
         value_pct = int(value.replace("%", ""))
         return int((value_pct / 100.0) * num_items) or min_value
     else:
@@ -47,3 +47,7 @@ def deduplicate_list(original_list):
     """
     seen = set()
     return [x for x in original_list if x not in seen and not seen.add(x)]
+
+
+def __getattr__(importable_name):
+    return _no_six.deprecate(importable_name, __name__, "string_types")

ansible/utils/jsonrpc.py

@@ -7,9 +7,9 @@ import json
 import pickle
 import traceback
 
+from ansible.module_utils._internal import _no_six
 from ansible.module_utils.common.text.converters import to_text
 from ansible.module_utils.connection import ConnectionError
-from ansible.module_utils.six import binary_type, text_type
 from ansible.utils.display import Display
 
 display = Display()
@@ -79,9 +79,9 @@ class JsonRpcServer(object):
 
     def response(self, result=None):
         response = self.header()
-        if isinstance(result, binary_type):
+        if isinstance(result, bytes):
             result = to_text(result)
-        if not isinstance(result, text_type):
+        if not isinstance(result, str):
             response["result_type"] = "pickle"
             result = to_text(pickle.dumps(result), errors='surrogateescape')
         response['result'] = result
@@ -110,3 +110,7 @@ class JsonRpcServer(object):
 
     def internal_error(self, data=None):
         return self.error(-32603, 'Internal error', data)
+
+
+def __getattr__(importable_name):
+    return _no_six.deprecate(importable_name, __name__, "binary_type", "text_type")

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")