atv 0.1.0__py3-none-any.whl

atv/__init__.py

@@ -0,0 +1,7 @@
+"""atv package metadata."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

atv/__main__.py

@@ -0,0 +1,9 @@
+"""Support ``python -m atv``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":  # pragma: no cover - module level entry point
+    main()

atv/app.py

@@ -0,0 +1,249 @@
+"""Textual application scaffolding for atv."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Iterable
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Container
+from textual.coordinate import Coordinate
+from textual.widgets import DataTable, Footer, Header, Log, Static
+
+from .processes import ProcessInfo, list_python_processes
+
+
+class ProcessTable(DataTable):
+    """Tabular view of detected Python processes."""
+
+    def on_mount(self) -> None:  # noqa: D401 - Textual lifecycle hook
+        self.cursor_type = "row"
+        self.zebra_stripes = True
+        self.add_columns("PID", "Process", "File", "Command line")
+
+    def get_selected_pid(self) -> int | None:
+        """Return the PID associated with the highlighted row, if any."""
+
+        if self.row_count == 0:
+            return None
+        coordinate = self.cursor_coordinate
+        if coordinate is None:
+            return None
+
+        # Always read PID from column 0 to avoid reliance on internal row keys.
+        pid_coordinate = Coordinate(coordinate.row, 0)
+        try:
+            pid_value = self.get_cell_at(pid_coordinate)
+        except Exception:  # pragma: no cover - defensive safeguard
+            return None
+
+        try:
+            return int(pid_value)
+        except (TypeError, ValueError):
+            return None
+
+    def update_processes(self, processes: Iterable[ProcessInfo]) -> None:
+        """Replace the table content with the given process collection."""
+
+        self.clear(columns=False)
+        for info in processes:
+            display_name = info.name or "(unknown)"
+            file_display = info.file or "-"
+            self.add_row(
+                str(info.pid),
+                display_name,
+                file_display,
+                info.command_line,
+                key=info.pid,
+            )
+
+        if self.row_count:
+            self.cursor_coordinate = (0, 0)
+
+
+class AtvApp(App):
+    """Primary Textual application for atv."""
+
+    CSS = """
+    #content {
+        layout: horizontal;
+        padding: 1 2;
+        height: 1fr;
+    }
+
+    #process-pane, #output-pane {
+        layout: vertical;
+        height: 1fr;
+    }
+
+    #process-pane {
+        width: 1fr;
+    }
+
+    #output-pane {
+        width: 2fr;
+        margin-left: 2;
+    }
+
+    #intro {
+        color: #b3b3b3;
+    }
+
+    DataTable {
+        height: 1fr;
+    }
+
+    Log {
+        height: 1fr;
+        border: round $accent;
+        padding: 0 1;
+    }
+    """
+
+    TITLE = "atv"
+    SUB_TITLE = "Asyncio process discovery (alpha)"
+
+    BINDINGS = [
+        Binding("r", "refresh_processes", "Refresh", priority=True),
+        Binding("enter", "inspect_selected", "Inspect"),
+        Binding("p", "inspect_selected", "Inspect"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        yield Container(
+            Container(
+                Static(
+                    "Select a Python process to inspect. Press R to refresh. \n"
+                    "Press Enter to capture `python -m asyncio ps <pid>`.",
+                    id="intro",
+                ),
+                ProcessTable(id="process-table"),
+                id="process-pane",
+            ),
+            Container(
+                Static("Awaiting selection", id="ps-title"),
+                Log(id="ps-output"),
+                id="output-pane",
+            ),
+            id="content",
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:  # noqa: D401 - Textual lifecycle hook
+        self.refresh_process_list()
+
+    def action_refresh_processes(self) -> None:
+        """Binding target: refresh the process table."""
+
+        self.refresh_process_list()
+
+    def action_inspect_selected(self) -> None:
+        """Run ``python -m asyncio ps`` for the highlighted process."""
+
+        table = self.query_one(ProcessTable)
+        pid = table.get_selected_pid()
+        if pid is None:
+            self.notify("Select a Python process first.", severity="warning", timeout=3)
+            return
+
+        header = self.query_one("#ps-title", Static)
+        header.update(f"Running asyncio ps for PID {pid}…")
+        log = self.query_one("#ps-output", Log)
+        log.clear()
+        log.write("Awaiting asyncio ps output…")
+
+        self.run_worker(
+            self.capture_asyncio_ps(pid),
+            exclusive=True,
+            description=f"Inspecting PID {pid}",
+            name=f"ps-{pid}",
+        )
+
+    def refresh_process_list(self) -> None:
+        """Fetch Python processes and update UI state."""
+
+        processes = list_python_processes()
+        table = self.query_one(ProcessTable)
+        table.update_processes(processes)
+
+        count = len(processes)
+        noun = "process" if count == 1 else "processes"
+        self.sub_title = f"{count} Python {noun} visible"
+
+        if not count:
+            self.notify(
+                "No Python processes detected. Launch your target application and press R to refresh.",
+                severity="warning",
+                timeout=4,
+            )
+            output = self.query_one("#ps-output", Log)
+            output.clear()
+            self.query_one("#ps-title", Static).update("Awaiting selection")
+
+    async def capture_asyncio_ps(self, pid: int) -> None:
+        """Execute ``python -m asyncio ps`` for *pid* and stream the results."""
+
+        cmd = [sys.executable, "-m", "asyncio", "ps", str(pid)]
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except FileNotFoundError:
+            self._display_ps_failure(pid, "Failed to locate python executable to launch asyncio ps.")
+            return
+
+        stdout_bytes, stderr_bytes = await process.communicate()
+        stdout_text = stdout_bytes.decode("utf-8", errors="replace")
+        stderr_text = stderr_bytes.decode("utf-8", errors="replace")
+
+        self.log.debug(
+            "asyncio ps completed",
+            pid=pid,
+            returncode=process.returncode,
+            stdout_preview=stdout_text[:200],
+            stderr_preview=stderr_text[:200],
+        )
+
+        if process.returncode != 0:
+            message = stderr_text or "asyncio ps exited with a non-zero status."
+            self._display_ps_failure(pid, message.strip())
+            return
+
+        self._display_ps_success(pid, stdout_text, stderr_text)
+
+    def _display_ps_success(self, pid: int, stdout_text: str, stderr_text: str) -> None:
+        header = self.query_one("#ps-title", Static)
+        header.update(f"asyncio ps output for PID {pid}")
+        log = self.query_one("#ps-output", Log)
+        log.clear()
+        lines: list[str] = [f"$ {sys.executable} -m asyncio ps {pid}"]
+
+        if stdout_text.strip():
+            lines.append("-- stdout --")
+            lines.extend(stdout_text.splitlines())
+        else:
+            lines.append("(stdout was empty)")
+
+        if stderr_text.strip():
+            lines.append("")
+            lines.append("-- stderr --")
+            lines.extend(stderr_text.splitlines())
+
+        log.write_lines(lines)
+
+    def _display_ps_failure(self, pid: int, message: str) -> None:
+        header = self.query_one("#ps-title", Static)
+        header.update(f"Failed to capture asyncio ps for PID {pid}")
+        log = self.query_one("#ps-output", Log)
+        log.clear()
+        log.write_lines([
+            f"$ {sys.executable} -m asyncio ps {pid}",
+            "-- error --",
+            message or "asyncio ps failed with an unknown error.",
+        ])

atv/cli.py

@@ -0,0 +1,15 @@
+"""Command-line entry points for atv."""
+
+from __future__ import annotations
+
+from .app import AtvApp
+
+
+def main() -> None:
+    """Launch the Textual application."""
+
+    AtvApp().run()
+
+
+if __name__ == "__main__":
+    main()

atv/processes.py

@@ -0,0 +1,82 @@
+"""Utilities for discovering asyncio-capable Python processes."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Iterable, List, Sequence
+
+import psutil
+
+
+@dataclass(slots=True)
+class ProcessInfo:
+    """Lightweight descriptor for a running Python process."""
+
+    pid: int
+    name: str
+    command_line: str
+    file: str | None
+
+
+def list_python_processes() -> List[ProcessInfo]:
+    """Return visible Python processes that are likely asyncio-capable.
+
+    We treat a process as "Python" if either its executable name or command
+    line contains the token ``python``. Processes we cannot introspect (e.g.
+    due to permissions) are skipped.
+    """
+
+    candidates: List[ProcessInfo] = []
+    for proc in psutil.process_iter(attrs=["pid", "name", "cmdline"]):
+        try:
+            name = proc.info.get("name") or ""
+            cmdline: Iterable[str] = proc.info.get("cmdline") or []
+            cmdline_list: List[str] = list(cmdline)
+            mark = "python" in name.lower() or any(
+                "python" in part.lower() for part in cmdline_list
+            )
+            if not mark:
+                continue
+
+            command_line = " ".join(cmdline_list) if cmdline_list else name
+            file = _detect_entrypoint(cmdline_list)
+            candidates.append(
+                ProcessInfo(
+                    pid=proc.pid, name=name, command_line=command_line, file=file
+                )
+            )
+        except (psutil.AccessDenied, psutil.NoSuchProcess):
+            continue
+
+    candidates.sort(key=lambda info: info.pid)
+    return candidates
+
+
+def _detect_entrypoint(cmdline: Sequence[str]) -> str | None:
+    """Best-effort extraction of the target script/module name.
+
+    Returns a basename for file paths, the module string for ``-m`` invocations,
+    or ``None`` if nothing matches.
+    """
+
+    if not cmdline:
+        return None
+
+    remainder = list(cmdline)
+
+    # If command begins with python executable, skip it.
+    if remainder and "python" in os.path.basename(remainder[0]).lower():
+        remainder = remainder[1:]
+
+    i = 0
+    while i < len(remainder):
+        token = remainder[i]
+        if token == "-m" and i + 1 < len(remainder):
+            return remainder[i + 1]
+        if token.startswith("-"):
+            i += 1
+            continue
+        # Treat first non-option token as a potential script path.
+        return os.path.basename(token)
+    return None

