shellog 1.0.5

A Python package to get notifications about the logs of a process

Shellog 1.0.5

Have you ever needed to monitor your background processes when you couldn't access your PC or VPN?

Shellog empowers you to seamlessly integrate logs into your Python code, delivering direct notifications to your Telegram chat. Additionally, for teams, it facilitates log sharing.

The primary aim of the Shellog library is to streamline process monitoring, and we'll explore how it accomplishes this with ease.

🚀 Features

• ✅ Send Python logs directly to Telegram
• ✅ Simple and intuitive API
• ✅ Support for multiple chat IDs (team notifications)
• ✅ Secure architecture (bot token never exposed to users)
• ✅ Rate limiting to prevent abuse
• ✅ Cross-platform (Linux, macOS, Windows)

📋 Requirements

1. Get the Server URL:

   • Contact the administrator to get the Shellog server URL
   • Or set up your own server (see DEPLOYMENT.md)

2. Get your ChatId:

   • Connect to Telegram: https://web.telegram.org/
   • Start a chat with the bot on Telegram
   • Send /id to get your ChatId
   • Save the ChatId for later use

3. Python 3.6+

📦 Installation

pip install shellog

🎯 Quick Start

import shellog

# Create bot instance with the server URL
bot = shellog.Bot(server_url="https://your-shellog-server.com")

# Or use environment variable SHELLOG_SERVER_URL
# bot = shellog.Bot()

# Add your ChatId (obtained from the bot with /id command)
bot.addChatId("YOUR_CHAT_ID")

# Send a message
bot.sendMessage("🎉 Hello from Python!")

📖 Usage Examples

Basic Usage

import shellog

bot = shellog.Bot(server_url="https://your-server.com")
bot.addChatId("123456789")

# Send notifications
bot.sendMessage("🚀 Process started!")
bot.sendMessage("✅ Task completed successfully!")

Progress Monitoring

import shellog
import time

bot = shellog.Bot(server_url="https://your-server.com")
bot.addChatId("123456789")

bot.sendMessage("⏳ Starting long process...")

for i in range(10):
    # Do some work
    time.sleep(1)
    bot.sendMessage(f"Progress: {(i+1)*10}%")

bot.sendMessage("✅ Process completed!")

Error Notifications

import shellog

bot = shellog.Bot(server_url="https://your-server.com")
bot.addChatId("123456789")

try:
    # Your code here
    result = some_risky_operation()
    bot.sendMessage("✅ Operation successful!")
except Exception as e:
    bot.sendMessage(f"❌ Error: {str(e)}")

Team Notifications

import shellog

bot = shellog.Bot(server_url="https://your-server.com")

# Add multiple team members
bot.addListChatIds([
    "123456789",  # Alice
    "987654321",  # Bob
    "555555555"   # Charlie
])

# Everyone gets the notification
bot.sendMessage("🎉 Deployment completed!")

Managing Chat IDs

import shellog

bot = shellog.Bot(server_url="https://your-server.com")

# Add single chat ID
bot.addChatId("123456789")

# Add multiple chat IDs
bot.addListChatIds(["123456789", "987654321"])

# Remove single chat ID
bot.removeChatId("123456789")

# Remove multiple chat IDs
bot.removeListChatIds(["123456789", "987654321"])

# Clear all chat IDs
bot.clearChatId()

🔧 Configuration

Server URL

You can specify the server URL in three ways:

1. Direct parameter (recommended for simple scripts):

bot = shellog.Bot(server_url="https://your-server.com")

2. Environment variable (recommended for production):

export SHELLOG_SERVER_URL="https://your-server.com"

bot = shellog.Bot()  # Automatically uses SHELLOG_SERVER_URL

3. Default (for local testing):

bot = shellog.Bot()  # Uses http://localhost:5005

🏗️ Architecture

Shellog uses a secure client-server architecture:

[Your Python Code] → [shellog library] → [Backend Server] → [Telegram]

• The bot token is never exposed to users
• All messages go through the backend server
• Rate limiting prevents abuse
• Secure and scalable

🛠️ For Server Administrators

If you want to host your own Shellog server, see DEPLOYMENT.md for detailed instructions.

Quick overview:

1. Run server.py (backend API)
2. Run bot_server.py (handles /id command)
3. Configure your domain/URL
4. Share the URL with your users

📊 API Reference

Bot(server_url=None)

Create a new Bot instance.

Parameters:

• server_url (str, optional): Backend server URL. Defaults to SHELLOG_SERVER_URL env var or http://localhost:5005

addChatId(id: str)

Add a single chat ID to the recipient list.

addListChatIds(ids: list)

Add multiple chat IDs at once.

removeChatId(id: str)

Remove a single chat ID from the recipient list.

removeListChatIds(ids: list)

Remove multiple chat IDs at once.

clearChatId()

Remove all chat IDs from the recipient list.

sendMessage(text: str)

Send a message to all registered chat IDs.

Returns: dict with send results

Raises:

• ValueError: If no chat IDs are registered or text is empty
• Exception: If the server is unreachable or returns an error

❓ FAQ

Q: Where do I get the ChatId?
A: Send /id to the Shellog bot on Telegram.

Q: Can I use this for team notifications?
A: Yes! Use addListChatIds() to add multiple team members.

Q: Is the bot token secure?
A: Yes! The token is stored only on the server, never in the client library.

Q: What if I send too many messages?
A: The server has rate limiting (default: 10 messages/minute per chat).

Q: Can I self-host the server?
A: Yes! See DEPLOYMENT.md for instructions.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

BSD 2-clause License - see LICENSE file for details.

👤 Author

Daniele Margiotta

• Email: [e-mail]
• GitHub: @danmargs

🙏 Credits

Reveal s.r.l.

---

⚙️ Server Setup

Important: Shellog requires a backend server to function. You have two options:

1. Use an existing server: Contact your administrator for the server URL
2. Host your own: Follow the instructions in DEPLOYMENT.md

The library is designed this way to keep the bot token secure and prevent abuse.

For administrators setting up a server, see:

• DEPLOYMENT.md - Complete deployment guide
• QUICKSTART.md - Quick local testing
• ARCHITECTURE.md - System architecture