ic-python-logging 0.3.0__tar.gz

ic_python_logging-0.3.0/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/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include requirements-dev.txt
+include pyproject.toml
+include setup.cfg

ic_python_logging-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,144 @@
+# 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/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-0.3.0/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