debugpy.txt

*debugpy.txt*	Debug Python code in Neovim
                                                                     *debugpy*

Version: 0.6.0
Author: Alejandro "HiPhish" Sanchez
License: MIT License



==============================================================================
TABLE OF CONTENTS                                           *debugpy-contents*


    1. Introduction ..................................... |debugpy-intro|
    2. Setup ............................................ |debugpy-setup|
    3. Tutorial ......................................... |debugpy-tutorial|
       3.1 Launching a process .......................... |debugpy-launch|
       3.2 Attaching to running process ................. |debugpy-attach|
       3.3 Attaching to remote process .................. |debugpy-ssh|
    4. Using ............................................ |debugpy-using|
       4.1 The Debugpy command .......................... |:Debugpy|
       4.2 Included adapters ............................ |debugpy-adapter|
    5. Recipes  ......................................... |debugpy-recipes|
       5. Django......................................... |debugpy-django|
    6. Debugpy API ...................................... |debugpy-api|
       6.1 Variables .................................... |debugpy-api-vars|
       6.2 Running the debugger ......................... |debugpy-api-run|
       6.3 Custom configuration ......................... |debugpy-api-config|
       6.4 Adapters ..................................... |debugpy-api-adapt|
       6.5 Custom sub-commands .......................... |debugpy-api-subcmd|
    7. Further reading .................................. |debugpy-seealso|


==============================================================================
INTRODUCTION                                                   *debugpy-intro*


Debugpy is a Python debug adapter server which implements the server side of
the Debug Adapter Protocol (DAP).  The nvim-dap plugin (|dap.txt|) is a Neovim
plugin which implements the client side of DAP.

Debugpy.nvim provides the |:Debugpy| command which will create the appropriate
debugger configurations for you and launch the debugger.  You do not have to
set up Debugpy yourself.

Only configuring and launching the debugger is covered, it is up to your own
nvim-dap configuration how to use the debugger once it is running.  This
allows debugpy.nvim to integrate into your existing workflow.


==============================================================================
SETUP AND FIRST STEPS                                          *debugpy-setup*


Install debugpy.nvim like any other Neovim plugin.  Make sure that nvim-dap
(Neovim plugin) and debugpy (Python package) are already working on your
system.

To try out the debugpy Python package you can launch it from your shell, e.g.
like this:
>sh
    python -m debugpy
<


==============================================================================
TUTORIAL                                                    *debugpy-tutorial*

This tutorial will guide you through the process of debugging a simple toy
example.  You will debug a standalone script, a snippet of code, and finally
attach to a running process.  Prerequisite knowledge:

  - How to program in Python
  - Using the nvim-dap plugin for debugging (|dap.txt|)


-------------------------------------------------------------------------------
LAUNCHING A PROCESS                                            *debugpy-launch*
                                                              
We can try debugging a simple Python script.  Create a new Python script file
named `main.py` with the following contents:
>python
    def add(x, y):
        """Recursively add two positive numbers"""
        if y == 0:
            return x
        return add(x + 1, y - 1)


    if __name__ == '__main__':
        x, y = 2, 3
        sum = add(x, y)
        print(f'The sum of {x} and {y} is {sum}.')
<
Make sure the `debugpy` Python package is available in your environment.  Open
the script in Neovim, create a breakpoint (see |dap.set_breakpoint()|)
somewhere (e.g. on line 3) and execute the `:Debugpy module main` command.
The debugger will run the module and stop at your breakpoint.

-------------------------------------------------------------------------------
ATTACHING TO A RUNNING PROCESS                                 *debugpy-attach*

It is possible to attach the debugger to a running process through the
sub-command |:Debugpy-attach|.  We can either write a script that useses the
`debugpy` package internally or we can launch a regular script through the
`debugpy` module.


Using the debugpy package internally ~

