austin-python 1.7.0__tar.gz → 2.0.0__tar.gz

{austin_python-1.7.0 → austin_python-2.0.0}/.readthedocs.yml

@@ -3,7 +3,7 @@ sphinx:
   configuration: docs/source/conf.py
 formats: all
 python:
-  version: 3.8
+  version: 3.13
   install:
     - requirements: docs/requirements.txt
     - path: .

{austin_python-1.7.0 → austin_python-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: austin-python
-Version: 1.7.0
+Version: 2.0.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
@@ -15,12 +15,12 @@ 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.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
 Requires-Dist: protobuf~=3.12
 Requires-Dist: psutil>=5.7.0
 Requires-Dist: toml~=0.10
@@ -93,35 +93,34 @@ 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()
 
-# 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)
+class CollapsedStackAsyncAustin(AsyncAustin):
+    async def on_sample(self, sample):
+        print(FORMATTER.format(sample))
 
-    def on_terminate(self, data):
-        print(data)
+    async def on_metadata(self, metadata):
+        print(FORMATTER.format(metadata))
 
 
-# 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
+
+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
@@ -188,7 +187,7 @@ raw samples by aggregation.
 # Compatibility
 
 The latest `austin-python` package is tested on Linux, macOS and Windows with
-Python 3.8-3.12.
+Python 3.9-3.13.
 
 
 # Documentation

{austin_python-1.7.0 → austin_python-2.0.0}/README.md

@@ -65,35 +65,34 @@ 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()
 
-# 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)
+class CollapsedStackAsyncAustin(AsyncAustin):
+    async def on_sample(self, sample):
+        print(FORMATTER.format(sample))
 
-    def on_terminate(self, data):
-        print(data)
+    async def on_metadata(self, metadata):
+        print(FORMATTER.format(metadata))
 
 
-# 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
+
+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
@@ -160,7 +159,7 @@ raw samples by aggregation.
 # Compatibility
 
 The latest `austin-python` package is tested on Linux, macOS and Windows with
-Python 3.8-3.12.
+Python 3.9-3.13.
 
 
 # Documentation

austin_python-2.0.0/austin/__init__.py

@@ -0,0 +1,22 @@
+# This file is part of "austin-python" which is released under GPL.
+#
+# See file LICENCE or go to http://www.gnu.org/licenses/ for full license
+# details.
+#
+# austin-python is a Python wrapper around Austin, the CPython frame stack
+# sampler.
+#
+# Copyright (c) 2018-2020 Gabriele N. Tornetta <phoenix1987@gmail.com>.
+# All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.

austin_python-2.0.0/austin/aio.py

@@ -0,0 +1,184 @@
+# This file is part of "austin-python" which is released under GPL.
+#
+# See file LICENCE or go to http://www.gnu.org/licenses/ for full license
+# details.
+#
+# austin-python is a Python wrapper around Austin, the CPython frame stack
+# sampler.
+#
+# Copyright (c) 2018-2020 Gabriele N. Tornetta <phoenix1987@gmail.com>.
+# All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import asyncio
+import sys
+import typing as t
+
+from austin.base import AustinState
+from austin.base import BaseAustin
+from austin.cli import AustinArgumentParser
+from austin.errors import AustinError
+from austin.events import AustinMetadata
+from austin.events import AustinSample
+from austin.format.mojo import AsyncMojoStreamReader
+
+
+class AsyncAustin(BaseAustin):
+    """Asynchronous implementation of Austin.
+
+    Implements an ``asyncio`` API for Austin so that it can be used alongside
+    other asynchronous tasks.
+
+    The following example shows how to make a simple asynchronous implementation
+    of Austin that returns stack in the collapsed format
+
+    Example::
+
+        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())
+    """
+
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        super().__init__(*args, **kwargs)
+
+        self._run_task: t.Optional[asyncio.Task] = None
+        self._proc: t.Optional[asyncio.subprocess.Process] = None
+
+    async def _run(self, mojo: AsyncMojoStreamReader) -> None:
+        # Start collecting samples
+        self._state = AustinState.RUNNING
+
+        async for e in mojo:
+            if isinstance(e, AustinSample):
+                try:
+                    await t.cast(t.Awaitable[None], self._sample_callback(e))
+                except Exception as exc:
+                    raise AustinError("Error in call to sample callback") from exc
+            elif isinstance(e, AustinMetadata):
+                self._meta[e.name] = e.value
+                if self._metadata_callback is not None:
+                    try:
+                        await t.cast(t.Awaitable[None], self._metadata_callback(e))
+                    except Exception as exc:
+                        raise AustinError("Error in call to metadata callback") from exc
+
+        self._state = AustinState.TERMINATING
+
+        # Call the terminate callback
+        try:
+            if self._terminate_callback is not None:
+                await t.cast(t.Awaitable[None], self._terminate_callback())
+        except Exception as exc:
+            raise AustinError("Error in call to terminate callback") from exc
+
+        self._state = AustinState.TERMINATED
+
+    async def start(self, args: t.Optional[t.Sequence[str]] = None) -> None:
+        """Create the start coroutine.
+
+        Use with the ``asyncio`` event loop.
+        """
+        self._args = AustinArgumentParser().parse_args(args)
+
+        self._state = AustinState.STARTING
+
+        try:
+            _args = list(args if args is not None else sys.argv[1:])  # Make a copy
+            _args.insert(0, "-P")
+            self._proc = await asyncio.create_subprocess_exec(
+                self.binary_path,
+                *_args,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except FileNotFoundError:
+            raise AustinError("Austin executable not found.") from None
+
+        if not self._proc.stdout:
+            raise AustinError("Standard output stream is unexpectedly missing")
+        if not self._proc.stderr:
+            raise AustinError("Standard error stream is unexpectedly missing")
+
+        mojo = AsyncMojoStreamReader(self._proc.stdout)
+
+        # Retrieve the Austin version, then call the ready callback
+        async for e in mojo:
+            if isinstance(e, AustinMetadata):
+                self._meta[e.name] = e.value
+
+                try:
+                    if self._metadata_callback is not None:
+                        await t.cast(t.Awaitable[None], self._metadata_callback(e))
+                except Exception as exc:
+                    raise AustinError("Error in call to metadata callback") from exc
+
+                if e.name == "austin":
+                    self._check_version()
+                    break
+        else:
+            raise AustinError("Cannot determine Austin version from output")
+
+        # Start the run task where we collect the samples
+        self._run_task = asyncio.create_task(self._run(mojo))
+
+    def terminate(self) -> None:
+        """Terminate Austin.
+
+        Stop the underlying Austin process by sending a termination signal.
+        """
+        if self._proc is None:
+            raise AustinError("Austin is not running")
+
+        try:
+            self._proc.terminate()
+        except ProcessLookupError as exc:
+            raise AustinError("Austin process already terminated") from exc
+
+    async def wait(self) -> int:
+        if self._proc is None or self._run_task is None:
+            raise AustinError("Austin process is not running")
+
+        # Await the run task. This will terminate naturally when the Austin
+        # process has terminated.
+        await self._run_task
+
+        # Wait for the Austin process to terminate and return the exit code
+        return await self._proc.wait()

austin_python-2.0.0/austin/base.py

@@ -0,0 +1,238 @@
+# This file is part of "austin-python" which is released under GPL.
+#
+# See file LICENCE or go to http://www.gnu.org/licenses/ for full license
+# details.
+#
+# austin-python is a Python wrapper around Austin, the CPython frame stack
+# sampler.
+#
+# Copyright (c) 2018-2020 Gabriele N. Tornetta <phoenix1987@gmail.com>.
+# All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+import functools
+import os
+import sys
+from abc import ABC
+from abc import abstractmethod
+from enum import Enum
+from itertools import takewhile
+from pathlib import Path
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Tuple
+
+from austin.cli import AustinArguments
+from austin.config import AustinConfiguration
+from austin.errors import AustinError
+from austin.events import AustinMetadata
+from austin.events import AustinSample
+
+
+SemVer = Tuple[int, int, int]
+
+
+def _to_semver(version: Optional[str]) -> SemVer:
+    if version is None:
+        return (0, 0, 0)
+
+    try:
+        return (
+            tuple(
+                int(_)
+                for _ in "".join(
+                    list(
+                        takewhile(
+                            lambda _: _.isdigit() or _ == ".", version.replace("?", "0")
+                        )
+                    )
+                ).split(".")
+            )
+            + (0, 0, 0)
+        )[
+            # type: ignore[return-value]
+            :3
+        ]
+    except ValueError:
+        raise ValueError("Invalid semantic version") from None
+
+
+class AustinState(int, Enum):
+    """Austin state."""
+
+    NOT_STARTED = 0
+    STARTING = 1
+    RUNNING = 2
+    TERMINATING = 3
+    TERMINATED = 4
+
+
+_EXE_EXT = ".exe" if sys.platform == "win32" else ""
+
+
+class BaseAustin(ABC):
+    """Base Austin class.
+
+    Defines the general API that abstract Austin as an external process.
+    Subclasses should implement the :func:`start` and :func:`terminate` methods,
+    and either define the :func:`on_sample` method or pass it via the
+    constructor. Additionally, the :func:`on_metadata` :func:`on_terminate`
+    methods can be overridden or passed via the constructor to catch metadata
+    and termination events respectively. Austin is considered to be ready when
+    the first metadata event is received, and the `start` function returns, and
+    it is considered to have terminated when the Austin process has terminated
+    gracefully.
+
+    If an error was encountered, the :class:`AustinError` exception is thrown.
+    """
+
+    BINARY = Path("austin").with_suffix(_EXE_EXT)
+    MINIMUM_BINARY_VERSION: SemVer = (4, 0, 0)
+
+    def __init__(
+        self,
+        sample_callback: Optional[Callable[[AustinSample], None]] = None,
+        metadata_callback: Optional[Callable[[AustinMetadata], None]] = None,
+        terminate_callback: Optional[Callable[[], None]] = None,
+    ) -> None:
+        """The ``BaseAustin`` constructor.
+
+        The callbacks can be passed as arguments, if they are not
+        defined/overridden in the definition of a sub-class.
+        """
+        self._args: Optional[AustinArguments] = None
+        self._meta: Dict[str, str] = {}
+
+        if sample_callback is None and not hasattr(self, "on_sample"):
+            msg = "No mandatory sample callback given or implemented."
+            raise AustinError(msg)
+
+        self._sample_callback = sample_callback or self.on_sample  # type: ignore[attr-defined]
+
+        self._metadata_callback = metadata_callback or getattr(
+            self, "on_metadata", None
+        )
+        self._terminate_callback = terminate_callback or getattr(
+            self, "on_terminate", None
+        )
+
+        self._state: AustinState = AustinState.NOT_STARTED
+
+    @abstractmethod
+    def start(self, args: Optional[List[str]] = None) -> Any:
+        """Start Austin.
+
+        Every subclass should implement this method and ensure that it spawns
+        a new Austin process.
+        """
+        ...
+
+    def get_arguments(self) -> Optional[AustinArguments]:
+        """Get the inferred command line.
+
+        Return the command line of the (main) process that is being profiled
+        by Austin.
+        """
+        return self._args
+
+    def is_running(self) -> bool:
+        """Determine whether Austin is running."""
+        return self._state is AustinState.RUNNING
+
+    @abstractmethod
+    def terminate(self) -> Any:
+        """Terminate Austin.
+
+        Stop the underlying Austin process by sending a termination signal.
+        """
+        ...
+
+    @abstractmethod
+    def wait(self) -> Any:
+        """Wait for Austin to terminate.
+
+        This method blocks until the Austin process has terminated.
+        Returns the exit code of the Austin process.
+        """
+        ...
+
+    def _check_version(self) -> None:
+        """Check for the minimum Austin binary version."""
+        austin_version = self.version
+        if austin_version is None:
+            raise AustinError("Cannot determine Austin version")
+        if austin_version < self.MINIMUM_BINARY_VERSION:
+            raise AustinError(
+                f"Incompatible Austin version (got {austin_version}, expected >= {self.MINIMUM_BINARY_VERSION})"
+            )
+
+    # ---- Properties ----
+
+    @functools.cached_property
+    def binary_path(self) -> Path:
+        """Discover the path of the Austin binary.
+
+        Lookup order is:
+        - current working directory
+        - ``AUSTINPATH`` variable
+        - ``~/.austinrc`` file
+        - ``PATH`` variable.
+        """
+        binary_name = self.BINARY
+
+        # Try CWD
+        binary_path = binary_name.resolve()
+        if binary_path.is_file():
+            return binary_path
+
+        # Try with AUSTINPATH variable
+        austin_path = os.environ.get("AUSTINPATH", None)
+        if austin_path:
+            binary_path = Path(austin_path).expanduser().resolve() / binary_name
+            if binary_path.is_file():
+                return binary_path
+
+        # Try with .austinrc file
+        if AustinConfiguration().binary is not None:
+            binary_path = Path(AustinConfiguration().binary).expanduser().resolve()
+            if binary_path.is_file():
+                return binary_path
+
+        # Try from PATH
+        return self.BINARY
+
+    @functools.cached_property
+    def version(self) -> SemVer:
+        """Austin version."""
+        try:
+            return _to_semver(self._meta.get("austin"))
+        except KeyError as exc:
+            raise AustinError("Austin version not set") from exc
+
+    @functools.cached_property
+    def python_version(self) -> SemVer:
+        """The version of the detected Python interpreter."""
+        try:
+            return _to_semver(self._meta.get("python"))
+        except KeyError as exc:
+            raise AustinError("Python version not set") from exc
+
+    @property
+    def state(self) -> AustinState:
+        """The current state of Austin."""
+        return self._state