Twiggy

0.5.1 · maintenance · verified Thu Apr 16

Twiggy is a Pythonic logging library that emphasizes structured logging and a fluid, method-chaining API. It aims to be more "Pythonic" than the standard library's `logging` module. The current version is 0.5.1, released on May 12, 2021. The library has a slow release cadence and is marked by its maintainers as "not rock solid (yet)", suggesting it is in a maintenance status rather than active, rapid development.

Common errors

```
NameError: name 'log' is not defined
```
cause The global 'log' object or 'quick_setup' function was used without being imported, or the `quick_setup()` function was not called to initialize the logging system.

fix Add `from twiggy import quick_setup, log` at the top of your file, and ensure `quick_setup()` is called once early in your application's lifecycle.
```
TypeError: 'Message' object is not callable
```
cause Attempting to call the `log` object directly like a function (`log("message")`) instead of calling one of its level-specific methods (e.g., `log.info()`, `log.warning()`).

fix Use a logging level method on the `log` object, e.g., `log.info("Your message here")`, `log.debug("Another message")`, etc.
```
SyntaxError: invalid syntax (related to string formatting in log messages)
```
cause Mixing up string formatting styles (e.g., using old-style `%` formatting with `str.format()` placeholders, or vice-versa).

fix Twiggy primarily uses `str.format()` style. Ensure your format string (`"hello {who}"`) matches the arguments (`who='world'`) and avoid mixing with C-style `%` formatting.

Warnings

gotcha The official documentation states, 'Twiggy works great, but is not rock solid (yet); do not use for nuclear power plants, spaceships or mortgage derivatives trading.' This suggests caution for mission-critical applications.
Fix: Evaluate suitability for your project's reliability requirements. Consider more mature logging solutions for high-stakes systems.
breaking Version 0.4.1's changelog mentions "deprecate features, pending a rewrite in 0.5". Users upgrading from versions prior to 0.5.0 that relied on these deprecated features may experience breakage.
Fix: Consult the 0.5.0 changelog and API documentation to identify and update usage of any deprecated features. Review the `logging_compat` module if transitioning from standard library logging.
gotcha Twiggy's `log` object needs to be imported (`from twiggy import log`) and often `quick_setup()` needs to be called to configure basic output before logging messages. Forgetting these steps leads to errors or no output.
Fix: Always ensure `from twiggy import quick_setup, log` and `quick_setup()` are at the start of your application, or use `twiggy.setup()` for more granular control.

Install

pip install Twiggy Install latest stable version

Imports

quick_setup
wrong:
```
import twiggy.quick_setup
```
correct:
```
from twiggy import quick_setup
```
Commonly imported alongside 'log' for initial configuration.
log
wrong:
```
import twiggy.log
```
correct:
```
from twiggy import log
```
The primary logger instance. Often used after calling quick_setup().
FileOutput
wrong:
```
from twiggy import FileOutput
```
correct:
```
from twiggy.outputs import FileOutput
```
Output classes reside in the `twiggy.outputs` submodule.

Quickstart

This quickstart demonstrates how to initialize Twiggy with default settings (console output) using `quick_setup()` and then log messages with bound names, structured fields, and different severity levels using the global `log` object. Twiggy supports `str.format()` style string formatting.

from twiggy import quick_setup, log

# Configure a basic console output
quick_setup()

# Log a message with structured fields
log.name('my_app').fields(user_id=123).info("User {user_id} logged in from {ip}", ip="192.168.1.100")

# Log a warning message
log.warning("Something unusual happened, but it's not critical.")

# Using the NOTICE level (added in 0.5.0)
log.notice("Heads up: An important event occurred.")

view raw JSON →