Metadata-Version: 2.5
Name: shadow-tools
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
Author: William Laurento II
License: MIT
License-File: LICENSE
Keywords: async,cli,http,tools,utilities,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: websocket
Requires-Dist: websocket-client>=1.8; extra == 'websocket'
Description-Content-Type: text/markdown

# 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

```bash
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

```python
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

```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))
```

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
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
```

## WebSockets

```python
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
