Segregate filter plugins (#578)

* vlan expander saved * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add a trivial changelog * add a test considering it breaks others * some more test fixes * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * vlan_parser fix * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add parse_xml * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add type5_pw * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * thy formalities * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add parse_cli_textfsm * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * update parse_xml * fix parse_xml * add parse_cli * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix doc and sanity * add hash_salt * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add test hash_salt * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add comp_type5 * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix Unit test * fix sanity * update test to assert on skip * workflow fix * add original authors * update all docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Fix Filter errors * generate docs * update security issues --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
ansible-collections · Aug 22, 2023 · a07256b · a07256b
1 parent 46dcfcd
commit a07256b
Show file tree

Hide file tree

Showing 35 changed files with 3,249 additions and 537 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -36,10 +36,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - run: >-
-          python -c "assert set([
+          python -c "assert 'failure' not in
+          set([
           '${{ needs.ansible-lint.result }}',
           '${{ needs.changelog.result }}',
           '${{ needs.sanity.result }}',
           '${{ needs.unit-galaxy.result }}',
           '${{ needs.unit-source.result }}'
-          ]) == {'success'}"
+          ])"
diff --git a/.gitignore b/.gitignore
@@ -108,3 +108,6 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# vs code configuration
+.vscode/
diff --git a/README.md b/README.md
@@ -44,21 +44,15 @@ Name | Description
 ### Filter plugins
 Name | Description
 --- | ---
+[ansible.netcommon.comp_type5](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.comp_type5_filter.rst)|The comp_type5 filter plugin.
+[ansible.netcommon.hash_salt](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.hash_salt_filter.rst)|The hash_salt filter plugin.
+[ansible.netcommon.parse_cli](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.parse_cli_filter.rst)|parse_cli filter plugin.
+[ansible.netcommon.parse_cli_textfsm](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.parse_cli_textfsm_filter.rst)|parse_cli_textfsm filter plugin.
+[ansible.netcommon.parse_xml](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.parse_xml_filter.rst)|The parse_xml filter plugin.
 [ansible.netcommon.pop_ace](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.pop_ace_filter.rst)|Remove ace entries from a acl source of truth.
