shadow-tools 0.2.0__tar.gz → 0.2.1__tar.gz

{shadow_tools-0.2.0 → shadow_tools-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.2.0
+Version: 0.2.1
 Summary: A practical all-in-one Python toolkit for HTTP, WebSockets, files, data, validation, async work, and CLIs.
 Project-URL: Homepage, https://github.com/WilliamLaurento/shadow-tools
 Project-URL: Issues, https://github.com/WilliamLaurento/shadow-tools/issues
@@ -59,11 +59,13 @@ assert is_email("person@example.com")
 ## DNS, subdomains, and test IPs
 
 ```python
-from shadowtools import generate_test_ips, make_subdomain, resolve_dns
+from shadowtools import generate_random_ips, generate_test_ips, make_subdomain, resolve_dns
 
 print(make_subdomain("api", "example.com"))  # api.example.com
 print(resolve_dns("example.com"))
 print(generate_test_ips(2))  # safe documentation-only addresses
+print(generate_random_ips(5))  # mixed private, public, and special IPv4 addresses
+print(generate_random_ips(3, family=6))
 ```
 
 ## AI app helpers

{shadow_tools-0.2.0 → shadow_tools-0.2.1}/README.md

@@ -35,11 +35,13 @@ assert is_email("person@example.com")
 ## DNS, subdomains, and test IPs
 
 ```python
-from shadowtools import generate_test_ips, make_subdomain, resolve_dns
+from shadowtools import generate_random_ips, generate_test_ips, make_subdomain, resolve_dns
 
 print(make_subdomain("api", "example.com"))  # api.example.com
 print(resolve_dns("example.com"))
 print(generate_test_ips(2))  # safe documentation-only addresses
+print(generate_random_ips(5))  # mixed private, public, and special IPv4 addresses
+print(generate_random_ips(3, family=6))
 ```
 
 ## AI app helpers

{shadow_tools-0.2.0 → shadow_tools-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.2.0"
+version = "0.2.1"
 description = "A practical all-in-one Python toolkit for HTTP, WebSockets, files, data, validation, async work, and CLIs."
 readme = "README.md"
 requires-python = ">=3.10"

{shadow_tools-0.2.0 → shadow_tools-0.2.1}/src/shadowtools/__init__.py

@@ -3,13 +3,13 @@
 from .data import read_csv, read_json, write_csv, write_json
 from .files import append_text, ensure_dir, read_text, write_text
 from .http import get, request
-from .network import generate_test_ips, is_subdomain_of, make_subdomain, resolve_dns
+from .network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain, resolve_dns
 from .validation import is_email, is_url, require_keys
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
-    "append_text", "ensure_dir", "generate_test_ips", "get", "is_email", "is_subdomain_of", "is_url", "make_subdomain", "read_csv",
+    "append_text", "ensure_dir", "generate_random_ips", "generate_test_ips", "get", "is_email", "is_subdomain_of", "is_url", "make_subdomain", "read_csv",
     "read_json", "read_text", "request", "require_keys", "write_csv",
     "write_json", "write_text", "resolve_dns",
 ]

shadow_tools-0.2.1/src/shadowtools/network.py

@@ -0,0 +1,94 @@
+"""Small network helpers for DNS lookups and safe test data."""
+from __future__ import annotations
+
+import ipaddress
+import random
+import socket
+
+
+def resolve_dns(hostname: str) -> dict[str, list[str]]:
+    """Resolve a hostname into deduplicated IPv4 and IPv6 addresses."""
+    results: dict[str, set[str]] = {"ipv4": set(), "ipv6": set()}
+    for family, _, _, _, address in socket.getaddrinfo(hostname, None):
+        if family == socket.AF_INET:
+            results["ipv4"].add(address[0])
+        elif family == socket.AF_INET6:
+            results["ipv6"].add(address[0])
+    return {kind: sorted(addresses) for kind, addresses in results.items()}
+
+
+def is_subdomain_of(hostname: str, domain: str) -> bool:
+    """Return whether hostname is the domain itself or one of its subdomains."""
+    cleaned_host = hostname.lower().rstrip(".")
+    cleaned_domain = domain.lower().lstrip(".").rstrip(".")
+    return cleaned_host == cleaned_domain or cleaned_host.endswith("." + cleaned_domain)
+
+
+def make_subdomain(label: str, domain: str) -> str:
+    """Build a normalized subdomain name, such as api.example.com."""
+    label = label.strip().lower().strip(".")
+    domain = domain.strip().lower().strip(".")
+    if not label or not domain:
+        raise ValueError("label and domain are required")
+    return f"{label}.{domain}"
+
+
+def generate_test_ips(count: int = 1, *, family: int = 4) -> list[str]:
+    """Generate documentation-only IP addresses safe for examples and tests."""
+    if not 1 <= count <= 10_000:
+        raise ValueError("count must be between 1 and 10,000")
+    network = ipaddress.ip_network("2001:db8::/64" if family == 6 else "192.0.2.0/24")
+    return [str(network.network_address + random.randint(1, network.num_addresses - 2)) for _ in range(count)]
+
+
+def generate_random_ips(count: int = 1, *, family: int = 4,
+                        include_special: bool = True) -> list[str]:
+    """Generate random IPv4 or IPv6 addresses for test data and mock inputs.
+
+    When ``include_special`` is true, the results can include private, public,
+    loopback, link-local, unspecified, and (for IPv4) broadcast addresses.
+    This function only creates address strings; it never connects to them.
+    """
+    if not 1 <= count <= 10_000:
+        raise ValueError("count must be between 1 and 10,000")
+    if family not in (4, 6):
+        raise ValueError("family must be 4 or 6")
+    kinds = ["private", "public"]
+    if include_special:
+        kinds += ["loopback", "link_local", "unspecified"]
+        if family == 4:
+            kinds.append("broadcast")
+    return [_random_ip(random.choice(kinds), family) for _ in range(count)]
+
+
+def _random_ip(kind: str, family: int) -> str:
+    if family == 4:
+        if kind == "private":
+            network = random.choice([ipaddress.ip_network("10.0.0.0/8"),
+                                     ipaddress.ip_network("172.16.0.0/12"),
+                                     ipaddress.ip_network("192.168.0.0/16")])
+            return str(network.network_address + random.randint(1, network.num_addresses - 2))
+        if kind == "loopback":
+            return str(ipaddress.IPv4Address((127 << 24) | random.randint(1, (1 << 24) - 2)))
+        if kind == "link_local":
+            return str(ipaddress.IPv4Address((169 << 24) | (254 << 16) | random.randint(1, (1 << 16) - 2)))
+        if kind == "unspecified":
+            return "0.0.0.0"
+        if kind == "broadcast":
+            return "255.255.255.255"
+        while True:
+            candidate = ipaddress.IPv4Address(random.getrandbits(32))
+            if candidate.is_global:
+                return str(candidate)
+    if kind == "private":
+        return str(ipaddress.IPv6Address((0xFD << 120) | random.getrandbits(120)))
+    if kind == "loopback":
+        return "::1"
+    if kind == "link_local":
+        return str(ipaddress.IPv6Address((0xFE80 << 112) | random.getrandbits(54)))
+    if kind == "unspecified":
+        return "::"
+    while True:
+        candidate = ipaddress.IPv6Address(random.getrandbits(128))
+        if candidate.is_global:
+            return str(candidate)

{shadow_tools-0.2.0 → shadow_tools-0.2.1}/tests/test_core.py

@@ -5,7 +5,7 @@ import pytest
 from shadowtools.async_tools import run_all
 from shadowtools.data import read_csv, read_json, write_csv, write_json
 from shadowtools.files import append_text, read_text, write_text
-from shadowtools.network import generate_test_ips, is_subdomain_of, make_subdomain
+from shadowtools.network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain
 from shadowtools.ai import prompt, tool_schema
 from shadowtools.validation import is_email, is_url, require_keys
 
@@ -41,5 +41,7 @@ def test_network_and_ai_helpers():
     assert make_subdomain("API", "Example.COM") == "api.example.com"
     assert is_subdomain_of("api.example.com", "example.com")
     assert generate_test_ips(1)[0].startswith("192.0.2.")
+    assert len(generate_random_ips(3)) == 3
+    assert len(generate_random_ips(2, family=6)) == 2
     assert prompt("Hi {name}", name="Will") == "Hi Will"
     assert tool_schema("lookup_dns", "Lookup DNS", {"host": {"type": "string"}})["name"] == "lookup_dns"

shadow_tools-0.2.0/src/shadowtools/network.py

@@ -1,41 +0,0 @@
-"""Small network helpers for DNS lookups and safe test data."""
-from __future__ import annotations
-
-import ipaddress
-import random
-import socket
-
-
-def resolve_dns(hostname: str) -> dict[str, list[str]]:
-    """Resolve a hostname into deduplicated IPv4 and IPv6 addresses."""
-    results: dict[str, set[str]] = {"ipv4": set(), "ipv6": set()}
-    for family, _, _, _, address in socket.getaddrinfo(hostname, None):
-        if family == socket.AF_INET:
-            results["ipv4"].add(address[0])
-        elif family == socket.AF_INET6:
-            results["ipv6"].add(address[0])
-    return {kind: sorted(addresses) for kind, addresses in results.items()}
-
-
-def is_subdomain_of(hostname: str, domain: str) -> bool:
-    """Return whether hostname is the domain itself or one of its subdomains."""
-    cleaned_host = hostname.lower().rstrip(".")
-    cleaned_domain = domain.lower().lstrip(".").rstrip(".")
-    return cleaned_host == cleaned_domain or cleaned_host.endswith("." + cleaned_domain)
-
-
-def make_subdomain(label: str, domain: str) -> str:
-    """Build a normalized subdomain name, such as api.example.com."""
-    label = label.strip().lower().strip(".")
-    domain = domain.strip().lower().strip(".")
-    if not label or not domain:
-        raise ValueError("label and domain are required")
-    return f"{label}.{domain}"
-
-
-def generate_test_ips(count: int = 1, *, family: int = 4) -> list[str]:
-    """Generate documentation-only IP addresses safe for examples and tests."""
-    if not 1 <= count <= 10_000:
-        raise ValueError("count must be between 1 and 10,000")
-    network = ipaddress.ip_network("2001:db8::/64" if family == 6 else "192.0.2.0/24")
-    return [str(network.network_address + random.randint(1, network.num_addresses - 2)) for _ in range(count)]