disagreement 0.0.1__tar.gz

disagreement-0.0.1/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2025, Slipstream
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

disagreement-0.0.1/MANIFEST.in

@@ -0,0 +1,3 @@
+graft docs
+graft examples
+include LICENSE

disagreement-0.0.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: disagreement
+Version: 0.0.1
+Summary: A Python library for the Discord API.
+Author-email: Slipstream <me@slipstreamm.dev>
+License: BSD 3-Clause
+Project-URL: Homepage, https://github.com/Slipstreamm/disagreement
+Project-URL: Issues, https://github.com/Slipstreamm/disagreement/issues
+Keywords: discord,api,bot,async,aiohttp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
+Requires-Dist: hypothesis>=6.89.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: dotenv>=0.0.5; extra == "dev"
+Dynamic: license-file
+
+# Disagreement
+
+A Python library for interacting with the Discord API, with a focus on bot development.
+
+## Features
+
+- Asynchronous design using `aiohttp`
+- Gateway and HTTP API clients
+- Slash command framework
+- Message component helpers
+- Built-in caching layer
+- Experimental voice support
+- Helpful error handling utilities
+
+## Installation
+
+```bash
+python -m pip install -U pip
+pip install disagreement
+# or install from source for development
+pip install -e .
+```
+
+Requires Python 3.11 or newer.
+
+## Basic Usage
+
+```python
+import asyncio
+import os
+import disagreement
+
+# Ensure DISCORD_BOT_TOKEN is set in your environment
+client = disagreement.Client(token=os.environ.get("DISCORD_BOT_TOKEN"))
+
+@client.on_event('MESSAGE_CREATE')
+async def on_message(message: disagreement.Message):
+    print(f"Received: {message.content} from {message.author.username}")
+    if message.content.lower() == '!ping':
+        await message.reply('Pong!')
+
+async def main():
+    if not client.token:
+        print("Error: DISCORD_BOT_TOKEN environment variable not set.")
+        return
+    try:
+        async with client:
+            await asyncio.Future()  # run until cancelled
+    except KeyboardInterrupt:
+        print("Bot shutting down...")
+    # Add any other specific exception handling from your library, e.g., disagreement.AuthenticationError
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+### Global Error Handling
+
+To ensure unexpected errors don't crash your bot, you can enable the library's
+global error handler:
+
+```python
+import disagreement
+
+disagreement.setup_global_error_handler()
+```
+
+Call this early in your program to log unhandled exceptions instead of letting
+them terminate the process.
+
+### Configuring Logging
+
+Use :func:`disagreement.logging_config.setup_logging` to configure logging for
+your bot. The helper accepts a logging level and an optional file path.
+
+```python
+import logging
+from disagreement.logging_config import setup_logging
+
+setup_logging(logging.INFO)
+# Or log to a file
+setup_logging(logging.DEBUG, file="bot.log")
+```
+
+### Defining Subcommands with `AppCommandGroup`
+
+```python
+from disagreement.ext.app_commands import AppCommandGroup
+
+settings = AppCommandGroup("settings", "Manage settings")
+
+@settings.command(name="show")
+async def show(ctx):
+    """Displays a setting."""
+    ...
+
+@settings.group("admin", description="Admin settings")
+def admin_group():
+    pass
+
+@admin_group.command(name="set")
+async def set_setting(ctx, key: str, value: str):
+    ...
+## Fetching Guilds
+
+Use `Client.fetch_guild` to retrieve a guild from the Discord API if it
+isn't already cached. This is useful when working with guild IDs from
+outside the gateway events.
+
+```python
+guild = await client.fetch_guild("123456789012345678")
+roles = await client.fetch_roles(guild.id)
+```
+
+## Sharding
+
+To run your bot across multiple gateway shards, pass `shard_count` when creating
+the client:
+
+```python
+client = disagreement.Client(token=BOT_TOKEN, shard_count=2)
+```
+
+See `examples/sharded_bot.py` for a full example.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+See the [docs](docs/) directory for detailed guides on components, slash commands, caching, and voice features.
+

disagreement-0.0.1/README.md