-
-### Network filter plugins
-Filters for working with output from network devices
-
-Name | Description
---- | ---
-ansible.netcommon.comp_type5|ansible.netcommon comp_type5 filter plugin
-ansible.netcommon.hash_salt|ansible.netcommon hash_salt filter plugin
-ansible.netcommon.parse_cli|ansible.netcommon parse_cli filter plugin
-ansible.netcommon.parse_cli_textfsm|ansible.netcommon parse_cli_textfsm filter plugin
-ansible.netcommon.parse_xml|ansible.netcommon parse_xml filter plugin
-ansible.netcommon.type5_pw|ansible.netcommon type5_pw filter plugin
-ansible.netcommon.vlan_expander|ansible.netcommon vlan_expander filter plugin
-ansible.netcommon.vlan_parser|Input: Unsorted list of vlan integers
+[ansible.netcommon.type5_pw](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.type5_pw_filter.rst)|The type5_pw filter plugin.
+[ansible.netcommon.vlan_expander](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.vlan_expander_filter.rst)|The vlan_expander filter plugin.
+[ansible.netcommon.vlan_parser](https://github.com/ansible-collections/ansible.netcommon/blob/main/docs/ansible.netcommon.vlan_parser_filter.rst)|The vlan_parser filter plugin.
 
 ### Httpapi plugins
 Name | Description

diff --git a/changelogs/fragments/vlan_extender.yaml b/changelogs/fragments/vlan_extender.yaml
@@ -0,0 +1,10 @@
+---
+trivial:
+  - vlan_expander - Filter plugin updated as individual plugin.
+  - vlan_parser - Filter plugin updated as individual plugin.
+  - type5_pw - Filter plugin updated as individual plugin.
+  - parse_xml - Filter plugin updated as individual plugin.
+  - comp_type5 - Filter plugin updated as individual plugin.
+  - hash_salt - Filter plugin updated as individual plugin.
+  - parse_cli - Filter plugin updated as individual plugin.
+  - parse_cli_textfsm - Filter plugin updated as individual plugin.
diff --git a/docs/ansible.netcommon.comp_type5_filter.rst b/docs/ansible.netcommon.comp_type5_filter.rst
@@ -0,0 +1,152 @@
+.. _ansible.netcommon.comp_type5_filter:
+
+
+****************************
+ansible.netcommon.comp_type5
+****************************
+
+**The comp_type5 filter plugin.**
+
+
+Version added: 1.0.0
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- The filter confirms configuration idempotency on use of type5_pw.
+
+
+
+
+Parameters
+----------
+
+.. raw:: html
+
+    <table  border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th colspan="1">Parameter</th>
+            <th>Choices/<font color="blue">Defaults</font></th>
+                <th>Configuration</th>
+            <th width="100%">Comments</th>
+        </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>encrypted_password</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                         / <span style="color: red">required</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                    <td>
+                    </td>
+                <td>
+                        <div>The encrypted text.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>return_original</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">boolean</span>
+                    </div>
+                </td>
+                <td>
+                        <ul style="margin: 0; padding: 0"><b>Choices:</b>
+                                    <li>no</li>
+                                    <li>yes</li>
+                        </ul>
+                </td>
+                    <td>
+                    </td>
+                <td>
+                        <div>Return the original text.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>unencrypted_password</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                         / <span style="color: red">required</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                    <td>
+                    </td>
+                <td>
+                        <div>The unencrypted text.</div>
+                </td>
+            </tr>
+    </table>
+    <br/>
+
+
+Notes
+-----
+
+.. note::
+   - The filter confirms configuration idempotency on use of type5_pw.
+   - Can be used to validate password post hashing username cisco secret 5 {{ ansible_ssh_pass | ansible.netcommon.comp_type5(encrypted, True) }}
+
+
+
+Examples
+--------
+
+.. code-block:: yaml
+
+    # Using comp_type5
+
+    # playbook
+
+    - name: Set the facts
+      ansible.builtin.set_fact:
+        unencrypted_password: "cisco@123"
+        encrypted_password: "$1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/"
+
+    - name: Invoke comp_type5
+      ansible.builtin.debug:
+        msg: "{{ unencrypted_password | ansible.netcommon.comp_type5(encrypted_password, False) }}"
+
+    # Task Output
+    # -----------
+    #
+    # TASK [Set the facts]
+    # ok: [35.155.113.92] => changed=false
+    #   ansible_facts:
+    #     encrypted_password: $1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/
+    #     unencrypted_password: cisco@123
+
+    # TASK [Invoke comp_type5]
+    # ok: [35.155.113.92] =>
+    #   msg: true
+
+
+
+
+Status
+------
+
+
+Authors
+~~~~~~~
+
+- Ken Celenza (@itdependsnetworks)
+
+
+.. hint::
+    Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.
diff --git a/docs/ansible.netcommon.hash_salt_filter.rst b/docs/ansible.netcommon.hash_salt_filter.rst
@@ -0,0 +1,113 @@
+.. _ansible.netcommon.hash_salt_filter:
+
+
+***************************
+ansible.netcommon.hash_salt
+***************************
+
+**The hash_salt filter plugin.**
+
+
+Version added: 1.0.0
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- The filter plugin produces the salt from a hashed password.
+- Using the parameters below - ``password | ansible.netcommon.hash_salt(template.yml``)
+
+
+
+
+Parameters
+----------
+
+.. raw:: html
+
+    <table  border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th colspan="1">Parameter</th>
+            <th>Choices/<font color="blue">Defaults</font></th>
+                <th>Configuration</th>
+            <th width="100%">Comments</th>
+        </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>password</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                         / <span style="color: red">required</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                    <td>
+                    </td>
+                <td>
+                        <div>This source data on which hash_salt invokes.</div>
+                        <div>For example <code>password | ansible.netcommon.hash_salt</code>, in this case <code>password</code> represents the hashed password.</div>
+                </td>
+            </tr>
+    </table>
+    <br/>
+
+
+Notes
+-----
+
+.. note::
+   - The filter plugin produces the salt from a hashed password.
+
+
+
+Examples
+--------
+
+.. code-block:: yaml
+
+    # Using hash_salt
+
+    # playbook
+
+    - name: Set the facts
+      ansible.builtin.set_fact:
+        password: "$1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/"
+
+    - name: Invoke hash_salt
+      ansible.builtin.debug:
+        msg: "{{ password | ansible.netcommon.hash_salt() }}"
+
+
+    # Task Output
+    # -----------
+    #
+    # TASK [Set the facts]
+    # ok: [host] => changed=false
+    #   ansible_facts:
+    #     password: $1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/
+
+    # TASK [Invoke hash_salt]
+    # ok: [host] =>
+    #   msg: avs
+
+
+
+
+Status
+------
+
+
+Authors
+~~~~~~~
+
+- Ken Celenza (@itdependsnetworks)
+
+
+.. hint::
+    Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.