Official Python SDK for the KaguneBin anonymous paste sharing service.
KaguneBin is a high-performance, dark-themed paste service inspired by the world of Tokyo Ghoul.
This official Python library lets you programmatically create, fetch, download, and manage pastes with full support for:
- 🔒 Zero-Trust Password Protection (bcrypt)
- 🔥 Burn-After-Read (instant self-destruction upon reading)
- ⏳ Automated Expiration (hours, days, or scheduled timestamps)
- 📥 Binary & File Downloads
- ⚡ Synchronous & Asynchronous Clients
- 🛡️ Typed Custom Exception Hierarchy
# Standard synchronous client
pip install kagunebin
# With asynchronous support (httpx)
pip install "kagunebin[async]"from kagunebin import KaguneBin
# Initialize client
kb = KaguneBin()
# Create a paste
paste = kb.create(
title="Main Execution Script",
content="import os\nprint('System initialized successfully.')",
syntax="python",
expires_in_hours=24
)
print("Paste Created Successfully!")
print("ID:", paste["id"])
print("URL:", paste["full_url"])Pastes can be secured with bcrypt encryption:
from kagunebin import KaguneBin
kb = KaguneBin()
# Create protected paste
paste = kb.create(
title="Confidential API Credentials",
content="DATABASE_SECRET_KEY=super_secure_99812",
syntax="yaml",
password="my_vault_password"
)
# Fetching requires the password
result = kb.get(paste["id"], password="my_vault_password")
print(result["content"])Burn-after-read pastes are permanently purged from the database after their very first retrieval:
paste = kb.create(
title="One-Time Verification Token",
content="AUTH_OTP_77192",
burn_after_read=True
)
# Read 1: Success
content = kb.raw(paste["id"])
print("Token:", content)
# Read 2: Raises KaguneBinNotFoundError or KaguneBinExpiredErrorSet automated lifetimes in hours or days:
# Expire in 6 hours
paste_6h = kb.create(
content="Temporary debug trace",
syntax="text",
expires_in_hours=6
)
# Expire in 7 days
paste_7d = kb.create(
content="Weekly report summary",
syntax="markdown",
expires_in_days=7
)Fetch pure plaintext directly for piping or logging:
raw_text = kb.raw("kgn_a1b2c3d4")
print(raw_text)# Download and save directly to file
kb.download("kgn_a1b2c3d4", save_as="output_script.py")
# Or obtain raw bytes
data_bytes = kb.download("kgn_a1b2c3d4")health = kb.verify()
print(f"Status: {health['status']} | Latency: {health['latency_ms']}ms")The SDK provides granular, typed exceptions for safe integration:
from kagunebin import (
KaguneBin,
KaguneBinAuthError,
KaguneBinNotFoundError,
KaguneBinExpiredError,
KaguneBinValidationError,
KaguneBinConnectionError,
KaguneBinError,
)
kb = KaguneBin()
try:
paste = kb.get("kgn_sample123", password="wrong_pass")
except KaguneBinAuthError:
print("❌ Incorrect or missing password!")
except KaguneBinNotFoundError:
print("❌ Paste does not exist.")
except KaguneBinExpiredError:
print("⚠️ Paste has expired or was already burned.")
except KaguneBinConnectionError as e:
print(f"🌐 Network connection error: {e}")
except KaguneBinError as e:
print(f"🚨 API error: {e}")For high-throughput applications, FastAPI backends, and Discord/Telegram bots:
import asyncio
from kagunebin import AsyncKaguneBin
async def main():
async with AsyncKaguneBin() as kb:
paste = await kb.create(
title="Async Log Dump",
content="[2026-10-04] System worker cluster running smoothly.",
syntax="text",
expires_in_hours=12
)
print("Async URL:", paste["full_url"])
asyncio.run(main())from pyrogram import Client, filters
from pyrogram.types import Message
from kagunebin import KaguneBin
app = Client("kagunebin_bot", api_id=12345, api_hash="your_hash", bot_token="your_token")
kb = KaguneBin()
@app.on_message(filters.command("paste") & filters.reply)
async def paste_handler(client: Client, message: Message):
text_to_paste = message.reply_to_message.text or message.reply_to_message.caption
if not text_to_paste:
return await message.reply("Please reply to a text message.")
status_msg = await message.reply("🩸 Creating KaguneBin paste...")
try:
paste = kb.create(
title=f"Paste by {message.from_user.first_name}",
content=text_to_paste,
syntax="plaintext",
expires_in_days=3
)
await status_msg.edit(
f"✅ **Paste Created!**\n\n"
f"🔗 **URL:** {paste['full_url']}\n"
f"⏳ **Expires In:** 3 Days"
)
except Exception as e:
await status_msg.edit(f"❌ Failed to create paste: {e}")
app.run()kb = KaguneBin()
print(kb.syntaxes())Supported languages include:
python, javascript, typescript, java, cpp, c, csharp, go, rust, php, ruby, swift, kotlin, html, css, scss, json, xml, yaml, sql, bash, shell, text, plaintext, markdown, dockerfile.
MIT License © 2026 Kishore M
🩸 Made with passion by Kishore M