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,168 +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
-          - stable-2.16
-          - stable-2.17
-          - 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
-          - stable-2.16
-          - stable-2.17
-          - 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.10"
-          - "3.11"
-          - "3.12"
-        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.11"
-          # 2.15
-          - ansible: stable-2.15
-            python: "3.9"
-          # 2.16
-          - ansible: stable-2.16
-            python: "3.10"
-          # 2.17
-          - ansible: stable-2.17
-            python: "3.12"
-
-    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]
 
@@ -40,12 +40,15 @@ 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 }}
       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
@@ -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,179 +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
-            other_deps: |2
-                python_interpreter:
-                  package_system: python3.11 python3.11-pip python3.11-wheel python3.11-cryptography
-                  python_path: "/usr/bin/python3.11"
-            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@v4
-        with:
-          path: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        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,51 +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@v4
-        with:
-          path: ansible_collections/${{env.NAMESPACE}}/${{env.COLLECTION_NAME}}
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - 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
-          git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.netcommon.git ./ansible_collections/ansible/netcommon
-          git clone --depth=1 --single-branch https://github.com/ansible-collections/ansible.utils.git ./ansible_collections/ansible/utils
-        # 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 ansible.netcommon -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,20 +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:
-
-jobs:
-  import-galaxy:
-    permissions:
-      contents: read
-    name: Test to import built collection artifact with Galaxy importer
-    uses: ansible-community/github-action-test-galaxy-import/.github/workflows/test-galaxy-import.yml@main

.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,27 +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@v4
-
-      - name: REUSE Compliance Check
-        uses: fsfe/reuse-action@v3

.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,300 @@ 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
 =======
 
@@ -396,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
 ======
@@ -425,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
 ======
@@ -463,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
 ======

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, ansible-core 2.14, ansible-core 2.15, ansible-core 2.16, and ansible-core 2.17 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.md).
+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,31 +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
+  - 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/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

@@ -57,7 +57,7 @@ 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 documentation of the :ansplugin:`community.routeros.api module <community.routeros.api#module>` for details on the options.
 
@@ -191,7 +191,7 @@ When this playbook completed successfully, you should be able to use the HTTPS a
 .. code-block:: yaml+jinja
 
     - community.routeros.api:
-        ...
+        # ...
         tls: true
         validate_certs: true
         validate_cert_hostname: true

docs/docsite/rst/ssh-guide.rst

@@ -66,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:
 
@@ -126,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.15.0
+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,17 +43,16 @@ options:
       - ssl
   port:
     description:
-      - RouterOS api port. If O(tls) is set, port will apply to TLS/SSL connection.
+      - 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 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).
+      - 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
@@ -61,10 +60,9 @@ options:
     description:
       - 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.
+      - 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
@@ -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

@@ -30,6 +30,7 @@ DOCUMENTATION:
     - 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_data.py

