Create tag module (#60)

* update requirements for tag module
* create tag module
* remove fixed flake8 excludes
* update find_current_entity to handle tags
* add tests for tag module
* add tag module documentation
* add changelog fragment for tag module

Co-authored-by: Alx Dll <porous@web.de>

Author: cmeissner

Makefile

@@ -30,7 +30,7 @@ info:
 	@echo " $(foreach PLUGIN_TYPE,$(PLUGIN_TYPES), $(PLUGIN_TYPE):\n $(foreach PLUGIN,$(basename $(notdir $(_$(PLUGIN_TYPE)))),   - $(PLUGIN)\n)\n)"
 
 lint: $(MANIFEST)
-	flake8 --ignore=E402,W503 --max-line-length=160 plugins/ tests/
+	flake8 plugins/ tests/
 
 $(MANIFEST): $(NAMESPACE)-$(NAME)-$(VERSION).tar.gz
 	ansible-galaxy collection install -p build/collections $< --force

README.md

@@ -45,6 +45,7 @@ A last option to read the docs is the docs folder in this repository.
 
 The following dependencies have to be fulfiled by the Ansible controller.
 
+* colour
 * inflection
 * ipaddress
 * phpypam>=1.0.0

changelogs/fragments/tag_module.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - add `tag_module` to `create`, `update` and `delete` tags

docs/plugins/tag_module.rst

@@ -190,6 +190,8 @@ def find_current_entity(self):
             entity = self.find_device(self.phpipam_params['hostname'])
         elif self.controller_name == 'tools/device_type':
             entity = self.find_device_type(self.phpipam_params['name'])
+        elif self.controller_name == 'tools/tags':
+            entity = self.find_by_key(self.controller_uri, self.phpipam_params['name'], key='type')
         elif 'tools' in self.controller_uri or self.controller_name in ['vlan', 'l2domain', 'vrf']:
             entity = self.find_by_key(self.controller_uri, self.phpipam_params['name'])
         else:

plugins/module_utils/phpipam_helper.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python
+
+# -*- coding: utf-8 -*-
+# (c) Christian Meißner 2021
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: tag
+version_added: 1.4.0
+short_description: Manage tags
+description:
+    - create, update and delete tags
+author:
+    - "Christian Meißner (@cmeissner)"
+options:
+    name:
+        description: Name of the given tag
+        type: str
+        required: true
+        aliases: [type]
+    show_tag:
+        description: Show tag or not
+        type: bool
+        required: false
+        default: no
+    bg_color:
+        description:
+            - Background color of the given tag
+            - Can be a valid color name or a hex code
+        type: str
+        required: true
+    fg_color:
+        description:
+            - Foreground color of the given tag
+            - Can be a valid color name or a hex code
+        type: str
+        required: true
+    compress_range:
+        description: Compress range or not
+        type: bool
+        required: false
+        default: no
+    update_tags:
+        description: Update tags or not
+        type: bool
+        required: false
+        default: no
+    is_locked:
+        description: Lock tag or not
+        type: bool
+        required: false
+        default: no
+requirements:
+    - colour
+    - inflection
+    - ipaddress
+    - phpypam>=1.0.0
+extends_documentation_fragment:
+    - codeaffen.phpipam.phpipam
+    - codeaffen.phpipam.phpipam.entity_state
+'''
+
+EXAMPLES = '''
+- name: "Create tag"
+  codeaffen.phpipam.tag:
+    username: "admin"
+    password: "s3cr3t"
+    server_url: "https://ipam.example.com"
+    name: "my tag"
+    bg_color: #ffffff
+    fg_color: #000000
+    state: present
+
+- name: "Remove tag"
+  codeaffen.phpipam.tag:
+    username: "admin"
+    password: "s3cr3t"
+    server_url: "https://ipam.example.com"
+    name: "my tag"
+    state: absent
+'''
+
+import traceback
+from ansible_collections.codeaffen.phpipam.plugins.module_utils.phpipam_helper import PhpipamEntityAnsibleModule, missing_required_lib
+try:
+    from colour import Color
+    HAS_COLOUR = True
+except ImportError:
+    HAS_COLOUR = False
+    COLOUR_IMP_ERR = traceback.format_exc()
+
+
+class PhpipamToolsTagsModule(PhpipamEntityAnsibleModule):
+    pass
+
+
+def main():
+    module = PhpipamToolsTagsModule(
+        phpipam_spec=dict(
+            id=dict(type='int', invisible=True, phpipam_name='id'),
+            name=dict(type='str', required=True, aliases=['type'], phpipam_name='type'),
+            show_tag=dict(type='bool', required=False, default=False, phpipam_name='showtag'),
+            bg_color=dict(type='str', required=True, phpipam_name='bgcolor'),
+            fg_color=dict(type='str', required=True, phpipam_name='fgcolor'),
+            compress_range=dict(type='bool', default=False),
+            update_tags=dict(type='bool', required=False, default=False, phpipam_name='updateTag'),
+            is_locked=dict(type='bool', default='no'),
+        )
+    )
+
+    def get_color_code(color):
+        try:
+            c = Color(color)
+            return c.get_hex()
+        except ValueError:
+            module.fail_json(msg="Invalid color: {}".format(color))
+
+    if not HAS_COLOUR:
+        module.fail_json(msg=missing_required_lib("colour"), exception=COLOUR_IMP_ERR)
+
+    module_params = module.phpipam_params
+
+    module_params['bg_color'] = get_color_code(module_params['bg_color'])
+    module_params['fg_color'] = get_color_code(module_params['fg_color'])
+    module_params['locked'] = 'yes' if module_params['is_locked'] else 'no'
+    module_params['compress'] = 'yes' if module_params['compress_range'] else 'no'
+
+    del(module_params['is_locked'])
+    del(module_params['compress_range'])
+
+    with module.api_connection():
+        module.run()
+
+
+if __name__ == "__main__":
+    main()

plugins/modules/tag.py

@@ -1,4 +1,5 @@
 ansible
+colour
 wheel
 jinja2 # pyup: ignore
 PyYAML~=5.3

requirements-dev.txt

@@ -1,3 +1,4 @@
+colour
 inflection
 ipaddress
 phpypam

requirements.txt

@@ -0,0 +1,36 @@
+---
+- hosts: localhost
+  collections:
+    - codeaffen.phpipam
+  gather_facts: false
+  vars_files:
+    - vars/server.yml
+    - vars/tag.yml
+  tasks:
+    - name: create tag
+      include: tasks/tag.yml
+      vars:
+        name: create tag
+        tag: "{{ base_tag_data }}"
+
+    - name: create tag again, no change
+      include: tasks/tag.yml
+      vars:
+        name: create tag again, no change
+        tag: "{{ base_tag_data }}"
+
+    - name: update tag
+      include: tasks/tag.yml
+      vars:
+        name: update tag
+        override:
+          bg_color: yellow
+        tag: "{{ base_tag_data | combine(override) }}"
+
+    - name: delete tag
+      include: tasks/tag.yml
+      vars:
+        type: delete tag
+        override:
+          state: absent
+        tag: "{{ base_tag_data | combine(override) }}"

tests/test_playbooks/tag.yml

@@ -0,0 +1,15 @@
+---
+- name: "Ensure state of tag: {{ name }}"
+  tag:
+    server_url: "{{ phpipam_server_url }}"
+    app_id: "{{ phpipam_app_id }}"
+    username: "{{ phpipam_username }}"
+    password: "{{ phpipam_password }}"
+    name: "{{ tag.name }}"
+    show_tag: "{{ tag.show_tag | default(omit) }}"
+    bg_color: "{{ tag.bg_color | default('white') }}"
+    fg_color: "{{ tag.fg_color | default('black') }}"
+    compress_range: "{{ tag.compress_range | default(omit) }}"
+    update_tags: "{{ tag.update_tags | default(omit) }}"
+    locked: "{{ tag.locked | default(omit) }}"
+    state: "{{ tag.state | default('present') }}"