pycommonlog 0.0.0__tar.gz

pycommonlog-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alvian Rahman Hanif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycommonlog-0.0.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: pycommonlog
+Version: 0.0.0
+Summary: Unified logging and alerting library for Python.
+Home-page: https://github.com/alvianhanif/pycommonlog
+Author: Alvian Rahman Hanif
+Author-email: alvian.hanif@pasarpolis.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# pycommonlog
+
+[![CI](https://github.com/alvianhanif/pycommonlog/actions/workflows/ci.yml/badge.svg)](https://github.com/alvianhanif/pycommonlog/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pycommonlog.svg)](https://badge.fury.io/py/pycommonlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A unified logging and alerting library for Python, supporting Slack and Lark integrations via WebClient and Webhook. Features configurable providers, alert levels, and file attachment support.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install pycommonlog
+```
+
+Or copy the `pycommonlog/` directory to your project.
+
+
+## Usage
+
+```python
+from pycommonlog import commonlog, Config, SendMethod, AlertLevel, Attachment, LarkToken
+
+# Configure logger
+config = Config(
+    provider="lark", # or "slack"
+    send_method=SendMethod.WEBCLIENT,
+    token="app_id++app_secret", # for Lark, use "app_id++app_secret" format
+    slack_token="xoxb-your-slack-token", # dedicated Slack token
+    lark_token=LarkToken(app_id="your-app-id", app_secret="your-app-secret"), # dedicated Lark token
+    channel="your_lark_channel_id",
+    redis_host="localhost", # required for Lark
+    redis_port="6379",      # required for Lark
+)
+logger = commonlog(config)
+
+# Send error with attachment
+try:
+    logger.send(AlertLevel.ERROR, "System error occurred", Attachment(url="https://example.com/log.txt"))
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+
+ # Send info (logs only)
+logger.send(AlertLevel.INFO, "Info message")
+
+# Send to a specific channel
+try:
+    logger.send_to_channel(AlertLevel.ERROR, "Send to another channel", channel="another-channel-id")
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+
+# Send to a different provider dynamically
+try:
+    logger.custom_send("slack", AlertLevel.ERROR, "Message via Slack", channel="slack-channel")
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+```
+
+## Send Methods
+
+commonlog supports two send methods: WebClient (API-based) and Webhook (simple HTTP POST).
+
+### WebClient Usage
+
+WebClient uses the full API with authentication tokens:
+
+```python
+config = Config(
+    provider="lark",
+    send_method=SendMethod.WEBCLIENT,
+    token="app_id++app_secret",  # for Lark
+    slack_token="xoxb-your-slack-token",  # for Slack
+    lark_token=LarkToken(app_id="your-app-id", app_secret="your-app-secret"),
+    channel="your_channel",
+    redis_host="localhost",  # required for Lark
+    redis_port="6379",
+)
+```
+
+### Webhook Usage
+
+Webhook is simpler and requires only a webhook URL:
+
+```python
+config = Config(
+    provider="slack",
+    send_method=SendMethod.WEBHOOK,
+    token="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+    channel="optional-channel-override",  # optional
+)
+```
+
+### Lark Token Caching
+
+When using Lark, the tenant_access_token is cached in Redis. The expiry is set dynamically from the API response minus 10 minutes. You must set `redis_host` and `redis_port` in your config.
+
+## Channel Mapping
+
+You can configure different channels for different alert levels using a channel resolver:
+
+```python
+from commonlog import commonlog, Config, SendMethod, AlertLevel, DefaultChannelResolver
+
+# Create a channel resolver
+resolver = DefaultChannelResolver(
+    channel_map={
+        AlertLevel.INFO: "#general",
+        AlertLevel.WARN: "#warnings",
+        AlertLevel.ERROR: "#alerts",
+    },
+    default_channel="#general"
+)
+
+# Create config with channel resolver
+config = Config(
+    provider="slack",
+    send_method=SendMethod.WEBCLIENT,
+    token="xoxb-your-slack-bot-token",
+    channel_resolver=resolver,
+    service_name="user-service",
+    environment="production"
+)
+
+logger = commonlog(config)
+
+# These will go to different channels based on level
+logger.send(AlertLevel.INFO, "Info message")    # goes to #general
+logger.send(AlertLevel.WARN, "Warning message") # goes to #warnings
+logger.send(AlertLevel.ERROR, "Error message")  # goes to #alerts
+```
+
+### Custom Channel Resolver
+
+You can implement custom channel resolution logic:
+
+```python
+class CustomResolver(ChannelResolver):
+    def resolve_channel(self, level):
+        if level == AlertLevel.ERROR:
+            return "#critical-alerts"
+        elif level == AlertLevel.WARN:
+            return "#monitoring"
+        else:
+            return "#general"
+```
+
+## Configuration Options
+
+### Common Settings
+
+- **provider**: `"slack"` or `"lark"`
+- **send_method**: `"webclient"` (token-based authentication)
+- **channel**: Target channel or chat ID (used if no resolver)
+- **channel_resolver**: Optional resolver for dynamic channel mapping
+- **service_name**: Name of the service sending alerts
+- **environment**: Environment (dev, staging, production)
+- **debug**: `True` to enable detailed debug logging of all internal processes
+
+### Provider-Specific
+
+- **token**: API token for WebClient authentication (required)
+
+## Alert Levels
+
+- **INFO**: Logs locally only
+- **WARN**: Logs + sends alert
+- **ERROR**: Always sends alert
+
+## File Attachments
+
+Provide a public URL. The library appends it to the message for simplicity.
+
+```python
+attachment = Attachment(url="https://example.com/log.txt")
+logger.send(AlertLevel.ERROR, "Error with log", attachment)
+```
+
+## Trace Log Section
+
+When `include_trace` is set to `True`, you can pass trace information as the fourth parameter to `send()`:
+
+```python
+trace = """Traceback (most recent call last):
+  File "app.py", line 10, in main
+    raise ValueError("Something went wrong")
+ValueError: Something went wrong"""
+
+logger.send(AlertLevel.ERROR, "System error occurred", None, trace)
+```
+
+This will format the trace as a code block in the alert message.
+
+## Testing
+
+```bash
+cd python
+PYTHONPATH=.. python -m unittest test_commonlog.py
+```
+
+## API Reference
+
+### Classes
+
+- `Config`: Configuration class
+- `Attachment`: File attachment class
+- `Provider`: Abstract base class for alert providers
+- `commonlog`: Main logger class
+
+### Constants
+
+- `SendMethod.WEBCLIENT`: Send method (token-based authentication)
+- `AlertLevel.INFO`, `AlertLevel.WARN`, `AlertLevel.ERROR`: Alert levels
+
+### Methods
+
+- `commonlog(config)`: Create a new logger
+- `commonlog.send(level, message, attachment=None, trace="")`: Send alert with optional trace

pycommonlog-0.0.0/README.md

@@ -0,0 +1,218 @@
+# pycommonlog
+
+[![CI](https://github.com/alvianhanif/pycommonlog/actions/workflows/ci.yml/badge.svg)](https://github.com/alvianhanif/pycommonlog/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pycommonlog.svg)](https://badge.fury.io/py/pycommonlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A unified logging and alerting library for Python, supporting Slack and Lark integrations via WebClient and Webhook. Features configurable providers, alert levels, and file attachment support.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install pycommonlog
+```
+
+Or copy the `pycommonlog/` directory to your project.
+
+
+## Usage
+
+```python
+from pycommonlog import commonlog, Config, SendMethod, AlertLevel, Attachment, LarkToken
+
+# Configure logger
+config = Config(
+    provider="lark", # or "slack"
+    send_method=SendMethod.WEBCLIENT,
+    token="app_id++app_secret", # for Lark, use "app_id++app_secret" format
+    slack_token="xoxb-your-slack-token", # dedicated Slack token
+    lark_token=LarkToken(app_id="your-app-id", app_secret="your-app-secret"), # dedicated Lark token
+    channel="your_lark_channel_id",
+    redis_host="localhost", # required for Lark
+    redis_port="6379",      # required for Lark
+)
+logger = commonlog(config)
+
+# Send error with attachment
+try:
+    logger.send(AlertLevel.ERROR, "System error occurred", Attachment(url="https://example.com/log.txt"))
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+
+ # Send info (logs only)
+logger.send(AlertLevel.INFO, "Info message")
+
+# Send to a specific channel
+try:
+    logger.send_to_channel(AlertLevel.ERROR, "Send to another channel", channel="another-channel-id")
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+
+# Send to a different provider dynamically
+try:
+    logger.custom_send("slack", AlertLevel.ERROR, "Message via Slack", channel="slack-channel")
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+```
+
+## Send Methods
+
+commonlog supports two send methods: WebClient (API-based) and Webhook (simple HTTP POST).
+
+### WebClient Usage
+
+WebClient uses the full API with authentication tokens:
+
+```python
+config = Config(
+    provider="lark",
+    send_method=SendMethod.WEBCLIENT,
+    token="app_id++app_secret",  # for Lark
+    slack_token="xoxb-your-slack-token",  # for Slack
+    lark_token=LarkToken(app_id="your-app-id", app_secret="your-app-secret"),
+    channel="your_channel",
+    redis_host="localhost",  # required for Lark
+    redis_port="6379",
+)
+```
+
+### Webhook Usage
+
+Webhook is simpler and requires only a webhook URL:
+
+```python
+config = Config(
+    provider="slack",
+    send_method=SendMethod.WEBHOOK,
+    token="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+    channel="optional-channel-override",  # optional
+)
+```
+
+### Lark Token Caching
+
+When using Lark, the tenant_access_token is cached in Redis. The expiry is set dynamically from the API response minus 10 minutes. You must set `redis_host` and `redis_port` in your config.
+
+## Channel Mapping
+
+You can configure different channels for different alert levels using a channel resolver:
+
+```python
+from commonlog import commonlog, Config, SendMethod, AlertLevel, DefaultChannelResolver
+
+# Create a channel resolver
+resolver = DefaultChannelResolver(
+    channel_map={
+        AlertLevel.INFO: "#general",
+        AlertLevel.WARN: "#warnings",
+        AlertLevel.ERROR: "#alerts",
+    },
+    default_channel="#general"
+)
+
+# Create config with channel resolver
+config = Config(
+    provider="slack",
+    send_method=SendMethod.WEBCLIENT,
+    token="xoxb-your-slack-bot-token",
+    channel_resolver=resolver,
+    service_name="user-service",
+    environment="production"
+)
+
+logger = commonlog(config)
+
+# These will go to different channels based on level
+logger.send(AlertLevel.INFO, "Info message")    # goes to #general
+logger.send(AlertLevel.WARN, "Warning message") # goes to #warnings
+logger.send(AlertLevel.ERROR, "Error message")  # goes to #alerts
+```
+
+### Custom Channel Resolver
+
+You can implement custom channel resolution logic:
+
+```python
+class CustomResolver(ChannelResolver):
+    def resolve_channel(self, level):
+        if level == AlertLevel.ERROR:
+            return "#critical-alerts"
+        elif level == AlertLevel.WARN:
+            return "#monitoring"
+        else:
+            return "#general"
+```
+
+## Configuration Options
+
+### Common Settings
+
+- **provider**: `"slack"` or `"lark"`
+- **send_method**: `"webclient"` (token-based authentication)
+- **channel**: Target channel or chat ID (used if no resolver)
+- **channel_resolver**: Optional resolver for dynamic channel mapping
+- **service_name**: Name of the service sending alerts
+- **environment**: Environment (dev, staging, production)
+- **debug**: `True` to enable detailed debug logging of all internal processes
+
+### Provider-Specific
+
+- **token**: API token for WebClient authentication (required)
+
+## Alert Levels
+
+- **INFO**: Logs locally only
+- **WARN**: Logs + sends alert
+- **ERROR**: Always sends alert
+
+## File Attachments
+
+Provide a public URL. The library appends it to the message for simplicity.
+
+```python
+attachment = Attachment(url="https://example.com/log.txt")
+logger.send(AlertLevel.ERROR, "Error with log", attachment)
+```
+
+## Trace Log Section
+
+When `include_trace` is set to `True`, you can pass trace information as the fourth parameter to `send()`:
+
+```python
+trace = """Traceback (most recent call last):
+  File "app.py", line 10, in main
+    raise ValueError("Something went wrong")
+ValueError: Something went wrong"""
+
+logger.send(AlertLevel.ERROR, "System error occurred", None, trace)
+```
+
+This will format the trace as a code block in the alert message.
+
+## Testing
+
+```bash
+cd python
+PYTHONPATH=.. python -m unittest test_commonlog.py
+```
+
+## API Reference
+
+### Classes
+
+- `Config`: Configuration class
+- `Attachment`: File attachment class
+- `Provider`: Abstract base class for alert providers
+- `commonlog`: Main logger class
+
+### Constants
+
+- `SendMethod.WEBCLIENT`: Send method (token-based authentication)
+- `AlertLevel.INFO`, `AlertLevel.WARN`, `AlertLevel.ERROR`: Alert levels
+
+### Methods
+
+- `commonlog(config)`: Create a new logger
+- `commonlog.send(level, message, attachment=None, trace="")`: Send alert with optional trace

pycommonlog-0.0.0/pycommonlog/__init__.py

@@ -0,0 +1,20 @@
+"""
+commonlog: Unified logging and alerting for Slack/Lark (Python)
+"""
+
+from .log_types import SendMethod, AlertLevel, Attachment, Config, Provider, ChannelResolver, DefaultChannelResolver
+from .providers import SlackProvider, LarkProvider
+from .logger import commonlog
+
+__all__ = [
+    "SendMethod",
+    "AlertLevel", 
+    "Attachment",
+    "Config",
+    "Provider",
+    "ChannelResolver",
+    "DefaultChannelResolver",
+    "SlackProvider",
+    "LarkProvider",
+    "commonlog"
+]

pycommonlog-0.0.0/pycommonlog/log_types.py

@@ -0,0 +1,70 @@
+"""
+commonlog: Unified logging and alerting for Slack/Lark (Python)
+"""
+from abc import ABC, abstractmethod
+
+class SendMethod:
+    WEBCLIENT = "webclient"
+    WEBHOOK = "webhook"
+
+class AlertLevel:
+    INFO = 0
+    WARN = 1
+    ERROR = 2
+
+class Attachment:
+    def __init__(self, url=None, file_name=None, content=None):
+        self.url = url
+        self.file_name = file_name
+        self.content = content
+
+class ChannelResolver(ABC):
+    @abstractmethod
+    def resolve_channel(self, level):
+        pass
+
+class DefaultChannelResolver(ChannelResolver):
+    def __init__(self, channel_map=None, default_channel=None):
+        self.channel_map = channel_map or {}
+        self.default_channel = default_channel
+
+    def resolve_channel(self, level):
+        return self.channel_map.get(level, self.default_channel)
+
+class LarkToken:
+    def __init__(self, app_id=None, app_secret=None):
+        self.app_id = app_id
+        self.app_secret = app_secret
+
+class Config:
+    def __init__(self, provider, send_method, token=None, slack_token=None, lark_token=None, channel=None, channel_resolver=None, service_name=None, environment=None, redis_host=None, redis_port=None, debug=False):
+        self.provider = provider
+        self.send_method = send_method
+        self.token = token
+        self.slack_token = slack_token
+        self.lark_token = lark_token
+        self.channel = channel
+        self.channel_resolver = channel_resolver
+        self.service_name = service_name
+        self.environment = environment
+        self.redis_host = redis_host
+        self.redis_port = redis_port
+        self.debug = debug
+
+class Provider(ABC):
+    @abstractmethod
+    def send_to_channel(self, level, message, attachment, config, channel):
+        pass
+
+# Debug logging
+import logging
+
+debug_logger = logging.getLogger('commonlog.debug')
+debug_logger.setLevel(logging.DEBUG)
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter('[COMMONLOG DEBUG] %(filename)s:%(lineno)d - %(message)s'))
+debug_logger.addHandler(handler)
+
+def debug_log(config, message, *args):
+    if hasattr(config, 'debug') and config.debug:
+        debug_logger.debug(message, *args)

pycommonlog-0.0.0/pycommonlog/logger.py

@@ -0,0 +1,151 @@
+"""
+Main logger for commonlog
+"""
+import logging
+import sys
+import os
+
+# Add current directory to path for direct imports
+_current_dir = os.path.dirname(os.path.abspath(__file__))
+if _current_dir not in sys.path:
+    sys.path.insert(0, _current_dir)
+
+from providers import SlackProvider, LarkProvider
+from log_types import AlertLevel, Attachment, debug_log
+
+# ====================
+# Configuration and Logger
+# ====================
+
+class commonlog:
+    def send_to_channel(self, level, message, attachment=None, trace="", channel=None):
+        debug_log(self.config, f"send_to_channel called with level: {level}, message length: {len(message)}, channel: {channel}, has attachment: {attachment is not None}, has trace: {bool(trace)}")
+        
+        if level == AlertLevel.INFO:
+            logging.info(message)
+            debug_log(self.config, "INFO level message logged locally, skipping provider send")
+            return
+        try:
+            # Use provided channel or fallback to resolved channel
+            target_channel = channel if channel else self._resolve_channel(level)
+            if channel is None:
+                debug_log(self.config, f"Resolved channel using resolver: {target_channel}")
+            else:
+                debug_log(self.config, f"Using provided channel: {target_channel}")
+            
+            original_channel = self.config.channel
+            self.config.channel = target_channel
+            if trace:
+                debug_log(self.config, f"Processing trace attachment, trace length: {len(trace)}")
+                if attachment is None:
+                    attachment = Attachment(content=trace, file_name="trace.log")
+                    debug_log(self.config, "Created new trace attachment")
+                else:
+                    if attachment.content:
+                        attachment.content += "\n\n--- Trace Log ---\n" + trace
+                        debug_log(self.config, "Appended trace to existing attachment content")
+                    else:
+                        attachment.content = trace
+                        attachment.file_name = "trace.log"
+                        debug_log(self.config, "Set trace as attachment content")
+            
+            debug_log(self.config, f"Calling provider.send_to_channel with resolved channel: {target_channel}")
+            self.provider.send_to_channel(level, message, attachment, self.config, target_channel)
+            self.config.channel = original_channel
+            debug_log(self.config, "Provider send_to_channel completed successfully")
+        except Exception as e:
+            debug_log(self.config, f"Provider send_to_channel failed: {e}")
+            logging.error(f"Failed to send alert: {e}")
+            raise
+
+    def custom_send(self, provider, level, message, attachment=None, trace="", channel=None):
+        debug_log(self.config, f"custom_send called with custom provider: {provider}, level: {level}, message length: {len(message)}")
+        
+        if provider == "slack":
+            custom_provider = SlackProvider()
+        elif provider == "lark":
+            custom_provider = LarkProvider()
+        else:
+            logging.warning(f"Unknown provider: {provider}, defaulting to Slack")
+            custom_provider = SlackProvider()
+            debug_log(self.config, f"Unknown provider '{provider}', defaulted to slack")
+        
+        debug_log(self.config, f"Created custom provider: {provider}")
+
+        if level == AlertLevel.INFO:
+            logging.info(message)
+            debug_log(self.config, "INFO level message logged locally for custom provider, skipping send")
+            return
+        try:
+            # Use provided channel or fallback to resolved channel
+            target_channel = channel if channel else self._resolve_channel(level)
+            debug_log(self.config, f"Resolved channel for custom send: {target_channel}")
+            
+            original_channel = self.config.channel
+            self.config.channel = target_channel
+            if trace:
+                debug_log(self.config, f"Processing trace for custom send, trace length: {len(trace)}")
+                if attachment is None:
+                    attachment = Attachment(content=trace, file_name="trace.log")
+                else:
+                    if attachment.content:
+                        attachment.content += "\n\n--- Trace Log ---\n" + trace
+                    else:
+                        attachment.content = trace
+                        attachment.file_name = "trace.log"
+            debug_log(self.config, f"Calling custom provider.send with provider: {provider}, channel: {target_channel}")
+            custom_provider.send(level, message, attachment, self.config)
+            self.config.channel = original_channel
+            debug_log(self.config, "Custom provider send completed successfully")
+        except Exception as e:
+            debug_log(self.config, f"Custom provider send failed: {e}")
+            logging.error(f"Failed to send alert: {e}")
+            raise
+
+    def __init__(self, config):
+        self.config = config
+        if config.provider == "slack":
+            self.provider = SlackProvider()
+        elif config.provider == "lark":
+            self.provider = LarkProvider()
+        else:
+            logging.warning(f"Unknown provider: {config.provider}, defaulting to Slack")
+            self.provider = SlackProvider()
+        
+        debug_log(config, f"Created logger with provider: {config.provider}, send method: {config.send_method}, debug: {config.debug}")
+
+    def _resolve_channel(self, level):
+        if self.config.channel_resolver:
+            return self.config.channel_resolver.resolve_channel(level)
+        return self.config.channel
+
+    def send(self, level, message, attachment=None, trace=""):
+        if level == AlertLevel.INFO:
+            logging.info(message)
+            return
+        try:
+            # Resolve the channel for this alert level
+            resolved_channel = self._resolve_channel(level)
+            
+            # Temporarily modify config with resolved channel
+            original_channel = self.config.channel
+            self.config.channel = resolved_channel
+            
+            # If trace is provided, create an attachment
+            if trace:
+                if attachment is None:
+                    attachment = Attachment(content=trace, file_name="trace.log")
+                else:
+                    # If there's already an attachment, combine the trace content
+                    if attachment.content:
+                        attachment.content += "\n\n--- Trace Log ---\n" + trace
+                    else:
+                        attachment.content = trace
+                        attachment.file_name = "trace.log"
+            self.provider.send(level, message, attachment, self.config)
+            
+            # Restore original channel
+            self.config.channel = original_channel
+        except Exception as e:
+            logging.error(f"Failed to send alert: {e}")
+            raise

pycommonlog-0.0.0/pycommonlog.egg-info/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: pycommonlog
+Version: 0.0.0
+Summary: Unified logging and alerting library for Python.
+Home-page: https://github.com/alvianhanif/pycommonlog
+Author: Alvian Rahman Hanif
+Author-email: alvian.hanif@pasarpolis.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# pycommonlog
+
+[![CI](https://github.com/alvianhanif/pycommonlog/actions/workflows/ci.yml/badge.svg)](https://github.com/alvianhanif/pycommonlog/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pycommonlog.svg)](https://badge.fury.io/py/pycommonlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A unified logging and alerting library for Python, supporting Slack and Lark integrations via WebClient and Webhook. Features configurable providers, alert levels, and file attachment support.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install pycommonlog
+```
+
+Or copy the `pycommonlog/` directory to your project.
+
+
+## Usage
+
+```python
+from pycommonlog import commonlog, Config, SendMethod, AlertLevel, Attachment, LarkToken
+
+# Configure logger
+config = Config(
+    provider="lark", # or "slack"
+    send_method=SendMethod.WEBCLIENT,
+    token="app_id++app_secret", # for Lark, use "app_id++app_secret" format
+    slack_token="xoxb-your-slack-token", # dedicated Slack token
+    lark_token=LarkToken(app_id="your-app-id", app_secret="your-app-secret"), # dedicated Lark token
+    channel="your_lark_channel_id",
+    redis_host="localhost", # required for Lark
+    redis_port="6379",      # required for Lark
+)
+logger = commonlog(config)
+
+# Send error with attachment
+try:
+    logger.send(AlertLevel.ERROR, "System error occurred", Attachment(url="https://example.com/log.txt"))
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+
+ # Send info (logs only)
+logger.send(AlertLevel.INFO, "Info message")
+
+# Send to a specific channel
+try:
+    logger.send_to_channel(AlertLevel.ERROR, "Send to another channel", channel="another-channel-id")
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+
+# Send to a different provider dynamically
+try:
+    logger.custom_send("slack", AlertLevel.ERROR, "Message via Slack", channel="slack-channel")
+except Exception as e:
+    print(f"Failed to send alert: {e}")
+```
+
+## Send Methods
+
+commonlog supports two send methods: WebClient (API-based) and Webhook (simple HTTP POST).
+
+### WebClient Usage
+
+WebClient uses the full API with authentication tokens:
+
+```python
+config = Config(
+    provider="lark",
+    send_method=SendMethod.WEBCLIENT,
+    token="app_id++app_secret",  # for Lark
+    slack_token="xoxb-your-slack-token",  # for Slack
+    lark_token=LarkToken(app_id="your-app-id", app_secret="your-app-secret"),
+    channel="your_channel",
+    redis_host="localhost",  # required for Lark
+    redis_port="6379",
+)
+```
+
+### Webhook Usage
+
+Webhook is simpler and requires only a webhook URL:
+
+```python
+config = Config(
+    provider="slack",
+    send_method=SendMethod.WEBHOOK,
+    token="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+    channel="optional-channel-override",  # optional
+)
+```
+
+### Lark Token Caching
+
+When using Lark, the tenant_access_token is cached in Redis. The expiry is set dynamically from the API response minus 10 minutes. You must set `redis_host` and `redis_port` in your config.
+
+## Channel Mapping
+
+You can configure different channels for different alert levels using a channel resolver:
+
+```python
+from commonlog import commonlog, Config, SendMethod, AlertLevel, DefaultChannelResolver
+
+# Create a channel resolver
+resolver = DefaultChannelResolver(
+    channel_map={
+        AlertLevel.INFO: "#general",
+        AlertLevel.WARN: "#warnings",
+        AlertLevel.ERROR: "#alerts",
+    },
+    default_channel="#general"
+)
+
+# Create config with channel resolver
+config = Config(
+    provider="slack",
+    send_method=SendMethod.WEBCLIENT,
+    token="xoxb-your-slack-bot-token",
+    channel_resolver=resolver,
+    service_name="user-service",
+    environment="production"
+)
+
+logger = commonlog(config)
+
+# These will go to different channels based on level
+logger.send(AlertLevel.INFO, "Info message")    # goes to #general
+logger.send(AlertLevel.WARN, "Warning message") # goes to #warnings
+logger.send(AlertLevel.ERROR, "Error message")  # goes to #alerts
+```
+
+### Custom Channel Resolver
+
+You can implement custom channel resolution logic:
+
+```python
+class CustomResolver(ChannelResolver):
+    def resolve_channel(self, level):
+        if level == AlertLevel.ERROR:
+            return "#critical-alerts"
+        elif level == AlertLevel.WARN:
+            return "#monitoring"
+        else:
+            return "#general"
+```
+
+## Configuration Options
+
+### Common Settings
+
+- **provider**: `"slack"` or `"lark"`
+- **send_method**: `"webclient"` (token-based authentication)
+- **channel**: Target channel or chat ID (used if no resolver)
+- **channel_resolver**: Optional resolver for dynamic channel mapping
+- **service_name**: Name of the service sending alerts
+- **environment**: Environment (dev, staging, production)
+- **debug**: `True` to enable detailed debug logging of all internal processes
+
+### Provider-Specific
+
+- **token**: API token for WebClient authentication (required)
+
+## Alert Levels
+
+- **INFO**: Logs locally only
+- **WARN**: Logs + sends alert
+- **ERROR**: Always sends alert
+
+## File Attachments
+
+Provide a public URL. The library appends it to the message for simplicity.
+
+```python
+attachment = Attachment(url="https://example.com/log.txt")
+logger.send(AlertLevel.ERROR, "Error with log", attachment)
+```
+
+## Trace Log Section
+
+When `include_trace` is set to `True`, you can pass trace information as the fourth parameter to `send()`:
+
+```python
+trace = """Traceback (most recent call last):
+  File "app.py", line 10, in main
+    raise ValueError("Something went wrong")
+ValueError: Something went wrong"""
+
+logger.send(AlertLevel.ERROR, "System error occurred", None, trace)
+```
+
+This will format the trace as a code block in the alert message.
+
+## Testing
+
+```bash
+cd python
+PYTHONPATH=.. python -m unittest test_commonlog.py
+```
+
+## API Reference
+
+### Classes
+
+- `Config`: Configuration class
+- `Attachment`: File attachment class
+- `Provider`: Abstract base class for alert providers
+- `commonlog`: Main logger class
+
+### Constants
+
+- `SendMethod.WEBCLIENT`: Send method (token-based authentication)
+- `AlertLevel.INFO`, `AlertLevel.WARN`, `AlertLevel.ERROR`: Alert levels
+
+### Methods
+
+- `commonlog(config)`: Create a new logger
+- `commonlog.send(level, message, attachment=None, trace="")`: Send alert with optional trace

pycommonlog-0.0.0/pycommonlog.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+pycommonlog/__init__.py
+pycommonlog/log_types.py
+pycommonlog/logger.py
+pycommonlog.egg-info/PKG-INFO
+pycommonlog.egg-info/SOURCES.txt
+pycommonlog.egg-info/dependency_links.txt
+pycommonlog.egg-info/top_level.txt

pycommonlog-0.0.0/pycommonlog.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pycommonlog-0.0.0/pycommonlog.egg-info/top_level.txt

@@ -0,0 +1 @@
+pycommonlog

pycommonlog-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pycommonlog-0.0.0/setup.py

@@ -0,0 +1,35 @@
+from setuptools import setup, find_packages
+import subprocess
+
+def get_latest_git_tag():
+    try:
+        tag = subprocess.check_output(["git", "describe", "--tags", "--abbrev=0"]).decode().strip()
+        # Clean up invalid version formats
+        if '-v' in tag:
+            # Extract base version from tags like 0.1.7-v24
+            base_version = tag.split('-v')[0]
+            return base_version
+        return tag
+    except Exception:
+        return "0.0.0"
+
+setup(
+    name="pycommonlog",
+    version=get_latest_git_tag(),
+    description="Unified logging and alerting library for Python.",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="Alvian Rahman Hanif",
+    author_email="alvian.hanif@pasarpolis.com",
+    url="https://github.com/alvianhanif/pycommonlog",
+    packages=["pycommonlog"],
+    install_requires=[],
+    license="MIT",
+    python_requires=">=3.8",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    include_package_data=True,
+)