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

shadow_tools-0.2.0/.gitignore

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.1.0
+Version: 0.2.0
 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,28 @@ write_json("output.json", {"ready": True})
 assert is_email("person@example.com")
 ```
 
+## DNS, subdomains, and test IPs
+
+```python
+from shadowtools import 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
+```
+
+## 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.0}/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,28 @@ write_json("output.json", {"ready": True})
 assert is_email("person@example.com")
 ```
 
+## DNS, subdomains, and test IPs
+
+```python
+from shadowtools import 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
+```
+
+## 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.1.0"
+version = "0.2.0"
 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.0}/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_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.0"
 
 __all__ = [
-    "append_text", "ensure_dir", "get", "is_email", "is_url", "read_csv",
+    "append_text", "ensure_dir", "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.0/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.0/src/shadowtools/network.py

@@ -0,0 +1,41 @@
+"""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)]

{shadow_tools-0.1.0 → shadow_tools-0.2.0}/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_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,11 @@ 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 prompt("Hi {name}", name="Will") == "Hi Will"
+    assert tool_schema("lookup_dns", "Lookup DNS", {"host": {"type": "string"}})["name"] == "lookup_dns"