ic-python-logging 0.3.0__py3-none-any.whl

ic_python_logging/__init__.py

@@ -0,0 +1,38 @@
+# Debug variable storage functions
+# New in-memory logging functions
+from ._handler import Level  # Enum for log levels
+from ._handler import LogEntry  # Log entry data class
+from ._handler import SimpleLogger  # The logger class itself
+from ._handler import clear_logs  # Function to clear all logs from memory
+from ._handler import disable_logging  # Function to disable all logging
+from ._handler import disable_memory_logging  # Function to disable in-memory logging
+from ._handler import enable_logging  # Function to re-enable logging
+from ._handler import enable_memory_logging  # Function to enable in-memory logging
+from ._handler import get_logger  # Function to get a named logger
+from ._handler import get_logs  # Function to retrieve logs from memory
+from ._handler import list_vars  # Function to list all saved variables
+from ._handler import load_var  # Function to load a saved variable
+from ._handler import logger  # Default logger for backwards compatibility
+from ._handler import save_var  # Function to save a variable for debugging
+from ._handler import set_log_level  # Function to set log level for one or all loggers
+from ._handler import set_max_log_entries  # Function to set maximum log storage size
+from ._handler import (  # Function to check memory logging status
+    is_memory_logging_enabled,
+)
+
+# New canister query function for exposing logs
+try:
+    from ._handler import PublicLogEntry  # Public log entry type for canister queries
+    from ._handler import (  # Query function to expose logs via canister query
+        get_canister_logs,
+    )
+except ImportError:
+    # If CDK isn't available, these imports will fail
+    # This allows the library to be used in non-IC environments
+    pass
+
+# This allows imports like:
+# from ic_python_logging import logger, get_logger, set_log_level
+# from ic_python_logging import save_var, load_var, list_vars
+# from ic_python_logging import get_logs, clear_logs, set_max_log_entries, enable_memory_logging, disable_memory_logging
+# from ic_python_logging import PublicLogEntry, get_canister_logs

ic_python_logging/_cdk.py

@@ -0,0 +1,36 @@
+"""CDK compatibility layer.
+
+This module centralizes all imports from the Internet Computer CDK (currently Basilisk).
+To switch CDKs, only this file needs to be modified.
+"""
+
+HAS_CDK = False
+
+try:
+    from basilisk import ic  # noqa: F401
+
+    # Verify ic.print actually works (we might be imported but not in IC env)
+    try:
+        ic.print("")
+        IN_IC_ENVIRONMENT = True
+    except Exception:
+        IN_IC_ENVIRONMENT = False
+
+    HAS_CDK = True
+
+except ImportError:
+    ic = None  # type: ignore
+    IN_IC_ENVIRONMENT = False
+
+
+def _import_types():
+    """Import CDK types for query function definitions.
+
+    Returns a tuple of (Opt, Record, Vec, nat, query) or None if CDK unavailable.
+    """
+    try:
+        from basilisk import Opt, Record, Vec, nat, query
+
+        return Opt, Record, Vec, nat, query
+    except ImportError:
+        return None

ic_python_logging/_handler.py

