From 32672c63268e36f4b6125d3609c67275b6114045 Mon Sep 17 00:00:00 2001
From: Mateus Rangel <mateusmrangel@hotmail.com>
Date: Mon, 6 Feb 2023 15:56:21 -0300
Subject: [PATCH] Improving the RETURN and its docs on the apt_repository
 module (#79658)

* Improving the documentation on how we generate the default value of the filename parameter

* fix pep8

* removing unnecessary documentation and improving the module's return

* making the RETURN docs

* pep8

* version_added and changelog

* module._diff

* module._diff fix

* add rudimentary tests for new outputs

---------

Co-authored-by: Matt Davis <mrd@redhat.com>
---
 .../79658-improving-return-and-docs.yaml      |  2 +
 lib/ansible/modules/apt_repository.py         | 45 ++++++++++++++-----
 .../targets/apt_repository/tasks/apt.yml      | 16 +++++++
 3 files changed, 52 insertions(+), 11 deletions(-)
 create mode 100644 changelogs/fragments/79658-improving-return-and-docs.yaml

diff --git a/changelogs/fragments/79658-improving-return-and-docs.yaml b/changelogs/fragments/79658-improving-return-and-docs.yaml
new file mode 100644
index 00000000000..bf0cc2a83d0
--- /dev/null
+++ b/changelogs/fragments/79658-improving-return-and-docs.yaml
@@ -0,0 +1,2 @@
+minor_changes:
+  - apt_repository - adds ``sources_added`` and ``sources_removed`` to the return of the module (https://github.com/ansible/ansible/issues/79306).
\ No newline at end of file
diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py
index f9a0cd91958..e4a957b32d2 100644
--- a/lib/ansible/modules/apt_repository.py
+++ b/lib/ansible/modules/apt_repository.py
@@ -146,7 +146,27 @@ EXAMPLES = '''
         state: present
 '''
 
-RETURN = '''#'''
+RETURN = '''
+repo:
+  description: A source string for the repository
+  returned: always
+  type: str
+  sample: "deb https://artifacts.elastic.co/packages/6.x/apt stable main"
+
+sources_added:
+  description: List of sources added
+  returned: success, sources were added
+  type: list
+  sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]
+  version_added: "2.15"
+
+sources_removed:
+  description: List of sources removed
+  returned: success, sources were removed
+  type: list
+  sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]
+  version_added: "2.15"
+'''
 
 import copy
 import glob
@@ -688,15 +708,18 @@ def main():
     sources_after = sourceslist.dump()
     changed = sources_before != sources_after
 
-    if changed and module._diff:
-        diff = []
-        for filename in set(sources_before.keys()).union(sources_after.keys()):
-            diff.append({'before': sources_before.get(filename, ''),
-                         'after': sources_after.get(filename, ''),
-                         'before_header': (filename, '/dev/null')[filename not in sources_before],
-                         'after_header': (filename, '/dev/null')[filename not in sources_after]})
-    else:
-        diff = {}
+    diff = []
+    sources_added = set()
+    sources_removed = set()
+    if changed:
+        sources_added = set(sources_after.keys()).difference(sources_before.keys())
+        sources_removed = set(sources_before.keys()).difference(sources_after.keys())
+        if module._diff:
+            for filename in set(sources_added.union(sources_removed)):
+                diff.append({'before': sources_before.get(filename, ''),
+                             'after': sources_after.get(filename, ''),
+                             'before_header': (filename, '/dev/null')[filename not in sources_before],
+                             'after_header': (filename, '/dev/null')[filename not in sources_after]})
 
     if changed and not module.check_mode:
         try:
@@ -728,7 +751,7 @@ def main():
             revert_sources_list(sources_before, sources_after, sourceslist_before)
             module.fail_json(msg=to_native(ex))
 
-    module.exit_json(changed=changed, repo=repo, state=state, diff=diff)
+    module.exit_json(changed=changed, repo=repo, sources_added=sources_added, sources_removed=sources_removed, state=state, diff=diff)
 
 
 if __name__ == '__main__':
diff --git a/test/integration/targets/apt_repository/tasks/apt.yml b/test/integration/targets/apt_repository/tasks/apt.yml
index 0dc25afd598..cb418c3436b 100644
--- a/test/integration/targets/apt_repository/tasks/apt.yml
+++ b/test/integration/targets/apt_repository/tasks/apt.yml
@@ -152,6 +152,11 @@
       - 'result.changed'
       - 'result.state == "present"'
       - 'result.repo == "{{test_ppa_spec}}"'
+      - '"sources_added" in result'
+      - 'result.sources_added | length == 1'
+      - '"git" in result.sources_added[0]'
+      - '"sources_removed" in result'
+      - 'result.sources_removed | length == 0'
       - result_cache is not changed
 
 - name: 'examine apt cache mtime'
@@ -167,6 +172,17 @@
   apt_repository: repo='{{test_ppa_spec}}' state=absent
   register: result
 
+- assert:
+    that:
+      - 'result.changed'
+      - 'result.state == "absent"'
+      - 'result.repo == "{{test_ppa_spec}}"'
+      - '"sources_added" in result'
+      - 'result.sources_added | length == 0'
+      - '"sources_removed" in result'
+      - 'result.sources_removed | length == 1'
+      - '"git" in result.sources_removed[0]'
+
 # When installing a repo with the spec, the key is *NOT* added
 - name: 'ensure ppa key is absent (expect: pass)'
   apt_key: id='{{test_ppa_key}}' state=absent