Metadata-Version: 2.4
Name: austin-python
Version: 2.2.0
Summary: Python wrapper for Austin, the CPython frame stack sampler.
Project-URL: homepage, https://github.com/P403n1x87/austin-python
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
Author-email: "Gabriele N. Tornetta" <phoenix1987@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: AUTHORS
License-File: COPYING
License-File: LICENSE.md
Keywords: development,performance,profiling,testing
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: protobuf~=3.12
Requires-Dist: psutil>=5.7.0
Requires-Dist: toml~=0.10
Description-Content-Type: text/markdown

  Austin

Python wrapper for Austin

    Downloads

  Synopsis •
  Installation •
  Usage •
  Compatibility •
  Documentation •
  Contribute

# 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
import asyncio
import sys

from austin.aio import AsyncAustin
from austin.format.collapsed_stack import AustinEventCollapsedStackFormatter

FORMATTER = AustinEventCollapsedStackFormatter()


class CollapsedStackAsyncAustin(AsyncAustin):
    async def on_sample(self, sample):
        print(FORMATTER.format(sample))

    async def on_metadata(self, metadata):
        print(FORMATTER.format(metadata))


if sys.platform == "win32":
    asyncio.set_event_loop(asyncio.ProactorEventLoop())


async def main():
    austin = CollapsedStackAsyncAustin()
    await austin.start(["-i", "10ms", "python", "myscript.py"])
    await austin.wait()


asyncio.run(main())
~~~

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
~~~

Please note that `austin-python` requires the [Austin] binary. The default
lookup locations are, in order,

- current working directory;
- the `AUSTINPATH` environment variable which gives the path to the folder that
  contains the Austin binary;
- the `.austinrc` TOML configuration file in the user's home folder, e.g.
  `~/.austinrc` on Linux (see below for a sample `.austinrc` file);
- the `PATH` environment variable.

A sample `.austinrc` file would look like so

~~~ toml
binary = "/path/to/austin"
~~~


# 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
~~~

The package also provide the `austin-compress` utility to compress the Austin
raw samples by aggregation.

# Compatibility

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

# 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, by [buying me a
coffee](https://www.buymeacoffee.com/Q9C1Hnm28) on BMC or by chipping in a few
pennies on [PayPal.Me](https://www.paypal.me/gtornetta/1).

[Austin]: https://github.com/p403n1x87/austin
