Metadata-Version: 2.1
Name: ipdbx
Version: 0.0.1
Summary: IPython-enabled pdb with extra functionality and customisation
Home-page: https://github.com/giladbarnea/ipdbx
Author: Gilad Barnea
Author-email: giladbrn@gmail.com
License: BSD
Description: IPython `pdb` 3
        ===============
        ipdbx_ is an improved version of ipdb_ that provides extra functionality and customisation.
        
        Python 2 support has been dropped to make way for new features.
        
        Use
        ---
        
        ``ipdbx`` 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 ipdbx
                ipdbx.set_trace()
                ipdbx.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
                ipdbx.set_trace(pretrace='/useful/debug/tools.py')  # can be set via IPDB_PRETRACE
                                                                   # env variable. pretrace also
                                                                   # accepts the same type of args
                                                                   # as ipdbx.run(), ipdbx.runcall()
                                                                   # and ipdbx.runeval()
                ipdbx.pm()
                ipdbx.run('x[0] = 3')
                result = ipdbx.runcall(function, arg0, arg1, kwarg='foo')
                result = ipdbx.runeval('f(1,2) - 3')
        
        
        
        Patching ``sys.breakpointhook`` to call ``ipdbx`` when calling ``breakpoint()``:
        
        .. code-block:: python
        
            import ipdbx
            import sys
            sys.breakpointhook = ipdbx.set_trace
        
            # You can also call set_trace with default arguments, likewise:
        
            from functools import partial
            sys.breakpointhook = partial(ipdbx.set_trace, context=30, pretrace='/my/favourite/things.py')
        
        Arguments for ``ipdbx.set_trace``
        +++++++++++++++++++++++++++++++++
        
        The ``ipdbx.set_trace`` function accepts the following optional parameters:
        
        * ``frame``, a `frame` object (defaults to last);
        * ``context: int``, which will show as many lines of code as defined;
        * ``cond: bool``, which accepts boolean values (such as ``abc == 17``) and will start ipdb's interface whenever ``cond`` equals to ``True``;
        * ``pretrace``, which accepts a file path, a python statement string, or a code object, which it will execute immediately before starting the debugger.
        
        
        Using configuration file
        ++++++++++++++++++++++++
        
        It's possible to set up context using a `.ipdb` file on your home folder or `setup.cfg`
        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
                pretrace=./file.py
        
        
        A valid .ipdb is as follows
        
        ::
        
                context=5
                pretrace="import inspect"
        
        
        The post-mortem function, ``ipdbx.pm()``, is equivalent to the magic function
        ``%debug``.
        
        .. _IPython: http://ipython.org
        .. _ipdb: https://github.com/gotcha/ipdb
        .. _ipdbx: https://github.com/giladbarnea/ipdbx
        
        If you install ``ipdbx`` with a tool which supports ``setuptools`` entry points,
        an ``ipdbx`` script is made for you. You can use it to debug your python scripts like
        
        ::
        
                $ bin/ipdbx mymodule.py
        
        You can also enclose code with the ``with`` statement to launch ipdb if an exception is raised:
        
        .. code-block:: python
        
                from ipdbx import launch_ipdb_on_exception
        
                with launch_ipdb_on_exception():
                    ...
        
        
        
        Issues with ``stdout``
        ----------------------
        
        Some tools, like ``nose`` fiddle with ``stdout``.
        
        If you use a tool that fiddles with ``stdout``, you should
        explicitly ask for ``stdout`` fiddling by using ``ipdbx`` like this
        
        .. code-block:: python
        
                import ipdbx
                ipdbx.sset_trace()
                ipdbx.spm()
        
                from ipdbx import slaunch_ipdb_on_exception
                with slaunch_ipdb_on_exception():
                    ...
        
        
        Development
        -----------
        
        ``ipdbx`` source code and tracker are at https://github.com/giladbarnea/ipdbx.
        
        Pull requests should take care of updating the changelog ``HISTORY.txt``.
        
        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.
        
        
Keywords: pdb ipython ipdb ipdbx ipdb-extended
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Debuggers
Classifier: License :: OSI Approved :: BSD License
Requires-Python: >=3.6
Provides-Extra: dev
