shadow-tools 0.2.5__tar.gz → 0.3.0__tar.gz

{shadow_tools-0.2.5 → shadow_tools-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.2.5
+Version: 0.3.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
@@ -43,6 +43,9 @@ pip install "shadow-tools[websocket]"  # optional WebSocket client
 - Email, URL, and required-key checks
 - DNS lookup, subdomain parsing, and documentation-only test IPs
 - Provider-neutral AI prompt and tool-schema helpers
+- File and text hashing
+- UUIDs, secure tokens, and timestamp IDs
+- Slugs, snake/camel case, chunks, environment variables, and retry logic
 - `shadow` command-line tool
 
 ## Quick start
@@ -94,6 +97,23 @@ search_tool = tool_schema(
 )
 ```
 
+## Everyday helpers
+
+```python
+from shadowtools import hash_text, random_token, slugify, to_bool, uuid4
+
+print(hash_text("hello"))
+print(random_token())
+print(uuid4())
+print(slugify("Shadow Tools: Version 3!"))  # shadow-tools-version-3
+print(to_bool("yes"))  # True
+```
+
+```bash
+shadow hash settings.json
+shadow uuid
+```
+
 ```bash
 shadow get https://api.github.com --json
 shadow json-format settings.json

{shadow_tools-0.2.5 → shadow_tools-0.3.0}/README.md

@@ -19,6 +19,9 @@ pip install "shadow-tools[websocket]"  # optional WebSocket client
 - Email, URL, and required-key checks
 - DNS lookup, subdomain parsing, and documentation-only test IPs
 - Provider-neutral AI prompt and tool-schema helpers
+- File and text hashing
+- UUIDs, secure tokens, and timestamp IDs
+- Slugs, snake/camel case, chunks, environment variables, and retry logic
 - `shadow` command-line tool
 
 ## Quick start
@@ -70,6 +73,23 @@ search_tool = tool_schema(
 )
 ```
 
+## Everyday helpers
+
+```python
+from shadowtools import hash_text, random_token, slugify, to_bool, uuid4
+
+print(hash_text("hello"))
+print(random_token())
+print(uuid4())
+print(slugify("Shadow Tools: Version 3!"))  # shadow-tools-version-3
+print(to_bool("yes"))  # True
+```
+
+```bash
+shadow hash settings.json
+shadow uuid
+```
+
 ```bash
 shadow get https://api.github.com --json
 shadow json-format settings.json

{shadow_tools-0.2.5 → shadow_tools-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.2.5"
+version = "0.3.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.3.0/src/shadowtools/__init__.py

@@ -0,0 +1,20 @@
+"""Shadow Tools: focused helpers for common Python automation tasks."""
+
+from .data import read_csv, read_json, write_csv, write_json
+from .config import env, require_env, to_bool
+from .files import append_text, ensure_dir, read_text, write_text
+from .hashing import file_hash, hash_text
+from .http import get, request
+from .ids import random_token, timestamp_id, uuid4
+from .network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain, resolve_dns, reverse_dns
+from .retry import retry
+from .text import chunks, slugify, to_camel, to_snake
+from .validation import is_email, is_url, require_keys
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "append_text", "chunks", "ensure_dir", "env", "file_hash", "generate_random_ips", "generate_test_ips", "get", "hash_text", "is_email", "is_subdomain_of", "is_url", "make_subdomain", "random_token", "read_csv",
+    "read_json", "read_text", "request", "require_env", "require_keys", "retry", "reverse_dns", "resolve_dns", "slugify", "timestamp_id", "to_bool", "to_camel", "to_snake", "uuid4", "write_csv",
+    "write_json", "write_text",
+]

{shadow_tools-0.2.5 → shadow_tools-0.3.0}/src/shadowtools/cli.py

@@ -8,6 +8,8 @@ from pathlib import Path
 from . import __version__
 from .data import read_json, write_json
 from .http import get
+from .hashing import file_hash
+from .ids import uuid4
 
 
 def main() -> None:
@@ -19,6 +21,9 @@ def main() -> None:
     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)
+    hash_parser = commands.add_parser("hash", help="Print a file SHA-256 checksum")
+    hash_parser.add_argument("path", type=Path)
+    commands.add_parser("uuid", help="Create a UUID")
     args = parser.parse_args()
     if args.command == "get":
         response = get(args.url)
@@ -27,6 +32,10 @@ def main() -> None:
     elif args.command == "json-format":
         write_json(args.path, read_json(args.path))
         print(f"Formatted {args.path}")
+    elif args.command == "hash":
+        print(file_hash(args.path))
+    elif args.command == "uuid":
+        print(uuid4())
 
 
 if __name__ == "__main__":

shadow_tools-0.3.0/src/shadowtools/config.py

