trickle-observe
Runtime type annotations for Python — see tensor shapes, variable types, and crash-time values as you code.
pip install trickle-observe
Quick Start
Scripts
pip install trickle-observe
npm install -g trickle-cli
trickle run python train.py # run with tracing
trickle hints # view source with inline types
trickle hints --errors # crash-time values + error underline
Jupyter Notebooks
%load_ext trickle # first cell, then run your code
Types appear inline in VSCode immediately after each cell runs.
What You See
Every variable gets its runtime type visible — in VSCode or in the terminal:
def forward(self, x: Tensor[128, 2] float32):
x: Tensor[128, 256] float32 = self.relu(self.bn0(self.embed(x)))
x: Tensor[128, 16, 16] float32 = x.view(x.size(0), 16, 16)
x: Tensor[128, 32, 16] float32 = self.relu(self.bn1(self.conv1(x)))
When code crashes, see exactly what each variable held:
# train.py — ERROR
# ValueError: could not convert string to float: 'ID' (line 20)
file_path: string = "demographics.txt"
patient_gait_data: string[] = ["ID\tStudy\tGroup\t..."]
[float(d) for d in time.split('\t')] for time in patient_gait_data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <- ValueError: ...
Usage
With the CLI (recommended)
pip install trickle-observe
npm install -g trickle-cli
trickle run python your_script.py
trickle hints your_script.py
As a library
import trickle
# Wrap individual functions
@trickle.trickle
def process(data):
...
# Instrument a FastAPI/Flask/Django app
trickle.instrument(app)
# Universal observation — wrap all functions on a module
trickle.observe(my_module)
In Jupyter Notebooks
%load_ext trickle
All cells after this are traced. The VSCode extension shows inline type hints.
With pytest
trickle run pytest tests/
What Gets Traced
- Tensor shapes — PyTorch (shape, dtype, device, memory, gradient norms), MLX (shape, dtype, memory), NumPy, pandas
- All variable assignments — simple, for-loops, function parameters, tuple unpacking, with-as
- Imported modules — your local modules are traced too, not just the entry file
- Error snapshots — all variables at crash time, including list comprehension scopes
Supported Frameworks
- ML: PyTorch, MLX, NumPy, pandas, scikit-learn, HuggingFace
- Web: FastAPI, Flask, Django, Litestar
- LLM: OpenAI, Anthropic, Google Gemini, LangChain, CrewAI
How It Works
Trickle rewrites your Python source via AST transformation before execution. After every variable assignment, it inserts a lightweight call that captures the type and a sample value, then writes to .trickle/variables.jsonl.
Only your code is traced — stdlib, site-packages, torch/numpy internals are skipped. No code changes to your files. No decorators required.
Related Packages
| Package | Description |
|---|---|
| trickle-cli | CLI for trickle run and trickle hints |
| trickle-vscode | VSCode extension for inline type hints |
License
Apache-2.0
Metadata
Release files for trickle-observe 0.2.71
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| trickle_observe-0.2.71.tar.gz | 156.0 kB | Without provenance | Details for trickle_observe-0.2.71.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| trickle_observe-0.2.71-py3-none-any.whl | Python 3 | none | any | Details for trickle_observe-0.2.71-py3-none-any.whl |
Total release size: 336.5 kB
Release files / trickle_observe-0.2.71.tar.gz
| Download URL | trickle_observe-0.2.71.tar.gz |
|---|---|
| Size | 156.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f910f86d83b08e7d5e3cd477849044ca447221a1b8d530d2ea6eaedb947e700
|
|
BLAKE2b-256 checksum How to use checksums |
b9e6ace798cd133936ac8b4b6b7b2ad1b288e42954322deec418075752e6cbb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / trickle_observe-0.2.71-py3-none-any.whl
| Download URL | trickle_observe-0.2.71-py3-none-any.whl |
|---|---|
| Size | 180.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d00d11e2992b734601a2bfb0cae5ab9a73098a22088c1167cd2ab7355c6c0a03
|
|
BLAKE2b-256 checksum How to use checksums |
3ae1e600c7c12317d0e4a0c1a1e16d6a6fa958756f65f93de02457371f9f434b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for trickle-observe 0.2.71
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.