From 44e6bb6f7a8839db42f574442973bbf600e1614b Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Mon, 30 Dec 2024 21:11:17 +0100
Subject: [PATCH] Add 'idempotent' attribute (#337)

* Add 'idempotent' attribute.

* Mention check mode in attribute description.

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

---------

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
---
 plugins/doc_fragments/attributes.py    | 14 ++++++++++++++
 plugins/modules/api.py                 |  4 ++++
 plugins/modules/api_facts.py           |  1 +
 plugins/modules/api_find_and_modify.py |  2 ++
 plugins/modules/api_info.py            |  1 +
 plugins/modules/api_modify.py          |  2 ++
 plugins/modules/command.py             |  4 ++++
 plugins/modules/facts.py               |  1 +
 8 files changed, 29 insertions(+)

diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
index d4f407f0..b8e68bff 100644
--- a/plugins/doc_fragments/attributes.py
+++ b/plugins/doc_fragments/attributes.py
@@ -21,6 +21,20 @@ class ModuleDocFragment(object):
   platform:
     description: Target OS/families that can be operated against.
     support: N/A
+  idempotent:
+    description:
+      - When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+      - This assumes that the system controlled/queried by the module has not changed in a relevant way.
+"""
+
+    # Should be used together with the standard fragment
+    IDEMPOTENT_NOT_MODIFY_STATE = r"""
+options: {}
+attributes:
+  idempotent:
+    support: full
+    details:
+      - This action does not modify state.
 """
 
     # Should be used together with the standard fragment
diff --git a/plugins/modules/api.py b/plugins/modules/api.py
index 404569d8..7d900455 100644
--- a/plugins/modules/api.py
+++ b/plugins/modules/api.py
@@ -33,6 +33,10 @@
     platforms: RouterOS
   action_group:
     version_added: 2.1.0
+  idempotent:
+    support: N/A
+    details:
+      - Whether the executed command is idempotent depends on the operation performed.
 options:
   path:
     description:
diff --git a/plugins/modules/api_facts.py b/plugins/modules/api_facts.py
index e1fb70a3..b6d12610 100644
--- a/plugins/modules/api_facts.py
+++ b/plugins/modules/api_facts.py
@@ -29,6 +29,7 @@
   - community.routeros.attributes.actiongroup_api
   - community.routeros.attributes.facts
   - community.routeros.attributes.facts_module
+  - community.routeros.attributes.idempotent_not_modify_state
 attributes:
   platform:
     support: full
diff --git a/plugins/modules/api_find_and_modify.py b/plugins/modules/api_find_and_modify.py
index f6aab9ff..817451c6 100644
--- a/plugins/modules/api_find_and_modify.py
+++ b/plugins/modules/api_find_and_modify.py
@@ -35,6 +35,8 @@
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: full
 options:
   path:
     description:
diff --git a/plugins/modules/api_info.py b/plugins/modules/api_info.py
index f6965480..e68ded02 100644
--- a/plugins/modules/api_info.py
+++ b/plugins/modules/api_info.py
@@ -28,6 +28,7 @@
   - community.routeros.api.restrict
   - community.routeros.attributes
   - community.routeros.attributes.actiongroup_api
+  - community.routeros.attributes.idempotent_not_modify_state
   - community.routeros.attributes.info_module
 attributes:
   platform:
diff --git a/plugins/modules/api_modify.py b/plugins/modules/api_modify.py
index 4abc8fc6..b4a77652 100644
--- a/plugins/modules/api_modify.py
+++ b/plugins/modules/api_modify.py
@@ -42,6 +42,8 @@
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: full
 options:
   path:
     description:
diff --git a/plugins/modules/command.py b/plugins/modules/command.py
index 306f6482..90f97337 100644
--- a/plugins/modules/command.py
+++ b/plugins/modules/command.py
@@ -29,6 +29,10 @@
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: N/A
+    details:
+      - Whether the executed command is idempotent depends on the command.
 options:
   commands:
     description:
diff --git a/plugins/modules/facts.py b/plugins/modules/facts.py
index 21013aa0..7b169b71 100644
--- a/plugins/modules/facts.py
+++ b/plugins/modules/facts.py
@@ -19,6 +19,7 @@
   - community.routeros.attributes
   - community.routeros.attributes.facts
   - community.routeros.attributes.facts_module
+  - community.routeros.attributes.idempotent_not_modify_state
 attributes:
   platform:
     support: full