Restructured libraries

filter_plugins/README.md

@@ -0,0 +1,27 @@
+# Custom Filter Plugins for CyMaIS
+
+This directory contains custom **Ansible filter plugins** used within the CyMaIS project.
+
+## When to Use a Filter Plugin
+
+- **Transform values:** Use filters to transform, extract, reformat, or compute values from existing variables or facts.
+- **Inline data manipulation:** Filters are designed for inline use in Jinja2 expressions (in templates, tasks, vars, etc.).
+- **No external lookups:** Filters only operate on data you explicitly pass to them and cannot access external files, the Ansible inventory, or runtime context.
+
+### Examples
+
+```jinja2
+{{ role_name | get_entity_name }}
+{{ my_list | unique }}
+{{ user_email | regex_replace('^(.+)@.*$', '\\1') }}
+````
+
+## When *not* to Use a Filter Plugin
+
+* If you need to **load data from an external source** (e.g., file, environment, API), use a lookup plugin instead.
+* If your logic requires **access to inventory, facts, or host-level information** that is not passed as a parameter.
+
+## Further Reading
+
+* [Ansible Filter Plugins Documentation](https://docs.ansible.com/ansible/latest/plugins/filter.html)
+* [Developing Ansible Filter Plugins](https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#developing-filter-plugins)

filter_plugins/get_application_id.py

@@ -1,5 +1,3 @@
-# filter_plugins/get_application_id.py
-
 import os
 import re
 import yaml

filter_plugins/get_docker_paths.py

@@ -1,4 +1,4 @@
-def get_docker_compose(path_docker_compose_instances: str, application_id: str) -> dict:
+def get_docker_paths(path_docker_compose_instances: str, application_id: str) -> dict:
     """
     Build the docker_compose dict based on
     path_docker_compose_instances and application_id.
@@ -23,5 +23,5 @@ def get_docker_compose(path_docker_compose_instances: str, application_id: str)
 class FilterModule(object):
     def filters(self):
         return {
-            'get_docker_compose':   get_docker_compose,
+            'get_docker_paths':   get_docker_paths,
         }

filter_plugins/get_public_id.py

@@ -1,17 +0,0 @@
-class FilterModule(object):
-    def filters(self):
-        return {
-            'get_public_id': self.get_public_id
-        }
-
-    def get_public_id(self, value):
-        """
-        Extract the substring after the last hyphen in the input string.
-        Example:
-          'service-user-abc123' => 'abc123'
-        """
-        if not isinstance(value, str):
-            raise ValueError("Expected a string")
-        if '-' not in value:
-            raise ValueError("No hyphen found in input string")
-        return value.rsplit('-', 1)[-1]

filter_plugins/role_path_by_app_id.py

@@ -1,5 +1,3 @@
-# filter_plugins/role_path_by_app_id.py
-
 import os
 import glob
 import yaml

filter_plugins/safe_join.py

@@ -1,4 +1,3 @@
-# file: filter_plugins/safe_join.py
 """
 Ansible filter plugin that joins a base string and a tail path safely.
 If the base is falsy (None, empty, etc.), returns an empty string.

filter_plugins/text_filters.py

@@ -1,5 +1,3 @@
-# filter_plugins/text_filters.py
-
 from ansible.errors import AnsibleFilterError
 import re