Netutils

netutils is a lightweight Python library providing a collection of functions designed for common network automation tasks. It aims to centralize utility logic—such as BGP ASN conversions, interface name normalization, and password encryption—to reduce code duplication in network automation scripts.

Key characteristics of the library include:

• Zero mandatory dependencies: The library does not require any external packages to run, though it may support optional dependencies that the user can opt into.
• Function-centric design: The library prefers standalone functions over complex class hierarchies.
• Flat structure: It utilizes a flat folder and file organization for simplicity.
• Docstring-driven documentation: Every public function includes examples within its docstrings to guide usage.

Netutils is a lightweight Python library providing a centralized collection of functions for common network automation tasks. It is designed to simplify repetitive operations such as:

• Converting BGP ASNs to and from dotted format.
• Normalizing interface names.
• Performing "type 5" password encryption.

The library aims to provide these utilities without adding significant overhead to your automation workflows.

To keep the core library lean, netutils uses an opt-in dependency model. Many powerful features require additional libraries to be installed separately.

If you attempt to use a function that relies on an optional dependency that is not installed (for example, calling get_napalm_getters() without having napalm installed), the function will raise an exception and warn you that the required library is missing.

Because IANA does not always provide a strict name-to-number mapping, service names may be duplicated across different port numbers. To handle this, netutils appends -secondary to the service name for subsequent occurrences.

For example, if compressnet is mapped to port 2 and port 3, the internal representation will look like:

• compressnet: port 2
• compressnet-secondary: port 3

To optimize performance and avoid loading large datasets unnecessarily, netutils uses lazy loading for OUI (Organizationally Unique Identifier) mappings. When calling functions like get_oui, the OUI_MAPPINGS dictionary is only imported from netutils.oui_mappings at runtime when the function is actually invoked.

Note that this optimization applies to the Python API; Jinja mappings will still load the full oui_mappings file as required by the template engine.

@_valid_mac
def get_oui(mac: str) -> str:
    from netutils.oui_mappings import OUI_MAPPINGS

When inheriting from ACLRule, you can implement custom logic for specific attributes by using the f"{type}_{attr}" naming convention.

• To add custom processing logic, define a method named process_{attr_name} (e.g., process_src_ip).
• To add custom matching logic, define a method named match_{attr_name} (e.g., match_dst_port).

The process and match methods will automatically discover and invoke these methods during execution.

Netutils uses Poetry instead of standard virtualenv commands.

Key Commands

• poetry shell: Creates and activates a virtual environment managed by Poetry. This ensures all subsequent commands run within the project's context.
• poetry install: Installs both main project dependencies (tool.poetry.dependencies) and development dependencies (tool.poetry.group.dev.dependencies) into the virtual environment.

Dependency Structure

Dependencies are defined in pyproject.toml:

• tool.poetry.dependencies: Main runtime dependencies.
• tool.poetry.group.dev.dependencies: Dependencies for linting, testing, and documentation building.

The netutils library provides a mapping between specific PYNTC (Python Network to Code) driver types and their corresponding normalized types. When working with network data, you can use these mappings to translate vendor-specific driver identifiers into a standardized, normalized format used across the netutils ecosystem.

| PYNTC | | NORMALIZED |
| ---------- | -- | ------ |
| arista_eos_eapi | → | arista_eos |
| cisco_aireos_ssh | → | cisco_wlc |
| cisco_asa_ssh | → | cisco_asa |
| cisco_ios_ssh | → | cisco_ios |
| cisco_iosxr_ssh | → | cisco_xr |
| cisco_nxos_nxapi | → | cisco_nxos |
| f5_tmos_icontrol | → | bigip_f5 |
| juniper_junos_netconf | → | juniper_junos |

When inheriting from ACLRule, you can add custom validation or enforcement logic using the f"{type}_*" naming convention.

• To add custom validation logic, define a method named validate_{logic_name} (e.g., validate_ip_in_network).
• To add custom enforcement logic, define a method named enforce_{logic_name}.

The validate and enforce methods will automatically discover and invoke these methods.

Ordering: By default, these methods are called in alphabetical order (as returned by Python's dir()). You can control the execution order by defining order_validate or order_enforce respectively.