# Kakashi - High-Performance Python Logging Utility
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/kakashi)
Enterprise-grade logging for Python with a modern functional pipeline, structured logging, and first-class FastAPI/Flask/Django integrations. Backward-compatible aliases are kept, but the functional API is now the recommended path.
## 🚀 Features
- **✅ Functional API (new)**: Immutable config, composable pipelines, thread-safe by design
- **🧱 Structured logging**: JSON and compact text formatters for consistent logs
- **📡 Enterprise integrations (new)**: One-line setup for FastAPI, Flask, and Django
- **📅 Rotation & files**: Daily rotation with 100MB size fallback; per-module files
- **🎨 Color control**: Bright/disabled modes; independent console/file color config
- **🌐 Context**: Request, user, and custom context fields with helpers
- **⚙️ Environments**: Development/production/testing presets with `setup()`
## 📦 Installation
### Basic Installation
```bash
pip install kakashi
```
### With integrations
```bash
pip install kakashi[fastapi]
```
```bash
pip install kakashi[flask]
```
```bash
pip install kakashi[django]
```
All web integrations:
```bash
pip install kakashi[web]
```
### Development Installation
```bash
pip install kakashi[dev]
```
Optional performance extras:
```bash
pip install kakashi[performance]
```
Everything:
```bash
pip install kakashi[all]
```
## 🛠️ Quick Start
### Basic Usage (simple API)
```python
import kakashi
# Intelligent, one-line setup (auto-detects environment and sensible defaults)
kakashi.setup()
# Ultra-simple logging helpers
kakashi.info("Application started")
kakashi.warning("This is a warning message")
kakashi.error("Something went wrong", component="startup")
```
### Module loggers (structured)
```python
from kakashi import get_structured_logger
app_logger = get_structured_logger("myapp")
db_logger = get_structured_logger("myapp.database")
api_logger = get_structured_logger("myapp.api")
db_logger.info("Database connection established", db="primary")
api_logger.info("Endpoint called", route="/users")
```
### Request/user/custom context
```python
from kakashi import (
get_structured_logger,
set_request_context,
set_user_context,
set_custom_context,
clear_request_context,
)
logger = get_structured_logger(__name__)
set_request_context("192.168.1.100", "POST /api/users")
set_user_context(user_id="42", role="admin")
set_custom_context(trace_id="abc-123")
logger.info("User created successfully")
clear_request_context()
```
### FastAPI integration (enterprise)
```python
from fastapi import FastAPI
import kakashi
app = FastAPI()
kakashi.setup_fastapi(app, service_name="my-api", environment="production")
@app.get("/")
async def root():
kakashi.info("Root endpoint accessed")
return {"message": "Hello World"}
```
## 📋 Log Format
The default log format includes:
```text
TIMESTAMP | LEVEL | MODULE | ACCESS | IP | MESSAGE
2024-01-15 10:30:45.123 | INFO | myapp.users | POST /api/users | 192.168.1.100 | User created successfully
```
## 🎨 Color Configuration
### Enable Bright Colors
```python
from kakashi import enable_bright_colors
enable_bright_colors()
```
### Disable All Colors
```python
from kakashi import disable_colors
disable_colors()
```
### Custom Color Configuration
```python
from kakashi import configure_colors
# Bright console colors, plain file logs
configure_colors(bright_colors=True, colored_file_logs=False)
```
## ⚙️ Environment Configuration
### Development Setup
```python
import kakashi
kakashi.setup("development") # Verbose console output
```
### Production Setup
```python
import kakashi
kakashi.setup("production", service="user-api", version="2.1.0")
```
## 📁 Log File Organization
```text
logs/
├── app.log # Default application logs
└── modules/
├── database.log # Database-specific logs
├── api.log # API-specific logs
├── authentication.log # Auth-specific logs
└── background_tasks.log # Background task logs
```
## 🔧 Advanced Configuration
### Log Level Configuration
```python
from kakashi import set_log_level
set_log_level('DEBUG') # Set global log level
```
### Console and File Color Settings
```python
from kakashi import set_console_colors, set_file_colors
set_console_colors(bright=True) # Bright console colors
set_file_colors(enabled=True, bright=False) # Normal file colors
```
### Request Context Management
```python
from kakashi import set_request_context, clear_request_context
# Set context
set_request_context("192.168.1.100", "GET /api/data")
# Your logging here...
# Clear context when done
clear_request_context()
```
## 🔌 Web Framework Integrations
### FastAPI (one-line enterprise setup)
```python
from fastapi import FastAPI
import kakashi
app = FastAPI()
kakashi.setup_fastapi(app)
```
### Flask (one-line enterprise setup)
```python
from flask import Flask
import kakashi
app = Flask(__name__)
kakashi.setup_flask(app)
@app.route("/")
def index():
kakashi.info("Flask index hit")
return {"ok": True}
### Django (URL patterns provided)
In Django, call `kakashi.setup_django()` in your startup (e.g., `apps.py`), then include the provided health/metrics URLs from `kakashi.integrations.django_integration.urlpatterns`.
## 🧪 Running the Demo
After installation, you can run the built-in demo:
```bash
kakashi-demo
```
This will create example log files in the `logs/` directory demonstrating all features.
## 🧭 Deprecations and Compatibility
- The legacy singleton-style API is maintained for compatibility but will be deprecated in future versions. Prefer the functional API exposed via `kakashi.core` and the simple top-level helpers in `kakashi`.
- Old middleware names like `IPLoggingMiddleware` and functions like `create_ip_logging_middleware`, `setup_fastapi_logging`, `init_flask_logging`, and legacy Django aliases now map to the new enterprise integrations and may be removed in the future. Use:
- FastAPI: `kakashi.setup_fastapi(app, ...)`
- Flask: `kakashi.setup_flask(app, ...)`
- Django: `kakashi.setup_django(...)`
See optional extras in installation for `fastapi`, `flask`, `django`, `web`, `performance`, and `all` bundles.
## 📚 API Reference
### Core Functions
- `setup(environment=None, service=None, version=None, ...)`: One-line intelligent setup
- `get_logger(name)`: Traditional logger instance (compat)
- `get_structured_logger(name)`: Structured logger instance (recommended)
- `get_request_logger(name)`: Logger with request context helpers
- `set_log_level(level)`: Set global log level
- `setup_logging(environment)`: Advanced environment configuration
- `set_request_context(ip, access)`, `set_user_context(...)`, `set_custom_context(...)`, `clear_request_context()`
### Color Configuration
- `configure_colors(bright_colors, colored_file_logs, bright_file_colors)`
- `enable_bright_colors()` / `disable_colors()`
- `set_console_colors(bright)` / `set_file_colors(enabled, bright)`
### Middleware (Compatibility)
- Legacy names like `IPLoggingMiddleware` map to enterprise integrations. Prefer:
- `setup_fastapi(app, ...)`
- `setup_flask(app, ...)`
- `setup_django(...)`
## 🏗️ Architecture
The core is a functional, pipeline-based design with immutable configuration:
- **Pipelines**: Composable enrichers, filters, formatters, and writers
- **Context**: Structured `LogContext` with helpers for request/user/custom fields
- **Async backend**: Optional async pipelines for high-throughput scenarios
- **Rotation**: Daily rotation with size-based fallback for file writers
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built for the NCCF Project
- Inspired by the need for production-ready logging solutions
- Thanks to the FastAPI and Starlette communities for middleware inspiration
## 📞 Support
For support, please open an issue on the [GitHub repository](https://github.com/IntegerAlex/kakashi/issues).
Raw data
{
"_id": null,
"home_page": "https://github.com/IntegerAlex/kakashi",
"name": "kakashi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Akshat Kotpalliwar <akshatkot@gmail.com>",
"keywords": "logging, logger, fastapi, middleware, colored-logs, performance, singleton, rotation",
"author": "Akshat Kotpalliwar",
"author_email": "Akshat Kotpalliwar <akshatkot@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/90/11/2ef85db73234b1faf1dfab0a9d4bdfe09e74e6a52b5145a1d6f66036b3e9/kakashi-0.1.0.tar.gz",
"platform": null,
"description": "# Kakashi - High-Performance Python Logging Utility\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/kakashi)\n\nEnterprise-grade logging for Python with a modern functional pipeline, structured logging, and first-class FastAPI/Flask/Django integrations. Backward-compatible aliases are kept, but the functional API is now the recommended path.\n\n## \ud83d\ude80 Features\n\n- **\u2705 Functional API (new)**: Immutable config, composable pipelines, thread-safe by design\n- **\ud83e\uddf1 Structured logging**: JSON and compact text formatters for consistent logs\n- **\ud83d\udce1 Enterprise integrations (new)**: One-line setup for FastAPI, Flask, and Django\n- **\ud83d\udcc5 Rotation & files**: Daily rotation with 100MB size fallback; per-module files\n- **\ud83c\udfa8 Color control**: Bright/disabled modes; independent console/file color config\n- **\ud83c\udf10 Context**: Request, user, and custom context fields with helpers\n- **\u2699\ufe0f Environments**: Development/production/testing presets with `setup()`\n\n## \ud83d\udce6 Installation\n\n### Basic Installation\n\n```bash\npip install kakashi\n```\n\n### With integrations\n\n```bash\npip install kakashi[fastapi]\n```\n\n```bash\npip install kakashi[flask]\n```\n\n```bash\npip install kakashi[django]\n```\n\nAll web integrations:\n\n```bash\npip install kakashi[web]\n```\n\n### Development Installation\n\n```bash\npip install kakashi[dev]\n```\n\nOptional performance extras:\n\n```bash\npip install kakashi[performance]\n```\n\nEverything:\n\n```bash\npip install kakashi[all]\n```\n\n## \ud83d\udee0\ufe0f Quick Start\n\n### Basic Usage (simple API)\n\n```python\nimport kakashi\n\n# Intelligent, one-line setup (auto-detects environment and sensible defaults)\nkakashi.setup()\n\n# Ultra-simple logging helpers\nkakashi.info(\"Application started\")\nkakashi.warning(\"This is a warning message\")\nkakashi.error(\"Something went wrong\", component=\"startup\")\n```\n\n### Module loggers (structured)\n\n```python\nfrom kakashi import get_structured_logger\n\napp_logger = get_structured_logger(\"myapp\")\ndb_logger = get_structured_logger(\"myapp.database\")\napi_logger = get_structured_logger(\"myapp.api\")\n\ndb_logger.info(\"Database connection established\", db=\"primary\")\napi_logger.info(\"Endpoint called\", route=\"/users\")\n```\n\n### Request/user/custom context\n\n```python\nfrom kakashi import (\n get_structured_logger,\n set_request_context,\n set_user_context,\n set_custom_context,\n clear_request_context,\n)\n\nlogger = get_structured_logger(__name__)\nset_request_context(\"192.168.1.100\", \"POST /api/users\")\nset_user_context(user_id=\"42\", role=\"admin\")\nset_custom_context(trace_id=\"abc-123\")\nlogger.info(\"User created successfully\")\nclear_request_context()\n```\n\n### FastAPI integration (enterprise)\n\n```python\nfrom fastapi import FastAPI\nimport kakashi\n\napp = FastAPI()\nkakashi.setup_fastapi(app, service_name=\"my-api\", environment=\"production\")\n\n@app.get(\"/\")\nasync def root():\n kakashi.info(\"Root endpoint accessed\")\n return {\"message\": \"Hello World\"}\n```\n\n## \ud83d\udccb Log Format\n\nThe default log format includes:\n\n```text\nTIMESTAMP | LEVEL | MODULE | ACCESS | IP | MESSAGE\n2024-01-15 10:30:45.123 | INFO | myapp.users | POST /api/users | 192.168.1.100 | User created successfully\n```\n\n## \ud83c\udfa8 Color Configuration\n\n### Enable Bright Colors\n\n```python\nfrom kakashi import enable_bright_colors\n\nenable_bright_colors()\n```\n\n### Disable All Colors\n\n```python\nfrom kakashi import disable_colors\n\ndisable_colors()\n```\n\n### Custom Color Configuration\n\n```python\nfrom kakashi import configure_colors\n\n# Bright console colors, plain file logs\nconfigure_colors(bright_colors=True, colored_file_logs=False)\n```\n\n## \u2699\ufe0f Environment Configuration\n\n### Development Setup\n\n```python\nimport kakashi\nkakashi.setup(\"development\") # Verbose console output\n```\n\n### Production Setup\n\n```python\nimport kakashi\nkakashi.setup(\"production\", service=\"user-api\", version=\"2.1.0\")\n```\n\n## \ud83d\udcc1 Log File Organization\n\n```text\nlogs/\n\u251c\u2500\u2500 app.log # Default application logs\n\u2514\u2500\u2500 modules/\n \u251c\u2500\u2500 database.log # Database-specific logs\n \u251c\u2500\u2500 api.log # API-specific logs\n \u251c\u2500\u2500 authentication.log # Auth-specific logs\n \u2514\u2500\u2500 background_tasks.log # Background task logs\n```\n\n## \ud83d\udd27 Advanced Configuration\n\n### Log Level Configuration\n\n```python\nfrom kakashi import set_log_level\n\nset_log_level('DEBUG') # Set global log level\n```\n\n### Console and File Color Settings\n\n```python\nfrom kakashi import set_console_colors, set_file_colors\n\nset_console_colors(bright=True) # Bright console colors\nset_file_colors(enabled=True, bright=False) # Normal file colors\n```\n\n### Request Context Management\n\n```python\nfrom kakashi import set_request_context, clear_request_context\n\n# Set context\nset_request_context(\"192.168.1.100\", \"GET /api/data\")\n\n# Your logging here...\n\n# Clear context when done\nclear_request_context()\n```\n\n## \ud83d\udd0c Web Framework Integrations\n\n### FastAPI (one-line enterprise setup)\n\n```python\nfrom fastapi import FastAPI\nimport kakashi\n\napp = FastAPI()\nkakashi.setup_fastapi(app)\n```\n\n### Flask (one-line enterprise setup)\n\n```python\nfrom flask import Flask\nimport kakashi\n\napp = Flask(__name__)\nkakashi.setup_flask(app)\n\n@app.route(\"/\")\ndef index():\n kakashi.info(\"Flask index hit\")\n return {\"ok\": True}\n\n### Django (URL patterns provided)\n\nIn Django, call `kakashi.setup_django()` in your startup (e.g., `apps.py`), then include the provided health/metrics URLs from `kakashi.integrations.django_integration.urlpatterns`.\n\n## \ud83e\uddea Running the Demo\n\nAfter installation, you can run the built-in demo:\n\n```bash\nkakashi-demo\n```\n\nThis will create example log files in the `logs/` directory demonstrating all features.\n\n## \ud83e\udded Deprecations and Compatibility\n\n- The legacy singleton-style API is maintained for compatibility but will be deprecated in future versions. Prefer the functional API exposed via `kakashi.core` and the simple top-level helpers in `kakashi`.\n- Old middleware names like `IPLoggingMiddleware` and functions like `create_ip_logging_middleware`, `setup_fastapi_logging`, `init_flask_logging`, and legacy Django aliases now map to the new enterprise integrations and may be removed in the future. Use:\n - FastAPI: `kakashi.setup_fastapi(app, ...)`\n - Flask: `kakashi.setup_flask(app, ...)`\n - Django: `kakashi.setup_django(...)`\n\nSee optional extras in installation for `fastapi`, `flask`, `django`, `web`, `performance`, and `all` bundles.\n\n## \ud83d\udcda API Reference\n\n### Core Functions\n\n- `setup(environment=None, service=None, version=None, ...)`: One-line intelligent setup\n- `get_logger(name)`: Traditional logger instance (compat)\n- `get_structured_logger(name)`: Structured logger instance (recommended)\n- `get_request_logger(name)`: Logger with request context helpers\n- `set_log_level(level)`: Set global log level\n- `setup_logging(environment)`: Advanced environment configuration\n- `set_request_context(ip, access)`, `set_user_context(...)`, `set_custom_context(...)`, `clear_request_context()`\n\n### Color Configuration\n\n- `configure_colors(bright_colors, colored_file_logs, bright_file_colors)`\n- `enable_bright_colors()` / `disable_colors()`\n- `set_console_colors(bright)` / `set_file_colors(enabled, bright)`\n\n### Middleware (Compatibility)\n\n- Legacy names like `IPLoggingMiddleware` map to enterprise integrations. Prefer:\n - `setup_fastapi(app, ...)`\n - `setup_flask(app, ...)`\n - `setup_django(...)`\n\n## \ud83c\udfd7\ufe0f Architecture\n\nThe core is a functional, pipeline-based design with immutable configuration:\n\n- **Pipelines**: Composable enrichers, filters, formatters, and writers\n- **Context**: Structured `LogContext` with helpers for request/user/custom fields\n- **Async backend**: Optional async pipelines for high-throughput scenarios\n- **Rotation**: Daily rotation with size-based fallback for file writers\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open 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\ude4f Acknowledgments\n\n- Built for the NCCF Project\n- Inspired by the need for production-ready logging solutions\n- Thanks to the FastAPI and Starlette communities for middleware inspiration\n\n## \ud83d\udcde Support\n\nFor support, please open an issue on the [GitHub repository](https://github.com/IntegerAlex/kakashi/issues).\n",
"bugtrack_url": null,
"license": null,
"summary": "High-performance logging utility for Python applications with advanced features",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/IntegerAlex/kakashi/issues",
"Documentation": "https://github.com/IntegerAlex/kakashi/wiki",
"Homepage": "https://github.com/IntegerAlex/kakashi",
"Repository": "https://github.com/IntegerAlex/kakashi"
},
"split_keywords": [
"logging",
" logger",
" fastapi",
" middleware",
" colored-logs",
" performance",
" singleton",
" rotation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8d271db55d8797f44ea3525a938fe02c6afa93c53b151a81769cb6b3117b29eb",
"md5": "1e460a1402d201cd78364ebd0482bbf3",
"sha256": "f4ab115b9a97c4fe71d391b17340ed17d570ae597ed879ae3e5a1326f128d651"
},
"downloads": -1,
"filename": "kakashi-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e460a1402d201cd78364ebd0482bbf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 115213,
"upload_time": "2025-08-22T15:38:19",
"upload_time_iso_8601": "2025-08-22T15:38:19.470648Z",
"url": "https://files.pythonhosted.org/packages/8d/27/1db55d8797f44ea3525a938fe02c6afa93c53b151a81769cb6b3117b29eb/kakashi-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "90112ef85db73234b1faf1dfab0a9d4bdfe09e74e6a52b5145a1d6f66036b3e9",
"md5": "f336e36cb2882e629f75401d18274eef",
"sha256": "85bf499dc4fc1e3670b3ab2a34c6a561d89f81e76bdbae6558cc510f8d3dd658"
},
"downloads": -1,
"filename": "kakashi-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f336e36cb2882e629f75401d18274eef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 100861,
"upload_time": "2025-08-22T15:38:23",
"upload_time_iso_8601": "2025-08-22T15:38:23.351036Z",
"url": "https://files.pythonhosted.org/packages/90/11/2ef85db73234b1faf1dfab0a9d4bdfe09e74e6a52b5145a1d6f66036b3e9/kakashi-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 15:38:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IntegerAlex",
"github_project": "kakashi",
"github_not_found": true,
"lcname": "kakashi"
}
JSON
