Settable completer type hint squiggles

[ShiftPoster]

Description

Hello!

I've been using the Settable class with the path completer, and Pylance shows an argument type error (reportArgumentType). When I change the code to get rid of the error and run it, I get a TypeError.

Please let me know if I am using the argument incorrectly, if this an issue with Pylance, or if I'm just being a doofus.

Thank you

Environment

• Python 3.12.2
• Visual Studio Code 1.115.0
  • Python ms-python.python 2026.4.0
  • Pylance ms-python.vscode-pylance 2026.2.1

Steps to Reproduce

Source

from cmd2 import Cmd, Settable


class App(Cmd):
    def __init__(self):
        super().__init__()
        self.no_error = None
        self.type_error = None
        self.add_settable(
            Settable(
                "no_error",
                str,
                "completer=self.path_complete",
                self,
                completer=self.path_complete,
            )
        )
        self.add_settable(
            Settable(
                "type_error",
                str,
                "completer=Cmd.path_complete",
                self,
                completer=Cmd.path_complete,
            )
        )


if __name__ == "__main__":
    App().cmdloop()

The squiggle:

What Pylance says:

When running:

The type_error attribute is correctly reporting available directories when I hit tab, while the no_error attribute gives the TypeError for a parameter mismatch.

[tleonhardt]

Explanation of what is happening

1. Why self.path_complete fails at runtime
   cmd2's completion API (such as the completer argument in Settable or add_argument) requires an unbound method/function.

   When completion is triggered, cmd2 automatically resolves the correct instance (which could be a Cmd application or CommandSet module) and explicitly passes it as the first argument to the completer function. If you provide a bound method like self.path_complete, Python implicitly passes self, and then cmd2 explicitly passes it again. This results in the function receiving one too many arguments, causing the TypeError.

2. Why cmd2.Cmd.path_complete fails Pylance Passing the unbound method cmd2.Cmd.path_complete is the correct approach for runtime. However, Pylance flags it because of how cmd2 types the completer parameter.

   In cmd2, the completer parameter expects a callable with a signature that accepts CmdOrSet (which is a Union of cmd2.Cmd and cmd2.CommandSet). This implies the completer must be able to handle either a Cmd app or a CommandSet. Because cmd2.Cmd.path_complete is strictly typed to accept only cmd2.Cmd, Pylance correctly warns that passing a CommandSet to it would violate the types.

How to fix it

Since you know this setting is being attached to your Cmd subclass (and not a CommandSet), you can satisfy both the type checker and the runtime using one of the following approaches:

• Option A: # type: ignore (Simplest)
  Because you are certain the self passed at runtime will be a Cmd instance, bypassing the type-checker here is completely safe, i.e.:

  completer=cmd2.Cmd.path_complete  # type: ignore[arg-type]

• Option B: typing.cast
  If you prefer strict typing without ignore comments, you can cast the unbound method to the expected type alias cmd2.types.CompleterUnbound:

  import typing
  
  # Inside your init:
  completer=typing.cast(cmd2.types.CompleterUnbound[cmd2.types.CmdOrSet], cmd2.Cmd.path_complete)

[tleonhardt]

@ShiftPoster Please let us know if there is something we can do to improve our documentation to make this easier to understand and get right for our users.

[kmvanbrunt]

@ShiftPoster @tleonhardt Don't use cmd2.types.CompleterUnbound just yet. That's on the main branch and not yet released. I am in the process of updating type hints and that may be renamed when cmd2 4.0 comes out.