🦎 ChameleonLog

ChameleonLog Logo

Colourful logging handlers for Logbook.

Made in Vietnam PyPI PyPI - Python Version PyPI - License Common Changelog Documentation Status

ChameleonLog provides colorful, structured logging for Python applications using the Logbook.

  • RichHandler: Beautiful console output with syntax highlighting and tracebacks using the Rich library (recommended for development).

  • JournaldHandler: Structured logging to systemd journald with automatic level-based coloring and filtering (recommended for production/Live systems on Linux).

📦 Installation

Install ChameleonLog using pip:

pip install chameleon-log

Or using uv:

uv add chameleon-log

🔧 Optional Dependencies

To use the JournaldHandler for sending logs to systemd journald:

pip install chameleon-log[journald]

Or using uv:

uv add chameleon-log --extra journald

This will also install the journald-send package, requiring systemd-based Linux distros.

🚀 Usage

✨ RichHandler

For development and debugging in terminal environments, use RichHandler for colorful, formatted console output:

import logbook

from chameleon_log import RichHandler

# Create a RichHandler with default settings
handler = RichHandler()

with handler:
    logger = logbook.Logger(__name__)
    logger.info('Application started successfully')
    logger.warning('This is a warning message')
    logger.error('An error occurred')

The console parameter controls Rich formatting:

  • True (default): Auto-detect based on isatty(). Use Rich rendering when the stream is a terminal.

  • False: Disable Rich formatting, render plain output.

  • A rich.Console instance: Use that Console directly. This is useful for sinking log output into an active Rich live display (e.g. a rich.progress.Progress bar).

Additionally, RichHandler accepts a rich_tracebacks boolean to control how exceptions are rendered:

  • rich_tracebacks=True: Render exceptions using Rich Traceback objects when terminal rendering is enabled.

  • rich_tracebacks=False (default): Append the plain-text formatted traceback to the log message. This is useful when logs are captured to files or external systems that do not support Rich rendering.

🖼️ Example output

Rich Handler Output Rich Handler Output

🐧 JournaldHandler

For applications deployed on Linux servers or in production environments, use JournaldHandler to write logs directly to journald, using its native protocol. This provides more efficient troubleshooting capabilities compared to file-based logging or stdout / stderr capture.

Basic usage:

import logbook
from chameleon_log.journald import JournaldHandler

handler = JournaldHandler(syslog_identifier='my-app')

with handler:
    logger = logbook.Logger(__name__)
    logger.info('Application started successfully')
    logger.warning('This is a warning message')
    logger.error('An error occurred')

📝 Simple logging output:

Journald Simple Output

🏗️ With extra fields for structured filtering:

Logbook provides two ways to attach extra fields:

Journald Extra Fields Output

Option 1: Use the extra= parameter (simple and direct)

import logbook
from chameleon_log.journald import JournaldHandler

handler = JournaldHandler(syslog_identifier='my-app')

with handler:
    logger = logbook.Logger(__name__)
    logger.info('User logged in', extra={'user_id': 123, 'action': 'login'})

Option 2: Use a Processor (for reusable context)

import logbook
from logbook import Logger, Processor
from chameleon_log.journald import JournaldHandler

handler = JournaldHandler()
    # or
handler = JournaldHandler(syslog_identifier='my-app')

# Use a Processor to inject context into multiple log records
def inject_request_context(record):
    record.extra['user_id'] = 123
    record.extra['request_id'] = 'abc-456'

with handler:
    logger = logbook.Logger(__name__)

    with Processor(inject_request_context):
        logger.info('User logged in')  # Fields injected automatically
        logger.info('Data processed')

View logs with journalctl:

journalctl -fu my-service
journalctl -t my-app F_USER_ID=123
journalctl -eu my-service -o json

Normally, you view your app logs with -u (unit), the syslog_identifier is helpful if your app scatters across many systemd units, you then can use journalctl -t to view all.

📖 Documentation

Full documentation is available at: https://chameleon-log.readthedocs.io

logbook-stubs

If you come here for logbook-stubs source, it is already moved to a separate repository.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Logo by Freepik.

Project links

Data verified by PyPI on Aug 13, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for quan from gravatar.com quan

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Nguyễn Hồng Quân

GitHub Statistics

Data verified by PyPI on Aug 13, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.12

Provides Extra

journald sentry

Tags

journald logbook logging rich sentry

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chameleon_log-3.2.0.tar.gz (124.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

chameleon_log-3.2.0-py3-none-any.whl (19.8 kB view details)

Uploaded Python 3

File details

Details for the file chameleon_log-3.2.0.tar.gz.

File metadata

  • Download URL: chameleon_log-3.2.0.tar.gz
  • Upload date:
  • Size: 124.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chameleon_log-3.2.0.tar.gz
Algorithm Hash digest
SHA256 94b1e9f9052fe3a46993cad940ac4e9f3247c247be8abb9a70112712e5965509
MD5 5c2ba1d37ae848f9bb6ff938a1282395
BLAKE2b-256 96b91517674545eeee3274f992022c6d5fefdfbe39641280fe38661c8d5f4ad3

See more details on using hashes here.

Provenance

The following attestation bundles were made for chameleon_log-3.2.0.tar.gz:

Publisher: ci.yml on hongquan/chameleon-log

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chameleon_log-3.2.0-py3-none-any.whl.

File metadata

  • Download URL: chameleon_log-3.2.0-py3-none-any.whl
  • Upload date:
  • Size: 19.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chameleon_log-3.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 cbca2d054c159b11c43a7f9ba6a91ab927fc62050ec068e630c9e395d7d73332
MD5 fef2decf3e2d1040fb5dc5da390dd47f
BLAKE2b-256 b3c4489a0f6c22917fbea281c3f1ccc92520a1947284e8bc8b3ac7c68ccd1e6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for chameleon_log-3.2.0-py3-none-any.whl:

Publisher: ci.yml on hongquan/chameleon-log

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

3.2.0 This release

2 files

3.1.0

2 files

3.0.0

2 files

2.0.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.2

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page