Closes networktocode#288 - added hostname_regex function and jinja fi…

…lter

docs/dev/code_reference/hostname.md

@@ -0,0 +1,5 @@
+# Hostname
+
+::: netutils.hostname
+    options:
+        show_submodules: True

docs/user/include_jinja_list.md

@@ -19,6 +19,7 @@
 | paloalto_panos_brace_to_set | netutils.config.conversion.paloalto_panos_brace_to_set |
 | fqdn_to_ip | netutils.dns.fqdn_to_ip |
 | is_fqdn_resolvable | netutils.dns.is_fqdn_resolvable |
+| hostname_regex | netutils.hostname.hostname_regex |
 | abbreviated_interface_name | netutils.interface.abbreviated_interface_name |
 | abbreviated_interface_name_list | netutils.interface.abbreviated_interface_name_list |
 | canonical_interface_name | netutils.interface.canonical_interface_name |

netutils/hostname.py

@@ -0,0 +1,35 @@
+import re
+
+
+def hostname_regex(hostname, match_regex_string):
+    """Given a hostname string and regex string, return the regex match object or `None` if no match found
+    
+    This is useful in two primary use cases:
+
+    1. Truthy conditional check that a hostname matches a given regex
+    2. Returning regex capture groups from the hostname string
+
+    Args:
+        hostname: String representation of the device hostname
+        match_regex_string: Regex string to match against
+
+    Returns:
+        Regex match object or None if no match found
+
+    Extamples:
+        >>> from netutils.hostname import hostname_regex
+        >>> print("South Carolina" if hostname_regex("USSCAMS07", ".+SC.+\d\d") else "Not South Carolina")
+        South Carolina
+        >>>
+        >>> match = hostname_regex("USSCAMS07", "([A-Z]{2})([A-Z]{2})([A-Z]{3})(\d*)")
+        >>> match[1]
+        'US'
+        >>> match[2]
+        'SC'
+        >>> match[3]
+        'AMS'
+        >>> match[4]
+        '07'
+
+    """
+    return re.match(match_regex_string, hostname)

netutils/utils.py

@@ -20,6 +20,7 @@
     "section_config": "config.compliance.section_config",
     "fqdn_to_ip": "dns.fqdn_to_ip",
     "is_fqdn_resolvable": "dns.is_fqdn_resolvable",
+    "hostname_regex": "hostname.hostname_regex",
     "interface_range_expansion": "interface.interface_range_expansion",
     "interface_range_compress": "interface.interface_range_compress",
     "split_interface": "interface.split_interface",

tests/unit/test_hostname.py

@@ -0,0 +1,23 @@
+"""Test for the Hostname based functions."""
+
+from netutils import hostname
+
+
+def test_truthy_happy_path_case():
+    match = hostname.hostname_regex("USSCAMS07", ".+SC.+\d\d")
+    assert bool(match) is True
+
+
+def test_truthy_sad_path_case():
+    match = hostname.hostname_regex("USSCAMS07", "foobar")
+    assert bool(match) is False
+
+
+def test_capture_group_happy_path_case():
+    match = hostname.hostname_regex("USSCAMS07", "([A-Z]{2})([A-Z]{2})([A-Z]{3})(\d*)")
+    assert match[1] == "US"
+
+
+def test_capture_group_sad_path_case():
+    match = hostname.hostname_regex("USSCAMS07", "(foobar)")
+    assert match is None