@@ -0,0 +1,407 @@
+# Simple custom logger that doesn't use Python's logging module
+# to avoid process ID access which is unsupported in IC environment
+
+import json
+import pickle
+import sys
+import time
+from collections import deque
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Callable, Deque, Dict, List, Optional, Union
+
+# Global settings
+_LOGGING_ENABLED = True
+_MEMORY_LOGGING_ENABLED = True  # Controls whether logs are stored in memory
+_LOGGERS: Dict[str, "SimpleLogger"] = {}
+
+# Debug variable storage
+_DEBUG_VARS: Dict[str, Any] = {}
+
+# In-memory log storage
+_MAX_LOG_ENTRIES = 1000  # Maximum number of log entries to keep in memory
+_LOG_STORAGE: Deque["LogEntry"] = deque(maxlen=_MAX_LOG_ENTRIES)
+_LOG_SEQUENCE_COUNTER = 0  # Global counter for generating unique log entry IDs
+
+
+# Define Level enum
+class Level(IntEnum):
+    DEBUG = 10
+    INFO = 20
+    WARNING = 30
+    ERROR = 40
+    CRITICAL = 50
+
+    def __str__(self) -> str:
+        """Return the string representation of the log level"""
+        return self.name
+
+
+@dataclass
+class LogEntry:
+    """Represents a single log entry stored in memory"""
+
+    timestamp: float
+    level: Level
+    logger_name: str
+    message: str
+    id: int  # Unique identifier for the log entry
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert log entry to dictionary for serialization"""
+        return {
+            "timestamp": self.timestamp,
+            "level": str(self.level),
+            "logger_name": self.logger_name,
+            "message": self.message,
+            "id": self.id,
+        }
+
+
+# Define a safe fallback first
+def _print_log(level: Level, message: str, logger_name: str) -> None:
+    if not _LOGGING_ENABLED:
+        return
+    print(f"[{level}] [{logger_name}] {message}")
+    # Store in memory regardless of print settings
+    _store_log_entry(level, message, logger_name)
+
+
+def _store_log_entry(level: Level, message: str, logger_name: str) -> None:
+    """Store a log entry in the memory buffer if memory logging is enabled"""
+    if not _MEMORY_LOGGING_ENABLED:
+        return
+
+    global _LOG_SEQUENCE_COUNTER
+    _LOG_SEQUENCE_COUNTER += 1
+
+    entry = LogEntry(
+        timestamp=time.time(),
+        level=level,
+        logger_name=logger_name,
+        message=message,
+        id=_LOG_SEQUENCE_COUNTER,
+    )
+    _LOG_STORAGE.append(entry)
+
+
+# Now try to use the IC-specific functionality if available and working
+_in_ic_environment = False
+try:
+    # Import IC functionality via CDK compatibility layer
+    from ._cdk import HAS_CDK, IN_IC_ENVIRONMENT, ic
+
+    if not HAS_CDK:
+        raise ImportError("CDK not available")
+
+    # Now safely test if ic.print actually works
+    try:
+        # Try to use ic.print but catch any errors
+        ic.print("Logger initializing")
+
+        # If we get here, ic.print works!
+        _in_ic_environment = True
+
+        # Override the print_log function with IC-specific version
+        def _ic_print_log(level: Level, message: str, logger_name: str) -> None:
+            if not _LOGGING_ENABLED:
+                return
+            ic.print(f"[{level}] [{logger_name}] {message}")
+            # Store in memory regardless of print settings
+            _store_log_entry(level, message, logger_name)
+
+        # Define IC-specific version of store_log_entry using ic.time()
+        def _ic_store_log_entry(level: Level, message: str, logger_name: str) -> None:
+            """Store a log entry in the memory buffer if memory logging is enabled"""
+            if not _MEMORY_LOGGING_ENABLED:
+                return
+
+            global _LOG_SEQUENCE_COUNTER
+            _LOG_SEQUENCE_COUNTER += 1
+
+            entry = LogEntry(
+                timestamp=ic.time(),
+                level=level,
+                logger_name=logger_name,
+                message=message,
+                id=_LOG_SEQUENCE_COUNTER,
+            )
+            _LOG_STORAGE.append(entry)
+
+        # Replace the regular functions with IC versions
+        _print_log = _ic_print_log
+        _store_log_entry = _ic_store_log_entry
+
+    except:
+        # If we get an error trying to use ic.print, fall back to regular print
+        pass
+
+except ImportError:
+    # If CDK isn't available, we're definitely not in an IC environment
+    print("Note: IC CDK not available, using regular print for logging")
+
+
+class SimpleLogger:
+    def __init__(self, name: str = "ic_python_logger", level: Level = Level.INFO):
+        self.name = name
+        self.level = level
+
+    def set_level(self, level: Level) -> None:
+        """Set the minimum logging level"""
+        self.level = level
+
+    def is_enabled_for(self, level: Level) -> bool:
+        """Check if this level should be logged"""
+        return int(level) >= int(self.level)
+
+    def log(self, level: Level, message: str) -> None:
+        if not self.is_enabled_for(level):
+            return
+        _print_log(level, message, self.name)
+
+    def debug(self, message: str) -> None:
+        self.log(Level.DEBUG, message)
+
+    def info(self, message: str) -> None:
+        self.log(Level.INFO, message)
+
+    def warning(self, message: str) -> None:
+        self.log(Level.WARNING, message)
+
+    def warn(self, message: str) -> None:
+        self.warning(message)
+
+    def error(self, message: str) -> None:
+        self.log(Level.ERROR, message)
+
+    def critical(self, message: str) -> None:
+        self.log(Level.CRITICAL, message)
+
+
+# Public API functions
+def get_logger(name: str = "ic_python_logging") -> SimpleLogger:
+    """Get or create a logger with the specified name"""
+    if name not in _LOGGERS:
+        _LOGGERS[name] = SimpleLogger(name)
+    return _LOGGERS[name]
+
+
+def set_log_level(level: Level, logger_name: Optional[str] = None) -> None:
+    """Set log level for all loggers or a specific one
+
+    Args:
+        level: The log level to set (e.g., Level.DEBUG, Level.INFO)
+        logger_name: Optional name of logger to set level for, or None for all loggers
+    """
+    if logger_name is not None:
+        if logger_name in _LOGGERS:
+            _LOGGERS[logger_name].set_level(level)
+    else:
+        # Set for all loggers
+        for logger in _LOGGERS.values():
+            logger.set_level(level)
+
+
+def disable_logging() -> None:
+    """Completely disable all logging"""
+    global _LOGGING_ENABLED
+    _LOGGING_ENABLED = False
+
+
+def enable_logging() -> None:
+    """Re-enable logging"""
+    global _LOGGING_ENABLED
+    _LOGGING_ENABLED = True
+
+
+# Debug variable storage functions
+def save_var(tag: str, obj: Any) -> None:
+    """Store a variable with a tag for debugging purposes
+
+    Args:
+        tag: A string identifier to later retrieve the object
+        obj: Any Python object to store
+    """
+    _DEBUG_VARS[tag] = obj
+
+
+def load_var(tag: str) -> Any:
+    """Retrieve a previously stored variable by its tag
+
+    Args:
+        tag: The identifier used when saving the variable
+
+    Returns:
+        The stored object or None if not found
+    """
+    if tag not in _DEBUG_VARS:
+        return None
+    return _DEBUG_VARS[tag]
+
+
+def list_vars() -> Dict[str, str]:
+    """List all stored variables with their types
+
+    Returns:
+        A dictionary mapping variable tags to their types
+    """
+    return {tag: str(type(obj).__name__) for tag, obj in _DEBUG_VARS.items()}
+
+
+# Default logger for backwards compatibility
+logger = get_logger()
+
+
+# In-memory log retrieval functions
+def get_logs(
+    from_entry: Optional[int] = None,
+    max_entries: Optional[int] = None,
+    min_level: Optional[Level] = None,
+    logger_name: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Retrieve logs from memory with optional filtering
+
+    Args:
+        from_entry: Start from a specific log entry ID
+        max_entries: Maximum number of entries to return (oldest first by default)
+        min_level: Minimum log level to include
+        logger_name: Filter logs to a specific logger
+
+    Returns:
+        List of log entries as dictionaries
+    """
+    # Create a copy of the logs to avoid modifying the original
+    logs = list(_LOG_STORAGE)
+
+    logs = [
+        log
+        for log in logs
+        if (from_entry is None or log.id >= from_entry)
+        and (min_level is None or log.level >= min_level)
+        and (logger_name is None or log.logger_name == logger_name)
+    ]
+
+    # Limit the number of entries if requested - return the LAST entries (most recent)
+    logs = logs[-max_entries:] if max_entries is not None else logs
+
+    # Convert to dictionaries for easier serialization
+    return [log.to_dict() for log in logs]
+
+
+def clear_logs() -> None:
+    """Clear all logs from memory"""
+    _LOG_STORAGE.clear()
+
+
+def disable_memory_logging() -> None:
+    """Disable storing logs in memory"""
+    global _MEMORY_LOGGING_ENABLED
+    _MEMORY_LOGGING_ENABLED = False
+
+
+def enable_memory_logging() -> None:
+    """Enable storing logs in memory"""
+    global _MEMORY_LOGGING_ENABLED
+    _MEMORY_LOGGING_ENABLED = True
+
+
+def is_memory_logging_enabled() -> bool:
+    """Check if memory logging is enabled"""
+    return _MEMORY_LOGGING_ENABLED
+
+
+def set_max_log_entries(max_entries: int) -> None:
+    """Set the maximum number of log entries to keep in memory
+
+    Args:
+        max_entries: New maximum capacity of the log storage
+    """
+    global _LOG_STORAGE, _MAX_LOG_ENTRIES
+    # Create a new deque with the new max length
+    _MAX_LOG_ENTRIES = max(1, max_entries)  # Ensure at least 1 entry
+    new_storage = deque(maxlen=_MAX_LOG_ENTRIES)
+
+    # Transfer any existing logs (up to the new capacity)
+    logs = list(_LOG_STORAGE)
+    logs.sort(key=lambda log: log.timestamp)  # Sort by timestamp (oldest first)
+
+    # Keep the newest logs if we're reducing capacity
+    if len(logs) > _MAX_LOG_ENTRIES:
+        logs = logs[-_MAX_LOG_ENTRIES:]
+
+    # Add logs to the new storage
+    for log in logs:
+        new_storage.append(log)
+
+    # Replace the old storage with the new one
+    _LOG_STORAGE = new_storage
+
+
+try:
+    # Add CDK imports for the query function via compatibility layer
+    _types = None
+    try:
+        from ._cdk import _import_types
+
+        _types = _import_types()
+    except ImportError:
+        pass
+
+    if _types is None:
+        raise ImportError("CDK types not available")
+
+    Opt, Record, Vec, nat, query = _types
+
+    # Define a public-facing LogEntry type for queries
+    class PublicLogEntry(Record):
+        """Public-facing log entry type for canister queries"""
+
+        timestamp: nat
+        level: str
+        logger_name: str
+        message: str
+        id: nat
+
+    @query
+    def get_canister_logs(
+        from_entry: Opt[int] = None,
+        max_entries: Opt[int] = None,
+        min_level: Opt[str] = None,
+        logger_name: Opt[str] = None,
+    ) -> Vec[PublicLogEntry]:
+        """Query function to retrieve logs from the canister
+
+        This function can be called externally via a canister query call.
+
+        Args:
+            max_entries: Maximum number of entries to return
+            min_level: Minimum log level to include
+            logger_name: Filter logs to a specific logger
+
+        Returns:
+            List of log entries
+        """
+        # Use the existing get_logs function
+        logs = get_logs(
+            from_entry=from_entry,
+            max_entries=max_entries,
+            min_level=None if min_level is None else Level[min_level],
+            logger_name=logger_name,
+        )
+
+        # Convert to PublicLogEntry objects
+        return [
+            PublicLogEntry(
+                timestamp=log["timestamp"],
+                level=log["level"],
+                logger_name=log["logger_name"],
+                message=log["message"],
+                id=log["id"],
+            )
+            for log in logs
+        ]
+
+except ImportError:
+    # If CDK isn't available, we don't expose the query function
+    # This allows the library to be used in non-IC environments
+    pass

