make api_modify to ignore builtin items (#130)

* make api_modify to ignore builtin items

Signed-off-by: Tomas Herfert <herfik>

* include_builtin parametr for api_info module

Signed-off-by: Tomas Herfert <herfik>

* api_info ignore_builtin changelog

Signed-off-by: Tomas Herfert <herfik>

* typo

Signed-off-by: Tomas Herfert <herfik>

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

Signed-off-by: Tomas Herfert <herfik>
Co-authored-by: Tomas Herfert <herfik>
Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/130-api-modify-builtin.yml

@@ -0,0 +1,6 @@
+minor_changes:
+  - api_info - new parameter ``include_builtin`` which allows to include "builtin" entries that are automatically generated by ROS and cannot be modified by the user
+    (https://github.com/ansible-collections/community.routeros/pull/130).
+trivial:
+  - api_modify - ignore  ``builtin`` entries
+    (https://github.com/ansible-collections/community.routeros/pull/130).

plugins/modules/api_info.py

@@ -18,9 +18,9 @@ version_added: 2.2.0
 description:
   - Allows to retrieve information for a path using the API.
   - This can be used to backup a path to restore it with the M(community.routeros.api_modify) module.
-  - Entries are normalized, and dynamic entries are not returned. Use the I(handle_disabled) and
+  - Entries are normalized, dynamic and builtin entries are not returned. Use the I(handle_disabled) and
-    I(hide_defaults) options to control normalization, the I(include_dynamic) option to also return
+    I(hide_defaults) options to control normalization, the I(include_dynamic) and I(include_builtin) options to also return
-    dynamic entries, and use I(unfiltered) to return all fields including counters.
+    dynamic resp. builtin entries, and use I(unfiltered) to return all fields including counters.
   - B(Note) that this module is still heavily in development, and only supports B(some) paths.
     If you want to support new paths, or think you found problems with existing paths, please first
     L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
@@ -196,6 +196,14 @@ options:
       - If set to C(true), they are returned as well, and the C(dynamic) keys are returned as well.
     type: bool
     default: false
+  include_builtin:
+    description:
+      - Whether to include builtin values.
+      - By default, they are not returned, and the C(builtin) keys are omitted.
+      - If set to C(true), they are returned as well, and the C(builtin) keys are returned as well.
+    type: bool
+    default: false
+    version_added: 2.4.0
 seealso:
   - module: community.routeros.api
   - module: community.routeros.api_facts
@@ -273,6 +281,7 @@ def main():
         handle_disabled=dict(type='str', choices=['exclamation', 'null-value', 'omit'], default='exclamation'),
         hide_defaults=dict(type='bool', default=True),
         include_dynamic=dict(type='bool', default=False),
+        include_builtin=dict(type='bool', default=False),
     )
     module_args.update(api_argument_spec())
 
@@ -292,6 +301,7 @@ def main():
     handle_disabled = module.params['handle_disabled']
     hide_defaults = module.params['hide_defaults']
     include_dynamic = module.params['include_dynamic']
+    include_builtin = module.params['include_builtin']
     try:
         api_path = compose_api_path(api, path)
 
@@ -301,12 +311,17 @@ def main():
             if not include_dynamic:
                 if entry.get('dynamic', False):
                     continue
+            if not include_builtin:
+                if entry.get('builtin', False):
+                    continue
             if not unfiltered:
                 for k in list(entry):
                     if k == '.id':
                         continue
                     if k == 'dynamic' and include_dynamic:
                         continue
+                    if k == 'builtin' and include_builtin:
+                        continue
                     if k not in path_info.fields:
                         entry.pop(k)
             if handle_disabled != 'omit':

plugins/modules/api_modify.py

@@ -20,7 +20,7 @@ description:
   - Use the M(community.routeros.api_find_and_modify) module to modify one or multiple entries in a controlled way
     depending on some search conditions.
   - To make a backup of a path that can be restored with this module, use the M(community.routeros.api_info) module.
-  - The module ignores dynamic entries.
+  - The module ignores dynamic and builtin entries.
   - B(Note) that this module is still heavily in development, and only supports B(some) paths.
     If you want to support new paths, or think you found problems with existing paths, please first
     L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
@@ -483,7 +483,7 @@ def match_entries(new_entries, old_entries, path_info, module):
 def remove_dynamic(entries):
     result = []
     for entry in entries:
-        if entry.get('dynamic', False):
+        if entry.get('dynamic', False) or entry.get('builtin', False):
             continue
         result.append(entry)
     return result