Create a new Python module named `server.py` with the following contents:
>python
    import debugpy
    from random import randint
    from time import sleep

    (host, port) = debugpy.listen(5678)

    print(f'Debugpy: Listening on {host}:{port}')

    if __name__ == '__main__':
        while True:
            x, y = randint(1, 10), randint(1, 10)
            print(f'The sum of {x} and {y} is {x + y}.')
            sleep(1)
<
Now launch this script from the shell and you will have an perpetually running
Python process.  Open the script in Neovim (in another shell), set your
breakpoint somewhere inside the loop (e.g. line 13), then execute the
`:Debugpy attach 127.0.0.1 5678` command (you do have to spell out the IP, you
cannot write `localhost`).  The debugger will stop at your breakpoint on the
next loop iteration.


Launching a script through debugpy externally ~

It is also possible to listen for DAP clients without modifying the source
code by launching the Python program through Debugpy itself.  Please refer to
the Debugpy command line reference for more information.  Example:
>sh
    # Debug module 'main' with arguments 'foo' and 'bar'
    python -m debugpy --listen 5678 -m main foo bar
<


-------------------------------------------------------------------------------
ATTACHING TO A REMOTE PROCESS                                     *debugpy-ssh*

It is possible to debug a process running on a remote machine by following the
above instructions as long as you have local port forwarding set up.  When
attaching specify `127.0.0.1` as the host and the forwarded port as the port.

Example:
>sh
    # In one shell connect to the remote machine
    ssh -L 5678:localhost:5678 user@remote
    # Navigate to the project on the remote machine
    cd my-project/
    # Run the program
    python -m debugpy --listen 5678 -m main foo bar
<
You can now use |:Debugpy-attach| to start the debugger on your local machine.
It is important that both machines have the same source code and ideally the
same version of Debugpy.


==============================================================================
USING                                                          *debugpy-using*

There is one new command (|:Debugpy|) which takes a number of arguments and
starts the debugger with an appropriate configuration.  Users who prefer more
direct control can use the included adapters (|debugpy-adapter|) in their
nvim-dap settings.


------------------------------------------------------------------------------
THE DEBUGPY COMMAND                                                 *:Debugpy*

:Debugpy {subcmd} [{arg} ...]
:Debugpy

    Start the debugger with a configuration based on the {subcmd} and its
    arguments.  For convenience if you execute `:Debugpy` without any arguments
    the last invocation will be re-used.  This does not persist between Neovim
    sessions, you have to execute the command at least once with arguments.

    Sub-commands: ~
    The following sub-commands are implemented by default:

       • |:Debugpy-module|   Run a single Python module
       • |:Debugpy-program|  Run a Python program
       • |:Debugpy-code|     Run a code snippet
       • |:Debugpy-attach|   Attach to a running Python process)

    You can add your own sub-commands or modify the existing ones through the
    |debugpy-api|.


:Debugpy module {module} [{arg} ...]                         *:Debugpy-module*

    Debug a specific Python module.  The argument must be given the same way
    as if you were running via `python -m {module}` it from the command line.
    The remaining arguments are passed as command-line arguments to Python.

    Arguments: ~
      • {module}  Name of the module, as given to `import` in Python
      • {arg}...  Command-line arguments to the module

    Example: ~
>vim
        Debugpy module main foo bar
>


:Debugpy program [{program} [{arg} ...]]                    *:Debugpy-program*

    Debug a {program} given its absolute path or path relative to the current
    working directory.  The remaining {arg}s are passed as command-line
    arguments to Python.

    If the {program} is omitted the current file will be used as the program.

    Arguments: ~
      • {program}  Name of the script, as given to the shell
      • {arg}...   Command-line arguments to the script

    Example: ~
>vim
        " Path relative to current working directory
        Debugpy program main.py foo bar

        " Absolute path
        Debugpy program /home/jdoe/projects/my-project/main.py foo bar
>

                   
:Debugpy code {code}                                           *:Debugpy-code*

    Debug the given snippet of source code.  This is rather awkward to use
    from the command line because you need to escape all special characters
    (see |cmdline-special|).

    Arguments: ~
      • {code}  A Python code expression

    Example: ~
