Skip to main content

A poor man's debugger for Python.

Project description

PySnooper - Never use print for debugging again

PySnooper is a poor man's debugger. If you've used Bash, it's like set -x for Python, except it's fancier.

Your story: You're trying to figure out why your Python code isn't doing what you think it should be doing. You'd love to use a full-fledged debugger with breakpoints and watches, but you can't be bothered to set one up right now.

You want to know which lines are running and which aren't, and what the values of the local variables are.

Most people would use print lines, in strategic locations, some of them showing the values of variables.

PySnooper lets you do the same, except instead of carefully crafting the right print lines, you just add one decorator line to the function you're interested in. You'll get a play-by-play log of your function, including which lines ran and when, and exactly when local variables were changed.

What makes PySnooper stand out from all other code intelligence tools? You can use it in your shitty, sprawling enterprise codebase without having to do any setup. Just slap the decorator on, as shown below, and redirect the output to a dedicated log file by specifying its path as the first argument.

Example

We're writing a function that converts a number to binary, by returning a list of bits. Let's snoop on it by adding the @pysnooper.snoop() decorator:

import pysnooper

@pysnooper.snoop()
def number_to_bits(number):
    if number:
        bits = []
        while number:
            number, remainder = divmod(number, 2)
            bits.insert(0, remainder)
        return bits
    else:
        return [0]

number_to_bits(6)

The output to stderr is:

Or if you don't want to trace an entire function, you can wrap the relevant part in a with block:

import pysnooper
import random

def foo():
    lst = []
    for i in range(10):
        lst.append(random.randrange(1, 1000))

    with pysnooper.snoop():
        lower = min(lst)
        upper = max(lst)
        mid = (lower + upper) / 2
        print(lower, mid, upper)

foo()

which outputs something like:

New var:....... i = 9
New var:....... lst = [681, 267, 74, 832, 284, 678, ...]
09:37:35.881721 line        10         lower = min(lst)
New var:....... lower = 74
09:37:35.882137 line        11         upper = max(lst)
New var:....... upper = 832
09:37:35.882304 line        12         mid = (lower + upper) / 2
74 453.0 832
New var:....... mid = 453.0
09:37:35.882486 line        13         print(lower, mid, upper)
Elapsed time: 00:00:00.000344

Features

If stderr is not easily accessible for you, you can redirect the output to a file:

@pysnooper.snoop('/my/log/file.log')

You can also pass a stream or a callable instead, and they'll be used.

See values of some expressions that aren't local variables:

@pysnooper.snoop(watch=('foo.bar', 'self.x["whatever"]'))

Show snoop lines for functions that your function calls:

@pysnooper.snoop(depth=2)

See Advanced Usage for more options. <------

Installation with Pip

The best way to install PySnooper is with Pip:

$ pip install pysnooper

Other installation options

Conda with conda-forge channel:

$ conda install -c conda-forge pysnooper

Arch Linux:

$ yay -S python-pysnooper

Fedora Linux:

$ dnf install python3-pysnooper

Citing PySnooper

If you use PySnooper in academic work, please use this citation format:

@software{rachum2019pysnooper,
    title={PySnooper: Never use print for debugging again},
    author={Rachum, Ram and Hall, Alex and Yanokura, Iori and others},
    year={2019},
    month={jun},
    publisher={PyCon Israel},
    doi={10.5281/zenodo.10462459},
    url={https://github.com/cool-RR/PySnooper}
}

License

Copyright (c) 2019 Ram Rachum and collaborators, released under the MIT license.

Media Coverage

Hacker News thread and /r/Python Reddit thread (22 April 2019)

Project details


Download files

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

Source Distribution

pysnooper-1.2.3.tar.gz (46.3 kB view details)

Uploaded Source

Built Distribution

PySnooper-1.2.3-py2.py3-none-any.whl (15.1 kB view details)

Uploaded Python 2Python 3

File details

Details for the file pysnooper-1.2.3.tar.gz.

File metadata

  • Download URL: pysnooper-1.2.3.tar.gz
  • Upload date:
  • Size: 46.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.13.1

File hashes

Hashes for pysnooper-1.2.3.tar.gz
Algorithm Hash digest
SHA256 1fa1425444a7af45108aaed860b5ca8b62b25bba25b0b037c059ba353d8f1e74
MD5 a4278138a6f45384a538d66fe83783c5
BLAKE2b-256 d24abe3c144f58de6b78911c417cc4a3b3fe5eb6d13cae4c12daf3ca17a8d473

See more details on using hashes here.

File details

Details for the file PySnooper-1.2.3-py2.py3-none-any.whl.

File metadata

  • Download URL: PySnooper-1.2.3-py2.py3-none-any.whl
  • Upload date:
  • Size: 15.1 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.13.1

File hashes

Hashes for PySnooper-1.2.3-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 546372f0e72da89f8d1b89e758b7c05a478d65288569a1ca2cc1620e7b1b1944
MD5 df686e0b9fcd7bce37b4753f2b58665f
BLAKE2b-256 6987df62c8a998216e6749b67d548dae0967906036c61457510ef49667927c49

See more details on using hashes here.

Supported by

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