Metadata-Version: 2.4
Name: chameleon_log
Version: 1.1.0
Summary: Colourful handlers for Logbook, based on Rich and Journald.
Project-URL: Repository, https://github.com/hongquan/chameleon-log.git
Project-URL: Documentation, https://chameleon-log.readthedocs.io
Project-URL: Changelog, https://github.com/hongquan/chameleon-log/blob/main/CHANGELOG.md
Author-email: Nguyễn Hồng Quân <ng.hong.quan@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: journald,logbook,logging,rich
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: logbook>=1.9.2
Requires-Dist: rich>=14.3.3
Provides-Extra: journald
Requires-Dist: systemd-python>=235; (sys_platform == 'linux') and extra == 'journald'
Description-Content-Type: text/x-rst

============
ChameleonLog
============

.. image:: https://quan-images.b-cdn.net/blogs/2026/03/chameleon-freepik.svg
   :alt: ChameleonLog Logo
   :width: 200px

Colourful logging handlers for `Logbook`_.

.. image:: https://madewithlove.vercel.app/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d
   :target: https://madewithlove.vercel.app
   :alt: Made in Vietnam

.. image:: https://img.shields.io/pypi/v/chameleon_log.svg
   :target: https://pypi.org/project/chameleon-log/
   :alt: PyPI

.. image:: https://img.shields.io/pypi/pyversions/chameleon_log.svg
   :target: https://pypi.org/project/chameleon-log/
   :alt: PyPI - Python Version

.. image:: https://img.shields.io/pypi/l/chameleon_log.svg
   :target: https://pypi.org/project/chameleon-log/
   :alt: PyPI - License

.. image:: https://common-changelog.org/badge.svg
   :target: https://common-changelog.org/
   :alt: Common Changelog

.. image:: https://readthedocs.org/projects/chameleon-log/badge/?version=latest
   :target: https://chameleon-log.readthedocs.io
   :alt: Documentation Status


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

- ``RichHandler``: Beautiful console output with syntax highlighting and tracebacks using the `Rich`_ library.
- ``JournaldHandler``: Structured logging to systemd journal with automatic level-based coloring and filtering.


Installation
------------

Install ChameleonLog using pip:

.. code-block:: bash

    pip install chameleon_log

Or using uv:

.. code-block:: bash

    uv add chameleon_log

Optional Dependencies
~~~~~~~~~~~~~~~~~~~~~

To use the ``JournaldHandler`` for sending logs to systemd journal (Linux only):

.. code-block:: bash

    pip install chameleon_log[journald]

Or using uv:

.. code-block:: bash

    uv add chameleon_log --extra journald

This requires Linux with systemd and installs the ``systemd-python`` package.

Usage
-----

Basic usage:

.. code-block:: python

    import logbook

    from chameleon_log import RichHandler

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

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

Customizing the handler:

.. code-block:: python

    # Create a RichHandler with custom settings
    handler = RichHandler(
        level=logbook.DEBUG,
        # Additional Rich-specific options can be added here
    )

Example Output
--------------

.. image:: https://quan-images.b-cdn.net/blogs/2026/03/rich.png
   :alt: Rich Handler Output
   :width: 100%


JournaldHandler Usage
---------------------

For systemd journal integration (Linux only) via journald, use ``JournaldHandler``. Logbook provides two ways to attach extra fields:

Simple logging output:
~~~~~~~~~~~~~~~~~~~~~~

.. image:: https://quan-images.b-cdn.net/blogs/2026/03/journald-simple.png
   :alt: Journald Simple Output
   :width: 100%

With extra fields for structured filtering:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. image:: https://quan-images.b-cdn.net/blogs/2026/03/journald-extra-fields.png
   :alt: Journald Extra Fields Output
   :width: 100%

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

.. code-block:: python

    import logbook
    from chameleon_log.journald import JournaldHandler

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

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

Option 2: Use a Processor (for reusable context)

.. code-block:: python

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

    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('MyApp')

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

View logs with journalctl:

.. code-block:: bash

    journalctl -t my-app
    journalctl -t my-app F_USER_ID=123
    journalctl -t my-app -o json

Documentation
-------------

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

License
-------

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

Logo by `Freepik <https://www.freepik.com>`_.

.. _logbook: https://pypi.org/project/Logbook/
.. _Rich: https://pypi.org/project/rich/
.. _systemd: https://systemd.io/
.. _journald: https://systemd.io/
.. _LICENSE: https://github.com/hongquan/chameleon-log/blob/master/LICENSE
