Release 3.10.0.

* Handle IP addresses configured on disappeared interfaces

* Handle IP addresses configured on disappeared interfaces

Always set type property, add changelog fragment

* Handle IP addresses configured on disappeared interfaces (wording)

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

---------

Co-authored-by: Claudio Luck <claudio.luck@datact.ch>
Co-authored-by: Felix Fontein <felix@fontein.de>

.git-blame-ignore-revs

@@ -0,0 +1,6 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Reformat YAML: https://github.com/ansible-collections/community.routeros/pull/369
+08152376de116e7d933d19ee25318f7a2eb222ae

.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      ci:
+        patterns:
+          - "*"

.github/workflows/ansible-test.yml

@@ -1,158 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-# For the comprehensive list of the inputs supported by the ansible-community/ansible-test-gh-action GitHub Action, see
-# https://github.com/marketplace/actions/ansible-test
-
-name: CI
-on:
-  # Run CI against all pushes (direct commits, also merged PRs), Pull Requests
-  push:
-    branches:
-      - main
-      - stable-*
-  pull_request:
-  # Run CI once per day (at 05:15 UTC)
-  schedule:
-    - cron: '15 5 * * *'
-
-jobs:
-  sanity:
-    name: Sanity (Ⓐ${{ matrix.ansible }})
-    strategy:
-      matrix:
-        ansible:
-          # It's important that Sanity is tested against all stable-X.Y branches
-          # Testing against `devel` may fail as new tests are added.
-          - stable-2.9
-          - stable-2.10
-          - stable-2.11
-          - stable-2.12
-          - stable-2.13
-          - stable-2.14
-          - stable-2.15
-          - devel
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
-    runs-on: >-
-      ${{ contains(fromJson(
-          '["stable-2.9", "stable-2.10", "stable-2.11"]'
-      ), matrix.ansible) && 'ubuntu-20.04' || 'ubuntu-latest' }}
-    steps:
-      - name: Perform sanity testing
-        uses: felixfontein/ansible-test-gh-action@main
-        with:
-          ansible-core-version: ${{ matrix.ansible }}
-          testing-type: sanity
-          # NOTE: we're installing with git to work around Galaxy being a huge PITA (https://github.com/ansible/galaxy/issues/2429)
-          pre-test-cmd: |-
-            git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.netcommon.git ../../ansible/netcommon
-            git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.utils.git ../../ansible/utils
-
-  units:
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
-    runs-on: >-
-      ${{ contains(fromJson(
-          '["stable-2.9", "stable-2.10", "stable-2.11"]'
-      ), matrix.ansible) && 'ubuntu-20.04' || 'ubuntu-latest' }}
-    name: Units (Ⓐ${{ matrix.ansible }})
-    strategy:
-      # As soon as the first unit test fails, cancel the others to free up the CI queue
-      fail-fast: true
-      matrix:
-        ansible:
-          - stable-2.9
-          - stable-2.10
-          - stable-2.11
-          - stable-2.12
-          - stable-2.13
-          - stable-2.14
-          - stable-2.15
-          - devel
-
-    steps:
-      - name: >-
-          Perform unit testing against
-          Ansible version ${{ matrix.ansible }}
-        uses: felixfontein/ansible-test-gh-action@main
-        with:
-          ansible-core-version: ${{ matrix.ansible }}
-          testing-type: units
-          # NOTE: we're installing with git to work around Galaxy being a huge PITA (https://github.com/ansible/galaxy/issues/2429)
-          pre-test-cmd: |-
-            git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.netcommon.git ../../ansible/netcommon
-            git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.utils.git ../../ansible/utils
-
-  integration:
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
-    runs-on: >-
-      ${{ contains(fromJson(
-          '["stable-2.9", "stable-2.10", "stable-2.11"]'
-      ), matrix.ansible) && 'ubuntu-20.04' || 'ubuntu-latest' }}
-    name: I (Ⓐ${{ matrix.ansible }}+py${{ matrix.python }})
-    strategy:
-      fail-fast: false
-      matrix:
-        ansible:
-          - devel
-        python:
-          - 3.9
-          - "3.10"
-          - "3.11"
-        include:
-          # 2.9
-          - ansible: stable-2.9
-            python: 2.7
-          - ansible: stable-2.9
-            python: 3.5
-          # 2.10
-          - ansible: stable-2.10
-            python: 3.5
-          # 2.11
-          - ansible: stable-2.11
-            python: 2.7
-          - ansible: stable-2.11
-            python: 3.6
-          # 2.12
-          - ansible: stable-2.12
-            python: 3.8
-          # 2.13
-          - ansible: stable-2.13
-            python: "3.10"
-          # 2.14
-          - ansible: stable-2.14
-            python: "3.9"
-          # 2.15
-          - ansible: stable-2.15
-            python: "3.11"
-
-    steps:
-      - name: >-
-          Perform integration testing against
-          Ansible version ${{ matrix.ansible }}
-          under Python ${{ matrix.python }}
-        uses: felixfontein/ansible-test-gh-action@main
-        with:
-          ansible-core-version: ${{ matrix.ansible }}
-          integration-continue-on-error: 'false'
-          integration-diff: 'false'
-          integration-retry-on-error: 'true'
-          # NOTE: we're installing with git to work around Galaxy being a huge PITA (https://github.com/ansible/galaxy/issues/2429)
-          pre-test-cmd: |-
-            git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.netcommon.git ../../ansible/netcommon
-            git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.utils.git ../../ansible/utils
-          target-python-version: ${{ matrix.python }}
-          testing-type: integration

.github/workflows/docs-pr.yml

@@ -7,7 +7,7 @@ name: Collection Docs
 concurrency:
   group: docs-pr-${{ github.head_ref }}
   cancel-in-progress: true
-on:
+'on':
   pull_request_target:
     types: [opened, synchronize, reopened, closed]
 
@@ -32,18 +32,23 @@ jobs:
       init-extra-html-theme-options: |
         documentation_home_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/branch/main/
       render-file-line: '> * `$<status>` [$<path_tail>](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}/$<path_tail>)'
+      provide-link-targets: |
+        ansible_collections.ansible.netcommon.network_cli_connection__parameter-ssh_type
 
   publish-docs-gh-pages:
     # for now we won't run this on forks
     if: github.repository == 'ansible-collections/community.routeros'
     permissions:
       contents: write
+      pages: write
+      id-token: write
     needs: [build-docs]
     name: Publish Ansible Docs
     uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
     with:
       artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
       action: ${{ (github.event.action == 'closed' || needs.build-docs.outputs.changed != 'true') && 'teardown' || 'publish' }}
+      publish-gh-pages-branch: true
     secrets:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/docs-push.yml

@@ -7,7 +7,7 @@ name: Collection Docs
 concurrency:
   group: docs-push-${{ github.sha }}
   cancel-in-progress: true
-on:
+'on':
   push:
     branches:
       - main
@@ -28,7 +28,7 @@ jobs:
     uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
     with:
       collection-name: community.routeros
-      init-lenient: false
+      init-lenient: true
       init-fail-on-error: true
       squash-hierarchy: true
       init-project: Community.Routeros Collection
@@ -43,10 +43,13 @@ jobs:
     if: github.repository == 'ansible-collections/community.routeros'
     permissions:
       contents: write
+      pages: write
+      id-token: write
     needs: [build-docs]
     name: Publish Ansible Docs
     uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
     with:
       artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+      publish-gh-pages-branch: true
     secrets:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ee.yml

@@ -1,175 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-name: execution environment
-on:
-  # Run CI against all pushes (direct commits, also merged PRs), Pull Requests
-  push:
-    branches:
-      - main
-      - stable-*
-  pull_request:
-  # Run CI once per day (at 05:15 UTC)
-  # This ensures that even if there haven't been commits that we are still testing against latest version of ansible-builder
-  schedule:
-    - cron: '15 5 * * *'
-
-env:
-  NAMESPACE: community
-  COLLECTION_NAME: routeros
-
-jobs:
-  build:
-    name: Build and test EE (${{ matrix.name }})
-    strategy:
-      fail-fast: false
-      matrix:
-        name:
-          - ''
-        ansible_core:
-          - ''
-        ansible_runner:
-          - ''
-        base_image:
-          - ''
-        pre_base:
-          - ''
-        extra_vars:
-          - ''
-        other_deps:
-          - ''
-        exclude:
-          - ansible_core: ''
-        include:
-          - name: ansible-core devel @ RHEL UBI 9
-            ansible_core: https://github.com/ansible/ansible/archive/devel.tar.gz
-            ansible_runner: ansible-runner
-            base_image: docker.io/redhat/ubi9:latest
-            pre_base: '"#"'
-          - name: ansible-core 2.15 @ Rocky Linux 9
-            ansible_core: https://github.com/ansible/ansible/archive/stable-2.15.tar.gz
-            ansible_runner: ansible-runner
-            base_image: quay.io/rockylinux/rockylinux:9
-            pre_base: '"#"'
-          - name: ansible-core 2.14 @ CentOS Stream 9
-            ansible_core: https://github.com/ansible/ansible/archive/stable-2.14.tar.gz
-            ansible_runner: ansible-runner
-            base_image: quay.io/centos/centos:stream9
-            pre_base: '"#"'
-          - name: ansible-core 2.13 @ RHEL UBI 8
-            ansible_core: https://github.com/ansible/ansible/archive/stable-2.13.tar.gz
-            ansible_runner: ansible-runner
-            other_deps: |2
-                python_interpreter:
-                  package_system: python39 python39-pip python39-wheel python39-cryptography
-            base_image: docker.io/redhat/ubi8:latest
-            pre_base: '"#"'
-          - name: ansible-core 2.12 @ CentOS Stream 8
-            ansible_core: https://github.com/ansible/ansible/archive/stable-2.12.tar.gz
-            ansible_runner: ansible-runner
-            other_deps: |2
-                python_interpreter:
-                  package_system: python39 python39-pip python39-wheel python39-cryptography
-            base_image: quay.io/centos/centos:stream8
-            pre_base: '"#"'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v3
-        with:
-          path: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-
-      - name: Install ansible-builder and ansible-navigator
-        run: pip install ansible-builder ansible-navigator
-
-      - name: Verify requirements
-        run: ansible-builder introspect --sanitize .
-
-      - name: Make sure galaxy.yml has version entry
-        run: >-
-          python -c
-          'import yaml ;
-          f = open("galaxy.yml", "rb") ;
-          data = yaml.safe_load(f) ;
-          f.close() ;
-          data["version"] = data.get("version") or "0.0.1" ;
-          f = open("galaxy.yml", "wb") ;
-          f.write(yaml.dump(data).encode("utf-8")) ;
-          f.close() ;
-          '
-        working-directory: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
-
-      - name: Build collection
-        run: |
-          ansible-galaxy collection build --output-path ../../../
-        working-directory: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
-
-      - name: Create files for building execution environment
-        run: |
-          COLLECTION_FILENAME="$(ls "${{ env.NAMESPACE }}-${{ env.COLLECTION_NAME }}"-*.tar.gz)"
-
-          # EE config
-          cat > execution-environment.yml <<EOF
-          ---
-          version: 3
-          dependencies:
-            ansible_core:
-              package_pip: ${{ matrix.ansible_core }}
-            ansible_runner:
-              package_pip: ${{ matrix.ansible_runner }}
-            galaxy: requirements.yml
-          ${{ matrix.other_deps }}
-
-          images:
-            base_image:
-              name: ${{ matrix.base_image }}
-
-          additional_build_files:
-            - src: ${COLLECTION_FILENAME}
-              dest: src
-
-          additional_build_steps:
-            prepend_base:
-              - ${{ matrix.pre_base }}
-          EOF
-          echo "::group::execution-environment.yml"
-          cat execution-environment.yml
-          echo "::endgroup::"
-
-          # Requirements
-          cat > requirements.yml <<EOF
-          ---
-          collections:
-            - name: src/${COLLECTION_FILENAME}
-              type: file
-          EOF
-          echo "::group::requirements.yml"
-          cat requirements.yml
-          echo "::endgroup::"
-
-      - name: Build image based on ${{ matrix.base_image }}
-        run: |
-          ansible-builder build --verbosity 3 --tag test-ee:latest --container-runtime docker
-
-      - name: Show images
-        run: docker image ls
-
-      - name: Run basic tests
-        run: >
-          ansible-navigator run
-          --mode stdout
-          --container-engine docker
-          --pull-policy never
-          --set-environment-variable ANSIBLE_PRIVATE_ROLE_VARS=true
-          --execution-environment-image test-ee:latest
-          -v
-          all.yml
-          ${{ matrix.extra_vars }}
-        working-directory: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}/tests/ee

.github/workflows/extra-tests.yml

@@ -1,48 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-name: extra-tests
-on:
-  # Run CI against all pushes (direct commits, also merged PRs), Pull Requests
-  push:
-    branches:
-      - main
-      - stable-*
-  pull_request:
-  # Run CI once per day (at 05:15 UTC)
-  # This ensures that even if there haven't been commits that we are still testing against latest version of ansible-test for each ansible-base version
-  schedule:
-    - cron: '15 5 * * *'
-env:
-  NAMESPACE: community
-  COLLECTION_NAME: routeros
-
-jobs:
-  extra-sanity:
-    name: Extra Sanity
-    runs-on: ubuntu-latest
-    steps:
-
-      - name: Check out code
-        uses: actions/checkout@v3
-        with:
-          path: ansible_collections/${{env.NAMESPACE}}/${{env.COLLECTION_NAME}}
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
-
-      - name: Install ansible-core
-        run: pip install https://github.com/ansible/ansible/archive/devel.tar.gz --disable-pip-version-check
-
-      - name: Install collection dependencies
-        run: git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ./ansible_collections/community/internal_test_tools
-        # NOTE: we're installing with git to work around Galaxy being a huge PITA (https://github.com/ansible/galaxy/issues/2429)
-        # run: ansible-galaxy collection install community.internal_test_tools -p .
-
-      - name: Run sanity tests
-        run: ../../community/internal_test_tools/tools/run.py --color
-        working-directory: ./ansible_collections/${{env.NAMESPACE}}/${{env.COLLECTION_NAME}}

.github/workflows/import-galaxy.yml

@@ -1,88 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-name: import-galaxy
-on:
-  # Run CI against all pushes (direct commits, also merged PRs) to main, and all Pull Requests
-  push:
-    branches:
-      - main
-      - stable-*
-  pull_request:
-
-env:
-  # Adjust this to your collection
-  NAMESPACE: community
-  COLLECTION_NAME: routeros
-
-jobs:
-  build-collection:
-    name: Build collection artifact
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v3
-        with:
-          path: ./checkout
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
-
-      - name: Install ansible-core
-        run: pip install https://github.com/ansible/ansible/archive/devel.tar.gz --disable-pip-version-check
-
-      - name: Make sure galaxy.yml has version entry
-        run: >-
-          python -c
-          'import yaml ;
-          f = open("galaxy.yml", "rb") ;
-          data = yaml.safe_load(f) ;
-          f.close() ;
-          data["version"] = data.get("version") or "0.0.1" ;
-          f = open("galaxy.yml", "wb") ;
-          f.write(yaml.dump(data).encode("utf-8")) ;
-          f.close() ;
-          '
-        working-directory: ./checkout
-
-      - name: Build collection
-        run: ansible-galaxy collection build
-        working-directory: ./checkout
-
-      - name: Copy artifact into subdirectory
-        run: mkdir ./artifact && mv ./checkout/${{ env.NAMESPACE }}-${{ env.COLLECTION_NAME }}-*.tar.gz ./artifact
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: ${{ env.NAMESPACE }}-${{ env.COLLECTION_NAME }}-${{ github.sha }}
-          path: ./artifact/
-
-  import-galaxy:
-    name: Import artifact with Galaxy importer
-    runs-on: ubuntu-latest
-    needs:
-      - build-collection
-    steps:
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
-
-      - name: Install ansible-core
-        run: pip install https://github.com/ansible/ansible/archive/devel.tar.gz --disable-pip-version-check
-
-      - name: Install galaxy-importer
-        run: pip install galaxy-importer --disable-pip-version-check
-
-      - name: Download artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: ${{ env.NAMESPACE }}-${{ env.COLLECTION_NAME }}-${{ github.sha }}
-
-      - name: Run Galaxy importer
-        run: python -m galaxy_importer.main ${{ env.NAMESPACE }}-${{ env.COLLECTION_NAME }}-*.tar.gz

.github/workflows/nox.yml

@@ -0,0 +1,35 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+name: nox
+'on':
+  push:
+    branches:
+      - main
+      - stable-*
+  pull_request:
+  # Run CI once per day (at 05:15 UTC)
+  schedule:
+    - cron: '15 5 * * *'
+  workflow_dispatch:
+
+jobs:
+  nox:
+    runs-on: ubuntu-latest
+    name: "Run extra sanity tests"
+    steps:
+      - name: Check out collection
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Run nox
+        uses: ansible-community/antsibull-nox@main
+
+  ansible-test:
+    uses: ansible-community/antsibull-nox/.github/workflows/reusable-nox-matrix.yml@main
+    with:
+      upload-codecov: true
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/reuse.yml

@@ -1,32 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-name: Verify REUSE
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-  # Run CI once per day (at 05:15 UTC)
-  schedule:
-    - cron: '15 5 * * *'
-
-jobs:
-  check:
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Install dependencies
-        run: |
-          pip install reuse
-
-      - name: Check REUSE compliance
-        run: |
-          reuse lint

.gitignore

@@ -4,6 +4,7 @@
 
 /tests/output/
 /changelogs/.plugin-cache.yaml
+/tests/integration/inventory
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.reuse/dep5

