kroxy 1.0.2__tar.gz → 1.0.3__tar.gz

{kroxy-1.0.2/kroxy.egg-info → kroxy-1.0.3}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: kroxy
-Version: 1.0.2
+Version: 1.0.3
 Summary: A powerful Python toolkit for building automation, integrations, and bots.
 Author-email: kroxy <kroxy@example.com>
 License-Expression: LicenseRef-Proprietary
 Project-URL: Homepage, https://pypi.org/project/kroxy
-Keywords: bot,automation,antinuke,giveaway,music,scraper,toolkit,utility
+Keywords: bot,automation,antinuke,giveaway,music,scraper,webhook,cache,moderation,toolkit
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10

{kroxy-1.0.2 → kroxy-1.0.3}/kroxy/__init__.py

@@ -6,15 +6,10 @@ A powerful Python toolkit for building automation, integrations, and bots.
 All classes are available directly from the top-level `kroxy` namespace.
 
     import kroxy
-    kroxy.AntiNuke(...)
-    kroxy.GiveawayManager()
-    kroxy.Fetcher()
-    kroxy.Scraper.get_title(html)
-    kroxy.WebUtils.slugify("Hello World")
-
-    from kroxy import AntiNuke, Utils, Checkers, Fetcher, Scraper, WebUtils
-    from kroxy import discord    # discord submodule
-    from kroxy import website    # website submodule
+    from kroxy import AntiNuke, Embed, Moderation, Cache, Webhook
+    from kroxy import Fetcher, Scraper, WebUtils, Monitor
+    from kroxy import discord   # full discord submodule
+    from kroxy import website   # full website submodule
 
 License
 -------
