Metadata-Version: 2.4
Name: pyrasite
Version: 2.1.0
Summary: Inject code into a running Python process
Author-email: Luke Macken <lmacken@redhat.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/lmacken/pyrasite
Project-URL: Documentation, https://pyrasite.readthedocs.io
Project-URL: Source, https://github.com/lmacken/pyrasite
Project-URL: Changelog, https://github.com/lmacken/pyrasite/blob/develop/CHANGELOG.rst
Keywords: debugging,injection,runtime
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Provides-Extra: memory-viewer
Requires-Dist: urwid>=2.0; extra == "memory-viewer"
Requires-Dist: meliae; extra == "memory-viewer"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff<0.18,>=0.17; extra == "dev"
Requires-Dist: sphinx>=7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Dynamic: license-file

.. image:: https://raw.githubusercontent.com/lmacken/pyrasite/develop/docs/logo.png

pyrasite
========

.. image:: https://github.com/lmacken/pyrasite/actions/workflows/ci.yml/badge.svg?branch=develop
   :target: https://github.com/lmacken/pyrasite/actions/workflows/ci.yml
.. image:: https://img.shields.io/pypi/v/pyrasite?style=flat
   :target: https://pypi.org/project/pyrasite/

Tools for injecting arbitrary code into running Python processes.

:homepage: https://github.com/lmacken/pyrasite
:documentation: https://pyrasite.readthedocs.io/
:download: https://pypi.org/project/pyrasite/
:source: https://github.com/lmacken/pyrasite
:issues: https://github.com/lmacken/pyrasite/issues

Requirements
~~~~~~~~~~~~

 * `gdb <https://www.gnu.org/s/gdb>`_ (version 7.3+)
 * A Linux system whose ptrace policy allows attaching to the target
   process.  See `ptrace_scope` below.

On OS X you will need to have a codesigned gdb - see https://sourceware.org/gdb/wiki/BuildingOnDarwin
if you get errors while running with --verbose which mention codesigning.

Installation
~~~~~~~~~~~~

::

    pipx install pyrasite

or, for the optional memory viewer::

    pip install "pyrasite[memory-viewer]"

Compatibility
~~~~~~~~~~~~~

Pyrasite runs on CPython 3.9 through 3.15. Injection works between versions
as well, so you can run Pyrasite under one Python and inject into a process
running another. Both the pyrasite client and the target process must be
CPython.

ptrace_scope
~~~~~~~~~~~~

Recent Linux distributions restrict ptrace so that a process may only be
attached to by its ancestors. If ``/proc/sys/kernel/yama/ptrace_scope`` is
non-zero you will see a warning. You can either allow attaching globally::

    echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

or let the target process opt in by calling ``prctl(PR_SET_PTRACER,
PR_SET_PTRACER_ANY)``. On Fedora, SELinux may also need::

    sudo setsebool -P deny_ptrace=off

For multi-threaded programs pyrasite queues the payload with
``Py_AddPendingCall`` so that it runs on a thread that already holds the GIL.
If the target is blocked in C and never executes Python bytecode, use
``--inject-method direct`` instead.

Testing
~~~~~~~

::

    pip install -e ".[dev]"
    pytest
    ruff check .
    ruff format --check .

To run the suite against every supported interpreter with `uv
<https://docs.astral.sh/uv/>`_::

    uv python install 3.9 3.10 3.11 3.12 3.13 3.14 3.15
    tox

To test injecting from one interpreter into all of the others, set
``PYRASITE_TEST_INTERPRETERS`` to a colon-separated list of interpreter
paths before running pytest.


pyrasite-gui
~~~~~~~~~~~~

The graphical interface is maintained separately at
https://github.com/lmacken/pyrasite-gui.

Authors
~~~~~~~

Created by `Luke Macken <https://twitter.com/lmacken>`_ with the help of
`David Malcolm <https://dmalcolm.livejournal.com>`_ and many other
`contributors <https://github.com/lmacken/pyrasite/contributors>`_.
Logo by `Adam Saunders <https://fedorahosted.org/design-team/ticket/214>`_.

Licenses
~~~~~~~~

Code
^^^^

.. image:: https://www.gnu.org/graphics/gplv3-127x51.png
   :target: https://www.gnu.org/licenses/gpl.txt

Logo
^^^^

.. image:: https://creativecommons.org/images/deed/nolaw.png
   :target: https://creativecommons.org/publicdomain/zero/1.0/
