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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -68,6 +68,18 @@ print(generate_random_ips(5))  # mixed private, public, and special IPv4 address
 print(generate_random_ips(3, family=6))
 ```
 
+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))
+
+# Or look up every generated IP at once.
+print(reverse_dns(generate_random_ips(5)))
+```
+
 ## AI app helpers
 
 ```python

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

@@ -44,6 +44,18 @@ print(generate_random_ips(5))  # mixed private, public, and special IPv4 address
 print(generate_random_ips(3, family=6))
 ```
 
+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))
+
+# Or look up every generated IP at once.
+print(reverse_dns(generate_random_ips(5)))
+```
+
 ## AI app helpers
 
 ```python

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.2.1"
+version = "0.2.3"
 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.1 → shadow_tools-0.2.3}/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_random_ips, 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, reverse_dns
 from .validation import is_email, is_url, require_keys
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 __all__ = [
     "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",
+    "write_json", "write_text", "resolve_dns", "reverse_dns",
 ]

{shadow_tools-0.2.1 → shadow_tools-0.2.3}/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,6 +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]]:
+    """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))
+        return {"ip": str(address), "hostname": hostname, "aliases": aliases}
+    except (socket.herror, socket.gaierror):
+        return {"ip": str(address), "hostname": None, "aliases": []}
+
+
 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(".")

{shadow_tools-0.2.1 → shadow_tools-0.2.3}/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_random_ips, generate_test_ips, is_subdomain_of, make_subdomain
+from shadowtools.network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain, reverse_dns
 from shadowtools.ai import prompt, tool_schema
 from shadowtools.validation import is_email, is_url, require_keys
 
@@ -43,5 +43,7 @@ def test_network_and_ai_helpers():
     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 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"