Perpetuo
perpetuo, verb: To cause to continue uninterruptedly, to proceed with continually
Perpetuo is a stall tracker for Python. Specifically, it can detect when:
-
One thread is holding the GIL for too long, blocking other threads from having a chance to run (requires an instrumented version of CPython)
-
One Trio task is running too long without checkpointing, blocking other tasks from having a chance to run
The actual monitoring is done from a separate process, using a customized version of py-spy. So the monitoring is very low overhead and should not interfere with the monitored process at all. The goal is to be able to use this in production.
Quickstart
-
pip install perpetuo -
Optional: patch CPython (see below)
-
import perpetuo -
If you're using Trio: call
perpetuo.dwim()insidetrio.runIf you're not using Trio: call
perpetuo.dwim()anywhere -
Optional: log
perpetuo.dwim()'s return value to see what it did
Available API
perpetuo.start_watcher(): Spawns the monitoring process in the background.
perpetuo.instrument_gil(): Enables GIL instrumentation, or raises
RuntimeError if you don't have the patched version of CPython.
perpetuo.instrument_trio(): Enables Trio instrumentation. Must be called
inside trio.run.
perpetuo.dwim(): Attempts to call all the above functions as appropriate, and
returns a list of strings describing which operations it actually performed. If
you're using Trio, make sure to call it inside trio.run.
StallTracker: Low-level class that allows you to add custom instrumentation to
other things. See source for details.
Patching CPython to instrument the GIL
There are patches available for:
CPython version 3.10.*:
https://github.com/python/cpython/compare/3.10...njsmith:cpython:njs/perpetuo-gil.diff
CPython version 3.11:
https://github.com/python/cpython/compare/3.11...njsmith:cpython:njs/perpetuo-gil-3.11.diff
CPython version 3.12:
https://github.com/python/cpython/compare/3.12...njsmith:cpython:njs/perpetuo-gil-3.12.diff
Bonus
1 maintainer
Metadata
1 maintainer
Release files for perpetuo 0.7.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| perpetuo-0.7.4.tar.gz | 33.2 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| perpetuo-0.7.4-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| perpetuo-0.7.4-cp39-abi3-manylinux_2_28_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| perpetuo-0.7.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| perpetuo-0.7.4-cp39-abi3-macosx_10_12_universal2.whl | CPython 3.9 | abi3 | macOS 10.12+ universal2 (ARM64, x86-64) | Details |
Total release size: 9.5 MB
Release files / perpetuo-0.7.4.tar.gz
| Download URL | perpetuo-0.7.4.tar.gz |
|---|---|
| Size | 33.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b02089f2c6ca8437be3d6553806c31739ac35826f36999f073f58204386de492
|
|
BLAKE2b-256 checksum How to use checksums |
22bb4386f7f3d4c39295b7db7194fcedf27d7defafbdee46407c1083458ea831
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / perpetuo-0.7.4-cp39-abi3-win_amd64.whl
| Download URL | perpetuo-0.7.4-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
8098b87742ffc4f9f00788cf9faf3011c3c732486bbae0d22025232be83bfb45
|
|
BLAKE2b-256 checksum How to use checksums |
747822ce90ecb2cd596a857c5046403588e98b66df3de218f042e1a9884162c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / perpetuo-0.7.4-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | perpetuo-0.7.4-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
32db1fc7e1ba97a9e59fc9ca0efcd9b46178f045709f90d7f274c4418709f407
|
|
BLAKE2b-256 checksum How to use checksums |
014b3a2636e8f8f678baa372336b86da441aafb66575fe82a1054b0dba3715b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / perpetuo-0.7.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | perpetuo-0.7.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
a6d69b1766040b20eb5671849186b76a6c66248bbecc3f4fdc20a3d5e694337a
|
|
BLAKE2b-256 checksum How to use checksums |
6c84768596265d00c974712e50cf5235a1999a3ad2afbdc47b1306f0ed1c58f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / perpetuo-0.7.4-cp39-abi3-macosx_10_12_universal2.whl
| Download URL | perpetuo-0.7.4-cp39-abi3-macosx_10_12_universal2.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
f2e360579d9608f2608cf4452fccd46d277e2e38334124ea7361a09d148262f3
|
|
BLAKE2b-256 checksum How to use checksums |
fbb023850cd7a8694372424cc7bbe365638930e5b19eb3d1aaed80ba2d81e6e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency log