@@ -0,0 +1,23 @@
+"""Environment-variable helpers."""
+from __future__ import annotations
+
+import os
+
+
+def env(name: str, default: str | None = None) -> str | None:
+    return os.environ.get(name, default)
+
+
+def require_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise EnvironmentError(f"Required environment variable is missing: {name}")
+    return value
+
+
+def to_bool(value: str | bool | int | None, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in {"1", "true", "yes", "on", "y"}

shadow_tools-0.3.0/src/shadowtools/hashing.py

@@ -0,0 +1,17 @@
+"""Checksums for text and files."""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def hash_text(value: str, algorithm: str = "sha256") -> str:
+    return hashlib.new(algorithm, value.encode("utf-8")).hexdigest()
+
+
+def file_hash(path: str | Path, algorithm: str = "sha256", *, chunk_size: int = 65_536) -> str:
+    digest = hashlib.new(algorithm)
+    with Path(path).open("rb") as handle:
+        for chunk in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(chunk)
+    return digest.hexdigest()

shadow_tools-0.3.0/src/shadowtools/ids.py

@@ -0,0 +1,20 @@
+"""IDs and secure random tokens."""
+from __future__ import annotations
+
+import secrets
+import time
+import uuid
+
+
+def uuid4() -> str:
+    return str(uuid.uuid4())
+
+
+def random_token(length: int = 32) -> str:
+    if not 8 <= length <= 256:
+        raise ValueError("length must be between 8 and 256")
+    return secrets.token_urlsafe(length)[:length]
+
+
+def timestamp_id(prefix: str = "item") -> str:
+    return f"{prefix}_{int(time.time() * 1000)}_{secrets.token_hex(3)}"

shadow_tools-0.3.0/src/shadowtools/retry.py

@@ -0,0 +1,28 @@
+"""Simple retry support for temporary failures."""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+def retry(attempts: int = 3, *, delay: float = 0.25,
+          exceptions: tuple[type[Exception], ...] = (Exception,)) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    if attempts < 1:
+        raise ValueError("attempts must be at least 1")
+
+    def decorate(function: Callable[P, T]) -> Callable[P, T]:
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> T:
+            for attempt in range(attempts):
+                try:
+                    return function(*args, **kwargs)
+                except exceptions:
+                    if attempt == attempts - 1:
+                        raise
+                    time.sleep(delay * (2 ** attempt))
+            raise RuntimeError("unreachable")
+        return wrapped
+    return decorate

shadow_tools-0.3.0/src/shadowtools/text.py

@@ -0,0 +1,33 @@
+"""Plain text cleanup and naming helpers."""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import TypeVar
+
+T = TypeVar("T")
+_WORDS = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+")
+
+
+def _words(value: str) -> list[str]:
+    return _WORDS.findall(value.replace("-", " ").replace("_", " "))
+
+
+def slugify(value: str) -> str:
+    return "-".join(word.lower() for word in _words(value))
+
+
+def to_snake(value: str) -> str:
+    return "_".join(word.lower() for word in _words(value))
+
+
+def to_camel(value: str) -> str:
+    words = _words(value)
+    return "".join(word[:1].upper() + word[1:].lower() for word in words)
+
+
+def chunks(items: Iterable[T], size: int) -> list[list[T]]:
+    if size < 1:
+        raise ValueError("size must be at least 1")
+    values = list(items)
+    return [values[index:index + size] for index in range(0, len(values), size)]

{shadow_tools-0.2.5 → shadow_tools-0.3.0}/tests/test_core.py

@@ -8,6 +8,10 @@ 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, reverse_dns
 from shadowtools.ai import prompt, tool_schema
+from shadowtools.config import to_bool
+from shadowtools.hashing import hash_text
+from shadowtools.ids import random_token
+from shadowtools.text import chunks, slugify, to_camel, to_snake
 from shadowtools.validation import is_email, is_url, require_keys
 
 
@@ -47,5 +51,15 @@ def test_network_and_ai_helpers():
     assert reverse_dns("0.0.0.0") is None
     assert reverse_dns("0.0.0.0", only_hostnames=False)["hostname"] is None
     assert all(item["hostname"] for item in reverse_dns(["0.0.0.0", "127.0.0.1"]))
+
+
+def test_general_utilities():
+    assert hash_text("hello") == "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+    assert len(random_token(16)) == 16
+    assert slugify("Shadow Tools V3") == "shadow-tools-v-3"
+    assert to_snake("ShadowTools") == "shadow_tools"
+    assert to_camel("shadow tools") == "ShadowTools"
+    assert chunks(range(5), 2) == [[0, 1], [2, 3], [4]]
+    assert to_bool("yes")
     assert prompt("Hi {name}", name="Will") == "Hi Will"
     assert tool_schema("lookup_dns", "Lookup DNS", {"host": {"type": "string"}})["name"] == "lookup_dns"

shadow_tools-0.2.5/src/shadowtools/__init__.py

@@ -1,15 +0,0 @@
-"""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 .network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain, resolve_dns, reverse_dns
-from .validation import is_email, is_url, require_keys
-
-__version__ = "0.2.5"
-
-__all__ = [
-    "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", "resolve_dns", "reverse_dns",
-]