shadow-tools 0.2.3__tar.gz → 0.2.5__tar.gz

{shadow_tools-0.2.3 → shadow_tools-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.2.3
+Version: 0.2.5
 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:
@@ -73,11 +74,12 @@ Reverse-DNS lookup for IP addresses:
 ```python
 from shadowtools import generate_random_ips, reverse_dns
 
-for ip in generate_random_ips(5):
-    print(reverse_dns(ip))
+for result in reverse_dns(generate_random_ips(5)):
+    print(result)  # only IPs with hostnames are shown
 
 # Or look up every generated IP at once.
 print(reverse_dns(generate_random_ips(5)))
+print(reverse_dns(generate_random_ips(5), only_hostnames=False))  # include misses
 ```
 
 ## AI app helpers

{shadow_tools-0.2.3 → shadow_tools-0.2.5}/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:
@@ -49,11 +50,12 @@ Reverse-DNS lookup for IP addresses:
 ```python
 from shadowtools import generate_random_ips, reverse_dns
 
-for ip in generate_random_ips(5):
-    print(reverse_dns(ip))
+for result in reverse_dns(generate_random_ips(5)):
+    print(result)  # only IPs with hostnames are shown
 
 # Or look up every generated IP at once.
 print(reverse_dns(generate_random_ips(5)))
+print(reverse_dns(generate_random_ips(5), only_hostnames=False))  # include misses
 ```
 
 ## AI app helpers

{shadow_tools-0.2.3 → shadow_tools-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.2.3"
+version = "0.2.5"
 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.3 → shadow_tools-0.2.5}/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.3"
+__version__ = "0.2.5"
 
 __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.3 → shadow_tools-0.2.5}/src/shadowtools/network.py

@@ -18,20 +18,22 @@ def resolve_dns(hostname: str) -> dict[str, list[str]]:
     return {kind: sorted(addresses) for kind, addresses in results.items()}
 
 
-def reverse_dns(ip: str | Iterable[str]) -> dict[str, object] | list[dict[str, object]]:
+def reverse_dns(ip: str | Iterable[str], *, only_hostnames: bool = True) -> dict[str, object] | list[dict[str, object]] | None:
     """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.
+    List lookups return only results with a hostname by default. Set
+    ``only_hostnames=False`` to include addresses without PTR records.
     """
     if not isinstance(ip, str):
-        return [reverse_dns(one_ip) for one_ip in ip]
+        results = [reverse_dns(one_ip, only_hostnames=False) for one_ip in ip]
+        return [result for result in results if not only_hostnames or result["hostname"]]
     address = ipaddress.ip_address(ip)
     try:
         hostname, aliases, _ = socket.gethostbyaddr(str(address))
         return {"ip": str(address), "hostname": hostname, "aliases": aliases}
     except (socket.herror, socket.gaierror):
-        return {"ip": str(address), "hostname": None, "aliases": []}
+        result = {"ip": str(address), "hostname": None, "aliases": []}
+        return None if only_hostnames else result
 
 
 def is_subdomain_of(hostname: str, domain: str) -> bool:
@@ -59,18 +61,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.3 → shadow_tools-0.2.5}/tests/test_core.py

@@ -1,4 +1,5 @@
 import asyncio
+import ipaddress
 
 import pytest
 
@@ -41,9 +42,10 @@ 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 reverse_dns("0.0.0.0") is None
+    assert reverse_dns("0.0.0.0", only_hostnames=False)["hostname"] is None
+    assert all(item["hostname"] for item in reverse_dns(["0.0.0.0", "127.0.0.1"]))
     assert prompt("Hi {name}", name="Will") == "Hi Will"
     assert tool_schema("lookup_dns", "Lookup DNS", {"host": {"type": "string"}})["name"] == "lookup_dns"