Skip to content

Commit 833b044

Browse files
mfusseneggermfussenegger
committed
Add namespace to all type definitions; regen docs
1 parent ede25d1 commit 833b044

File tree

4 files changed

+97
-81
lines changed

4 files changed

+97
-81
lines changed

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,14 @@ Settings][debugpy_wiki]
184184
A test runner building upon vim-test with nvim-dap support.
185185
Aims to work for all python runners.
186186

187+
## Development
188+
189+
- Generate docs using [vimcats][vimcats]:
190+
191+
```bash
192+
vimcats -f -t lua/dap-python.lua > doc/dap-python.txt
193+
```
194+
187195

188196
[1]: https://github.com/mfussenegger/nvim-dap
189197
[3]: https://github.com/microsoft/debugpy
@@ -192,3 +200,4 @@ Aims to work for all python runners.
192200
[6]: https://github.com/junegunn/vim-plug
193201
[7]: https://github.com/wbthomason/packer.nvim
194202
[debugpy_wiki]: https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings
203+
[vimcats]: https://github.com/mrcjkb/vimcats

‎doc/dap-python.txt‎

Lines changed: 49 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
================================================================================
1+
==============================================================================
22
Python extension for nvim-dap *dap-python*
33

44
M.test_runner *dap-python.test_runner*
55
Test runner to use by default.
6-
The default value is dynamic and depends on `pytest.ini`, `manage.py` or `pyproject.toml` markers.
7-
If none are found "unittest" is used. See |dap-python.test_runners|
6+
The default value is dynamic and depends on `pytest.ini` or `manage.py` markers.
7+
If neither is found "unittest" is used. See |dap-python.test_runners|
88
Override this to set a different runner:
99
```
1010
require('dap-python').test_runner = "pytest"
1111
```
1212

1313
Type: ~
14-
((string|fun():string)) name of the test runner
14+
(string|fun():string) name of the test runner
1515

1616

1717
M.resolve_python *dap-python.resolve_python*
@@ -30,101 +30,99 @@ M.test_runners *dap-python.test_runners*
3030
module name to run and its arguments. See |dap-python.TestRunner|
3131

3232
Type: ~
33-
(table<string,TestRunner>)
33+
(table<string,dap-python.TestRunner>)
3434

3535

36-
M.setup({adapter_python_path}, {opts}) *dap-python.setup*
36+
M.setup({python_path}, {opts?}) *dap-python.setup*
3737
Register the python debug adapter
3838

3939
Parameters: ~
40-
{adapter_python_path} (string|nil) Path to the python interpreter. Path must be absolute or in $PATH and needs to have the debugpy package installed. Default is `python3`
41-
{opts} (SetupOpts|nil) See |dap-python.SetupOpts|
40+
{python_path} (string|nil) Path to the python interpreter. Path must be absolute or in $PATH and needs to have the debugpy package installed. Default is `python3`
41+
{opts?} (dap-python.setup.opts) See |dap-python.setup.opts|
4242

4343

44-
M.test_class({opts}) *dap-python.test_class*
44+
M.test_class({opts?}) *dap-python.test_class*
4545
Run test class above cursor
4646

4747
Parameters: ~
48-
{opts} (DebugOpts) See |dap-python.DebugOpts|
48+
{opts?} (dap-python.debug_opts) See |dap-python.debug_opts|
4949

5050

51-
M.test_method({opts}) *dap-python.test_method*
51+
M.test_method({opts?}) *dap-python.test_method*
5252
Run the test method above cursor
5353

5454
Parameters: ~
55-
{opts} (DebugOpts) See |dap-python.DebugOpts|
55+
{opts?} (dap-python.debug_opts) See |dap-python.debug_opts|
5656

5757

58-
M.debug_selection({opts}) *dap-python.debug_selection*
58+
M.debug_selection({opts?}) *dap-python.debug_selection*
5959
Debug the selected code
6060

6161
Parameters: ~
62-
{opts} (DebugOpts)
62+
{opts?} (dap-python.debug_opts)
6363

6464

65-
PathMapping *dap-python.PathMapping*
65+
dap-python.PathMapping *dap-python.PathMapping*
6666

6767
Fields: ~
6868
{localRoot} (string)
6969
{remoteRoot} (string)
7070

7171

72-
DebugpyConfig *dap-python.DebugpyConfig*
72+
dap-python.Config *dap-python.Config*
7373

