ipools 1.1.0

Efficient IP address pool management and operations for IPv4/IPv6 networks.

English | 中文

ipools

Efficient IP address pool management and operations for IPv4/IPv6 networks.

Features

• Fast add/remove/merge of IP ranges and networks
• Support for both IPv4 and IPv6
• Flexible input: CIDR, range string, tuple, object, etc.
• Efficient intersection, subtraction, and membership operations
• Output as summarized networks or raw ranges
• Pythonic API, well-tested, and production-ready
• Command-line tool for batch operations

Installation

pip install ipools

Quick Start (Python API)

from ippool import IPv4Pool, IPv6Pool

# Create a pool from CIDR and range strings
pool = IPv4Pool(["192.168.1.0/24", "10.0.0.1-10.0.0.10"])

# Add more networks
pool.add("172.16.0.0/16")

# Remove a subnet
pool.remove("192.168.1.128/25")

# Check if an IP is in the pool
print("192.168.1.5" in pool)  # True
print("192.168.2.1" in pool)  # False

# Get summarized networks
print(pool.networks)  # (IPv4Network('10.0.0.1/32'), ..., IPv4Network('172.16.0.0/16'))

# Intersection
other = IPv4Pool("10.0.0.0/8")
print(pool & other)

# Set operations examples
pool1 = IPv4Pool("192.168.1.0/24")
pool2 = IPv4Pool("192.168.1.128/25")
pool3 = IPv4Pool("192.168.2.0/24")

# Union
union = pool1 + pool2 + pool3
print(f"Union contains {union.num_addresses} IP addresses")

# Subtraction
diff = pool1 - pool2
print(f"Difference contains {diff.num_addresses} IP addresses")

# Intersection
intersection = pool1 & pool2
print(f"Intersection contains {intersection.num_addresses} IP addresses")

# IPv6 support
ipv6_pool = IPv6Pool(["2001:db8::/48", "2001:db8:1::/48"])
print(f"IPv6 pool contains {ipv6_pool.num_addresses} addresses")

# Complex operations example
# Exclude multiple small networks from a large network
large_network = IPv4Pool("10.0.0.0/8")
excluded_networks = [
    "10.0.1.0/24",
    "10.0.2.0/24", 
    "10.1.0.0/16"
]
result = large_network - excluded_networks
print(f"Remaining IP addresses after exclusion: {result.num_addresses}")

# Check if IP ranges overlap
range1 = IPv4Pool("192.168.1.0/24")
range2 = IPv4Pool("192.168.1.128/25")
if range1 & range2:
    print("IP ranges overlap")

# Get pool statistics
print(f"Pool contains {len(pool.networks)} networks")
print(f"Pool contains {len(pool.ip_ranges)} IP ranges")
print(f"Total IP count: {pool.num_addresses}")

# Create from string in batch
networks_str = """
192.168.1.0/24
10.0.0.0/8
172.16.0.0/16
"""
pool_from_str = IPv4Pool(networks_str)
print(f"Created pool with {pool_from_str.num_addresses} IPs from string")

# Copy and modify
pool_copy = pool.copy()
pool_copy.add("192.168.3.0/24")
print(f"Original pool: {pool.num_addresses} IPs, Copy: {pool_copy.num_addresses} IPs")

Command Line Usage

Install via pip, then use the ippool command:

Basic Operations

# Default merge operation (no command needed)
ippool "192.168.1.0/24,10.0.0.0/8"
ippool "192.168.1.0/24;192.168.2.0/24"
ippool "192.168.1.0/24 192.168.2.0/24"

# Subtract one pool from another (note: global options must come before subcommands)
ippool --format cidr diff "192.168.0.0/16" "192.168.1.0/24"
# Subtract multiple small networks from a large network
ippool --format cidr diff 192.168.0.0/16 "192.168.1.0/24;192.168.2.0-192.168.100.255,192.168.254.0-255"
# Load address pools from files
ippool --ipv6 diff @ippool1.txt @ippool2.txt