@@ -22,7 +17,7 @@ Proprietary — Copyright (c) 2026 kroxy. All rights reserved.
 Unauthorized copying, modification, or redistribution is strictly prohibited.
 """
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"
 __author__ = "kroxy"
 __license__ = "Proprietary"
 __copyright__ = "Copyright (c) 2026 kroxy. All rights reserved."
@@ -33,70 +28,57 @@ from kroxy import website
 
 # ── Discord ────────────────────────────────────────────────────────────────────
 from kroxy.discord.api import DiscordAPI
-
-from kroxy.discord.commands import (
-    SlashCommand,
-    PrefixCommand,
-    Option,
-    CommandRegistry,
-    CooldownError,
-)
-
+from kroxy.discord.commands import SlashCommand, PrefixCommand, Option, CommandRegistry, CooldownError
 from kroxy.discord.utils import Utils
-
 from kroxy.discord.antinuke import AntiNuke, ActionLog
-
 from kroxy.discord.checkers import Checkers, CheckFailed
-
 from kroxy.discord.giveaway import GiveawayManager, Giveaway, GiveawayEntry
-
-from kroxy.discord.music import (
-    MusicPlayerManager,
-    MusicPlayer,
-    MusicQueue,
-    Track,
-    LoopMode,
-)
+from kroxy.discord.music import MusicPlayerManager, MusicPlayer, MusicQueue, Track, LoopMode
+from kroxy.discord.moderation import Moderation, Warning
+from kroxy.discord.embed import Embed
+from kroxy.discord.logger import ModLogger
+from kroxy.discord.cache import Cache
+from kroxy.discord.webhook import Webhook
 
 # ── Website ────────────────────────────────────────────────────────────────────
 from kroxy.website.fetch import Fetcher
 from kroxy.website.scraper import Scraper
 from kroxy.website.utils import WebUtils
+from kroxy.website.monitor import Monitor, CheckResult
 
 __all__ = [
     # Submodules
-    "discord",
-    "website",
+    "discord", "website",
     # Discord — API
     "DiscordAPI",
     # Discord — Commands
-    "SlashCommand",
-    "PrefixCommand",
-    "Option",
-    "CommandRegistry",
-    "CooldownError",
+    "SlashCommand", "PrefixCommand", "Option", "CommandRegistry", "CooldownError",
     # Discord — Utils
     "Utils",
     # Discord — Anti-Nuke
-    "AntiNuke",
-    "ActionLog",
+    "AntiNuke", "ActionLog",
     # Discord — Checkers
-    "Checkers",
-    "CheckFailed",
+    "Checkers", "CheckFailed",
     # Discord — Giveaway
-    "GiveawayManager",
-    "Giveaway",
-    "GiveawayEntry",
+    "GiveawayManager", "Giveaway", "GiveawayEntry",
     # Discord — Music
-    "MusicPlayerManager",
-    "MusicPlayer",
-    "MusicQueue",
-    "Track",
-    "LoopMode",
+    "MusicPlayerManager", "MusicPlayer", "MusicQueue", "Track", "LoopMode",
+    # Discord — Moderation
+    "Moderation", "Warning",
+    # Discord — Embed
+    "Embed",
+    # Discord — Logger
+    "ModLogger",
+    # Discord — Cache
+    "Cache",
+    # Discord — Webhook
+    "Webhook",
     # Website — Fetch
     "Fetcher",
     # Website — Scraper
     "Scraper",
     # Website — Utils
     "WebUtils",
+    # Website — Monitor
+    "Monitor", "CheckResult",
 ]

kroxy-1.0.3/kroxy/discord/__init__.py

@@ -0,0 +1,31 @@
+"""
+kroxy.discord - Discord bot utilities, automation, and server management.
+"""
+
+from kroxy.discord.api import DiscordAPI
+from kroxy.discord.commands import SlashCommand, PrefixCommand, Option, CommandRegistry, CooldownError
+from kroxy.discord.utils import Utils
+from kroxy.discord.antinuke import AntiNuke, ActionLog
+from kroxy.discord.checkers import Checkers, CheckFailed
+from kroxy.discord.giveaway import GiveawayManager, Giveaway, GiveawayEntry
+from kroxy.discord.music import MusicPlayerManager, MusicPlayer, MusicQueue, Track, LoopMode
+from kroxy.discord.moderation import Moderation, Warning
+from kroxy.discord.embed import Embed
+from kroxy.discord.logger import ModLogger
+from kroxy.discord.cache import Cache
+from kroxy.discord.webhook import Webhook
+
+__all__ = [
+    "DiscordAPI",
+    "SlashCommand", "PrefixCommand", "Option", "CommandRegistry", "CooldownError",
+    "Utils",
+    "AntiNuke", "ActionLog",
+    "Checkers", "CheckFailed",
+    "GiveawayManager", "Giveaway", "GiveawayEntry",
+    "MusicPlayerManager", "MusicPlayer", "MusicQueue", "Track", "LoopMode",
+    "Moderation", "Warning",
+    "Embed",
+    "ModLogger",
+    "Cache",
+    "Webhook",
+]

kroxy-1.0.3/kroxy/discord/cache.py

@@ -0,0 +1,202 @@
+"""
+kroxy.discord.cache - TTL in-memory cache for bot data.
+"""
+
+import time
+import asyncio
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+class _Entry:
+    __slots__ = ("value", "expires_at")
+
+    def __init__(self, value: Any, expires_at: float):
+        self.value = value
+        self.expires_at = expires_at
+
+    def is_expired(self) -> bool:
+        return time.time() > self.expires_at
+
+
+class Cache:
+    """
+    Thread-safe TTL in-memory cache.
+
+    Ideal for caching Discord API responses, guild configs,
+    user data, cooldowns, and any frequently-read values.
+
+    Usage:
+        from kroxy import Cache
+
+        cache = Cache(default_ttl=300)  # 5 minute default TTL
+        cache.set("user:123", user_data)
+        user = cache.get("user:123")
+        cache.delete("user:123")
+
+        # get or compute
+        guild = await cache.get_or_set("guild:456", lambda: fetch_guild(456), ttl=60)
+    """
+
+    def __init__(self, default_ttl: int = 300):
+        """
+        Args:
+            default_ttl: Default time-to-live in seconds for cached entries.
+        """
+        self._store: Dict[str, _Entry] = {}
+        self.default_ttl = default_ttl
+
+    def set(self, key: str, value: Any, ttl: int = None) -> None:
+        """
+        Store a value in the cache.
+
+        Args:
+            key: Cache key string.
+            value: Value to store (any type).
+            ttl: Time-to-live in seconds. Uses default_ttl if not specified.
+        """
+        ttl = ttl if ttl is not None else self.default_ttl
+        self._store[key] = _Entry(value=value, expires_at=time.time() + ttl)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Retrieve a value from the cache.
+
+        Args:
+            key: Cache key string.
+            default: Value to return if key is missing or expired.
+
+        Returns:
+            Cached value or default.
+        """
+        entry = self._store.get(key)
+        if entry is None or entry.is_expired():
+            self._store.pop(key, None)
+            return default
+        return entry.value
+
+    def delete(self, key: str) -> bool:
+        """
+        Remove a key from the cache.
+
+        Returns:
+            True if the key existed and was removed, False otherwise.
+        """
+        return self._store.pop(key, None) is not None
+
+    def has(self, key: str) -> bool:
+        """
+        Check if a key exists in the cache and has not expired.
+
+        Returns:
+            True if the key is present and valid.
+        """
+        entry = self._store.get(key)
+        if entry is None or entry.is_expired():
+            self._store.pop(key, None)
+            return False
+        return True
+
+    def clear(self) -> int:
+        """
+        Remove all entries from the cache.
+
+        Returns:
+            Number of entries that were cleared.
+        """
+        count = len(self._store)
+        self._store.clear()
+        return count
+
+    def size(self) -> int:
+        """
+        Count non-expired entries.
+
+        Returns:
+            Number of valid (non-expired) entries.
+        """
+        now = time.time()
+        return sum(1 for e in self._store.values() if e.expires_at > now)
+
+    def keys(self) -> List[str]:
+        """
+        Return all active (non-expired) keys.
+
+        Returns:
+            List of key strings.
+        """
+        now = time.time()
+        return [k for k, e in self._store.items() if e.expires_at > now]
+
+    async def get_or_set(self, key: str, factory: Callable,
+                          ttl: int = None) -> Any:
+        """
+        Return cached value if available, otherwise call factory(), cache and return the result.
+
+        Args:
+            key: Cache key.
+            factory: Async or sync callable that produces the value.
+            ttl: TTL for the new entry.
+
+        Returns:
+            Cached or freshly computed value.
+        """
+        value = self.get(key)
+        if value is not None:
+            return value
+        if asyncio.iscoroutinefunction(factory):
+            value = await factory()
+        else:
+            value = factory()
+        self.set(key, value, ttl=ttl)
+        return value
+
+    def expire(self, key: str, new_ttl: int) -> bool:
+        """
+        Update the TTL of an existing non-expired cache entry.
+
+        Args:
+            key: Cache key.
+            new_ttl: New TTL in seconds from now.
+
+        Returns:
+            True if the key existed and was updated, False otherwise.
+        """
+        entry = self._store.get(key)
+        if entry is None or entry.is_expired():
+            return False
+        entry.expires_at = time.time() + new_ttl
+        return True
+
+    def cleanup(self) -> int:
+        """
+        Remove all expired entries to free memory.
+
+        Returns:
+            Number of expired entries removed.
+        """
+        now = time.time()
+        expired = [k for k, e in self._store.items() if e.expires_at <= now]
+        for k in expired:
+            del self._store[k]
+        return len(expired)
+
+    def get_ttl(self, key: str) -> Optional[float]:
+        """
+        Get remaining TTL for a key in seconds.
+
+        Returns:
+            Seconds remaining, or None if key is missing/expired.
+        """
+        entry = self._store.get(key)
+        if entry is None or entry.is_expired():
+            return None
+        return max(0.0, entry.expires_at - time.time())
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __contains__(self, key: str) -> bool:
+        return self.has(key)
+
+    def __repr__(self) -> str:
+        return f"<Cache size={self.size()} default_ttl={self.default_ttl}s>"

