Snoop

0.6.0 · active · verified Thu Apr 16

Snoop is a powerful Python library that provides detailed insights into code execution with minimal effort. It serves as a more featureful and refined alternative to traditional print debugging and PySnooper, incorporating its own version of 'icecream' for enhanced output. Currently at version 0.6.0, the library is actively maintained and designed for easy use in tracing function calls, variable values, and overall code flow.

Common errors

```
NameError: name 'snoop' is not defined
```
cause The `snoop` decorator or function was used without being imported first.

fix Add `from snoop import snoop` at the top of your file. Alternatively, for global availability, use `from snoop import install` and call `install()` (e.g., `install(builtins=True)` to make `snoop` directly available).
```
ModuleNotFoundError: No module named 'birdseye'
```
cause The `@spy` decorator was used, but the `birdseye` library, which it depends on, is not installed.

fix Install the `birdseye` dependency: `pip install birdseye`.
```
TypeError: snoop() got an unexpected keyword argument 'output'
```
cause You are attempting to use PySnooper's `output` argument with `snoop`, which uses a different parameter name (`out`) and context for global configuration.

fix For global output configuration, use `from snoop import install` and then `install(out='your_file.log')`. The `@snoop` decorator itself does not take an `out` argument directly.
```
No snoop output appears in the console.
```
cause Snoop's output defaults to `sys.stderr`. In some environments or execution contexts (e.g., IDEs, certain CI/CD pipelines), `stderr` might not be directly displayed or captured where you expect.

fix Explicitly direct snoop's output to `sys.stdout` or a file using `from snoop import install` and then `install(out=sys.stdout)` or `install(out='debug.log', overwrite=True)`.

Warnings

breaking Snoop's API differs from PySnooper. Specifically, arguments like 'output', 'thread_info', 'prefix', and 'overwrite' are passed to `snoop.install()` or handled as `snoop` decorator arguments with different names (e.g., 'out' instead of 'output', 'columns' for thread info).
Fix: Consult the snoop documentation for correct argument names and usage. For global configuration, use `snoop.install(out=..., prefix=..., columns=...)`.
gotcha The `@spy` decorator (which integrates with `birdseye`) incurs a significant performance overhead and should be used cautiously, especially in functions with many loop iterations or performance-critical sections.
Fix: Use `@snoop` for general debugging. Only use `@spy` when the enhanced visual debugging of `birdseye` is strictly necessary and performance is not a primary concern. Ensure 'birdseye' is installed separately via `pip install birdseye`.
gotcha By default, `snoop` outputs its trace to `sys.stderr`. If you are running scripts where `stderr` is not visible or captured, you might not see any output.
Fix: Redirect output using `snoop.install(out=sys.stdout)` to print to standard output, or `snoop.install(out='path/to/log.txt', overwrite=True)` to write to a file.
gotcha Snoop is explicitly designed for Python >=3.8. Attempting to use it with older Python versions (e.g., Python 2.7) will result in syntax errors or `ModuleNotFoundError`.
Fix: Ensure your project is running on Python 3.8 or newer.

Install

pip install snoop Install latest version

Imports

snoop
```
from snoop import snoop
```
pp
wrong:
```
import snoop.pp
```
correct:
```
from snoop import pp
```
The pp object is typically imported directly from the snoop package.
spy
wrong:
```
from snoop.spy import spy
```
correct:
```
from snoop import spy
```
The spy decorator is imported directly from the top-level snoop package, not a submodule. Requires 'birdseye' package to be installed.
install
wrong:
```
snoop.configure()
```
correct:
```
from snoop import install
```
Global configuration for snoop is done via the 'install' function, not a 'configure' method on the main snoop object.

Quickstart

Demonstrates the basic usage of the `@snoop` decorator to automatically trace the execution and display variable values within a function. The output is sent to `stderr` by default.

from snoop import snoop

@snoop
def calculate_total(prices, tax_rate):
    total = sum(prices)
    tax = total * tax_rate
    final_total = total + tax
    return final_total

prices_list = [10, 20, 30]
rate = 0.08
result = calculate_total(prices_list, rate)
print(f"Final Total: {result}")

view raw JSON →