ipdb 0.13.13
IPython-enabled pdb
License: BSD
Requires Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
Keywords: pdb ipython

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

.. image:: https://travis-ci.org/gotcha/ipdb.png?branch=master
  :target: https://travis-ci.org/gotcha/ipdb
.. 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
-------------------

Products.PDBDebugMode
+++++++++++++++++++++

Zope2 Products.PDBDebugMode_ uses ``ipdb``, if available, in place of ``pdb``.

.. _Products.PDBDebugMode: http://pypi.python.org/pypi/Products.PDBDebugMode

iw.debug
++++++++

iw.debug_ allows you to trigger an ``ipdb`` debugger on any published object
of a Zope2 application.

.. _iw.debug: http://pypi.python.org/pypi/iw.debug

ipdbplugin
++++++++++

ipdbplugin_ is a nose_ test runner plugin that also uses the IPython debugger
instead of ``pdb``. (It does not depend on ``ipdb`` anymore).

.. _ipdbplugin: http://pypi.python.org/pypi/ipdbplugin
.. _nose: http://readthedocs.org/docs/nose


Changelog
=========

0.13.13 (2023-03-09)
--------------------

- Use context manager for opening toml config
  [andrewzwicky]


0.13.12 (2023-03-09)
--------------------

- Modify tests to test 3.11 separately from earlier python versions.
  [andrewzwicky]


0.13.11 (2022-12-13)
--------------------

- Better exception handling when looking for config.
  [bignose-debian]


0.13.10 (2022-12-13)
--------------------

- Better toml support (use tomlib for 3.11, tomli for 3.6 to 3.10).
  [salty-horse, mgorny]

- Minimal PEP 517 support.
  [cpcloud]

- 3.11 support for run as module and run as script.
  [nphilipp, gotcha]

- Based on OSV:PYSEC-2022-12 change ipython dependencies,
  for users using python 3.6, install 7.16.3 <= IPython < 7.17.0,
  for users using python>3.6, install IPython >= 7.31.1.
  [malkstar]


0.13.9 (2021-06-02)
-------------------

- Fix again when `pyproject.toml` does not contain `tool` section.
  [markab108]


0.13.8 (2021-05-26)
-------------------

- Fix when `pyproject.toml` does not contain `tool` section.
  [anjos]

- Add the convenience function ``iex()``.
  [alanbernstein]


0.13.7 (2021-03-16)
-------------------

- Do not instantiate IPython on import
  [adamchainz]


0.13.6 (2021-03-08)
-------------------

- Fix broken parsing of pyproject.toml
  [alexandrebarbaruiva]


0.13.5 (2021-03-02)
-------------------

- Add support for pyproject.toml as configuration file
  [alexandrebarbaruiva]

- For users using python 3.4, install 6.0.0 <= IPython < 7.0.0,
  for users using python 3.5, install 7.0.0 <= IPython < 7.10.0,
  for users using python 3.6, install 7.10.0 <= IPython < 7.17.0,
  for users using python>3.6, install IPython >= 7.17.0.
  [d1618033]


0.13.4 (2020-10-01)
-------------------

- Add '-m' option
  [mrmino]


0.13.3 (2020-06-23)
-------------------

- Allow runcall, runeval to also use set context value
  [meowser]

- Add condition argument to set_trace
  [alexandrebarbaruiva]


0.13.2 (2020-03-03)
-------------------

- Remove leftover debug code
  [gotcha]


0.13.1 (2020-02-28)
-------------------

- Fix when no configuration file
  [gotcha]


0.13.0 (2020-02-28)
-------------------

- Add option to set context via environment variable or configuration file
  [alexandrebarbaruiva]


0.12.3 (2019-12-03)
-------------------

- Fix version in usage
  [gotcha]


0.12.2 (2019-07-30)
-------------------

- Avoid emitting term-title bytes
  [steinnes]


0.12.1 (2019-07-26)
-------------------

- Fix --help 
  [native-api]


0.12 (2019-03-20)
-----------------

- Drop support for Python 3.3.x
  [bmw]
- Stop deprecation warnings from being raised when IPython >= 5.1 is used.
  Support for IPython < 5.1 has been dropped.
  [bmw]


0.11 (2018-02-15)
-----------------

- Simplify loading IPython and getting information from it.
  Drop support for python 2.6
  Drop support for IPython < 5.0.0
  [takluyver]


0.10.3 (2017-04-22)
-------------------

- For users using python 2.6, do not install IPython >= 2.0.0.
  And for users using python 2.7, do not install IPython >= 6.0.0.
  [vphilippon]
- Drop support for python 3.2.
  [vphilippon]
