Debian Codegraph @

PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: manhole
3 Version: 1.8.1
4 Summary: Manhole is in-process service that will accept unix domain socket connections and present thestacktraces for all threads and an interactive prompt.
5 Home-page: https://github.com/ionelmc/python-manhole
6 Author: Ionel Cristian Mărieș
7 Author-email: [email protected]
8 License: BSD-2-Clause
9 Project-URL: Documentation, https://python-manhole.readthedocs.io/
10 Project-URL: Changelog, https://python-manhole.readthedocs.io/en/latest/changelog.html
11 Project-URL: Issue Tracker, https://github.com/ionelmc/python-manhole/issues
12 Keywords: debugging,manhole,thread,socket,unix domain socket
13 Classifier: Development Status :: 5 - Production/Stable
14 Classifier: Intended Audience :: Developers
15 Classifier: License :: OSI Approved :: BSD License
16 Classifier: Operating System :: Unix
17 Classifier: Operating System :: POSIX
18 Classifier: Programming Language :: Python
19 Classifier: Topic :: Software Development :: Debuggers
20 Classifier: Topic :: Utilities
21 Classifier: Topic :: System :: Monitoring
22 Classifier: Topic :: System :: Networking
23 Classifier: Programming Language :: Python :: 3
24 Classifier: Programming Language :: Python :: 3 :: Only
25 Classifier: Programming Language :: Python :: 3.8
26 Classifier: Programming Language :: Python :: 3.9
27 Classifier: Programming Language :: Python :: 3.10
28 Classifier: Programming Language :: Python :: 3.11
29 Classifier: Programming Language :: Python :: 3.12
30 Classifier: Programming Language :: Python :: Implementation :: CPython
31 Classifier: Programming Language :: Python :: Implementation :: PyPy
32 Classifier: Topic :: Utilities
33 Requires-Python: >=3.8
34 License-File: LICENSE
35 License-File: AUTHORS.rst
36
37 ========
38 Overview
39 ========
40
41
42
43
44 Features
45 ========
46
47 * Uses unix domain sockets, only root or same effective user can connect.
48 * Can run the connection in a thread or in a signal handler (see ``oneshot_on`` option).
49 * Can start the thread listening for connections from a signal handler (see ``activate_on`` option)
50 * Compatible with apps that fork, reinstalls the Manhole thread after fork - had to monkeypatch os.fork/os.forkpty for
51 this.
52 * Compatible with gevent and eventlet with some limitations - you need to either:
53
54 * Use ``oneshot_on``, *or*
55 * Disable thread monkeypatching (eg: ``gevent.monkey.patch_all(thread=False)``, ``eventlet.monkey_patch(thread=False)``
56
57 Note: on eventlet `you might <https://github.com/eventlet/eventlet/issues/401>`_ need to setup the hub first to prevent
58 circular import problems:
59
60 .. sourcecode:: python
61
62 import eventlet
63 eventlet.hubs.get_hub() # do this first
64 eventlet.monkey_patch(thread=False)
65
66 * The thread is compatible with apps that use signalfd (will mask all signals for the Manhole threads).
67
68 Options
69 -------
70
71 .. code-block:: python
72
73 manhole.install(
74 verbose=True,
75 verbose_destination=2,
76 patch_fork=True,
77 activate_on=None,
78 oneshot_on=None,
79 sigmask=manhole.ALL_SIGNALS,
80 socket_path=None,
81 reinstall_delay=0.5,
82 locals=None,
83 strict=True,
84 )
85
86 * ``verbose`` - Set it to ``False`` to squelch the logging.
87 * ``verbose_destination`` - Destination for verbose messages. Set it to a file descriptor or handle. Default is
88 unbuffered stderr (stderr ``2`` file descriptor).
89 * ``patch_fork`` - Set it to ``False`` if you don't want your ``os.fork`` and ``os.forkpy`` monkeypatched
90 * ``activate_on`` - Set to ``"USR1"``, ``"USR2"`` or some other signal name, or a number if you want the Manhole thread
91 to start when this signal is sent. This is desirable in case you don't want the thread active all the time.
92 * ``thread`` - Set to ``True`` to start the always-on ManholeThread. Default: ``True``.
93 Automatically switched to ``False`` if ``oneshot_on`` or ``activate_on`` are used.
94 * ``oneshot_on`` - Set to ``"USR1"``, ``"USR2"`` or some other signal name, or a number if you want the Manhole to
95 listen for connection in the signal handler. This is desireable in case you don't want threads at all.
96 * ``sigmask`` - Will set the signal mask to the given list (using ``signalfd.sigprocmask``). No action is done if
97 ``signalfd`` is not importable. **NOTE**: This is done so that the Manhole thread doesn't *steal* any signals;
98 Normally that is fine because Python will force all the signal handling to be run in the main thread but signalfd
99 doesn't.
100 * ``socket_path`` - Use a specific path for the unix domain socket (instead of ``/tmp/manhole-<pid>``). This disables
101 ``patch_fork`` as children cannot reuse the same path.
102 * ``reinstall_delay`` - Delay the unix domain socket creation *reinstall_delay* seconds. This alleviates
103 cleanup failures when using fork+exec patterns.
104 * ``locals`` - Names to add to manhole interactive shell locals.
105 * ``daemon_connection`` - The connection thread is daemonic (dies on app exit). Default: ``False``.
106 * ``redirect_stderr`` - Redirect output from stderr to manhole console. Default: ``True``.
107 * ``strict`` - If ``True`` then ``AlreadyInstalled`` will be raised when attempting to install manhole twice.
108 Default: ``True``.
109
110 Environment variable installation
111 ---------------------------------
112
113 Manhole can be installed via the ``PYTHONMANHOLE`` environment variable.
114
115 This::
116
117 PYTHONMANHOLE='' python yourapp.py
118
119 Is equivalent to having this in ``yourapp.py``::
120
121 import manhole
122 manhole.install()
123
124 Any extra text in the environment variable is passed to ``manhole.install()``. Example::
125
126 PYTHONMANHOLE='oneshot_on="USR2"' python yourapp.py
127
128 What happens when you actually connect to the socket
129 ----------------------------------------------------
130
131 1. Credentials are checked (if it's same user or root)
132 2. ``sys.__std*__``/``sys.std*`` are redirected to the UDS
133 3. Stacktraces for each thread are written to the UDS
134 4. REPL is started so you can fiddle with the process
135
136 Known issues
137 ============
138
139 * Using threads and file handle (not raw file descriptor) ``verbose_destination`` can cause deadlocks. See bug reports:
140 `PyPy <https://github.com/pypy/pypy/issues/1895>`_ and `Python 3.4 <http://bugs.python.org/issue22697>`_.
141
142 SIGTERM and socket cleanup
143 --------------------------
144
145 By default Python doesn't call the ``atexit`` callbacks with the default SIGTERM handling. This makes manhole leave
146 stray socket files around. If this is undesirable you should install a custom SIGTERM handler so ``atexit`` is
147 properly invoked.
148
149 Example:
150
151 .. code-block:: python
152
153 import signal
154 import sys
155
156 def handle_sigterm(signo, frame):
157 sys.exit(128 + signo) # this will raise SystemExit and cause atexit to be called
158
159 signal.signal(signal.SIGTERM, handle_sigterm)
160
161 Using Manhole with uWSGI
162 ------------------------
163
164 Because uWSGI overrides signal handling Manhole is a bit more tricky to setup. One way is to use "uWSGI signals" (not
165 the POSIX signals) and have the workers check a file for the pid you want to open the Manhole in.
166
167 Stick something this in your WSGI application file:
168
169 .. sourcecode:: python
170
171 from __future__ import print_function
172 import sys
173 import os
174 import manhole
175
176 stack_dump_file = '/tmp/manhole-pid'
177 uwsgi_signal_number = 17
178
179 try:
180 import uwsgi
181
182 if not os.path.exists(stack_dump_file):
183 open(stack_dump_file, 'w')
184
185 def open_manhole(dummy_signum):
186 with open(stack_dump_file, 'r') as fh:
187 pid = fh.read().strip()
188 if pid == str(os.getpid()):
189 inst = manhole.install(strict=False, thread=False)
190 inst.handle_oneshot(dummy_signum, dummy_signum)
191
192 uwsgi.register_signal(uwsgi_signal_number, 'workers', open_manhole)
193 uwsgi.add_file_monitor(uwsgi_signal_number, stack_dump_file)
194
195 print("Listening for stack mahole requests via %r" % (stack_dump_file,), file=sys.stderr)
196 except ImportError:
197 print("Not running under uwsgi; unable to configure manhole trigger", file=sys.stderr)
198 except IOError:
199 print("IOError creating manhole trigger %r" % (stack_dump_file,), file=sys.stderr)
200
201
202 # somewhere bellow you'd have something like
203 from django.core.wsgi import get_wsgi_application
204 application = get_wsgi_application()
205 # or
206 def application(environ, start_response):
207 start_response('200 OK', [('Content-Type', 'text/plain'), ('Content-Length', '2')])
208 yield b'OK'
209
210 To open the Manhole just run `echo 1234 > /tmp/manhole-pid` and then `manhole-cli 1234`.
211
212 Requirements
213 ============
214
215 :OS: Linux, OS X
216 :Runtime: Python 2.7, 3.4, 3.5, 3.6 or PyPy
217
218 Similar projects
219 ================
220
221 * Twisted's `manhole <http://twistedmatrix.com/documents/current/api/twisted.conch.manhole.html>`__ - it has colors and
222 server-side history.
223 * `wsgi-shell <https://github.com/GrahamDumpleton/wsgi-shell>`_ - spawns a thread.
224 * `pyrasite <https://github.com/lmacken/pyrasite>`_ - uses gdb to inject code.
225 * `pydbattach <https://github.com/albertz/pydbattach>`_ - uses gdb to inject code.
226 * `pystuck <https://github.com/alonho/pystuck>`_ - very similar, uses `rpyc <https://github.com/tomerfiliba/rpyc>`_ for
227 communication.
228 * `pyringe <https://github.com/google/pyringe>`_ - uses gdb to inject code, more reliable, but relies on `dbg` python
229 builds unfortunatelly.
230 * `pdb-clone <https://pypi.python.org/pypi/pdb-clone>`_ - uses gdb to inject code, with a `different strategy
231 <https://code.google.com/p/pdb-clone/wiki/RemoteDebugging>`_.
232
233
234 Changelog
235 =========
236
237 1.8.1 (2024-07-24)
238 ------------------
239
240 * Fixed buffering issue on Python 3.11. See ``66``.
241 * Cleaned up some packaging/test problems.
242 * Removed more leftover Python 2 code.
243 * Fixed license metadata. See: ``68``.
244
245 1.8.0 (2021-04-08)
246 ------------------
247
248 * Simplified connection closing code.
249 Contributed by Anton Ryzhov in ``62``.
250 * Made connection shutdown in ``manhole-cli`` more graceful.
251 Contributed by Anton Ryzhov in ``63``.
252
253 1.7.0 (2021-03-22)
254 ------------------
255
256 * Fixed memory leak via ``sys.last_type``, ``sys.last_value``, ``sys.last_traceback``.
257 Contributed by Anton Ryzhov in ``59``.
258 * Fixed a bunch of double-close bugs and simplified stream handler code.
259 Contributed by Anton Ryzhov in ``58``.
260 * Loosen up ``pid`` argument parsing in ``manhole-cli`` to allow using paths with any prefix
261 (not just ``/tmp``).
262
263 1.6.0 (2019-01-19)
264 ------------------
265
266 * Testing improvements (changed some skips to xfail, added osx in Travis).
267 * Fixed long standing Python 2.7 bug where ``sys.getfilesystemencoding()`` would be broken after installing a threaded
268 manhole. See ``51``.
269 * Dropped support for Python 2.6, 3.3 and 3.4.
270 * Fixed handling when ``socket.setdefaulttimeout()`` is used.
271 Contributed by "honnix" in ``53``.
272 * Fixed some typos. Contributed by Jesús Cea in ``43``.
273 * Fixed handling in ``manhole-cli`` so that timeout is actually seconds and not milliseconds.
274 Contributed by Nir Soffer in ``45``.
275 * Cleaned up useless polling options in ``manhole-cli``.
276 Contributed by Nir Soffer in ``46``.
277 * Documented and implemented a solution for using Manhole with Eventlet.
278 See ``49``.
279
280 1.5.0 (2017-08-31)
281 ------------------
282
283 * Added two string aliases for ``connection_handler`` option. Now you can conveniently use ``connection_handler="exec"``.
284 * Improved ``handle_connection_exec``. It now has a clean way to exit (``exit()``) and properly closes the socket.
285
286 1.4.0 (2017-08-29)
287 ------------------
288
289 * Added the ``connection_handler`` install option. Default value is ``manhole.handle_connection_repl``, and alternate
290 ``manhole.handle_connection_exec`` is provided (very simple: no output redirection, no stacktrace dumping).
291 * Dropped Python 3.2 from the test grid. It may work but it's a huge pain to support (pip/pytest don't support it anymore).
292 * Added Python 3.5 and 3.6 in the test grid.
293 * Fixed issues with piping to ``manhole-cli``. Now ``echo foobar | manhole-cli`` will wait 1 second for output from manhole
294 (you can customize this with the ``--timeout`` option).
295 * Fixed issues with newer PyPy (caused by gevent/eventlet socket unwrapping).
296
297 1.3.0 (2015-09-03)
298 ------------------
299
300 * Allowed Manhole to be configured without any thread or activation (in case you want to manually activate).
301 * Added an example and tests for using Manhole with uWSGi.
302 * Fixed error handling in ``manhole-cli`` on Python 3 (exc vars don't leak anymore).
303 * Fixed support for running in gevent/eventlet-using apps on Python 3 (now that they support Python 3).
304 * Allowed reinstalling the manhole (in non-``strict`` mode). Previous install is undone.
305
306 1.2.0 (2015-07-06)
307 ------------------
308
309 * Changed ``manhole-cli``:
310
311 * Won't spam the terminal with errors if socket file doesn't exist.
312 * Allowed sending any signal (new ``--signal`` argument).
313 * Fixed some validation issues for the ``PID`` argument.
314
315 1.1.0 (2015-06-06)
316 ------------------
317
318 * Added support for installing the manhole via the ``PYTHONMANHOLE`` environment variable.
319 * Added a ``strict`` install option. Set it to false to avoid getting the ``AlreadyInstalled`` exception.
320 * Added a ``manhole-cli`` script that emulates ``socat readline unix-connect:/tmp/manhole-1234``.
321
322 1.0.0 (2014-10-13)
323 ------------------
324
325 * Added ``socket_path`` install option (contributed by `Nir Soffer`_).
326 * Added ``reinstall_delay`` install option.
327 * Added ``locals`` install option (contributed by `Nir Soffer`_).
328 * Added ``redirect_stderr`` install option (contributed by `Nir Soffer`_).
329 * Lots of internals cleanup (contributed by `Nir Soffer`_).
330
331 0.6.2 (2014-04-28)
332 ------------------
333
334 * Fix OS X regression.
335
336 0.6.1 (2014-04-28)
337 ------------------
338
339 * Support for OS X (contributed by `Saulius Menkevičius`_).
340
341 .. _Saulius Menkevičius: https://github.com/razzmatazz
342 .. _Nir Soffer: https://github.com/nirs