`Mathics3 <https://mathics.org>`_ Debugger Module
==================================================
Until we have some proper documentation, here are some examples.
Mathics3 Module Examples
------------------------
Loading Module and getting help
+++++++++++++++++++++++++++++++
To enable debugging in Mathics3, install ``mathics3-trepan``.
Inside a mathics3 session run ``LoadModule["pymathics.trepan"]``.
You can then force a call to the debugger using Mathics3 builtin function ``Debugger[]``.
Extensive help is available in the debugger using the ``help`` command.
Here is an example of this and calling ``help``:
.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/help-example.png
Stopping on certain Mathics3 call events
+++++++++++++++++++++++++++++++++++++++++
After loading Next, you may want to set up events that trigger entering the debugger::
In[2]:= DebugActivate[mpmath->True]
Out[2]=
Other events include: "Debugger", "Get", "Numpy", "SymPy", "apply", "evalMethod", and "evaluation".
In the above, ``mpmath->True`` goes into the debugger anytime an mpmath function is called.
``Exp[1.0]`` is such a function::
In[3]:= Exp[1.0]
mpmath call : mpmath.ctx_base.StandardBaseContext.power(2.718281828459045, 1.0)
(/tmp/mathics-core/mathics/eval/arithmetic.py:68 @88): run_mpmath
mp 68 result_mp = tracing.run_mpmath(mpmath_function, *mpmath_args)
(Mathics3 Debug)
A useful command to run is ``bt -b`` which shows the Built-in Function calls in the call stack::
(Mathics3 Debug) bt -b
B#0 (2) Power[z__]
called from file '/tmp/mathics-core/mathics/core/builtin.py' at line 659
B#1 (3) Power[x_, y_]
called from file '/tmp/mathics-core/mathics/builtin/arithfns/basic.py' at line 477
To get a list of all debugger commands::
(Mathics3 Debug) help *
List of all debugger commands:
abort backtrace down frame help kill printelement quit set trepan3k
alias continue eval handle info mathics3 python reload show up
When you are done inspecting things, run ``continue`` (or short-hand ``c``) to resume execution::
(Mathics3 Debug) c
mpmath result: 2.71828182845905
Out[3]= 2.71828
Improved TraceEvaluation
+++++++++++++++++++++++++
As before, install ``mathics3-trepan``. To set up tracing ``.evaluate()`` calls::
In[1]:= LoadModule["pymathics.trepan"]
Out[1]= "pymathics.trepan"
In[2]:= TraceActivate[evaluation->True]
Out[2]=
In contrast to ``DebugActivate``, ``TraceActivate`` prints or traces events.
Now we are ready for some action:
.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/TraceEvaluation.png
Above we trace before an ``evaluate()`` method call and also sometimes show the return value.
To reduce unnecessary output, evaluations are performed only when the evaluation changes. In particular, above there is an evaluation of the Symbols "Power" and "Plus". The result of evaluating these is the same symbol. So we don't show either ``Evaluating: Power``or ``Returning: Power``. Similarly, we omit the same for ``Plus``.
We also omit ``Returning: Plus[1, x]`` because ``Plus[1, x]`` is the same expression as went in.
But notice we *do* show ``Returning: Plus[x, 1] = Plus[1, x]``. Here, the difference is that the order of the parameters got rearranged. Perhaps this is not interesting either, but currently, it is shown.
Now let's do the same thing but set the value of ``x``::
In[4]:= x = 3
Evaluating: Set[x, 3]
Returning: Set[x, 3] = 3
Out[4]= 3
In[5]:= (x + 1) ^ 2
Evaluating: Power[Plus[x, 1], 2]
Evaluating: Plus[x, 1]
Returning: x = 3
Returning: Plus[x, 1] = 4
Returning: Power[Plus[x, 1], 2] = 16
Out[5]= 16
Here, the return values have the computed Integer values from evaluation, as you'd expect to see when working with Integer values instead of mixed symbolic and Integer values.
DebugEvaluation
+++++++++++++++
``DebugEvaluation`` is like ``TraceEvaluation``, but instead of displaying expression information, we stop inside a gdb-like debugger, or rather a trepan-like debugger. See https://github.com/Trepan-Debugger for other such gdb-like debuggers. I use this debugger base because I am familiar with the code, and it was written in a way that was intended to be easily adapted to other programming languages.
Replacing Expression values in DebugEvaluation
++++++++++++++++++++++++++++++++++++++++++++++
You can change the computation of a value instead of calling a Mathics3 built-in function, or replace the return value after calling a Mathics3 built-in function.
This is done using the ``set return`` command. Here is an example of that:
.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/traceback-with-Ctrl-C.png
Post-mortem debugging
++++++++++++++++++++++
To enter the debugger on an unrecoverable error, use the
``--post-mortem`` option when invoking ``mathics``::
mathics --post-mortem
# Find a Python bug in Mathics3 and trigger that.
# I modified Compress.eval() and added 1/0
In[1]:= Compress["abc"]
Traceback (most recent call last):
File "/tmp/mathicsscript", line 8, in <module>
sys.exit(main())
^^^^^
...
ZeroDivisionError: division by zero
Uncaught exception. Entering post-mortem debugger...
(/tmp/mathics/builtin/compress.py:37 @6): eval
!! 37 1/0
R=> (<class 'ZeroDivisionError'>, ZeroDivisionError('division by zero'),
(Trepan3k:pm) load trepan3k_mathics3
loaded command: "mathics3"
loaded command: "mbacktrace"
loaded command: "mup"
loaded command: "printelement"
(Trepan3k:pm) mbt -b
B>0 (0) Compress[expr_, OptionsPattern[Compress]]
called from file '/tmp/Mathics3/mathics-core/mathics/builtin/compress.py' at line 37
B>1 (36) Compress[expr_, OptionsPattern[Compress]]
called from file '/tmp/Mathics3/mathics-core/mathics/builtin/compress.py' at line 37
(Trepan3k:pm)
Showing Tracebacks on long-running operations
++++++++++++++++++++++++++++++++++++++++++++++
The debugger (and trepan3k) support signal handling. With this, you can set up a ``SIGINT`` handler.
Here is an example:
.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/traceback-with-Ctrl-C.png
Without the debugger, but with ``trepan3k`` installed, you can use ``Breakpoint[]``, and issue the ``handle`` command. You won't get as nice of a traceback, but it should still work.
Raw data
{
"_id": null,
"home_page": null,
"name": "Mathics3-Module-trepan",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Mathics Group <mathics-devel@googlegroups.com>",
"keywords": "Mathematica, Wolfram, Interpreter, Shell, Math, CAS",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1b/5f/2a236dde13a1d95a73fd836b149991040a44c712bb59f25fbdd152b18f4f/mathics3_module_trepan-9.0.0.tar.gz",
"platform": null,
"description": "`Mathics3 <https://mathics.org>`_ Debugger Module\n==================================================\n\nUntil we have some proper documentation, here are some examples.\n\n\nMathics3 Module Examples\n------------------------\n\nLoading Module and getting help\n+++++++++++++++++++++++++++++++\n\nTo enable debugging in Mathics3, install ``mathics3-trepan``.\nInside a mathics3 session run ``LoadModule[\"pymathics.trepan\"]``.\n\nYou can then force a call to the debugger using Mathics3 builtin function ``Debugger[]``.\n\nExtensive help is available in the debugger using the ``help`` command.\n\nHere is an example of this and calling ``help``:\n\n.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/help-example.png\n\n\nStopping on certain Mathics3 call events\n+++++++++++++++++++++++++++++++++++++++++\n\nAfter loading Next, you may want to set up events that trigger entering the debugger::\n\n In[2]:= DebugActivate[mpmath->True]\n Out[2]=\n\nOther events include: \"Debugger\", \"Get\", \"Numpy\", \"SymPy\", \"apply\", \"evalMethod\", and \"evaluation\".\n\nIn the above, ``mpmath->True`` goes into the debugger anytime an mpmath function is called.\n``Exp[1.0]`` is such a function::\n\n In[3]:= Exp[1.0]\n mpmath call : mpmath.ctx_base.StandardBaseContext.power(2.718281828459045, 1.0)\n (/tmp/mathics-core/mathics/eval/arithmetic.py:68 @88): run_mpmath\n mp 68 result_mp = tracing.run_mpmath(mpmath_function, *mpmath_args)\n (Mathics3 Debug)\n\nA useful command to run is ``bt -b`` which shows the Built-in Function calls in the call stack::\n\n (Mathics3 Debug) bt -b\n B#0 (2) Power[z__]\n called from file '/tmp/mathics-core/mathics/core/builtin.py' at line 659\n B#1 (3) Power[x_, y_]\n called from file '/tmp/mathics-core/mathics/builtin/arithfns/basic.py' at line 477\n\nTo get a list of all debugger commands::\n\n (Mathics3 Debug) help *\n List of all debugger commands:\n abort backtrace down frame help kill printelement quit set trepan3k\n alias continue eval handle info mathics3 python reload show up\n\nWhen you are done inspecting things, run ``continue`` (or short-hand ``c``) to resume execution::\n\n (Mathics3 Debug) c\n mpmath result: 2.71828182845905\n Out[3]= 2.71828\n\n\nImproved TraceEvaluation\n+++++++++++++++++++++++++\n\nAs before, install ``mathics3-trepan``. To set up tracing ``.evaluate()`` calls::\n\n In[1]:= LoadModule[\"pymathics.trepan\"]\n Out[1]= \"pymathics.trepan\"\n\n In[2]:= TraceActivate[evaluation->True]\n Out[2]=\n\nIn contrast to ``DebugActivate``, ``TraceActivate`` prints or traces events.\n\nNow we are ready for some action:\n\n.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/TraceEvaluation.png\n\nAbove we trace before an ``evaluate()`` method call and also sometimes show the return value.\n\nTo reduce unnecessary output, evaluations are performed only when the evaluation changes. In particular, above there is an evaluation of the Symbols \"Power\" and \"Plus\". The result of evaluating these is the same symbol. So we don't show either ``Evaluating: Power``or ``Returning: Power``. Similarly, we omit the same for ``Plus``.\n\nWe also omit ``Returning: Plus[1, x]`` because ``Plus[1, x]`` is the same expression as went in.\nBut notice we *do* show ``Returning: Plus[x, 1] = Plus[1, x]``. Here, the difference is that the order of the parameters got rearranged. Perhaps this is not interesting either, but currently, it is shown.\n\nNow let's do the same thing but set the value of ``x``::\n\n In[4]:= x = 3\n Evaluating: Set[x, 3]\n\n Returning: Set[x, 3] = 3\n\n Out[4]= 3\n\n In[5]:= (x + 1) ^ 2\n Evaluating: Power[Plus[x, 1], 2]\n Evaluating: Plus[x, 1]\n Returning: x = 3\n Returning: Plus[x, 1] = 4\n Returning: Power[Plus[x, 1], 2] = 16\n\n Out[5]= 16\n\nHere, the return values have the computed Integer values from evaluation, as you'd expect to see when working with Integer values instead of mixed symbolic and Integer values.\n\nDebugEvaluation\n+++++++++++++++\n\n``DebugEvaluation`` is like ``TraceEvaluation``, but instead of displaying expression information, we stop inside a gdb-like debugger, or rather a trepan-like debugger. See https://github.com/Trepan-Debugger for other such gdb-like debuggers. I use this debugger base because I am familiar with the code, and it was written in a way that was intended to be easily adapted to other programming languages.\n\n\n\n\nReplacing Expression values in DebugEvaluation\n++++++++++++++++++++++++++++++++++++++++++++++\n\nYou can change the computation of a value instead of calling a Mathics3 built-in function, or replace the return value after calling a Mathics3 built-in function.\n\nThis is done using the ``set return`` command. Here is an example of that:\n\n.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/traceback-with-Ctrl-C.png\n\n\n\nPost-mortem debugging\n++++++++++++++++++++++\n\n\nTo enter the debugger on an unrecoverable error, use the\n``--post-mortem`` option when invoking ``mathics``::\n\n mathics --post-mortem\n # Find a Python bug in Mathics3 and trigger that.\n # I modified Compress.eval() and added 1/0\n\n In[1]:= Compress[\"abc\"]\n Traceback (most recent call last):\n File \"/tmp/mathicsscript\", line 8, in <module>\n sys.exit(main())\n ^^^^^\n ...\n ZeroDivisionError: division by zero\n Uncaught exception. Entering post-mortem debugger...\n (/tmp/mathics/builtin/compress.py:37 @6): eval\n !! 37 1/0\n R=> (<class 'ZeroDivisionError'>, ZeroDivisionError('division by zero'),\n (Trepan3k:pm) load trepan3k_mathics3\n loaded command: \"mathics3\"\n loaded command: \"mbacktrace\"\n loaded command: \"mup\"\n loaded command: \"printelement\"\n (Trepan3k:pm) mbt -b\n B>0 (0) Compress[expr_, OptionsPattern[Compress]]\n called from file '/tmp/Mathics3/mathics-core/mathics/builtin/compress.py' at line 37\n B>1 (36) Compress[expr_, OptionsPattern[Compress]]\n called from file '/tmp/Mathics3/mathics-core/mathics/builtin/compress.py' at line 37\n (Trepan3k:pm)\n\n\nShowing Tracebacks on long-running operations\n++++++++++++++++++++++++++++++++++++++++++++++\n\nThe debugger (and trepan3k) support signal handling. With this, you can set up a ``SIGINT`` handler.\n\nHere is an example:\n\n.. image:: https://github.com/Mathics3/mathics3-debugger/blob/master/screenshots/traceback-with-Ctrl-C.png\n\n\nWithout the debugger, but with ``trepan3k`` installed, you can use ``Breakpoint[]``, and issue the ``handle`` command. You won't get as nice of a traceback, but it should still work.\n",
"bugtrack_url": null,
"license": null,
"summary": "Mathics3 Debugger Module based on trepan debuggers",
"version": "9.0.0",
"project_urls": {
"Downloads": "https://github.com/Mathics3/Mathics3-Module-trepan/releases",
"Homepage": "https://github.com/Mathics3/Mathics3-Module-trepan"
},
"split_keywords": [
"mathematica",
" wolfram",
" interpreter",
" shell",
" math",
" cas"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "03e4e64c7648c2af28d10a01c173aaeca33c92110848469a2513e877b7a6113c",
"md5": "98a96d4639ba56b5f22eda58e71e4031",
"sha256": "3ada9ae466c29c0fdb8dc8265e2f60c543f847e995bca9374b54b1b391c08eba"
},
"downloads": -1,
"filename": "mathics3_module_trepan-9.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "98a96d4639ba56b5f22eda58e71e4031",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 121972,
"upload_time": "2025-08-30T23:41:08",
"upload_time_iso_8601": "2025-08-30T23:41:08.124672Z",
"url": "https://files.pythonhosted.org/packages/03/e4/e64c7648c2af28d10a01c173aaeca33c92110848469a2513e877b7a6113c/mathics3_module_trepan-9.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1b5f2a236dde13a1d95a73fd836b149991040a44c712bb59f25fbdd152b18f4f",
"md5": "9a2c6de39ea1a2df43f6c3f4e35a1c01",
"sha256": "f6a691178fcbcd2fc45bb47c277458580f755cec5f0f5932f6f47b206bbe9e4a"
},
"downloads": -1,
"filename": "mathics3_module_trepan-9.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9a2c6de39ea1a2df43f6c3f4e35a1c01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27573,
"upload_time": "2025-08-30T23:41:09",
"upload_time_iso_8601": "2025-08-30T23:41:09.625890Z",
"url": "https://files.pythonhosted.org/packages/1b/5f/2a236dde13a1d95a73fd836b149991040a44c712bb59f25fbdd152b18f4f/mathics3_module_trepan-9.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 23:41:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mathics3",
"github_project": "Mathics3-Module-trepan",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mathics3-module-trepan"
}
JSON