kroxy-1.0.3/kroxy/discord/embed.py

@@ -0,0 +1,275 @@
+"""
+kroxy.discord.embed - OOP chainable Discord embed builder.
+"""
+
+import datetime
+import json
+from typing import Any, Dict, List, Optional
+
+
+class Embed:
+    """
+    Chainable, OOP-style Discord embed builder.
+
+    All setter methods return `self` so they can be chained.
+
+    Discord limits enforced by is_valid() / truncate_all():
+    - Title:        256 chars
+    - Description:  4096 chars
+    - Fields:       25 max
+    - Field name:   256 chars
+    - Field value:  1024 chars
+    - Footer text:  2048 chars
+    - Author name:  256 chars
+    - Total chars:  6000
+
+    Usage:
+        embed = (
+            Embed(title="Hello", color=0x5865F2)
+            .set_description("This is an embed.")
+            .add_field("Field 1", "Value 1", inline=True)
+            .add_field("Field 2", "Value 2", inline=True)
+            .set_footer("kroxy")
+            .set_timestamp()
+        )
+        await api.send_message(channel_id, embed=embed.to_dict())
+    """
+
+    LIMITS = {
+        "title": 256,
+        "description": 4096,
+        "field_name": 256,
+        "field_value": 1024,
+        "footer_text": 2048,
+        "author_name": 256,
+        "total": 6000,
+        "fields": 25,
+    }
+
+    def __init__(self, title: str = None, description: str = None,
+                 color: int = 0x5865F2):
+        self._title: Optional[str] = title
+        self._description: Optional[str] = description
+        self._color: int = color
+        self._fields: List[Dict] = []
+        self._footer: Optional[Dict] = None
+        self._thumbnail: Optional[Dict] = None
+        self._image: Optional[Dict] = None
+        self._author: Optional[Dict] = None
+        self._timestamp: Optional[str] = None
+        self._url: Optional[str] = None
+
+    # ── Setters (all chainable) ───────────────────────────────────────────────
+
+    def set_title(self, title: str) -> "Embed":
+        """Set the embed title."""
+        self._title = title
+        return self
+
+    def set_description(self, description: str) -> "Embed":
+        """Set the embed description."""
+        self._description = description
+        return self
+
+    def set_color(self, color: int) -> "Embed":
+        """Set the embed color as an integer (e.g. 0x5865F2)."""
+        self._color = color
+        return self
+
+    def set_url(self, url: str) -> "Embed":
+        """Set the embed URL (makes the title a hyperlink)."""
+        self._url = url
+        return self
+
+    def add_field(self, name: str, value: str,
+                  inline: bool = False) -> "Embed":
+        """Add a field to the embed."""
+        self._fields.append({"name": name, "value": value, "inline": inline})
+        return self
+
+    def remove_field(self, index: int) -> "Embed":
+        """Remove a field by its index (0-based)."""
+        if 0 <= index < len(self._fields):
+            self._fields.pop(index)
+        return self
+
+    def clear_fields(self) -> "Embed":
+        """Remove all fields from the embed."""
+        self._fields.clear()
+        return self
+
+    def set_footer(self, text: str, icon_url: str = None) -> "Embed":
+        """Set the embed footer."""
+        self._footer = {"text": text}
+        if icon_url:
+            self._footer["icon_url"] = icon_url
+        return self
+
+    def set_thumbnail(self, url: str) -> "Embed":
+        """Set the embed thumbnail (small image in top-right corner)."""
+        self._thumbnail = {"url": url}
+        return self
+
+    def set_image(self, url: str) -> "Embed":
+        """Set the embed large image (shown below fields)."""
+        self._image = {"url": url}
+        return self
+
+    def set_author(self, name: str, url: str = None,
+                   icon_url: str = None) -> "Embed":
+        """Set the embed author section."""
+        self._author = {"name": name}
+        if url:
+            self._author["url"] = url
+        if icon_url:
+            self._author["icon_url"] = icon_url
+        return self
+
+    def set_timestamp(self, dt: datetime.datetime = None) -> "Embed":
+        """
+        Set the embed timestamp.
+        If dt is None, uses the current UTC time.
+        """
+        dt = dt or datetime.datetime.utcnow()
+        self._timestamp = dt.isoformat()
+        return self
+
+    # ── Export ────────────────────────────────────────────────────────────────
+
+    def to_dict(self) -> Dict:
+        """Export the embed as a Discord-compatible dict."""
+        data: Dict[str, Any] = {"color": self._color}
+        if self._title:
+            data["title"] = self._title
+        if self._description:
+            data["description"] = self._description
+        if self._url:
+            data["url"] = self._url
+        if self._fields:
+            data["fields"] = list(self._fields)
+        if self._footer:
+            data["footer"] = self._footer
+        if self._thumbnail:
+            data["thumbnail"] = self._thumbnail
+        if self._image:
+            data["image"] = self._image
+        if self._author:
+            data["author"] = self._author
+        if self._timestamp:
+            data["timestamp"] = self._timestamp
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "Embed":
+        """
+        Create an Embed from an existing Discord embed dict.
+
+        Returns:
+            Embed instance populated from the dict.
+        """
+        e = cls(
+            title=data.get("title"),
+            description=data.get("description"),
+            color=data.get("color", 0x5865F2),
+        )
+        e._url = data.get("url")
+        e._fields = list(data.get("fields", []))
+        e._footer = data.get("footer")
+        e._thumbnail = data.get("thumbnail")
+        e._image = data.get("image")
+        e._author = data.get("author")
+        e._timestamp = data.get("timestamp")
+        return e
+
+    def copy(self) -> "Embed":
+        """Return a deep copy of this embed."""
+        return Embed.from_dict(self.to_dict())
+
+    def merge(self, other: "Embed") -> "Embed":
+        """
+        Merge another embed's fields into this one (fields are appended).
+
+        Returns:
+            self (chainable)
+        """
+        for f in other._fields:
+            self._fields.append(dict(f))
+        if not self._description and other._description:
+            self._description = other._description
+        if not self._footer and other._footer:
+            self._footer = dict(other._footer)
+        return self
+
+    # ── Validation ────────────────────────────────────────────────────────────
+
+    @property
+    def total_chars(self) -> int:
+        """Total character count across all text fields."""
+        total = 0
+        if self._title:
+            total += len(self._title)
+        if self._description:
+            total += len(self._description)
+        for f in self._fields:
+            total += len(f.get("name", "")) + len(f.get("value", ""))
+        if self._footer:
+            total += len(self._footer.get("text", ""))
+        if self._author:
+            total += len(self._author.get("name", ""))
+        return total
+
+    def is_valid(self) -> bool:
+        """
+        Check that the embed is within Discord's character and count limits.
+
+        Returns:
+            True if valid, False otherwise.
+        """
+        if self._title and len(self._title) > self.LIMITS["title"]:
+            return False
+        if self._description and len(self._description) > self.LIMITS["description"]:
+            return False
+        if len(self._fields) > self.LIMITS["fields"]:
+            return False
+        for f in self._fields:
+            if len(f.get("name", "")) > self.LIMITS["field_name"]:
+                return False
+            if len(f.get("value", "")) > self.LIMITS["field_value"]:
+                return False
+        if self._footer and len(self._footer.get("text", "")) > self.LIMITS["footer_text"]:
+            return False
+        if self._author and len(self._author.get("name", "")) > self.LIMITS["author_name"]:
+            return False
+        if self.total_chars > self.LIMITS["total"]:
+            return False
+        return True
+
+    def truncate_all(self) -> "Embed":
+        """
+        Auto-truncate all text fields to Discord's limits.
+
+        Returns:
+            self (chainable)
+        """
+        def _cut(text: str, limit: int) -> str:
+            return text[: limit - 3] + "..." if len(text) > limit else text
+
+        if self._title:
+            self._title = _cut(self._title, self.LIMITS["title"])
+        if self._description:
+            self._description = _cut(self._description, self.LIMITS["description"])
+        if self._footer and self._footer.get("text"):
+            self._footer["text"] = _cut(self._footer["text"], self.LIMITS["footer_text"])
+        if self._author and self._author.get("name"):
+            self._author["name"] = _cut(self._author["name"], self.LIMITS["author_name"])
+        self._fields = self._fields[: self.LIMITS["fields"]]
+        for f in self._fields:
+            f["name"] = _cut(f.get("name", ""), self.LIMITS["field_name"])
+            f["value"] = _cut(f.get("value", ""), self.LIMITS["field_value"])
+        return self
+
+    def __repr__(self) -> str:
+        return (
+            f"<Embed title={self._title!r} fields={len(self._fields)} "
+            f"chars={self.total_chars} valid={self.is_valid()}>"
+        )