@@ -226,6 +226,25 @@ def join_path(path):
 # 3. All bold attributes go into the `primary_keys` list -- this is not always true!
 
 PATHS = {
+    ('interface', '6to4'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            primary_keys=('name', ),
+            fields={
+                'clamp-tcp-mss': KeyInfo(default=True),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'disabled': KeyInfo(default=False),
+                'dont-fragment': KeyInfo(default=False),
+                'dscp': KeyInfo(default='inherit'),
+                'ipsec-secret': KeyInfo(can_disable=True),
+                'keepalive': KeyInfo(default='10s,10', can_disable=True),
+                'local-address': KeyInfo(default='0.0.0.0'),
+                'mtu': KeyInfo(default='auto'),
+                'name': KeyInfo(),
+                'remote-address': KeyInfo(required=True),
+            }
+        ),
+    ),
     ('interface', 'bonding'): APIData(
         unversioned=VersionedAPIData(
             fully_understood=True,
@@ -259,6 +278,13 @@ PATHS = {
         unversioned=VersionedAPIData(
             fully_understood=True,
             primary_keys=('name', ),
+            versioned_fields=[
+                ([('7.0', '<')], 'ingress-filtering', KeyInfo(default=False)),
+                ([('7.0', '>=')], 'ingress-filtering', KeyInfo(default=True)),
+                ([('7.13', '>=')], 'port-cost-mode', KeyInfo(default='long')),
+                ([('7.16', '>=')], 'forward-reserved-addresses', KeyInfo(default=False)),
+                ([('7.16', '>=')], 'max-learned-entries', KeyInfo(default='auto')),
+            ],
             fields={
                 'admin-mac': KeyInfo(default=''),
                 'ageing-time': KeyInfo(default='5m'),
@@ -270,12 +296,13 @@ PATHS = {
                 'disabled': KeyInfo(default=False),
                 'ether-type': KeyInfo(default='0x8100'),
                 'fast-forward': KeyInfo(default=True),
-                'frame-types': KeyInfo(default='admit-all'),
                 'forward-delay': KeyInfo(default='15s'),
+                'frame-types': KeyInfo(default='admit-all'),
                 'igmp-snooping': KeyInfo(default=False),
-                'ingress-filtering': KeyInfo(default=True),
                 'max-message-age': KeyInfo(default='20s'),
+                'mld-version': KeyInfo(default=1),
                 'mtu': KeyInfo(default='auto'),
+                'multicast-querier': KeyInfo(default=False),
                 'name': KeyInfo(),
                 'priority': KeyInfo(default='0x8000'),
                 'protocol-mode': KeyInfo(default='rstp'),
@@ -327,9 +354,9 @@ PATHS = {
                 'combo-mode': KeyInfo(can_disable=True),
                 'comment': KeyInfo(can_disable=True, remove_value=''),
                 'disabled': KeyInfo(default=False),
-                'fec-mode': KeyInfo(can_disable=True),
+                'fec-mode': KeyInfo(can_disable=True, remove_value='auto'),
                 'full-duplex': KeyInfo(default=True),
-                'l2mtu': KeyInfo(default=1598),
+                'l2mtu': KeyInfo(),
                 'loop-protect': KeyInfo(default='default'),
                 'loop-protect-disable-time': KeyInfo(default='5m'),
                 'loop-protect-send-interval': KeyInfo(default='5s'),
@@ -338,8 +365,8 @@ PATHS = {
                 'mtu': KeyInfo(default=1500),
                 'name': KeyInfo(),
                 'orig-mac-address': KeyInfo(),
-                'poe-out': KeyInfo(can_disable=True),
-                'poe-priority': KeyInfo(can_disable=True),
+                'poe-out': KeyInfo(can_disable=True, remove_value='auto-on'),
+                'poe-priority': KeyInfo(can_disable=True, remove_value=10),
                 'poe-voltage': KeyInfo(can_disable=True),
                 'power-cycle-interval': KeyInfo(),
                 'power-cycle-ping-address': KeyInfo(can_disable=True),
@@ -347,7 +374,7 @@ PATHS = {
                 'power-cycle-ping-timeout': KeyInfo(can_disable=True),
                 'rx-flow-control': KeyInfo(default='off'),
                 'sfp-rate-select': KeyInfo(default='high'),
-                'sfp-shutdown-temperature': KeyInfo(default='95C'),
+                'sfp-shutdown-temperature': KeyInfo(default=95),
                 'speed': KeyInfo(),
                 'tx-flow-control': KeyInfo(default='off'),
             },
@@ -414,8 +441,8 @@ PATHS = {
             fully_understood=True,
             fields={
                 'comment': KeyInfo(can_disable=True, remove_value=''),
-                'exclude': KeyInfo(),
-                'include': KeyInfo(),
+                'exclude': KeyInfo(default=''),
+                'include': KeyInfo(default=''),
                 'name': KeyInfo(),
             },
         ),
@@ -625,13 +652,22 @@ PATHS = {
     ),
     ('ip', 'ipsec', 'mode-config'): APIData(
         unversioned=VersionedAPIData(
-            unknown_mechanism=True,
-            # primary_keys=('default', ),
+            fully_understood=True,
+            primary_keys=('name', ),
+            versioned_fields=[
+                ([('6.43', '>=')], 'responder', KeyInfo(default=False)),
+                ([('6.44', '>=')], 'address', KeyInfo(can_disable=True, remove_value='0.0.0.0')),
+            ],
             fields={
-                'default': KeyInfo(),
+                'address-pool': KeyInfo(can_disable=True, remove_value='none'),
+                'address-prefix-length': KeyInfo(),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
                 'name': KeyInfo(),
-                'responder': KeyInfo(),
-                'use-responder-dns': KeyInfo(),
+                'split-dns': KeyInfo(can_disable=True, remove_value=''),
+                'split-include': KeyInfo(can_disable=True, remove_value=''),
+                'src-address-list': KeyInfo(can_disable=True, remove_value=''),
+                'static-dns': KeyInfo(can_disable=True, remove_value=''),
+                'system-dns': KeyInfo(default=False),
             },
         ),
     ),
@@ -701,7 +737,9 @@ PATHS = {
             fully_understood=True,
             primary_keys=('name', ),
             fields={
+                'comment': KeyInfo(),
                 'name': KeyInfo(),
+                'next-pool': KeyInfo(),
                 'ranges': KeyInfo(),
             },
         ),
@@ -774,36 +812,6 @@ PATHS = {
             )),
         ],
     ),
-    ('ip', 'dhcp-server'): APIData(
-        unversioned=VersionedAPIData(
-            fully_understood=True,
-            primary_keys=('name', ),
-            fields={
-                'address-pool': KeyInfo(default='static-only'),
-                'allow-dual-stack-queue': KeyInfo(can_disable=True, remove_value=True),
-                'always-broadcast': KeyInfo(can_disable=True, remove_value=False),
-                'authoritative': KeyInfo(default=True),
-                'bootp-lease-time': KeyInfo(default='forever'),
-                'bootp-support': KeyInfo(can_disable=True, remove_value='static'),
-                'client-mac-limit': KeyInfo(can_disable=True, remove_value='unlimited'),
-                'comment': KeyInfo(can_disable=True, remove_value=''),
-                'conflict-detection': KeyInfo(can_disable=True, remove_value=True),
-                'delay-threshold': KeyInfo(can_disable=True, remove_value='none'),
-                'dhcp-option-set': KeyInfo(can_disable=True, remove_value='none'),
-                'disabled': KeyInfo(default=False),
-                'insert-queue-before': KeyInfo(can_disable=True, remove_value='first'),
-                'interface': KeyInfo(required=True),
-                'lease-script': KeyInfo(default=''),
-                'lease-time': KeyInfo(default='10m'),
-                'name': KeyInfo(),
-                'parent-queue': KeyInfo(can_disable=True, remove_value='none'),
-                'relay': KeyInfo(can_disable=True, remove_value='0.0.0.0'),
-                'server-address': KeyInfo(can_disable=True, remove_value='0.0.0.0'),
-                'use-framed-as-classless': KeyInfo(can_disable=True, remove_value=True),
-                'use-radius': KeyInfo(default=False),
-            },
-        ),
-    ),
     ('routing', 'filter'): APIData(
         versioned=[
             ('7', '<', VersionedAPIData(
@@ -871,6 +879,19 @@ PATHS = {
             )),
         ],
     ),
+    ('routing', 'filter', 'num-list'): APIData(
+        versioned=[
+            ('7', '>=', VersionedAPIData(
+                fully_understood=True,
+                fields={
+                    'list': KeyInfo(required=True),
+                    'comment': KeyInfo(can_disable=True, remove_value=''),
+                    'disabled': KeyInfo(can_disable=True),
+                    'range': KeyInfo(can_disable=True),
+                },
+            )),
+        ],
+    ),
     ('routing', 'filter', 'rule'): APIData(
         versioned=[
             ('7', '>=', VersionedAPIData(
@@ -903,6 +924,20 @@ PATHS = {
             )),
         ],
     ),
+    ('routing', 'filter', 'community-list'): APIData(
+        versioned=[
+            ('7', '>=', VersionedAPIData(
+                fully_understood=True,
+                fields={
+                    'list': KeyInfo(required=True),
+                    'comment': KeyInfo(can_disable=True, remove_value=''),
+                    'disabled': KeyInfo(can_disable=True),
+                    'communities': KeyInfo(can_disable=True),
+                    'regexp': KeyInfo(can_disable=True),
+                },
+            )),
+        ],
+    ),
     ('routing', 'ospf', 'instance'): APIData(
         unversioned=VersionedAPIData(
             fully_understood=True,
@@ -986,6 +1021,21 @@ PATHS = {
             },
         ),
     ),
+    ('routing', 'ospf', 'static-neighbor'): APIData(
+        versioned=[
+            ('7', '>=', VersionedAPIData(
+                fully_understood=True,
+                fields={
+                    'address': KeyInfo(required=True),
+                    'area': KeyInfo(required=True),
+                    'comment': KeyInfo(can_disable=True, remove_value=''),
+                    'disabled': KeyInfo(default=False),
+                    'instance-id': KeyInfo(default=0),
+                    'poll-interval': KeyInfo(default='2m'),
+                },
+            )),
+        ],
+    ),
     ('routing', 'ospf-v3', 'instance'): APIData(
         unversioned=VersionedAPIData(
             unknown_mechanism=True,
@@ -1098,6 +1148,7 @@ PATHS = {
             fully_understood=True,
             primary_keys=('name', ),
             fields={
+                'default': KeyInfo(read_only=True),
                 'addresses': KeyInfo(default='::/0'),
                 'authentication-password': KeyInfo(default=''),
                 'authentication-protocol': KeyInfo(default='MD5'),
@@ -1325,6 +1376,10 @@ PATHS = {
         unversioned=VersionedAPIData(
             fully_understood=True,
             primary_keys=('interface', ),
+            versioned_fields=[
+                ([('7.0', '<')], 'ingress-filtering', KeyInfo(default=False)),
+                ([('7.0', '>=')], 'ingress-filtering', KeyInfo(default=True)),
+            ],
             fields={
                 'auto-isolate': KeyInfo(default=False),
                 'bpdu-guard': KeyInfo(default=False),
@@ -1337,7 +1392,6 @@ PATHS = {
                 'frame-types': KeyInfo(default='admit-all'),
                 'horizon': KeyInfo(default='none'),
                 'hw': KeyInfo(default=True),
-                'ingress-filtering': KeyInfo(default=True),
                 'interface': KeyInfo(),
                 'internal-path-cost': KeyInfo(default=10),
                 'learn': KeyInfo(default='auto'),
@@ -1443,6 +1497,9 @@ PATHS = {
             fully_understood=True,
             versioned_fields=[
                 ([('7.7', '>=')], 'mode', KeyInfo(default='tx-and-rx')),
+                ([('7.15', '>=')], 'lldp-mac-phy-config', KeyInfo(default=False)),
+                ([('7.16', '>=')], 'discover-interval', KeyInfo(default='30s')),
+                ([('7.16', '>=')], 'lldp-vlan-info', KeyInfo(default=False)),
             ],
             fields={
                 'discover-interface-list': KeyInfo(),
@@ -1455,6 +1512,9 @@ PATHS = {
         unversioned=VersionedAPIData(
             single_value=True,
             fully_understood=True,
+            versioned_fields=[
+                ([('7.16', '>=')], 'ipv4-multipath-hash-policy', KeyInfo(default='l3')),
+            ],
             fields={
                 'accept-redirects': KeyInfo(default=False),
                 'accept-source-route': KeyInfo(default=False),
@@ -1491,12 +1551,21 @@ PATHS = {
         unversioned=VersionedAPIData(
             single_value=True,
             fully_understood=True,
+            versioned_fields=[
+                ([('7.16', '>=')], 'multipath-hash-policy', KeyInfo(default='l3')),
+                ([('7.17', '>=')], 'disable-link-local-address', KeyInfo(default=False)),
+                ([('7.17', '>=')], 'stale-neighbor-timeout', KeyInfo(default=60)),
+                ([('7.18', '>=')], 'allow-fast-path', KeyInfo(default=True)),
+                ([('7.18', '<')], 'max-neighbor-entries', KeyInfo(default=8192)),
+                ([('7.18', '>=')], 'min-neighbor-entries', KeyInfo()),
+                ([('7.18', '>=')], 'soft-max-neighbor-entries', KeyInfo()),
+                ([('7.18', '>=')], 'max-neighbor-entries', KeyInfo()),
+            ],
             fields={
                 'accept-redirects': KeyInfo(default='yes-if-forwarding-disabled'),
                 'accept-router-advertisements': KeyInfo(default='yes-if-forwarding-disabled'),
                 'disable-ipv6': KeyInfo(default=False),
                 'forward': KeyInfo(default=True),
-                'max-neighbor-entries': KeyInfo(default=8192),
             },
         ),
     ),
@@ -1512,6 +1581,38 @@ PATHS = {
             },
         ),
     ),
+    ('interface', 'l2tp-client',): APIData(
+        unversioned=VersionedAPIData(
+            primary_keys=('name', ),
+            single_value=False,
+            fully_understood=True,
+            fields={
+                'add-default-route': KeyInfo(default=False),
+                'allow': KeyInfo(default='pap,chap,mschap1,mschap2'),
+                'allow-fast-path': KeyInfo(default=False),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'connect-to': KeyInfo(required=True),
+                'default-route-distance': KeyInfo(default=False),
+                'dial-on-demand': KeyInfo(default=False),
+                'disabled': KeyInfo(default=True),
+                'ipsec-secret': KeyInfo(default=''),
+                'keepalive-timeout': KeyInfo(default=60),
+                'l2tp-proto-version': KeyInfo(default='l2tpv2'),
+                'l2tpv3-cookie-length': KeyInfo(default=0),
+                'l2tpv3-digest-hash': KeyInfo(default='md5'),
+                'max-mru': KeyInfo(default=1450),
+                'max-mtu': KeyInfo(default=1450),
+                'mrru': KeyInfo(default='disabled'),
+                'name': KeyInfo(required=True),
+                'password': KeyInfo(),
+                'profile': KeyInfo(default='default-encryption'),
+                'src-address': KeyInfo(),
+                'use-ipsec': KeyInfo(default=False),
+                'use-peer-dns': KeyInfo(default=False),
+                'user': KeyInfo(required=True),
+            },
+        ),
+    ),
     ('interface', 'l2tp-server', 'server'): APIData(
         unversioned=VersionedAPIData(
             single_value=True,
@@ -1563,23 +1664,46 @@ PATHS = {
         ),
     ),
     ('interface', 'ovpn-server', 'server'): APIData(
-        unversioned=VersionedAPIData(
-            single_value=True,
-            fully_understood=True,
-            fields={
-                'auth': KeyInfo(),
-                'cipher': KeyInfo(),
-                'default-profile': KeyInfo(default='default'),
-                'enabled': KeyInfo(default=False),
-                'keepalive-timeout': KeyInfo(default=60),
-                'mac-address': KeyInfo(),
-                'max-mtu': KeyInfo(default=1500),
-                'mode': KeyInfo(default='ip'),
-                'netmask': KeyInfo(default=24),
-                'port': KeyInfo(default=1194),
-                'require-client-certificate': KeyInfo(default=False),
-            },
-        ),
+        versioned=[
+            ('7.17', '>=', VersionedAPIData(
+                fully_understood=True,
+                fields={
+                    'auth': KeyInfo(),
+                    'cipher': KeyInfo(),
+                    'default-profile': KeyInfo(default='default'),
+                    'enabled': KeyInfo(default=False),
+                    'keepalive-timeout': KeyInfo(default=60),
+                    'mac-address': KeyInfo(),
+                    'max-mtu': KeyInfo(default=1500),
+                    'mode': KeyInfo(default='ip'),
+                    'name': KeyInfo(default=''),
+                    'netmask': KeyInfo(default=24),
+                    'port': KeyInfo(default=1194),
+                    'protocol': KeyInfo(default='tcp'),
+                    'require-client-certificate': KeyInfo(default=False),
+                    'vrf': KeyInfo(default='main'),
+                },
+            )),
+            ('7.17', '<', VersionedAPIData(
+                single_value=True,
+                fully_understood=True,
+                fields={
+                    'auth': KeyInfo(),
+                    'cipher': KeyInfo(),
+                    'default-profile': KeyInfo(default='default'),
+                    'enabled': KeyInfo(default=False),
+                    'keepalive-timeout': KeyInfo(default=60),
+                    'mac-address': KeyInfo(),
+                    'max-mtu': KeyInfo(default=1500),
+                    'mode': KeyInfo(default='ip'),
+                    'name': KeyInfo(default=''),
+                    'netmask': KeyInfo(default=24),
+                    'port': KeyInfo(default=1194),
+                    'protocol': KeyInfo(default='tcp'),
+                    'require-client-certificate': KeyInfo(default=False),
+                },
+            ))
+        ]
     ),
     ('interface', 'pppoe-server', 'server'): APIData(
         unversioned=VersionedAPIData(
@@ -1952,7 +2076,6 @@ PATHS = {
         versioned=[
             ('7.13', '>=', VersionedAPIData(
                 fully_understood=True,
-                primary_keys=('action', ),
                 fields={
                     'action': KeyInfo(default='none'),
                     'address-ranges': KeyInfo(can_disable=True),
@@ -2355,6 +2478,11 @@ PATHS = {
                 'preshared-key': KeyInfo(can_disable=True, remove_value=''),
                 'public-key': KeyInfo(),
             },
+            versioned_fields=[
+                ([('7.15', '>=')], 'name', KeyInfo()),
+                ([('7.15', '>='), ('7.17', '<')], 'is-responder', KeyInfo()),
+                ([('7.17', '>=')], 'responder', KeyInfo()),
+            ],
         ),
     ),
     ('interface', 'wireless'): APIData(
@@ -2475,6 +2603,30 @@ PATHS = {
             },
         ),
     ),
+    ('interface', 'wireless', 'access-list'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            fields={
+                'allow-signal-out-of-range': KeyInfo(default='10s'),
+                'ap-tx-limit': KeyInfo(default=0),
+                'authentication': KeyInfo(default=True),
+                'client-tx-limit': KeyInfo(default=0),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'disabled': KeyInfo(default=False),
+                'forwarding': KeyInfo(default=True),
+                'interface': KeyInfo(default='any'),
+                'mac-address': KeyInfo(default='00:00:00:00:00:00'),
+                'management-protection-key': KeyInfo(default=''),
+                'private-algo': KeyInfo(default='none'),
+                'private-key': KeyInfo(default=''),
+                'private-pre-shared-key': KeyInfo(default=''),
+                'signal-range': KeyInfo(default='-120..120'),
+                'time': KeyInfo(),
+                'vlan-id': KeyInfo(default=1),
+                'vlan-mode': KeyInfo(default='default'),
+            },
+        ),
+    ),
     ('interface', 'wireless', 'cap'): APIData(
         unversioned=VersionedAPIData(
             single_value=True,
@@ -2493,6 +2645,41 @@ PATHS = {
             },
         ),
     ),
+    ('interface', 'wireless', 'connect-list'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            fields={
+                '3gpp': KeyInfo(default=''),
+                'allow-signal-out-of-range': KeyInfo(default='10s'),
+                'area-prefix': KeyInfo(default=''),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'connect': KeyInfo(default=True),
+                'disabled': KeyInfo(default=False),
+                'interface': KeyInfo(required=True),
+                'interworking': KeyInfo(default='any'),
+                'iw-asra': KeyInfo(default='any'),
+                'iw-authentication-types': KeyInfo(),
+                'iw-connection-capabilities': KeyInfo(),
+                'iw-esr': KeyInfo(default='any'),
+                'iw-hessid': KeyInfo(default='00:00:00:00:00:00'),
+                'iw-hotspot20': KeyInfo(default='any'),
+                'iw-hotspot20-dgaf': KeyInfo(default='any'),
+                'iw-internet': KeyInfo(default='any'),
+                'iw-ipv4-availability': KeyInfo(default='any'),
+                'iw-ipv6-availability': KeyInfo(default='any'),
+                'iw-network-type': KeyInfo(default='wildcard'),
+                'iw-realms': KeyInfo(),
+                'iw-roaming-ois': KeyInfo(default=''),
+                'iw-uesa': KeyInfo(default='any'),
+                'iw-venue': KeyInfo(default='any'),
+                'mac-address': KeyInfo(default='00:00:00:00:00:00'),
+                'security-profile': KeyInfo(default='none'),
+                'signal-range': KeyInfo(default='-120..120'),
+                'ssid': KeyInfo(default=''),
+                'wireless-protocol': KeyInfo(default='any'),
+            },
+        ),
+    ),
     ('interface', 'wireless', 'security-profiles'): APIData(
         unversioned=VersionedAPIData(
             fully_understood=True,
@@ -2630,8 +2817,11 @@ PATHS = {
         unversioned=VersionedAPIData(
             single_value=True,
             fully_understood=True,
+            versioned_fields=[
+                ([('7.17', '<')], 'ddns-enabled', KeyInfo(default=False)),
+                ([('7.17', '>=')], 'ddns-enabled', KeyInfo(default='auto')),
+            ],
             fields={
-                'ddns-enabled': KeyInfo(default=False),
                 'ddns-update-interval': KeyInfo(default='none'),
                 'update-time': KeyInfo(default=True),
             },
@@ -2679,6 +2869,36 @@ PATHS = {
             },
         ),
     ),
+    ('ip', 'dhcp-server'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            primary_keys=('name', ),
+            fields={
+                'address-pool': KeyInfo(default='static-only'),
+                'allow-dual-stack-queue': KeyInfo(can_disable=True, remove_value=True),
+                'always-broadcast': KeyInfo(can_disable=True, remove_value=False),
+                'authoritative': KeyInfo(default=True),
+                'bootp-lease-time': KeyInfo(default='forever'),
+                'bootp-support': KeyInfo(can_disable=True, remove_value='static'),
+                'client-mac-limit': KeyInfo(can_disable=True, remove_value='unlimited'),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'conflict-detection': KeyInfo(can_disable=True, remove_value=True),
+                'delay-threshold': KeyInfo(can_disable=True, remove_value='none'),
+                'dhcp-option-set': KeyInfo(can_disable=True, remove_value='none'),
+                'disabled': KeyInfo(default=False),
+                'insert-queue-before': KeyInfo(can_disable=True, remove_value='first'),
+                'interface': KeyInfo(required=True),
+                'lease-script': KeyInfo(default=''),
+                'lease-time': KeyInfo(default='10m'),
+                'name': KeyInfo(),
+                'parent-queue': KeyInfo(can_disable=True, remove_value='none'),
+                'relay': KeyInfo(can_disable=True, remove_value='0.0.0.0'),
+                'server-address': KeyInfo(can_disable=True, remove_value='0.0.0.0'),
+                'use-framed-as-classless': KeyInfo(can_disable=True, remove_value=True),
+                'use-radius': KeyInfo(default=False),
+            },
+        ),
+    ),
     ('ip', 'dhcp-server', 'config'): APIData(
         unversioned=VersionedAPIData(
             single_value=True,
@@ -2734,11 +2954,14 @@ PATHS = {
         unversioned=VersionedAPIData(
             fully_understood=True,
             primary_keys=('name',),
+            versioned_fields=[
+                ([('7.16', '>=')], 'comment', KeyInfo(can_disable=True, remove_value='')),
+            ],
             fields={
                 'code': KeyInfo(required=True),
                 'name': KeyInfo(),
                 'value': KeyInfo(default=''),
-                'force': KeyInfo(),
+                'force': KeyInfo(default=False),
             },
         ),
     ),
@@ -2746,12 +2969,36 @@ PATHS = {
         unversioned=VersionedAPIData(
             fully_understood=True,
             primary_keys=('name',),
+            versioned_fields=[
+                ([('7.16', '>=')], 'comment', KeyInfo(can_disable=True, remove_value='')),
+            ],
             fields={
                 'name': KeyInfo(required=True),
                 'options': KeyInfo(),
             },
         ),
     ),
+    ('ip', 'dhcp-server', 'matcher'): APIData(
+        versioned=[
+            ('7.4', '>=', VersionedAPIData(
+                fully_understood=True,
+                primary_keys=('name', ),
+                versioned_fields=[
+                    ([('7.16', '>=')], 'comment', KeyInfo(can_disable=True, remove_value='')),
+                    ([('7.16', '>=')], 'matching-type', KeyInfo()),
+                ],
+                fields={
+                    'address-pool': KeyInfo(default='none'),
+                    'code': KeyInfo(required=True),
+                    'disabled': KeyInfo(default=False),
+                    'name': KeyInfo(required=True),
+                    'option-set': KeyInfo(),
+                    'server': KeyInfo(default='all'),
+                    'value': KeyInfo(required=True),
+                },
+            )),
+        ],
+    ),
     ('ip', 'dns'): APIData(
         unversioned=VersionedAPIData(
             single_value=True,
@@ -2760,6 +3007,7 @@ PATHS = {
                 ([('7.8', '>=')], 'doh-max-concurrent-queries', KeyInfo(default=50)),
                 ([('7.8', '>=')], 'doh-max-server-connections', KeyInfo(default=5)),
                 ([('7.8', '>=')], 'doh-timeout', KeyInfo(default='5s')),
+                ([('7.16', '>=')], 'mdns-repeat-ifaces', KeyInfo()),
             ],
             fields={
                 'allow-remote-requests': KeyInfo(),
@@ -2776,6 +3024,38 @@ PATHS = {
             },
         ),
     ),
+    ('ip', 'dns', 'adlist'): APIData(
+        versioned=[
+            ('7.15', '>=', VersionedAPIData(
+                fully_understood=True,
+                fields={
+                    'comment': KeyInfo(can_disable=True, remove_value=''),
+                    'disabled': KeyInfo(default=False),
+                    'file': KeyInfo(default=''),
+                    'match-count': KeyInfo(read_only=True),
+                    'name-count': KeyInfo(read_only=True),
+                    'ssl-verify': KeyInfo(default=True),
+                    'url': KeyInfo(default=''),
+                },
+            )),
+        ],
+    ),
+    ('ip', 'dns', 'forwarders'): APIData(
+        versioned=[
+            ('7.17', '>=', VersionedAPIData(
+                fully_understood=True,
+                required_one_of=[['dns-servers', 'doh-servers']],
+                fields={
+                    'comment': KeyInfo(can_disable=True, remove_value=''),
+                    'disabled': KeyInfo(default=False),
+                    'dns-servers': KeyInfo(default=''),
+                    'doh-servers': KeyInfo(default=''),
+                    'name': KeyInfo(required=True),
+                    'verify-doh-cert': KeyInfo(default=True),
+                },
+            )),
+        ],
+    ),
     ('ip', 'dns', 'static'): APIData(
         unversioned=VersionedAPIData(
             fully_understood=True,
@@ -2857,8 +3137,8 @@ PATHS = {
                 'jump-target': KeyInfo(can_disable=True),
                 'layer7-protocol': KeyInfo(can_disable=True),
                 'limit': KeyInfo(can_disable=True),
-                'log': KeyInfo(can_disable=True),
-                'log-prefix': KeyInfo(can_disable=True),
+                'log': KeyInfo(default=False),
+                'log-prefix': KeyInfo(default=''),
                 'nth': KeyInfo(can_disable=True),
                 'out-bridge-port': KeyInfo(can_disable=True),
                 'out-bridge-port-list': KeyInfo(can_disable=True),
@@ -2894,6 +3174,10 @@ PATHS = {
         unversioned=VersionedAPIData(
             fully_understood=True,
             stratify_keys=('chain', ),
+            versioned_fields=[
+                ([('7.19', '<')], 'passthrough', KeyInfo(can_disable=True)),
+                ([('7.19', '>=')], 'passthrough', KeyInfo(default=True)),
+            ],
             fields={
                 'action': KeyInfo(),
                 'address-list': KeyInfo(can_disable=True),
@@ -2928,8 +3212,8 @@ PATHS = {
                 'jump-target': KeyInfo(can_disable=True),
                 'layer7-protocol': KeyInfo(can_disable=True),
                 'limit': KeyInfo(can_disable=True),
-                'log': KeyInfo(can_disable=True),
-                'log-prefix': KeyInfo(can_disable=True),
+                'log': KeyInfo(default=False),
+                'log-prefix': KeyInfo(default=''),
                 'new-connection-mark': KeyInfo(can_disable=True),
                 'new-dscp': KeyInfo(can_disable=True),
                 'new-mss': KeyInfo(can_disable=True),
@@ -2945,7 +3229,6 @@ PATHS = {
                 'p2p': KeyInfo(can_disable=True),
                 'packet-mark': KeyInfo(can_disable=True),
                 'packet-size': KeyInfo(can_disable=True),
-                'passthrough': KeyInfo(can_disable=True),
                 'per-connection-classifier': KeyInfo(can_disable=True),
                 'port': KeyInfo(can_disable=True),
                 'priority': KeyInfo(can_disable=True),
@@ -3008,8 +3291,8 @@ PATHS = {
                 'jump-target': KeyInfo(can_disable=True),
                 'layer7-protocol': KeyInfo(can_disable=True),
                 'limit': KeyInfo(can_disable=True),
-                'log': KeyInfo(can_disable=True),
-                'log-prefix': KeyInfo(can_disable=True),
+                'log': KeyInfo(default=False),
+                'log-prefix': KeyInfo(default=''),
                 'nth': KeyInfo(can_disable=True),
                 'out-bridge-port': KeyInfo(can_disable=True),
                 'out-bridge-port-list': KeyInfo(can_disable=True),
@@ -3071,8 +3354,8 @@ PATHS = {
                 'ipv4-options': KeyInfo(can_disable=True),
                 'jump-target': KeyInfo(can_disable=True),
                 'limit': KeyInfo(can_disable=True),
-                'log': KeyInfo(can_disable=True),
-                'log-prefix': KeyInfo(can_disable=True),
+                'log': KeyInfo(default=False),
+                'log-prefix': KeyInfo(default=''),
                 'nth': KeyInfo(can_disable=True),
                 'out-bridge-port': KeyInfo(can_disable=True),
                 'out-bridge-port-list': KeyInfo(can_disable=True),
@@ -3205,6 +3488,9 @@ PATHS = {
         unversioned=VersionedAPIData(
             single_value=True,
             fully_understood=True,
+            versioned_fields=[
+                ([('7.9', '>=')], 'host-key-type', KeyInfo(default='rsa')),
+            ],
             fields={
                 'allow-none-crypto': KeyInfo(default=False),
                 'always-allow-password-login': KeyInfo(default=False),
@@ -3339,6 +3625,14 @@ PATHS = {
                 'request': KeyInfo(),
                 'use-peer-dns': KeyInfo(default=True),
             },
+            versioned_fields=[
+                # Mikrotik does not provide exact version in official changelogs.
+                # The 7.15 version is the earliest, found option in router config backups:
+                ([('7.15', '>=')], 'script', KeyInfo(default='')),
+                ([('7.15', '>=')], 'custom-duid', KeyInfo(default='')),
+                ([('7.15', '>=')], 'use-interface-duid', KeyInfo(default=False)),
+                ([('7.15', '>=')], 'validate-server-duid', KeyInfo(default=True)),
+            ],
         ),
     ),
     ('ipv6', 'dhcp-server'): APIData(
@@ -3662,6 +3956,22 @@ PATHS = {
             },
         ),
     ),
+    ('ipv6', 'nd', 'prefix'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            fields={
+                '6to4-interface': KeyInfo(default='none'),
+                'autonomous': KeyInfo(),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'disabled': KeyInfo(default=False),
+                'interface': KeyInfo(required=True),
+                'on-link': KeyInfo(default=True),
+                'preferred-lifetime': KeyInfo(),
+                'prefix': KeyInfo(),
+                'valid-lifetime': KeyInfo(),
+            },
+        ),
+    ),
     ('ipv6', 'nd', 'prefix', 'default'): APIData(
         unversioned=VersionedAPIData(
             single_value=True,
@@ -3856,6 +4166,9 @@ PATHS = {
                 'src-address': KeyInfo(default='0.0.0.0'),
                 'timeout': KeyInfo(default='300ms'),
             },
+            versioned_fields=[
+                ([('7.15', '>=')], 'require-message-auth', KeyInfo(default='yes-for-request-resp')),
+            ],
         ),
     ),
     ('radius', 'incoming'): APIData(
@@ -3881,6 +4194,53 @@ PATHS = {
             },
         ),
     ),
+    ('routing', 'igmp-proxy'): APIData(
+        unversioned=VersionedAPIData(
+            single_value=True,
+            fully_understood=True,
+            fields={
+                'query-interval': KeyInfo(),
+                'query-response-interval': KeyInfo(),
+                'quick-leave': KeyInfo(default=False),
+            },
+        ),
+    ),
+    ('routing', 'igmp-proxy', 'interface'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            primary_keys=('interface', ),
+            fields={
+                'alternative-subnets': KeyInfo(default=''),
+                'comment': KeyInfo(can_disable=True, remove_value=''),
+                'disabled': KeyInfo(default=False),
+                'interface': KeyInfo(),
+                'threshold': KeyInfo(),
+                'upstream': KeyInfo(default=False),
+            },
+        ),
+    ),
+    ('routing', 'bfd', 'configuration'): APIData(
+        versioned=[
+            ('7.11', '>=', VersionedAPIData(
+                fully_understood=True,
+                fields={
+                    'address-list': KeyInfo(),
+                    'addresses': KeyInfo(),
+                    'comment': KeyInfo(can_disable=True, remove_value=''),
+                    'copy-from': KeyInfo(),
+                    'disabled': KeyInfo(default=False),
+                    'forbid-bfd': KeyInfo(),
+                    'interfaces': KeyInfo(),
+                    'min-echo-rx': KeyInfo(),
+                    'min-rx': KeyInfo(),
+                    'min-tx': KeyInfo(),
+                    'multiplier': KeyInfo(),
+                    'place-before': KeyInfo(),
+                    'vrf': KeyInfo(),
+                },
+            ))
+        ],
+    ),
     ('routing', 'bfd', 'interface'): APIData(
         unversioned=VersionedAPIData(
             unknown_mechanism=True,
@@ -4001,6 +4361,44 @@ PATHS = {
             },
         ),
     ),
+    ('system', 'health', 'settings'): APIData(
+        versioned=[
+            ('7.14', '<', VersionedAPIData(
+                single_value=True,
+                fully_understood=True,
+                fields={
+                    'cpu-overtemp-check': KeyInfo(),
+                    'cpu-overtemp-startup-delay': KeyInfo(),
+                    'cpu-overtemp-threshold': KeyInfo(),
+                    'fan-control-interval': KeyInfo(can_disable=True, default='30s'),
+                    'fan-full-speed-temp': KeyInfo(default=65),
+                    'fan-min-speed-percent': KeyInfo(default=0),
+                    'fan-mode': KeyInfo(),
+                    'fan-on-threshold': KeyInfo(),
+                    'fan-switch': KeyInfo(),
+                    'fan-target-temp': KeyInfo(default=58),
+                    'use-fan': KeyInfo(),
+                },
+            )),
+            ('7.14', '>=', VersionedAPIData(
+                single_value=True,
+                fully_understood=True,
+                fields={
+                    'cpu-overtemp-check': KeyInfo(),
+                    'cpu-overtemp-startup-delay': KeyInfo(),
+                    'cpu-overtemp-threshold': KeyInfo(),
+                    'fan-control-interval': KeyInfo(default=30),
+                    'fan-full-speed-temp': KeyInfo(default=65),
+                    'fan-min-speed-percent': KeyInfo(default=12),
+                    'fan-mode': KeyInfo(),
+                    'fan-on-threshold': KeyInfo(),
+                    'fan-switch': KeyInfo(),
+                    'fan-target-temp': KeyInfo(default=58),
+                    'use-fan': KeyInfo(),
+                },
+            )),
+        ],
+    ),
     ('system', 'identity'): APIData(
         unversioned=VersionedAPIData(
             single_value=True,
@@ -4023,6 +4421,9 @@ PATHS = {
         unversioned=VersionedAPIData(
             single_value=True,
             fully_understood=True,
+            versioned_fields=[
+                ([('7.14', '>=')], 'show-at-cli-login', KeyInfo(default=False)),
+            ],
             fields={
                 'note': KeyInfo(default=''),
                 'show-at-login': KeyInfo(default=True),
@@ -4098,9 +4499,13 @@ PATHS = {
                 'boot-delay': KeyInfo(default='2s'),
                 'boot-device': KeyInfo(default='nand-if-fail-then-ethernet'),
                 'boot-protocol': KeyInfo(default='bootp'),
+                'cpu-frequency': KeyInfo(),
                 'enable-jumper-reset': KeyInfo(default=True),
                 'enter-setup-on': KeyInfo(default='any-key'),
                 'force-backup-booter': KeyInfo(default=False),
+                'memory-frequency': KeyInfo(),
+                'preboot-etherboot': KeyInfo(),
+                'preboot-etherboot-server': KeyInfo(),
                 'protected-routerboot': KeyInfo(default='disabled'),
                 'reformat-hold-button': KeyInfo(default='20s'),
                 'reformat-hold-button-max': KeyInfo(default='10m'),
@@ -4263,6 +4668,10 @@ PATHS = {
         versioned=[
             ('7', '>=', VersionedAPIData(
                 fully_understood=True,
+                versioned_fields=[
+                    ([('7.16', '>=')], 'accept-icmp-time-exceeded', KeyInfo(default=False)),
+                    ([('7.16', '>=')], 'ttl', KeyInfo(default=255)),
+                ],
                 fields={
                     'certificate': KeyInfo(),
                     'check-certificate': KeyInfo(),
@@ -4551,6 +4960,18 @@ PATHS = {
             },
         ),
     ),
+    ('interface', 'ethernet', 'switch', 'port-isolation'): APIData(
+        versioned=[
+            ('6.43', '>=', VersionedAPIData(
+                primary_keys=('name', ),
+                fully_understood=True,
+                fields={
+                    'forwarding-override': KeyInfo(),
+                    'name': KeyInfo(),
+                },
+            )),
+        ],
+    ),
     ('ip', 'dhcp-client', 'option'): APIData(
         unversioned=VersionedAPIData(
             fixed_entries=True,
@@ -4600,6 +5021,27 @@ PATHS = {
             },
         ),
     ),
+    ('ppp', 'secret'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            primary_keys=('name', ),
+            fields={
+                'caller-id': KeyInfo(default=''),
+                'disabled': KeyInfo(default=False),
+                'ipv6-routes': KeyInfo(default=''),
+                'limit-bytes-in': KeyInfo(default=0),
+                'limit-bytes-out': KeyInfo(default=0),
+                'local-address': KeyInfo(can_disable=True),
+                'name': KeyInfo(required=True),
+                'password': KeyInfo(),
+                'profile': KeyInfo(default='default'),
+                'remote-address': KeyInfo(can_disable=True),
+                'remote-ipv6-prefix': KeyInfo(can_disable=True),
+                'routes': KeyInfo(can_disable=True),
+                'service': KeyInfo(default='any'),
+            },
+        ),
+    ),
     ('routing', 'bgp', 'aggregate'): APIData(
         unversioned=VersionedAPIData(
             primary_keys=('prefix',),
@@ -4620,10 +5062,13 @@ PATHS = {
     ('routing', 'bgp', 'connection'): APIData(
         unversioned=VersionedAPIData(
             fully_understood=True,
+            versioned_fields=[
+                ([('7.19', '<')], 'address-families', KeyInfo()),
+                ([('7.19', '>=')], 'afi', KeyInfo()),
+            ],
             fields={
                 'as': KeyInfo(),
                 'add-path-out': KeyInfo(),
-                'address-families': KeyInfo(),
                 'cisco-vpls-nlri-len-fmt': KeyInfo(),
                 'cluster-id': KeyInfo(),
                 'comment': KeyInfo(),
@@ -4802,6 +5247,11 @@ PATHS = {
         unversioned=VersionedAPIData(
             fully_understood=True,
             primary_keys=('name',),
+            versioned_fields=[
+                ([('7.18', '>=')], 'remote-log-format', KeyInfo(default='default')),
+                ([('7.18', '>=')], 'remote-protocol', KeyInfo(default='udp')),
+                ([('7.18', '>=')], 'cef-event-delimiter', KeyInfo(default='\r\n')),
+            ],
             fields={
                 'bsd-syslog': KeyInfo(default=False),
                 'comment': KeyInfo(can_disable=True, remove_value=''),
@@ -4904,9 +5354,10 @@ PATHS = {
                 'protocol': KeyInfo(default='all'),
                 'src-address': KeyInfo(),
                 'src-port': KeyInfo(default='any'),
+                # The template field ca not really be changed once the item is
+                # created. This config captures the behavior best as it can
+                # i.e. template=yes is shown, template=no is hidden.
                 'template': KeyInfo(can_disable=True, remove_value=False),
-                # the tepmlate field can't really be changed once the item is created. This config captures the behavior best as it can
-                # i.e. tepmplate=yes is shown, tepmlate=no is hidden
                 'tunnel': KeyInfo(default=False),
             },
         ),
@@ -4916,6 +5367,9 @@ PATHS = {
             fixed_entries=True,
             primary_keys=('name', ),
             fully_understood=True,
+            versioned_fields=[
+                ([('7.16', '>=')], 'max-sessions', KeyInfo(default=20)),
+            ],
             fields={
                 'address': KeyInfo(),
                 'certificate': KeyInfo(),
@@ -4945,6 +5399,16 @@ PATHS = {
             },
         ),
     ),
+    ('system', 'resource', 'irq', 'rps'): APIData(
+        unversioned=VersionedAPIData(
+            fully_understood=True,
+            primary_keys=('name',),
+            fields={
+                'disabled': KeyInfo(default=False),
+                'name': KeyInfo(),
+            },
+        ),
+    ),
     ('system', 'scheduler'): APIData(
         unversioned=VersionedAPIData(
             fully_understood=True,

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)

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:
   - 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.
+  - 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,11 +33,15 @@ 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.
+      - 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
@@ -59,20 +61,21 @@ options:
   update:
     description:
       - Update config/value in RouterOS by '.id' in selected path.
-      - Example V(.id=*03 address=1.1.1.3/32) and path V(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 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.
+      - 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:
@@ -91,7 +94,8 @@ options:
       where:
         description:
           - Allows to restrict the objects returned.
-          - The conditions here must all match. An O(extended_query.where[].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:
@@ -105,7 +109,8 @@ options:
             description:
               - The operator to use for matching.
               - 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.
+              - 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
@@ -133,7 +138,8 @@ options:
                 description:
                   - The operator to use for matching.
                   - 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.
+                  - 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
@@ -150,14 +156,15 @@ options:
     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 }}"
@@ -216,8 +223,8 @@ 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
@@ -231,9 +238,9 @@ EXAMPLES = '''
     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:
@@ -255,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
-        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.
+      - 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
@@ -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 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."
+  - "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,6 +35,8 @@ attributes:
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: full
 options:
   path:
     description:
@@ -74,14 +75,30 @@ options:
       - Whether to allow that no match is found.
       - 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 O(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 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/).
+  - 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:
@@ -42,213 +43,232 @@ options:
     type: str
     choices:
     # BEGIN PATH LIST
-        - 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 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-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 align
-        - interface wireless cap
-        - 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 network
-        - ip dhcp-server option
-        - ip dhcp-server option sets
-        - 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 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 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
-        - queue interface
-        - queue simple
-        - queue tree
-        - queue type
-        - radius
-        - radius incoming
-        - routing bgp aggregate
-        - routing bgp connection
-        - routing bgp instance
-        - routing bgp network
-        - routing bgp peer
-        - routing bgp template
-        - routing filter
-        - routing filter rule
-        - routing filter select-rule
-        - routing id
-        - 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
-        - routing rule
-        - routing table
-        - 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 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
+      - 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:
@@ -295,14 +315,18 @@ options:
     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:
@@ -315,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
@@ -352,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:
@@ -377,6 +418,7 @@ def main():
         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,
@@ -405,6 +447,7 @@ def main():
     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)
 
@@ -417,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':

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,21 +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.
+  - 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:
@@ -42,222 +42,244 @@ attributes:
   platform:
     support: full
     platforms: RouterOS
+  idempotent:
+    support: full
 options:
   path:
     description:
       - Path to query.
-      - An example value is V(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 channel
-        - caps-man configuration
-        - caps-man datapath
-        - caps-man manager
-        - caps-man manager interface
-        - 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-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 align
-        - interface wireless cap
-        - 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 network
-        - ip dhcp-server option
-        - ip dhcp-server option sets
-        - 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 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 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
-        - queue interface
-        - queue simple
-        - queue tree
-        - queue type
-        - radius
-        - radius incoming
-        - routing bgp aggregate
-        - routing bgp connection
-        - routing bgp instance
-        - routing bgp network
-        - routing bgp peer
-        - routing bgp template
-        - routing filter
-        - routing filter rule
-        - routing filter select-rule
-        - routing id
-        - 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
-        - routing rule
-        - routing table
-        - 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 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
+      - 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:
@@ -285,12 +307,12 @@ options:
     default: ignore
   handle_entries_content:
     description:
-      - 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.
+      - 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.
+      - 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:
@@ -302,8 +324,8 @@ options:
     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(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:
@@ -316,9 +338,8 @@ options:
     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(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:
@@ -327,14 +348,21 @@ options:
       - 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)
@@ -372,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
 
@@ -428,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
@@ -693,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(
@@ -725,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)
@@ -837,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:
@@ -863,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:
@@ -875,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(
@@ -906,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:
@@ -1032,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:
@@ -1058,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.')
@@ -1156,6 +1225,7 @@ def main():
         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,
@@ -1187,7 +1257,9 @@ def main():
     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 O(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 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.
+      - 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
-        O(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
-        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.
+      - 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
@@ -129,9 +126,9 @@ ansible_facts:
     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.
+        - 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
@@ -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', '--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/licenses.py.license

@@ -1,3 +0,0 @@
-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>

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.json.license

@@ -1,3 +0,0 @@
-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: Ansible Project

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.json.license

@@ -1,3 +0,0 @@
-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: Ansible Project

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,9 +1,9 @@
 docs/docsite/rst/api-guide.rst rstcheck
 docs/docsite/rst/quoting.rst rstcheck
 docs/docsite/rst/ssh-guide.rst rstcheck
-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.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

@@ -1,2 +1 @@
-update-docs.py shebang
-tests/unit/compat/mock.py pylint:use-yield-from  # suggested construct does not work with Python 2
+tests/update-docs.py shebang

tests/sanity/ignore-2.18.txt

@@ -1,2 +1 @@
-update-docs.py shebang
-tests/unit/compat/mock.py pylint:use-yield-from  # suggested construct does not work with Python 2
+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.9.txt

@@ -1,9 +1,9 @@
 docs/docsite/rst/api-guide.rst rstcheck
 docs/docsite/rst/quoting.rst rstcheck
 docs/docsite/rst/ssh-guide.rst rstcheck
-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/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_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/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)
@@ -450,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)
@@ -502,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)
@@ -553,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)
@@ -606,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)
@@ -620,6 +667,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'comment': 'defconf',
                 'protocol': 'icmp',
                 'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*3',
@@ -627,6 +676,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'chain': 'input',
                 'comment': 'defconf',
                 'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*4',
@@ -634,6 +685,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'chain': 'input',
                 'comment': 'defconf',
                 'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*7',
@@ -642,6 +695,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'comment': 'defconf',
                 'disabled': False,
                 'in-interface': 'wan',
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*8',
@@ -650,6 +705,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'comment': 'defconf',
                 'connection-state': 'established',
                 'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*9',
@@ -658,6 +715,8 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 'comment': 'defconf',
                 'connection-state': 'related',
                 'disabled': False,
+                'log': False,
+                'log-prefix': '',
             },
             {
                 '.id': '*A',
@@ -666,7 +725,35 @@ class TestRouterosApiFindAndModifyModule(ModuleTestCase):
                 '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,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 (
     FAKE_ROS_VERSION, 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_info
 
 
@@ -41,8 +42,8 @@ class TestRouterosApiInfoModule(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)
@@ -53,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)
@@ -68,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)
@@ -93,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)
@@ -122,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)
@@ -155,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)
@@ -189,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)
@@ -278,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)
@@ -367,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)
@@ -402,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)
@@ -460,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)
@@ -469,8 +470,6 @@ class TestRouterosApiInfoModule(ModuleTestCase):
             {
                 '.id': '*2000010',
                 'name': 'WAN',
-                'include': '',
-                'exclude': '',
                 'comment': 'defconf',
             },
         ])
@@ -513,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)
@@ -522,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',
             },
@@ -605,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)
@@ -688,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)
@@ -776,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)
@@ -822,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 (
     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
 
 
@@ -318,8 +319,8 @@ class TestRouterosApiModifyModule(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)
@@ -331,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)
@@ -348,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)
@@ -366,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)
@@ -383,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)
@@ -400,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)
@@ -416,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)
@@ -432,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)
@@ -448,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)
@@ -466,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)
@@ -498,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)
@@ -533,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)
@@ -556,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)
@@ -591,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)
@@ -656,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)
@@ -722,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)
@@ -785,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)
@@ -844,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)
@@ -903,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)
@@ -963,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)
@@ -1017,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)
@@ -1077,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)
@@ -1128,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)
@@ -1164,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)
@@ -1212,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)
@@ -1285,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)
@@ -1340,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)
@@ -1363,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)
@@ -1386,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)
@@ -1426,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)
@@ -1466,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)
@@ -1507,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)
@@ -1551,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)
@@ -1587,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)
@@ -1621,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)
@@ -1676,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)
@@ -1729,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)
@@ -1785,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)
@@ -1847,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)
@@ -1879,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)
@@ -1911,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)
@@ -1969,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)
@@ -2005,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

@@ -11,9 +11,6 @@ Updates DOCUMENTATION of modules using module_utils._api_data with the correct l
 
 import sys
 
-# Ensure that we can import things from ansible_collections
-sys.path.append('../../..')
-
 from ansible_collections.community.routeros.plugins.module_utils._api_data import (
     PATHS,
     join_path,
@@ -26,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:]))