7474
Fields: ~
75-
{django} (boolean|nil) Enable django templates. Default is `false`
76-
{gevent} (boolean|nil) Enable debugging of gevent monkey-patched code. Default is `false`
77-
{jinja} (boolean|nil) Enable jinja2 template debugging. Default is `false`
78-
{justMyCode} (boolean|nil) Debug only user-written code. Default is `true`
79-
{pathMappings} (PathMapping[]|nil) Map of local and remote paths.
80-
{pyramid} (boolean|nil) Enable debugging of pyramid applications
81-
{redirectOutput} (boolean|nil) Redirect output to debug console. Default is `false`
82-
{showReturnValue} (boolean|nil) Shows return value of function when stepping
83-
{sudo} (boolean|nil) Run program under elevated permissions. Default is `false`
75+
{django} (boolean|nil) Enable django templates. Default is `false`
76+
{gevent} (boolean|nil) Enable debugging of gevent monkey-patched code. Default is `false`
77+
{jinja} (boolean|nil) Enable jinja2 template debugging. Default is `false`
78+
{justMyCode} (boolean|nil) Debug only user-written code. Default is `true`
79+
{pathMappings} (dap-python.PathMapping[]|nil) Map of local and remote paths.
80+
{pyramid} (boolean|nil) Enable debugging of pyramid applications
81+
{redirectOutput} (boolean|nil) Redirect output to debug console. Default is `false`
82+
{showReturnValue} (boolean|nil) Shows return value of function when stepping
83+
{sudo} (boolean|nil) Run program under elevated permissions. Default is `false`
8484

8585

86-
DebugpyLaunchConfig *dap-python.DebugpyLaunchConfig*
87-
: DebugpyConfig
86+
*dap-python.LaunchConfig*
87+
dap-python.LaunchConfig : dap-python.Config
8888

8989
Fields: ~
90-
{module} (string|nil) Name of the module to debug
91-
{program} (string|nil) Absolute path to the program
92-
{code} (string|nil) Code to execute in string form
93-
{python} (string[]|nil) Path to python executable and interpreter arguments
94-
{args} (string[]|nil) Command line arguments passed to the program
95-
{console} (DebugpyConsole) See |dap-python.DebugpyConsole|
96-
{cwd} (string|nil) Absolute path to the working directory of the program being debugged.
97-
{env} (table|nil) Environment variables defined as key value pair
98-
{stopOnEntry} (boolean|nil) Stop at first line of user code.
90+
{module} (string|nil) Name of the module to debug
91+
{program} (string|nil) Absolute path to the program
92+
{code} (string|nil) Code to execute in string form
93+
{python} (string[]|nil) Path to python executable and interpreter arguments
94+
{args} (string[]|nil) Command line arguments passed to the program
95+
{console} (dap-python.console) See |dap-python.console|
96+
{cwd} (string|nil) Absolute path to the working directory of the program being debugged.
97+
{env} (table|nil) Environment variables defined as key value pair
98+
{stopOnEntry} (boolean|nil) Stop at first line of user code.
9999

100100

101-
DebugOpts *dap-python.DebugOpts*
102-
101+
dap-python.debug_opts *dap-python.debug_opts*
103102

104103
Fields: ~
105-
{console} (DebugpyConsole) See |dap-python.DebugpyConsole|
106-
{test_runner} ("unittest"|"pytest"|"django"|string) name of the test runner. Default is |dap-python.test_runner|
107-
{config} (DebugpyConfig) Overrides for the configuration
108-
104+
{console?} (dap-python.console)
105+
{test_runner?} ()
109106

110-
SetupOpts *dap-python.SetupOpts*
111107

108+
dap-python.setup.opts *dap-python.setup.opts*
112109

113110
Fields: ~
114-
{include_configs} (boolean) Add default configurations
115-
{console} (DebugpyConsole) See |dap-python.DebugpyConsole|
116-
{pythonPath} (string|nil) Path to python interpreter. Uses interpreter from `VIRTUAL_ENV` environment variable or `adapter_python_path` by default
111+
{include_configs?} (boolean) Add default configurations
112+
{console?} (dap-python.console)
113+
{pythonPath?} (string)
114+
Path to python interpreter. Uses interpreter from `VIRTUAL_ENV` environment
115+
variable or `python_path` by default
117116

118117

119-
TestRunner *TestRunner*
120-
string, methodname: string): string module, string[] args
118+
dap-python.TestRunner *dap-python.TestRunner*
119+
A function receiving classname and methodname; must return module to run and its arguments
121120

