Metadata-Version: 2.4
Name: logxpy
Version: 0.3.0
Summary: Modern structured logging library with hierarchical Sqid task IDs
Home-page: https://github.com/logxpy/logxpy/
Maintainer: logxpy Team
Maintainer-email: 
License: Apache 2.0
Keywords: logging
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: System :: Logging
Requires-Python: >=3.12.0
License-File: LICENSE
Requires-Dist: zope.interface
Requires-Dist: pyrsistent>=0.11.8
Requires-Dist: boltons>=19.0.1
Requires-Dist: orjson; implementation_name == "cpython"
Provides-Extra: journald
Requires-Dist: cffi>=1.1.2; extra == "journald"
Provides-Extra: test
Requires-Dist: hypothesis>=1.14.0; extra == "test"
Requires-Dist: testtools; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Provides-Extra: dev
Requires-Dist: setuptools>=40; extra == "dev"
Requires-Dist: twine>=1.12.1; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx_rtd_theme; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

logxpy: Structured Logging with Action Tracing
===============================================

**logxpy** is a Python logging library that outputs structured, actionable logs
tracing causal chains of actions—helping you understand *why* things happened
in your application.

The **log-x-py** project consists of three components:

* **logxpy** - Zero-dependency structured logging library (Python 3.12+)
* **logxpy-cli-view** - Colored tree viewer for logs
* **logxy-log-parser** - Log parsing, analysis, and monitoring library

Why logxpy?
-----------

Python's built-in ``logging`` and similar systems output a stream of factoids:
they're interesting, but hard to trace.

* Why is your application slow?
* What caused this code path to be chosen?
* Why did this error happen?

Standard logging can't answer these questions easily.

With **logxpy**, you get **causal chains of actions**: actions can spawn other
actions, and eventually they either **succeed or fail**. The resulting logs tell
you the story of what your software did.

Features
--------

* **Structured Logging** - JSON output for easy parsing and analysis
* **Action Tracing** - Track operations from start to finish with timing
* **Hierarchical Tasks** - Nested actions show the full call chain
* **Color Support** - Foreground/background colors for log entries (rendered by logxpy-cli-view)
* **Python 3.12+ Ready** - Built with modern Python features
* **Async Support** - Works with asyncio and async/await patterns
* **Type Safety** - Full type hints throughout

Quick Start
-----------

Install logxpy::

    pip install logxpy

Basic usage::

    from logxpy import start_action, Message, to_file

    # Output to a file
    to_file(open("app.log", "w"))

    # Log messages
    Message.log(message_type="app:startup", version="1.0.0")

    # Trace actions
    with start_action(action_type="http:request", method="POST", path="/api/users"):
        with start_action(action_type="database:query", table="users"):
            Message.log(message_type="database:result", rows=10)

Output is structured JSON that's easy to parse, visualize, and analyze.

Color Support
-------------

LogXPy supports foreground/background colors that render beautifully in the CLI viewer::

    from logxpy import log

    # Set foreground color for subsequent messages
    log.set_foreground("cyan")
    log.info("This renders with cyan text")
    log.reset_foreground()

    # Set background color
    log.set_background("yellow")
    log.warning("Yellow background warning")
    log.reset_background()

    # Combined colors
    log.set_foreground("white").set_background("red")
    log.error("White text on red background")
    log.reset_foreground().reset_background()

    # One-shot colored message for highlighted blocks
    log.colored(
        "╔═══════════════════════════════════╗\n"
        "║  ⚠️  IMPORTANT HIGHLIGHTED BLOCK  ║\n"
        "╚═══════════════════════════════════╝",
        foreground="black",
        background="yellow"
    )

Available colors: black, red, green, yellow, blue, magenta, cyan, white, light_cyan, dark_gray, light_gray

Viewing Logs
------------

Use the companion ``logxpy-cli-view`` package to render logs as beautiful
colored trees::

    pip install logxpy-cli-view
    logxpy-view app.log

Or use the standalone viewer from the examples::

    python examples-log-view/view_tree.py app.log

LoggerX API
-----------

LogXPy provides a modern LoggerX class with fluent API::

    from logxpy import log

    # Level methods (return self for chaining)
    log.debug("Debug message", count=5)
    log.info("User login", user="alice")
    log.success("Operation completed", total=100)
    log.note("Checkpoint reached", step=3)
    log.warning("Slow query", ms=5000)
    log.error("Request failed", code=500)
    log.critical("System down")

    # Data type methods
    log.color((255, 0, 0), "Theme Color")
    log.currency("19.99", "USD")
    log.datetime(dt, "Start Time")
    log.enum(Status.ACTIVE)
    log.ptr(my_object)
    log.variant(data, "Input")
    log.sset({1, 2, 3}, "Tags")

    # System methods
    log.system_info()
    log.memory_status()
    log.stack_trace(limit=10)

    # File/stream methods
    log.file_hex("data.bin")
    log.file_text("app.log")
    log.memory_hex(buffer)
    log.stream_hex(bio)
    log.stream_text(io)

Requirements
------------

* Python 3.12 or newer (uses modern Python 3.12+ features)

Links
-----

* `Documentation <https://github.com/logxpy/logxpy/>`_
* `Issue Tracker <https://github.com/logxpy/logxpy/issues>`_

License
-------

Apache 2.0 License