ic_python_logging/cli.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import os
+import select
+import subprocess
+import sys
+import time
+from datetime import datetime
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Query and display canister logs")
+    parser.add_argument("canister_id", help="Canister ID to query logs from")
+
+    # Log filtering options
+    parser.add_argument("--tail", type=int, help="Show only the last N logs")
+    parser.add_argument(
+        "--level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Minimum log level to display",
+    )
+    parser.add_argument(
+        "--name",
+        help="Filter logs by logger name",
+    )
+
+    # Follow mode options
+    parser.add_argument(
+        "--follow", action="store_true", help="Follow logs (poll every 5 seconds)"
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        default=5,
+        help="Polling interval in seconds for follow mode",
+    )
+
+    # Network options
+    network_group = parser.add_mutually_exclusive_group()
+    network_group.add_argument(
+        "--network", help="Network URL (e.g., http://localhost:4943)"
+    )
+    network_group.add_argument("--ic", action="store_true", help="Use the IC mainnet")
+
+    return parser.parse_args()
+
+
+def get_logs(
+    canister_id, tail=None, level=None, network=None, from_entry=None, name=None
+):
+    """Query log entries from a canister
+
+    Args:
+        canister_id: ID of the canister to query
+        tail: Maximum number of entries to return (optional)
+        level: Minimum log level to include (optional)
+        network: Network to query (optional)
+        from_entry: Start retrieving logs from this ID (optional)
+        name: Filter logs by logger name (optional)
+
+    Returns:
+        List of log entries as dictionaries
+
+    Note:
+        The parameters are passed to the canister in the following order:
+        1. from_entry
+        2. max_entries (tail)
+        3. min_level (level)
+        4. logger_name (name)
+    """
+    # Build the query arguments in the correct order as expected by the canister API
+    args = []
+
+    # 1. from_entry parameter
+    if from_entry is not None:
+        args.append(f"(opt {from_entry})")
+    else:
+        args.append("null")
+
+    # 2. tail/max_entries parameter
+    if tail is not None:
+        args.append(f"(opt {tail})")
+    else:
+        args.append("null")
+
+    # 3. level/min_level parameter
+    if level is not None:
+        args.append(f'(opt "{level}")')
+    else:
+        args.append("null")
+
+    # 4. logger_name parameter
+    if name is not None:
+        args.append(f'(opt "{name}")')
+    else:
+        args.append("null")
+
+    query_args = ", ".join(args)
+
+    # Call dfx to query the logs with JSON output
+    cmd = ["dfx", "canister", "call", "--output", "json"]
+
+    # Add network option if specified
+    if network is not None:
+        cmd.extend(["--network", network])
+
+    # Add canister ID and method
+    cmd.extend([canister_id, "get_canister_logs", f"({query_args})"])
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        return json.loads(result.stdout)
+    except subprocess.CalledProcessError as e:
+        print(f"Error querying logs: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error parsing JSON response: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def format_log(log_entry):
+    # Convert timestamp from nanoseconds to seconds and format as datetime
+    try:
+        timestamp = datetime.fromtimestamp(int(log_entry["timestamp"]) / 1e9).strftime(
+            "%Y-%m-%d %H:%M:%S"
+        )
+    except (ValueError, KeyError):
+        timestamp = "Unknown time"
+
+    level = log_entry.get("level", "UNKNOWN")
+    name = log_entry.get("logger_name", "unknown")
+    message = log_entry.get("message", "")
+    id = log_entry.get("id", "unknown")
+
+    # Add colors based on log level
+    level_colors = {
+        "DEBUG": "\033[94m",  # Blue
+        "INFO": "\033[92m",  # Green
+        "WARNING": "\033[93m",  # Yellow
+        "ERROR": "\033[91m",  # Red
+        "CRITICAL": "\033[91m\033[1m",  # Bold Red
+    }
+    reset = "\033[0m"
+    color = level_colors.get(level, "")
+
+    return f"{timestamp} [{id}] {color}[{level}]{reset} [{name}] {message}"
+
+
+def main():
+    # Set stdout to line buffering mode to ensure timely output when piped
+    import io
+
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, line_buffering=True)
+
+    args = parse_args()
+
+    # Determine network option
+    network = None
+    if args.ic:
+        network = "ic"
+    elif args.network:
+        network = args.network
+
+    if not args.follow:
+        # One-time query
+        logs = get_logs(
+            args.canister_id,
+            tail=args.tail,
+            level=args.level,
+            network=network,
+            name=args.name,
+        )
+
+        for log in logs:
+            print(format_log(log), flush=True)
+        return
+
+    # Follow mode
+    try:
+        last_poll_time = 0
+        last_log_id = 0
+        first_poll = True
+
+        while True:
+            current_time = time.time()
+            if (
+                first_poll
+                or current_time - last_poll_time >= args.interval
+                or select.select([sys.stdin], [], [], 0)[0]
+            ):
+                if select.select([sys.stdin], [], [], 0)[0]:
+                    input()
+
+                if first_poll:
+                    logs = get_logs(
+                        args.canister_id,
+                        tail=args.tail,
+                        level=args.level,
+                        network=network,
+                        name=args.name,
+                    )
+                    first_poll = False
+                else:
+                    logs = get_logs(
+                        args.canister_id,
+                        tail=None,
+                        level=args.level,
+                        network=network,
+                        from_entry=last_log_id + 1,
+                        name=args.name,
+                    )
+
+                last_poll_time = current_time
+
+                for log in logs:
+                    print(format_log(log), flush=True)
+
+                # Update the last log ID if we have logs
+                if logs:
+                    last_log_id = max(int(log.get("id", 0)) for log in logs)
+
+            time.sleep(0.1)
+    except KeyboardInterrupt:
+        print("\nExiting log follower")
+
+
+if __name__ == "__main__":
+    main()

