Typing for BaseConverter convert doesn't respect CONSUME_MULTIPLE_SEGMENTS

[davetapley]

Correct:

falcon/falcon/routing/converters.py

Lines 49 to 52 in 6d7a45b

	"""Convert a URI template field value to another format or type.
	Args:
	value (str or List[str]): Original string to convert.

Wrong, should be value: str | list[str]:

falcon/falcon/routing/converters.py

Line 48 in 6d7a45b

def convert(self, value: str) -> Any:

[davetapley]

... although, str | list[str] is a bit awkward since the implementor will have to assert the correct type based on:

falcon/falcon/routing/converters.py

Line 39 in 6d7a45b

CONSUME_MULTIPLE_SEGMENTS: ClassVar[bool] = False

I'm guessing there's no way to express that relationship in typing.

If not I don't know how much appetite to e.g. make the current BaseConvertor private (i.e. _BaseConvertor) and expose a separate BaseConvertor with an explicit CONSUME_MULTIPLE_SEGMENTS, as with PathConverter.

[davetapley]

... I thought I could workaround with:

Replace:

class MyConvertor(BaseConverter):
    CONSUME_MULTIPLE_SEGMENTS = True

With:

class MyConvertor(PathConverter):
    ...

... but PathConverter is typed to return str, not Any as BaseConverter 😑

falcon/falcon/routing/converters.py

Line 247 in 6d7a45b

def convert(self, value: Iterable[str]) -> str:

[jkmnt]

I think the elegant (but breaking) API for such scalar-or-vector argument is vararg.

def convert(*value: str) -> Any

then convert('a') and convert ('a', 'b') are all valid.
It has the extra bonus of not needing to check isinstance(value, list) in implementation.

[vytas7]

In retrospect, even typing aside, I think this is a design mistake, I just didn't think of this specific detail before. The converter should always receive a string value, if needed, pre-joint on / by the router.

We cannot change this now, but we should plan a breaking change for 5.0.

[CaselIT]

You mean that the converter should pre-join them here?

falcon/falcon/routing/compiled.py

Lines 1094 to 1102 in 6d7a45b

	class _CxSetFragmentFromRemainingPaths(_CxChild):
	def __init__(self, segment_idx: int) -> None:
	self._segment_idx = segment_idx
	def src(self, indentation: int) -> str:
	return '{0}fragment = path[{1}:]'.format(
	_TAB_STR * indentation,
	self._segment_idx,
	)

so that the current path converter becomes a no-op?

Maybe I guess. Overall it would probably help if we were to require subclassing here, so we could avoid using that classvar.

[davetapley]

Ooh, someone suggested a good workaround using Protocols here:

https://discuss.python.org/t/typing-instance-based-on-classvar/69716/2