# Intersection of multiple pools
ippool --format json intersect "192.168.1.0/24" "192.168.1.128/25" "192.168.1.192/26"

Input Formats

# Direct input with separators (comma, semicolon, space)
ippool "192.168.1.0/24,10.0.0.0/8,172.16.0.0/16"

# Read from file
ippool @ranges.txt
ippool @"path with spaces/ranges.txt"

# Read from stdin
cat ranges.txt | ippool -
echo "192.168.1.0/24,10.0.0.0/8" | ippool -

# Mix different input sources
ippool @vpc1.txt "192.168.1.0/24" @vpc2.txt

Output Formats

# Range format (default)
ippool "192.168.1.0/24;192.168.2.0/24"
# Output: 192.168.1.0-192.168.2.255

# CIDR format
ippool --format=cidr 192.168.1.0/24,192.168.2.0/24
# Output: 192.168.1.0/24
#         192.168.2.0/24

# Statistics
ippool --format=stat "192.168.1.0/24"
# Output: Networks: 1
#         Total IPs: 256
#         Largest: 192.168.1.0/24 (256 IPs)
#         Smallest: 192.168.1.0/24 (256 IPs)

# JSON format
ippool --format=json "192.168.1.0/24"
# Output: {
#   "ranges": ["192.168.1.0-192.168.1.255"],
#   "cidr": ["192.168.1.0/24"],
#   "total_ips": 256
# }

Advanced Usage

# IPv6 support
ippool --ipv6 "2001:db8::/48" "2001:db8:1::/48"

# Output to file
ippool --format=json --output=result.json "192.168.1.0/24"

# Complex operations
ippool --format=stat "192.168.1.0/24,10.0.0.0/8,172.16.0.0/16"

# Batch processing multiple files
ippool --format=cidr -o merged.txt @file1.txt @file2.txt @file3.txt

# Process from standard input
echo "192.168.1.0/24\n10.0.0.0/8" | ippool --format=json -

overlap: Find all overlapping IP ranges and their sources

Finds all overlapping IP ranges from input (supports IPv4/IPv6, file/stdin, any format).

Usage:

ippool overlap [--ipv6] [--format plain|json] <inputs...>

• --format: Output format. plain (default) prints readable text, json prints machine-readable JSON.

Example:

ippool overlap 192.168.0.0/24 192.168.0.128/25 10.0.0.0/8

Plain output:

[192.168.0.128/25]:
    192.168.0.0/24
    192.168.0.128/25

JSON output:

ippool overlap --format json 192.168.0.0/24 192.168.0.128/25 10.0.0.0/8
[
  {
    "overlap": "192.168.0.128-192.168.0.255",
    "sources": [
      "192.168.0.0-192.168.0.255",
      "192.168.0.128-192.168.0.255"
    ]
  }
]

CLI Help

ippool --help
ippool diff --help
ippool intersect --help

Python API Detailed Examples

Network Management Scenarios

from ippool import IPv4Pool

# Scenario 1: Managing company network allocation
company_networks = IPv4Pool([
    "10.0.0.0/8",      # Headquarters network
    "172.16.0.0/12",   # Branch offices
    "192.168.0.0/16"   # Office network
])

# Department network allocation
dept_allocations = {
    "IT Department": IPv4Pool("10.0.1.0/24"),
    "Finance": IPv4Pool("10.0.2.0/24"),
    "HR": IPv4Pool("10.0.3.0/24")
}

# Check for conflicts
for dept, network in dept_allocations.items():
    if company_networks & network:
        print(f"{dept} network allocation is valid")
    else:
        print(f"{dept} network allocation is invalid")

# Scenario 2: Security policy configuration
allowed_networks = IPv4Pool("192.168.1.0/24")
blocked_ranges = IPv4Pool([
    "192.168.1.100-192.168.1.110",  # Server maintenance window
    "192.168.1.200-192.168.1.255"   # Test environment
])

# Calculate actually allowed networks
effective_allowed = allowed_networks - blocked_ranges
print(f"Actually allowed IPs: {effective_allowed.num_addresses}")

Cloud Platform Resource Management

