shadow-tools 0.2.2__tar.gz → 0.2.4__tar.gz

{shadow_tools-0.2.2 → shadow_tools-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -64,8 +64,9 @@ from shadowtools import generate_random_ips, generate_test_ips, make_subdomain,
 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(5))  # globally routable public IPv4 addresses only
 print(generate_random_ips(3, family=6))
+print(generate_random_ips(3, include_private=True, include_special=True))
 ```
 
 Reverse-DNS lookup for IP addresses:
@@ -75,6 +76,9 @@ from shadowtools import generate_random_ips, reverse_dns
 
 for ip in generate_random_ips(5):
     print(reverse_dns(ip))
+
+# Or look up every generated IP at once.
+print(reverse_dns(generate_random_ips(5)))
 ```
 
 ## AI app helpers

{shadow_tools-0.2.2 → shadow_tools-0.2.4}/README.md

@@ -40,8 +40,9 @@ from shadowtools import generate_random_ips, generate_test_ips, make_subdomain,
 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(5))  # globally routable public IPv4 addresses only
 print(generate_random_ips(3, family=6))
+print(generate_random_ips(3, include_private=True, include_special=True))
 ```
 
 Reverse-DNS lookup for IP addresses:
@@ -51,6 +52,9 @@ from shadowtools import generate_random_ips, reverse_dns
 
 for ip in generate_random_ips(5):
     print(reverse_dns(ip))
+
+# Or look up every generated IP at once.
+print(reverse_dns(generate_random_ips(5)))
 ```
 
 ## AI app helpers

{shadow_tools-0.2.2 → shadow_tools-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.2.2"
+version = "0.2.4"
 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.2 → shadow_tools-0.2.4}/src/shadowtools/__init__.py

@@ -6,7 +6,7 @@ from .http import get, request
 from .network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain, resolve_dns, reverse_dns
 from .validation import is_email, is_url, require_keys
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 __all__ = [
     "append_text", "ensure_dir", "generate_random_ips", "generate_test_ips", "get", "is_email", "is_subdomain_of", "is_url", "make_subdomain", "read_csv",

{shadow_tools-0.2.2 → shadow_tools-0.2.4}/src/shadowtools/network.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import ipaddress
 import random
 import socket
+from collections.abc import Iterable
 
 
 def resolve_dns(hostname: str) -> dict[str, list[str]]:
@@ -17,12 +18,14 @@ def resolve_dns(hostname: str) -> dict[str, list[str]]:
     return {kind: sorted(addresses) for kind, addresses in results.items()}
 
 
-def reverse_dns(ip: str) -> dict[str, object]:
-    """Look up the DNS name assigned to one IPv4 or IPv6 address.
+def reverse_dns(ip: str | Iterable[str]) -> dict[str, object] | list[dict[str, object]]:
+    """Look up DNS names for one IP address or each address in a list.
 
     An address without a PTR record returns ``hostname: None`` instead of
     raising an exception.
     """
+    if not isinstance(ip, str):
+        return [reverse_dns(one_ip) for one_ip in ip]
     address = ipaddress.ip_address(ip)
     try:
         hostname, aliases, _ = socket.gethostbyaddr(str(address))
@@ -56,18 +59,23 @@ def generate_test_ips(count: int = 1, *, family: int = 4) -> list[str]:
 
 
 def generate_random_ips(count: int = 1, *, family: int = 4,
-                        include_special: bool = True) -> list[str]:
+                        include_private: bool = False,
+                        include_special: bool = False) -> 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.
+    By default, results are globally routable public addresses only. Set
+    ``include_private=True`` to include private ranges, or
+    ``include_special=True`` to include loopback, link-local, unspecified, and
+    broadcast-style 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"]
+    kinds = ["public"]
+    if include_private:
+        kinds.append("private")
     if include_special:
         kinds += ["loopback", "link_local", "unspecified"]
         if family == 4:

{shadow_tools-0.2.2 → shadow_tools-0.2.4}/tests/test_core.py

@@ -1,4 +1,5 @@
 import asyncio
+import ipaddress
 
 import pytest
 
@@ -41,8 +42,9 @@ 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 all(ipaddress.ip_address(ip).is_global for ip in generate_random_ips(3))
     assert len(generate_random_ips(2, family=6)) == 2
     assert reverse_dns("0.0.0.0")["hostname"] is None
+    assert len(reverse_dns(["0.0.0.0", "127.0.0.1"])) == 2
     assert prompt("Hi {name}", name="Will") == "Hi Will"
     assert tool_schema("lookup_dns", "Lookup DNS", {"host": {"type": "string"}})["name"] == "lookup_dns"