a-c-m
/
ansible.utils
mirror of https://github.com/ansible-collections/ansible.utils.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add previous_nth_usable filter plugin (#124) 

Add previous_nth_usable filter plugin

SUMMARY


ISSUE TYPE


New Module Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

Reviewed-by: Nathaniel Case <this.is@nathanielca.se>
Reviewed-by: Nilashish Chakraborty <nilashishchakraborty8@gmail.com>
Reviewed-by: None <None>
pull/115/head
Ashwini Mhatre 2022-01-21 23:34:36 +05:30 committed by GitHub
parent 315200166f
commit 3cb7ea10ca
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 362 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -34,6 +34,7 @@ Name | Description
[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
[ansible.utils.ipv4](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv4_filter.rst)|To filter only Ipv4 addresses Ipv4 filter is used.
[ansible.utils.param_list_compare](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.param_list_compare_filter.rst)|Generate the final param list combining/comparing base and provided parameters.
[ansible.utils.previous_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.previous_nth_usable_filter.rst)|This filter returns the previous nth usable ip within a network described by value.
[ansible.utils.reduce_on_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.reduce_on_network_filter.rst)|This filter reduces a list of addresses to only the addresses that match a given network.
[ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_filter.rst)|Flatten a complex object into a dictionary of paths and values
[ansible.utils.to_xml](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_xml_filter.rst)|Convert given JSON string to XML

3
changelogs/fragments/add_previous_nth_usable_filter.yaml Normal file
View File

@ -0,0 +1,3 @@
---
minor_changes:
- Add previous_nth_usable filter plugin.

153
docs/ansible.utils.previous_nth_usable_filter.rst Normal file
View File

@ -0,0 +1,153 @@
.. _ansible.utils.previous_nth_usable_filter:
*********************************
ansible.utils.previous_nth_usable
*********************************
**This filter returns the previous nth usable ip within a network described by value.**
Version added: 2.5.0
.. contents::
:local:
:depth: 1
Synopsis
--------
- This filter returns the previous nth usable ip within a network described by value.
- Use previous_nth_usable to find the previous nth usable IP address in relation to another within a range
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>offset</b>
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">integer</span>
</div>
</td>
<td>
</td>
<td>
</td>
<td>
<div>index value</div>
<div>previous nth usable IP address</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-"></div>
<b>value</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>subnets or individual address input for previous_nth_usable plugin</div>
</td>
</tr>
</table>
<br/>
Examples
--------
.. code-block:: yaml
#### examples
- name: previous_nth_usable returns the second usable IP address for the given IP range
debug:
msg: "{{ '192.168.122.10/24' | ansible.utils.previous_nth_usable(2) }}"
- name: If there is no usable address, it returns an empty string.
debug:
msg: "{{ '192.168.122.1/24' | ansible.utils.previous_nth_usable(2) }}"
# TASK [previous_nth_usable returns the second usable IP address for the given IP range] **************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_previous_nth_usable.yaml:9
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.122.8"
# }
#
# TASK [If there is no usable address, it returns an empty string.] *******************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_previous_nth_usable.yaml:14
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": ""
# }
Return Values
-------------
Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this filter:
.. raw:: html
<table border=0 cellpadding=0 class="documentation-table">
<tr>
<th colspan="1">Key</th>
<th>Returned</th>
<th width="100%">Description</th>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="return-"></div>
<b>data</b>
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
<div style="font-size: small">
<span style="color: purple">list</span>
/ <span style="color: purple">elements=string</span>
</div>
</td>
<td></td>
<td>
<div>Returns list with values valid for a particular query.</div>
<br/>
</td>
</tr>
</table>
<br/><br/>
Status
------
Authors
~~~~~~~
- Ashwini Mhatre (@amhatre)
.. 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.

155
plugins/filter/previous_nth_usable.py Normal file
View File

@ -0,0 +1,155 @@
# -*- coding: utf-8 -*-
# Copyright 2021 Red Hat
# GNU General Public License v3.0+
# (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
"""
filter plugin file for ipaddr filters: previous_nth_usable
"""
from __future__ import absolute_import, division, print_function
from functools import partial
from ansible_collections.ansible.utils.plugins.plugin_utils.base.ipaddr_utils import (
ipaddr,
_need_netaddr,
_first_last,
)
from ansible.errors import AnsibleFilterError
from ansible_collections.ansible.utils.plugins.module_utils.common.argspec_validate import (
AnsibleArgSpecValidator,
)
__metaclass__ = type
try:
from jinja2.filters import pass_environment
except ImportError:
from jinja2.filters import environmentfilter as pass_environment
try:
import netaddr
HAS_NETADDR = True
except ImportError:
# in this case, we'll make the filters return error messages (see bottom)
HAS_NETADDR = False
else:
class mac_linux(netaddr.mac_unix):
pass
mac_linux.word_fmt = "%.2x"
DOCUMENTATION = """
name: previous_nth_usable
author: Ashwini Mhatre (@amhatre)
version_added: "2.5.0"
short_description: This filter returns the previous nth usable ip within a network described by value.
description:
- This filter returns the previous nth usable ip within a network described by value.
- Use previous_nth_usable to find the previous nth usable IP address in relation to another within a range
options:
value:
description:
- subnets or individual address input for previous_nth_usable plugin
type: str
required: True
offset:
description:
- index value
- previous nth usable IP address
type: int
notes:
"""
EXAMPLES = r"""
#### examples
- name: previous_nth_usable returns the second usable IP address for the given IP range
debug:
msg: "{{ '192.168.122.10/24' | ansible.utils.previous_nth_usable(2) }}"
- name: If there is no usable address, it returns an empty string.
debug:
msg: "{{ '192.168.122.1/24' | ansible.utils.previous_nth_usable(2) }}"
# TASK [previous_nth_usable returns the second usable IP address for the given IP range] **************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_previous_nth_usable.yaml:9
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.122.8"
# }
#
# TASK [If there is no usable address, it returns an empty string.] *******************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_previous_nth_usable.yaml:14
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": ""
# }
"""
RETURN = """
data:
type: list
elements: str
description:
- Returns list with values valid for a particular query.
"""
@pass_environment
def _previous_nth_usable(*args, **kwargs):
"""This filter returns the previous nth usable ip within a network described by value."""
keys = ["value", "offset"]
data = dict(zip(keys, args[1:]))
data.update(kwargs)
aav = AnsibleArgSpecValidator(
data=data, schema=DOCUMENTATION, name="previous_nth_usable"
)
valid, errors, updated_data = aav.validate()
if not valid:
raise AnsibleFilterError(errors)
return previous_nth_usable(**updated_data)
def previous_nth_usable(value, offset):
"""
Returns the previous nth usable ip within a network described by value.
"""
try:
vtype = ipaddr(value, "type")
if vtype == "address":
v = ipaddr(value, "cidr")
elif vtype == "network":
v = ipaddr(value, "subnet")
v = netaddr.IPNetwork(v)
except Exception:
return False
if type(offset) != int:
raise AnsibleFilterError("Must pass in an integer")
if v.size > 1:
first_usable, last_usable = _first_last(v)
nth_ip = int(netaddr.IPAddress(int(v.ip) - offset))
if nth_ip >= first_usable and nth_ip <= last_usable:
return str(netaddr.IPAddress(int(v.ip) - offset))
class FilterModule(object):
"""IP address and network manipulation filters
"""
filter_map = {
# IP addresses and networks
"previous_nth_usable": _previous_nth_usable
}
def filters(self):
""" ipaddr filter """
if HAS_NETADDR:
return self.filter_map
else:
return dict(
(f, partial(_need_netaddr, f)) for f in self.filter_map
)

16
tests/integration/targets/utils_ipaddr_filter/tasks/previous_nth_usable.yaml Normal file
View File

@ -0,0 +1,16 @@
---
- name: previous_nth_usable filter
ansible.builtin.set_fact:
result1: "{{ '192.168.122.10/24'|ansible.utils.previous_nth_usable(2) }}"
- name: Assert result for previous_nth_usable.
assert:
that: "{{ result1 == '192.168.122.8' }}"
- name: previous_nth_usable filter
ansible.builtin.set_fact:
result1: "{{ '192.168.122.1/24'|ansible.utils.previous_nth_usable(2) }}"
- name: Assert result for ipv4.
assert:
that: "{{ result1 == '' }}"

34
tests/unit/plugins/filter/test_previous_nth_usable.py Normal file
View File

@ -0,0 +1,34 @@
# -*- coding: utf-8 -*-
# Copyright 2021 Red Hat
# GNU General Public License v3.0+
# (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
"""
Unit test file for ipwrap filter plugin
"""
from __future__ import absolute_import, division, print_function
__metaclass__ = type
import unittest
from ansible_collections.ansible.utils.plugins.filter.previous_nth_usable import (
_previous_nth_usable,
)
class Test_previous_Nth_Usable(unittest.TestCase):
def setUp(self):
pass
def test_previous_nth_usable_filter(self):
"""previous_nth_usable filter"""
args = ["", "192.168.122.10/24", 2]
result = _previous_nth_usable(*args)
self.assertEqual(result, "192.168.122.8")
def test_previous_nth_usable_with_empty_return_string(self):
"""Check ipv4 to ipv6 conversion"""
args = ["", "192.168.122.1/24", 2]
result = _previous_nth_usable(*args)
self.assertEqual(result, None)