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

shadow_tools-0.2.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+dist/
+build/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.1.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
@@ -41,6 +41,8 @@ pip install "shadow-tools[websocket]"  # optional WebSocket client
 - File and directory helpers
 - JSON and CSV reading/writing
 - Email, URL, and required-key checks
+- DNS lookup, subdomain parsing, and documentation-only test IPs
+- Provider-neutral AI prompt and tool-schema helpers
 - `shadow` command-line tool
 
 ## Quick start
@@ -54,6 +56,30 @@ write_json("output.json", {"ready": True})
 assert is_email("person@example.com")
 ```
 
+## DNS, subdomains, and test IPs
+
+```python
+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
+
+```python
+from shadowtools.ai import prompt, tool_schema
+
+message = prompt("Explain {topic} in {words} words.", topic="DNS", words=50)
+search_tool = tool_schema(
+    "search_docs", "Search internal documentation",
+    {"query": {"type": "string"}}, required=["query"]
+)
+```
+
 ```bash
 shadow get https://api.github.com --json
 shadow json-format settings.json

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

@@ -17,6 +17,8 @@ pip install "shadow-tools[websocket]"  # optional WebSocket client
 - File and directory helpers
 - JSON and CSV reading/writing
 - Email, URL, and required-key checks
+- DNS lookup, subdomain parsing, and documentation-only test IPs
+- Provider-neutral AI prompt and tool-schema helpers
 - `shadow` command-line tool
 
 ## Quick start
@@ -30,6 +32,30 @@ write_json("output.json", {"ready": True})
 assert is_email("person@example.com")
 ```
 
+## DNS, subdomains, and test IPs
+
+```python
+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
+
+```python
+from shadowtools.ai import prompt, tool_schema
+
+message = prompt("Explain {topic} in {words} words.", topic="DNS", words=50)
+search_tool = tool_schema(
+    "search_docs", "Search internal documentation",
+    {"query": {"type": "string"}}, required=["query"]
+)
+```
+
 ```bash
 shadow get https://api.github.com --json
 shadow json-format settings.json

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

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

@@ -3,12 +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 .validation import is_email, is_url, require_keys
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 __all__ = [
-    "append_text", "ensure_dir", "get", "is_email", "is_url", "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",
+    "write_json", "write_text", "resolve_dns",
 ]

shadow_tools-0.2.1/src/shadowtools/ai.py

@@ -0,0 +1,29 @@
+"""Provider-neutral building blocks for AI application code."""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+def prompt(template: str, /, **values: object) -> str:
+    """Fill a named prompt template and flag any missing variables clearly."""
+    try:
+        return template.format(**values)
+    except KeyError as exc:
+        raise ValueError(f"Missing prompt value: {exc.args[0]}") from exc
+
+
+def tool_schema(name: str, description: str, properties: Mapping[str, Any],
+                required: list[str] | None = None) -> dict[str, Any]:
+    """Create a compact JSON-schema function definition for AI tool calling."""
+    if not name.replace("_", "").isalnum():
+        raise ValueError("name may contain only letters, numbers, and underscores")
+    return {
+        "name": name,
+        "description": description,
+        "parameters": {
+            "type": "object",
+            "properties": dict(properties),
+            "required": required or [],
+            "additionalProperties": False,
+        },
+    }

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.1.0 → shadow_tools-0.2.1}/tests/test_core.py

@@ -5,6 +5,8 @@ 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.ai import prompt, tool_schema
 from shadowtools.validation import is_email, is_url, require_keys
 
 
@@ -33,3 +35,13 @@ def test_validation():
 
 def test_run_all():
     assert asyncio.run(run_all([lambda: 2, lambda: 3])) == [2, 3]
+
+
+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"