shadow-tools 0.1.0__tar.gz

shadow_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Laurento II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shadow_tools-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: shadow-tools
+Version: 0.1.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
+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
+- `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")
+```
+
+```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

shadow_tools-0.1.0/README.md

@@ -0,0 +1,55 @@
+# 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
+- `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")
+```
+
+```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

shadow_tools-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shadow-tools"
+version = "0.1.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"
+license = { text = "MIT" }
+authors = [{ name = "William Laurento II" }]
+keywords = ["tools", "websocket", "http", "async", "cli", "utilities"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = []
+
+[project.optional-dependencies]
+websocket = ["websocket-client>=1.8"]
+dev = ["pytest>=8.0", "build>=1.2", "twine>=6.0"]
+
+[project.scripts]
+shadow = "shadowtools.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/WilliamLaurento/shadow-tools"
+Issues = "https://github.com/WilliamLaurento/shadow-tools/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shadowtools"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shadow_tools-0.1.0/src/shadowtools/__init__.py

@@ -0,0 +1,14 @@
+"""Shadow Tools: focused helpers for common Python automation tasks."""
+
+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 .validation import is_email, is_url, require_keys
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "append_text", "ensure_dir", "get", "is_email", "is_url", "read_csv",
+    "read_json", "read_text", "request", "require_keys", "write_csv",
+    "write_json", "write_text",
+]

shadow_tools-0.1.0/src/shadowtools/async_tools.py

@@ -0,0 +1,11 @@
+"""Async helpers that keep blocking work off the event loop."""
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Iterable
+from typing import Any
+
+
+async def run_all(functions: Iterable[Callable[[], Any]]) -> list[Any]:
+    """Run zero-argument blocking functions concurrently in worker threads."""
+    return list(await asyncio.gather(*(asyncio.to_thread(fn) for fn in functions)))

shadow_tools-0.1.0/src/shadowtools/cli.py

@@ -0,0 +1,33 @@
+"""The `shadow` command-line interface."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from . import __version__
+from .data import read_json, write_json
+from .http import get
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="shadow", description="Useful developer tools without the clutter.")
+    parser.add_argument("--version", action="version", version=f"shadow-tools {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    http_parser = commands.add_parser("get", help="Fetch a URL")
+    http_parser.add_argument("url")
+    http_parser.add_argument("--json", action="store_true", help="Pretty-print a JSON response")
+    json_parser = commands.add_parser("json-format", help="Format a JSON file")
+    json_parser.add_argument("path", type=Path)
+    args = parser.parse_args()
+    if args.command == "get":
+        response = get(args.url)
+        print(f"HTTP {response.status}")
+        print(json.dumps(response.json(), indent=2) if args.json else response.text)
+    elif args.command == "json-format":
+        write_json(args.path, read_json(args.path))
+        print(f"Formatted {args.path}")
+
+
+if __name__ == "__main__":
+    main()

shadow_tools-0.1.0/src/shadowtools/data.py

@@ -0,0 +1,39 @@
+"""JSON and CSV convenience functions."""
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+
+def read_json(path: str | Path) -> Any:
+    with Path(path).open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def write_json(path: str | Path, value: Any, *, indent: int = 2) -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("w", encoding="utf-8") as handle:
+        json.dump(value, handle, indent=indent, ensure_ascii=False)
+        handle.write("\n")
+    return target
+
+
+def read_csv(path: str | Path) -> list[dict[str, str]]:
+    with Path(path).open(newline="", encoding="utf-8") as handle:
+        return list(csv.DictReader(handle))
+
+
+def write_csv(path: str | Path, rows: Iterable[Mapping[str, Any]]) -> Path:
+    materialized = list(rows)
+    if not materialized:
+        raise ValueError("rows cannot be empty because CSV headers are unknown")
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(materialized[0]))
+        writer.writeheader()
+        writer.writerows(materialized)
+    return target

shadow_tools-0.1.0/src/shadowtools/files.py

@@ -0,0 +1,29 @@
+"""Safe, small file helpers."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def ensure_dir(path: str | Path) -> Path:
+    target = Path(path)
+    target.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def read_text(path: str | Path, *, encoding: str = "utf-8") -> str:
+    return Path(path).read_text(encoding=encoding)
+
+
+def write_text(path: str | Path, content: str, *, encoding: str = "utf-8") -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding=encoding)
+    return target
+
+
+def append_text(path: str | Path, content: str, *, encoding: str = "utf-8") -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("a", encoding=encoding) as handle:
+        handle.write(content)
+    return target