ic_python_logging-0.3.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: ic_python_logging
+Version: 0.3.0
+Summary: A lightweight logging library for the Internet Computer (IC)
+Home-page: https://github.com/smart-social-contracts/ic-python-logging
+Author: Smart Social Contracts
+Author-email: Smart Social Contracts <smartsocialcontracts@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Smart Social Contracts
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/smart-social-contracts/ic-python-logging
+Project-URL: Repository, https://github.com/smart-social-contracts/ic-python-logging.git
+Project-URL: Issues, https://github.com/smart-social-contracts/ic-python-logging/issues
+Keywords: logging,debugging,ic,internet-computer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# IC Python Logging
+
+[![Test IC](https://github.com/smart-social-contracts/ic-python-logging/actions/workflows/test_ic.yml/badge.svg)](https://github.com/smart-social-contracts/ic-python-logging/actions)
+[![Test](https://github.com/smart-social-contracts/ic-python-logging/actions/workflows/test.yml/badge.svg)](https://github.com/smart-social-contracts/ic-python-logging/actions)
+[![PyPI version](https://badge.fury.io/py/ic-python-logging.svg)](https://badge.fury.io/py/ic-python-logging)
+[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3107/)
+[![License](https://img.shields.io/github/license/smart-social-contracts/ic-python-logging.svg)](https://github.com/smart-social-contracts/ic-python-logging/blob/main/LICENSE)
+
+A simple logging system for the [Internet Computer](https://internetcomputer.org). Forked from [kybra-simple-logging](https://github.com/smart-social-contracts/kybra-simple-logging). The library includes in-memory log storage capabilities, providing robust logging for all canister functions including asynchronous operations.
+
+
+## Features
+
+- CLI tool for querying logs directly from canisters to your local machine (including in semi-real time with `--follow`)
+- Works seamlessly in both Internet Computer and non-IC environments
+- Avoids using Python's standard logging module (which has compatibility issues in the IC environment)
+- Named loggers with `get_logger()` function similar to Python's standard library
+- Support for level-based filtering (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- Global and per-logger log level configuration
+- Ability to enable/disable logging completely
+- Circular buffer to store logs in memory without exhausting memory
+
+
+## Installation
+
+```bash
+pip install ic-python-logging
+```
+
+## Quick Start
+
+```python
+from ic_python_logging import get_logger
+
+# Create a logger
+logger = get_logger("my_canister")
+
+# Log messages at a specific level
+logger.info("This is an info message")
+
+# Set log level for a specific logger
+logger.set_level(LogLevel.DEBUG)
+
+# Use in-memory logging to retrieve logs
+from ic_python_logging import get_logs, clear_logs, enable_memory_logging, disable_memory_logging
+
+# Retrieve only ERROR logs
+error_logs = get_logs(min_level="ERROR")
+
+# Filter logs by logger name
+component_logs = get_logs(logger_name="my_component")
+```
+
+## CLI Tool
+
+The package includes a command-line tool for querying logs from canisters.
+Example:
+
+```bash
+# View the first 10 ERROR log entries of logger with name MY_LOGGER_NAME, and then follow and poll every 5 seconds, from the canister with ID <CANISTER_ID> on the IC network
+kslog <CANISTER_ID> --tail 10 --level ERROR --name MY_LOGGER_NAME --follow --ic --interval 5
+```
+
+To use this `kslog` with your canister, expose the query function:
+
+```python
+# ##### Import Basilisk and the internal function #####
+
+from basilisk import Opt, Record, Vec, nat, query
+from ic_python_logging import get_canister_logs as _get_canister_logs
+
+
+# Define the PublicLogEntry class directly in the test canister
+class PublicLogEntry(Record):
+    timestamp: nat
+    level: str
+    logger_name: str
+    message: str
+    id: nat
+
+
+@query
+def get_canister_logs(
+        from_entry: Opt[nat] = None,
+        max_entries: Opt[nat] = None,
+        min_level: Opt[str] = None,
+        logger_name: Opt[str] = None,
+) -> Vec[PublicLogEntry]:
+    """
+    Re-export the get_canister_logs query function from the library
+    This makes it accessible as a query method on the test canister
+    """
+    logs = _get_canister_logs(
+        from_entry=from_entry,
+        max_entries=max_entries,
+        min_level=min_level,
+        logger_name=logger_name
+    )
+
+    # Convert the logs to our local PublicLogEntry type
+    return [
+        PublicLogEntry(
+            timestamp=log["timestamp"],
+            level=log["level"],
+            logger_name=log["logger_name"],
+            message=log["message"],
+            id=log["id"],
+        )
+        for log in logs
+    ]
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/smart-social-contracts/ic-python-logging.git
+cd ic-python-logging
+
+# Recommended setup
+pyenv install 3.10.7
+pyenv local 3.10.7
+python -m venv venv
+source venv/bin/activate
+pip install ic-basilisk
+python -m basilisk install-dfx-extension
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Run linters
+./run_linters.sh
+
+# Run tests
+cd tests && ./run_test.sh
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

ic_python_logging-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ic_python_logging/__init__.py,sha256=NzzwXsYJl5O7pZGk-OQ6jqdF4UxDxBXzwrRf5Qfizrw,2074
+ic_python_logging/_cdk.py,sha256=CYAnqJ77hsjoSDJNe0yHUOpw1AJAYbIRy-qcsI5ticU,865
+ic_python_logging/_handler.py,sha256=rGR-tcbtkbxsv6VPOYx3jQx586oodOLF0MU5D5lD_tI,11892
+ic_python_logging/cli.py,sha256=F39B13SnhhlxxbWH99WfZeJNG7_TQXDsN5TKghE7Zgc,6539
+ic_python_logging-0.3.0.dist-info/licenses/LICENSE,sha256=6q6XYNOGnJcVSus2bAezFn7bU_2Y5T6W4aGQHBb8X-c,1079
+ic_python_logging-0.3.0.dist-info/METADATA,sha256=bip1zm-zacqDiQCBULOswx0aVQFRvUTaQDKnm2b3mTc,7015
+ic_python_logging-0.3.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+ic_python_logging-0.3.0.dist-info/entry_points.txt,sha256=UKmZ8D0AC-HHn4HDypuhpT_2C9rKtY5ETkcnUFRhkW8,53
+ic_python_logging-0.3.0.dist-info/top_level.txt,sha256=LMsY26rDPsH7Vu-7chKcbK2aiKEEgcyW_gEs75NzbTw,18
+ic_python_logging-0.3.0.dist-info/RECORD,,

ic_python_logging-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ic_python_logging-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kslog = ic_python_logging.cli:main

ic_python_logging-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Smart Social Contracts
+
+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.

ic_python_logging-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ic_python_logging