>vim
        " A code snippet which jumps straight into a function call
        Debugpy code from\ foo\ import\ bar;\ bar(1,\ 2)
<
    This sub-command is much easier to use in the |debugpy-api|.  Here is the
    same example as above, but using the API instead.

    Example (Vim script): ~
>vim
        let conf = debugpy#configure('code', 'from foo import bar; bar(1, 2)')
        call debugpy#run(conf)
<
    Example (Lua): ~
>lua
        local debugpy = require 'debugpy'
        local conf = debugpy.configure('code', 'from foo import bar; bar(1, 2)')
        debugpy.run(conf)
<


:Debugpy attach {host} {port}                                *:Debugpy-attach*

    Attach to a running Python process which is listening for DAP clients.
    First you need to launch the process in a separate shell and have it
    listen for DAP client connections.  Once you know the {host} and {port} you
    can attach to the process.

    See |debugpy-attach| and |debugpy-ssh| for examples.

    Note ~
        If the process is running on a remote you must be editing the same
        source code as what is running on the remote machine.

    Note ~
        You cannot use `localhost` as the host, you have to spell out the IP
        `127.0.0.1` instead.

    Arguments: ~
      • {host}  IP address of the host machine
      • {port}  Network port on the host machine


------------------------------------------------------------------------------
INCLUDED ADAPTERS                                            *debugpy-adapter*

There are two custom adapters included, see |debugpy.adapter|.  Those two
adapters will be automatically registered.  For convenience the included
adapters will be registered under the following names, unless there already is
an adapter with that name.

    • `python`              |debugpy.adapter.executable| 
    • `debugpy_executable`  |debugpy.adapter.executable| 
    • `debugpy_server`      |debugpy.adapter.executable| 

See |dap-adapter| for more information on adapters.


==============================================================================
RECIPES                                                      *debugpy-recipes*

This is a collection of exceptional of otherwise noteworthy use-cases for
debugging Python.


------------------------------------------------------------------------------
DJANGO                                                        *debugpy-django*

In my experience debugging Django does not work if module reloading is
enabled.  We have to start the server with the `--noreload` option.
>vim
    Debugpy program manage.py runserver --noreload
<


==============================================================================
DEBUGPY API                                                      *debugpy-api*

Debugpy is hackable, you can customize the default of debugpy.nvim by settings
the values within its public module `debugpy`.


------------------------------------------------------------------------------
VARIABLES                                                   *debugpy-api-vars*


                                                            *g:loaded_debugpy*
Set this variable to a |TRUE| value before the plugin has been loaded to
prevent it from loading.  The API will still work, it is lazy-loaded.


------------------------------------------------------------------------------
RUNNING THE DEBUGGER                                         *debugpy-api-run*


                                                               *debugpy.run()*
debugpy.run({config})

    Callback function to run the debugger with the final configuration (see
    |dap-configuration|) which you can replace with your implementation.  The
    default implementations calls |dap.run|.

    Example: Lua
>lua
        -- Your personal default settings
        default = { justMyCode = false }

        -- Implementation which injects your default settings
        require('debugpy').run = function(config)
            local final = vim.tbl_extend('keep', config, default)
            require('dap').run(final)
        end
<
    You can also call this function directly to run the debugger.  Example:
>lua
        local debugpy = require 'debugpy'
        local config = debugpy.configure('attach', '127.0.0.1', '5678')

        debugpy.run(config)
<
                                                               *debugpy#run()*
debugpy#run({config})

    Vim script wrapper around |debugpy.run()|.  Do not overwrite this
    implementation, overwrite |debugpy.run()| in Lua instead.

    Example:
>vim
        let config = debugpy#configure('attach', '127.0.0.1', '5678')
        call debugpy#run(config)
<

