IPython `pdb`
=============

.. image:: https://github.com/gotcha/ipdb/actions/workflows/tests.yml/badge.svg
  :target: https://github.com/gotcha/ipdb/actions/workflows/tests.yml
.. image:: https://codecov.io/gh/gotcha/ipdb/branch/master/graphs/badge.svg?style=flat
  :target: https://codecov.io/gh/gotcha/ipdb?branch=master

Use
---

ipdb exports functions to access the IPython_ debugger, which features
tab completion, syntax highlighting, better tracebacks, better introspection
with the same interface as the `pdb` module.

Example usage:

.. code-block:: python

        import ipdb
        ipdb.set_trace()
        ipdb.set_trace(context=5)  # will show five lines of code
                                   # instead of the default three lines
                                   # or you can set it via IPDB_CONTEXT_SIZE env variable
                                   # or setup.cfg file
        ipdb.pm()
        ipdb.run('x[0] = 3')
        result = ipdb.runcall(function, arg0, arg1, kwarg='foo')
        result = ipdb.runeval('f(1,2) - 3')


Arguments for `set_trace`
+++++++++++++++++++++++++

The `set_trace` function accepts `context` which will show as many lines of code as defined,
and `cond`, which accepts boolean values (such as `abc == 17`) and will start ipdb's
interface whenever `cond` equals to `True`.

Using configuration file
++++++++++++++++++++++++

It's possible to set up context using a `.ipdb` file on your home folder, `setup.cfg`
or `pyproject.toml` on your project folder. You can also set your file location via
env var `$IPDB_CONFIG`. Your environment variable has priority over the home
configuration file, which in turn has priority over the setup config file.
Currently, only context setting is available.

A valid setup.cfg is as follows

::

        [ipdb]
        context=5


A valid .ipdb is as follows

::

        context=5


A valid pyproject.toml is as follows

::

        [tool.ipdb]
        context=5


The post-mortem function, ``ipdb.pm()``, is equivalent to the magic function
``%debug``.

.. _IPython: http://ipython.org

If you install ``ipdb`` with a tool which supports ``setuptools`` entry points,
an ``ipdb`` script is made for you. You can use it to debug your python 2 scripts like

::

        $ bin/ipdb mymodule.py

And for python 3

::

        $ bin/ipdb3 mymodule.py

Alternatively with Python 2.7 only, you can also use

::

        $ python -m ipdb mymodule.py

You can also enclose code with the ``with`` statement to launch ipdb if an exception is raised:

.. code-block:: python

        from ipdb import launch_ipdb_on_exception

        with launch_ipdb_on_exception():
            [...]

.. warning::
   Context managers were introduced in Python 2.5.
   Adding a context manager implies dropping Python 2.4 support.
   Use ``ipdb==0.6`` with 2.4.

Or you can use ``iex`` as a function decorator to launch ipdb if an exception is raised:

.. code-block:: python

        from ipdb import iex

        @iex
        def main():
            [...]

.. warning::
   Using ``from future import print_function`` for Python 3 compat implies dropping Python 2.5 support.
   Use ``ipdb<=0.8`` with 2.5.

Issues with ``stdout``
----------------------

Some tools, like ``nose`` fiddle with ``stdout``.

Until ``ipdb==0.9.4``, we tried to guess when we should also
fiddle with ``stdout`` to support those tools.
However, all strategies tried until 0.9.4 have proven brittle.

If you use ``nose`` or another tool that fiddles with ``stdout``, you should
explicitly ask for ``stdout`` fiddling by using ``ipdb`` like this

.. code-block:: python

        import ipdb
        ipdb.sset_trace()
        ipdb.spm()

        from ipdb import slaunch_ipdb_on_exception
        with slaunch_ipdb_on_exception():
            [...]


Development
-----------

``ipdb`` source code and tracker are at https://github.com/gotcha/ipdb.

Pull requests should take care of updating the changelog ``HISTORY.txt``.

Under the unreleased section, add your changes and your username.

Manual testing
++++++++++++++

To test your changes, make use of ``manual_test.py``. Create a virtual environment,
install IPython and run ``python manual_test.py`` and check if your changes are in effect.
If possible, create automated tests for better behaviour control.

Automated testing
+++++++++++++++++

To run automated tests locally, create a virtual environment, install `coverage`
and run `coverage run setup.py test`.

Third-party support
-------------------

pytest
+++++++
pytest_ supports a ``--pdb`` option which can run ``ipdb`` /
``IPython.terminal.debugger:TerminalPdb`` on ``Exception`` and ``breakpoint()``:

.. code:: bash

    pytest --pdb --pdbcls=IPython.terminal.debugger:TerminalPdb -v ./test_example.py

You don't need to specify ``--pdbcls`` for every ``pytest`` invocation 
if you add ``addopts`` to ``pytest.ini`` or ``pyproject.toml``.

``pytest.ini``:

.. code:: bash

  [tool.pytest.ini_options]
  addopts = "--pdbcls=IPython.terminal.debugger:TerminalPdb"

``pyproject.toml``:

.. code:: yml

  [tool.pytest.ini_options]
  addopts = "--pdbcls=IPython.terminal.debugger:TerminalPdb"


.. _pytest: https://pypi.python.org/pypi/pytest