Add docs and examples for the '--pdbcls' option

[nicoddemus]

From #647 (comment).

[recursivelycurious]

@nicoddemus happy to tackle this if no one else is working on it per your comment on #2324 -- note I'm still open to implementing that if we think its worth doing.

[nicoddemus]

@recursivelycurious please go ahead, thanks!

[recursivelycurious]

@nicoddemus will do :) feel free to assign it to me if that is part of the workflow.

[nicoddemus]

Thanks, we usually do not assign, you can go ahead and open the PR when you can. 👍

[blueyed]

JFI: by now attribute access also works, e.g. --pdbcls ipdb:__main__.debugger_cls.

[nnrepos]

@nicoddemus could you reference where in the code --pdbcls is implemented, or an example where it can be used? Thanks

[nicoddemus]

@nnrepos sure, here's the option is defined:

pytest/src/_pytest/debugging.py

Lines 32 to 39 in 35800a2

	group._addoption(
	"--pdbcls",
	dest="usepdb_cls",
	metavar="modulename:classname",
	type=_validate_usepdb_cls,
	help="start a custom interactive Python debugger on errors. "
	"For example: --pdbcls=IPython.terminal.debugger:TerminalPdb",
	)

And here the option (the attribute usepdb_cls) is used:

pytest/src/_pytest/debugging.py

Lines 89 to 121 in 35800a2

	def _import_pdb_cls(cls, capman):
	if not cls._config:
	# Happens when using pytest.set_trace outside of a test.
	return pdb.Pdb
	usepdb_cls = cls._config.getvalue("usepdb_cls")
	if cls._wrapped_pdb_cls and cls._wrapped_pdb_cls[0] == usepdb_cls:
	return cls._wrapped_pdb_cls[1]
	if usepdb_cls:
	modname, classname = usepdb_cls
	try:
	__import__(modname)
	mod = sys.modules[modname]
	# Handle --pdbcls=pdb:pdb.Pdb (useful e.g. with pdbpp).
	parts = classname.split(".")
	pdb_cls = getattr(mod, parts[0])
	for part in parts[1:]:
	pdb_cls = getattr(pdb_cls, part)
	except Exception as exc:
	value = ":".join((modname, classname))
	raise UsageError(
	"--pdbcls: could not import {!r}: {}".format(value, exc)
	)
	else:
	pdb_cls = pdb.Pdb
	wrapped_cls = cls._get_pdb_wrapper_class(pdb_cls, capman)
	cls._wrapped_pdb_cls = (usepdb_cls, wrapped_cls)
	return wrapped_cls

Let us know if you need further pointers. 👍

[Leundai]

Hi has this issue been finished yet at all?

[nicoddemus]

Hi @Leundai, not yet, feel free to pick it up if you are interested. 👍

[yasharth291]

I will pick it up
@nicoddemus

[pralkarz]

I did some research and it looks like the docs have been added in #7747 and #8536.
Are we okay to close this issue now or should the docs elaborate more on the feature?

[nicoddemus]

Thanks @ziebam!

If anything else is still missing, we can open a new issue to track that specifically. 👍