Metadata-Version: 2.1
Name: austin-python
Version: 0.1.0
Summary: Python wrapper for Austin, the frame stack sampler for CPython
Home-page: https://github.com/P403n1x87/austin-python
License: GPL-3.0-or-later
Keywords: performance,profiling,testing,development
Author: Gabriele N. Tornetta
Author-email: phoenix1987@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: dataclasses
Requires-Dist: protobuf (>=3.12.2,<4.0.0)
Requires-Dist: psutil (>=5.7.0)
Project-URL: Documentation, https://austin-python.readthedocs.io
Project-URL: Repository, https://github.com/P403n1x87/austin-python
Project-URL: issues, https://github.com/P403n1x87/austin-python/issues
Description-Content-Type: text/markdown

<p align="center">
  <br/>
  <img src="docs/source/images/logo.png"
       alt="Austin"
       height="256px" />
  <br/>
</p>

<h3 align="center">Python wrapper for Austin, the frame stack sampler for CPython</h3>

<p align="center">
  <a href="https://github.com/P403n1x87/austin-python/actions?workflow=Tests">
    <img src="https://github.com/P403n1x87/austin-python/workflows/Tests/badge.svg"
         alt="GitHub Actions: Tests">
  </a>
  <a href="https://travis-ci.com/P403n1x87/austin-python">
    <img src="https://travis-ci.com/P403n1x87/austin-python.svg?token=fzW2yzQyjwys4tWf9anS"
         alt="Travis CI">
  </a>
  <a href="https://codecov.io/gh/P403n1x87/austin-python">
    <img src="https://codecov.io/gh/P403n1x87/austin-python/branch/master/graph/badge.svg"
         alt="Codecov">
  </a>
  <a href="https://pypi.org/project/austin-python/">
    <img src="https://img.shields.io/pypi/v/austin-python.svg"
         alt="PyPI">
  </a>
  <a href="https://austin-python.readthedocs.io/">
    <img src="https://readthedocs.org/projects/austin-python/badge/"
         alt="Documentation">
  </a>
  <a href="https://github.com/P403n1x87/austin-python/blob/master/LICENSE.md">
    <img src="https://img.shields.io/badge/license-GPLv3-ff69b4.svg"
         alt="LICENSE">
  </a>
</p>

<p align="center">
  <a href="#synopsis"><b>Synopsis</b></a>&nbsp;&bull;
  <a href="#installation"><b>Installation</b></a>&nbsp;&bull;
  <a href="#usage"><b>Usage</b></a>&nbsp;&bull;
  <a href="#compatibility"><b>Compatibility</b></a>&nbsp;&bull;
  <a href="#documentation"><b>Documentation</b></a>&nbsp;&bull;
  <a href="#contribute"><b>Contribute</b></a>
</p>

<p align="center">
  <a href="https://www.buymeacoffee.com/Q9C1Hnm28" target="_blank">
    <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" />
  </a>
</p>


# Synopsis

The `austin-python` package is a Python wrapper around the Austin binary that
provides convenience classes to quickly develop your statistical profiling
tools. Whether your code is thread-based or asynchronous, `austin-python` has
you covered. This is, for instance, how you would turn Austin into a Python
application:

~~~ python
from austin.aio import AsyncAustin


# Make your sub-class of AsyncAustin
class EchoAsyncAustin(AsyncAustin):
    def on_ready(self, process, child_process, command_line):
        print(f"Austin PID: {process.pid}")
        print(f"Python PID: {child_process.pid}")
        print(f"Command Line: {command_line}")

    def on_sample_received(self, line):
        print(line)

    def on_terminate(self, data):
        print(data)


# Use the Proactor event loop on Windows
if sys.platform == "win32":
    asyncio.set_event_loop(asyncio.ProactorEventLoop())

try:
    # Start the Austin application with some command line arguments
    austin = EchoAsyncAustin()
    asyncio.get_event_loop().run_until_complete(
        austin.start(["-i", "10000", "python3", "myscript.py"])
    )
except (KeyboardInterrupt, asyncio.CancelledError):
    pass
~~~

The `austin-python` package is at the heart of the [Austin
TUI](https://github.com/P403n1x87/austin-tui) and the [Austin
Web](https://github.com/P403n1x87/austin-web) Python applications. Go check them
out if you are looking for full-fledged usage examples.

Included with the package come two applications for the conversion of Austin
collected output, which is in the form of [collapsed
stacks](https://github.com/brendangregg/FlameGraph), to either the
[Speedscope](https://speedscope.app/) JSON format or the [Google pprof
format](https://github.com/google/pprof). Note, however, that the Speedscope web
application supports Austin native format directly.


# Installation

This package can be installed from PyPI with

~~~ bash
pip install --user austin-python --upgrade
~~~


# Usage

A simple example of an echo application was shown above. Other examples using,
e.g., threads, can be found in the official documentation. YOu can also browse
through the code of the [Austin TUI](https://github.com/P403n1x87/austin-tui)
and the [Austin Web](https://github.com/P403n1x87/austin-web) Python
applications to see how they leverage `austin-python`.

## Format conversion

As it was mentioned before, this package also comes with two scripts for format
conversion, namely `austin2speedscope` and `austin2pprof`. They both take two
mandatory arguments, that is, the input and output file. For example, to convert
the Austin profile data file `myscript.aprof` to the Google pprof data file
`myscript.pprof`, you can run

~~~ bash
austin2pprof myscript.aprof myscript.pprof
~~~


# Compatibility

The `austin-python` package is tested on Linux, macOS and Windows with Python
3.6-3.9.


# Documentation

The official documentation is hosted on readthedocs.io at
[austin-python.readthedocs.io](https://austin-python.readthedocs.io/).


# Contribute

If you want to help with the development, then have a look at the open issues
and have a look at the [contributing guidelines](CONTRIBUTING.md) before you
open a pull request.

You can also contribute to the development by either [becoming a
Patron](https://www.patreon.com/bePatron?u=19221563) on Patreon

<a href="https://www.patreon.com/bePatron?u=19221563" target="_blank">
  <img src="https://c5.patreon.com/external/logo/become_a_patron_button.png" alt="Become a Patron" />
</a><br/>

by [buying me a coffee](https://www.buymeacoffee.com/Q9C1Hnm28) on BMC

<a href="https://www.buymeacoffee.com/Q9C1Hnm28" target="_blank">
  <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" />
</a>

or by chipping in a few pennies on
[PayPal.Me](https://www.paypal.me/gtornetta/1).