atv-0.1.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: atv
+Version: 0.1.0
+Summary: TaskScope: a TUI tool for experimenting with Python 3.14 asyncio ps/pstree features
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual<0.61,>=0.57
+Requires-Dist: psutil>=5.9
+Dynamic: license-file
+
+# atv 🌱
+
+<img width="2850" height="1480" alt="image" src="https://github.com/user-attachments/assets/9b8916b7-4ca0-4715-b63b-280f2c1bf8fd" />
+
+
+atv(async task viewer) is a CLI for exploring Python `asyncio` processes with a Textual UI. It starts by listing Python processes running locally, and we plan to integrate execution of `asyncio ps` / `pstree` and call-graph visualization.
+
+## Setup
+
+```bash
+cd atv
+uv sync
+```
+
+`uv sync` installs the specified dependencies (`textual`, `psutil`) into your local environment.
+
+## Usage
+
+```bash
+uv run atv
+```
+
+Shortcuts:
+
+- `R` – Refresh the process list (the table shows PID / Process / File / Command Line)
+- `Q` – Exit
+- `Enter` / `P` – Run `python -m asyncio ps` for the selected PID and display the result in the right pane
+
+### Using uvx
+
+Once released, you'll be able to launch it with a one-liner.
+
+```bash
+uvx atv
+```
+
+If you want to test uvx behavior during local development, run the following in the project root.
+
+```bash
+uvx --from . atv
+```
+
+## Roadmap
+
+- View that periodically runs `python -m asyncio ps` for the selected process
+- Visualization for `asyncio pstree` / `format_call_graph`
+- Snapshot capture and diff comparison
+- Integration with the FastAPI demo (retrieve task information via the API)
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