@@ -1,5 +0,0 @@
-Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-
-Files: changelogs/fragments/*
-Copyright: Ansible Project
-License: GPL-3.0-or-later

.yamllint

@@ -0,0 +1,53 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 300
+    level: error
+  document-start:
+    present: true
+  document-end: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

.yamllint-docs

@@ -0,0 +1,54 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 160
+    level: error
+  document-start:
+    present: false
+  document-end:
+    present: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

.yamllint-examples

@@ -0,0 +1,54 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 160
+    level: error
+  document-start:
+    present: true
+  document-end:
+    present: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

.yamllint-extra-docs

@@ -0,0 +1,53 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 160
+    level: error
+  document-start: disable
+  document-end:
+    present: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

CHANGELOG.rst

@@ -4,6 +4,485 @@ Community RouterOS Release Notes
 
 .. contents:: Topics
 
+v3.10.0
+=======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add ``show-at-cli-login`` property in ``system note`` (https://github.com/ansible-collections/community.routeros/pull/392).
+- api_info, api_modify - set default value for ``include`` and ``exclude`` properties in ``system note`` to an empty string (https://github.com/ansible-collections/community.routeros/pull/394).
+
+Bugfixes
+--------
+
+- api_facts - also report interfaces that are inferred only by reference by IP addresses.
+  RouterOS's APIs have IPv4 and IPv6 addresses point at interfaces by their name, which can
+  change over time and in-between API calls, such that interfaces may have been enumerated
+  under another name, or not at all (for example when removed). Such interfaces are now reported
+  under their new or temporary name and with a synthetic ``type`` property set to differentiate
+  the more likely and positively confirmed removal case (with ``type: "ansible:unknown"``) from
+  the unlikely and probably transient naming mismatch (with ``type: "ansible:mismatch"``).
+  Previously, the api_facts module would have crashed with a ``KeyError`` exception
+  (https://github.com/ansible-collections/community.routeros/pull/391).
+
+v3.9.0
+======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- api_info, api modify - add ``remote-log-format``, ``remote-protocol``, and ``event-delimiter`` to ``system logging action`` (https://github.com/ansible-collections/community.routeros/pull/381).
+- api_info, api_modify - add ``disable-link-local-address`` and ``stale-neighbor-timeout`` fields to ``ipv6 settings`` (https://github.com/ansible-collections/community.routeros/pull/380).
+- api_info, api_modify - adjust neighbor limit fields in ``ipv6 settings`` to match RouterOS 7.18 and newer (https://github.com/ansible-collections/community.routeros/pull/380).
+- api_info, api_modify - set ``passthrough`` default in ``ip firewall mangle`` to ``true`` for RouterOS 7.19 and newer (https://github.com/ansible-collections/community.routeros/pull/382).
+- api_info, api_modify - since RouterOS 7.17 VRF is supported for OVPN server. It now supports multiple entries, while ``api_modify`` so far only accepted a single entry. The ``interface ovpn-server server`` path now allows multiple entries on RouterOS 7.17 and newer (https://github.com/ansible-collections/community.routeros/pull/383).
+
+Bugfixes
+--------
+
+- routeros terminal plugin - fix ``terminal_stdout_re`` pattern to handle long system identities when connecting to RouterOS through SSH (https://github.com/ansible-collections/community.routeros/pull/386).
+
+v3.8.1
+======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Bugfixes
+--------
+
+- facts and api_facts modules - prevent deprecation warnings when used with ansible-core 2.19 (https://github.com/ansible-collections/community.routeros/pull/384).
+
+v3.8.0
+======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add ``interface ethernet switch port-isolation`` which is supported since RouterOS 6.43 (https://github.com/ansible-collections/community.routeros/pull/375).
+- api_info, api_modify - add ``routing bfd configuration``. Officially stabilized BFD support for BGP and OSPF is available since RouterOS 7.11
+  (https://github.com/ansible-collections/community.routeros/pull/375).
+- api_modify, api_info - support API path ``ip ipsec mode-config`` (https://github.com/ansible-collections/community.routeros/pull/376).
+
+v3.7.0
+======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_find_and_modify - allow to control whether ``dynamic`` and/or ``builtin`` entries are ignored with the new ``ignore_dynamic`` and ``ignore_builtin`` options (https://github.com/ansible-collections/community.routeros/issues/372, https://github.com/ansible-collections/community.routeros/pull/373).
+- api_info, api_modify - add ``port-cost-mode`` to ``interface bridge`` which is supported since RouterOS 7.13 (https://github.com/ansible-collections/community.routeros/pull/371).
+
+v3.6.0
+======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add ``mdns-repeat-ifaces`` to ``ip dns`` for RouterOS 7.16 and newer (https://github.com/ansible-collections/community.routeros/pull/358).
+- api_info, api_modify - field name change in ``routing bgp connection`` path implemented by RouterOS 7.19 and newer (https://github.com/ansible-collections/community.routeros/pull/360).
+- api_info, api_modify - rename ``is-responder`` property in ``interface wireguard peers`` to ``responder`` for RouterOS 7.17 and newer (https://github.com/ansible-collections/community.routeros/pull/364).
+
+v3.5.0
+======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - change default for ``/ip/cloud/ddns-enabled`` for RouterOS 7.17 and newer from ``yes`` to ``auto`` (https://github.com/ansible-collections/community.routeros/pull/350).
+
+v3.4.0
+======
+
+Release Summary
+---------------
+
+Feature and bugfix release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add support for the ``ip dns forwarders`` path implemented by RouterOS 7.17 and newer (https://github.com/ansible-collections/community.routeros/pull/343).
+
+Bugfixes
+--------
+
+- api_info, api_modify - remove the primary key ``action`` from the ``interface wifi provisioning`` path, since RouterOS also allows to create completely duplicate entries (https://github.com/ansible-collections/community.routeros/issues/344, https://github.com/ansible-collections/community.routeros/pull/345).
+
+v3.3.0
+======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add missing attribute ``require-message-auth`` for the ``radius`` path which exists since RouterOS version 7.15 (https://github.com/ansible-collections/community.routeros/issues/338, https://github.com/ansible-collections/community.routeros/pull/339).
+- api_info, api_modify - add the ``interface 6to4`` path. Used to manage IPv6 tunnels via tunnel-brokers like HE, where native IPv6 is not provided (https://github.com/ansible-collections/community.routeros/pull/342).
+- api_info, api_modify - add the ``interface wireless access-list`` and ``interface wireless connect-list`` paths (https://github.com/ansible-collections/community.routeros/issues/284, https://github.com/ansible-collections/community.routeros/pull/340).
+- api_info, api_modify - add the ``use-interface-duid`` option for ``ipv6 dhcp-client`` path. This option prevents issues with Fritzbox modems and routers, when using virtual interfaces (like VLANs) may create duplicated records in hosts config, this breaks original "expose-host" function. Also add the ``script``, ``custom-duid`` and ``validate-server-duid`` as backport from 7.15 version update (https://github.com/ansible-collections/community.routeros/pull/341).
+
+v3.2.0
+======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add support for the ``routing filter community-list`` path implemented by RouterOS 7 and newer (https://github.com/ansible-collections/community.routeros/pull/331).
+
+v3.1.0
+======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add missing fields ``comment``, ``next-pool`` to ``ip pool`` path (https://github.com/ansible-collections/community.routeros/pull/327).
+
+Bugfixes
+--------
+
+- api_info, api_modify - fields ``log`` and ``log-prefix`` in paths ``ip firewall filter``, ``ip firewall mangle``, ``ip firewall nat``, ``ip firewall raw`` now have the correct default values (https://github.com/ansible-collections/community.routeros/pull/324).
+
+v3.0.0
+======
+
+Release Summary
+---------------
+
+Major release that drops support for End of Life Python versions and fixes check mode for community.routeros.command.
+
+Breaking Changes / Porting Guide
+--------------------------------
+
+- command - the module no longer declares that it supports check mode (https://github.com/ansible-collections/community.routeros/pull/318).
+
+Removed Features (previously deprecated)
+----------------------------------------
+
+- The collection no longer supports Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. If you need to continue using End of Life versions of Ansible/ansible-base/ansible-core, please use community.routeros 2.x.y (https://github.com/ansible-collections/community.routeros/pull/318).
+
+v2.20.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add new parameters from the RouterOS 7.16 release (https://github.com/ansible-collections/community.routeros/pull/323).
+- api_info, api_modify - add support ``interface l2tp-client`` configuration (https://github.com/ansible-collections/community.routeros/pull/322).
+- api_info, api_modify - add support for the ``cpu-frequency``, ``memory-frequency``, ``preboot-etherboot`` and ``preboot-etherboot-server`` properties in ``system routerboard settings`` (https://github.com/ansible-collections/community.routeros/pull/320).
+- api_info, api_modify - add support for the ``matching-type`` property in ``ip dhcp-server matcher`` introduced by RouterOS 7.16 (https://github.com/ansible-collections/community.routeros/pull/321).
+
+v2.19.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add support for the ``ip dns adlist`` path implemented by RouterOS 7.15 and newer (https://github.com/ansible-collections/community.routeros/pull/310).
+- api_info, api_modify - add support for the ``mld-version`` and ``multicast-querier`` properties in ``interface bridge`` (https://github.com/ansible-collections/community.routeros/pull/315).
+- api_info, api_modify - add support for the ``routing filter num-list`` path implemented by RouterOS 7 and newer (https://github.com/ansible-collections/community.routeros/pull/313).
+- api_info, api_modify - add support for the ``routing igmp-proxy`` path (https://github.com/ansible-collections/community.routeros/pull/309).
+- api_modify, api_info - add read-only ``default`` field to ``snmp community`` (https://github.com/ansible-collections/community.routeros/pull/311).
+
+v2.18.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info - allow to restrict the output by limiting fields to specific values with the new ``restrict`` option (https://github.com/ansible-collections/community.routeros/pull/305).
+- api_info, api_modify - add support for the ``ip dhcp-server matcher`` path (https://github.com/ansible-collections/community.routeros/pull/300).
+- api_info, api_modify - add support for the ``ipv6 nd prefix`` path (https://github.com/ansible-collections/community.routeros/pull/303).
+- api_info, api_modify - add support for the ``name`` and ``is-responder`` properties under the ``interface wireguard peers`` path introduced in RouterOS 7.15 (https://github.com/ansible-collections/community.routeros/pull/304).
+- api_info, api_modify - add support for the ``routing ospf static-neighbor`` path in RouterOS 7 (https://github.com/ansible-collections/community.routeros/pull/302).
+- api_info, api_modify - set default for ``force`` in ``ip dhcp-server option`` to an explicit ``false`` (https://github.com/ansible-collections/community.routeros/pull/300).
+- api_modify - allow to restrict what is updated by limiting fields to specific values with the new ``restrict`` option (https://github.com/ansible-collections/community.routeros/pull/305).
+
+Deprecated Features
+-------------------
+
+- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix <https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix>`__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14.
+
+Bugfixes
+--------
+
+- api_modify, api_info - change the default of ``ingress-filtering`` in paths ``interface bridge`` and ``interface bridge port`` back to ``false`` for RouterOS before version 7 (https://github.com/ansible-collections/community.routeros/pull/305).
+
+v2.17.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add ``system health settings`` path (https://github.com/ansible-collections/community.routeros/pull/294).
+- api_info, api_modify - add missing path ``/system resource irq rps`` (https://github.com/ansible-collections/community.routeros/pull/295).
+- api_info, api_modify - add parameter ``host-key-type`` for ``ip ssh`` path (https://github.com/ansible-collections/community.routeros/issues/280, https://github.com/ansible-collections/community.routeros/pull/297).
+
+v2.16.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add missing path ``/ppp secret`` (https://github.com/ansible-collections/community.routeros/pull/286).
+- api_info, api_modify - minor changes ``/interface ethernet`` path fields (https://github.com/ansible-collections/community.routeros/pull/288).
+
+v2.15.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - Add RouterOS 7.x support to ``/mpls ldp`` path (https://github.com/ansible-collections/community.routeros/pull/271).
+- api_info, api_modify - add ``/ip route rule`` path for RouterOS 6.x (https://github.com/ansible-collections/community.routeros/pull/278).
+- api_info, api_modify - add ``/routing filter`` path for RouterOS 6.x (https://github.com/ansible-collections/community.routeros/pull/279).
+- api_info, api_modify - add default value for ``from-pool`` field in ``/ipv6 address`` (https://github.com/ansible-collections/community.routeros/pull/270).
+- api_info, api_modify - add missing path ``/interface pppoe-server server`` (https://github.com/ansible-collections/community.routeros/pull/273).
+- api_info, api_modify - add missing path ``/ip dhcp-relay`` (https://github.com/ansible-collections/community.routeros/pull/276).
+- api_info, api_modify - add missing path ``/queue simple`` (https://github.com/ansible-collections/community.routeros/pull/269).
+- api_info, api_modify - add missing path ``/queue type`` (https://github.com/ansible-collections/community.routeros/pull/274).
+- api_info, api_modify - add missing paths ``/routing bgp aggregate``, ``/routing bgp network`` and ``/routing bgp peer`` (https://github.com/ansible-collections/community.routeros/pull/277).
+- api_info, api_modify - add support for paths ``/mpls interface``, ``/mpls ldp accept-filter``, ``/mpls ldp advertise-filter`` and ``mpls ldp interface`` (https://github.com/ansible-collections/community.routeros/pull/272).
+
+v2.14.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add read-only fields ``installed-version``, ``latest-version`` and ``status`` in ``system package update`` (https://github.com/ansible-collections/community.routeros/pull/263).
+- api_info, api_modify - added support for ``interface wifi`` and its sub-paths (https://github.com/ansible-collections/community.routeros/pull/266).
+- api_info, api_modify - remove default value for read-only ``running`` field in ``interface wireless`` (https://github.com/ansible-collections/community.routeros/pull/264).
+
+v2.13.0
+=======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - make path ``user group`` modifiable and add ``comment`` attribute (https://github.com/ansible-collections/community.routeros/issues/256, https://github.com/ansible-collections/community.routeros/pull/257).
+- api_modify, api_info - add support for the ``ip vrf`` path in RouterOS 7  (https://github.com/ansible-collections/community.routeros/pull/259)
+
+Bugfixes
+--------
+
+- facts - fix date not getting removed for idempotent config export (https://github.com/ansible-collections/community.routeros/pull/262).
+
+v2.12.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add ``interface ovpn-client`` path (https://github.com/ansible-collections/community.routeros/issues/242, https://github.com/ansible-collections/community.routeros/pull/244).
+- api_info, api_modify - add ``radius`` path (https://github.com/ansible-collections/community.routeros/issues/241, https://github.com/ansible-collections/community.routeros/pull/245).
+- api_info, api_modify - add ``routing rule`` path (https://github.com/ansible-collections/community.routeros/issues/162, https://github.com/ansible-collections/community.routeros/pull/246).
+- api_info, api_modify - add missing path ``routing bgp template`` (https://github.com/ansible-collections/community.routeros/pull/243).
+- api_info, api_modify - add support for the ``tx-power`` attribute in ``interface wireless`` (https://github.com/ansible-collections/community.routeros/pull/239).
+- api_info, api_modify - removed ``host`` primary key in ``tool netwatch`` path (https://github.com/ansible-collections/community.routeros/pull/248).
+- api_modify, api_info - added support for ``interface wifiwave2`` (https://github.com/ansible-collections/community.routeros/pull/226).
+
+v2.11.0
+=======
+
+Release Summary
+---------------
+
+Feature and bugfix release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add missing DoH parameters ``doh-max-concurrent-queries``, ``doh-max-server-connections``, and ``doh-timeout`` to the ``ip dns`` path (https://github.com/ansible-collections/community.routeros/issues/230, https://github.com/ansible-collections/community.routeros/pull/235)
+- api_info, api_modify - add missing parameters ``address-list``, ``address-list-timeout``, ``randomise-ports``, and ``realm`` to subpaths of the ``ip firewall`` path (https://github.com/ansible-collections/community.routeros/issues/236, https://github.com/ansible-collections/community.routeros/pull/237).
+- api_info, api_modify - mark the ``interface wireless`` parameter ``running`` as read-only (https://github.com/ansible-collections/community.routeros/pull/233).
+- api_info, api_modify - set the default value to ``false`` for the  ``disabled`` parameter in some more paths where it can be seen in the documentation (https://github.com/ansible-collections/community.routeros/pull/237).
+- api_modify - add missing ``comment`` attribute to ``/routing id`` (https://github.com/ansible-collections/community.routeros/pull/234).
+- api_modify - add missing attributes to the ``routing bgp connection`` path (https://github.com/ansible-collections/community.routeros/pull/234).
+- api_modify - add versioning to the ``/tool e-mail`` path (RouterOS 7.12 release) (https://github.com/ansible-collections/community.routeros/pull/234).
+- api_modify - make ``/ip traffic-flow target`` a multiple value attribute (https://github.com/ansible-collections/community.routeros/pull/234).
+
+v2.10.0
+=======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- api_info - add new ``include_read_only`` option to select behavior for read-only values. By default these are not returned (https://github.com/ansible-collections/community.routeros/pull/213).
+- api_info, api_modify - add support for ``address-list`` and ``match-subdomain`` introduced by RouterOS 7.7 in the ``ip dns static`` path (https://github.com/ansible-collections/community.routeros/pull/197).
+- api_info, api_modify - add support for ``user``, ``time`` and ``gmt-offset`` under the ``system clock`` path (https://github.com/ansible-collections/community.routeros/pull/210).
+- api_info, api_modify - add support for the ``interface ppp-client`` path (https://github.com/ansible-collections/community.routeros/pull/199).
+- api_info, api_modify - add support for the ``interface wireless`` path (https://github.com/ansible-collections/community.routeros/pull/195).
+- api_info, api_modify - add support for the ``iot modbus`` path (https://github.com/ansible-collections/community.routeros/pull/205).
+- api_info, api_modify - add support for the ``ip dhcp-server option`` and ``ip dhcp-server option sets`` paths (https://github.com/ansible-collections/community.routeros/pull/223).
+- api_info, api_modify - add support for the ``ip upnp interfaces``, ``tool graphing interface``, ``tool graphing resource`` paths (https://github.com/ansible-collections/community.routeros/pull/227).
+- api_info, api_modify - add support for the ``ipv6 firewall nat`` path (https://github.com/ansible-collections/community.routeros/pull/204).
+- api_info, api_modify - add support for the ``mode`` property in ``ip neighbor discovery-settings`` introduced in RouterOS 7.7 (https://github.com/ansible-collections/community.routeros/pull/198).
+- api_info, api_modify - add support for the ``port remote-access`` path (https://github.com/ansible-collections/community.routeros/pull/224).
+- api_info, api_modify - add support for the ``routing filter rule`` and ``routing filter select-rule`` paths (https://github.com/ansible-collections/community.routeros/pull/200).
+- api_info, api_modify - add support for the ``routing table`` path in RouterOS 7 (https://github.com/ansible-collections/community.routeros/pull/215).
+- api_info, api_modify - add support for the ``tool netwatch`` path in RouterOS 7 (https://github.com/ansible-collections/community.routeros/pull/216).
+- api_info, api_modify - add support for the ``user settings`` path (https://github.com/ansible-collections/community.routeros/pull/201).
+- api_info, api_modify - add support for the ``user`` path (https://github.com/ansible-collections/community.routeros/pull/211).
+- api_info, api_modify - finalize fields for the ``interface wireless security-profiles`` path and enable it (https://github.com/ansible-collections/community.routeros/pull/203).
+- api_info, api_modify - finalize fields for the ``ppp profile`` path and enable it (https://github.com/ansible-collections/community.routeros/pull/217).
+- api_modify - add new ``handle_read_only`` and ``handle_write_only`` options to handle the module's behavior for read-only and write-only fields (https://github.com/ansible-collections/community.routeros/pull/213).
+- api_modify, api_info - support API paths ``routing id``, ``routing bgp connection`` (https://github.com/ansible-collections/community.routeros/pull/220).
+
+Bugfixes
+--------
+
+- api_info, api_modify - in the ``snmp`` path, ensure that ``engine-id-suffix`` is only available on RouterOS 7.10+, and that ``engine-id`` is read-only on RouterOS 7.10+ (https://github.com/ansible-collections/community.routeros/issues/208, https://github.com/ansible-collections/community.routeros/pull/218).
+
+v2.9.0
+======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- api_info, api_modify - add path ``caps-man channel`` and enable path ``caps-man manager interface`` (https://github.com/ansible-collections/community.routeros/issues/193, https://github.com/ansible-collections/community.routeros/pull/194).
+- api_info, api_modify - add path ``ip traffic-flow target`` (https://github.com/ansible-collections/community.routeros/issues/191, https://github.com/ansible-collections/community.routeros/pull/192).
+
+Bugfixes
+--------
+
+- api_modify, api_info - add missing parameter ``engine-id-suffix`` for the ``snmp`` path (https://github.com/ansible-collections/community.routeros/issues/189, https://github.com/ansible-collections/community.routeros/pull/190).
+
+v2.8.3
+======
+
+Release Summary
+---------------
+
+Maintenance release with updated documentation.
+
+From this version on, community.routeros is using the new `Ansible semantic markup
+<https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation>`__
+in its documentation. If you look at documentation with the ansible-doc CLI tool
+from ansible-core before 2.15, please note that it does not render the markup
+correctly. You should be still able to read it in most cases, but you need
+ansible-core 2.15 or later to see it as it is intended. Alternatively you can
+look at `the devel docsite <https://docs.ansible.com/ansible/devel/collections/community/routeros/>`__
+for the rendered HTML version of the documentation of the latest release.
+
+Known Issues
+------------
+
+- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/routeros/.
+
+v2.8.2
+======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Bugfixes
+--------
+
+- api_modify, api_info - add missing parameter ``tls`` for the ``tool e-mail`` path (https://github.com/ansible-collections/community.routeros/issues/179, https://github.com/ansible-collections/community.routeros/pull/180).
 
 v2.8.1
 ======
@@ -141,7 +620,7 @@ Known Issues
 ------------
 
 - api_modify - when limits for entries in ``queue tree`` are defined as human readable - for example ``25M`` -, the configuration will be correctly set in ROS, but the module will indicate the item is changed on every run even when there was no change done. This is caused by the ROS API which returns the number in bytes - for example ``25000000`` (which is inconsistent with the CLI behavior). In order to mitigate that, the limits have to be defined in bytes (those will still appear as human readable in the ROS CLI) (https://github.com/ansible-collections/community.routeros/pull/131).
-- api_modify, api_info - ``routing ospf area``, ``routing ospf area range``, ``routing ospf instance``, ``routing ospf interface-template`` paths are not fully implemeted for ROS6 due to the significat changes between ROS6 and ROS7 (https://github.com/ansible-collections/community.routeros/pull/131).
+- api_modify, api_info - ``routing ospf area``, ``routing ospf area range``, ``routing ospf instance``, ``routing ospf interface-template`` paths are not fully implemented for ROS6 due to the significant changes between ROS6 and ROS7 (https://github.com/ansible-collections/community.routeros/pull/131).
 
 v2.3.1
 ======
@@ -211,8 +690,8 @@ Bugfixes
 New Modules
 -----------
 
-- api_info - Retrieve information from API
-- api_modify - Modify data at paths with API
+- community.routeros.api_info - Retrieve information from API
+- community.routeros.api_modify - Modify data at paths with API
 
 v2.1.0
 ======
@@ -240,8 +719,8 @@ Bugfixes
 New Modules
 -----------
 
-- api_facts - Collect facts from remote devices running MikroTik RouterOS using the API
-- api_find_and_modify - Find and modify information using the API
+- community.routeros.api_facts - Collect facts from remote devices running MikroTik RouterOS using the API
+- community.routeros.api_find_and_modify - Find and modify information using the API
 
 v2.0.0
 ======
@@ -278,11 +757,11 @@ New Plugins
 Filter
 ~~~~~~
 
-- join - Join a list of arguments to a command
-- list_to_dict - Convert a list of arguments to a list of dictionary
-- quote_argument - Quote an argument
-- quote_argument_value - Quote an argument value
-- split - Split a command into arguments
+- community.routeros.join - Join a list of arguments to a command
+- community.routeros.list_to_dict - Convert a list of arguments to a list of dictionary
+- community.routeros.quote_argument - Quote an argument
+- community.routeros.quote_argument_value - Quote an argument value
+- community.routeros.split - Split a command into arguments
 
 v1.2.0
 ======
@@ -340,7 +819,6 @@ Release Summary
 
 This is the first production (non-prerelease) release of ``community.routeros``.
 
-
 Bugfixes
 --------
 
@@ -367,7 +845,6 @@ Release Summary
 
 The ``community.routeros`` continues the work on the Ansible RouterOS modules from their state in ``community.network`` 1.2.0. The changes listed here are thus relative to the modules ``community.network.routeros_*``.
 
-
 Minor Changes
 -------------
 

LICENSES/PSF-2.0.txt

@@ -1,48 +0,0 @@
-PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
---------------------------------------------
-
-1. This LICENSE AGREEMENT is between the Python Software Foundation
-("PSF"), and the Individual or Organization ("Licensee") accessing and
-otherwise using this software ("Python") in source or binary form and
-its associated documentation.
-
-2. Subject to the terms and conditions of this License Agreement, PSF hereby
-grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
-analyze, test, perform and/or display publicly, prepare derivative works,
-distribute, and otherwise use Python alone or in any derivative version,
-provided, however, that PSF's License Agreement and PSF's notice of copyright,
-i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
-2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Python Software Foundation;
-All Rights Reserved" are retained in Python alone or in any derivative version
-prepared by Licensee.
-
-3. In the event Licensee prepares a derivative work that is based on
-or incorporates Python or any part thereof, and wants to make
-the derivative work available to others as provided herein, then
-Licensee hereby agrees to include in any such work a brief summary of
-the changes made to Python.
-
-4. PSF is making Python available to Licensee on an "AS IS"
-basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
-IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
-DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
-FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
-INFRINGE ANY THIRD PARTY RIGHTS.
-
-5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
-A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
-OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
-
-6. This License Agreement will automatically terminate upon a material
-breach of its terms and conditions.
-
-7. Nothing in this License Agreement shall be deemed to create any
-relationship of agency, partnership, or joint venture between PSF and
-Licensee.  This License Agreement does not grant permission to use PSF
-trademarks or trade name in a trademark sense to endorse or promote
-products or services of Licensee, or any third party.
-
-8. By copying, installing or otherwise using Python, Licensee
-agrees to be bound by the terms and conditions of this License
-Agreement.

README.md

@@ -5,19 +5,40 @@ SPDX-License-Identifier: GPL-3.0-or-later
 -->
 
 # Community RouterOS Collection
-[![CI](https://github.com/ansible-collections/community.routeros/workflows/CI/badge.svg?event=push)](https://github.com/ansible-collections/community.routeros/actions) [![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.routeros)](https://codecov.io/gh/ansible-collections/community.routeros)
+[![Documentation](https://img.shields.io/badge/docs-brightgreen.svg)](https://docs.ansible.com/ansible/devel/collections/community/routeros/)
+[![CI](https://github.com/ansible-collections/community.routeros/actions/workflows/nox.yml/badge.svg?branch=main)](https://github.com/ansible-collections/community.routeros/actions)
+[![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.routeros)](https://codecov.io/gh/ansible-collections/community.routeros)
+[![REUSE status](https://api.reuse.software/badge/github.com/ansible-collections/community.routeros)](https://api.reuse.software/info/github.com/ansible-collections/community.routeros)
 
-Provides modules for [Ansible](https://www.ansible.com/community) to manage [MikroTik RouterOS](http://www.mikrotik-routeros.net/routeros.aspx) instances.
+Provides modules for [Ansible](https://www.ansible.com/community) to manage [MikroTik RouterOS](https://mikrotik.com/software) instances.
 
 You can find [documentation for the modules and plugins in this collection here](https://docs.ansible.com/ansible/devel/collections/community/routeros/).
 
+## Code of Conduct
+
+We follow [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) in all our interactions within this project.
+
+If you encounter abusive behavior violating the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html), please refer to the [policy violations](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html#policy-violations) section of the Code of Conduct for information on how to raise a complaint.
+
+## Communication
+
+* Join the Ansible forum:
+  * [Get Help](https://forum.ansible.com/c/help/6): get help or help others.Please add appropriate tags if you start new discussions, for example the `routeros` tag.
+  * [Posts tagged with 'routeros'](https://forum.ansible.com/tag/routeros): subscribe to participate in RouterOS related conversations.
+  * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
+  * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
+
+* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.
+
+For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
+
 ## Tested with Ansible
 
-Tested with the current Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 releases and the current development version of ansible-core. Ansible versions before 2.9.10 are not supported.
+Tested with the current ansible-core 2.15, ansible-core 2.16, ansible-core 2.17, ansible-core 2.18, and ansible-core 2.19 releases and the current development version of ansible-core. Ansible 2.9, ansible-base 2.10, and ansible-core versions before 2.15.0 are not supported.
 
 ## External requirements
 
-The exact requirements for every module are listed in the module documentation. 
+The exact requirements for every module are listed in the module documentation.
 
 ### Supported connections
 
@@ -163,7 +184,7 @@ See [Ansible's dev guide](https://docs.ansible.com/ansible/devel/dev_guide/devel
 
 ## Release notes
 
-See the [changelog](https://github.com/ansible-collections/community.routeros/blob/main/CHANGELOG.rst).
+See the [collection's changelog](https://github.com/ansible-collections/community.routeros/blob/main/CHANGELOG.md).
 
 ## Roadmap
 
@@ -187,4 +208,4 @@ See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/commu
 
 Parts of the collection are licensed under the [BSD 2-Clause license](https://github.com/ansible-collections/community.routeros/blob/main/LICENSES/BSD-2-Clause.txt).
 
-All files have a machine readable `SDPX-License-Identifier:` comment denoting its respective license(s) or an equivalent entry in an accompanying `.license` file. Only changelog fragments (which will not be part of a release) are covered by a blanket statement in `.reuse/dep5`. This conforms to the [REUSE specification](https://reuse.software/spec/).
+All files have a machine readable `SDPX-License-Identifier:` comment denoting its respective license(s) or an equivalent entry in an accompanying `.license` file. Only changelog fragments (which will not be part of a release) are covered by a blanket statement in `REUSE.toml`. This conforms to the [REUSE specification](https://reuse.software/spec/).

REUSE.toml

@@ -0,0 +1,11 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+version = 1
+
+[[annotations]]
+path = "changelogs/fragments/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "Ansible Project"
+SPDX-License-Identifier = "GPL-3.0-or-later"

antsibull-nox.toml

@@ -0,0 +1,97 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+[collection_sources]
+"community.internal_test_tools" = "git+https://github.com/ansible-collections/community.internal_test_tools.git,main"
+"community.netcommon" = "git+https://github.com/ansible-collections/ansible.netcommon.git,main"
+"community.utils" = "git+https://github.com/ansible-collections/ansible.utils.git,main"
+
+[sessions]
+
+[sessions.lint]
+run_isort = false
+run_black = false
+run_flake8 = false
+run_pylint = false
+run_yamllint = true
+yamllint_config = ".yamllint"
+yamllint_config_plugins = ".yamllint-docs"
+yamllint_config_plugins_examples = ".yamllint-examples"
+yamllint_config_extra_docs = ".yamllint-extra-docs"
+run_mypy = false
+
+[sessions.docs_check]
+validate_collection_refs="all"
+codeblocks_restrict_types = [
+    "ansible-output",
+    "ini",
+    "yaml",
+    "yaml+jinja",
+]
+codeblocks_restrict_type_exact_case = true
+codeblocks_allow_without_type = false
+codeblocks_allow_literal_blocks = false
+
+[sessions.license_check]
+
+[sessions.extra_checks]
+run_no_unwanted_files = true
+no_unwanted_files_module_extensions = [".py"]
+no_unwanted_files_yaml_extensions = [".yml"]
+run_action_groups = true
+run_no_trailing_whitespace = true
+no_trailing_whitespace_skip_directories = [
+    "tests/unit/plugins/modules/fixtures/",
+]
+run_avoid_characters = true
+
+[[sessions.extra_checks.action_groups_config]]
+name = "api"
+pattern = "^api.*$"
+exclusions = []
+doc_fragment = "community.routeros.attributes.actiongroup_api"
+
+[[sessions.extra_checks.avoid_character_group]]
+name = "tab"
+regex = "\\x09"
+
+[sessions.build_import_check]
+run_galaxy_importer = true
+
+[sessions.ansible_test_sanity]
+include_devel = true
+
+[sessions.ansible_test_units]
+include_devel = true
+
+[sessions.ansible_test_integration_w_default_container]
+include_devel = true
+controller_python_versions_only = true
+
+[sessions.ansible_test_integration_w_default_container.core_python_versions]
+"2.15" = ["2.7", "3.6", "3.7"]
+"2.16" = ["3.10"]
+"2.17" = ["3.8"]
+"2.18" = ["3.9"]
+"2.19" = ["3.11"]
+
+[[sessions.ee_check.execution_environments]]
+name = "devel-ubi-9"
+description = "ansible-core devel @ RHEL UBI 9"
+test_playbooks = ["tests/ee/all.yml"]
+config.images.base_image.name = "docker.io/redhat/ubi9:latest"
+config.dependencies.ansible_core.package_pip = "https://github.com/ansible/ansible/archive/devel.tar.gz"
+config.dependencies.ansible_runner.package_pip = "ansible-runner"
+config.dependencies.python_interpreter.package_system = "python3.12 python3.12-pip python3.12-wheel python3.12-cryptography"
+config.dependencies.python_interpreter.python_path = "/usr/bin/python3.12"
+runtime_environment = {"ANSIBLE_PRIVATE_ROLE_VARS" = "true"}
+
+[[sessions.ee_check.execution_environments]]
+name = "2.15-rocky-9"
+description = "ansible-core 2.15 @ Rocky Linux 9"
+test_playbooks = ["tests/ee/all.yml"]
+config.images.base_image.name = "quay.io/rockylinux/rockylinux:9"
+config.dependencies.ansible_core.package_pip = "https://github.com/ansible/ansible/archive/stable-2.15.tar.gz"
+config.dependencies.ansible_runner.package_pip = "ansible-runner"
+runtime_environment = {"ANSIBLE_PRIVATE_ROLE_VARS" = "true"}

changelogs/config.yaml

@@ -7,28 +7,37 @@ changelog_filename_template: ../CHANGELOG.rst
 changelog_filename_version_depth: 0
 changes_file: changelog.yaml
 changes_format: combined
+ignore_other_fragment_extensions: true
 keep_fragments: false
 mention_ancestor: true
-flatmap: true
 new_plugins_after_name: removed_features
 notesdir: fragments
+output_formats:
+  - rst
+  - md
 prelude_section_name: release_summary
 prelude_section_title: Release Summary
 sections:
-- - major_changes
-  - Major Changes
-- - minor_changes
-  - Minor Changes
-- - breaking_changes
-  - Breaking Changes / Porting Guide
-- - deprecated_features
-  - Deprecated Features
-- - removed_features
-  - Removed Features (previously deprecated)
-- - security_fixes
-  - Security Fixes
-- - bugfixes
-  - Bugfixes
-- - known_issues
-  - Known Issues
+  - - major_changes
+    - Major Changes
+  - - minor_changes
+    - Minor Changes
+  - - breaking_changes
+    - Breaking Changes / Porting Guide
+  - - deprecated_features
+    - Deprecated Features
+  - - removed_features
+    - Removed Features (previously deprecated)
+  - - security_fixes
+    - Security Fixes
+  - - bugfixes
+    - Bugfixes
+  - - known_issues
+    - Known Issues
 title: Community RouterOS
+trivial_section_name: trivial
+use_fqcn: true
+add_plugin_period: true
+changelog_nice_yaml: true
+changelog_sort: version
+vcs: auto

docs/docsite/config.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+changelog:
+  write_changelog: true

docs/docsite/links.yml

@@ -9,6 +9,8 @@ edit_on_github:
   path_prefix: ''
 
 extra_links:
+  - description: Ask for help (RouterOS)
+    url: https://forum.ansible.com/tags/c/help/6/none/routeros
   - description: Submit a bug report
     url: https://github.com/ansible-collections/community.routeros/issues/new?assignees=&labels=&template=bug_report.md
   - description: Request a feature
@@ -22,6 +24,10 @@ communication:
     - topic: General usage and support questions
       network: Libera
       channel: '#ansible'
-  mailing_lists:
-    - topic: Ansible Project List
-      url: https://groups.google.com/g/ansible-project
+  forums:
+    - topic: "Ansible Forum: General usage and support questions"
+      # The following URL directly points to the "Get Help" section
+      url: https://forum.ansible.com/c/help/6/none
+    - topic: "Ansible Forum: Discussions about RouterOS"
+      # The following URL directly points to the "routeros" tag
+      url: https://forum.ansible.com/tag/routeros

docs/docsite/rst/api-guide.rst

@@ -8,7 +8,7 @@
 How to connect to RouterOS devices with the RouterOS API
 ========================================================
 
-You can use the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` to connect to a RouterOS device with the RouterOS API. More specific module to modify certain entries are the :ref:`community.routeros.api_modify <ansible_collections.community.routeros.api_modify_module>` and :ref:`community.routeros.api_find_and_modify <ansible_collections.community.routeros.api_find_and_modify_module>` modules. The :ref:`community.routeros.api_info module <ansible_collections.community.routeros.api_info_module>` allows to retrieve information on specific predefined paths that can be used as input for the ``community.routeros.api_modify`` module, and the :ref:`community.routeros.api_facts module <ansible_collections.community.routeros.api_facts_module>` allows to retrieve Ansible facts using the RouterOS API.
+You can use the :ansplugin:`community.routeros.api module <community.routeros.api#module>` to connect to a RouterOS device with the RouterOS API. More specific module to modify certain entries are the :ansplugin:`community.routeros.api_modify <community.routeros.api_modify#module>` and :ansplugin:`community.routeros.api_find_and_modify <community.routeros.api_find_and_modify#module>` modules. The :ansplugin:`community.routeros.api_info module <community.routeros.api_info#module>` allows to retrieve information on specific predefined paths that can be used as input for the :ansplugin:`community.routeros.api_modify <community.routeros.api_modify#module>` module, and the :ansplugin:`community.routeros.api_facts module <community.routeros.api_facts#module>` allows to retrieve Ansible facts using the RouterOS API.
 
 No special setup is needed; the module needs to be run on a host that can connect to the device's API. The most common case is that the module is run on ``localhost``, either by using ``hosts: localhost`` in the playbook, or by using ``delegate_to: localhost`` for the task. The following example shows how to run the equivalent of ``/ip address print``:
 
@@ -57,14 +57,14 @@ This results in the following output:
     }
 
     PLAY RECAP *******************************************************************************************************
-    localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
+    localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
 
-Check out the documenation of the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` for details on the options.
+Check out the documentation of the :ansplugin:`community.routeros.api module <community.routeros.api#module>` for details on the options.
 
 Using the ``community.routeros.api`` module defaults group
 ----------------------------------------------------------
 
-To avoid having to specify common parameters for all the API based modules in every task, you can use the ``community.routeros.api`` module defaults group:
+To avoid having to specify common parameters for all the API based modules in every task, you can use the ``community.routeros.api`` :ref:`module defaults group <module_defaults_groups>`:
 
 .. code-block:: yaml+jinja
 
@@ -73,7 +73,7 @@ To avoid having to specify common parameters for all the API based modules in ev
       hosts: localhost
       gather_facts: false
       module_defaults:
-        group/community.routeros.api
+        group/community.routeros.api:
           hostname: 192.168.1.1
           password: admin
           username: test1234
@@ -85,7 +85,7 @@ To avoid having to specify common parameters for all the API based modules in ev
           # If you are using your own PKI, specify the path to your CA certificate here:
           # ca_path: /path/to/ca-certificate.pem
       tasks:
-        - name: Gather facts"
+        - name: Gather facts
           community.routeros.api_facts:
 
         - name: Get "ip address print"
@@ -105,12 +105,12 @@ Here all three tasks will use the options set for the module defaults group.
 Setting up encryption
 ---------------------
 
-It is recommended to always use ``tls: true`` when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used:
+It is recommended to always use :ansopt:`tls=true` when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used:
 
-:force_no_cert: Setting to ``true`` connects to the device without a certificate. **This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks**, but might be useful when setting the device up. The default value is ``false``.
-:validate_certs: Setting to ``false`` disables any certificate validation. **This is discouraged to use in production**, but is needed when setting the device up. The default value is ``true``.
-:validate_cert_hostname: Setting to ``false`` (default) disables hostname verification during certificate validation. This is needed if the hostnames specified in the certificate do not match the hostname used for connecting (usually the device's IP). It is recommended to set up the certificate correctly and set this to ``true``; the default ``false`` is chosen for backwards compatibility to an older version of the module.
-:ca_path: If you are not using a commerically trusted CA certificate to sign your device's certificate, or have not included your CA certificate in Python's truststore, you need to point this option to the CA certificate.
+:force_no_cert: Setting to :ansval:`true` connects to the device without a certificate. **This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks**, but might be useful when setting the device up. The default value is :ansval:`false`.
+:validate_certs: Setting to :ansval:`false` disables any certificate validation. **This is discouraged to use in production**, but is needed when setting the device up. The default value is :ansval:`true`.
+:validate_cert_hostname: Setting to :ansval:`false` (default) disables hostname verification during certificate validation. This is needed if the hostnames specified in the certificate do not match the hostname used for connecting (usually the device's IP). It is recommended to set up the certificate correctly and set this to :ansval:`true`; the default :ansval:`false` is chosen for backwards compatibility to an older version of the module.
+:ca_path: If you are not using a commercially trusted CA certificate to sign your device's certificate, or have not included your CA certificate in Python's truststore, you need to point this option to the CA certificate.
 
 We recommend to create a CA certificate that is used to sign the certificates for your RouterOS devices, and have the certificates include the correct hostname(s), including the IP of the device. That way, you can fully enable TLS and be sure that you always talk to the correct device.
 
@@ -124,7 +124,7 @@ Installing a certificate on a MikroTik router
 
 Installing the certificate is best done with the SSH connection. (See the :ref:`ansible_collections.community.routeros.docsite.ssh-guide` guide for more information.) Once the certificate has been installed, and the HTTPS API enabled, it's easier to work with the API, since it has a quite a few less problems, and returns data as JSON objects instead of text you first have to parse.
 
-First you have to convert the certificate and its private key to a `PKCS #12 bundle <https://en.wikipedia.org/wiki/PKCS_12>`_. This can be done with the :ref:`community.crypto.openssl_pkcs12 <ansible_collections.community.crypto.openssl_pkcs12_module>`. The following playbook assumes that the certificate is available as ``keys/{{ inventory_hostname }}.pem``, and its private key is available as ``keys/{{ inventory_hostname }}.key``. It generates a random passphrase to protect the PKCS#12 file.
+First you have to convert the certificate and its private key to a `PKCS #12 bundle <https://en.wikipedia.org/wiki/PKCS_12>`_. This can be done with the :ansplugin:`community.crypto.openssl_pkcs12 <community.crypto.openssl_pkcs12#module>`. The following playbook assumes that the certificate is available as ``keys/{{ inventory_hostname }}.pem``, and its private key is available as ``keys/{{ inventory_hostname }}.key``. It generates a random passphrase to protect the PKCS#12 file.
 
 .. code-block:: yaml+jinja
 
@@ -186,12 +186,12 @@ First you have to convert the certificate and its private key to a `PKCS #12 bun
 
 The playbook also assumes that ``admin_network`` describes the network from which the HTTPS and API interface can be accessed. This can be for example ``192.168.1.0/24``.
 
-When this playbook completed successfully, you should be able to use the HTTPS admin interface (reachable in a browser from ``https://192.168.1.1/``, with the correct IP inserted), as well as the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` module with TLS and certificate validation enabled:
+When this playbook completed successfully, you should be able to use the HTTPS admin interface (reachable in a browser from ``https://192.168.1.1/``, with the correct IP inserted), as well as the :ansplugin:`community.routeros.api module <community.routeros.api#module>` module with TLS and certificate validation enabled:
 
 .. code-block:: yaml+jinja
 
     - community.routeros.api:
-        ...
+        # ...
         tls: true
         validate_certs: true
         validate_cert_hostname: true

docs/docsite/rst/quoting.rst

@@ -8,12 +8,12 @@
 How to quote and unquote commands and arguments
 ===============================================
 
-When using the :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` or the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` modules, you need to pass text data in quoted form. While in some cases quoting is not needed (when passing IP addresses or names without spaces, for example), in other cases it is required, like when passing a comment which contains a space.
+When using the :ansplugin:`community.routeros.command module <community.routeros.command#module>` or the :ansplugin:`community.routeros.api module <community.routeros.api#module>` modules, you need to pass text data in quoted form. While in some cases quoting is not needed (when passing IP addresses or names without spaces, for example), in other cases it is required, like when passing a comment which contains a space.
 
 The community.routeros collection provides a set of Jinja2 filter plugins which helps you with these tasks:
 
-- The :ref:`community.routeros.quote_argument_value filter <ansible_collections.community.routeros.quote_argument_value_filter>` quotes an argument value: ``'this is a "comment"' | community.routeros.quote_argument_value == '"this is a \\"comment\\""'``.
-- The :ref:`community.routeros.quote_argument filter <ansible_collections.community.routeros.quote_argument_filter>` quotes an argument with or without a value: ``'comment=this is a "comment"' | community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``.
-- The :ref:`community.routeros.join filter <ansible_collections.community.routeros.join_filter>` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] | community.routeros.join == 'foo=bar comment="foo is bar"'``.
-- The :ref:`community.routeros.split filter <ansible_collections.community.routeros.split_filter>` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' | community.routeros.split == ['foo=bar', 'comment=foo is bar']``
-- The :ref:`community.routeros.list_to_dict filter <ansible_collections.community.routeros.list_to_dict_filter>` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: ``require_assignment`` (default value ``true``) allows to accept arguments without values when set to ``false``; and ``skip_empty_values`` (default value ``false``) allows to skip arguments whose value is empty.
+- The :ansplugin:`community.routeros.quote_argument_value filter <community.routeros.quote_argument_value#filter>` quotes an argument value: ``'this is a "comment"' | community.routeros.quote_argument_value == '"this is a \\"comment\\""'``.
+- The :ansplugin:`community.routeros.quote_argument filter <community.routeros.quote_argument#filter>` quotes an argument with or without a value: ``'comment=this is a "comment"' | community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``.
+- The :ansplugin:`community.routeros.join filter <community.routeros.join#filter>` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] | community.routeros.join == 'foo=bar comment="foo is bar"'``.
+- The :ansplugin:`community.routeros.split filter <community.routeros.split#filter>` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' | community.routeros.split == ['foo=bar', 'comment=foo is bar']``
+- The :ansplugin:`community.routeros.list_to_dict filter <community.routeros.list_to_dict#filter>` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: :ansopt:`community.routeros.list_to_dict#filter:require_assignment` (default value :ansval:`true`) allows to accept arguments without values when set to :ansval:`false`; and :ansopt:`community.routeros.list_to_dict#filter:skip_empty_values` (default value :ansval:`false`) allows to skip arguments whose value is empty.

docs/docsite/rst/ssh-guide.rst

@@ -10,17 +10,17 @@ How to connect to RouterOS devices with SSH
 
 The collection offers two modules to connect to RouterOS devies with SSH:
 
-- The :ref:`community.routeros.facts module <ansible_collections.community.routeros.facts_module>` gathers facts about a RouterOS device;
-- The :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` executes commands on a RouterOS device.
+- The :ansplugin:`community.routeros.facts module <community.routeros.facts#module>` gathers facts about a RouterOS device;
+- The :ansplugin:`community.routeros.command module <community.routeros.command#module>` executes commands on a RouterOS device.
 
-The modules need the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` for this.
+The modules need the :ansplugin:`ansible.netcommon.network_cli connection plugin <ansible.netcommon.network_cli#connection>` for this.
 
 Important notes
 ---------------
 
 1. The SSH-based modules do not support arbitrary symbols in the router's identity. If you are having trouble connecting to your device, please make sure that your MikroTik's identity contains only alphanumeric characters and dashes. Also make sure that the identity string is not longer than 19 characters (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/31>`__). Similar problems can happen for unsupported characters in your username.
 
-2. The :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` does not support nesting commands and expects every command to start with a forward slash (``/``). Running the following command will produce an error:
+2. The :ansplugin:`community.routeros.command module <community.routeros.command#module>` does not support nesting commands and expects every command to start with a forward slash (``/``). Running the following command will produce an error:
 
    .. code-block:: yaml+jinja
 
@@ -29,9 +29,11 @@ Important notes
              - /ip
              - print
 
-3. When using the :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` module, make sure to not specify too long commands. Alternatively, add something like ``+cet512w`` to the username (replace ``admin`` with ``admin+cet512w``) to tell RouterOS to not wrap before 512 characters in a line (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/6>`__).
+3. When using the :ansplugin:`community.routeros.command module <community.routeros.command#module>` module, make sure to not specify too long commands. Alternatively, add something like ``+cet512w`` to the username (replace ``admin`` with ``admin+cet512w``) to tell RouterOS to not wrap before 512 characters in a line (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/6>`__).
 
-4. Finally, the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` uses `paramiko <https://pypi.org/project/paramiko/>`_ by default to connect to devices with SSH. You can set its ``ssh_type`` option to ``libssh`` to use `ansible-pylibssh <https://pypi.org/project/ansible-pylibssh/>`_ instead, which offers Python bindings to libssh. See its documentation for details.
+4. The :ansplugin:`ansible.netcommon.network_cli connection plugin <ansible.netcommon.network_cli#connection>` uses `paramiko <https://pypi.org/project/paramiko/>`_ by default to connect to devices with SSH. You can set its :ansopt:`ansible.netcommon.network_cli#connection:ssh_type` option to :ansval:`libssh` to use `ansible-pylibssh <https://pypi.org/project/ansible-pylibssh/>`_ instead, which offers Python bindings to libssh. See its documentation for details.
+
+5. User is **not allowed** to login via SSH by password to modern Mikrotik if SSH key for the user is added!
 
 Setting up an inventory
 -----------------------
@@ -49,7 +51,7 @@ An example inventory ``hosts`` file for a RouterOS device is as follows:
     ansible_user=admin
     ansible_ssh_pass=test1234
 
-This tells Ansible that you have a RouterOS device called ``router`` with IP ``192.168.2.1``. Ansible should use the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` together with the the :ref:`community.routeros.routeros cliconf plugin <ansible_collections.community.routeros.routeros_cliconf>`. The credentials are stored as ``ansible_user`` and ``ansible_ssh_pass`` in the inventory.
+This tells Ansible that you have a RouterOS device called ``router`` with IP ``192.168.2.1``. Ansible should use the :ansplugin:`ansible.netcommon.network_cli connection plugin <ansible.netcommon.network_cli#connection>` together with the the :ansplugin:`community.routeros.routeros cliconf plugin <community.routeros.routeros#cliconf>`. The credentials are stored as ``ansible_user`` and ``ansible_ssh_pass`` in the inventory.
 
 Connecting to the device
 ------------------------
@@ -64,22 +66,22 @@ With the above inventory, you can use the following playbook to execute ``/syste
       gather_facts: false
       tasks:
 
-      - name: Gather system resources
-        community.routeros.command:
-          commands:
-            - /system resource print
-        register: system_resource_print
+        - name: Gather system resources
+          community.routeros.command:
+            commands:
+              - /system resource print
+          register: system_resource_print
 
-      - name: Show system resources
-        debug:
-          var: system_resource_print.stdout_lines
+        - name: Show system resources
+          debug:
+            var: system_resource_print.stdout_lines
 
-      - name: Gather facts
-        community.routeros.facts:
+        - name: Gather facts
+          community.routeros.facts:
 
-      - name: Show a fact
-        debug:
-          msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}"
+        - name: Show a fact
+          debug:
+            msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}"
 
 This results in the following output:
 
@@ -124,4 +126,4 @@ This results in the following output:
     }
 
     PLAY RECAP *******************************************************************************************************
-    router                     : ok=4    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
+    router                     : ok=4    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

galaxy.yml

@@ -7,16 +7,16 @@
 
 namespace: community
 name: routeros
-version: 2.8.1
+version: 3.10.0
 readme: README.md
 authors:
   - Egor Zaitsev (github.com/heuels)
   - Nikolay Dachev (github.com/NikolayDachev)
   - Felix Fontein (github.com/felixfontein)
-description: Modules for MikroTik RouterOS
+description: Modules and plugins for MikroTik RouterOS
 license:
   - GPL-3.0-or-later
-#license_file: COPYING
+# license_file: COPYING
 tags:
   - network
   - mikrotik

meta/runtime.yml

@@ -3,7 +3,7 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-requires_ansible: '>=2.9.10'
+requires_ansible: '>=2.15.0'
 action_groups:
   api:
     - api

noxfile.py

@@ -0,0 +1,53 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# The following metadata allows Python runners and nox to install the required
+# dependencies for running this Python script:
+#
+# /// script
+# dependencies = ["nox>=2025.02.09", "antsibull-nox"]
+# ///
+
+import os
+import sys
+
+import nox
+
+
+# We try to import antsibull-nox, and if that doesn't work, provide a more useful
+# error message to the user.
+try:
+    import antsibull_nox
+except ImportError:
+    print("You need to install antsibull-nox in the same Python environment as nox.")
+    sys.exit(1)
+
+
+IN_CI = os.environ.get("CI") == "true"
+
+
+antsibull_nox.load_antsibull_nox_toml()
+
+
+@nox.session(name="update-docs", default=True)
+def update_docs_fragments(session: nox.Session) -> None:
+    """
+    Update/check auto-generated parts of docs fragments.
+    """
+    session.install("ansible-core")
+    prepare = antsibull_nox.sessions.prepare_collections(
+        session, install_in_site_packages=True
+    )
+    if not prepare:
+        return
+    data = ["python", "tests/update-docs.py"]
+    if IN_CI:
+        data.append("--lint")
+    session.run(*data)
+
+
+# Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar.
+# Requires nox >= 2025.02.09
+if __name__ == "__main__":
+    nox.main()

plugins/cliconf/routeros.py

@@ -5,15 +5,14 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 author: "Egor Zaitsev (@heuels)"
 name: routeros
 short_description: Use routeros cliconf to run command on MikroTik RouterOS platform
 description:
-  - This routeros plugin provides low level abstraction apis for
-    sending and receiving CLI commands from MikroTik RouterOS network devices.
-'''
+  - This routeros plugin provides low level abstraction APIs for sending and receiving CLI commands from MikroTik RouterOS
+    network devices.
+"""
 
 import re
 import json

plugins/doc_fragments/api.py

@@ -10,7 +10,7 @@ __metaclass__ = type
 
 class ModuleDocFragment(object):
 
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   hostname:
     description:
@@ -43,48 +43,46 @@ options:
       - ssl
   port:
     description:
-      - RouterOS api port. If I(tls) is set, port will apply to TLS/SSL connection.
-      - Defaults are C(8728) for the HTTP API, and C(8729) for the HTTPS API.
+      - RouterOS API port. If O(tls) is set, port will apply to TLS/SSL connection.
+      - Defaults are V(8728) for the HTTP API, and V(8729) for the HTTPS API.
     type: int
   force_no_cert:
     description:
-      - Set to C(true) to connect without a certificate when I(tls=true).
-      - See also I(validate_certs).
-      - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible
-        to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated.
-        Instead of simply connecting without a certificate to "make things work" have a look at
-        I(validate_certs) and I(ca_path).
+      - Set to V(true) to connect without a certificate when O(tls=true).
+      - See also O(validate_certs).
+      - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle
+        attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate
+        to "make things work" have a look at O(validate_certs) and O(ca_path).
     type: bool
     default: false
     version_added: 2.4.0
   validate_certs:
     description:
-      - Set to C(false) to skip validation of TLS certificates.
-      - See also I(validate_cert_hostname). Only used when I(tls=true).
-      - B(Note:) instead of simply deactivating certificate validations to "make things work",
-        please consider creating your own CA certificate and using it to sign certificates used
-        for your router. You can tell the module about your CA certificate with the I(ca_path)
-        option.
+      - Set to V(false) to skip validation of TLS certificates.
+      - See also O(validate_cert_hostname). Only used when O(tls=true).
+      - B(Note:) instead of simply deactivating certificate validations to "make things work", please consider creating your
+        own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate
+        with the O(ca_path) option.
     type: bool
     default: true
     version_added: 1.2.0
   validate_cert_hostname:
     description:
-      - Set to C(true) to validate hostnames in certificates.
-      - See also I(validate_certs). Only used when I(tls=true) and I(validate_certs=true).
+      - Set to V(true) to validate hostnames in certificates.
+      - See also O(validate_certs). Only used when O(tls=true) and O(validate_certs=true).
     type: bool
     default: false
     version_added: 1.2.0
   ca_path:
     description:
       - PEM formatted file that contains a CA certificate to be used for certificate validation.
-      - See also I(validate_cert_hostname). Only used when I(tls=true) and I(validate_certs=true).
+      - See also O(validate_cert_hostname). Only used when O(tls=true) and O(validate_certs=true).
     type: path
     version_added: 1.2.0
   encoding:
     description:
       - Use the specified encoding when communicating with the RouterOS device.
-      - Default is C(ASCII). Note that C(UTF-8) requires librouteros 3.2.1 or newer.
+      - Default is V(ASCII). Note that V(UTF-8) requires librouteros 3.2.1 or newer.
     type: str
     default: ASCII
     version_added: 2.1.0
@@ -93,5 +91,43 @@ requirements:
   - Python >= 3.6 (for librouteros)
 seealso:
   - ref: ansible_collections.community.routeros.docsite.api-guide
-    description: How to connect to RouterOS devices with the RouterOS API
-'''
+    description: How to connect to RouterOS devices with the RouterOS API.
+"""
+
+    RESTRICT = r"""
+options:
+  restrict:
+    type: list
+    elements: dict
+    suboptions:
+      field:
+        description:
+          - The field whose values to restrict.
+        required: true
+        type: str
+      match_disabled:
+        description:
+          - Whether disabled or not provided values should match.
+        type: bool
+        default: false
+      values:
+        description:
+          - The values of the field to limit to.
+          - 'Note that the types of the values are important. If you provide a string V("0"), and librouteros converts the
+            value returned by the API to the integer V(0), then this will not match. If you are not sure, better include both
+            variants: both the string and the integer.'
+        type: list
+        elements: raw
+      regex:
+        description:
+          - A regular expression matching values of the field to limit to.
+          - Note that all values will be converted to strings before matching.
+          - It is not possible to match disabled values with regular expressions. Set O(restrict[].match_disabled=true) if
+            you also want to match disabled values.
+        type: str
+      invert:
+        description:
+          - Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values), and O(restrict[].regex).
+        type: bool
+        default: false
+"""

plugins/doc_fragments/attributes.py

@@ -11,88 +11,102 @@ __metaclass__ = type
 class ModuleDocFragment(object):
 
     # Standard documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options: {}
 attributes:
-    check_mode:
-      description: Can run in C(check_mode) and return changed status prediction without modifying target.
-    diff_mode:
-      description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
-    platform:
-      description: Target OS/families that can be operated against.
-      support: N/A
-'''
+  check_mode:
+    description: Can run in C(check_mode) and return changed status prediction without modifying target.
+  diff_mode:
+    description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+  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
     INFO_MODULE = r'''
 options: {}
 attributes:
-    check_mode:
-      support: full
-      details:
-        - This action does not modify state.
-    diff_mode:
-      support: N/A
-      details:
-        - This action does not modify state.
+  check_mode:
+    support: full
+    details:
+      - This action does not modify state.
+  diff_mode:
+    support: N/A
+    details:
+      - This action does not modify state.
 '''
 
     ACTIONGROUP_API = r'''
 options: {}
 attributes:
-    action_group:
-      description: Use C(group/community.routeros.api) in C(module_defaults) to set defaults for this module.
-      support: full
-      membership:
-        - community.routeros.api
+  action_group:
+    description: Use C(group/community.routeros.api) in C(module_defaults) to set defaults for this module.
+    support: full
+    membership:
+      - community.routeros.api
 '''
 
-    CONN = r'''
+    CONN = r"""
 options: {}
 attributes:
-    become:
-      description: Is usable alongside C(become) keywords.
-    connection:
-      description: Uses the target's configured connection information to execute code on it.
-    delegation:
-      description: Can be used in conjunction with C(delegate_to) and related keywords.
-'''
+  become:
+    description: Is usable alongside C(become) keywords.
+  connection:
+    description: Uses the target's configured connection information to execute code on it.
+  delegation:
+    description: Can be used in conjunction with C(delegate_to) and related keywords.
+"""
 
-    FACTS = r'''
+    FACTS = r"""
 options: {}
 attributes:
-    facts:
-      description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
-'''
+  facts:
+    description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
+"""
 
     # Should be used together with the standard fragment and the FACTS fragment
     FACTS_MODULE = r'''
 options: {}
 attributes:
-    check_mode:
-      support: full
-      details:
-        - This action does not modify state.
-    diff_mode:
-      support: N/A
-      details:
-        - This action does not modify state.
-    facts:
-      support: full
+  check_mode:
+    support: full
+    details:
+      - This action does not modify state.
+  diff_mode:
+    support: N/A
+    details:
+      - This action does not modify state.
+  facts:
+    support: full
 '''
 
-    FILES = r'''
+    FILES = r"""
 options: {}
 attributes:
-    safe_file_operations:
-      description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
-'''
+  safe_file_operations:
+    description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
+"""
 
-    FLOW = r'''
+    FLOW = r"""
 options: {}
 attributes:
-    action:
-      description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
-    async:
-      description: Supports being used with the C(async) keyword.
-'''
+  action:
+    description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
+  async:
+    description: Supports being used with the C(async) keyword.
+"""

plugins/filter/join.yml

@@ -20,6 +20,7 @@ DOCUMENTATION:
     - Felix Fontein (@felixfontein)
 
 EXAMPLES: |
+  ---
   - name: Join arguments for a RouterOS CLI command
     ansible.builtin.set_fact:
       arguments: "{{ ['foo=bar', 'comment=foo is bar'] | community.routeros.join }}"

plugins/filter/list_to_dict.yml

@@ -12,24 +12,25 @@ DOCUMENTATION:
   options:
     _input:
       description:
-        - A list of assignments. Can be the result of the C(community.routeros.split) filter.
+        - A list of assignments. Can be the result of the P(community.routeros.split#filter) filter.
       type: list
       elements: string
       required: true
     require_assignment:
       description:
-        - Allows to accept arguments without values when set to C(false).
+        - Allows to accept arguments without values when set to V(false).
       type: boolean
       default: true
     skip_empty_values:
       description:
-        - Allows to skip arguments whose value is empty when set to C(true).
+        - Allows to skip arguments whose value is empty when set to V(true).
       type: boolean
       default: false
   author:
     - Felix Fontein (@felixfontein)
 
 EXAMPLES: |
+  ---
   - name: Convert a list to a dictionary
     ansible.builtin.set_fact:
       dictionary: "{{ ['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict }}"

plugins/filter/quote_argument.yml

@@ -19,9 +19,11 @@ DOCUMENTATION:
     - Felix Fontein (@felixfontein)
 
 EXAMPLES: |
+  ---
   - name: Quote a RouterOS CLI command argument
     ansible.builtin.set_fact:
-      quoted: "{{ 'comment=this is a "comment"' | community.routeros.quote_argument }}"
+      quoted: >-
+        {{ 'comment=this is a "comment"' | community.routeros.quote_argument }}
       # Should result in 'comment="this is a \"comment\""'
 
 RETURN:

plugins/filter/quote_argument_value.yml

@@ -19,9 +19,11 @@ DOCUMENTATION:
     - Felix Fontein (@felixfontein)
 
 EXAMPLES: |
+  ---
   - name: Quote a RouterOS CLI command argument's value
     ansible.builtin.set_fact:
-      quoted: "{{ 'this is a "comment"' | community.routeros.quote_argument_value }}"
+      quoted: >-
+        {{ 'this is a "comment"' | community.routeros.quote_argument_value }}
       # Should result in '"this is a \"comment\""'
 
 RETURN:

plugins/filter/split.yml

@@ -19,9 +19,11 @@ DOCUMENTATION:
     - Felix Fontein (@felixfontein)
 
 EXAMPLES: |
+  ---
   - name: Split command into list of arguments
     ansible.builtin.set_fact:
-      argument_list: "{{ 'foo=bar comment="foo is bar" baz' | community.routeros.split }}"
+      argument_list: >-
+        {{ 'foo=bar comment="foo is bar" baz' | community.routeros.split }}
       # Should result in ['foo=bar', 'comment=foo is bar', 'baz']
 
 RETURN:

plugins/module_utils/_api_helper.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2022, Felix Fontein (@felixfontein) <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# The data inside here is private to this collection. If you use this from outside the collection,
+# you are on your own. There can be random changes to its format even in bugfix releases!
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+import re
+
+from ansible.module_utils.common.text.converters import to_text
+
+
+def validate_and_prepare_restrict(module, path_info):
+    restrict = module.params['restrict']
+    if restrict is None:
+        return None
+    restrict_data = []
+    for rule in restrict:
+        field = rule['field']
+        if field.startswith('!'):
+            module.fail_json(msg='restrict: the field name "{0}" must not start with "!"'.format(field))
+        f = path_info.fields.get(field)
+        if f is None:
+            module.fail_json(msg='restrict: the field "{0}" does not exist for this path'.format(field))
+
+        new_rule = dict(
+            field=field,
+            match_disabled=rule['match_disabled'],
+            invert=rule['invert'],
+        )
+        if rule['values'] is not None:
+            new_rule['values'] = rule['values']
+        if rule['regex'] is not None:
+            regex = rule['regex']
+            try:
+                new_rule['regex'] = re.compile(regex)
+                new_rule['regex_source'] = regex
+            except Exception as exc:
+                module.fail_json(msg='restrict: invalid regular expression "{0}": {1}'.format(regex, exc))
+        restrict_data.append(new_rule)
+    return restrict_data
+
+
+def _value_to_str(value):
+    if value is None:
+        return None
+    value_str = to_text(value)
+    if isinstance(value, bool):
+        value_str = value_str.lower()
+    return value_str
+
+
+def _test_rule_except_invert(value, rule):
+    if value is None and rule['match_disabled']:
+        return True
+    if 'values' in rule and value in rule['values']:
+        return True
+    if 'regex' in rule and value is not None and rule['regex'].match(_value_to_str(value)):
+        return True
+    return False
+
+
+def restrict_entry_accepted(entry, path_info, restrict_data):
+    if restrict_data is None:
+        return True
+    for rule in restrict_data:
+        # Obtain field and value
+        field = rule['field']
+        field_info = path_info.fields[field]
+        value = entry.get(field)
+        if value is None:
+            value = field_info.default
+        if field not in entry and field_info.absent_value:
+            value = field_info.absent_value
+
+        # Check
+        matches_rule = _test_rule_except_invert(value, rule)
+        if rule['invert']:
+            matches_rule = not matches_rule
+        if not matches_rule:
+            return False
+    return True
+
+
+def restrict_argument_spec():
+    return dict(
+        restrict=dict(
+            type='list',
+            elements='dict',
+            options=dict(
+                field=dict(type='str', required=True),
+                match_disabled=dict(type='bool', default=False),
+                values=dict(type='list', elements='raw'),
+                regex=dict(type='str'),
+                invert=dict(type='bool', default=False),
+            ),
+        ),
+    )

plugins/module_utils/_version.py

@@ -1,345 +0,0 @@
-# Vendored copy of distutils/version.py from CPython 3.9.5
-#
-# Implements multiple version numbering conventions for the
-# Python Module Distribution Utilities.
-#
-# Copyright (c) 2001-2022 Python Software Foundation.  All rights reserved.
-# PSF License (see LICENSES/PSF-2.0.txt or https://opensource.org/licenses/Python-2.0)
-# SPDX-License-Identifier: PSF-2.0
-#
-
-"""Provides classes to represent module version numbers (one class for
-each style of version numbering).  There are currently two such classes
-implemented: StrictVersion and LooseVersion.
-
-Every version number class implements the following interface:
-  * the 'parse' method takes a string and parses it to some internal
-    representation; if the string is an invalid version number,
-    'parse' raises a ValueError exception
-  * the class constructor takes an optional string argument which,
-    if supplied, is passed to 'parse'
-  * __str__ reconstructs the string that was passed to 'parse' (or
-    an equivalent string -- ie. one that will generate an equivalent
-    version number instance)
-  * __repr__ generates Python code to recreate the version number instance
-  * _cmp compares the current instance with either another instance
-    of the same class or a string (which will be parsed to an instance
-    of the same class, thus must follow the same rules)
-"""
-
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-import re
-
-try:
-    RE_FLAGS = re.VERBOSE | re.ASCII
-except AttributeError:
-    RE_FLAGS = re.VERBOSE
-
-
-class Version:
-    """Abstract base class for version numbering classes.  Just provides
-    constructor (__init__) and reproducer (__repr__), because those
-    seem to be the same for all version numbering classes; and route
-    rich comparisons to _cmp.
-    """
-
-    def __init__(self, vstring=None):
-        if vstring:
-            self.parse(vstring)
-
-    def __repr__(self):
-        return "%s ('%s')" % (self.__class__.__name__, str(self))
-
-    def __eq__(self, other):
-        c = self._cmp(other)
-        if c is NotImplemented:
-            return c
-        return c == 0
-
-    def __lt__(self, other):
-        c = self._cmp(other)
-        if c is NotImplemented:
-            return c
-        return c < 0
-
-    def __le__(self, other):
-        c = self._cmp(other)
-        if c is NotImplemented:
-            return c
-        return c <= 0
-
-    def __gt__(self, other):
-        c = self._cmp(other)
-        if c is NotImplemented:
-            return c
-        return c > 0
-
-    def __ge__(self, other):
-        c = self._cmp(other)
-        if c is NotImplemented:
-            return c
-        return c >= 0
-
-
-# Interface for version-number classes -- must be implemented
-# by the following classes (the concrete ones -- Version should
-# be treated as an abstract class).
-#    __init__ (string) - create and take same action as 'parse'
-#                        (string parameter is optional)
-#    parse (string)    - convert a string representation to whatever
-#                        internal representation is appropriate for
-#                        this style of version numbering
-#    __str__ (self)    - convert back to a string; should be very similar
-#                        (if not identical to) the string supplied to parse
-#    __repr__ (self)   - generate Python code to recreate
-#                        the instance
-#    _cmp (self, other) - compare two version numbers ('other' may
-#                        be an unparsed version string, or another
-#                        instance of your version class)
-
-
-class StrictVersion(Version):
-    """Version numbering for anal retentives and software idealists.
-    Implements the standard interface for version number classes as
-    described above.  A version number consists of two or three
-    dot-separated numeric components, with an optional "pre-release" tag
-    on the end.  The pre-release tag consists of the letter 'a' or 'b'
-    followed by a number.  If the numeric components of two version
-    numbers are equal, then one with a pre-release tag will always
-    be deemed earlier (lesser) than one without.
-
-    The following are valid version numbers (shown in the order that
-    would be obtained by sorting according to the supplied cmp function):
-
-        0.4       0.4.0  (these two are equivalent)
-        0.4.1
-        0.5a1
-        0.5b3
-        0.5
-        0.9.6
-        1.0
-        1.0.4a3
-        1.0.4b1
-        1.0.4
-
-    The following are examples of invalid version numbers:
-
-        1
-        2.7.2.2
-        1.3.a4
-        1.3pl1
-        1.3c4
-
-    The rationale for this version numbering system will be explained
-    in the distutils documentation.
-    """
-
-    version_re = re.compile(r'^(\d+) \. (\d+) (\. (\d+))? ([ab](\d+))?$',
-                            RE_FLAGS)
-
-    def parse(self, vstring):
-        match = self.version_re.match(vstring)
-        if not match:
-            raise ValueError("invalid version number '%s'" % vstring)
-
-        (major, minor, patch, prerelease, prerelease_num) = \
-            match.group(1, 2, 4, 5, 6)
-
-        if patch:
-            self.version = tuple(map(int, [major, minor, patch]))
-        else:
-            self.version = tuple(map(int, [major, minor])) + (0,)
-
-        if prerelease:
-            self.prerelease = (prerelease[0], int(prerelease_num))
-        else:
-            self.prerelease = None
-
-    def __str__(self):
-        if self.version[2] == 0:
-            vstring = '.'.join(map(str, self.version[0:2]))
-        else:
-            vstring = '.'.join(map(str, self.version))
-
-        if self.prerelease:
-            vstring = vstring + self.prerelease[0] + str(self.prerelease[1])
-
-        return vstring
-
-    def _cmp(self, other):
-        if isinstance(other, str):
-            other = StrictVersion(other)
-        elif not isinstance(other, StrictVersion):
-            return NotImplemented
-
-        if self.version != other.version:
-            # numeric versions don't match
-            # prerelease stuff doesn't matter
-            if self.version < other.version:
-                return -1
-            else:
-                return 1
-
-        # have to compare prerelease
-        # case 1: neither has prerelease; they're equal
-        # case 2: self has prerelease, other doesn't; other is greater
-        # case 3: self doesn't have prerelease, other does: self is greater
-        # case 4: both have prerelease: must compare them!
-
-        if (not self.prerelease and not other.prerelease):
-            return 0
-        elif (self.prerelease and not other.prerelease):
-            return -1
-        elif (not self.prerelease and other.prerelease):
-            return 1
-        elif (self.prerelease and other.prerelease):
-            if self.prerelease == other.prerelease:
-                return 0
-            elif self.prerelease < other.prerelease:
-                return -1
-            else:
-                return 1
-        else:
-            raise AssertionError("never get here")
-
-# end class StrictVersion
-
-# The rules according to Greg Stein:
-# 1) a version number has 1 or more numbers separated by a period or by
-#    sequences of letters. If only periods, then these are compared
-#    left-to-right to determine an ordering.
-# 2) sequences of letters are part of the tuple for comparison and are
-#    compared lexicographically
-# 3) recognize the numeric components may have leading zeroes
-#
-# The LooseVersion class below implements these rules: a version number
-# string is split up into a tuple of integer and string components, and
-# comparison is a simple tuple comparison.  This means that version
-# numbers behave in a predictable and obvious way, but a way that might
-# not necessarily be how people *want* version numbers to behave.  There
-# wouldn't be a problem if people could stick to purely numeric version
-# numbers: just split on period and compare the numbers as tuples.
-# However, people insist on putting letters into their version numbers;
-# the most common purpose seems to be:
-#   - indicating a "pre-release" version
-#     ('alpha', 'beta', 'a', 'b', 'pre', 'p')
-#   - indicating a post-release patch ('p', 'pl', 'patch')
-# but of course this can't cover all version number schemes, and there's
-# no way to know what a programmer means without asking him.
-#
-# The problem is what to do with letters (and other non-numeric
-# characters) in a version number.  The current implementation does the
-# obvious and predictable thing: keep them as strings and compare
-# lexically within a tuple comparison.  This has the desired effect if
-# an appended letter sequence implies something "post-release":
-# eg. "0.99" < "0.99pl14" < "1.0", and "5.001" < "5.001m" < "5.002".
-#
-# However, if letters in a version number imply a pre-release version,
-# the "obvious" thing isn't correct.  Eg. you would expect that
-# "1.5.1" < "1.5.2a2" < "1.5.2", but under the tuple/lexical comparison
-# implemented here, this just isn't so.
-#
-# Two possible solutions come to mind.  The first is to tie the
-# comparison algorithm to a particular set of semantic rules, as has
-# been done in the StrictVersion class above.  This works great as long
-# as everyone can go along with bondage and discipline.  Hopefully a
-# (large) subset of Python module programmers will agree that the
-# particular flavour of bondage and discipline provided by StrictVersion
-# provides enough benefit to be worth using, and will submit their
-# version numbering scheme to its domination.  The free-thinking
-# anarchists in the lot will never give in, though, and something needs
-# to be done to accommodate them.
-#
-# Perhaps a "moderately strict" version class could be implemented that
-# lets almost anything slide (syntactically), and makes some heuristic
-# assumptions about non-digits in version number strings.  This could
-# sink into special-case-hell, though; if I was as talented and
-# idiosyncratic as Larry Wall, I'd go ahead and implement a class that
-# somehow knows that "1.2.1" < "1.2.2a2" < "1.2.2" < "1.2.2pl3", and is
-# just as happy dealing with things like "2g6" and "1.13++".  I don't
-# think I'm smart enough to do it right though.
-#
-# In any case, I've coded the test suite for this module (see
-# ../test/test_version.py) specifically to fail on things like comparing
-# "1.2a2" and "1.2".  That's not because the *code* is doing anything
-# wrong, it's because the simple, obvious design doesn't match my
-# complicated, hairy expectations for real-world version numbers.  It
-# would be a snap to fix the test suite to say, "Yep, LooseVersion does
-# the Right Thing" (ie. the code matches the conception).  But I'd rather
-# have a conception that matches common notions about version numbers.
-
-
-class LooseVersion(Version):
-    """Version numbering for anarchists and software realists.
-    Implements the standard interface for version number classes as
-    described above.  A version number consists of a series of numbers,
-    separated by either periods or strings of letters.  When comparing
-    version numbers, the numeric components will be compared
-    numerically, and the alphabetic components lexically.  The following
-    are all valid version numbers, in no particular order:
-
-        1.5.1
-        1.5.2b2
-        161
-        3.10a
-        8.02
-        3.4j
-        1996.07.12
-        3.2.pl0
-        3.1.1.6
-        2g6
-        11g
-        0.960923
-        2.2beta29
-        1.13++
-        5.5.kw
-        2.0b1pl0
-
-    In fact, there is no such thing as an invalid version number under
-    this scheme; the rules for comparison are simple and predictable,
-    but may not always give the results you want (for some definition
-    of "want").
-    """
-
-    component_re = re.compile(r'(\d+ | [a-z]+ | \.)', re.VERBOSE)
-
-    def __init__(self, vstring=None):
-        if vstring:
-            self.parse(vstring)
-
-    def parse(self, vstring):
-        # I've given up on thinking I can reconstruct the version string
-        # from the parsed tuple -- so I just store the string here for
-        # use by __str__
-        self.vstring = vstring
-        components = [x for x in self.component_re.split(vstring) if x and x != '.']
-        for i, obj in enumerate(components):
-            try:
-                components[i] = int(obj)
-            except ValueError:
-                pass
-
-        self.version = components
-
-    def __str__(self):
-        return self.vstring
-
-    def __repr__(self):
-        return "LooseVersion ('%s')" % str(self)
-
-    def _cmp(self, other):
-        if isinstance(other, str):
-            other = LooseVersion(other)
-        elif not isinstance(other, LooseVersion):
-            return NotImplemented
-
-        if self.version == other.version:
-            return 0
-        if self.version < other.version:
-            return -1
-        if self.version > other.version:
-            return 1
-
-# end class LooseVersion

plugins/module_utils/api.py

@@ -77,7 +77,7 @@ def _ros_api_connect(module, username, password, host, port, use_tls, force_no_c
             elif not validate_cert_hostname:
                 ctx.check_hostname = False
             else:
-                # Since librouteros doesn't pass server_hostname,
+                # Since librouteros does not pass server_hostname,
                 # we have to do this ourselves:
                 def wrap_context(*args, **kwargs):
                     kwargs.pop('server_hostname', None)
@@ -97,6 +97,7 @@ def _ros_api_connect(module, username, password, host, port, use_tls, force_no_c
 
 
 def create_api(module):
+    """Create an API object."""
     return _ros_api_connect(
         module,
         module.params['username'],
@@ -111,3 +112,9 @@ def create_api(module):
         module.params['encoding'],
         module.params['timeout'],
     )
+
+
+def get_api_version(api):
+    """Given an API object, query the system's version."""
+    system_info = list(api.path().join('system', 'resource'))[0]
+    return system_info['version'].split(' ', 1)[0]

plugins/module_utils/version.py

@@ -10,9 +10,4 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-# Once we drop support for Ansible 2.9, ansible-base 2.10, and ansible-core 2.11, we can
-# remove the _version.py file, and replace the following import by
-#
-#     from ansible.module_utils.compat.version import LooseVersion
-
-from ._version import LooseVersion  # noqa: F401, pylint: disable=unused-import
+from ansible.module_utils.compat.version import LooseVersion  # pylint: disable=unused-import

plugins/modules/api.py

@@ -8,19 +8,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: api
 author: "Nikolay Dachev (@NikolayDachev)"
 short_description: Ansible module for RouterOS API
 description:
   - Ansible module for RouterOS API with the Python C(librouteros) library.
-  - This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
+  - This module can add, remove, update, query, and execute arbitrary command in RouterOS through the API.
 notes:
-  - I(add), I(remove), I(update), I(cmd) and I(query) are mutually exclusive.
-  - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules
-    for more specific modifications, and the M(community.routeros.api_info) module for a more controlled
-    way of returning all entries for a path.
+  - O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive.
+  - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications,
+    and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path.
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
@@ -35,44 +33,49 @@ attributes:
     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:
       - Main path for all other arguments.
-      - If other arguments are not set, api will return all items in selected path.
-      - Example C(ip address). Equivalent of RouterOS CLI C(/ip address print).
+      - If other arguments are not set, the module will return all items in selected path.
+      - Example V(ip address). Equivalent of RouterOS CLI C(/ip address print).
     required: true
     type: str
   add:
     description:
       - Will add selected arguments in selected path to RouterOS config.
-      - Example C(address=1.1.1.1/32 interface=ether1).
+      - Example V(address=1.1.1.1/32 interface=ether1).
       - Equivalent in RouterOS CLI C(/ip address add address=1.1.1.1/32 interface=ether1).
     type: str
   remove:
     description:
       - Remove config/value from RouterOS by '.id'.
-      - Example C(*03) will remove config/value with C(id=*03) in selected path.
+      - Example V(*03) will remove config/value with C(id=*03) in selected path.
       - Equivalent in RouterOS CLI C(/ip address remove numbers=1).
       - Note C(number) in RouterOS CLI is different from C(.id).
     type: str
   update:
     description:
       - Update config/value in RouterOS by '.id' in selected path.
-      - Example C(.id=*03 address=1.1.1.3/32) and path C(ip address) will replace existing ip address with C(.id=*03).
+      - Example V(.id=*03 address=1.1.1.3/32) and path V(ip address) will replace the existing IP address with C(.id=*03).
       - Equivalent in RouterOS CLI C(/ip address set address=1.1.1.3/32 numbers=1).
       - Note C(number) in RouterOS CLI is different from C(.id).
     type: str
   query:
     description:
-      - Query given path for selected query attributes from RouterOS aip.
+      - Query given path for selected query attributes from RouterOS API.
       - WHERE is key word which extend query. WHERE format is key operator value - with spaces.
-      - WHERE valid operators are C(==) or C(eq), C(!=) or C(not), C(>) or C(more), C(<) or C(less).
-      - Example path C(ip address) and query C(.id address) will return only C(.id) and C(address) for all items in C(ip address) path.
-      - Example path C(ip address) and query C(.id address WHERE address == 1.1.1.3/32).
-        will return only C(.id) and C(address) for items in C(ip address) path, where address is eq to 1.1.1.3/32.
-      - Example path C(interface) and query C(mtu name WHERE mut > 1400) will
-        return only interfaces C(mtu,name) where mtu is bigger than 1400.
+      - WHERE valid operators are V(==) or V(eq), V(!=) or V(not), V(>) or V(more), V(<) or V(less).
+      - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address)
+        path.
+      - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32). will return only C(.id) and C(address)
+        for items in V(ip address) path, where address is eq to 1.1.1.3/32.
+      - Example path V(interface) and query V(mtu name WHERE mut > 1400) will return only interfaces C(mtu,name) where mtu
+        is bigger than 1400.
       - Equivalent in RouterOS CLI C(/interface print where mtu > 1400).
     type: str
   extended_query:
@@ -84,76 +87,84 @@ options:
       attributes:
         description:
           - The list of attributes to return.
-          - Every attribute used in a I(where) clause need to be listed here.
+          - Every attribute used in a O(extended_query.where[]) clause need to be listed here.
         type: list
         elements: str
         required: true
       where:
         description:
           - Allows to restrict the objects returned.
-          - The conditions here must all match. An I(or) condition needs at least one of its conditions to match.
+          - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions
+            to match.
         type: list
         elements: dict
         suboptions:
           attribute:
             description:
-              - The attribute to match. Must be part of I(attributes).
-              - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified.
+              - The attribute to match. Must be part of O(extended_query.attributes).
+              - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is),
+                and O(extended_query.where[].value) have to be specified.
             type: str
           is:
             description:
               - The operator to use for matching.
-              - For equality use C(==) or C(eq). For less use C(<) or C(less). For more use C(>) or C(more).
-              - Use C(in) to check whether the value is part of a list. In that case, I(value) must be a list.
-              - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified.
+              - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more).
+              - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must
+                be a list.
+              - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is),
+                and O(extended_query.where[].value) have to be specified.
             type: str
             choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"]
           value:
             description:
-              - The value to compare to. Must be a list for I(is=in).
-              - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified.
+              - The value to compare to. Must be a list for O(extended_query.where[].is=in).
+              - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is),
+                and O(extended_query.where[].value) have to be specified.
             type: raw
           or:
             description:
               - A list of conditions so that at least one of them has to match.
-              - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified.
+              - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is),
+                and O(extended_query.where[].value) have to be specified.
             type: list
             elements: dict
             suboptions:
               attribute:
                 description:
-                  - The attribute to match. Must be part of I(attributes).
+                  - The attribute to match. Must be part of O(extended_query.attributes).
                 type: str
                 required: true
               is:
                 description:
                   - The operator to use for matching.
-                  - For equality use C(==) or C(eq). For less use C(<) or C(less). For more use C(>) or C(more).
-                  - Use C(in) to check whether the value is part of a list. In that case, I(value) must be a list.
+                  - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more).
+                  - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value)
+                    must be a list.
                 type: str
                 choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"]
                 required: true
               value:
                 description:
-                  - The value to compare to. Must be a list for I(is=in).
+                  - The value to compare to. Must be a list for O(extended_query.where[].or[].is=in).
                 type: raw
                 required: true
   cmd:
     description:
       - Execute any/arbitrary command in selected path, after the command we can add C(.id).
-      - Example path C(system script) and cmd C(run .id=*03) is equivalent in RouterOS CLI C(/system script run number=0).
-      - Example path C(ip address) and cmd C(print) is equivalent in RouterOS CLI C(/ip address print).
+      - Example path V(system script) and cmd V(run .id=*03) is equivalent in RouterOS CLI C(/system script run number=0).
+      - Example path V(ip address) and cmd V(print) is equivalent in RouterOS CLI C(/ip address print).
     type: str
 seealso:
   - ref: ansible_collections.community.routeros.docsite.quoting
-    description: How to quote and unquote commands and arguments
+    description: How to quote and unquote commands and arguments.
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 - name: Get example - ip address print
   community.routeros.api:
     hostname: "{{ hostname }}"
@@ -212,24 +223,24 @@ EXAMPLES = '''
         - attribute: "network"
           is: "in"
           value:
-             - "10.20.36.0"
-             - "192.168.255.0"
+            - "10.20.36.0"
+            - "192.168.255.0"
   register: extended_queryout
 
 - name: Dump "Extended query example" output
   ansible.builtin.debug:
     msg: '{{ extended_queryout }}'
 
-- name: Update example - ether2 ip addres with ".id = *14"
+- name: Update example - ether2 ip address with ".id = *14"
   community.routeros.api:
     hostname: "{{ hostname }}"
     password: "{{ password }}"
     username: "{{ username }}"
     path: "ip address"
     update: >-
-        .id=*14
-        address=192.168.255.20/24
-        comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}
+      .id=*14
+      address=192.168.255.20/24
+      comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}
 
 - name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
   community.routeros.api:
@@ -251,18 +262,17 @@ EXAMPLES = '''
 - name: Dump "Arbitrary command example" output
   ansible.builtin.debug:
     msg: '{{ arbitraryout }}'
-'''
+"""
 
-RETURN = '''
----
+RETURN = r"""
 message:
-    description: All outputs are in list with dictionary elements returned from RouterOS api.
-    sample:
-        - address: 1.2.3.4
-        - address: 2.3.4.5
-    type: list
-    returned: always
-'''
+  description: All outputs are in list with dictionary elements returned from RouterOS API.
+  sample:
+    - address: 1.2.3.4
+    - address: 2.3.4.5
+  type: list
+  returned: always
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native

plugins/modules/api_facts.py

@@ -9,29 +9,27 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: api_facts
 author:
-    - "Egor Zaitsev (@heuels)"
-    - "Nikolay Dachev (@NikolayDachev)"
-    - "Felix Fontein (@felixfontein)"
+  - "Egor Zaitsev (@heuels)"
+  - "Nikolay Dachev (@NikolayDachev)"
+  - "Felix Fontein (@felixfontein)"
 version_added: 2.1.0
 short_description: Collect facts from remote devices running MikroTik RouterOS using the API
 description:
-  - Collects a base set of device facts from a remote device that
-    is running RouterOS.  This module prepends all of the
-    base network fact keys with C(ansible_net_<fact>).  The facts
-    module will always collect a base set of facts from the device
+  - Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the base
+    network fact keys with C(ansible_net_<fact>). The facts module will always collect a base set of facts from the device
     and can enable or disable collection of additional facts.
-  - As opposed to the M(community.routeros.facts) module, it uses the
-    RouterOS API, similar to the M(community.routeros.api) module.
+  - As opposed to the M(community.routeros.facts) module, it uses the RouterOS API, similar to the M(community.routeros.api)
+    module.
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
   - 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
@@ -39,12 +37,10 @@ attributes:
 options:
   gather_subset:
     description:
-      - When supplied, this argument will restrict the facts collected
-        to a given subset.  Possible values for this argument include
-        C(all), C(hardware), C(interfaces), and C(routing).
-      - Can specify a list of values to include a larger subset.
-        Values can also be used with an initial C(!) to specify that a
-        specific subset should not be collected.
+      - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
+        include V(all), V(hardware), V(interfaces), and V(routing).
+      - Can specify a list of values to include a larger subset. Values can also be used with an initial V(!) to specify that
+        a specific subset should not be collected.
     required: false
     default:
       - all
@@ -56,9 +52,10 @@ seealso:
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Collect all facts from the device
   community.routeros.api_facts:
     hostname: 192.168.88.1
@@ -75,7 +72,7 @@ EXAMPLES = """
       - "!hardware"
 """
 
-RETURN = """
+RETURN = r"""
 ansible_facts:
   description: "Dictionary of IP geolocation facts for a host's IP address."
   returned: always
@@ -89,93 +86,93 @@ ansible_facts:
     # default
     ansible_net_model:
       description: The model name returned from the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_serialnum:
       description: The serial number of the remote device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_version:
       description: The operating system version running on the remote device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_hostname:
       description: The configured hostname of the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_arch:
       description: The CPU architecture of the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_uptime:
       description: The uptime of the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_cpu_load:
       description: Current CPU load.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
 
     # hardware
     ansible_net_spacefree_mb:
       description: The available disk space on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: dict
     ansible_net_spacetotal_mb:
       description: The total disk space on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: dict
     ansible_net_memfree_mb:
       description: The available free memory on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: int
     ansible_net_memtotal_mb:
       description: The total memory on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: int
 
     # interfaces
     ansible_net_all_ipv4_addresses:
       description: All IPv4 addresses configured on the device.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: list
     ansible_net_all_ipv6_addresses:
       description: All IPv6 addresses configured on the device.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: list
     ansible_net_interfaces:
       description: A hash of all interfaces running on the system.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: dict
     ansible_net_neighbors:
       description: The list of neighbors from the remote device.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: dict
 
     # routing
     ansible_net_bgp_peer:
       description: A dictionary with BGP peer information.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_bgp_vpnv4_route:
       description: A dictionary with BGP vpnv4 route information.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_bgp_instance:
       description: A dictionary with BGP instance information.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_route:
       description: A dictionary for routes in all routing tables.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_ospf_instance:
       description: A dictionary with OSPF instances.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_ospf_neighbor:
       description: A dictionary with OSPF neighbors.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
 """
 
@@ -320,8 +317,10 @@ class Interfaces(FactsBase):
     def populate_addresses(self, data, family):
         for value in data:
             key = value['interface']
-            if family not in self.facts['interfaces'][key]:
-                self.facts['interfaces'][key][family] = []
+            iface = self.facts['interfaces'].setdefault(key, (
+                {"type": "ansible:unknown"} if key.startswith('*') else
+                {"type": "ansible:mismatch"}))
+            iface_addrs = iface.setdefault(family, [])
             addr, subnet = value['address'].split('/')
             subnet = subnet.strip()
             # Try to convert subnet to an integer
@@ -331,7 +330,7 @@ class Interfaces(FactsBase):
                 pass
             ip = dict(address=addr.strip(), subnet=subnet)
             self.add_ip_address(addr.strip(), family)
-            self.facts['interfaces'][key][family].append(ip)
+            iface_addrs.append(ip)
 
     def add_ip_address(self, address, family):
         if family == 'ipv4':
@@ -422,8 +421,6 @@ FACT_SUBSETS = dict(
 
 VALID_SUBSETS = frozenset(FACT_SUBSETS.keys())
 
-warnings = []
-
 
 def main():
     argument_spec = dict(
@@ -488,7 +485,7 @@ def main():
         key = 'ansible_net_%s' % key
         ansible_facts[key] = value
 
-    module.exit_json(ansible_facts=ansible_facts, warnings=warnings)
+    module.exit_json(ansible_facts=ansible_facts)
 
 
 if __name__ == '__main__':

plugins/modules/api_find_and_modify.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: api_find_and_modify
 author:
   - "Felix Fontein (@felixfontein)"
@@ -17,13 +16,13 @@ short_description: Find and modify information using the API
 version_added: 2.1.0
 description:
   - Allows to find entries for a path by conditions and modify the values of these entries.
-  - Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values,
-    or change multiple entries in different ways in one step.
+  - Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values, or change multiple
+    entries in different ways in one step.
 notes:
-  - "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that
-     there are at least N such values, you can use I(require_matches_min=N) together with I(allow_no_matches=true).
-     This will make the module fail if there are less than N such entries, but not if there is no match. The latter case
-     is needed for idempotency of the task: once the values have been changed, there should be no further match."
+  - "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that there
+    are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true). This will make
+    the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency
+    of the task: once the values have been changed, there should be no further match."
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
@@ -36,25 +35,27 @@ attributes:
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: full
 options:
   path:
     description:
       - Path to query.
-      - An example value is C(ip address). This is equivalent to running C(/ip address) in the RouterOS CLI.
+      - An example value is V(ip address). This is equivalent to running C(/ip address) in the RouterOS CLI.
     required: true
     type: str
   find:
     description:
       - Fields to search for.
-      - The module will only consider entries in the given I(path) that match all fields provided here.
-      - Use YAML C(~), or prepend keys with C(!), to specify an unset value.
+      - The module will only consider entries in the given O(path) that match all fields provided here.
+      - Use YAML V(~), or prepend keys with V(!), to specify an unset value.
       - Note that if the dictionary specified here is empty, every entry in the path will be matched.
     required: true
     type: dict
   values:
     description:
-      - On all entries matching the conditions in I(find), set the keys of this option to the values specified here.
-      - Use YAML C(~), or prepend keys with C(!), to specify to unset a value.
+      - On all entries matching the conditions in O(find), set the keys of this option to the values specified here.
+      - Use YAML V(~), or prepend keys with V(!), to specify to unset a value.
     required: true
     type: dict
   require_matches_min:
@@ -72,16 +73,32 @@ options:
   allow_no_matches:
     description:
       - Whether to allow that no match is found.
-      - If not specified, this value is induced from whether I(require_matches_min) is 0 or larger.
+      - If not specified, this value is induced from whether O(require_matches_min) is 0 or larger.
     type: bool
+  ignore_dynamic:
+    description:
+      - Whether to ignore dynamic entries.
+      - By default, they are considered. If set to V(true), they are not considered.
+      - It is generally recommended to set this to V(true) unless when you really need to modify dynamic entries.
+    type: bool
+    default: false
+    version_added: 3.7.0
+  ignore_builtin:
+    description:
+      - Whether to ignore builtin entries.
+      - By default, they are considered. If set to V(true), they are not considered.
+      - It is generally recommended to set this to V(true) unless when you really need to modify builtin entries.
+    type: bool
+    default: false
+    version_added: 3.7.0
 seealso:
   - module: community.routeros.api
   - module: community.routeros.api_facts
   - module: community.routeros.api_modify
   - module: community.routeros.api_info
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 - name: Rename bridge from 'bridge' to 'my-bridge'
   community.routeros.api_find_and_modify:
@@ -93,6 +110,10 @@ EXAMPLES = '''
       name: bridge
     values:
       name: my-bridge
+    # Always ignore dynamic and builtin entries
+    # (not relevant for this path, but generally recommended)
+    ignore_dynamic: true
+    ignore_builtin: true
 
 - name: Change IP address to 192.168.1.1 for interface bridge - assuming there is only one
   community.routeros.api_find_and_modify:
@@ -108,55 +129,58 @@ EXAMPLES = '''
     # exactly one is configured.
     require_matches_min: 1
     require_matches_max: 1
-'''
+    # Always ignore dynamic and builtin entries
+    # (not relevant for this path, but generally recommended)
+    ignore_dynamic: true
+    ignore_builtin: true
+"""
 
-RETURN = '''
----
+RETURN = r"""
 old_data:
-    description:
-      - A list of all elements for the current path before a change was made.
-    sample:
-      - '.id': '*1'
-        actual-interface: bridge
-        address: "192.168.88.1/24"
-        comment: defconf
-        disabled: false
-        dynamic: false
-        interface: bridge
-        invalid: false
-        network: 192.168.88.0
-    type: list
-    elements: dict
-    returned: success
+  description:
+    - A list of all elements for the current path before a change was made.
+  sample:
+    - '.id': '*1'
+      actual-interface: bridge
+      address: "192.168.88.1/24"
+      comment: defconf
+      disabled: false
+      dynamic: false
+      interface: bridge
+      invalid: false
+      network: 192.168.88.0
+  type: list
+  elements: dict
+  returned: success
 new_data:
-    description:
-      - A list of all elements for the current path after a change was made.
-    sample:
-      - '.id': '*1'
-        actual-interface: bridge
-        address: "192.168.1.1/24"
-        comment: awesome
-        disabled: false
-        dynamic: false
-        interface: bridge
-        invalid: false
-        network: 192.168.1.0
-    type: list
-    elements: dict
-    returned: success
+  description:
+    - A list of all elements for the current path after a change was made.
+  sample:
+    - '.id': '*1'
+      actual-interface: bridge
+      address: "192.168.1.1/24"
+      comment: awesome
+      disabled: false
+      dynamic: false
+      interface: bridge
+      invalid: false
+      network: 192.168.1.0
+  type: list
+  elements: dict
+  returned: success
 match_count:
-    description:
-      - The number of entries that matched the criteria in I(find).
-    sample: 1
-    type: int
-    returned: success
+  description:
+    - The number of entries that matched the criteria in O(find).
+  sample: 1
+  type: int
+  returned: success
 modify__count:
-    description:
-      - The number of entries that were modified.
-    sample: 1
-    type: int
-    returned: success
-'''
+  description:
+    - The number of entries that were modified.
+  sample: 1
+  type: int
+  returned: success
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native
@@ -185,6 +209,17 @@ def compose_api_path(api, path):
     return api_path
 
 
+def filter_entries(entries, ignore_dynamic=False, ignore_builtin=False):
+    result = []
+    for entry in entries:
+        if ignore_dynamic and entry.get('dynamic', False):
+            continue
+        if ignore_builtin and entry.get('builtin', False):
+            continue
+        result.append(entry)
+    return result
+
+
 DISABLED_MEANS_EMPTY_STRING = ('comment', )
 
 
@@ -196,6 +231,8 @@ def main():
         require_matches_min=dict(type='int', default=0),
         require_matches_max=dict(type='int'),
         allow_no_matches=dict(type='bool'),
+        ignore_dynamic=dict(type='bool', default=False),
+        ignore_builtin=dict(type='bool', default=False),
     )
     module_args.update(api_argument_spec())
 
@@ -223,6 +260,9 @@ def main():
             if key in values:
                 module.fail_json(msg='`values` must not contain both "{key}" and "!{key}"!'.format(key=key))
 
+    ignore_dynamic = module.params['ignore_dynamic']
+    ignore_builtin = module.params['ignore_builtin']
+
     check_has_library(module)
     api = create_api(module)
 
@@ -230,7 +270,7 @@ def main():
 
     api_path = compose_api_path(api, path)
 
-    old_data = list(api_path)
+    old_data = filter_entries(list(api_path), ignore_dynamic=ignore_dynamic, ignore_builtin=ignore_builtin)
     new_data = [entry.copy() for entry in old_data]
 
     # Find matching entries
@@ -299,7 +339,7 @@ def main():
                         error=to_native(e),
                     )
                 )
-        new_data = list(api_path)
+        new_data = filter_entries(list(api_path), ignore_dynamic=ignore_dynamic, ignore_builtin=ignore_builtin)
 
     # Produce return value
     more = {}

plugins/modules/api_info.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: api_info
 author:
   - "Felix Fontein (@felixfontein)"
@@ -18,16 +17,18 @@ 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, dynamic and builtin entries are not returned. Use the I(handle_disabled) and
-    I(hide_defaults) options to control normalization, the I(include_dynamic) and I(include_builtin) options to also return
-    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/).
+  - Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and O(hide_defaults)
+    options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return dynamic resp. builtin
+    entries, and use O(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/).
 extends_documentation_fragment:
   - community.routeros.api
+  - 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:
@@ -37,153 +38,237 @@ options:
   path:
     description:
       - Path to query.
-      - An example value is C(ip address). This is equivalent to running C(/ip address print) in the RouterOS CLI.
+      - An example value is V(ip address). This is equivalent to running C(/ip address print) in the RouterOS CLI.
     required: true
     type: str
     choices:
     # BEGIN PATH LIST
-        - caps-man aaa
-        - caps-man access-list
-        - caps-man configuration
-        - caps-man datapath
-        - caps-man manager
-        - caps-man provisioning
-        - caps-man security
-        - certificate settings
-        - interface bonding
-        - interface bridge
-        - interface bridge mlag
-        - interface bridge port
-        - interface bridge port-controller
-        - interface bridge port-extender
-        - interface bridge settings
-        - interface bridge vlan
-        - interface detect-internet
-        - interface eoip
-        - interface ethernet
-        - interface ethernet poe
-        - interface ethernet switch
-        - interface ethernet switch port
-        - interface gre
-        - interface gre6
-        - interface l2tp-server server
-        - interface list
-        - interface list member
-        - interface ovpn-server server
-        - interface pppoe-client
-        - interface pptp-server server
-        - interface sstp-server server
-        - interface vlan
-        - interface vrrp
-        - interface wireguard
-        - interface wireguard peers
-        - interface wireless align
-        - interface wireless cap
-        - interface wireless sniffer
-        - interface wireless snooper
-        - ip accounting
-        - ip accounting web-access
-        - ip address
-        - ip arp
-        - ip cloud
-        - ip cloud advanced
-        - ip dhcp-client
-        - ip dhcp-client option
-        - ip dhcp-server
-        - ip dhcp-server config
-        - ip dhcp-server lease
-        - ip dhcp-server network
-        - ip dns
-        - ip dns static
-        - ip firewall address-list
-        - ip firewall connection tracking
-        - ip firewall filter
-        - ip firewall layer7-protocol
-        - ip firewall mangle
-        - ip firewall nat
-        - ip firewall raw
-        - ip firewall service-port
-        - ip hotspot service-port
-        - ip ipsec identity
-        - ip ipsec peer
-        - ip ipsec policy
-        - ip ipsec profile
-        - ip ipsec proposal
-        - ip ipsec settings
-        - ip neighbor discovery-settings
-        - ip pool
-        - ip proxy
-        - ip route
-        - ip route vrf
-        - ip service
-        - ip settings
-        - ip smb
-        - ip socks
-        - ip ssh
-        - ip tftp settings
-        - ip traffic-flow
-        - ip traffic-flow ipfix
-        - ip upnp
-        - ipv6 address
-        - ipv6 dhcp-client
-        - ipv6 dhcp-server
-        - ipv6 dhcp-server option
-        - ipv6 firewall address-list
-        - ipv6 firewall filter
-        - ipv6 firewall mangle
-        - ipv6 firewall raw
-        - ipv6 nd
-        - ipv6 nd prefix default
-        - ipv6 route
-        - ipv6 settings
-        - mpls
-        - mpls ldp
-        - port firmware
-        - ppp aaa
-        - queue interface
-        - queue tree
-        - radius incoming
-        - routing bgp instance
-        - routing mme
-        - routing ospf area
-        - routing ospf area range
-        - routing ospf instance
-        - routing ospf interface-template
-        - routing pimsm instance
-        - routing pimsm interface-template
-        - routing rip
-        - routing ripng
-        - snmp
-        - snmp community
-        - system clock
-        - system clock manual
-        - system identity
-        - system leds settings
-        - system logging
-        - system logging action
-        - system note
-        - system ntp client
-        - system ntp client servers
-        - system ntp server
-        - system package update
-        - system routerboard settings
-        - system scheduler
-        - system script
-        - system upgrade mirror
-        - system ups
-        - system watchdog
-        - tool bandwidth-server
-        - tool e-mail
-        - tool graphing
-        - tool mac-server
-        - tool mac-server mac-winbox
-        - tool mac-server ping
-        - tool romon
-        - tool sms
-        - tool sniffer
-        - tool traffic-generator
-        - user aaa
-        - user group
+      - caps-man aaa
+      - caps-man access-list
+      - caps-man channel
+      - caps-man configuration
+      - caps-man datapath
+      - caps-man manager
+      - caps-man manager interface
+      - caps-man provisioning
+      - caps-man security
+      - certificate settings
+      - interface 6to4
+      - interface bonding
+      - interface bridge
+      - interface bridge mlag
+      - interface bridge port
+      - interface bridge port-controller
+      - interface bridge port-extender
+      - interface bridge settings
+      - interface bridge vlan
+      - interface detect-internet
+      - interface eoip
+      - interface ethernet
+      - interface ethernet poe
+      - interface ethernet switch
+      - interface ethernet switch port
+      - interface ethernet switch port-isolation
+      - interface gre
+      - interface gre6
+      - interface l2tp-client
+      - interface l2tp-server server
+      - interface list
+      - interface list member
+      - interface ovpn-client
+      - interface ovpn-server server
+      - interface ppp-client
+      - interface pppoe-client
+      - interface pppoe-server server
+      - interface pptp-server server
+      - interface sstp-server server
+      - interface vlan
+      - interface vrrp
+      - interface wifi
+      - interface wifi aaa
+      - interface wifi access-list
+      - interface wifi cap
+      - interface wifi capsman
+      - interface wifi channel
+      - interface wifi configuration
+      - interface wifi datapath
+      - interface wifi interworking
+      - interface wifi provisioning
+      - interface wifi security
+      - interface wifi steering
+      - interface wifiwave2
+      - interface wifiwave2 aaa
+      - interface wifiwave2 access-list
+      - interface wifiwave2 cap
+      - interface wifiwave2 capsman
+      - interface wifiwave2 channel
+      - interface wifiwave2 configuration
+      - interface wifiwave2 datapath
+      - interface wifiwave2 interworking
+      - interface wifiwave2 provisioning
+      - interface wifiwave2 security
+      - interface wifiwave2 steering
+      - interface wireguard
+      - interface wireguard peers
+      - interface wireless
+      - interface wireless access-list
+      - interface wireless align
+      - interface wireless cap
+      - interface wireless connect-list
+      - interface wireless security-profiles
+      - interface wireless sniffer
+      - interface wireless snooper
+      - iot modbus
+      - ip accounting
+      - ip accounting web-access
+      - ip address
+      - ip arp
+      - ip cloud
+      - ip cloud advanced
+      - ip dhcp-client
+      - ip dhcp-client option
+      - ip dhcp-relay
+      - ip dhcp-server
+      - ip dhcp-server config
+      - ip dhcp-server lease
+      - ip dhcp-server matcher
+      - ip dhcp-server network
+      - ip dhcp-server option
+      - ip dhcp-server option sets
+      - ip dns
+      - ip dns adlist
+      - ip dns forwarders
+      - ip dns static
+      - ip firewall address-list
+      - ip firewall connection tracking
+      - ip firewall filter
+      - ip firewall layer7-protocol
+      - ip firewall mangle
+      - ip firewall nat
+      - ip firewall raw
+      - ip firewall service-port
+      - ip hotspot service-port
+      - ip ipsec identity
+      - ip ipsec mode-config
+      - ip ipsec peer
+      - ip ipsec policy
+      - ip ipsec profile
+      - ip ipsec proposal
+      - ip ipsec settings
+      - ip neighbor discovery-settings
+      - ip pool
+      - ip proxy
+      - ip route
+      - ip route rule
+      - ip route vrf
+      - ip service
+      - ip settings
+      - ip smb
+      - ip socks
+      - ip ssh
+      - ip tftp settings
+      - ip traffic-flow
+      - ip traffic-flow ipfix
+      - ip traffic-flow target
+      - ip upnp
+      - ip upnp interfaces
+      - ip vrf
+      - ipv6 address
+      - ipv6 dhcp-client
+      - ipv6 dhcp-server
+      - ipv6 dhcp-server option
+      - ipv6 firewall address-list
+      - ipv6 firewall filter
+      - ipv6 firewall mangle
+      - ipv6 firewall nat
+      - ipv6 firewall raw
+      - ipv6 nd
+      - ipv6 nd prefix
+      - ipv6 nd prefix default
+      - ipv6 route
+      - ipv6 settings
+      - mpls
+      - mpls interface
+      - mpls ldp
+      - mpls ldp accept-filter
+      - mpls ldp advertise-filter
+      - mpls ldp interface
+      - port firmware
+      - port remote-access
+      - ppp aaa
+      - ppp profile
+      - ppp secret
+      - queue interface
+      - queue simple
+      - queue tree
+      - queue type
+      - radius
+      - radius incoming
+      - routing bfd configuration
+      - routing bgp aggregate
+      - routing bgp connection
+      - routing bgp instance
+      - routing bgp network
+      - routing bgp peer
+      - routing bgp template
+      - routing filter
+      - routing filter community-list
+      - routing filter num-list
+      - routing filter rule
+      - routing filter select-rule
+      - routing id
+      - routing igmp-proxy
+      - routing igmp-proxy interface
+      - routing mme
+      - routing ospf area
+      - routing ospf area range
+      - routing ospf instance
+      - routing ospf interface-template
+      - routing ospf static-neighbor
+      - routing pimsm instance
+      - routing pimsm interface-template
+      - routing rip
+      - routing ripng
+      - routing rule
+      - routing table
+      - snmp
+      - snmp community
+      - system clock
+      - system clock manual
+      - system health settings
+      - system identity
+      - system leds settings
+      - system logging
+      - system logging action
+      - system note
+      - system ntp client
+      - system ntp client servers
+      - system ntp server
+      - system package update
+      - system resource irq rps
+      - system routerboard settings
+      - system scheduler
+      - system script
+      - system upgrade mirror
+      - system ups
+      - system watchdog
+      - tool bandwidth-server
+      - tool e-mail
+      - tool graphing
+      - tool graphing interface
+      - tool graphing resource
+      - tool mac-server
+      - tool mac-server mac-winbox
+      - tool mac-server ping
+      - tool netwatch
+      - tool romon
+      - tool sms
+      - tool sniffer
+      - tool traffic-generator
+      - user
+      - user aaa
+      - user group
+      - user settings
     # END PATH LIST
   unfiltered:
     description:
@@ -194,9 +279,9 @@ options:
   handle_disabled:
     description:
       - How to handle unset values.
-      - C(exclamation) prepends the keys with C(!) in the output with value C(null).
-      - C(null-value) uses the regular key with value C(null).
-      - C(omit) omits these values from the result.
+      - V(exclamation) prepends the keys with V(!) in the output with value V(null).
+      - V(null-value) uses the regular key with value V(null).
+      - V(omit) omits these values from the result.
     type: str
     choices:
       - exclamation
@@ -212,25 +297,36 @@ options:
     description:
       - Whether to include dynamic values.
       - By default, they are not returned, and the C(dynamic) keys are omitted.
-      - If set to C(true), they are returned as well, and the C(dynamic) keys are returned as well.
+      - If set to V(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.
+      - If set to V(true), they are returned as well, and the C(builtin) keys are returned as well.
     type: bool
     default: false
     version_added: 2.4.0
+  include_read_only:
+    description:
+      - Whether to include read-only fields.
+      - By default, they are not returned.
+    type: bool
+    default: false
+    version_added: 2.10.0
+  restrict:
+    description:
+      - Restrict output to entries matching the following criteria.
+    version_added: 2.18.0
 seealso:
   - module: community.routeros.api
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 - name: Get IP addresses
   community.routeros.api_info:
@@ -243,26 +339,37 @@ EXAMPLES = '''
 - name: Print data for IP addresses
   ansible.builtin.debug:
     var: ip_addresses.result
-'''
 
-RETURN = '''
----
+- name: Get IP addresses
+  community.routeros.api_info:
+    hostname: "{{ hostname }}"
+    password: "{{ password }}"
+    username: "{{ username }}"
+    path: ip address
+  register: ip_addresses
+
+- name: Print data for IP addresses
+  ansible.builtin.debug:
+    var: ip_addresses.result
+"""
+
+RETURN = r"""
 result:
-    description: A list of all elements for the current path.
-    sample:
-      - '.id': '*1'
-        actual-interface: bridge
-        address: "192.168.88.1/24"
-        comment: defconf
-        disabled: false
-        dynamic: false
-        interface: bridge
-        invalid: false
-        network: 192.168.88.0
-    type: list
-    elements: dict
-    returned: always
-'''
+  description: A list of all elements for the current path.
+  sample:
+    - '.id': '*1'
+      actual-interface: bridge
+      address: "192.168.88.1/24"
+      comment: defconf
+      disabled: false
+      dynamic: false
+      interface: bridge
+      invalid: false
+      network: 192.168.88.0
+  type: list
+  elements: dict
+  returned: always
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native
@@ -271,6 +378,7 @@ from ansible_collections.community.routeros.plugins.module_utils.api import (
     api_argument_spec,
     check_has_library,
     create_api,
+    get_api_version,
 )
 
 from ansible_collections.community.routeros.plugins.module_utils._api_data import (
@@ -279,6 +387,12 @@ from ansible_collections.community.routeros.plugins.module_utils._api_data impor
     split_path,
 )
 
+from ansible_collections.community.routeros.plugins.module_utils._api_helper import (
+    restrict_argument_spec,
+    restrict_entry_accepted,
+    validate_and_prepare_restrict,
+)
+
 try:
     from librouteros.exceptions import LibRouterosError
 except Exception:
@@ -301,8 +415,10 @@ def main():
         hide_defaults=dict(type='bool', default=True),
         include_dynamic=dict(type='bool', default=False),
         include_builtin=dict(type='bool', default=False),
+        include_read_only=dict(type='bool', default=False),
     )
     module_args.update(api_argument_spec())
+    module_args.update(restrict_argument_spec())
 
     module = AnsibleModule(
         argument_spec=module_args,
@@ -313,14 +429,25 @@ def main():
     api = create_api(module)
 
     path = split_path(module.params['path'])
-    path_info = PATHS.get(tuple(path))
-    if path_info is None:
+    versioned_path_info = PATHS.get(tuple(path))
+    if versioned_path_info is None:
         module.fail_json(msg='Path /{path} is not yet supported'.format(path='/'.join(path)))
+    if versioned_path_info.needs_version:
+        api_version = get_api_version(api)
+        supported, not_supported_msg = versioned_path_info.provide_version(api_version)
+        if not supported:
+            msg = 'Path /{path} is not supported for API version {api_version}'.format(path='/'.join(path), api_version=api_version)
+            if not_supported_msg:
+                msg = '{0}: {1}'.format(msg, not_supported_msg)
+            module.fail_json(msg=msg)
+    path_info = versioned_path_info.get_data()
 
     handle_disabled = module.params['handle_disabled']
     hide_defaults = module.params['hide_defaults']
     include_dynamic = module.params['include_dynamic']
     include_builtin = module.params['include_builtin']
+    include_read_only = module.params['include_read_only']
+    restrict_data = validate_and_prepare_restrict(module, path_info)
     try:
         api_path = compose_api_path(api, path)
 
@@ -333,6 +460,8 @@ def main():
             if not include_builtin:
                 if entry.get('builtin', False):
                     continue
+            if not restrict_entry_accepted(entry, path_info, restrict_data):
+                continue
             if not unfiltered:
                 for k in list(entry):
                     if k == '.id':
@@ -344,7 +473,10 @@ def main():
                     if k not in path_info.fields:
                         entry.pop(k)
             if handle_disabled != 'omit':
-                for k in path_info.fields:
+                for k, field_info in path_info.fields.items():
+                    if field_info.write_only:
+                        entry.pop(k, None)
+                        continue
                     if k not in entry:
                         if handle_disabled == 'exclamation':
                             k = '!%s' % k
@@ -355,6 +487,8 @@ def main():
                         entry.pop(k)
                 if field_info.absent_value and k not in entry:
                     entry[k] = field_info.absent_value
+                if not include_read_only and k in entry and field_info.read_only:
+                    entry.pop(k)
             result.append(entry)
 
         module.exit_json(result=result)

plugins/modules/api_modify.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: api_modify
 author:
   - "Felix Fontein (@felixfontein)"
@@ -17,17 +16,22 @@ short_description: Modify data at paths with API
 version_added: 2.2.0
 description:
   - Allows to modify information for a path using the API.
-  - 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.
+  - 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 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/).
+  - 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/).
+notes:
+  - If write-only fields are present in the path, the module is B(not idempotent) in a strict sense, since it is not able
+    to verify the current value of these fields. The behavior the module should assume can be controlled with the O(handle_write_only)
+    option.
 requirements:
   - Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6
 extends_documentation_fragment:
   - community.routeros.api
+  - community.routeros.api.restrict
   - community.routeros.attributes
   - community.routeros.attributes.actiongroup_api
 attributes:
@@ -38,157 +42,244 @@ attributes:
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: full
 options:
   path:
     description:
       - Path to query.
-      - An example value is C(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS CLI.
+      - An example value is V(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS
+        CLI.
     required: true
     type: str
     choices:
     # BEGIN PATH LIST
-        - caps-man aaa
-        - caps-man access-list
-        - caps-man configuration
-        - caps-man datapath
-        - caps-man manager
-        - caps-man provisioning
-        - caps-man security
-        - certificate settings
-        - interface bonding
-        - interface bridge
-        - interface bridge mlag
-        - interface bridge port
-        - interface bridge port-controller
-        - interface bridge port-extender
-        - interface bridge settings
-        - interface bridge vlan
-        - interface detect-internet
-        - interface eoip
-        - interface ethernet
-        - interface ethernet poe
-        - interface ethernet switch
-        - interface ethernet switch port
-        - interface gre
-        - interface gre6
-        - interface l2tp-server server
-        - interface list
-        - interface list member
-        - interface ovpn-server server
-        - interface pppoe-client
-        - interface pptp-server server
-        - interface sstp-server server
-        - interface vlan
-        - interface vrrp
-        - interface wireguard
-        - interface wireguard peers
-        - interface wireless align
-        - interface wireless cap
-        - interface wireless sniffer
-        - interface wireless snooper
-        - ip accounting
-        - ip accounting web-access
-        - ip address
-        - ip arp
-        - ip cloud
-        - ip cloud advanced
-        - ip dhcp-client
-        - ip dhcp-client option
-        - ip dhcp-server
-        - ip dhcp-server config
-        - ip dhcp-server lease
-        - ip dhcp-server network
-        - ip dns
-        - ip dns static
-        - ip firewall address-list
-        - ip firewall connection tracking
-        - ip firewall filter
-        - ip firewall layer7-protocol
-        - ip firewall mangle
-        - ip firewall nat
-        - ip firewall raw
-        - ip firewall service-port
-        - ip hotspot service-port
-        - ip ipsec identity
-        - ip ipsec peer
-        - ip ipsec policy
-        - ip ipsec profile
-        - ip ipsec proposal
-        - ip ipsec settings
-        - ip neighbor discovery-settings
-        - ip pool
-        - ip proxy
-        - ip route
-        - ip route vrf
-        - ip service
-        - ip settings
-        - ip smb
-        - ip socks
-        - ip ssh
-        - ip tftp settings
-        - ip traffic-flow
-        - ip traffic-flow ipfix
-        - ip upnp
-        - ipv6 address
-        - ipv6 dhcp-client
-        - ipv6 dhcp-server
-        - ipv6 dhcp-server option
-        - ipv6 firewall address-list
-        - ipv6 firewall filter
-        - ipv6 firewall mangle
-        - ipv6 firewall raw
-        - ipv6 nd
-        - ipv6 nd prefix default
-        - ipv6 route
-        - ipv6 settings
-        - mpls
-        - mpls ldp
-        - port firmware
-        - ppp aaa
-        - queue interface
-        - queue tree
-        - radius incoming
-        - routing bgp instance
-        - routing mme
-        - routing ospf area
-        - routing ospf area range
-        - routing ospf instance
-        - routing ospf interface-template
-        - routing pimsm instance
-        - routing pimsm interface-template
-        - routing rip
-        - routing ripng
-        - snmp
-        - snmp community
-        - system clock
-        - system clock manual
-        - system identity
-        - system leds settings
-        - system logging
-        - system logging action
-        - system note
-        - system ntp client
-        - system ntp client servers
-        - system ntp server
-        - system package update
-        - system routerboard settings
-        - system scheduler
-        - system script
-        - system upgrade mirror
-        - system ups
-        - system watchdog
-        - tool bandwidth-server
-        - tool e-mail
-        - tool graphing
-        - tool mac-server
-        - tool mac-server mac-winbox
-        - tool mac-server ping
-        - tool romon
-        - tool sms
-        - tool sniffer
-        - tool traffic-generator
-        - user aaa
-        - user group
+      - caps-man aaa
+      - caps-man access-list
+      - caps-man channel
+      - caps-man configuration
+      - caps-man datapath
+      - caps-man manager
+      - caps-man manager interface
+      - caps-man provisioning
+      - caps-man security
+      - certificate settings
+      - interface 6to4
+      - interface bonding
+      - interface bridge
+      - interface bridge mlag
+      - interface bridge port
+      - interface bridge port-controller
+      - interface bridge port-extender
+      - interface bridge settings
+      - interface bridge vlan
+      - interface detect-internet
+      - interface eoip
+      - interface ethernet
+      - interface ethernet poe
+      - interface ethernet switch
+      - interface ethernet switch port
+      - interface ethernet switch port-isolation
+      - interface gre
+      - interface gre6
+      - interface l2tp-client
+      - interface l2tp-server server
+      - interface list
+      - interface list member
+      - interface ovpn-client
+      - interface ovpn-server server
+      - interface ppp-client
+      - interface pppoe-client
+      - interface pppoe-server server
+      - interface pptp-server server
+      - interface sstp-server server
+      - interface vlan
+      - interface vrrp
+      - interface wifi
+      - interface wifi aaa
+      - interface wifi access-list
+      - interface wifi cap
+      - interface wifi capsman
+      - interface wifi channel
+      - interface wifi configuration
+      - interface wifi datapath
+      - interface wifi interworking
+      - interface wifi provisioning
+      - interface wifi security
+      - interface wifi steering
+      - interface wifiwave2
+      - interface wifiwave2 aaa
+      - interface wifiwave2 access-list
+      - interface wifiwave2 cap
+      - interface wifiwave2 capsman
+      - interface wifiwave2 channel
+      - interface wifiwave2 configuration
+      - interface wifiwave2 datapath
+      - interface wifiwave2 interworking
+      - interface wifiwave2 provisioning
+      - interface wifiwave2 security
+      - interface wifiwave2 steering
+      - interface wireguard
+      - interface wireguard peers
+      - interface wireless
+      - interface wireless access-list
+      - interface wireless align
+      - interface wireless cap
+      - interface wireless connect-list
+      - interface wireless security-profiles
+      - interface wireless sniffer
+      - interface wireless snooper
+      - iot modbus
+      - ip accounting
+      - ip accounting web-access
+      - ip address
+      - ip arp
+      - ip cloud
+      - ip cloud advanced
+      - ip dhcp-client
+      - ip dhcp-client option
+      - ip dhcp-relay
+      - ip dhcp-server
+      - ip dhcp-server config
+      - ip dhcp-server lease
+      - ip dhcp-server matcher
+      - ip dhcp-server network
+      - ip dhcp-server option
+      - ip dhcp-server option sets
+      - ip dns
+      - ip dns adlist
+      - ip dns forwarders
+      - ip dns static
+      - ip firewall address-list
+      - ip firewall connection tracking
+      - ip firewall filter
+      - ip firewall layer7-protocol
+      - ip firewall mangle
+      - ip firewall nat
+      - ip firewall raw
+      - ip firewall service-port
+      - ip hotspot service-port
+      - ip ipsec identity
+      - ip ipsec mode-config
+      - ip ipsec peer
+      - ip ipsec policy
+      - ip ipsec profile
+      - ip ipsec proposal
+      - ip ipsec settings
+      - ip neighbor discovery-settings
+      - ip pool
+      - ip proxy
+      - ip route
+      - ip route rule
+      - ip route vrf
+      - ip service
+      - ip settings
+      - ip smb
+      - ip socks
+      - ip ssh
+      - ip tftp settings
+      - ip traffic-flow
+      - ip traffic-flow ipfix
+      - ip traffic-flow target
+      - ip upnp
+      - ip upnp interfaces
+      - ip vrf
+      - ipv6 address
+      - ipv6 dhcp-client
+      - ipv6 dhcp-server
+      - ipv6 dhcp-server option
+      - ipv6 firewall address-list
+      - ipv6 firewall filter
+      - ipv6 firewall mangle
+      - ipv6 firewall nat
+      - ipv6 firewall raw
+      - ipv6 nd
+      - ipv6 nd prefix
+      - ipv6 nd prefix default
+      - ipv6 route
+      - ipv6 settings
+      - mpls
+      - mpls interface
+      - mpls ldp
+      - mpls ldp accept-filter
+      - mpls ldp advertise-filter
+      - mpls ldp interface
+      - port firmware
+      - port remote-access
+      - ppp aaa
+      - ppp profile
+      - ppp secret
+      - queue interface
+      - queue simple
+      - queue tree
+      - queue type
+      - radius
+      - radius incoming
+      - routing bfd configuration
+      - routing bgp aggregate
+      - routing bgp connection
+      - routing bgp instance
+      - routing bgp network
+      - routing bgp peer
+      - routing bgp template
+      - routing filter
+      - routing filter community-list
+      - routing filter num-list
+      - routing filter rule
+      - routing filter select-rule
+      - routing id
+      - routing igmp-proxy
+      - routing igmp-proxy interface
+      - routing mme
+      - routing ospf area
+      - routing ospf area range
+      - routing ospf instance
+      - routing ospf interface-template
+      - routing ospf static-neighbor
+      - routing pimsm instance
+      - routing pimsm interface-template
+      - routing rip
+      - routing ripng
+      - routing rule
+      - routing table
+      - snmp
+      - snmp community
+      - system clock
+      - system clock manual
+      - system health settings
+      - system identity
+      - system leds settings
+      - system logging
+      - system logging action
+      - system note
+      - system ntp client
+      - system ntp client servers
+      - system ntp server
+      - system package update
+      - system resource irq rps
+      - system routerboard settings
+      - system scheduler
+      - system script
+      - system upgrade mirror
+      - system ups
+      - system watchdog
+      - tool bandwidth-server
+      - tool e-mail
+      - tool graphing
+      - tool graphing interface
+      - tool graphing resource
+      - tool mac-server
+      - tool mac-server mac-winbox
+      - tool mac-server ping
+      - tool netwatch
+      - tool romon
+      - tool sms
+      - tool sniffer
+      - tool traffic-generator
+      - user
+      - user aaa
+      - user group
+      - user settings
     # END PATH LIST
   data:
     description:
@@ -200,15 +291,15 @@ options:
     elements: dict
   ensure_order:
     description:
-      - Whether to ensure the same order of the config as present in I(data).
-      - Requires I(handle_absent_entries=remove).
+      - Whether to ensure the same order of the config as present in O(data).
+      - Requires O(handle_absent_entries=remove).
     type: bool
     default: false
   handle_absent_entries:
     description:
-      - How to handle entries that are present in the current config, but not in I(data).
-      - C(ignore) ignores them.
-      - C(remove) removes them.
+      - How to handle entries that are present in the current config, but not in O(data).
+      - V(ignore) ignores them.
+      - V(remove) removes them.
     type: str
     choices:
       - ignore
@@ -216,26 +307,62 @@ options:
     default: ignore
   handle_entries_content:
     description:
-      - For a single entry in I(data), this describes how to handle fields that are not mentioned
-        in that entry, but appear in the actual config.
-      - If C(ignore), they are not modified.
-      - If C(remove), they are removed. If at least one cannot be removed, the module will fail.
-      - If C(remove_as_much_as_possible), all that can be removed will be removed. The ones that
-        cannot be removed will be kept.
+      - For a single entry in O(data), this describes how to handle fields that are not mentioned in that entry, but appear
+        in the actual config.
+      - If V(ignore), they are not modified.
+      - If V(remove), they are removed. If at least one cannot be removed, the module will fail.
+      - If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that cannot be removed will be
+        kept.
+      - Note that V(remove) and V(remove_as_much_as_possible) do not apply to write-only fields.
     type: str
     choices:
       - ignore
       - remove
       - remove_as_much_as_possible
     default: ignore
+  handle_read_only:
+    description:
+      - How to handle values passed in for read-only fields.
+      - If V(ignore), they are not passed to the API.
+      - If V(validate), the values are not passed for creation, and for updating they are compared to the value returned for
+        the object. If they differ, the module fails.
+      - If V(error), the module will fail if read-only fields are provided.
+    type: str
+    choices:
+      - ignore
+      - validate
+      - error
+    default: error
+    version_added: 2.10.0
+  handle_write_only:
+    description:
+      - How to handle values passed in for write-only fields.
+      - If V(create_only), they are passed on creation, and ignored for updating.
+      - If V(always_update), they are always passed to the API. This means that if such a value is present, the module will
+        always result in C(changed) since there is no way to validate whether the value actually changed.
+      - If V(error), the module will fail if write-only fields are provided.
+    type: str
+    choices:
+      - create_only
+      - always_update
+      - error
+    default: create_only
+    version_added: 2.10.0
+  restrict:
+    description:
+      - Restrict operation to entries matching the following criteria.
+      - This can be useful together with O(handle_absent_entries=remove) to operate on a subset of the values.
+      - For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and O(restrict[].values=input)
+        to restrict operation to the input chain, and ignore the forward and output chains.
+    version_added: 2.18.0
 seealso:
   - module: community.routeros.api
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 - name: Setup DHCP server networks
   # Ensures that we have exactly two DHCP server networks (in the specified order)
@@ -273,43 +400,59 @@ EXAMPLES = '''
         out-interface:
         to-addresses: ~
         '!to-ports':
-'''
 
-RETURN = '''
----
+- name: Block all incoming connections
+  community.routeros.api_modify:
+    hostname: "{{ hostname }}"
+    password: "{{ password }}"
+    username: "{{ username }}"
+    path: ip firewall filter
+    handle_absent_entries: remove
+    handle_entries_content: remove_as_much_as_possible
+    restrict:
+      # Do not touch any chain except the input chain
+      - field: chain
+        values:
+          - input
+    data:
+      - action: drop
+        chain: input
+"""
+
+RETURN = r"""
 old_data:
-    description:
-      - A list of all elements for the current path before a change was made.
-    sample:
-      - '.id': '*1'
-        actual-interface: bridge
-        address: "192.168.88.1/24"
-        comment: defconf
-        disabled: false
-        dynamic: false
-        interface: bridge
-        invalid: false
-        network: 192.168.88.0
-    type: list
-    elements: dict
-    returned: always
+  description:
+    - A list of all elements for the current path before a change was made.
+  sample:
+    - '.id': '*1'
+      actual-interface: bridge
+      address: "192.168.88.1/24"
+      comment: defconf
+      disabled: false
+      dynamic: false
+      interface: bridge
+      invalid: false
+      network: 192.168.88.0
+  type: list
+  elements: dict
+  returned: always
 new_data:
-    description:
-      - A list of all elements for the current path after a change was made.
-    sample:
-      - '.id': '*1'
-        actual-interface: bridge
-        address: "192.168.1.1/24"
-        comment: awesome
-        disabled: false
-        dynamic: false
-        interface: bridge
-        invalid: false
-        network: 192.168.1.0
-    type: list
-    elements: dict
-    returned: always
-'''
+  description:
+    - A list of all elements for the current path after a change was made.
+  sample:
+    - '.id': '*1'
+      actual-interface: bridge
+      address: "192.168.1.1/24"
+      comment: awesome
+      disabled: false
+      dynamic: false
+      interface: bridge
+      invalid: false
+      network: 192.168.1.0
+  type: list
+  elements: dict
+  returned: always
+"""
 
 from collections import defaultdict
 
@@ -320,6 +463,7 @@ from ansible_collections.community.routeros.plugins.module_utils.api import (
     api_argument_spec,
     check_has_library,
     create_api,
+    get_api_version,
 )
 
 from ansible_collections.community.routeros.plugins.module_utils._api_data import (
@@ -328,6 +472,12 @@ from ansible_collections.community.routeros.plugins.module_utils._api_data impor
     split_path,
 )
 
+from ansible_collections.community.routeros.plugins.module_utils._api_helper import (
+    restrict_argument_spec,
+    restrict_entry_accepted,
+    validate_and_prepare_restrict,
+)
+
 HAS_ORDEREDDICT = True
 try:
     from collections import OrderedDict
@@ -373,6 +523,18 @@ def find_modifications(old_entry, new_entry, path_info, module, for_text='', ret
             continue
         if k not in old_entry and path_info.fields[k].default == v and not path_info.fields[k].can_disable:
             continue
+        key_info = path_info.fields[k]
+        if key_info.read_only:
+            # handle_read_only must be 'validate'
+            if old_entry.get(k) != v:
+                module.fail_json(
+                    msg='Read-only key "{key}" has value "{old_value}", but should have new value "{new_value}"{for_text}.'.format(
+                        key=k, old_value=old_entry.get(k), new_value=v, for_text=for_text))
+            continue
+        if key_info.write_only:
+            if module.params['handle_write_only'] == 'create_only':
+                # do not update this value
+                continue
         if k not in old_entry or old_entry[k] != v:
             modifications[k] = v
             updated_entry[k] = v
@@ -441,6 +603,18 @@ def essentially_same_weight(old_entry, new_entry, path_info, module):
     return weight
 
 
+def remove_read_only(entry, path_info):
+    to_remove = []
+    for real_k, v in entry.items():
+        k = real_k
+        if k.startswith('!'):
+            k = k[1:]
+        if path_info.fields[k].read_only:
+            to_remove.append(real_k)
+    for k in to_remove:
+        entry.pop(k)
+
+
 def format_pk(primary_keys, values):
     return ', '.join('{pk}="{value}"'.format(pk=pk, value=value) for pk, value in zip(primary_keys, values))
 
@@ -448,6 +622,7 @@ def format_pk(primary_keys, values):
 def polish_entry(entry, path_info, module, for_text):
     if '.id' in entry:
         entry.pop('.id')
+    to_remove = []
     for key, value in entry.items():
         real_key = key
         disabled_key = False
@@ -467,6 +642,16 @@ def polish_entry(entry, path_info, module, for_text):
         elif value is None:
             if not key_info.can_disable:
                 module.fail_json(msg='Key "{key}" must not be disabled (value null/~/None){for_text}.'.format(key=key, for_text=for_text))
+        if key_info.read_only:
+            if module.params['handle_read_only'] == 'error':
+                module.fail_json(msg='Key "{key}" is read-only{for_text}, and handle_read_only=error.'.format(key=key, for_text=for_text))
+            if module.params['handle_read_only'] == 'ignore':
+                to_remove.append(real_key)
+        if key_info.write_only:
+            if module.params['handle_write_only'] == 'error':
+                module.fail_json(msg='Key "{key}" is write-only{for_text}, and handle_write_only=error.'.format(key=key, for_text=for_text))
+    for key in to_remove:
+        entry.pop(key)
     for key, field_info in path_info.fields.items():
         if field_info.required and key not in entry:
             module.fail_json(msg='Key "{key}" must be present{for_text}.'.format(key=key, for_text=for_text))
@@ -558,18 +743,29 @@ def prepare_for_add(entry, path_info):
     return new_entry
 
 
-def sync_list(module, api, path, path_info):
+def remove_rejected(data, path_info, restrict_data):
+    return [
+        entry for entry in data
+        if restrict_entry_accepted(entry, path_info, restrict_data)
+    ]
+
+
+def sync_list(module, api, path, path_info, restrict_data):
     handle_absent_entries = module.params['handle_absent_entries']
     handle_entries_content = module.params['handle_entries_content']
     if handle_absent_entries == 'remove':
         if handle_entries_content == 'ignore':
-            module.fail_json('For this path, handle_absent_entries=remove cannot be combined with handle_entries_content=ignore')
+            module.fail_json(
+                msg='For this path, handle_absent_entries=remove cannot be combined with handle_entries_content=ignore'
+            )
 
     stratify_keys = path_info.stratify_keys or ()
 
     data = module.params['data']
     stratified_data = defaultdict(list)
     for index, entry in enumerate(data):
+        if not restrict_entry_accepted(entry, path_info, restrict_data):
+            module.fail_json(msg='The element at index #{index} does not match `restrict`'.format(index=index + 1))
         for stratify_key in stratify_keys:
             if stratify_key not in entry:
                 module.fail_json(
@@ -590,6 +786,7 @@ def sync_list(module, api, path, path_info):
 
     old_data = get_api_data(api_path, path_info)
     old_data = remove_dynamic(old_data)
+    old_data = remove_rejected(old_data, path_info, restrict_data)
     stratified_old_data = defaultdict(list)
     for index, entry in enumerate(old_data):
         sks = tuple(entry[stratify_key] for stratify_key in stratify_keys)
@@ -622,6 +819,7 @@ def sync_list(module, api, path, path_info):
                 new_data.append((old_index, updated_entry))
                 new_entry['.id'] = old_entry['.id']
             else:
+                remove_read_only(new_entry, path_info)
                 create_list.append(new_entry)
 
         if handle_absent_entries == 'remove':
@@ -701,6 +899,7 @@ def sync_list(module, api, path, path_info):
         # For sake of completeness, retrieve the full new data:
         if modify_list or create_list or reorder_list:
             new_data = remove_dynamic(get_api_data(api_path, path_info))
+            new_data = remove_rejected(new_data, path_info, restrict_data)
 
     # Remove 'irrelevant' data
     for entry in old_data:
@@ -727,7 +926,7 @@ def sync_list(module, api, path, path_info):
     )
 
 
-def sync_with_primary_keys(module, api, path, path_info):
+def sync_with_primary_keys(module, api, path, path_info, restrict_data):
     primary_keys = path_info.primary_keys
 
     if path_info.fixed_entries:
@@ -739,6 +938,8 @@ def sync_with_primary_keys(module, api, path, path_info):
     data = module.params['data']
     new_data_by_key = OrderedDict()
     for index, entry in enumerate(data):
+        if not restrict_entry_accepted(entry, path_info, restrict_data):
+            module.fail_json(msg='The element at index #{index} does not match `restrict`'.format(index=index + 1))
         for primary_key in primary_keys:
             if primary_key not in entry:
                 module.fail_json(
@@ -770,6 +971,7 @@ def sync_with_primary_keys(module, api, path, path_info):
 
     old_data = get_api_data(api_path, path_info)
     old_data = remove_dynamic(old_data)
+    old_data = remove_rejected(old_data, path_info, restrict_data)
     old_data_by_key = OrderedDict()
     id_by_key = {}
     for entry in old_data:
@@ -814,6 +1016,7 @@ def sync_with_primary_keys(module, api, path, path_info):
                     for primary_key in primary_keys
                 ]),
             ))
+        remove_read_only(new_entry, path_info)
         create_list.append(new_entry)
         new_entry = new_entry.copy()
         for key in list(new_entry):
@@ -895,6 +1098,7 @@ def sync_with_primary_keys(module, api, path, path_info):
         # For sake of completeness, retrieve the full new data:
         if modify_list or create_list or reorder_list:
             new_data = remove_dynamic(get_api_data(api_path, path_info))
+            new_data = remove_rejected(new_data, path_info, restrict_data)
 
     # Remove 'irrelevant' data
     for entry in old_data:
@@ -921,7 +1125,9 @@ def sync_with_primary_keys(module, api, path, path_info):
     )
 
 
-def sync_single_value(module, api, path, path_info):
+def sync_single_value(module, api, path, path_info, restrict_data):
+    if module.params['restrict'] is not None:
+        module.fail_json(msg='The restrict option cannot be used with this path, since there is precisely one entry.')
     data = module.params['data']
     if len(data) != 1:
         module.fail_json(msg='Data must be a list with exactly one element.')
@@ -992,16 +1198,34 @@ def get_backend(path_info):
     return None
 
 
+def has_backend(versioned_path_info):
+    if not versioned_path_info.fully_understood:
+        return False
+
+    if versioned_path_info.unversioned is not None:
+        return get_backend(versioned_path_info.unversioned) is not None
+
+    if versioned_path_info.versioned is not None:
+        for dummy, dummy, unversioned in versioned_path_info.versioned:
+            if unversioned and not isinstance(unversioned, str) and get_backend(unversioned) is not None:
+                return True
+
+    return False
+
+
 def main():
-    path_choices = sorted([join_path(path) for path, path_info in PATHS.items() if get_backend(path_info) is not None])
+    path_choices = sorted([join_path(path) for path, versioned_path_info in PATHS.items() if has_backend(versioned_path_info)])
     module_args = dict(
         path=dict(type='str', required=True, choices=path_choices),
         data=dict(type='list', elements='dict', required=True),
         handle_absent_entries=dict(type='str', choices=['ignore', 'remove'], default='ignore'),
         handle_entries_content=dict(type='str', choices=['ignore', 'remove', 'remove_as_much_as_possible'], default='ignore'),
         ensure_order=dict(type='bool', default=False),
+        handle_read_only=dict(type='str', default='error', choices=['ignore', 'validate', 'error']),
+        handle_write_only=dict(type='str', default='create_only', choices=['create_only', 'always_update', 'error']),
     )
     module_args.update(api_argument_spec())
+    module_args.update(restrict_argument_spec())
 
     module = AnsibleModule(
         argument_spec=module_args,
@@ -1018,12 +1242,24 @@ def main():
     api = create_api(module)
 
     path = split_path(module.params['path'])
-    path_info = PATHS.get(tuple(path))
+    versioned_path_info = PATHS.get(tuple(path))
+    if versioned_path_info.needs_version:
+        api_version = get_api_version(api)
+        supported, not_supported_msg = versioned_path_info.provide_version(api_version)
+        if not supported:
+            msg = 'Path /{path} is not supported for API version {api_version}'.format(path='/'.join(path), api_version=api_version)
+            if not_supported_msg:
+                msg = '{0}: {1}'.format(msg, not_supported_msg)
+            module.fail_json(msg=msg)
+    path_info = versioned_path_info.get_data()
+
     backend = get_backend(path_info)
     if path_info is None or backend is None:
         module.fail_json(msg='Path /{path} is not yet supported'.format(path='/'.join(path)))
 
-    backend(module, api, path, path_info)
+    restrict_data = validate_and_prepare_restrict(module, path_info)
+
+    backend(module, api, path, path_info, restrict_data)
 
 
 if __name__ == '__main__':

plugins/modules/command.py

@@ -7,89 +7,77 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: command
 author: "Egor Zaitsev (@heuels)"
 short_description: Run commands on remote devices running MikroTik RouterOS
 description:
-  - Sends arbitrary commands to an RouterOS node and returns the results
-    read from the device. This module includes an
-    argument that will cause the module to wait for a specific condition
-    before returning or timing out if the condition is not met.
-  - The module always indicates a (changed) status. You can use
-    R(the changed_when task property,override_the_changed_result) to determine
-    whether a command task actually resulted in a change or not.
-notes:
-  - The module declares that it B(supports check mode). This is a bug and will
-    be changed in community.routeros 3.0.0.
+  - Sends arbitrary commands to an RouterOS node and returns the results read from the device. This module includes an argument
+    that will cause the module to wait for a specific condition before returning or timing out if the condition is not met.
+  - The module always indicates a (changed) status. You can use R(the changed_when task property,override_the_changed_result)
+    to determine whether a command task actually resulted in a change or not.
 extends_documentation_fragment:
   - community.routeros.attributes
 attributes:
   check_mode:
-    support: partial
+    support: none
     details:
-      - The module claims to support check mode, but it simply always executes the command.
+      - Before community.routeros 3.0.0, the module claimed to support check mode. It simply executed the command in check
+        mode.
   diff_mode:
     support: none
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: N/A
+    details:
+      - Whether the executed command is idempotent depends on the command.
 options:
   commands:
     description:
-      - List of commands to send to the remote RouterOS device over the
-        configured provider. The resulting output from the command
-        is returned. If the I(wait_for) argument is provided, the
-        module is not returned until the condition is satisfied or
-        the number of retries has expired.
+      - List of commands to send to the remote RouterOS device over the configured provider. The resulting output from the
+        command is returned. If the O(wait_for) argument is provided, the module is not returned until the condition is satisfied
+        or the number of retries has expired.
     required: true
     type: list
     elements: str
   wait_for:
     description:
-      - List of conditions to evaluate against the output of the
-        command. The task will wait for each condition to be true
-        before moving forward. If the conditional is not true
-        within the configured number of retries, the task fails.
-        See examples.
+      - List of conditions to evaluate against the output of the command. The task will wait for each condition to be true
+        before moving forward. If the conditional is not true within the configured number of retries, the task fails. See
+        examples.
     type: list
     elements: str
   match:
     description:
-      - The I(match) argument is used in conjunction with the
-        I(wait_for) argument to specify the match policy.  Valid
-        values are C(all) or C(any).  If the value is set to C(all)
-        then all conditionals in the wait_for must be satisfied.  If
-        the value is set to C(any) then only one of the values must be
-        satisfied.
+      - The O(match) argument is used in conjunction with the O(wait_for) argument to specify the match policy. Valid values
+        are V(all) or V(any). If the value is set to V(all) then all conditionals in the wait_for must be satisfied. If the
+        value is set to V(any) then only one of the values must be satisfied.
     default: all
     choices: ['any', 'all']
     type: str
   retries:
     description:
-      - Specifies the number of retries a command should by tried
-        before it is considered failed. The command is run on the
-        target device every retry and evaluated against the
-        I(wait_for) conditions.
+      - Specifies the number of retries a command should by tried before it is considered failed. The command is run on the
+        target device every retry and evaluated against the O(wait_for) conditions.
     default: 10
     type: int
   interval:
     description:
-      - Configures the interval in seconds to wait between retries
-        of the command. If the command does not pass the specified
-        conditions, the interval indicates how long to wait before
-        trying the command again.
+      - Configures the interval in seconds to wait between retries of the command. If the command does not pass the specified
+        conditions, the interval indicates how long to wait before trying the command again.
     default: 1
     type: int
 seealso:
   - ref: ansible_collections.community.routeros.docsite.ssh-guide
-    description: How to connect to RouterOS devices with SSH
+    description: How to connect to RouterOS devices with SSH.
   - ref: ansible_collections.community.routeros.docsite.quoting
-    description: How to quote and unquote commands and arguments
-'''
+    description: How to quote and unquote commands and arguments.
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Run command on remote devices
   community.routeros.command:
     commands: /system routerboard print
@@ -115,19 +103,19 @@ EXAMPLES = """
       - result[1] contains ether1
 """
 
-RETURN = """
+RETURN = r"""
 stdout:
-  description: The set of responses from the commands
+  description: The set of responses from the commands.
   returned: always apart from low level errors (such as action plugin)
   type: list
   sample: ['...', '...']
 stdout_lines:
-  description: The value of stdout split into a list
+  description: The value of stdout split into a list.
   returned: always apart from low level errors (such as action plugin)
   type: list
   sample: [['...', '...'], ['...'], ['...']]
 failed_conditions:
-  description: The list of conditionals that have failed
+  description: The list of conditionals that have failed.
   returned: failed
   type: list
   sample: ['...', '...']
@@ -165,7 +153,7 @@ def main():
     argument_spec.update(routeros_argument_spec)
 
     module = AnsibleModule(argument_spec=argument_spec,
-                           supports_check_mode=True)
+                           supports_check_mode=False)
 
     result = {'changed': False}
 

plugins/modules/facts.py

@@ -7,21 +7,19 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: facts
 author: "Egor Zaitsev (@heuels)"
 short_description: Collect facts from remote devices running MikroTik RouterOS
 description:
-  - Collects a base set of device facts from a remote device that
-    is running RouterOS.  This module prepends all of the
-    base network fact keys with C(ansible_net_<fact>).  The facts
-    module will always collect a base set of facts from the device
+  - Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the base
+    network fact keys with C(ansible_net_<fact>). The facts module will always collect a base set of facts from the device
     and can enable or disable collection of additional facts.
 extends_documentation_fragment:
   - community.routeros.attributes
   - community.routeros.attributes.facts
   - community.routeros.attributes.facts_module
+  - community.routeros.attributes.idempotent_not_modify_state
 attributes:
   platform:
     support: full
@@ -29,12 +27,10 @@ attributes:
 options:
   gather_subset:
     description:
-      - When supplied, this argument will restrict the facts collected
-        to a given subset.  Possible values for this argument include
-        C(all), C(hardware), C(config), C(interfaces), and C(routing).
-      - Can specify a list of values to include a larger subset.
-        Values can also be used with an initial C(!) to specify that a
-        specific subset should not be collected.
+      - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
+        include V(all), V(hardware), V(config), V(interfaces), and V(routing).
+      - Can specify a list of values to include a larger subset. Values can also be used with an initial V(!) to specify that
+        a specific subset should not be collected.
     required: false
     default:
       - '!config'
@@ -42,10 +38,11 @@ options:
     elements: str
 seealso:
   - ref: ansible_collections.community.routeros.docsite.ssh-guide
-    description: How to connect to RouterOS devices with SSH
-'''
+    description: How to connect to RouterOS devices with SSH.
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Collect all facts from the device
   community.routeros.facts:
     gather_subset: all
@@ -61,7 +58,7 @@ EXAMPLES = """
       - "!hardware"
 """
 
-RETURN = """
+RETURN = r"""
 ansible_facts:
   description: "Dictionary of IP geolocation facts for a host's IP address."
   returned: always
@@ -75,109 +72,109 @@ ansible_facts:
     # default
     ansible_net_model:
       description: The model name returned from the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_serialnum:
       description: The serial number of the remote device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_version:
       description: The operating system version running on the remote device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_hostname:
       description: The configured hostname of the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_arch:
       description: The CPU architecture of the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_uptime:
       description: The uptime of the device.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
     ansible_net_cpu_load:
       description: Current CPU load.
-      returned: I(gather_subset) contains C(default)
+      returned: O(gather_subset) contains V(default)
       type: str
 
     # hardware
     ansible_net_spacefree_mb:
       description: The available disk space on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: dict
     ansible_net_spacetotal_mb:
       description: The total disk space on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: dict
     ansible_net_memfree_mb:
       description: The available free memory on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: int
     ansible_net_memtotal_mb:
       description: The total memory on the remote device in MiB.
-      returned: I(gather_subset) contains C(hardware)
+      returned: O(gather_subset) contains V(hardware)
       type: int
 
     # config
     ansible_net_config:
       description: The current active config from the device.
-      returned: I(gather_subset) contains C(config)
+      returned: O(gather_subset) contains V(config)
       type: str
 
     ansible_net_config_nonverbose:
       description:
         - The current active config from the device in minimal form.
-        - This value is idempotent in the sense that if the facts module is run twice and the device's config
-          was not changed between the runs, the value is identical. This is achieved by running C(/export)
-          and stripping the timestamp from the comment in the first line.
-      returned: I(gather_subset) contains C(config)
+        - This value is idempotent in the sense that if the facts module is run twice and the device's config was not changed
+          between the runs, the value is identical. This is achieved by running C(/export) and stripping the timestamp from
+          the comment in the first line.
+      returned: O(gather_subset) contains V(config)
       type: str
       version_added: 1.2.0
 
     # interfaces
     ansible_net_all_ipv4_addresses:
       description: All IPv4 addresses configured on the device.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: list
     ansible_net_all_ipv6_addresses:
       description: All IPv6 addresses configured on the device.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: list
     ansible_net_interfaces:
       description: A hash of all interfaces running on the system.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: dict
     ansible_net_neighbors:
       description: The list of neighbors from the remote device.
-      returned: I(gather_subset) contains C(interfaces)
+      returned: O(gather_subset) contains V(interfaces)
       type: dict
 
     # routing
     ansible_net_bgp_peer:
       description: A dictionary with BGP peer information.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_bgp_vpnv4_route:
       description: A dictionary with BGP vpnv4 route information.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_bgp_instance:
       description: A dictionary with BGP instance information.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_route:
       description: A dictionary for routes in all routing tables.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_ospf_instance:
       description: A dictionary with OSPF instances.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
     ansible_net_ospf_neighbor:
       description: A dictionary with OSPF neighbors.
-      returned: I(gather_subset) contains C(routing)
+      returned: O(gather_subset) contains V(routing)
       type: dict
 """
 import re
@@ -311,7 +308,7 @@ class Config(FactsBase):
         '/export',
     ]
 
-    RM_DATE_RE = re.compile(r'^# [a-z0-9/][a-z0-9/]* [0-9:]* by RouterOS')
+    RM_DATE_RE = re.compile(r'^# [a-z0-9/-][a-z0-9/-]* [0-9:]* by RouterOS')
 
     def populate(self):
         super(Config, self).populate()
@@ -592,8 +589,6 @@ FACT_SUBSETS = dict(
 
 VALID_SUBSETS = frozenset(FACT_SUBSETS.keys())
 
-warnings = list()
-
 
 def main():
     """main entry point for module execution
@@ -656,7 +651,7 @@ def main():
         key = 'ansible_net_%s' % key
         ansible_facts[key] = value
 
-    module.exit_json(ansible_facts=ansible_facts, warnings=warnings)
+    module.exit_json(ansible_facts=ansible_facts)
 
 
 if __name__ == '__main__':

plugins/terminal/routeros.py

@@ -31,7 +31,9 @@ class TerminalModule(TerminalBase):
 
     terminal_stdout_re = [
         re.compile(br"\x1b<"),
-        re.compile(br"\[[\w\-\.]+\@[\w\s\-\.\/]+\] ?(<SAFE)?> ?$"),
+        re.compile(
+            br"((\[[\w\-\.]+\@)|(\r\<(([\w\-\.]*\@)|)))"
+            br"[\w\s\-\.\/]+\] ?(<SAFE)?> ?$"),
         re.compile(br"Please press \"Enter\" to continue!"),
         re.compile(br"Do you want to see the software license\? \[Y\/n\]: ?"),
     ]

tests/ee/roles/filter_quoting/tasks/main.yml

@@ -22,7 +22,7 @@
   assert:
     that:
       - >-
-        result.msg == "Unexpected end of string during escaped parameter"
+        "Unexpected end of string during escaped parameter" in result.msg
 
 - name: "Test quote_argument filter"
   assert:

tests/integration/requirements.yml

@@ -4,4 +4,4 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 collections:
-- ansible.netcommon
+  - ansible.netcommon

tests/integration/targets/filter_quoting/tasks/main.yml

@@ -22,7 +22,7 @@
   assert:
     that:
       - >-
-        result.msg == "Unexpected end of string during escaped parameter"
+        "Unexpected end of string during escaped parameter" in result.msg
 
 - name: "Test quote_argument filter"
   assert:

tests/sanity/extra/extra-docs.json

@@ -1,13 +0,0 @@
-{
-    "include_symlinks": false,
-    "prefixes": [
-        "docs/docsite/",
-        "plugins/",
-        "roles/"
-    ],
-    "output": "path-line-column-message",
-    "requirements": [
-        "ansible-core",
-        "antsibull-docs"
-    ]
-}

tests/sanity/extra/extra-docs.py

@@ -1,29 +0,0 @@
-#!/usr/bin/env python
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-"""Check extra collection docs with antsibull-docs."""
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-import os
-import sys
-import subprocess
-
-
-def main():
-    """Main entry point."""
-    env = os.environ.copy()
-    suffix = ':{env}'.format(env=env["ANSIBLE_COLLECTIONS_PATH"]) if 'ANSIBLE_COLLECTIONS_PATH' in env else ''
-    env['ANSIBLE_COLLECTIONS_PATH'] = '{root}{suffix}'.format(root=os.path.dirname(os.path.dirname(os.path.dirname(os.getcwd()))), suffix=suffix)
-    p = subprocess.run(
-        ['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--disallow-semantic-markup', '--skip-rstcheck', '.'],
-        env=env,
-        check=False,
-    )
-    if p.returncode not in (0, 3):
-        print('{0}:0:0: unexpected return code {1}'.format(sys.argv[0], p.returncode))
-
-
-if __name__ == '__main__':
-    main()

tests/sanity/extra/licenses.json

@@ -1,4 +0,0 @@
-{
-    "include_symlinks": false,
-    "output": "path-message"
-}

tests/sanity/extra/licenses.py

@@ -1,110 +0,0 @@
-#!/usr/bin/env python
-# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-"""Prevent files without a correct license identifier from being added to the source tree."""
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-import os
-import glob
-import sys
-
-
-def format_license_list(licenses):
-    if not licenses:
-        return '(empty)'
-    return ', '.join(['"%s"' % license for license in licenses])
-
-
-def find_licenses(filename, relax=False):
-    spdx_license_identifiers = []
-    other_license_identifiers = []
-    has_copyright = False
-    try:
-        with open(filename, 'r', encoding='utf-8') as f:
-            for line in f:
-                line = line.rstrip()
-                if 'Copyright ' in line:
-                    has_copyright = True
-                if 'Copyright: ' in line:
-                    print('%s: found copyright line with "Copyright:". Please remove the colon.' % (filename, ))
-                if 'SPDX-FileCopyrightText: ' in line:
-                    has_copyright = True
-                idx = line.find('SPDX-License-Identifier: ')
-                if idx >= 0:
-                    lic_id = line[idx + len('SPDX-License-Identifier: '):]
-                    spdx_license_identifiers.extend(lic_id.split(' OR '))
-                if 'GNU General Public License' in line:
-                    if 'v3.0+' in line:
-                        other_license_identifiers.append('GPL-3.0-or-later')
-                    if 'version 3 or later' in line:
-                        other_license_identifiers.append('GPL-3.0-or-later')
-                if 'Simplified BSD License' in line:
-                    other_license_identifiers.append('BSD-2-Clause')
-                if 'Apache License 2.0' in line:
-                    other_license_identifiers.append('Apache-2.0')
-                if 'PSF License' in line or 'Python-2.0' in line:
-                    other_license_identifiers.append('PSF-2.0')
-                if 'MIT License' in line:
-                    other_license_identifiers.append('MIT')
-    except Exception as exc:
-        print('%s: error while processing file: %s' % (filename, exc))
-    if len(set(spdx_license_identifiers)) < len(spdx_license_identifiers):
-        print('%s: found identical SPDX-License-Identifier values' % (filename, ))
-    if other_license_identifiers and set(other_license_identifiers) != set(spdx_license_identifiers):
-        print('%s: SPDX-License-Identifier yielded the license list %s, while manual guessing yielded the license list %s' % (
-            filename, format_license_list(spdx_license_identifiers), format_license_list(other_license_identifiers)))
-    if not has_copyright and not relax:
-        print('%s: found no copyright notice' % (filename, ))
-    return sorted(spdx_license_identifiers)
-
-
-def main():
-    """Main entry point."""
-    paths = sys.argv[1:] or sys.stdin.read().splitlines()
-
-    # The following paths are allowed to have no license identifier
-    no_comments_allowed = [
-        'changelogs/fragments/*.yml',
-        'changelogs/fragments/*.yaml',
-    ]
-
-    # These files are completely ignored
-    ignore_paths = [
-        '.ansible-test-timeout.json',
-        '.reuse/dep5',
-        'LICENSES/*.txt',
-        'COPYING',
-    ]
-
-    no_comments_allowed = [fn for pattern in no_comments_allowed for fn in glob.glob(pattern)]
-    ignore_paths = [fn for pattern in ignore_paths for fn in glob.glob(pattern)]
-
-    valid_licenses = [license_file[len('LICENSES/'):-len('.txt')] for license_file in glob.glob('LICENSES/*.txt')]
-
-    for path in paths:
-        if path.startswith('./'):
-            path = path[2:]
-        if path in ignore_paths or path.startswith('tests/output/'):
-            continue
-        if os.stat(path).st_size == 0:
-            continue
-        if not path.endswith('.license') and os.path.exists(path + '.license'):
-            path = path + '.license'
-        valid_licenses_for_path = valid_licenses
-        if path.startswith('plugins/') and not path.startswith(('plugins/modules/', 'plugins/module_utils/')):
-            valid_licenses_for_path = [license for license in valid_licenses if license == 'GPL-3.0-or-later']
-        licenses = find_licenses(path, relax=path in no_comments_allowed)
-        if not licenses:
-            if path not in no_comments_allowed:
-                print('%s: must have at least one license' % (path, ))
-        else:
-            for license in licenses:
-                if license not in valid_licenses_for_path:
-                    print('%s: found not allowed license "%s", must be one of %s' % (
-                        path, license, format_license_list(valid_licenses_for_path)))
-
-
-if __name__ == '__main__':
-    main()

tests/sanity/extra/no-unwanted-files.json

@@ -1,7 +0,0 @@
-{
-    "include_symlinks": true,
-    "prefixes": [
-        "plugins/"
-    ],
-    "output": "path-message"
-}

tests/sanity/extra/no-unwanted-files.py

@@ -1,58 +0,0 @@
-#!/usr/bin/env python
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-"""Prevent unwanted files from being added to the source tree."""
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-import os
-import os.path
-import sys
-
-
-def main():
-    """Main entry point."""
-    paths = sys.argv[1:] or sys.stdin.read().splitlines()
-
-    allowed_extensions = (
-        '.cs',
-        '.ps1',
-        '.psm1',
-        '.py',
-    )
-
-    skip_paths = set([
-    ])
-
-    skip_directories = (
-    )
-
-    yaml_directories = (
-        'plugins/test/',
-        'plugins/filter/',
-    )
-
-    for path in paths:
-        if path in skip_paths:
-            continue
-
-        if any(path.startswith(skip_directory) for skip_directory in skip_directories):
-            continue
-
-        if os.path.islink(path):
-            print('%s: is a symbolic link' % (path, ))
-        elif not os.path.isfile(path):
-            print('%s: is not a regular file' % (path, ))
-
-        ext = os.path.splitext(path)[1]
-
-        if ext in ('.yml', ) and any(path.startswith(yaml_directory) for yaml_directory in yaml_directories):
-            continue
-
-        if ext not in allowed_extensions:
-            print('%s: extension must be one of: %s' % (path, ', '.join(allowed_extensions)))
-
-
-if __name__ == '__main__':
-    main()

tests/sanity/extra/update-docs.json

@@ -1,8 +0,0 @@
-{
-    "include_symlinks": false,
-    "prefixes": [
-        "docs/docsite/rst/api-guide.rst",
-        "plugins/modules/"
-    ],
-    "output": "path-line-column-message"
-}

tests/sanity/extra/update-docs.py

@@ -1,21 +0,0 @@
-#!/usr/bin/env python
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-"""Check whether update-docs.py modifies something."""
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-import sys
-import subprocess
-
-
-def main():
-    """Main entry point."""
-    p = subprocess.run(['./update-docs.py'], check=False)
-    if p.returncode not in (0, 1):
-        print('{0}:0:0: unexpected return code {1}'.format(sys.argv[0], p.returncode))
-
-
-if __name__ == '__main__':
-    main()

tests/sanity/ignore-2.10.txt

@@ -1,6 +1,9 @@
-update-docs.py compile-2.6
-update-docs.py compile-2.7
-update-docs.py compile-3.5
-update-docs.py future-import-boilerplate
-update-docs.py metaclass-boilerplate
-update-docs.py shebang
+docs/docsite/rst/api-guide.rst rstcheck
+docs/docsite/rst/quoting.rst rstcheck
+docs/docsite/rst/ssh-guide.rst rstcheck
+tests/update-docs.py compile-2.6
+tests/update-docs.py compile-2.7
+tests/update-docs.py compile-3.5
+tests/update-docs.py future-import-boilerplate
+tests/update-docs.py metaclass-boilerplate
+tests/update-docs.py shebang

tests/sanity/ignore-2.11.txt

@@ -1,6 +1,6 @@
-update-docs.py compile-2.6
-update-docs.py compile-2.7
-update-docs.py compile-3.5
-update-docs.py future-import-boilerplate
-update-docs.py metaclass-boilerplate
-update-docs.py shebang
+tests/update-docs.py compile-2.6
+tests/update-docs.py compile-2.7
+tests/update-docs.py compile-3.5
+tests/update-docs.py future-import-boilerplate
+tests/update-docs.py metaclass-boilerplate
+tests/update-docs.py shebang

tests/sanity/ignore-2.12.txt

@@ -1 +1 @@
-update-docs.py shebang
+tests/update-docs.py shebang

tests/sanity/ignore-2.13.txt

@@ -1 +1 @@
-update-docs.py shebang
+tests/update-docs.py shebang

tests/sanity/ignore-2.14.txt

@@ -1 +1 @@
-update-docs.py shebang
+tests/update-docs.py shebang

tests/sanity/ignore-2.15.txt

@@ -1 +1 @@
-update-docs.py shebang
+tests/update-docs.py shebang

tests/sanity/ignore-2.16.txt

@@ -1 +1 @@
-update-docs.py shebang
+tests/update-docs.py shebang

tests/sanity/ignore-2.17.txt

@@ -0,0 +1 @@
+tests/update-docs.py shebang

tests/sanity/ignore-2.18.txt

@@ -0,0 +1 @@
+tests/update-docs.py shebang

tests/sanity/ignore-2.19.txt

@@ -0,0 +1 @@
+tests/update-docs.py shebang

tests/sanity/ignore-2.20.txt

@@ -0,0 +1,4 @@
+plugins/modules/api_facts.py pylint:ansible-bad-import-from
+plugins/modules/command.py pylint:ansible-bad-import-from
+plugins/modules/facts.py pylint:ansible-bad-import-from
+tests/update-docs.py shebang

tests/sanity/ignore-2.20.txt.license

@@ -1,3 +1,3 @@
 GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 SPDX-License-Identifier: GPL-3.0-or-later
-SPDX-FileCopyrightText: 2022, Felix Fontein <felix@fontein.de>
+SPDX-FileCopyrightText: Ansible Project

tests/sanity/ignore-2.9.txt

@@ -1,6 +1,9 @@
-update-docs.py compile-2.6
-update-docs.py compile-2.7
-update-docs.py compile-3.5
-update-docs.py future-import-boilerplate
-update-docs.py metaclass-boilerplate
-update-docs.py shebang
+docs/docsite/rst/api-guide.rst rstcheck
+docs/docsite/rst/quoting.rst rstcheck
+docs/docsite/rst/ssh-guide.rst rstcheck
+tests/update-docs.py compile-2.6
+tests/update-docs.py compile-2.7
+tests/update-docs.py compile-3.5
+tests/update-docs.py future-import-boilerplate
+tests/update-docs.py metaclass-boilerplate
+tests/update-docs.py shebang

tests/unit/compat/builtins.py

@@ -1,20 +0,0 @@
-# Copyright (c) 2014, Toshio Kuratomi <tkuratomi@ansible.com>
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-#
-# Compat for python2.7
-#
-
-# One unittest needs to import builtins via __import__() so we need to have
-# the string that represents it
-try:
-    import __builtin__  # noqa: F401, pylint: disable=unused-import
-except ImportError:
-    BUILTINS = 'builtins'
-else:
-    BUILTINS = '__builtin__'

tests/unit/compat/mock.py

@@ -1,109 +0,0 @@
-# Copyright (c) 2014, Toshio Kuratomi <tkuratomi@ansible.com>
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-'''
-Compat module for Python3.x's unittest.mock module
-'''
-import sys
-
-# Python 2.7
-
-# Note: Could use the pypi mock library on python3.x as well as python2.x.  It
-# is the same as the python3 stdlib mock library
-
-try:
-    # Allow wildcard import because we really do want to import all of mock's
-    # symbols into this compat shim
-    # pylint: disable=wildcard-import,unused-wildcard-import
-    from unittest.mock import *  # noqa: F401, pylint: disable=unused-import
-except ImportError:
-    # Python 2
-    # pylint: disable=wildcard-import,unused-wildcard-import
-    try:
-        from mock import *  # noqa: F401, pylint: disable=unused-import
-    except ImportError:
-        print('You need the mock library installed on python2.x to run tests')
-
-
-# Prior to 3.4.4, mock_open cannot handle binary read_data
-if sys.version_info >= (3,) and sys.version_info < (3, 4, 4):
-    file_spec = None
-
-    def _iterate_read_data(read_data):
-        # Helper for mock_open:
-        # Retrieve lines from read_data via a generator so that separate calls to
-        # readline, read, and readlines are properly interleaved
-        sep = b'\n' if isinstance(read_data, bytes) else '\n'
-        data_as_list = [l + sep for l in read_data.split(sep)]
-
-        if data_as_list[-1] == sep:
-            # If the last line ended in a newline, the list comprehension will have an
-            # extra entry that's just a newline.  Remove this.
-            data_as_list = data_as_list[:-1]
-        else:
-            # If there wasn't an extra newline by itself, then the file being
-            # emulated doesn't have a newline to end the last line  remove the
-            # newline that our naive format() added
-            data_as_list[-1] = data_as_list[-1][:-1]
-
-        for line in data_as_list:
-            yield line
-
-    def mock_open(mock=None, read_data=''):
-        """
-        A helper function to create a mock to replace the use of `open`. It works
-        for `open` called directly or used as a context manager.
-
-        The `mock` argument is the mock object to configure. If `None` (the
-        default) then a `MagicMock` will be created for you, with the API limited
-        to methods or attributes available on standard file handles.
-
-        `read_data` is a string for the `read` methoddline`, and `readlines` of the
-        file handle to return.  This is an empty string by default.
-        """
-        def _readlines_side_effect(*args, **kwargs):
-            if handle.readlines.return_value is not None:
-                return handle.readlines.return_value
-            return list(_data)
-
-        def _read_side_effect(*args, **kwargs):
-            if handle.read.return_value is not None:
-                return handle.read.return_value
-            return type(read_data)().join(_data)
-
-        def _readline_side_effect():
-            if handle.readline.return_value is not None:
-                while True:
-                    yield handle.readline.return_value
-            for line in _data:
-                yield line
-
-        global file_spec
-        if file_spec is None:
-            import _io
-            file_spec = list(set(dir(_io.TextIOWrapper)).union(set(dir(_io.BytesIO))))
-
-        if mock is None:
-            mock = MagicMock(name='open', spec=open)
-
-        handle = MagicMock(spec=file_spec)
-        handle.__enter__.return_value = handle
-
-        _data = _iterate_read_data(read_data)
-
-        handle.write.return_value = None
-        handle.read.return_value = None
-        handle.readline.return_value = None
-        handle.readlines.return_value = None
-
-        handle.read.side_effect = _read_side_effect
-        handle.readline.side_effect = _readline_side_effect()
-        handle.readlines.side_effect = _readlines_side_effect
-
-        mock.return_value = handle
-        return mock

tests/unit/compat/unittest.py

@@ -1,25 +0,0 @@
-# Copyright (c) 2014, Toshio Kuratomi <tkuratomi@ansible.com>
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
-'''
-Compat module for Python2.7's unittest module
-'''
-
-import sys
-
-# Allow wildcard import because we really do want to import all of
-# unittests's symbols into this compat shim
-# pylint: disable=wildcard-import,unused-wildcard-import
-if sys.version_info < (2, 7):
-    try:
-        # Need unittest2 on python2.6
-        from unittest2 import *  # noqa: F401, pylint: disable=unused-import
-    except ImportError:
-        print('You need unittest2 installed on python2.6.x to run tests')
-else:
-    from unittest import *  # noqa: F401, pylint: disable=unused-import

tests/unit/plugins/module_utils/test__api_data.py

@@ -10,7 +10,7 @@ __metaclass__ = type
 import pytest
 
 from ansible_collections.community.routeros.plugins.module_utils._api_data import (
-    APIData,
+    VersionedAPIData,
     KeyInfo,
     split_path,
     join_path,
@@ -19,7 +19,7 @@ from ansible_collections.community.routeros.plugins.module_utils._api_data impor
 
 def test_api_data_errors():
     with pytest.raises(ValueError) as exc:
-        APIData()
+        VersionedAPIData()
     assert exc.value.args[0] == 'fields must be provided'
 
     values = [
@@ -33,39 +33,39 @@ def test_api_data_errors():
     for index, (param, param_value) in enumerate(values):
         for param2, param2_value in values[index + 1:]:
             with pytest.raises(ValueError) as exc:
-                APIData(**{param: param_value, param2: param2_value})
+                VersionedAPIData(**{param: param_value, param2: param2_value})
             assert exc.value.args[0] == 'primary_keys, stratify_keys, has_identifier, single_value, and unknown_mechanism are mutually exclusive'
 
     with pytest.raises(ValueError) as exc:
-        APIData(unknown_mechanism=True, fully_understood=True)
+        VersionedAPIData(unknown_mechanism=True, fully_understood=True)
     assert exc.value.args[0] == 'unknown_mechanism and fully_understood cannot be combined'
 
     with pytest.raises(ValueError) as exc:
-        APIData(unknown_mechanism=True, fixed_entries=True)
+        VersionedAPIData(unknown_mechanism=True, fixed_entries=True)
     assert exc.value.args[0] == 'fixed_entries can only be used with primary_keys'
 
     with pytest.raises(ValueError) as exc:
-        APIData(primary_keys=['foo'], fields={})
+        VersionedAPIData(primary_keys=['foo'], fields={})
     assert exc.value.args[0] == 'Primary key foo must be in fields!'
 
     with pytest.raises(ValueError) as exc:
-        APIData(stratify_keys=['foo'], fields={})
+        VersionedAPIData(stratify_keys=['foo'], fields={})
     assert exc.value.args[0] == 'Stratify key foo must be in fields!'
 
     with pytest.raises(ValueError) as exc:
-        APIData(required_one_of=['foo'], fields={})
+        VersionedAPIData(required_one_of=['foo'], fields={})
     assert exc.value.args[0] == 'Require one of element at index #1 must be a list!'
 
     with pytest.raises(ValueError) as exc:
-        APIData(required_one_of=[['foo']], fields={})
+        VersionedAPIData(required_one_of=[['foo']], fields={})
     assert exc.value.args[0] == 'Require one of key foo must be in fields!'
 
     with pytest.raises(ValueError) as exc:
-        APIData(mutually_exclusive=['foo'], fields={})
+        VersionedAPIData(mutually_exclusive=['foo'], fields={})
     assert exc.value.args[0] == 'Mutually exclusive element at index #1 must be a list!'
 
     with pytest.raises(ValueError) as exc:
-        APIData(mutually_exclusive=[['foo']], fields={})
+        VersionedAPIData(mutually_exclusive=[['foo']], fields={})
     assert exc.value.args[0] == 'Mutually exclusive key foo must be in fields!'
 
 
@@ -99,8 +99,16 @@ def test_key_info_errors():
         KeyInfo(remove_value='')
     assert exc.value.args[0] == 'remove_value can only be specified if can_disable=True'
 
+    with pytest.raises(ValueError) as exc:
+        KeyInfo(read_only=True, write_only=True)
+    assert exc.value.args[0] == 'read_only and write_only cannot be used at the same time'
 
-SPLITTED_PATHS = [
+    with pytest.raises(ValueError) as exc:
+        KeyInfo(read_only=True, default=0)
+    assert exc.value.args[0] == 'read_only can not be combined with can_disable, remove_value, absent_value, default, or required'
+
+
+SPLIT_PATHS = [
     ('', [], ''),
     ('  ip  ', ['ip'], 'ip'),
     ('ip', ['ip'], 'ip'),
@@ -108,7 +116,7 @@ SPLITTED_PATHS = [
 ]
 
 
-@pytest.mark.parametrize("joined_input, splitted, joined_output", SPLITTED_PATHS)
-def test_join_split_path(joined_input, splitted, joined_output):
-    assert split_path(joined_input) == splitted
-    assert join_path(splitted) == joined_output
+@pytest.mark.parametrize("joined_input, split, joined_output", SPLIT_PATHS)
+def test_join_split_path(joined_input, split, joined_output):
+    assert split_path(joined_input) == split
+    assert join_path(split) == joined_output

tests/unit/plugins/module_utils/test__api_helper.py

@@ -0,0 +1,377 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2021, Felix Fontein (@felixfontein) <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+import re
+import sys
+
+import pytest
+
+from ansible_collections.community.routeros.plugins.module_utils._api_data import (
+    PATHS,
+)
+
+from ansible_collections.community.routeros.plugins.module_utils._api_helper import (
+    _value_to_str,
+    _test_rule_except_invert,
+    validate_and_prepare_restrict,
+    restrict_entry_accepted,
+)
+
+
+VALUE_TO_STR = [
+    (None, None),
+    ('', u''),
+    ('foo', u'foo'),
+    (True, u'true'),
+    (False, u'false'),
+    ([], u'[]'),
+    ({}, u'{}'),
+    (1, u'1'),
+    (-42, u'-42'),
+    (1.5, u'1.5'),
+    (1.0, u'1.0'),
+]
+
+
+@pytest.mark.parametrize("value, expected", VALUE_TO_STR)
+def test_value_to_str(value, expected):
+    result = _value_to_str(value)
+    print(repr(result))
+    assert result == expected
+
+
+TEST_RULE_EXCEPT_INVERT = [
+    (
+        None,
+        {
+            'field': u'foo',
+            'match_disabled': False,
+            'invert': False,
+        },
+        False,
+    ),
+    (
+        None,
+        {
+            'field': u'foo',
+            'match_disabled': True,
+            'invert': False,
+        },
+        True,
+    ),
+    (
+        1,
+        {
+            'field': u'foo',
+            'match_disabled': False,
+            'invert': False,
+            'values': [1],
+        },
+        True,
+    ),
+    (
+        1,
+        {
+            'field': u'foo',
+            'match_disabled': False,
+            'invert': False,
+            'values': ['1'],
+        },
+        False,
+    ),
+    (
+        1,
+        {
+            'field': u'foo',
+            'match_disabled': False,
+            'invert': False,
+            'regex': re.compile(u'^1$'),
+            'regex_source': u'^1$',
+        },
+        True,
+    ),
+    (
+        1.10,
+        {
+            'field': u'foo',
+            'match_disabled': False,
+            'invert': False,
+            'regex': re.compile(u'^1\\.1$'),
+            'regex_source': u'^1\\.1$',
+        },
+        True,
+    ),
+    (
+        10,
+        {
+            'field': u'foo',
+            'match_disabled': False,
+            'invert': False,
+            'regex': re.compile(u'^1$'),
+            'regex_source': u'^1$',
+        },
+        False,
+    ),
+]
+
+
+@pytest.mark.parametrize("value, rule, expected", TEST_RULE_EXCEPT_INVERT)
+def test_rule_except_invert(value, rule, expected):
+    result = _test_rule_except_invert(value, rule)
+    print(repr(result))
+    assert result == expected
+
+
+_test_path = PATHS[('ip', 'firewall', 'filter')]
+_test_path.provide_version('7.0')
+TEST_PATH = _test_path.get_data()
+
+
+class FailJsonExc(Exception):
+    def __init__(self, msg, kwargs):
+        self.msg = msg
+        self.kwargs = kwargs
+
+
+class FakeModule(object):
+    def __init__(self, restrict_value):
+        self.params = {
+            'restrict': restrict_value,
+        }
+
+    def fail_json(self, msg, **kwargs):
+        raise FailJsonExc(msg, kwargs)
+
+
+TEST_VALIDATE_AND_PREPARE_RESTRICT = [
+    (
+        [{
+            'field': u'chain',
+            'match_disabled': False,
+            'values': None,
+            'regex': None,
+            'invert': False,
+        }],
+        [{
+            'field': u'chain',
+            'match_disabled': False,
+            'invert': False,
+        }],
+    ),
+    (
+        [{
+            'field': u'comment',
+            'match_disabled': True,
+            'values': None,
+            'regex': None,
+            'invert': False,
+        }],
+        [{
+            'field': u'comment',
+            'match_disabled': True,
+            'invert': False,
+        }],
+    ),
+    (
+        [{
+            'field': u'comment',
+            'match_disabled': False,
+            'values': None,
+            'regex': None,
+            'invert': True,
+        }],
+        [{
+            'field': u'comment',
+            'match_disabled': False,
+            'invert': True,
+        }],
+    ),
+]
+
+if sys.version_info >= (2, 7, 17):
+    # Somewhere between Python 2.7.15 (used by Ansible 3.9) and 2.7.17 (used by ansible-base 2.10)
+    # something changed with ``==`` for ``re.Pattern``, at least for some patterns
+    # (my guess is: for ``re.compile(u'')``)
+    TEST_VALIDATE_AND_PREPARE_RESTRICT.extend([
+        (
+            [
+                {
+                    'field': u'comment',
+                    'match_disabled': False,
+                    'values': [],
+                    'regex': None,
+                    'invert': False,
+                },
+                {
+                    'field': u'comment',
+                    'match_disabled': False,
+                    'values': [None, 1, 42.0, True, u'foo', [], {}],
+                    'regex': None,
+                    'invert': False,
+                },
+                {
+                    'field': u'chain',
+                    'match_disabled': False,
+                    'values': None,
+                    'regex': u'',
+                    'invert': True,
+                },
+                {
+                    'field': u'chain',
+                    'match_disabled': False,
+                    'values': None,
+                    'regex': u'foo',
+                    'invert': False,
+                },
+            ],
+            [
+                {
+                    'field': u'comment',
+                    'match_disabled': False,
+                    'invert': False,
+                    'values': [],
+                },
+                {
+                    'field': u'comment',
+                    'match_disabled': False,
+                    'invert': False,
+                    'values': [None, 1, 42.0, True, u'foo', [], {}],
+                },
+                {
+                    'field': u'chain',
+                    'match_disabled': False,
+                    'invert': True,
+                    'regex': re.compile(u''),
+                    'regex_source': u'',
+                },
+                {
+                    'field': u'chain',
+                    'match_disabled': False,
+                    'invert': False,
+                    'regex': re.compile(u'foo'),
+                    'regex_source': u'foo',
+                },
+            ],
+        ),
+    ])
+
+
+@pytest.mark.parametrize("restrict_value, expected", TEST_VALIDATE_AND_PREPARE_RESTRICT)
+def test_validate_and_prepare_restrict(restrict_value, expected):
+    fake_module = FakeModule(restrict_value)
+    result = validate_and_prepare_restrict(fake_module, TEST_PATH)
+    print(repr(result))
+    assert result == expected
+
+
+TEST_VALIDATE_AND_PREPARE_RESTRICT_FAIL = [
+    (
+        [{
+            'field': u'!foo',
+            'match_disabled': False,
+            'values': None,
+            'regex': None,
+            'invert': False,
+        }],
+        ['restrict: the field name "!foo" must not start with "!"'],
+    ),
+    (
+        [{
+            'field': u'foo',
+            'match_disabled': False,
+            'values': None,
+            'regex': None,
+            'invert': False,
+        }],
+        ['restrict: the field "foo" does not exist for this path'],
+    ),
+    (
+        [{
+            'field': u'chain',
+            'match_disabled': False,
+            'values': None,
+            'regex': u'(',
+            'invert': False,
+        }],
+        [
+            'restrict: invalid regular expression "(": missing ), unterminated subpattern at position 0',
+            'restrict: invalid regular expression "(": unbalanced parenthesis',
+        ]
+    ),
+]
+
+
+@pytest.mark.parametrize("restrict_value, expected", TEST_VALIDATE_AND_PREPARE_RESTRICT_FAIL)
+def test_validate_and_prepare_restrict_fail(restrict_value, expected):
+    fake_module = FakeModule(restrict_value)
+    with pytest.raises(FailJsonExc) as exc:
+        validate_and_prepare_restrict(fake_module, TEST_PATH)
+    print(repr(exc.value.msg))
+    assert exc.value.msg in expected
+
+
+TEST_RESTRICT_ENTRY_ACCEPTED = [
+    (
+        {
+            'chain': 'input',
+        },
+        [
+            {
+                'field': u'chain',
+                'match_disabled': False,
+                'invert': False,
+            },
+        ],
+        False,
+    ),
+    (
+        {
+            'chain': 'input',
+        },
+        [
+            {
+                'field': u'chain',
+                'match_disabled': False,
+                'invert': True,
+            },
+        ],
+        True,
+    ),
+    (
+        {
+            'comment': 'foo',
+        },
+        [
+            {
+                'field': u'comment',
+                'match_disabled': True,
+                'invert': False,
+            },
+        ],
+        False,
+    ),
+    (
+        {},
+        [
+            {
+                'field': u'comment',
+                'match_disabled': True,
+                'invert': False,
+            },
+        ],
+        True,
+    ),
+]
+
+
+@pytest.mark.parametrize("entry, restrict_data, expected", TEST_RESTRICT_ENTRY_ACCEPTED)
+def test_restrict_entry_accepted(entry, restrict_data, expected):
+    result = restrict_entry_accepted(entry, TEST_PATH, restrict_data)
+    print(repr(result))
+    assert result == expected

tests/unit/plugins/modules/fake_api.py

@@ -9,6 +9,9 @@ __metaclass__ = type
 from ansible_collections.community.routeros.plugins.module_utils._api_data import PATHS
 
 
+FAKE_ROS_VERSION = '7.5.0'
+
+
 class FakeLibRouterosError(Exception):
     def __init__(self, message):
         self.message = message
@@ -16,7 +19,7 @@ class FakeLibRouterosError(Exception):
 
 
 class TrapError(FakeLibRouterosError):
-    def __init__(self, message="failure: already have interface with such name"):
+    def __init__(self, message='failure: already have interface with such name'):
         super(TrapError, self).__init__(message)
 
 
@@ -133,7 +136,9 @@ def _normalize_entry(entry, path_info, on_create=False):
 
 
 def massage_expected_result_data(values, path, keep_all=False, remove_dynamic=False, remove_builtin=False):
-    path_info = PATHS[path]
+    versioned_path_info = PATHS[path]
+    versioned_path_info.provide_version(FAKE_ROS_VERSION)
+    path_info = versioned_path_info.get_data()
     if remove_dynamic:
         values = [entry for entry in values if not entry.get('dynamic', False)]
     if remove_builtin:
@@ -155,15 +160,25 @@ def massage_expected_result_data(values, path, keep_all=False, remove_dynamic=Fa
 class Path(object):
     def __init__(self, path, initial_values, read_only=False):
         self._path = path
-        self._path_info = PATHS[path]
+        versioned_path_info = PATHS[path]
+        versioned_path_info.provide_version(FAKE_ROS_VERSION)
+        self._path_info = versioned_path_info.get_data()
         self._values = [entry.copy() for entry in initial_values]
         for entry in self._values:
             _normalize_entry(entry, self._path_info)
         self._new_id_counter = 0
         self._read_only = read_only
 
+    def _sanitize(self, entry):
+        entry = entry.copy()
+        for field, field_info in self._path_info.fields.items():
+            if field in entry:
+                if field_info.write_only:
+                    del entry[field]
+        return entry
+
     def __iter__(self):
-        return [entry.copy() for entry in self._values].__iter__()
+        return [self._sanitize(entry) for entry in self._values].__iter__()
 
     def _find_id(self, id, required=False):
         for index, entry in enumerate(self._values):
@@ -187,7 +202,15 @@ class Path(object):
         entry = {
             '.id': id,
         }
-        entry.update(kwargs)
+        for field, value in kwargs.items():
+            if field.startswith('!'):
+                field = field[1:]
+            if field not in self._path_info.fields:
+                raise ValueError('Trying to set unknown field "{field}"'.format(field=field))
+            field_info = self._path_info.fields[field]
+            if field_info.read_only:
+                raise ValueError('Trying to set read-only field "{field}"'.format(field=field))
+            entry[field] = value
         _normalize_entry(entry, self._path_info, on_create=True)
         self._values.append(entry)
         return id
@@ -216,6 +239,16 @@ class Path(object):
         entry = self._values[index]
         if entry.get('dynamic', False) or entry.get('builtin', False):
             raise Exception('Trying to update a dynamic or builtin entry')
+        for field in kwargs:
+            if field == '.id':
+                continue
+            if field.startswith('!'):
+                field = field[1:]
+            if field not in self._path_info.fields:
+                raise ValueError('Trying to update unknown field "{field}"'.format(field=field))
+            field_info = self._path_info.fields[field]
+            if field_info.read_only:
+                raise ValueError('Trying to update read-only field "{field}"'.format(field=field))
         entry.update(kwargs)
         _normalize_entry(entry, self._path_info)
 

tests/unit/plugins/modules/routeros_module.py

@@ -9,7 +9,7 @@ __metaclass__ = type
 import os
 import json
 
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import AnsibleExitJson, AnsibleFailJson, ModuleTestCase
 
 
 fixture_path = os.path.join(os.path.dirname(__file__), 'fixtures')

tests/unit/plugins/modules/test_api.py

@@ -6,9 +6,10 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+
 from ansible_collections.community.routeros.tests.unit.plugins.modules.fake_api import FakeLibRouterosError, Key, Or, fake_ros_api
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
 from ansible_collections.community.routeros.plugins.modules import api
 
 
@@ -34,8 +35,8 @@ class TestRouterosApiModule(ModuleTestCase):
 
     def test_module_fail_when_required_args_missing(self):
         with self.assertRaises(AnsibleFailJson) as exc:
-            set_module_args({})
-            self.module.main()
+            with set_module_args({}):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -43,8 +44,8 @@ class TestRouterosApiModule(ModuleTestCase):
     @patch('ansible_collections.community.routeros.plugins.modules.api.ROS_api_module.api_add_path', new=fake_ros_api.path)
     def test_api_path(self):
         with self.assertRaises(AnsibleExitJson) as exc:
-            set_module_args(self.config_module_args.copy())
-            self.module.main()
+            with set_module_args(self.config_module_args.copy()):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -54,8 +55,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['add'] = "name=unit_test_brige"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -65,8 +66,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleFailJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['add'] = "name=unit_test_brige_exist"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -77,8 +78,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['remove'] = "*A1"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -88,8 +89,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleFailJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['remove'] = "*A2"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -100,8 +101,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['cmd'] = "add name=unit_test_brige_arbitrary"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -111,8 +112,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleFailJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['cmd'] = "add NONE_EXIST=unit_test_brige_arbitrary"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -123,8 +124,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['update'] = ".id=*A1 name=unit_test_brige"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -134,8 +135,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleFailJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['update'] = ".id=*A2 name=unit_test_brige"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -146,8 +147,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['query'] = ".id name"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -162,8 +163,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['query'] = ".id other"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -174,8 +175,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['query'] = ".id name WHERE name == dummy_bridge_A2"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -188,8 +189,8 @@ class TestRouterosApiModule(ModuleTestCase):
         with self.assertRaises(AnsibleExitJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['query'] = ".id name WHERE name != dummy_bridge_A2"
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -204,8 +205,8 @@ class TestRouterosApiModule(ModuleTestCase):
             module_args['extended_query'] = {
                 'attributes': ['.id', 'name'],
             }
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -222,8 +223,8 @@ class TestRouterosApiModule(ModuleTestCase):
             module_args['extended_query'] = {
                 'attributes': ['.id', 'other'],
             }
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -243,8 +244,8 @@ class TestRouterosApiModule(ModuleTestCase):
                     },
                 ],
             }
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -266,8 +267,8 @@ class TestRouterosApiModule(ModuleTestCase):
                     },
                 ],
             }
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -298,8 +299,8 @@ class TestRouterosApiModule(ModuleTestCase):
                     },
                 ],
             }
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)

tests/unit/plugins/modules/test_api_facts.py

@@ -6,9 +6,10 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+
 from ansible_collections.community.routeros.tests.unit.plugins.modules.fake_api import FakeLibRouterosError, Key, fake_ros_api
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
 from ansible_collections.community.routeros.plugins.modules import api_facts
 
 
@@ -437,8 +438,8 @@ class TestRouterosApiFactsModule(ModuleTestCase):
 
     def test_module_fail_when_required_args_missing(self):
         with self.assertRaises(AnsibleFailJson) as exc:
-            set_module_args({})
-            self.module.main()
+            with set_module_args({}):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -447,8 +448,8 @@ class TestRouterosApiFactsModule(ModuleTestCase):
         with self.assertRaises(AnsibleFailJson) as exc:
             module_args = self.config_module_args.copy()
             module_args['gather_subset'] = ['!foobar']
-            set_module_args(module_args)
-            self.module.main()
+            with set_module_args(module_args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -456,8 +457,8 @@ class TestRouterosApiFactsModule(ModuleTestCase):
 
     def test_full_run(self):
         with self.assertRaises(AnsibleExitJson) as exc:
-            set_module_args(self.config_module_args.copy())
-            self.module.main()
+            with set_module_args(self.config_module_args.copy()):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)

tests/unit/plugins/modules/test_api_find_and_modify.py

@@ -6,11 +6,12 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+
 from ansible_collections.community.routeros.tests.unit.plugins.modules.fake_api import (
     FakeLibRouterosError, fake_ros_api, massage_expected_result_data, create_fake_path,
 )
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
 from ansible_collections.community.routeros.plugins.modules import api_find_and_modify
 
 
@@ -93,6 +94,52 @@ START_IP_FIREWALL_FILTER = [
 
 START_IP_FIREWALL_FILTER_OLD_DATA = massage_expected_result_data(START_IP_FIREWALL_FILTER, ('ip', 'firewall', 'filter'), keep_all=True)
 
+START_IP_SERVICE = [
+    # I removed all entryes not for 'api' and 'api-ssl'
+    {
+        "certificate": None,
+        "tls-version": None,
+        ".id": "*7",
+        "address": "",
+        "disabled": True,
+        "dynamic": False,
+        "invalid": True,
+        "name": "api",
+        "port": 8728,
+        "proto": "tcp",
+        "vrf": "main"
+    },
+    {
+        ".id": "*9",
+        "address": "192.168.1.0/24",
+        "certificate": "mycert",
+        "dynamic": False,
+        "invalid": False,
+        "name": "api-ssl",
+        "port": 8729,
+        "proto": "tcp",
+        "tls-version": "only-1.2",
+        "vrf": "main"
+    },
+    {
+        "address": None,
+        "certificate": None,
+        "max-sessions": None,
+        "tls-version": None,
+        ".id": "*13",
+        "connection": True,
+        "dynamic": True,
+        "invalid": False,
+        "local": "192.168.1.1",
+        "name": "api-ssl",
+        "port": 8729,
+        "proto": "tcp",
+        "remote": "192.168.1.2:12346"
+    }
+]
+
+START_IP_SERVICE_OLD_DATA = massage_expected_result_data(START_IP_SERVICE, ('ip', 'service'), keep_all=True)
+
 
 class TestRouterosApiFindAndModifyModule(ModuleTestCase):
 
@@ -117,8 +164,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
 
     def test_module_fail_when_required_args_missing(self):
         with self.assertRaises(AnsibleFailJson) as exc:
-            set_module_args({})
-            self.module.main()
+            with set_module_args({}):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -136,8 +183,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     'comment': 'bar',
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -155,8 +202,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     'comment': 'bar',
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -173,8 +220,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     '!comment': None,
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -190,8 +237,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     '!comment': 'gone',
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -212,8 +259,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 },
                 'require_matches_min': 10,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -234,8 +281,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 },
                 'require_matches_min': 10,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -256,8 +303,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 },
                 'require_matches_max': 1,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -277,8 +324,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     'name': 'bam',
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -303,8 +350,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'require_matches_min': 2,
                 'allow_no_matches': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -325,8 +372,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'values': {
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -349,8 +396,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     'comment': None,
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -374,8 +421,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 },
                 '_ansible_diff': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -389,6 +436,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -397,6 +445,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -406,6 +455,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
         ])
         self.assertEqual(result['diff']['before']['values'], [
@@ -416,6 +466,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
         ])
         self.assertEqual(result['diff']['after']['values'], [
@@ -427,6 +478,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
         ])
         self.assertEqual(result['match_count'], 1)
@@ -445,8 +497,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     'comment': None,
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -459,6 +511,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -467,6 +520,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -475,6 +529,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
         ])
         self.assertEqual('diff' in result, False)
@@ -494,8 +549,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     'comment': '',
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -508,6 +563,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -516,6 +572,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -524,6 +581,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
         ])
         self.assertEqual(result['match_count'], 3)
@@ -542,8 +600,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     '!comment': None,
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -556,6 +614,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -564,6 +623,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -572,6 +632,7 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'ttl': '1d',
                 'disabled': False,
                 'dynamic': False,
+                'match-subdomain': False,
             },
         ])
         self.assertEqual(result['match_count'], 3)
@@ -592,8 +653,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                     '!connection-state': None,
                 },
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -605,25 +666,37 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'chain': 'input',
                 'comment': 'defconf',
                 'protocol': 'icmp',
+                'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*3',
                 'action': 'accept',
                 'chain': 'input',
                 'comment': 'defconf',
+                'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*4',
                 'action': 'accept',
                 'chain': 'input',
                 'comment': 'defconf',
+                'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*7',
                 'action': 'drop',
                 'chain': 'input',
                 'comment': 'defconf',
+                'disabled': False,
                 'in-interface': 'wan',
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*8',
@@ -631,6 +704,9 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'chain': 'forward',
                 'comment': 'defconf',
                 'connection-state': 'established',
+                'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*9',
@@ -638,6 +714,9 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'chain': 'forward',
                 'comment': 'defconf',
                 'connection-state': 'related',
+                'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*A',
@@ -645,7 +724,36 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'chain': 'forward',
                 'comment': 'defconf',
                 'connection-status': 'invalid',
+                'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
         ])
         self.assertEqual(result['match_count'], 3)
         self.assertEqual(result['modify_count'], 2)
+
+    @patch('ansible_collections.community.routeros.plugins.modules.api_find_and_modify.compose_api_path',
+           new=create_fake_path(('ip', 'service'), START_IP_SERVICE))
+    def test_change_ignore_dynamic(self):
+        with self.assertRaises(AnsibleExitJson) as exc:
+            args = self.config_module_args.copy()
+            args.update({
+                'path': 'ip service',
+                'find': {
+                    'name': 'api-ssl',
+                },
+                'values': {
+                    'address': '192.168.1.0/24',
+                },
+                'ignore_dynamic': True,
+                '_ansible_diff': True,
+            })
+            with set_module_args(args):
+                self.module.main()
+
+        result = exc.exception.args[0]
+        self.assertEqual(result['changed'], False)
+        self.assertEqual(result['old_data'], [entry for entry in START_IP_SERVICE_OLD_DATA if entry["dynamic"] is False])
+        self.assertEqual(result['new_data'], [entry for entry in START_IP_SERVICE_OLD_DATA if entry["dynamic"] is False])
+        self.assertEqual(result['match_count'], 1)
+        self.assertEqual(result['modify_count'], 0)

tests/unit/plugins/modules/test_api_info.py

@@ -6,9 +6,12 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch, MagicMock
-from ansible_collections.community.routeros.tests.unit.plugins.modules.fake_api import FakeLibRouterosError, Key, fake_ros_api
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+
+from ansible_collections.community.routeros.tests.unit.plugins.modules.fake_api import (
+    FAKE_ROS_VERSION, FakeLibRouterosError, Key, fake_ros_api,
+)
 from ansible_collections.community.routeros.plugins.modules import api_info
 
 
@@ -22,6 +25,10 @@ class TestRouterosApiInfoModule(ModuleTestCase):
         self.module.check_has_library = MagicMock()
         self.patch_create_api = patch('ansible_collections.community.routeros.plugins.modules.api_info.create_api', MagicMock(new=fake_ros_api))
         self.patch_create_api.start()
+        self.patch_get_api_version = patch(
+            'ansible_collections.community.routeros.plugins.modules.api_info.get_api_version',
+            MagicMock(return_value=FAKE_ROS_VERSION))
+        self.patch_get_api_version.start()
         self.module.Key = MagicMock(new=Key)
         self.config_module_args = {
             'username': 'admin',
@@ -30,12 +37,13 @@ class TestRouterosApiInfoModule(ModuleTestCase):
         }
 
     def tearDown(self):
+        self.patch_get_api_version.stop()
         self.patch_create_api.stop()
 
     def test_module_fail_when_required_args_missing(self):
         with self.assertRaises(AnsibleFailJson) as exc:
-            set_module_args({})
-            self.module.main()
+            with set_module_args({}):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -46,8 +54,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             args.update({
                 'path': 'something invalid'
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -61,8 +69,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             args.update({
                 'path': 'ip dns static'
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -86,8 +94,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             args.update({
                 'path': 'caps-man aaa',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -115,8 +123,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'caps-man aaa',
                 'hide_defaults': False,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -148,8 +156,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'caps-man aaa',
                 'unfiltered': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -182,8 +190,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'ip firewall filter',
                 'handle_disabled': 'exclamation',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -191,6 +199,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             'chain': 'input',
             'in-interface-list': 'LAN',
             '!action': None,
+            '!address-list': None,
+            '!address-list-timeout': None,
             '!comment': None,
             '!connection-bytes': None,
             '!connection-limit': None,
@@ -236,6 +246,7 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             '!protocol': None,
             '!psd': None,
             '!random': None,
+            '!realm': None,
             '!reject-with': None,
             '!routing-mark': None,
             '!routing-table': None,
@@ -268,8 +279,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'ip firewall filter',
                 'handle_disabled': 'null-value',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -277,6 +288,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             'chain': 'input',
             'in-interface-list': 'LAN',
             'action': None,
+            'address-list': None,
+            'address-list-timeout': None,
             'comment': None,
             'connection-bytes': None,
             'connection-limit': None,
@@ -322,6 +335,7 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             'protocol': None,
             'psd': None,
             'random': None,
+            'realm': None,
             'reject-with': None,
             'routing-mark': None,
             'routing-table': None,
@@ -354,8 +368,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'ip firewall filter',
                 'handle_disabled': 'omit',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -389,8 +403,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'handle_disabled': 'omit',
                 'include_dynamic': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -447,8 +461,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'interface list',
                 'handle_disabled': 'omit',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -456,8 +470,6 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             {
                 '.id': '*2000010',
                 'name': 'WAN',
-                'include': '',
-                'exclude': '',
                 'comment': 'defconf',
             },
         ])
@@ -500,8 +512,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'handle_disabled': 'omit',
                 'include_builtin': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -509,24 +521,18 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             {
                 '.id': '*2000000',
                 'name': 'all',
-                'include': '',
-                'exclude': '',
                 'builtin': True,
                 'comment': 'contains all interfaces',
             },
             {
                 '.id': '*2000001',
                 'name': 'none',
-                'include': '',
-                'exclude': '',
                 'builtin': True,
                 'comment': 'contains no interfaces',
             },
             {
                 '.id': '*2000010',
                 'name': 'WAN',
-                'include': '',
-                'exclude': '',
                 'builtin': False,
                 'comment': 'defconf',
             },
@@ -592,8 +598,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'path': 'ip dhcp-server lease',
                 'handle_disabled': 'omit',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -675,8 +681,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             args.update({
                 'path': 'interface gre',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -763,8 +769,8 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'handle_disabled': 'omit',
                 'hide_defaults': False,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -809,3 +815,169 @@ class TestRouterosApiInfoModule(ModuleTestCase):
                 'comment': 'foo',
             },
         ])
+
+    @patch('ansible_collections.community.routeros.plugins.modules.api_info.compose_api_path')
+    def test_restrict_1(self, mock_compose_api_path):
+        mock_compose_api_path.return_value = [
+            {
+                'chain': 'input',
+                'in-interface-list': 'LAN',
+                'dynamic': False,
+                '.id': '*1',
+            },
+            {
+                'chain': 'forward',
+                'action': 'drop',
+                'in-interface': 'sfp1',
+                '.id': '*2',
+                'dynamic': False,
+            },
+        ]
+        with self.assertRaises(AnsibleExitJson) as exc:
+            args = self.config_module_args.copy()
+            args.update({
+                'path': 'ip firewall filter',
+                'handle_disabled': 'omit',
+                'restrict': [],
+            })
+            with set_module_args(args):
+                self.module.main()
+
+        result = exc.exception.args[0]
+        self.assertEqual(result['changed'], False)
+        self.assertEqual(result['result'], [
+            {
+                'chain': 'input',
+                'in-interface-list': 'LAN',
+                '.id': '*1',
+            },
+            {
+                'chain': 'forward',
+                'action': 'drop',
+                'in-interface': 'sfp1',
+                '.id': '*2',
+            },
+        ])
+
+    @patch('ansible_collections.community.routeros.plugins.modules.api_info.compose_api_path')
+    def test_restrict_2(self, mock_compose_api_path):
+        mock_compose_api_path.return_value = [
+            {
+                'chain': 'input',
+                'in-interface-list': 'LAN',
+                'dynamic': False,
+                '.id': '*1',
+            },
+            {
+                'chain': 'forward',
+                'action': 'drop',
+                'in-interface': 'sfp1',
+                '.id': '*2',
+                'dynamic': False,
+            },
+            {
+                'chain': 'input',
+                'action': 'drop',
+                'dynamic': False,
+                '.id': '*3',
+            },
+        ]
+        with self.assertRaises(AnsibleExitJson) as exc:
+            args = self.config_module_args.copy()
+            args.update({
+                'path': 'ip firewall filter',
+                'handle_disabled': 'omit',
+                'restrict': [{
+                    'field': 'chain',
+                    'values': ['forward'],
+                }],
+            })
+            with set_module_args(args):
+                self.module.main()
+
+        result = exc.exception.args[0]
+        self.assertEqual(result['changed'], False)
+        self.assertEqual(result['result'], [
+            {
+                'chain': 'forward',
+                'action': 'drop',
+                'in-interface': 'sfp1',
+                '.id': '*2',
+            },
+        ])
+
+    @patch('ansible_collections.community.routeros.plugins.modules.api_info.compose_api_path')
+    def test_restrict_3(self, mock_compose_api_path):
+        mock_compose_api_path.return_value = [
+            {
+                'chain': 'input',
+                'in-interface-list': 'LAN',
+                'dynamic': False,
+                '.id': '*1',
+            },
+            {
+                'chain': 'forward',
+                'action': 'drop',
+                'in-interface': 'sfp1',
+                '.id': '*2',
+                'dynamic': False,
+            },
+            {
+                'chain': 'input',
+                'action': 'drop',
+                'dynamic': False,
+                '.id': '*3',
+            },
+            {
+                'chain': 'input',
+                'action': 'drop',
+                'comment': 'Foo',
+                'dynamic': False,
+                '.id': '*4',
+            },
+            {
+                'chain': 'input',
+                'action': 'drop',
+                'comment': 'Bar',
+                'dynamic': False,
+                '.id': '*5',
+            },
+        ]
+        with self.assertRaises(AnsibleExitJson) as exc:
+            args = self.config_module_args.copy()
+            args.update({
+                'path': 'ip firewall filter',
+                'handle_disabled': 'omit',
+                'restrict': [
+                    {
+                        'field': 'chain',
+                        'values': ['input', 'foobar'],
+                    },
+                    {
+                        'field': 'action',
+                        'values': ['drop', 42],
+                    },
+                    {
+                        'field': 'comment',
+                        'values': [None, 'Foo'],
+                    },
+                ],
+            })
+            with set_module_args(args):
+                self.module.main()
+
+        result = exc.exception.args[0]
+        self.assertEqual(result['changed'], False)
+        self.assertEqual(result['result'], [
+            {
+                'chain': 'input',
+                'action': 'drop',
+                '.id': '*3',
+            },
+            {
+                'chain': 'input',
+                'action': 'drop',
+                'comment': 'Foo',
+                '.id': '*4',
+            },
+        ])

tests/unit/plugins/modules/test_api_modify.py

@@ -6,11 +6,12 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch, MagicMock
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
+
 from ansible_collections.community.routeros.tests.unit.plugins.modules.fake_api import (
-    FakeLibRouterosError, fake_ros_api, massage_expected_result_data, create_fake_path,
+    FAKE_ROS_VERSION, FakeLibRouterosError, fake_ros_api, massage_expected_result_data, create_fake_path,
 )
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args, AnsibleExitJson, AnsibleFailJson, ModuleTestCase
 from ansible_collections.community.routeros.plugins.modules import api_modify
 
 
@@ -302,6 +303,10 @@ class TestRouterosApiModifyModule(ModuleTestCase):
             'ansible_collections.community.routeros.plugins.modules.api_modify.create_api',
             MagicMock(new=fake_ros_api))
         self.patch_create_api.start()
+        self.patch_get_api_version = patch(
+            'ansible_collections.community.routeros.plugins.modules.api_modify.get_api_version',
+            MagicMock(return_value=FAKE_ROS_VERSION))
+        self.patch_get_api_version.start()
         self.config_module_args = {
             'username': 'admin',
             'password': 'pаss',
@@ -309,12 +314,13 @@ class TestRouterosApiModifyModule(ModuleTestCase):
         }
 
     def tearDown(self):
+        self.patch_get_api_version.stop()
         self.patch_create_api.stop()
 
     def test_module_fail_when_required_args_missing(self):
         with self.assertRaises(AnsibleFailJson) as exc:
-            set_module_args({})
-            self.module.main()
+            with set_module_args({}):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -326,8 +332,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'path': 'something invalid',
                 'data': [],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -343,8 +349,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     'foo': 'bar',
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -361,8 +367,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     '!comment': None,
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -378,8 +384,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     '!disabled': None,
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -395,8 +401,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     '!comment': 'foo',
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -411,8 +417,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     'name': None,
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -427,8 +433,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     'interface': 'eth0',
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -443,8 +449,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     'address': '192.168.88.1',
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -461,8 +467,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     'address': '192.168.88.1',
                 }],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['failed'], True)
@@ -493,8 +499,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -528,8 +534,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -551,8 +557,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -586,8 +592,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -600,6 +606,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -607,6 +614,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -614,6 +622,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*NEW1',
@@ -621,6 +630,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry 2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -647,8 +657,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -661,6 +671,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -668,6 +679,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -675,6 +687,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*NEW1',
@@ -682,6 +695,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry 2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -709,8 +723,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 ],
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -723,6 +737,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -730,6 +745,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -737,6 +753,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 'name': 'router',
@@ -769,8 +786,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -782,6 +799,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -789,6 +807,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry 2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -796,6 +815,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -825,8 +845,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -838,6 +858,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -845,6 +866,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry 2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -852,6 +874,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -881,8 +904,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -894,6 +917,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -901,6 +925,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*NEW1',
@@ -908,6 +933,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'cname': 'router.com.',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -938,8 +964,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -951,6 +977,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -958,6 +985,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 'name': 'router',
@@ -990,8 +1018,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1003,6 +1031,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -1011,6 +1040,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry 2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -1018,6 +1048,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -1047,8 +1078,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1060,6 +1091,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -1068,6 +1100,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry 2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*7',
@@ -1075,6 +1108,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -1095,8 +1129,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1109,6 +1143,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -1130,8 +1165,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1144,6 +1179,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -1177,8 +1213,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1190,6 +1226,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*NEW1',
@@ -1197,6 +1234,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'bar',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*A',
@@ -1204,6 +1242,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*1',
@@ -1212,6 +1251,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -1246,8 +1286,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'ensure_order': True,
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1259,6 +1299,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.2',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 'name': 'foo',
@@ -1270,6 +1311,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'text': 'Router Text Entry',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
             {
                 '.id': '*1',
@@ -1278,6 +1320,7 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'address': '192.168.88.1',
                 'ttl': '1d',
                 'disabled': False,
+                'match-subdomain': False,
             },
         ])
 
@@ -1298,8 +1341,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1321,8 +1364,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 ],
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1344,8 +1387,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1384,8 +1427,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 ],
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1424,8 +1467,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 ],
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1465,8 +1508,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1509,8 +1552,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                     },
                 ],
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1545,8 +1588,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1579,8 +1622,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'handle_entries_content': 'remove',
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1634,8 +1677,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1687,8 +1730,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1743,8 +1786,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'ensure_order': True,
                 '_ansible_check_mode': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1805,8 +1848,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1837,8 +1880,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1869,8 +1912,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_entries_content': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], True)
@@ -1927,8 +1970,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)
@@ -1963,8 +2006,8 @@ class TestRouterosApiModifyModule(ModuleTestCase):
                 'handle_absent_entries': 'remove',
                 'ensure_order': True,
             })
-            set_module_args(args)
-            self.module.main()
+            with set_module_args(args):
+                self.module.main()
 
         result = exc.exception.args[0]
         self.assertEqual(result['changed'], False)

tests/unit/plugins/modules/test_command.py

@@ -8,9 +8,10 @@ __metaclass__ = type
 
 import json
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args
+
 from ansible_collections.community.routeros.plugins.modules import command
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args
 from .routeros_module import TestRouterosModule, load_fixture
 
 
@@ -47,54 +48,54 @@ class TestRouterosCommandModule(TestRouterosModule):
         self.run_commands.side_effect = load_from_file
 
     def test_command_simple(self):
-        set_module_args(dict(commands=['/system resource print']))
-        result = self.execute_module(changed=True)
+        with set_module_args(dict(commands=['/system resource print'])):
+            result = self.execute_module(changed=True)
         self.assertEqual(len(result['stdout']), 1)
         self.assertTrue('platform: "MikroTik"' in result['stdout'][0])
 
     def test_command_multiple(self):
-        set_module_args(dict(commands=['/system resource print', '/system resource print']))
-        result = self.execute_module(changed=True)
+        with set_module_args(dict(commands=['/system resource print', '/system resource print'])):
+            result = self.execute_module(changed=True)
         self.assertEqual(len(result['stdout']), 2)
         self.assertTrue('platform: "MikroTik"' in result['stdout'][0])
 
     def test_command_wait_for(self):
         wait_for = 'result[0] contains "MikroTik"'
-        set_module_args(dict(commands=['/system resource print'], wait_for=wait_for))
-        self.execute_module(changed=True)
+        with set_module_args(dict(commands=['/system resource print'], wait_for=wait_for)):
+            self.execute_module(changed=True)
 
     def test_command_wait_for_fails(self):
         wait_for = 'result[0] contains "test string"'
-        set_module_args(dict(commands=['/system resource print'], wait_for=wait_for))
-        self.execute_module(failed=True)
+        with set_module_args(dict(commands=['/system resource print'], wait_for=wait_for)):
+            self.execute_module(failed=True)
         self.assertEqual(self.run_commands.call_count, 10)
 
     def test_command_retries(self):
         wait_for = 'result[0] contains "test string"'
-        set_module_args(dict(commands=['/system resource print'], wait_for=wait_for, retries=2))
-        self.execute_module(failed=True)
+        with set_module_args(dict(commands=['/system resource print'], wait_for=wait_for, retries=2)):
+            self.execute_module(failed=True)
         self.assertEqual(self.run_commands.call_count, 2)
 
     def test_command_match_any(self):
         wait_for = ['result[0] contains "MikroTik"',
                     'result[0] contains "test string"']
-        set_module_args(dict(commands=['/system resource print'], wait_for=wait_for, match='any'))
-        self.execute_module(changed=True)
+        with set_module_args(dict(commands=['/system resource print'], wait_for=wait_for, match='any')):
+            self.execute_module(changed=True)
 
     def test_command_match_all(self):
         wait_for = ['result[0] contains "MikroTik"',
                     'result[0] contains "RB1100"']
-        set_module_args(dict(commands=['/system resource print'], wait_for=wait_for, match='all'))
-        self.execute_module(changed=True)
+        with set_module_args(dict(commands=['/system resource print'], wait_for=wait_for, match='all')):
+            self.execute_module(changed=True)
 
     def test_command_match_all_failure(self):
         wait_for = ['result[0] contains "MikroTik"',
                     'result[0] contains "test string"']
         commands = ['/system resource print', '/system resource print']
-        set_module_args(dict(commands=commands, wait_for=wait_for, match='all'))
-        self.execute_module(failed=True)
+        with set_module_args(dict(commands=commands, wait_for=wait_for, match='all')):
+            self.execute_module(failed=True)
 
     def test_command_wait_for_2(self):
         wait_for = 'result[0] contains "wireless"'
-        set_module_args(dict(commands=['/system package print'], wait_for=wait_for))
-        self.execute_module(changed=True)
+        with set_module_args(dict(commands=['/system package print'], wait_for=wait_for)):
+            self.execute_module(changed=True)

tests/unit/plugins/modules/test_facts.py

@@ -6,9 +6,10 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch
+from ansible_collections.community.internal_test_tools.tests.unit.compat.mock import patch
+from ansible_collections.community.internal_test_tools.tests.unit.plugins.modules.utils import set_module_args
+
 from ansible_collections.community.routeros.plugins.modules import facts
-from ansible_collections.community.routeros.tests.unit.plugins.modules.utils import set_module_args
 from .routeros_module import TestRouterosModule, load_fixture
 
 
@@ -39,8 +40,8 @@ class TestRouterosFactsModule(TestRouterosModule):
         self.run_commands.side_effect = load_from_file
 
     def test_facts_default(self):
-        set_module_args(dict(gather_subset='default'))
-        result = self.execute_module()
+        with set_module_args(dict(gather_subset='default')):
+            result = self.execute_module()
         self.assertEqual(
             result['ansible_facts']['ansible_net_hostname'], 'MikroTik'
         )
@@ -61,8 +62,8 @@ class TestRouterosFactsModule(TestRouterosModule):
         )
 
     def test_facts_hardware(self):
-        set_module_args(dict(gather_subset='hardware'))
-        result = self.execute_module()
+        with set_module_args(dict(gather_subset='hardware')):
+            result = self.execute_module()
         self.assertEqual(
             result['ansible_facts']['ansible_net_spacefree_mb'], 64921.6
         )
@@ -77,8 +78,8 @@ class TestRouterosFactsModule(TestRouterosModule):
         )
 
     def test_facts_config(self):
-        set_module_args(dict(gather_subset='config'))
-        result = self.execute_module()
+        with set_module_args(dict(gather_subset='config')):
+            result = self.execute_module()
         self.assertIsInstance(
             result['ansible_facts']['ansible_net_config'], str
         )
@@ -88,8 +89,8 @@ class TestRouterosFactsModule(TestRouterosModule):
         )
 
     def test_facts_interfaces(self):
-        set_module_args(dict(gather_subset='interfaces'))
-        result = self.execute_module()
+        with set_module_args(dict(gather_subset='interfaces')):
+            result = self.execute_module()
         self.assertIn(
             result['ansible_facts']['ansible_net_all_ipv4_addresses'][0], ['10.37.129.3', '10.37.0.0', '192.168.88.1']
         )
@@ -118,8 +119,8 @@ class TestRouterosFactsModule(TestRouterosModule):
         self.assertEqual(result, None)
 
     def test_facts_routing(self):
-        set_module_args(dict(gather_subset='routing'))
-        result = self.execute_module()
+        with set_module_args(dict(gather_subset='routing')):
+            result = self.execute_module()
         self.assertIn(
             result['ansible_facts']['ansible_net_bgp_peer']['iBGP_BRAS.TYRMA']['name'], ['iBGP_BRAS.TYRMA']
         )

tests/unit/plugins/modules/utils.py

@@ -1,54 +0,0 @@
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
-
-import json
-
-from ansible_collections.community.routeros.tests.unit.compat import unittest
-from ansible_collections.community.routeros.tests.unit.compat.mock import patch
-from ansible.module_utils import basic
-from ansible.module_utils.common.text.converters import to_bytes
-
-
-def set_module_args(args):
-    if '_ansible_remote_tmp' not in args:
-        args['_ansible_remote_tmp'] = '/tmp'
-    if '_ansible_keep_remote_files' not in args:
-        args['_ansible_keep_remote_files'] = False
-
-    args = json.dumps({'ANSIBLE_MODULE_ARGS': args})
-    basic._ANSIBLE_ARGS = to_bytes(args)
-
-
-class AnsibleExitJson(Exception):
-    pass
-
-
-class AnsibleFailJson(Exception):
-    pass
-
-
-def exit_json(*args, **kwargs):
-    if 'changed' not in kwargs:
-        kwargs['changed'] = False
-    raise AnsibleExitJson(kwargs)
-
-
-def fail_json(*args, **kwargs):
-    kwargs['failed'] = True
-    raise AnsibleFailJson(kwargs)
-
-
-class ModuleTestCase(unittest.TestCase):
-
-    def setUp(self):
-        self.mock_module = patch.multiple(basic.AnsibleModule, exit_json=exit_json, fail_json=fail_json)
-        self.mock_module.start()
-        self.mock_sleep = patch('time.sleep')
-        self.mock_sleep.start()
-        set_module_args({})
-        self.addCleanup(self.mock_module.stop)
-        self.addCleanup(self.mock_sleep.stop)

tests/unit/requirements.yml

@@ -4,4 +4,4 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 collections:
-- ansible.netcommon
+  - community.internal_test_tools

tests/update-docs.py

@@ -9,7 +9,9 @@
 Updates DOCUMENTATION of modules using module_utils._api_data with the correct list of supported paths.
 '''
 
-from plugins.module_utils._api_data import (
+import sys
+
+from ansible_collections.community.routeros.plugins.module_utils._api_data import (
     PATHS,
     join_path,
 )
@@ -21,24 +23,34 @@ MODULES = [
 ]
 
 
-def update_file(file, begin_line, end_line, choice_line, path_choices):
+def update_file(file: str, begin_line: str, end_line: str, choice_line: str, path_choices: list[str]) -> bool:
     with open(file, 'r', encoding='utf-8') as f:
         lines = f.read().splitlines()
     begin_index = lines.index(begin_line)
     end_index = lines.index(end_line, begin_index + 1)
     new_lines = lines[:begin_index + 1] + [choice_line.format(choice=choice) for choice in path_choices] + lines[end_index:]
-    if lines != new_lines:
-        print(f'{file} has been updated')
-        with open(file, 'w', encoding='utf-8') as f:
-            f.write('\n'.join(new_lines) + '\n')
+    if lines == new_lines:
+        return False
+    print(f'{file} has been updated')
+    with open(file, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(new_lines) + '\n')
+    return True
 
 
-def main():
+def main(args: list[str]) -> int:
     path_choices = sorted([join_path(path) for path, path_info in PATHS.items() if path_info.fully_understood])
 
+    changes = False
     for file in MODULES:
-        update_file(file, '    # BEGIN PATH LIST', '    # END PATH LIST', '        - {choice}', path_choices)
+        changes |= update_file(file, '    # BEGIN PATH LIST', '    # END PATH LIST', '      - {choice}', path_choices)
+
+    lint = "--lint" in args
+    if not lint or not changes:
+        return 0
+
+    print("Run 'nox -Re update-docs'!")
+    return 1
 
 
 if __name__ == '__main__':
-    main()
+    sys.exit(main(sys.argv[1:]))