- Command line usage consistent with pdb - Add argument commands
  [zvodd]


0.10.2 (2017-01-25)
-------------------

- Ask IPython which debugger class to use.
  Closes https://github.com/gotcha/ipdb/issues/105
  [gnebehay, JBKahn] 

- ipdb.set_trace() does not ignore context arg anymore.
  Closes https://github.com/gotcha/ipdb/issues/93.
  [gnebehay, Garrett-R]


0.10.1 (2016-06-14)
-------------------

- Support IPython 5.0.
  [ngoldbaum]


0.10.0 (2016-04-29)
-------------------

- Stop trying to magically guess when stdout needs to be captured.
  Like needed by `nose`.
  Rather, provide a set of function that can be called explicitely when needed.
  [gotcha]

- drop support of IPython before 0.10.2


0.9.4 (2016-04-29)
------------------

- Fix Restart error when using `python -m ipdb`
  Closes https://github.com/gotcha/ipdb/issues/93.
  [gotcha]


0.9.3 (2016-04-15)
------------------

- Don't require users to pass a traceback to post_mortem.
  [Wilfred]


0.9.2 (2016-04-15)
------------------

- Closes https://github.com/gotcha/ipdb/issues/93.
  [gotcha]


0.9.1 (2016-04-12)
------------------

- Reset ``sys.modules['__main__']`` to original value.
  Closes https://github.com/gotcha/ipdb/issues/85
  [gotcha]

- Fix support of IPython versions 0.x
  [asivokon]


0.9.0 (2016-02-22)
------------------

- Switch to revised BSD license (with approval of all contributors).
  Closes https://github.com/gotcha/ipdb/issues/68
  [lebedov, gotcha]

0.8.3 (2016-02-17)
------------------

- Don't pass sys.argv to IPython for configuration.
  [emulbreh]


0.8.2 (2016-02-15)
------------------

- Fix lexical comparison for version numbers.
  [sas23]

- Allow configuring how many lines of code context are displayed
  by `set_trace`
  [JamshedVesuna]

- If an instance of IPython is already running its configuration will be
  loaded.
  [IxDay]


0.8.1 (2015-06-03)
------------------

- Make Nose support less invasive.
  Closes https://github.com/gotcha/ipdb/issues/52
  Closes https://github.com/gotcha/ipdb/issues/31
  [blink1073, gotcha]

- Fix for post_mortem in context manager.
  Closes https://github.com/gotcha/ipdb/issues/20
  [omergertel]


0.8 (2013-09-19)
----------------

- More Python 3 compatibility; implies dropping Python 2.5 support.
  Closes https://github.com/gotcha/ipdb/issues/37
  [gotcha]


0.7.1 (2013-09-19)
------------------

- IPython 1.0 compatibility.
  Closes https://github.com/gotcha/ipdb/issues/44
  [pgularski]

- Index into version_info in setup.py for Python 2.6 compatibility.
  [kynan]

- Add Travis CI configuration.
  [kynan]

0.7 (2012-07-06)
----------------

- Add ``launch_ipdb_on_exception`` context manager. Implies dropping Python 2.4 support.
  [Psycojoker]

- Wrap sys.excepthook only once.
  [marciomazza]

- Add GPL file and refer in headers.
  [stan3]

- Python 3 support.
  [Piet Delport]

- Basic tests.
  [msabramo]

- Added the functions ``runcall``, ``runeval`` and ``run``.
  [dimasad]


0.6.1 (2011-10-17)
------------------

- State dependency on IPython later or equal to 0.10.
  [gotcha]


0.6 (2011-09-01)
----------------

- Add setuptools ``console_scripts`` entry point.
  [akrito, gotcha] 

- Nose support.
  Closes https://github.com/gotcha/ipdb/issues/8
  [akaihola, gotcha]


0.5 (2011-08-05)
----------------

- IPython 0.11 support.
  [lebedov]


0.4 (2011-06-13)
----------------

- When used from IPython, use its colors.
  Closes https://github.com/gotcha/ipdb/issues/1
  [gotcha]

- Fixed errors when exiting with "q". 
  [gotcha]

- Allow use of ``python -m ipdb mymodule.py``.
  Python 2.7 only. 
  Closes https://github.com/gotcha/ipdb/issues/3 
  [gotcha]

- Fixed post_mortem when the traceback is None.
  [maurits]


0.3 (2011-01-16)
----------------

- Add ``post_mortem()`` for ``Products.PDBDebugMode`` support.
  [Jean Jordaan]

- Moved to github.com.


0.2 (2010-10-20)
----------------

- Added ``pm()``.
  [Paulo Benedict Ang]


0.1 (2010-04-26)
----------------

- First "non dev" release.