Skip to main content


Austin

Python wrapper for Austin

GitHub Actions: Tests GitHub Actions: Checks Codecov Documentation
PyPI Downloads
LICENSE

Synopsis • Installation • Usage • Compatibility • Documentation • Contribute

Buy Me A Coffee

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:

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 and the 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, to either the Speedscope JSON format or the Google pprof format. Note, however, that the Speedscope web application supports Austin native format directly.

Installation

This package can be installed from PyPI with

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

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 and the 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. The input file can be either in the MOJO binary format (the default output of Austin 4) or in the collapsed stack format, and is detected automatically. For example, to convert the Austin profile data file myscript.mojo to the Google pprof data file myscript.pprof, you can run

austin2pprof myscript.mojo myscript.pprof

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

Querying profiles

The austin.query module provides the ProfileQuery class to answer the most common questions about a profile, like which functions are the hottest, what the sampled stacks are, or who calls a given function:

from austin.query import ProfileQuery

q = ProfileQuery.from_file("myscript.mojo")

print(q.top(10))                       # hottest functions
print(q.callers("db.py:execute"))      # who calls execute
print(q.filter(thread="main").tree())  # call tree of the main thread

Every result renders as a text table when printed, and can be converted to JSON-ready data with to_dict(). For asyncio profiles (Python 3.14+), q.tasks() shows the task trees, q.task_stacks("worker-0") where a task was running and awaiting, and q.filter(task="worker-0") narrows any query down to the samples in which a task was running.

The same queries are available from the command line with austin-query:

austin-query myscript.mojo top -n 10
austin-query myscript.mojo callers db.py:execute --thread main
austin-query myscript.mojo tasks --json
austin-query myscript.mojo task-stacks worker-0  # where a task ran and awaited

Run austin-query --help for the selector syntax and a suggested workflow.

Compatibility

The latest austin-python package is tested on Linux, macOS and Windows with Python 3.11-3.15.

Documentation

The official documentation is hosted on readthedocs.io at 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 before you open a pull request.

You can also contribute to the development by either becoming a Patron on Patreon, by buying me a coffee on BMC or by chipping in a few pennies on PayPal.Me.

Buy Me A Coffee

Metadata

Release files for austin-python 2.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for austin-python 2.7.0
File Size Uploaded Provenance Actions
austin_python-2.7.0.tar.gz 255.9 kB Without provenance Details for austin_python-2.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for austin-python 2.7.0
File Interpreter ABI Platform Actions
austin_python-2.7.0-py3-none-any.whl Python 3 none any Details for austin_python-2.7.0-py3-none-any.whl

Total release size: 360.7 kB

Release files / austin_python-2.7.0.tar.gz

Download URL austin_python-2.7.0.tar.gz
Size 255.9 kB
Tags Source
SHA-256 checksum
How to use checksums
7c4a4632b019f58512c26d884bbededa78bc73cc8036a69da15ef605718c40ea
BLAKE2b-256 checksum
How to use checksums
83a8237fdcfb637829b14a4ff36e8695aee4672d4a0595c374d3e86ed5cf9949
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via Hatch/1.18.2 {"ci":true,"cpu":"x86_64","distro":{"id":"noble","libc":{"lib":"glibc","version":"2.39"},"name":"Ubuntu","version":"24.04"},"implementation":{"name":"CPython","version":"3.11.18"},"installer":{"name":"hatch","version":"1.18.2"},"openssl_version":"OpenSSL 3.0.13 30 Jan 2024","python":"3.11.18","system":{"name":"Linux","release":"7.0.0-1017-azure"}} HTTPX2/2.16.0

Release files / austin_python-2.7.0-py3-none-any.whl

Download URL austin_python-2.7.0-py3-none-any.whl
Size 104.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b329b6b4c4bd32902462ec8f1ff2938a63f44ab7e9a730b329cf04a84884dbea
BLAKE2b-256 checksum
How to use checksums
3cd1587f26b5122d4f15baa9b251edfff61c323f1de465c721ddb5adeb2bed16
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via Hatch/1.18.2 {"ci":true,"cpu":"x86_64","distro":{"id":"noble","libc":{"lib":"glibc","version":"2.39"},"name":"Ubuntu","version":"24.04"},"implementation":{"name":"CPython","version":"3.11.18"},"installer":{"name":"hatch","version":"1.18.2"},"openssl_version":"OpenSSL 3.0.13 30 Jan 2024","python":"3.11.18","system":{"name":"Linux","release":"7.0.0-1017-azure"}} HTTPX2/2.16.0

Security for austin-python 2.7.0

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.

Release history Release notifications | RSS feed

This release

2.7.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page