Shadow Tools

shadow-tools is a lightweight Python toolbox for everyday apps and scripts. It keeps the basics in one clean package without trying to replace specialized libraries.

Install

pip install shadow-tools
pip install "shadow-tools[websocket]"  # optional WebSocket client

What is included

• HTTP requests with no required third-party dependency
• WebSocket connections through an optional extra
• Async execution for blocking jobs
• 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

from shadowtools import get, write_json, is_email

response = get("https://api.github.com")
print(response.status, response.json())
write_json("output.json", {"ready": True})
assert is_email("person@example.com")

DNS, subdomains, and test IPs

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))  # 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:

from shadowtools import generate_random_ips, reverse_dns

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

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"]
)

shadow get https://api.github.com --json
shadow json-format settings.json

WebSockets

from shadowtools.websocket import connect

socket = connect("wss://example.com/socket")
socket.send("hello")
print(socket.recv())
socket.close()

Release

Build locally with python -m build, then publish only after reviewing the generated distributions and confirming the PyPI project name is available.

License

MIT