shadow_tools-0.1.0/src/shadowtools/http.py

@@ -0,0 +1,52 @@
+"""Small, dependency-free HTTP client built on urllib."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+    @property
+    def text(self) -> str:
+        charset = "utf-8"
+        content_type = self.headers.get("Content-Type", "")
+        if "charset=" in content_type.lower():
+            charset = content_type.split("charset=", 1)[1].split(";", 1)[0].strip()
+        return self.body.decode(charset, errors="replace")
+
+    def json(self) -> Any:
+        return json.loads(self.text)
+
+
+def request(method: str, url: str, *, headers: Mapping[str, str] | None = None,
+            json_body: Any | None = None, data: bytes | str | None = None,
+            timeout: float = 20) -> Response:
+    """Make an HTTP request and return a response, including HTTP error bodies."""
+    if json_body is not None and data is not None:
+        raise ValueError("Pass json_body or data, not both.")
+    final_headers = dict(headers or {})
+    if json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        final_headers.setdefault("Content-Type", "application/json")
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    req = Request(url, data=data, headers=final_headers, method=method.upper())
+    try:
+        with urlopen(req, timeout=timeout) as raw:
+            return Response(raw.status, dict(raw.headers.items()), raw.read())
+    except HTTPError as exc:
+        return Response(exc.code, dict(exc.headers.items()) if exc.headers else {}, exc.read())
+    except URLError as exc:
+        raise ConnectionError(f"Could not reach {url}: {exc.reason}") from exc
+
+
+def get(url: str, **kwargs: Any) -> Response:
+    return request("GET", url, **kwargs)

shadow_tools-0.1.0/src/shadowtools/validation.py

@@ -0,0 +1,23 @@
+"""Simple input checks for common automation code."""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from urllib.parse import urlparse
+
+_EMAIL = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+def is_email(value: str) -> bool:
+    return bool(_EMAIL.fullmatch(value))
+
+
+def is_url(value: str, *, schemes: tuple[str, ...] = ("http", "https")) -> bool:
+    parsed = urlparse(value)
+    return parsed.scheme in schemes and bool(parsed.netloc)
+
+
+def require_keys(value: Mapping[str, object], *keys: str) -> None:
+    missing = [key for key in keys if key not in value]
+    if missing:
+        raise ValueError(f"Missing required keys: {', '.join(missing)}")

shadow_tools-0.1.0/src/shadowtools/websocket.py

@@ -0,0 +1,12 @@
+"""Optional WebSocket support. Install with: pip install shadow-tools[websocket]"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def connect(url: str, **kwargs: Any) -> Any:
+    try:
+        import websocket
+    except ImportError as exc:
+        raise ImportError("WebSocket support needs `pip install shadow-tools[websocket]`.") from exc
+    return websocket.create_connection(url, **kwargs)

shadow_tools-0.1.0/tests/test_core.py

@@ -0,0 +1,35 @@
+import asyncio
+
+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.validation import is_email, is_url, require_keys
+
+
+def test_file_and_data_helpers(tmp_path):
+    note = tmp_path / "nested" / "note.txt"
+    write_text(note, "hi")
+    append_text(note, " there")
+    assert read_text(note) == "hi there"
+    payload = tmp_path / "payload.json"
+    write_json(payload, {"ok": True})
+    assert read_json(payload) == {"ok": True}
+    table = tmp_path / "table.csv"
+    write_csv(table, [{"name": "Will", "count": 1}])
+    assert read_csv(table) == [{"name": "Will", "count": "1"}]
+
+
+def test_validation():
+    assert is_email("will@example.com")
+    assert not is_email("bad email")
+    assert is_url("https://example.com/a")
+    assert not is_url("not-a-url")
+    require_keys({"a": 1}, "a")
+    with pytest.raises(ValueError):
+        require_keys({}, "missing")
+
+
+def test_run_all():
+    assert asyncio.run(run_all([lambda: 2, lambda: 3])) == [2, 3]