Use fully qualified collection name (FQCN) for generated snippets with Ansible 2.10 or greater

Author: pescobar

UltiSnips/generate.py

@@ -2,6 +2,8 @@
 import argparse
 import os
 import os.path
+import ansible
+from packaging import version
 import ansible.modules
 from ansible.utils.plugin_docs import get_docstring
 from ansible.plugins.loader import fragment_loader
@@ -14,14 +16,11 @@
  "priority -50",
 ]
 MAX_DESCRIPTION_LENGTH = 512
+ANSIBLE_VERSION = ansible.release.__version__
 
 
-def get_files(include_user: bool = False) -> List[str]:
- """Return the sorted list of all module files that ansible provides
- Parameters
- ----------
- include_user: bool
- Include modules from the user's ansible-galaxy
+def get_files_builtin() -> List[str]:
+ """Return the sorted list of all module files that ansible provides with the ansible package
 
  Returns
  -------
@@ -32,47 +31,63 @@ def get_files(include_user: bool = False) -> List[str]:
 
  file_names: List[str] = []
  for root, dirs, files in os.walk(os.path.dirname(ansible.modules.__file__)):
+ files_without_symlinks = []
+ for f in files:
+ if not os.path.islink(os.path.join(root, f)):
+ files_without_symlinks.append(f)
  file_names += [
  f"{root}/{file_name}"
- for file_name in files
+ for file_name in files_without_symlinks
  if file_name.endswith(".py") and not file_name.startswith("__init__")
  ]
- if include_user:
- for root, dirs, files in os.walk(os.path.expanduser('~/.ansible/collections/ansible_collections/')):
- file_names += [
- f"{root}/{file_name}"
- for file_name in files
- if file_name.endswith(".py") and not file_name.startswith("__init__")
- ]
 
  return sorted(file_names)
 
+def get_files_user() -> List[str]:
+ """Return the sorted list of all module files provided by collections installed in the
+ user home folder ~/.ansible/collections/
 
-def get_docstrings(file_names: List[str]) -> List[Any]:
- """Extract and return a list of docstring information from a list of files
+ Returns
+ -------
+ List[str]
+ A list of strings representing the Python module files installed in ~/.ansible/collections/
+ """
+
+ file_names: List[str] = []
+ for root, dirs, files in os.walk(os.path.expanduser('~/.ansible/collections/ansible_collections/')):
+ files_without_symlinks = []
+ for f in files:
+ if not os.path.islink(os.path.join(root, f)):
+ files_without_symlinks.append(f)
+ file_names += [
+ f"{root}/{file_name}"
+ for file_name in files_without_symlinks
+ if file_name.endswith(".py") and not file_name.startswith("__init__") and "plugins/modules" in root
+ ]
+
+ return sorted(file_names)
+
+
+def get_module_docstring(file_path: str) -> Any:
+ """Extract and return docstring information from a module file
 
  Parameters
  ----------
- file_names: List[str]
- A list of strings representing file names
+ file_names: file_path[str]
+ string representing module file
 
  Returns
  -------
- List[Any]
- A list of AnsibleMapping objects, representing docstring information
+ Any
+ An AnsibleMapping object, representing docstring information
  (in dict form), excluding those that are marked as deprecated.
 
  """
 
- found_docstrings: List[Any] = []
- found_docstrings += [
- get_docstring(file_name, fragment_loader)[0] for file_name in file_names
- ]
- return [
- current_docstring
- for current_docstring in found_docstrings
- if current_docstring and not current_docstring.get("deprecated")
- ]
+ docstring = get_docstring(file_path, fragment_loader)[0]
+
+ if docstring and not docstring.get("deprecated"):
+ return docstring
 
 
 def escape_strings(escapist: str) -> str:
@@ -228,7 +243,7 @@ def module_options_to_snippet_options(module_options: Any) -> List[str]:
  return options
 
 
-def convert_docstring_to_snippet(convert_docstring: Any) -> List[str]:
+def convert_docstring_to_snippet(convert_docstring: Any, collection_name) -> List[str]:
  """Converts data about an Ansible module into an UltiSnips snippet string
 
  Parameters
@@ -250,17 +265,36 @@ def convert_docstring_to_snippet(convert_docstring: Any) -> List[str]:
  module_name = convert_docstring["module"]
  module_short_description = convert_docstring["short_description"]
 
+ # use only the module name if ansible version < 2.10
+ if version.parse(ANSIBLE_VERSION) < version.parse("2.10"):
+ snippet_module_name = f"{module_name}:"
+ # use FQCN if ansible version is 2.10 or higher
+ else:
+ snippet_module_name = f"{collection_name}.{module_name}:"
+
  snippet += [f'snippet {module_name} "{escape_strings(module_short_description)}" {snippet_options}']
  if args.style == "dictionary":
- snippet += [f"{module_name}:"]
+ snippet += [f"{snippet_module_name}"]
  else:
- snippet += [f"{module_name}:{' >' if convert_docstring.get('options') else ''}"]
+ snippet += [f"{snippet_module_name}:{' >' if convert_docstring.get('options') else ''}"]
  module_options = module_options_to_snippet_options(convert_docstring.get("options"))
  snippet += module_options
  snippet += ["endsnippet"]
 
  return snippet
 
+def get_collection_name(filepath:str) -> str:
+ """ Returns the collection name for a full file path """
+
+ path_splitted = filepath.split('/')
+
+ collection_top_folder_index = path_splitted.index('ansible_collections')
+ collection_namespace = path_splitted[collection_top_folder_index + 1]
+ collection_name = path_splitted[collection_top_folder_index + 2]
+
+ # print(f"{collection_namespace}.{collection_name}")
+ return f"{collection_namespace}.{collection_name}"
+
 
 if __name__ == "__main__":
 
@@ -284,10 +318,36 @@ def convert_docstring_to_snippet(convert_docstring: Any) -> List[str]:
  )
  args = parser.parse_args()
 
- docstrings = get_docstrings(get_files(include_user=args.user))
+
+ if version.parse(ANSIBLE_VERSION) < version.parse("2.10"):
+ print(f"ansible version {ANSIBLE_VERSION} doesn't support FQCN")
+ print("generated snippets will only use the module name e.g. 'yum' instead of 'ansible.builtin.yum'")
+ else:
+ print(f"ansible version {ANSIBLE_VERSION} supports using FQCN")
+ print("Generated snippets will use FQCN e.g. 'ansible.builtin.yum' instead of 'yum'")
+ print("Still, you only need to type 'yum' to trigger the snippet")
+
+ modules_docstrings = []
+
+ builtin_modules_paths = get_files_builtin()
+ for f in builtin_modules_paths:
+ docstring_builtin = get_module_docstring(f)
+ if docstring_builtin and docstring_builtin not in modules_docstrings:
+ docstring_builtin['collection_name'] = "ansible.builtin"
+ modules_docstrings.append(docstring_builtin)
+
+ if args.user:
+ user_modules_paths = get_files_user()
+ for f in user_modules_paths:
+ docstring_user = get_module_docstring(f)
+ if docstring_user and docstring_user not in modules_docstrings:
+ collection_name = get_collection_name(f)
+ docstring_user['collection_name'] = collection_name
+ modules_docstrings.append(docstring_user)
+
  with open(args.output, "w") as f:
  f.writelines(f"{header}\n" for header in HEADER)
- for docstring in docstrings:
+ for docstring in modules_docstrings:
  f.writelines(
- f"{line}\n" for line in convert_docstring_to_snippet(docstring)
+ f"{line}\n" for line in convert_docstring_to_snippet(docstring, docstring.get("collection_name"))
  )