------------------------------------------------------------------------------
CUSTOM CONFIGURATION                                      *debugpy-api-config*


                                                         *debugpy.configure()*
                                                         *debugpy#configure()*
debugpy.configure({subcmd}[, {arg} ...])
debugpy#configure({subcmd}[, {arg} ...])

    Takes a subcommand string {subcmd} and any number of string {arg}uments,
    returns the final |dap-configuration|.  The function does check the arity
    of the subcommand, it is an error to supply the wrong number of arguments.

    There is a Lua function and a Vim script function.

    Example: Lua
>lua
        -- Manually configure
        local debugpy = require 'debugpy'
        local config = debugpy.configure('attach', '127.0.0.1, '5678')
<
    Example: Vim script
>vim
        " Manually configure
        let config = debugpy#configure('attach', '127.0.0.1, '5678')
<

------------------------------------------------------------------------------
ADAPTERS                                                 *debugpy-api-adapter*

The following adapters can be used on their own with nvim-dap.


                                                             *debugpy.adapter*
Table containing the adapters.  See also |debugpy-adapter|.


                                                  *debugpy.adapter.executable*
Adapter which launches a Python process.


                                                      *debugpy.adapter.server*
Adapter which attaches to a running Python process.  See |debugpy-ssh| for
instructions.


------------------------------------------------------------------------------
CUSTOM SUB-COMMANDS                                       *debugpy-api-subcmd*
                                                       *debugpy-api-subcommad*

The |:Debugpy| command takes as its first argument a sub-command such as
`module`.  This part of the API allows users to define their own sub-commands
which integrate with the default ones.  Each custom sub-command can have its
own custom completion type.


                                                          *debugpy.subcommand*
                                                        *g:debugpy_subcommand*
This variable is a Lua table or a Vim script dictionary, both can exist at the
same time.  The key is the name of a sub-command, the value is its
specification.

Each specification has the following entries:

    'arity'      Optional, default is `{}`.  A table or dictionary describing
                 the arity of the sub-command.  the entry 'min' is optional
                 and defaults to `0`, the entry 'max' is optional (unlimited
                 upper arity if omitted).  If both values are the same the
                 arity is fixed.  Both values are inclusive.

    'configure'  A function which takes the arguments (as strings) from the
                 sub-command and returns a configuration table according to
                 |dap-configuration|

    'complete'   Optional, default is no completion.  A function which takes a
                 list of strings (current arguments to the subcommand) and a
                 boolean (whether the current argument is incomplete), returns
                 a list of completion candidates.

You can define sub-commands in either Vim script or Lua, both work equally.
If a subcommand in defined in both it is undefined which one will be chosen.

Example: Lua
>lua
    -- Fixed arity
    local code = {
        arity = {min = 1, max = 1},
        configure = function(code)
            return {
                type = 'debugpy_executable',
                request = 'launch',
                code = code
            }
        end
    }

    -- Variable arity, completion function
    local program = {
        -- Default arity is {} which is the same as {min=0, max=nil}
        configure = function(program, ...)
            return {
                type = 'debugpy_executable',
                request = 'launch',
                program = program or '${file}',
                args = {...}
            }
        end,
        completion = function(args, arg_pending)
            -- Only complete the first argument, stop if it is complete
            if #args > 1 or (#args == 1 and not arg_pending) then
                return {}
            end
            -- For a real implementation you need to escape whitespace in the
            -- result entries
            return vim.fn.getcompletion(args[1] or '', 'file')
        end
    }
<


==============================================================================
FURTHER READING                                              *debugpy-seealso*


Offical Debugpy website:
    https://github.com/microsoft/debugpy

Debugpy Wiki:
    https://github.com/microsoft/debugpy/wiki

nvim-dap:
    https://github.com/mfussenegger/nvim-dap

nvim-dap manual:
    |dap.txt|

Official DAP website:
    https://microsoft.github.io/debug-adapter-protocol/


==============================================================================
 vim:tw=78:ts=8:ft=help:norl: