austin-python


Nameaustin-python JSON
Version 1.7.1 PyPI version JSON
download
home_pageNone
SummaryPython wrapper for Austin, the CPython frame stack sampler.
upload_time2023-11-20 12:52:46
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseNone
keywords development performance profiling testing
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <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>&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
~~~

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.8-3.12.


# 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.8",
    "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/4f/a4/3e94328b4467891759f5dbcdb7459eea1cf60b3fbb1243617c343b7c7568/austin_python-1.7.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>&nbsp;&bull;\n  <a href=\"#installation\"><b>Installation</b></a>&nbsp;&bull;\n  <a href=\"#usage\"><b>Usage</b></a>&nbsp;&bull;\n  <a href=\"#compatibility\"><b>Compatibility</b></a>&nbsp;&bull;\n  <a href=\"#documentation\"><b>Documentation</b></a>&nbsp;&bull;\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\nfrom austin.aio import AsyncAustin\n\n\n# Make your sub-class of AsyncAustin\nclass EchoAsyncAustin(AsyncAustin):\n    def on_ready(self, process, child_process, command_line):\n        print(f\"Austin PID: {process.pid}\")\n        print(f\"Python PID: {child_process.pid}\")\n        print(f\"Command Line: {command_line}\")\n\n    def on_sample_received(self, line):\n        print(line)\n\n    def on_terminate(self, data):\n        print(data)\n\n\n# Use the Proactor event loop on Windows\nif sys.platform == \"win32\":\n    asyncio.set_event_loop(asyncio.ProactorEventLoop())\n\ntry:\n    # Start the Austin application with some command line arguments\n    austin = EchoAsyncAustin()\n    asyncio.get_event_loop().run_until_complete(\n        austin.start([\"-i\", \"10000\", \"python3\", \"myscript.py\"])\n    )\nexcept (KeyboardInterrupt, asyncio.CancelledError):\n    pass\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.8-3.12.\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": "1.7.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": "4346011defe60684131f39450411036a7fe09869ce2b9068d8a5dc68ebca2d35",
                "md5": "44cc6db6f2b9c519b6d8ad60c9921955",
                "sha256": "f9493ed0d95f10ee0ae1ea8bc17cabba4585fd0e73d28101f7f3c2fa48ceacb1"
            },
            "downloads": -1,
            "filename": "austin_python-1.7.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "44cc6db6f2b9c519b6d8ad60c9921955",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 69722,
            "upload_time": "2023-11-20T12:52:43",
            "upload_time_iso_8601": "2023-11-20T12:52:43.193727Z",
            "url": "https://files.pythonhosted.org/packages/43/46/011defe60684131f39450411036a7fe09869ce2b9068d8a5dc68ebca2d35/austin_python-1.7.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4fa43e94328b4467891759f5dbcdb7459eea1cf60b3fbb1243617c343b7c7568",
                "md5": "b22239bd68d570b0be8b71e74bd7010c",
                "sha256": "c99a692feaf452a04e5b8cbb11b230fbb6294bb9229bcf7b493d650557236290"
            },
            "downloads": -1,
            "filename": "austin_python-1.7.1.tar.gz",
            "has_sig": false,
            "md5_digest": "b22239bd68d570b0be8b71e74bd7010c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 198876,
            "upload_time": "2023-11-20T12:52:46",
            "upload_time_iso_8601": "2023-11-20T12:52:46.934665Z",
            "url": "https://files.pythonhosted.org/packages/4f/a4/3e94328b4467891759f5dbcdb7459eea1cf60b3fbb1243617c343b7c7568/austin_python-1.7.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-11-20 12:52:46",
    "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"
}
        
Elapsed time: 0.14269s