Install & Compatibility
Where this runs
tested against v1.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.049s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.047s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
logged
✓ from autologging import logged
traced
✓ from autologging import traced
TRACE
✓ from autologging import TRACE
A custom log level (value 1) for tracing, lower in severity than `logging.DEBUG`.
This example demonstrates how to use the `@logged` and `@traced` decorators on a class. It sets up basic logging to console, including the custom `TRACE` level. When `MyClass` methods are called, `__log` is available for manual logging, and `@traced` automatically logs method entry and exit. Ensure `logging.getLogger().setLevel(TRACE)` is called to make `TRACE` level messages visible.
import logging
import sys
from autologging import logged, traced, TRACE
# Configure basic logging to see the output
logging.basicConfig(
level=logging.DEBUG,
stream=sys.stdout,
format="%(levelname)s:%(name)s:%(funcName)s:%(message)s"
)
# Set root logger level to TRACE to see tracing output
logging.getLogger().setLevel(TRACE)
@traced # Apply @traced outermost for consistent behavior
@logged
class MyClass:
def __init__(self, name):
self.name = name
self.__log.info("MyClass instance created with name: %s", self.name)
def do_work(self, value):
self.__log.debug("Doing work with value: %s", value)
result = value * 2
return result
def _internal_method(self):
self.__log.trace("Executing internal method.")
return "internal_result"
# Example usage
instance = MyClass("Example")
output = instance.do_work(10)
print(f"Result of do_work: {output}")
instance._internal_method()
Debug
Known issues
gotchaWhen combining `@logged` and `@traced` decorators on the same class or function, it is recommended to apply `@traced` as the outermost decorator and `@logged` as the innermost (i.e., `@traced @logged def ...`). While the library is designed to work regardless of order, this order is considered 'safe' because `@logged` simply sets an attribute and returns the original object.fixAlways apply `@traced` before `@logged` on the same callable.
affects: 1.0.0+
gotchaIf a subclass of a `@logged`-decorated parent class wishes to use a `self.__log` object that correctly reflects its own class name in log messages, it must itself be decorated with `@logged`. Otherwise, logs made through the parent's `__log` will show the parent's name.fixDecorate subclasses with `@logged` if they need their own `__log` instance and proper logger naming.
affects: 1.0.0+
gotchaWhen using `autologging` with IronPython, you might encounter misreported line numbers and '<unknown file>' in log records due to IronPython's limited support for frames.fixBe aware of these limitations when debugging on IronPython; this is a platform-specific issue.
affects: All versions on IronPython
gotchaKey names for extra data passed to Python's standard logging module (which autologging uses) cannot clash with some internal names (e.g., 'message', 'args'). If a clash occurs, autologging may issue a warning and change the key name (e.g., from 'message' to 'protected_message').fixAvoid using Python logging's internal keyword arguments as keys in your extra logging data.
affects: 1.0.0+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'autologging'
The 'autologging' module is not installed in the Python environment.
fixInstall the module using pip: 'pip install autologging'.
ImportError: cannot import name 'logged' from 'autologging'
The 'autologging' module is installed, but the 'logged' decorator cannot be imported, possibly due to an outdated version.
fixEnsure you have the latest version of autologging installed: 'pip install --upgrade autologging'.
AttributeError: module 'autologging' has no attribute 'traced'
The 'traced' decorator is not found in the 'autologging' module, likely due to an incorrect installation or version.
fixVerify the installation and version of autologging: 'pip show autologging'.
TypeError: 'NoneType' object is not callable
This error can occur if the 'traced' decorator is not properly applied, possibly due to incorrect usage or import issues.
fixEnsure that the 'traced' decorator is correctly imported and applied to the function or class.
ValueError: No JSON object could be decoded
This error may occur if the logging configuration is set to output in JSON format, but the log messages are not properly formatted.
fixCheck the logging configuration and ensure that log messages are correctly formatted as JSON.
Upgrade
Version history
1.3.2latest on PyPI · released Apr 20, 2019
Audit
Dependencies
No dependency data recorded yet.