<p align="center">
<br/>
<img src="docs/source/images/logo.png"
alt="Austin"
height="256px" />
<br/>
</p>
<h3 align="center">Python wrapper for Austin</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://github.com/P403n1x87/austin-python/actions?workflow=Checks">
<img src="https://github.com/P403n1x87/austin-python/workflows/Checks/badge.svg"
alt="GitHub Actions: Checks">
</a> <a href="https://codecov.io/gh/P403n1x87/austin-python">
<img src="https://codecov.io/gh/P403n1x87/austin-python/branch/main/graph/badge.svg"
alt="Codecov">
</a>
<a href="https://austin-python.readthedocs.io/">
<img src="https://readthedocs.org/projects/austin-python/badge/"
alt="Documentation">
</a>
<br/>
<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://pepy.tech/project/austin-python">
<img src="https://static.pepy.tech/personalized-badge/austin-python?period=total&units=international_system&left_color=grey&right_color=blue&left_text=downloads"
alt="Downloads" />
<a/>
<br/>
<a href="https://github.com/P403n1x87/austin-python/blob/main/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> •
<a href="#installation"><b>Installation</b></a> •
<a href="#usage"><b>Usage</b></a> •
<a href="#compatibility"><b>Compatibility</b></a> •
<a href="#documentation"><b>Documentation</b></a> •
<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
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.13.
# 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).
<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>
[Austin]: https://github.com/p403n1x87/austin
Raw data
{
"_id": null,
"home_page": null,
"name": "austin-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "development, performance, profiling, testing",
"author": null,
"author_email": "\"Gabriele N. Tornetta\" <phoenix1987@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/01/db/c54ddb72305f4c6db034eb9e067eca583d147bafe7bfdf53933420bd7538/austin_python-2.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <br/>\n <img src=\"docs/source/images/logo.png\"\n alt=\"Austin\"\n height=\"256px\" />\n <br/>\n</p>\n\n<h3 align=\"center\">Python wrapper for Austin</h3>\n\n<p align=\"center\">\n <a href=\"https://github.com/P403n1x87/austin-python/actions?workflow=Tests\">\n <img src=\"https://github.com/P403n1x87/austin-python/workflows/Tests/badge.svg\"\n alt=\"GitHub Actions: Tests\">\n </a>\n <a href=\"https://github.com/P403n1x87/austin-python/actions?workflow=Checks\">\n <img src=\"https://github.com/P403n1x87/austin-python/workflows/Checks/badge.svg\"\n alt=\"GitHub Actions: Checks\">\n </a> <a href=\"https://codecov.io/gh/P403n1x87/austin-python\">\n <img src=\"https://codecov.io/gh/P403n1x87/austin-python/branch/main/graph/badge.svg\"\n alt=\"Codecov\">\n </a>\n <a href=\"https://austin-python.readthedocs.io/\">\n <img src=\"https://readthedocs.org/projects/austin-python/badge/\"\n alt=\"Documentation\">\n </a>\n <br/>\n <a href=\"https://pypi.org/project/austin-python/\">\n <img src=\"https://img.shields.io/pypi/v/austin-python.svg\"\n alt=\"PyPI\">\n </a>\n <a href=\"https://pepy.tech/project/austin-python\">\n <img src=\"https://static.pepy.tech/personalized-badge/austin-python?period=total&units=international_system&left_color=grey&right_color=blue&left_text=downloads\"\n alt=\"Downloads\" />\n <a/>\n <br/>\n <a href=\"https://github.com/P403n1x87/austin-python/blob/main/LICENSE.md\">\n <img src=\"https://img.shields.io/badge/license-GPLv3-ff69b4.svg\"\n alt=\"LICENSE\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"#synopsis\"><b>Synopsis</b></a> •\n <a href=\"#installation\"><b>Installation</b></a> •\n <a href=\"#usage\"><b>Usage</b></a> •\n <a href=\"#compatibility\"><b>Compatibility</b></a> •\n <a href=\"#documentation\"><b>Documentation</b></a> •\n <a href=\"#contribute\"><b>Contribute</b></a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://www.buymeacoffee.com/Q9C1Hnm28\" target=\"_blank\">\n <img src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" />\n </a>\n</p>\n\n\n# Synopsis\n\nThe `austin-python` package is a Python wrapper around the [Austin] binary that\nprovides convenience classes to quickly develop your statistical profiling\ntools. Whether your code is thread-based or asynchronous, `austin-python` has\nyou covered. This is, for instance, how you would turn Austin into a Python\napplication:\n\n~~~ python\nimport asyncio\nimport sys\n\nfrom austin.aio import AsyncAustin\nfrom austin.format.collapsed_stack import AustinEventCollapsedStackFormatter\n\nFORMATTER = AustinEventCollapsedStackFormatter()\n\n\nclass CollapsedStackAsyncAustin(AsyncAustin):\n async def on_sample(self, sample):\n print(FORMATTER.format(sample))\n\n async def on_metadata(self, metadata):\n print(FORMATTER.format(metadata))\n\n\nif sys.platform == \"win32\":\n asyncio.set_event_loop(asyncio.ProactorEventLoop())\n\n\nasync def main():\n austin = CollapsedStackAsyncAustin()\n await austin.start([\"-i\", \"10ms\", \"python\", \"myscript.py\"])\n await austin.wait()\n\n\nasyncio.run(main())\n~~~\n\nThe `austin-python` package is at the heart of the [Austin\nTUI](https://github.com/P403n1x87/austin-tui) and the [Austin\nWeb](https://github.com/P403n1x87/austin-web) Python applications. Go check them\nout if you are looking for full-fledged usage examples.\n\nIncluded with the package come two applications for the conversion of Austin\ncollected output, which is in the form of [collapsed\nstacks](https://github.com/brendangregg/FlameGraph), to either the\n[Speedscope](https://speedscope.app/) JSON format or the [Google pprof\nformat](https://github.com/google/pprof). Note, however, that the Speedscope web\napplication supports Austin native format directly.\n\n\n# Installation\n\nThis package can be installed from PyPI with\n\n~~~ bash\npip install --user austin-python --upgrade\n~~~\n\nPlease note that `austin-python` requires the [Austin] binary. The default\nlookup locations are, in order,\n\n- current working directory;\n- the `AUSTINPATH` environment variable which gives the path to the folder that\n contains the Austin binary;\n- the `.austinrc` TOML configuration file in the user's home folder, e.g.\n `~/.austinrc` on Linux (see below for a sample `.austinrc` file);\n- the `PATH` environment variable.\n\nA sample `.austinrc` file would look like so\n\n~~~ toml\nbinary = \"/path/to/austin\"\n~~~\n\n\n# Usage\n\nA simple example of an echo application was shown above. Other examples using,\ne.g., threads, can be found in the official documentation. You can also browse\nthrough the code of the [Austin TUI](https://github.com/P403n1x87/austin-tui)\nand the [Austin Web](https://github.com/P403n1x87/austin-web) Python\napplications to see how they leverage `austin-python`.\n\n## Format conversion\n\nAs it was mentioned before, this package also comes with two scripts for format\nconversion, namely `austin2speedscope` and `austin2pprof`. They both take two\nmandatory arguments, that is, the input and output file. For example, to convert\nthe Austin profile data file `myscript.aprof` to the Google pprof data file\n`myscript.pprof`, you can run\n\n~~~ bash\naustin2pprof myscript.aprof myscript.pprof\n~~~\n\nThe package also provide the `austin-compress` utility to compress the Austin\nraw samples by aggregation.\n\n# Compatibility\n\nThe latest `austin-python` package is tested on Linux, macOS and Windows with\nPython 3.9-3.13.\n\n\n# Documentation\n\nThe official documentation is hosted on readthedocs.io at\n[austin-python.readthedocs.io](https://austin-python.readthedocs.io/).\n\n\n# Contribute\n\nIf you want to help with the development, then have a look at the open issues\nand have a look at the [contributing guidelines](CONTRIBUTING.md) before you\nopen a pull request.\n\nYou can also contribute to the development by either [becoming a\nPatron](https://www.patreon.com/bePatron?u=19221563) on Patreon, by [buying me a\ncoffee](https://www.buymeacoffee.com/Q9C1Hnm28) on BMC or by chipping in a few\npennies on [PayPal.Me](https://www.paypal.me/gtornetta/1).\n\n<p align=\"center\">\n <a href=\"https://www.buymeacoffee.com/Q9C1Hnm28\" target=\"_blank\">\n <img src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\"\n alt=\"Buy Me A Coffee\" />\n </a>\n</p>\n\n\n[Austin]: https://github.com/p403n1x87/austin\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for Austin, the CPython frame stack sampler.",
"version": "2.1.1",
"project_urls": {
"documentation": "https://austin-python.readthedocs.io",
"homepage": "https://github.com/P403n1x87/austin-python",
"issues": "https://github.com/P403n1x87/austin-python/issues",
"repository": "https://github.com/P403n1x87/austin-python"
},
"split_keywords": [
"development",
" performance",
" profiling",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dc7f265275a92cac6c590bc1c45c6ea4bee462b38f858764ad63810f06af7b84",
"md5": "90dca8790ac5cfe60df653e00988230b",
"sha256": "e1da5be99fb342acdc531ac47a3f3d55d08f31a0d167e10d3c69a7eb6b8a4d30"
},
"downloads": -1,
"filename": "austin_python-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90dca8790ac5cfe60df653e00988230b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 76116,
"upload_time": "2025-10-10T14:50:38",
"upload_time_iso_8601": "2025-10-10T14:50:38.180872Z",
"url": "https://files.pythonhosted.org/packages/dc/7f/265275a92cac6c590bc1c45c6ea4bee462b38f858764ad63810f06af7b84/austin_python-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01dbc54ddb72305f4c6db034eb9e067eca583d147bafe7bfdf53933420bd7538",
"md5": "dd6f0de60114447f1d6f098c58e41210",
"sha256": "9fbf26bac8d2aee91347b3dfdde56d88632a0965bf278a055f46d589ae5a241e"
},
"downloads": -1,
"filename": "austin_python-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "dd6f0de60114447f1d6f098c58e41210",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 202978,
"upload_time": "2025-10-10T14:50:33",
"upload_time_iso_8601": "2025-10-10T14:50:33.368442Z",
"url": "https://files.pythonhosted.org/packages/01/db/c54ddb72305f4c6db034eb9e067eca583d147bafe7bfdf53933420bd7538/austin_python-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 14:50:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "P403n1x87",
"github_project": "austin-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "austin-python"
}
JSON