@@ -0,0 +1,131 @@
+# Disagreement
+
+A Python library for interacting with the Discord API, with a focus on bot development.
+
+## Features
+
+- Asynchronous design using `aiohttp`
+- Gateway and HTTP API clients
+- Slash command framework
+- Message component helpers
+- Built-in caching layer
+- Experimental voice support
+- Helpful error handling utilities
+
+## Installation
+
+```bash
+python -m pip install -U pip
+pip install disagreement
+# or install from source for development
+pip install -e .
+```
+
+Requires Python 3.11 or newer.
+
+## Basic Usage
+
+```python
+import asyncio
+import os
+import disagreement
+
+# Ensure DISCORD_BOT_TOKEN is set in your environment
+client = disagreement.Client(token=os.environ.get("DISCORD_BOT_TOKEN"))
+
+@client.on_event('MESSAGE_CREATE')
+async def on_message(message: disagreement.Message):
+    print(f"Received: {message.content} from {message.author.username}")
+    if message.content.lower() == '!ping':
+        await message.reply('Pong!')
+
+async def main():
+    if not client.token:
+        print("Error: DISCORD_BOT_TOKEN environment variable not set.")
+        return
+    try:
+        async with client:
+            await asyncio.Future()  # run until cancelled
+    except KeyboardInterrupt:
+        print("Bot shutting down...")
+    # Add any other specific exception handling from your library, e.g., disagreement.AuthenticationError
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+### Global Error Handling
+
+To ensure unexpected errors don't crash your bot, you can enable the library's
+global error handler:
+
+```python
+import disagreement
+
+disagreement.setup_global_error_handler()
+```
+
+Call this early in your program to log unhandled exceptions instead of letting
+them terminate the process.
+
+### Configuring Logging
+
+Use :func:`disagreement.logging_config.setup_logging` to configure logging for
+your bot. The helper accepts a logging level and an optional file path.
+
+```python
+import logging
+from disagreement.logging_config import setup_logging
+
+setup_logging(logging.INFO)
+# Or log to a file
+setup_logging(logging.DEBUG, file="bot.log")
+```
+
+### Defining Subcommands with `AppCommandGroup`
+
+```python
+from disagreement.ext.app_commands import AppCommandGroup
+
+settings = AppCommandGroup("settings", "Manage settings")
+
+@settings.command(name="show")
+async def show(ctx):
+    """Displays a setting."""
+    ...
+
+@settings.group("admin", description="Admin settings")
+def admin_group():
+    pass
+
+@admin_group.command(name="set")
+async def set_setting(ctx, key: str, value: str):
+    ...
+## Fetching Guilds
+
+Use `Client.fetch_guild` to retrieve a guild from the Discord API if it
+isn't already cached. This is useful when working with guild IDs from
+outside the gateway events.
+
+```python
+guild = await client.fetch_guild("123456789012345678")
+roles = await client.fetch_roles(guild.id)
+```
+
+## Sharding
+
+To run your bot across multiple gateway shards, pass `shard_count` when creating
+the client:
+
+```python
+client = disagreement.Client(token=BOT_TOKEN, shard_count=2)
+```
+
+See `examples/sharded_bot.py` for a full example.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+See the [docs](docs/) directory for detailed guides on components, slash commands, caching, and voice features.
+

disagreement-0.0.1/disagreement/__init__.py

@@ -0,0 +1,36 @@
+# disagreement/__init__.py
+
+"""
+Disagreement
+~~~~~~~~~~~~
+
+A Python library for interacting with the Discord API.
+
+:copyright: (c) 2025 Slipstream
+:license: BSD 3-Clause License, see LICENSE for more details.
+"""
+
+__title__ = "disagreement"
+__author__ = "Slipstream"
+__license__ = "BSD 3-Clause License"
+__copyright__ = "Copyright 2025 Slipstream"
+__version__ = "0.0.1"
+
+from .client import Client
+from .models import Message, User
+from .voice_client import VoiceClient
+from .typing import Typing
+from .errors import (
+    DisagreementException,
+    HTTPException,
+    GatewayException,
+    AuthenticationError,
+)
+from .enums import GatewayIntent, GatewayOpcode  # Export enums
+from .error_handler import setup_global_error_handler
+from .hybrid_context import HybridContext
+from .ext import tasks
+
+# Set up logging if desired
+# import logging
+# logging.getLogger(__name__).addHandler(logging.NullHandler())

disagreement-0.0.1/disagreement/cache.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Dict, Generic, Optional, TypeVar
+
+if TYPE_CHECKING:
+    from .models import Channel, Guild
+
+T = TypeVar("T")
+
+
+class Cache(Generic[T]):
+    """Simple in-memory cache with optional TTL support."""
+
+    def __init__(self, ttl: Optional[float] = None) -> None:
+        self.ttl = ttl
+        self._data: Dict[str, tuple[T, Optional[float]]] = {}
+
+    def set(self, key: str, value: T) -> None:
+        expiry = time.monotonic() + self.ttl if self.ttl is not None else None
+        self._data[key] = (value, expiry)
+
+    def get(self, key: str) -> Optional[T]:
+        item = self._data.get(key)
+        if not item:
+            return None
+        value, expiry = item
+        if expiry is not None and expiry < time.monotonic():
+            self.invalidate(key)
+            return None
+        return value
+
+    def invalidate(self, key: str) -> None:
+        self._data.pop(key, None)
+
+    def clear(self) -> None:
+        self._data.clear()
+
+    def values(self) -> list[T]:
+        now = time.monotonic()
+        items = []
+        for key, (value, expiry) in list(self._data.items()):
+            if expiry is not None and expiry < now:
+                self.invalidate(key)
+            else:
+                items.append(value)
+        return items
+
+
+class GuildCache(Cache["Guild"]):
+    """Cache specifically for :class:`Guild` objects."""
+
+
+class ChannelCache(Cache["Channel"]):
+    """Cache specifically for :class:`Channel` objects."""