# Tamga [](https://pepy.tech/projects/tamga)
A modern, high-performance logging utility for Python with multiple output formats and colorful console output.
[](https://pypi.org/project/tamga/)
**🤖 AI Integration:** For AI/LLM integration, see [LLMs.txt](https://raw.githubusercontent.com/DogukanUrker/Tamga/refs/heads/main/llms.txt) or access documentation directly via [Context7](https://context7.com/dogukanurker/tamga)
> **tam·ga** */ˈtæmɡə/* · noun
> An ancient Turkic symbol or seal used for marking ownership, identity, or lineage.
<img alt="Terminal" src="https://github.com/DogukanUrker/Tamga/blob/main/Images/terminal.png?raw=true" />
## ✨ Features
- 🎨 **Beautiful Console Output** - Colorful, formatted logs using Tailwind CSS colors
- ⚡ **High Performance** - Buffered writing system (10x faster than traditional logging)
- 📊 **Multiple Outputs** - Console, file, JSON, SQLite, MongoDB
- 🔄 **Automatic Rotation** - File size management with backup support
- 🧵 **Thread-Safe** - Safe for multi-threaded applications
- 🔔 **Notifications** - Multi-service notifications via [Apprise](https://github.com/caronc/apprise) (Discord, Slack, Email, SMS, and more)
- 🔍 **Structured Logging** - Key-value data support with all log methods
## 🚀 Quick Start
See [`examples/simple_usage.py`](./examples/simple_usage.py) for a full script.
```python
from tamga import Tamga
# Create logger with default settings
logger = Tamga()
# Log messages
logger.info("Application started")
logger.warning("Memory usage at 85%")
logger.error("Failed to connect to API")
logger.success("User registered successfully")
logger.debug("Cache initialized with 1000 entries")
```
## 🧑💻 Examples
See [`examples/`](./examples) for ready-to-run scripts:
- `simple_usage.py` — basic logging
- `fastapi_webapp.py` — FastAPI integration
- `advanced_config.py` — production config
- `high_performance.py` — high-speed big data logging demo
## 📦 Installation
```bash
pip install tamga # Basic installation
pip install tamga[mongo] # With MongoDB support
pip install tamga[notifications] # With notification support
pip install tamga[all] # All features
```
## 🎯 Usage Examples
### Basic Configuration
```python
logger = Tamga(
# Display settings
colored_output=True, # Colored output
show_time=True, # Include timestamp
show_timezone=False, # Include timezone
# Output destinations
file_output=True, # Log to file
file_path="app.log", # Log file path
buffer_size=50, # Buffer size for performance
)
```
### Structured Logging
```python
# Log with key-value data using any log method
logger.info("User action",
user_id="123",
action="login",
ip_address="192.168.1.1",
success=True
)
# Works with all log levels
logger.error("Database connection failed",
host="localhost",
port=5432,
timeout=30,
retry_count=3
)
logger.success("Payment processed",
amount=99.99,
currency="USD",
method="credit_card",
transaction_id="tx_123"
)
```
### Production Setup
```python
logger = Tamga(
# File rotation
file_output=True,
max_file_size_mb=50, # 50MB max file size
enable_backup=True, # Create backups
# Performance
buffer_size=200, # Larger buffer for production
console_output=False, # Disable console for speed
# External services
mongo_output=True,
mongo_uri="mongodb://...",
# Multi-service notifications
notify_services=[
"discord://webhook_id/webhook_token",
"slack://tokenA/tokenB/tokenC/#alerts",
"mailto://user:pass@smtp.gmail.com:587/?to=alerts@company.com",
"twilio://SID:Token@+1234567890/+0987654321",
],
notify_levels=["CRITICAL", "ERROR", "NOTIFY"],
)
```
## 📋 Log Levels
| Level | Color | Method | Use Case |
|-------|-------|---------|----------|
| INFO | Sky | `logger.info()` | General information |
| WARNING | Amber | `logger.warning()` | Warning messages |
| ERROR | Rose | `logger.error()` | Error messages |
| SUCCESS | Emerald | `logger.success()` | Success messages |
| DEBUG | Indigo | `logger.debug()` | Debug information |
| CRITICAL | Red | `logger.critical()` | Critical issues |
| DATABASE | Green | `logger.database()` | Database operations |
| NOTIFY | Purple | `logger.notify()` | Send notifications |
| METRIC | Cyan | `logger.metric()` | Performance metrics |
| TRACE | Gray | `logger.trace()` | Detailed trace info |
| CUSTOM | Any | `logger.custom()` | Custom levels |
## 🔧 Advanced Features
### Notifications
```python
# Configure notification services (supports 80+ services via Apprise)
logger = Tamga(
notify_services=[
"discord://webhook_id/webhook_token",
"slack://tokenA/tokenB/tokenC/#channel",
],
notify_levels=["CRITICAL", "ERROR", "NOTIFY"],
notify_title="{appname}: {level} Alert",
notify_format="markdown", # text, markdown, or html
)
# Send notification
logger.notify("Payment received from user #123")
# Critical logs also trigger notifications
logger.critical("Database connection lost")
```
### Custom Log Levels
```python
logger.custom("Deploy completed", "DEPLOY", "purple")
logger.custom("Payment received", "PAYMENT", "green")
```
### Buffer Control
```python
# Force write all buffered logs
logger.flush()
```
### File Rotation
When log files reach `max_file_size_mb`, Tamga automatically:
- Creates timestamped backups (if enabled)
- Clears the original file
- Continues logging seamlessly
## 📊 Performance
Tamga uses a buffered writing system that delivers significantly faster performance compared to traditional logging. The buffering mechanism provides optimal throughput for high-volume logging scenarios while maintaining thread safety.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [PyPI Package](https://pypi.org/project/tamga/)
- [GitHub Repository](https://github.com/DogukanUrker/Tamga)
- [Documentation](https://tamga.vercel.app/)
- [Bug Reports](https://github.com/DogukanUrker/Tamga/issues)
---
<p align="center">
Made with ❤️ by <a href="https://github.com/DogukanUrker">Doğukan Ürker</a>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "tamga",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "logging, async, mongodb, colorful, console, file, json, sql, notifications, apprise, performance, buffered, alerting, monitoring, discord, slack, email, sms, webhooks, telegram, modern, high-performance, logger, structured-logging, developer-tools, observability",
"author": null,
"author_email": "Do\u011fukan \u00dcrker <dogukanurker@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/2b/1f8841bb4d36b950bb283bd833ccddc8a646858806a3f4ca0b9ba23b6ed9/tamga-1.4.0.tar.gz",
"platform": null,
"description": "# Tamga [](https://pepy.tech/projects/tamga)\n\nA modern, high-performance logging utility for Python with multiple output formats and colorful console output.\n\n[](https://pypi.org/project/tamga/)\n\n**\ud83e\udd16 AI Integration:** For AI/LLM integration, see [LLMs.txt](https://raw.githubusercontent.com/DogukanUrker/Tamga/refs/heads/main/llms.txt) or access documentation directly via [Context7](https://context7.com/dogukanurker/tamga)\n\n> **tam\u00b7ga** */\u02c8t\u00e6m\u0261\u0259/* \u00b7 noun\n> An ancient Turkic symbol or seal used for marking ownership, identity, or lineage.\n\n<img alt=\"Terminal\" src=\"https://github.com/DogukanUrker/Tamga/blob/main/Images/terminal.png?raw=true\" />\n\n## \u2728 Features\n\n- \ud83c\udfa8 **Beautiful Console Output** - Colorful, formatted logs using Tailwind CSS colors\n- \u26a1 **High Performance** - Buffered writing system (10x faster than traditional logging)\n- \ud83d\udcca **Multiple Outputs** - Console, file, JSON, SQLite, MongoDB\n- \ud83d\udd04 **Automatic Rotation** - File size management with backup support\n- \ud83e\uddf5 **Thread-Safe** - Safe for multi-threaded applications\n- \ud83d\udd14 **Notifications** - Multi-service notifications via [Apprise](https://github.com/caronc/apprise) (Discord, Slack, Email, SMS, and more)\n- \ud83d\udd0d **Structured Logging** - Key-value data support with all log methods\n\n## \ud83d\ude80 Quick Start\n\nSee [`examples/simple_usage.py`](./examples/simple_usage.py) for a full script.\n\n```python\nfrom tamga import Tamga\n\n# Create logger with default settings\nlogger = Tamga()\n\n# Log messages\nlogger.info(\"Application started\")\nlogger.warning(\"Memory usage at 85%\")\nlogger.error(\"Failed to connect to API\")\nlogger.success(\"User registered successfully\")\nlogger.debug(\"Cache initialized with 1000 entries\")\n```\n\n## \ud83e\uddd1\u200d\ud83d\udcbb Examples\n\nSee [`examples/`](./examples) for ready-to-run scripts:\n\n- `simple_usage.py` \u2014 basic logging\n- `fastapi_webapp.py` \u2014 FastAPI integration\n- `advanced_config.py` \u2014 production config\n- `high_performance.py` \u2014 high-speed big data logging demo\n\n\n## \ud83d\udce6 Installation\n\n```bash\npip install tamga # Basic installation\npip install tamga[mongo] # With MongoDB support\npip install tamga[notifications] # With notification support\npip install tamga[all] # All features\n```\n\n## \ud83c\udfaf Usage Examples\n\n### Basic Configuration\n```python\nlogger = Tamga(\n # Display settings\n colored_output=True, # Colored output\n show_time=True, # Include timestamp\n show_timezone=False, # Include timezone\n\n # Output destinations\n file_output=True, # Log to file\n file_path=\"app.log\", # Log file path\n buffer_size=50, # Buffer size for performance\n)\n```\n\n### Structured Logging\n```python\n# Log with key-value data using any log method\nlogger.info(\"User action\",\n user_id=\"123\",\n action=\"login\",\n ip_address=\"192.168.1.1\",\n success=True\n)\n\n# Works with all log levels\nlogger.error(\"Database connection failed\",\n host=\"localhost\",\n port=5432,\n timeout=30,\n retry_count=3\n)\n\nlogger.success(\"Payment processed\",\n amount=99.99,\n currency=\"USD\",\n method=\"credit_card\",\n transaction_id=\"tx_123\"\n)\n```\n\n### Production Setup\n```python\nlogger = Tamga(\n # File rotation\n file_output=True,\n max_file_size_mb=50, # 50MB max file size\n enable_backup=True, # Create backups\n\n # Performance\n buffer_size=200, # Larger buffer for production\n console_output=False, # Disable console for speed\n\n # External services\n mongo_output=True,\n mongo_uri=\"mongodb://...\",\n\n # Multi-service notifications\n notify_services=[\n \"discord://webhook_id/webhook_token\",\n \"slack://tokenA/tokenB/tokenC/#alerts\",\n \"mailto://user:pass@smtp.gmail.com:587/?to=alerts@company.com\",\n \"twilio://SID:Token@+1234567890/+0987654321\",\n ],\n notify_levels=[\"CRITICAL\", \"ERROR\", \"NOTIFY\"],\n)\n```\n\n## \ud83d\udccb Log Levels\n\n| Level | Color | Method | Use Case |\n|-------|-------|---------|----------|\n| INFO | Sky | `logger.info()` | General information |\n| WARNING | Amber | `logger.warning()` | Warning messages |\n| ERROR | Rose | `logger.error()` | Error messages |\n| SUCCESS | Emerald | `logger.success()` | Success messages |\n| DEBUG | Indigo | `logger.debug()` | Debug information |\n| CRITICAL | Red | `logger.critical()` | Critical issues |\n| DATABASE | Green | `logger.database()` | Database operations |\n| NOTIFY | Purple | `logger.notify()` | Send notifications |\n| METRIC | Cyan | `logger.metric()` | Performance metrics |\n| TRACE | Gray | `logger.trace()` | Detailed trace info |\n| CUSTOM | Any | `logger.custom()` | Custom levels |\n\n## \ud83d\udd27 Advanced Features\n\n### Notifications\n```python\n# Configure notification services (supports 80+ services via Apprise)\nlogger = Tamga(\n notify_services=[\n \"discord://webhook_id/webhook_token\",\n \"slack://tokenA/tokenB/tokenC/#channel\",\n ],\n notify_levels=[\"CRITICAL\", \"ERROR\", \"NOTIFY\"],\n notify_title=\"{appname}: {level} Alert\",\n notify_format=\"markdown\", # text, markdown, or html\n)\n\n# Send notification\nlogger.notify(\"Payment received from user #123\")\n\n# Critical logs also trigger notifications\nlogger.critical(\"Database connection lost\")\n```\n\n### Custom Log Levels\n```python\nlogger.custom(\"Deploy completed\", \"DEPLOY\", \"purple\")\nlogger.custom(\"Payment received\", \"PAYMENT\", \"green\")\n```\n\n### Buffer Control\n```python\n# Force write all buffered logs\nlogger.flush()\n```\n\n### File Rotation\nWhen log files reach `max_file_size_mb`, Tamga automatically:\n- Creates timestamped backups (if enabled)\n- Clears the original file\n- Continues logging seamlessly\n\n## \ud83d\udcca Performance\n\nTamga uses a buffered writing system that delivers significantly faster performance compared to traditional logging. The buffering mechanism provides optimal throughput for high-volume logging scenarios while maintaining thread safety.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- [PyPI Package](https://pypi.org/project/tamga/)\n- [GitHub Repository](https://github.com/DogukanUrker/Tamga)\n- [Documentation](https://tamga.vercel.app/)\n- [Bug Reports](https://github.com/DogukanUrker/Tamga/issues)\n\n---\n\n<p align=\"center\">\n Made with \u2764\ufe0f by <a href=\"https://github.com/DogukanUrker\">Do\u011fukan \u00dcrker</a>\n</p>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern, high-performance async logging utility with multiple output formats and colorful console output",
"version": "1.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/dogukanurker/tamga/issues",
"Changelog": "https://github.com/DogukanUrker/Tamga/releases",
"Documentation": "https://tamga.vercel.app/",
"Homepage": "https://tamga.vercel.app/",
"Source": "https://github.com/dogukanurker/tamga/"
},
"split_keywords": [
"logging",
" async",
" mongodb",
" colorful",
" console",
" file",
" json",
" sql",
" notifications",
" apprise",
" performance",
" buffered",
" alerting",
" monitoring",
" discord",
" slack",
" email",
" sms",
" webhooks",
" telegram",
" modern",
" high-performance",
" logger",
" structured-logging",
" developer-tools",
" observability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bf1aa7dbf8d4f381db5bd941c3db4bcb4932a3b1dcfdb1b9e926a5bde402ce02",
"md5": "7a70eebfbcc28e8bca92b2a53b24f24a",
"sha256": "e2000fb9410582278337af15b397efe76ba96c72d57b81c9af5b626085bbe092"
},
"downloads": -1,
"filename": "tamga-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a70eebfbcc28e8bca92b2a53b24f24a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17099,
"upload_time": "2025-07-12T23:01:40",
"upload_time_iso_8601": "2025-07-12T23:01:40.295350Z",
"url": "https://files.pythonhosted.org/packages/bf/1a/a7dbf8d4f381db5bd941c3db4bcb4932a3b1dcfdb1b9e926a5bde402ce02/tamga-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eb2b1f8841bb4d36b950bb283bd833ccddc8a646858806a3f4ca0b9ba23b6ed9",
"md5": "5a8878dfbb04e52dc7c5ea3e70e359d4",
"sha256": "960faf5cc6a19333aeb04d45ec0980d3f6ad5bcbbd5075d7925e644552011c02"
},
"downloads": -1,
"filename": "tamga-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "5a8878dfbb04e52dc7c5ea3e70e359d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21497,
"upload_time": "2025-07-12T23:01:41",
"upload_time_iso_8601": "2025-07-12T23:01:41.548953Z",
"url": "https://files.pythonhosted.org/packages/eb/2b/1f8841bb4d36b950bb283bd833ccddc8a646858806a3f4ca0b9ba23b6ed9/tamga-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 23:01:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dogukanurker",
"github_project": "tamga",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tamga"
}
JSON