atv-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+atv/__init__.py,sha256=cDhu2_cmAhSN_dpqA71H3Shvbcz3R675dtupTmqog7g,114
+atv/__main__.py,sha256=cRSA9o0oEbImR-ZVm5QNdxuvxv027xXUo9yPPyWti_U,179
+atv/app.py,sha256=wi8VCKuJF0tTHK3cPO4WaHzPAtDnF_1nTfCl7imdh9Q,7743
+atv/cli.py,sha256=Nvl2rWMd56Uz3hqljePqxTIVUbQXNWdPrKz-irtBn78,226
+atv/processes.py,sha256=66B6YpKUV4dmsemACtyGPTzlnNQkR_dsEfJbVp8k-MY,2480
+atv-0.1.0.dist-info/licenses/LICENSE,sha256=7ZKgkwFg8Wl7hZzdWuaB5TD9p6ogW3rKUswUtS8vAIQ,1069
+atv-0.1.0.dist-info/METADATA,sha256=dfW2UVK98pK0gHG-1A-4tYZTNKaCxyrncbKdnfz4-Iw,1673
+atv-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+atv-0.1.0.dist-info/entry_points.txt,sha256=_k2ip4adJ7bdQuCUT66MyfOHCjL4MAkT5NUEfG4O_Dw,37
+atv-0.1.0.dist-info/top_level.txt,sha256=SMwFWE_ISfvPk9wZWA-T84DwRwemIA-dR9f6gAGzCV0,4
+atv-0.1.0.dist-info/RECORD,,

atv-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

atv-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+atv = atv.cli:main

atv-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Junya Fukuda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atv-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+atv