122121
Type: ~
123-
fun(classname:
124-
122+
fun
125123

126-
DebugpyConsole *DebugpyConsole*
127124

125+
dap-python.console *dap-python.console*
128126

129127
Type: ~
130128
"internalConsole"|"integratedTerminal"|"externalTerminal"|nil

‎lemmy.sh‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎lua/dap-python.lua‎

Lines changed: 39 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ local uv = vim.uv or vim.loop
1111
--- ```
1212
--- require('dap-python').test_runner = "pytest"
1313
--- ```
14-
---@type (string|fun():string) name of the test runner
14+
---@type string|fun():string name of the test runner
1515
M.test_runner = nil
1616

1717

@@ -26,7 +26,7 @@ M.resolve_python = nil
2626
--- Built-in are test runners for unittest, pytest and django.
2727
--- The key is the test runner name, the value a function to generate the
2828
--- module name to run and its arguments. See |dap-python.TestRunner|
29-
---@type table<string, TestRunner>
29+
---@type table<string, dap-python.TestRunner>
3030
M.test_runners = {}
3131

3232

@@ -90,6 +90,7 @@ local function default_runner()
9090
end
9191

9292

93+
---@return string|nil
9394
local get_python_path = function()
9495
local venv_path = os.getenv('VIRTUAL_ENV')
9596
if venv_path then
@@ -123,8 +124,11 @@ local get_python_path = function()
123124
end
124125

125126

127+
---@param config dap-python.Config|dap-python.LaunchConfig
128+
---@param on_config fun(config: dap-python.Config)
126129
local enrich_config = function(config, on_config)
127130
if not config.pythonPath and not config.python then
131+
---@diagnostic disable-next-line: inject-field
128132
config.pythonPath = get_python_path()
129133
end
130134
on_config(config)
@@ -164,6 +168,7 @@ local function flatten(...)
164168
if vim.iter then
165169
return vim.iter(values):flatten(2):totable()
166170
end
171+
---@diagnostic disable-next-line: deprecated
167172
return vim.tbl_flatten(values)
168173
end
169174

@@ -202,11 +207,11 @@ end
202207

203208

204209
--- Register the python debug adapter
205-
---@param adapter_python_path string|nil Path to the python interpreter. Path must be absolute or in $PATH and needs to have the debugpy package installed. Default is `python3`
206-
---@param opts SetupOpts|nil See |dap-python.SetupOpts|
207-
function M.setup(adapter_python_path, opts)
210+
---@param python_path string|nil Path to the python interpreter. Path must be absolute or in $PATH and needs to have the debugpy package installed. Default is `python3`
211+
---@param opts? dap-python.setup.opts See |dap-python.setup.opts|
212+
function M.setup(python_path, opts)
208213
local dap = load_dap()
209-
adapter_python_path = adapter_python_path and vim.fn.expand(vim.fn.trim(adapter_python_path), true) or 'python3'
214+
python_path = python_path and vim.fn.expand(vim.fn.trim(python_path), true) or 'python3'
210215
opts = vim.tbl_extend('keep', opts or {}, default_setup_opts)
211216
dap.adapters.python = function(cb, config)
212217
if config.request == 'attach' then
@@ -226,7 +231,7 @@ function M.setup(adapter_python_path, opts)
226231
else
227232
cb({
228233
type = 'executable';
229-
command = adapter_python_path;
234+
command = python_path;
230235
args = { '-m', 'debugpy.adapter' };
231236
enrich_config = enrich_config;
232237
options = {
@@ -317,6 +322,7 @@ local function reverse(list)
317322
end
318323

319324

325+
---@private
320326
---@param source string|integer
321327
---@param subject "function"|"class"
322328
---@param end_row integer? defaults to cursor
@@ -392,7 +398,7 @@ end
392398

393399
---@param classnames string[]
394400
---@param methodname string?
395-
---@param opts DebugOpts
401+
---@param opts dap-python.debug_opts
396402
local function trigger_test(classnames, methodname, opts)
397403
local test_runner = opts.test_runner or (M.test_runner or default_runner)
398404
if type(test_runner) == "function" then
@@ -420,7 +426,7 @@ end
420426

421427

422428
--- Run test class above cursor
423-
---@param opts? DebugOpts See |dap-python.DebugOpts|
429+
---@param opts? dap-python.debug_opts See |dap-python.debug_opts|
424430
function M.test_class(opts)
425431
opts = vim.tbl_extend('keep', opts or {}, default_test_opts)
426432
local candidates = M._get_nodes(0, "class")
@@ -452,7 +458,7 @@ end
452458

453459

454460
--- Run the test method above cursor
455-
---@param opts? DebugOpts See |dap-python.DebugOpts|
461+
---@param opts? dap-python.debug_opts See |dap-python.debug_opts|
456462
function M.test_method(opts)
457463
opts = vim.tbl_extend('keep', opts or {}, default_test_opts)
458464
local functions = M._get_nodes(0, "function")
@@ -471,6 +477,8 @@ end
471477
--
472478
-- >>> remove_indent({' print(10)', ' if True:', ' print(20)'})
473479
-- {'print(10)', 'if True:', ' print(20)'}
480+
---@param lines string[]
481+
---@return string[]
474482
local function remove_indent(lines)
475483
local offset = nil
476484
for _, line in ipairs(lines) do
@@ -489,7 +497,7 @@ end
489497

490498

491499
--- Debug the selected code
492-
---@param opts? DebugOpts
500+
---@param opts? dap-python.debug_opts
493501
function M.debug_selection(opts)
494502
opts = vim.tbl_extend('keep', opts or {}, default_test_opts)
495503
local start_row, _ = unpack(api.nvim_buf_get_mark(0, '<'))
@@ -507,47 +515,52 @@ end
507515

508516

509517

510-
---@class PathMapping
518+
---@class dap-python.PathMapping
511519
---@field localRoot string
512520
---@field remoteRoot string
513521

514522

515-
---@class DebugpyConfig
523+
---@class dap-python.Config
516524
---@field django boolean|nil Enable django templates. Default is `false`
517525
---@field gevent boolean|nil Enable debugging of gevent monkey-patched code. Default is `false`
518526
---@field jinja boolean|nil Enable jinja2 template debugging. Default is `false`
519527
---@field justMyCode boolean|nil Debug only user-written code. Default is `true`
520-
---@field pathMappings PathMapping[]|nil Map of local and remote paths.
528+
---@field pathMappings dap-python.PathMapping[]|nil Map of local and remote paths.
521529
---@field pyramid boolean|nil Enable debugging of pyramid applications
522530
---@field redirectOutput boolean|nil Redirect output to debug console. Default is `false`
523531
---@field showReturnValue boolean|nil Shows return value of function when stepping
524532
---@field sudo boolean|nil Run program under elevated permissions. Default is `false`
525533

526-
---@class DebugpyLaunchConfig : DebugpyConfig
534+
535+
---@class dap-python.LaunchConfig : dap-python.Config
527536
---@field module string|nil Name of the module to debug
528537
---@field program string|nil Absolute path to the program
529538
---@field code string|nil Code to execute in string form
530539
---@field python string[]|nil Path to python executable and interpreter arguments
531540
---@field args string[]|nil Command line arguments passed to the program
532-
---@field console DebugpyConsole See |dap-python.DebugpyConsole|
541+
---@field console dap-python.console See |dap-python.console|
533542
---@field cwd string|nil Absolute path to the working directory of the program being debugged.
534543
---@field env table|nil Environment variables defined as key value pair
535544
---@field stopOnEntry boolean|nil Stop at first line of user code.
536545

537546

538-
---@class DebugOpts
539-
---@field console DebugpyConsole See |dap-python.DebugpyConsole|
540-
---@field test_runner "unittest"|"pytest"|"django"|string name of the test runner. Default is |dap-python.test_runner|
541-
---@field config DebugpyConfig Overrides for the configuration
547+
---@class dap-python.debug_opts
548+
---@field console? dap-python.console
549+
---@field test_runner? "unittest"|"pytest"|"django"|string name of the test runner
550+
---@field config? dap-python.Config Overrides for the configuration
542551

543-
---@class SetupOpts
544-
---@field include_configs boolean Add default configurations
545-
---@field console DebugpyConsole See |dap-python.DebugpyConsole|
546-
---@field pythonPath string|nil Path to python interpreter. Uses interpreter from `VIRTUAL_ENV` environment variable or `adapter_python_path` by default
552+
---@class dap-python.setup.opts
553+
---@field include_configs? boolean Add default configurations
554+
---@field console? dap-python.console
555+
---
556+
--- Path to python interpreter. Uses interpreter from `VIRTUAL_ENV` environment
557+
--- variable or `python_path` by default
558+
---@field pythonPath? string
547559

548560

549-
---@alias TestRunner fun(classname: string|string[], methodname: string?):string, string[]
561+
--- A function receiving classname and methodname; must return module to run and its arguments
562+
---@alias dap-python.TestRunner fun(classname: string|string[], methodname: string?):string, string[]
550563

551-
---@alias DebugpyConsole "internalConsole"|"integratedTerminal"|"externalTerminal"|nil
564+
---@alias dap-python.console 'internalConsole'|'integratedTerminal'|'externalTerminal'|nil
552565

553566
return M

0 commit comments

Comments
 (0)