from ippool import IPv4Pool, IPv6Pool

# Scenario 3: Cloud platform VPC management
vpc_pools = {
    "vpc-1": IPv4Pool("10.1.0.0/16"),
    "vpc-2": IPv4Pool("10.2.0.0/16"),
    "vpc-3": IPv4Pool("10.3.0.0/16")
}

# Check for IP conflicts between VPCs
def check_vpc_conflicts(vpc_pools):
    vpc_list = list(vpc_pools.values())
    for i, pool1 in enumerate(vpc_list):
        for j, pool2 in enumerate(vpc_list[i+1:], i+1):
            if pool1 & pool2:
                print(f"VPC {i+1} and VPC {j+1} have IP conflicts")
                return True
    return False

# Scenario 4: Container network planning
kubernetes_pods = IPv4Pool("10.244.0.0/16")
kubernetes_services = IPv4Pool("10.96.0.0/12")

# Ensure Pod and Service networks don't overlap
if kubernetes_pods & kubernetes_services:
    print("Warning: Pod and Service networks overlap")
else:
    print("Pod and Service network configuration is correct")

Data Analysis and Statistics

from ippool import IPv4Pool

# Scenario 5: Network traffic analysis
def analyze_network_coverage(access_logs, network_pools):
    """
    Analyze IP address coverage in access logs
    """
    # Assume access_logs is a list containing IP addresses
    accessed_ips = IPv4Pool(access_logs)
    
    results = {}
    for name, pool in network_pools.items():
        overlap = accessed_ips & pool
        coverage_rate = overlap.num_addresses / pool.num_addresses
        results[name] = {
            "total_ips": pool.num_addresses,
            "accessed_ips": overlap.num_addresses,
            "coverage_rate": coverage_rate
        }
    
    return results

# Scenario 6: Network utilization statistics
def calculate_network_utilization(allocated_pools, total_network):
    """
    Calculate network utilization
    """
    total_allocated = IPv4Pool()
    for pool in allocated_pools:
        total_allocated += pool
    
    utilization = total_allocated & total_network
    utilization_rate = utilization.num_addresses / total_network.num_addresses
    
    return {
        "total_ips": total_network.num_addresses,
        "allocated_ips": utilization.num_addresses,
        "utilization_rate": utilization_rate,
        "available_ips": total_network.num_addresses - utilization.num_addresses
    }

Automation Script Examples

from ippool import IPv4Pool
import json

# Scenario 7: Batch network configuration generation
def generate_network_configs(base_network, subnet_count, subnet_size):
    """
    Generate multiple subnet configurations from base network
    """
    base_pool = IPv4Pool(base_network)
    configs = []
    
    # Simplified processing, actual implementation needs more complex subnet division logic
    for i in range(subnet_count):
        # Example: Create subnet configuration
        config = {
            "name": f"subnet-{i+1}",
            "network": f"10.0.{i}.0/24",
            "gateway": f"10.0.{i}.1",
            "dhcp_range": f"10.0.{i}.10-10.0.{i}.254"
        }
        configs.append(config)
    
    return configs

# Scenario 8: Configuration file validation
def validate_network_config(config_file):
    """
    Validate IP address settings in network configuration file
    """
    with open(config_file, 'r') as f:
        config = json.load(f)
    
    networks = IPv4Pool()
    errors = []
    
    for item in config.get('networks', []):
        try:
            network = IPv4Pool(item['cidr'])
            # Check for overlaps
            if networks & network:
                errors.append(f"Network {item['name']} overlaps with other networks")
            networks += network
        except Exception as e:
            errors.append(f"Network {item['name']} configuration error: {e}")
    
    return errors

# Usage example
if __name__ == "__main__":
    # Validate configuration file
    errors = validate_network_config('network_config.json')
    if errors:
        print("Configuration validation failed:")
        for error in errors:
            print(f"  - {error}")
    else:
        print("Configuration validation passed")

License

MIT License. See LICENSE.

Links

• PyPI
• GitHub

Authors

• jackyspy
• Theunsafe
• tutu