Update tests and filters to include Cloudera versioning scheme (#256)

Signed-off-by: Webster Mudge <[email protected]>

Author: wmudge

plugins/filter/cm_version.py

@@ -0,0 +1,66 @@
+# Copyright 2025 Cloudera, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+---
+DOCUMENTATION:
+  name: combine_onto
+  author: Webster Mudge (@wmudge) <[email protected]>
+  short_description: combine two dictionaries
+  description:
+    - Create a dictionary (hash/associative array) as a result of merging existing dictionaries.
+    - This is the reverse of the C(ansible.builtin.combine) filter.
+  positional: _input, _dicts
+  options:
+    _input:
+      description:
+        - First dictionary to combine.
+      type: dict
+      required: true
+    _dicts:
+      description:
+        - The list of dictionaries to combine
+      type: list
+      elements: dict
+      required: true
+    recursive:
+      description:
+        - If V(True), merge elements recursively.
+      type: boolean
+      default: false
+    list_merge:
+      description: Behavior when encountering list elements.
+      type: str
+      default: replace
+      choices:
+        replace: overwrite older entries with newer ones
+        keep: discard newer entries
+        append: append newer entries to the older ones
+        prepend: insert newer entries in front of the older ones
+        append_rp: append newer entries to the older ones, overwrite duplicates
+        prepend_rp: insert newer entries in front of the older ones, discard duplicates
+
+EXAMPLES: |
+  # ab => {'a':1, 'b':2, 'c': 4}
+  ab: "{{ {'a':1, 'b':2} | cloudera.exe.combine_onto({'b':3, 'c':4}) }}"
+
+  many: "{{ dict1 | cloudera.exe.combine_onto(dict2, dict3, dict4) }}"
+
+  # defaults => {'a':{'b':3, 'c':4}, 'd': 5}
+  # customization => {'a':{'c':20}}
+  # final => {'a':{'b':3, 'c':20}, 'd': 5}
+  final: "{{ customization | cloudera.exe.combine_onto(defaults, recursive=true) }}"
+
+RETURN:
+  _value:
+    description: Resulting merge of supplied dictionaries.
+    type: dict

plugins/filter/combine_onto.yml

@@ -19,67 +19,15 @@
 
 __metaclass__ = type
 
-DOCUMENTATION = """
-name: combine_onto
-author: Webster Mudge (@wmudge) <[email protected]>
-short_description: combine two dictionaries
-description:
-    - Create a dictionary (hash/associative array) as a result of merging existing dictionaries.
-    - This is the reverse of the C(ansible.builtin.combine) filter.
-positional: _input, _dicts
-options:
-    _input:
-        description:
-            - First dictionary to combine.
-        type: dict
-        required: True
-    _dicts:
-        description:
-            - The list of dictionaries to combine
-        type: list
-        elements: dict
-        required: True
-    recursive:
-        description:
-            - If V(True), merge elements recursively.
-        type: boolean
-        default: False
-    list_merge:
-        description: Behavior when encountering list elements.
-        type: str
-        default: replace
-        choices:
-            replace: overwrite older entries with newer ones
-            keep: discard newer entries
-            append: append newer entries to the older ones
-            prepend: insert newer entries in front of the older ones
-            append_rp: append newer entries to the older ones, overwrite duplicates
-            prepend_rp: insert newer entries in front of the older ones, discard duplicates
-"""
-
-EXAMPLES = """
-# ab => {'a':1, 'b':2, 'c': 4}
-ab: "{{ {'a':1, 'b':2} | cloudera.exe.combine_onto({'b':3, 'c':4}) }}"
-
-many: "{{ dict1 | cloudera.exe.combine_onto(dict2, dict3, dict4) }}"
-
-# defaults => {'a':{'b':3, 'c':4}, 'd': 5}
-# customization => {'a':{'c':20}}
-# final => {'a':{'b':3, 'c':20}, 'd': 5}
-final: "{{ customization | cloudera.exe.combine_onto(defaults, recursive=true) }}"
-"""
-
-RETURN = """
-_value:
-    description: Resulting merge of supplied dictionaries.
-    type: dict
-"""
-
 from ansible.errors import AnsibleFilterError
 from ansible.plugins.filter.core import flatten
 from ansible.template import recursive_check_defined
 from ansible.utils.vars import merge_hash
 
+from ansible_collections.cloudera.exe.plugins.module_utils.cldr_version import (
+    ClouderaVersion,
+)
+
 
 def combine_onto(*terms, **kwargs):
     """
@@ -112,10 +60,31 @@ def combine_onto(*terms, **kwargs):
     return result
 
 
+def cldr_version(version: str):
+    """
+    Parse a Cloudera version string into its parts.
+    """
+
+    try:
+        parsed_version = ClouderaVersion(version)
+        return dict(
+            major=parsed_version.major,
+            minor=parsed_version.minor,
+            patch=parsed_version.patch,
+            prerelease=parsed_version.prerelease,
+            buildmetadata=parsed_version.buildmetadata,
+        )
+    except Exception as e:
+        raise AnsibleFilterError(orig_exc=e)
+
+
 class FilterModule(object):
-    """Derivatives of Ansible jinja2 filters"""
+    """Cloudera Ansible jinja2 filters"""
 
     def filters(self):
-        filters = {"combine_onto": combine_onto}
+        filters = {
+            "combine_onto": combine_onto,
+            "version": cldr_version,
+        }
 
         return filters

plugins/filter/core_exe.py

@@ -0,0 +1,72 @@
+# Copyright 2025 Cloudera, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+---
+DOCUMENTATION:
+  name: version
+  author: Cloudera Labs
+  short_description: Parse a Cloudera Manager version string
+  description:
+    - Cloudera Manager version string parsing.
+    - Returns a dictionary of the version parts.
+    - Cloudera versioning is an extension of Semantic Versioning that uses the C(prerelease) segment to indicate service packs or extended patch releases.
+    - Moreover, this versioning scheme allow the C(prerelease) delimiter to use whitespace (C(' ')) and dots  (C('.')) in addition to the semantic version's
+      dash (C('-')).
+  version_added: "3.0.0"
+  positional: _input
+  options:
+    _input:
+      description: A version string to parse.
+      type: dict
+      required: true
+
+EXAMPLES: |
+  - name: Parse a standard version string
+    ansible.builtin.set_fact:
+      standard: "{{ '1.2.3' | cloudera.exe.version }}"
+
+  - name: Parse a version plus build number
+    ansible.builtin.set_fact:
+      build: "{{ '1.2.3.4' | cloudera.exe.version }}"
+
+  - name: Parse a version plus service pack (as prerelease)
+    ansible.builtin.set_fact:
+      service_pack: "{{ '1.2.3 SP2' | cloudera.exe.version }}"
+
+  - name: Parse a version plus build metadata string
+    ansible.builtin.set_fact:
+      build: "{{ '1.2.3+build7' | clouder.exe.version }}"
+
+  - name: Parse a version plus prerelease and build string
+    ansible.builtin.set_fact:
+      full: "{{ '1.2.3-rc1+build7' | cloudera.exe.version }}"
+
+RETURN:
+  _value:
+    description:
+      - A dictionary of the version parts.
+      - If unable to parse the string, returns C(None).
+    type: dict
+    options:
+      major:
+        description: Major version
+      minor:
+        description: Minor version
+      patch:
+        description: Patch version
+      prerelease:
+        description: Prerelease/Service pack version
+        returned: when supported
+      buildmetadata:
+        description: Build metadata version
+        returned: when supported