Metadata-Version: 2.4
Name: kepler
Version: 0.2.3
Summary: Fast, easy, pretty and readable program instrumentation.
Project-URL: Homepage, https://bethebunny.github.io/kepler
Project-URL: Documentation, https://bethebunny.github.io/kepler
Project-URL: Repository, https://github.com/bethebunny/kepler
Project-URL: Issues, https://github.com/bethebunny/kepler/issues
Project-URL: Changelog, https://github.com/bethebunny/kepler/releases
Author-email: Stef Lindall <bethebunny@gmail.com>
License: Copyright 2024 Stef Lindall, License BSD-3-Clause
Keywords: async,asyncio,instrument,instrumentation,profile,rich
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Requires-Dist: numpy
Requires-Dist: rich
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.10'
Description-Content-Type: text/markdown

# Kepler

Wish you could see stuff like this about your program?

<img width="1227" alt="image" src="https://github.com/user-attachments/assets/aa60de68-2648-4794-a29c-873365bc077b">

Kepler meticulously tracks your program, and creates simply and easily readable reports to help you understand what they're doing.

Kepler _is not_ a replacement for a good profiling tool, nor is it necessarily a great production implementation tool. Kepler is designed to be that go-to tool in your toolbelt for quick and dirty measurements of your programs.

## Installing Kepler

```bash
pip install kepler
```

## Kepler in action

The first thing you should do with Kepler is annotate a function or two you want to time with `@kepler.time`, and then add a `kepler.report()` call to your amin function.

Here's the script that produced the screenshot above:

```python
import kepler, random, time

@kepler.time("do some stuff")
def do_some_stuff():
    split = kepler.stopwatch("watch")
    for i in kepler.time("loop", range(20)):
        with kepler.time("sleep"):
            time.sleep(random.random() / 100)
        if i % 2 == 1:
            with kepler.time("overhead"):
                split("odd")
        else:
            with kepler.time("overhead"):
                split("even")

@kepler.time
def main():
    with kepler.time("sloooow"):
        time.sleep(0.3)
    do_some_stuff()

main()
kepler.report()
```

## Roadmap

### ✅ Changelog

- Import and export reports as json
- Report directly from json -- try `python -m kepler.report < tests/data/simple_log.json`
- Testing for units, json import and export

### 🔜 Up next

- Track system metrics

### 🌈 Before 1.0

- Export traces to pandas
- Flamegraphs
- Integrate with open-telemetry
- Track and report other metrics besidings timings
- Thorough unit testing
- Docs
- Examples
- Logo
