{"id":19280800,"url":"https://github.com/lalaio1/wooklib","last_synced_at":"2026-01-29T10:45:36.453Z","repository":{"id":255954342,"uuid":"851382088","full_name":"lalaio1/wooklib","owner":"lalaio1","description":"A **Discord Webhook Library** provides a comprehensive set of tools for sending, managing, and interacting with Discord webhooks using synchronous and asynchronous methods.","archived":false,"fork":false,"pushed_at":"2024-09-08T03:27:17.000Z","size":26,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-11T08:16:18.063Z","etag":null,"topics":["discord","library","python","webhook"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lalaio1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-03T01:58:36.000Z","updated_at":"2024-10-02T01:18:35.000Z","dependencies_parsed_at":"2024-09-08T04:30:04.312Z","dependency_job_id":"2ea21a1d-668d-48dd-b017-56f1f729c4e0","html_url":"https://github.com/lalaio1/wooklib","commit_stats":null,"previous_names":["lalaio1/wooklib"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lalaio1/wooklib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalaio1%2Fwooklib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalaio1%2Fwooklib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalaio1%2Fwooklib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalaio1%2Fwooklib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lalaio1","download_url":"https://codeload.github.com/lalaio1/wooklib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalaio1%2Fwooklib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28875761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","library","python","webhook"],"created_at":"2024-11-09T21:20:41.715Z","updated_at":"2026-01-29T10:45:36.436Z","avatar_url":"https://github.com/lalaio1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wooklib Library Documentation\n\nWelcome to the **wooklib** library documentation! This guide provides a comprehensive overview of how to use the **wooklib** library to send messages, manage webhooks, and handle various scenarios on Discord. This library offers both synchronous and asynchronous implementations for interacting with Discord webhooks, making it flexible and suitable for different needs.\n\n## Table of Contents\n1. [🚀 Installation](#installation)\n2. [⚡ Quick Start](#quick-start)\n3. [📚 Class Overview](#class-overview)\n4. [🔧 Features](#features)\n   - [Sending Messages](#sending-messages)\n   - [Sending Rich Embeds](#sending-rich-embeds)\n   - [Sending Files](#sending-files)\n   - [Managing Webhooks](#managing-webhooks)\n   - [Handling Errors](#handling-errors)\n   - [Advanced Features](#advanced-features)\n5. [💻 Examples](#examples)\n6. [🛠️ Advanced Usage](#advanced-usage)\n7. [💡 Tips and Best Practices](#tips-and-best-practices)\n8. [📝 Changelog](#changelog)\n9. [📄 License](#license)\n\n---\n\n## 🚀 Installation\n\nTo install the **wooklib** library, simply use pip:\n\n```bash\npip install .\n```\n\nEnsure you have Python 3.6 or higher installed to use the latest features of the library.\n\n---\n\n## ⚡ Quick Start\n\nHere's a quick example to get you started with the **wooklib** library:\n\n```python\nfrom wooklib import DiscordWebhook\n\n# Initialize the webhook\nwebhook = DiscordWebhook(url=\"https://discord.com/api/webhooks/your_webhook_id\")\n\n# Send a simple message\nwebhook.send_message(\"Hello, Discord!\")\n```\n\nThis will send a message saying \"Hello, Discord!\" to the specified Discord channel.\n\n---\n\n## 📚 Class Overview\n\n### DiscordWebhook\n\n- **`DiscordWebhook(url, username=None, avatar_url=None, log_errors=False, timeout=None, proxies=None, user_agent=None, verbose=False)`**\n  - The main class for interacting with Discord webhooks.\n  - **Parameters**:\n    - `url`: The Discord webhook URL.\n    - `username`: Optional username to override the default webhook username.\n    - `avatar_url`: Optional URL to override the default webhook avatar.\n    - `log_errors`: If `True`, errors will be logged.\n    - `timeout`: Request timeout in seconds.\n    - `proxies`: Dictionary of proxies to use for the requests.\n    - `user_agent`: Custom user agent for requests.\n    - `verbose`: If `True`, detailed logs will be shown.\n\n### AsyncDiscordWebhook\n\n- **`AsyncDiscordWebhook(url, username=None, avatar_url=None, user_agent=None, timeout=None)`**\n  - An asynchronous version of the `DiscordWebhook` class, using `aiohttp` for non-blocking requests.\n\n### MentioningDiscordWebhook\n\n- **`MentioningDiscordWebhook(url, username=None, avatar_url=None, log_errors=False, timeout=None, proxies=None, user_agent=None, verbose=False)`**\n  - A subclass of `DiscordWebhook` that allows you to easily mention users or roles.\n\n### ValidatingDiscordWebhook\n\n- **`ValidatingDiscordWebhook(url, username=None, avatar_url=None, log_errors=False, timeout=None, proxies=None, user_agent=None, verbose=False)`**\n  - A subclass of `DiscordWebhook` that includes validation for message content lengths.\n\n### CachedDiscordWebhook\n\n- **`CachedDiscordWebhook(url, username=None, avatar_url=None, timeout=None, max_cache_size=128, cache_ttl=300)`**\n  - A subclass that caches messages to avoid duplicate sends within a specified time period.\n\n### ExponentialBackoffDiscordWebhook\n\n- **`ExponentialBackoffDiscordWebhook(url, username=None, avatar_url=None, timeout=None)`**\n  - A subclass that handles rate limiting with exponential backoff.\n\n### VerboseDiscordWebhook\n\n- **`VerboseDiscordWebhook(url, username=None, avatar_url=None, log_errors=False, timeout=None, proxies=None, user_agent=None, verbose=True)`**\n  - A subclass of `DiscordWebhook` that provides verbose logging for debugging.\n\n### PrivateWebhook\n\n- **`PrivateWebhook(url, username=None, avatar_url=None)`**\n  - A class for handling private or internal webhooks with additional security features.\n\n### WebhookException\n\n- **`WebhookException`**\n  - Base class for all exceptions related to webhooks.\n\n### WebhookNotFoundError\n\n- **`WebhookNotFoundError`**\n  - Raised when a webhook is not found.\n\n### RateLimitExceededError\n\n- **`RateLimitExceededError`**\n  - Raised when the rate limit for a webhook is exceeded.\n\n### InvalidWebhookURLError\n\n- **`InvalidWebhookURLError`**\n  - Raised when the webhook URL is invalid.\n\n### WebhookResponseHandler\n\n- **`WebhookResponseHandler`**\n  - Handles responses from the webhook requests.\n\n---\n\n## 🔧 Features\n\n### Sending Messages\n\nSending a message with **wooklib** is straightforward:\n\n```python\nwebhook = DiscordWebhook(url=\"https://discord.com/api/webhooks/your_webhook_id\")\nwebhook.send_message(\"This is a test message!\")\n```\n\n### Sending Rich Embeds\n\nYou can send rich embeds with a title, description, and other details:\n\n```python\nwebhook.send_embed(\n    title=\"Important Update\",\n    description=\"New features have been added!\",\n    color=0x00ff00,  # Optional: Hex color code\n    fields=[\n        {\"name\": \"Feature 1\", \"value\": \"Details about feature 1\", \"inline\": False},\n        {\"name\": \"Feature 2\", \"value\": \"Details about feature 2\", \"inline\": False}\n    ],\n    footer=\"Footer text here\",\n    timestamp=\"2023-09-01T12:34:56Z\"  # Optional: ISO 8601 timestamp\n)\n```\n\n### Sending Files\n\nYou can also send files along with your messages:\n\n```python\nwebhook.send_file(file_path=\"path/to/your/file.txt\", content=\"Here is the file you requested!\")\n```\n\n### Managing Webhooks\n\nThe **wooklib** library allows you to manage webhooks with the following methods:\n- `modify_webhook`: Modify the webhook's name and avatar.\n- `delete_webhook`: Delete the webhook.\n- `get_webhook_info`: Retrieve information about the webhook.\n\n```python\nwebhook.modify_webhook(name=\"New Webhook Name\", avatar=\"path/to/avatar.png\")\ninfo = webhook.get_webhook_info()\nwebhook.delete_webhook()\n```\n\n### Handling Errors\n\nCustom error classes are provided to handle different types of webhook-related errors, such as `WebhookNotFoundError`, `RateLimitExceededError`, and `InvalidWebhookURLError`.\n\nExample:\n\n```python\nfrom wooklib import WebhookNotFoundError\n\ntry:\n    webhook.send_message(\"This is a test message!\")\nexcept WebhookNotFoundError as e:\n    print(f\"Error: {e}\")\n```\n\n### Advanced Features\n\nThe library includes advanced features such as exponential backoff, cache management, and asynchronous requests. These features are designed to make the library robust and versatile.\n\n---\n\n## 💻 Examples\n\n### Example 1: Sending a Batch of Messages Asynchronously\n\n```python\nimport asyncio\nfrom wooklib import AsyncDiscordWebhook\n\nasync def main():\n    webhook = AsyncDiscordWebhook(url=\"https://discord.com/api/webhooks/your_webhook_id\")\n    messages = [\"Message 1\", \"Message 2\", \"Message 3\"]\n    await webhook.send_messages_batch(messages)\n\nasyncio.run(main())\n```\n\n### Example 2: Sending a Mention with a Role ID\n\n```python\nfrom wooklib import MentioningDiscordWebhook\n\nwebhook = MentioningDiscordWebhook(url=\"https://discord.com/api/webhooks/your_webhook_id\")\nwebhook.send_mention(\"Attention everyone!\", role_id=\"123456789012345678\")\n```\n\n---\n\n## 🛠️ Advanced Usage\n\n### Using a Proxy\n\nIf you need to use a proxy:\n\n```python\nwebhook = DiscordWebhook(url=\"https://discord.com/api/webhooks/your_webhook_id\")\nwebhook.set_proxy(\"http://yourproxy.com:8080\")\nwebhook.send_message(\"Message sent through a proxy!\")\n```\n\n### Custom Headers\n\nAdd custom headers to your requests:\n\n```python\nwebhook.set_custom_headers({\"Authorization\": \"Bearer your_token\"})\nwebhook.send_message(\"Message with custom headers!\")\n```\n\n### Rate Limiting with Exponential Backoff\n\nThe `ExponentialBackoffDiscordWebhook` class automatically handles rate limiting with exponential backoff:\n\n```python\nwebhook = ExponentialBackoffDiscordWebhook(url=\"https://discord.com/api/webhooks/your_webhook_id\")\nwebhook.send_message(\"Message with rate limit handling!\")\n```\n\n---\n\n## 💡 Tips and Best Practices\n\n- **Handle Errors Gracefully:** Always handle exceptions to avoid crashing your application.\n- **Use Asynchronous Methods for High Volume:** For high-frequency message sending, consider using the `AsyncDiscordWebhook` class to avoid blocking your application.\n- **Respect Discord's Rate Limits:** Avoid sending too many requests too quickly to prevent being rate limited.\n\n---\n\n## 📝 Changelog\n\n### Version 1.0.0\n\n- Initial release with support for synchronous and asynchronous message sending.\n- Added error handling and webhook management features.\n\n### Version 1.1.0\n\n- Added support for sending rich embeds and files.\n- Introduced the `CachedDiscordWebhook` class for caching messages.\n\n---\n\n## 📄 License\n\nThe **wooklib\n\n** library is licensed under the MIT License. See the `LICENSE` file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flalaio1%2Fwooklib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flalaio1%2Fwooklib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flalaio1%2Fwooklib/lists"}