Implement `reprlib.repr_args`

[bswck]

Feature or enhancement

Proposal:

As discussed in the discourse thread, a function in reprlib to help construct dataclass-like representation for arbitrary classes, drawing inspiration from existing implementations in asyncio and unittest private helpers. Any input is very welcome.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/new-function-repr-args-in-pprint-or-reprlib/65193/1

[SofieTorch]

I'm going to check it out so maybe I can work on this :)

[bswck]

Sure, give it a shot @SofieTorch :)
I'm happy to review / discuss, ping me anytime!

[SofieTorch]

@bswck I was checking the discussion and also the current repr implementation code (to understand a little bit how does it access to object's elements), and I was wondering for which types is this repr_args to be implemented? I think it makes sense for dict, but how would it be for tuples? I feel like the intention is to make it available for classes, because the piece of code in the discussion is pretty common there, but then we will need to handle it a bit different from the current repr implementation, right? and also different from the mock._format_call_signature, as the idea is not to receive the args and kwargs as arguments of the method, but then is the intention actually to format the args and kwargs? or for attributes of the object? Just trying to understand it better, please correct me if I'm misunderstanding something 😊

[SofieTorch]

If you provide me with an example of how the method will be called and the expected output it would be very helpful!

[sobolevn]

@SofieTorch you can take a look at

cpython/Lib/dataclasses.py

Lines 1105 to 1113 in 800d37f

	flds = [f for f in field_list if f.repr]
	func_builder.add_fn('__repr__',
	('self',),
	[' return f"{self.__class__.__qualname__}(' +
	', '.join([f"{f.name}={{self.{f.name}!r}}"
	for f in flds]) + ')"'],
	locals={'__dataclasses_recursive_repr': recursive_repr},
	decorator="@__dataclasses_recursive_repr()")

and how we test this in test_dataclasses

[bswck]

The implementation specification isn't very clear. I think it's good to discuss the scope of the function here.

As I'm thinking about it, maybe repr_call would be a better name for it, because my intention was to suggest a routine for writing representations of calls quickly.

I was thinking of something like

import reprlib

class Foobar:  # silly example
    def __init__(self, foo: int, bar: int, /, biz: int) -> None:
        self.foo = foo
        self.bar = bar
        self.biz = biz

    def __repr__(self) -> None:
        return reprlib.repr_call(
            target=type(self).__name__,  # "Foobar" but inheritance-friendly
            args=(self.foo, self.bar),
            kwargs={"biz": self.biz},
        )  # Example result: "Foobar(1, 2, biz=5)"

Which would otherwise be

    def __repr__(self) -> None:
        args = (self.foo, self.bar)  # as an example
        kwargs = {"biz": self.biz}  # as an example
        arg_reprs = map(repr, args)
        kwarg_reprs = [f"{k}={v!r}" for k, v in kwargs]
        return type(self).__name__ + ", ".join((*arg_reprs, *kwarg_reprs))

That's sort of the primary use case.

[bswck]

It would be nice if we could give a callback for repr() calls of arguments (i.e. parameter values).

        return reprlib.repr_call(
            target=type(self).__name__,  # "Foobar" but inheritance-friendly
            args=(self.foo, self.bar),
            kwargs={"biz": self.biz},
+           repr_function=partial(textwrap.wrap, width=40),  # Function as the `repr()` on every arg
        )

Example:

>>> reprlib.repr_call("hello", args=(-1, -2), repr_function=lambda v: repr(abs(v)))
'hello(1, 2)'

(It's important that the repr_function would have to return a string as it would be passed to a tuple passed to sep.join())
Where sep would be used to join args and kwargs representations, by default ", ":

>>> reprlib.repr_call("hello", args=(-1, -2), repr_function=lambda v: repr(abs(v)), sep="; ")
'hello(1; 2)'

[bswck]

What are your thoughts on this? @sobolevn @jaraco @dg-pb @pawamoy (and everyone else's feedback is also welcome!)

[dg-pb]

It would be nice if we could give a callback for repr()

Agreed. Have been using this for a while and it has proven to be useful. In particular, for alternatives that special case certain "could be a bit prettier" cases, such as #136521

Where sep would be used to join args and kwargs representations

Not sure about this. I have never used anything apart from ",". Any cases where this is needed? (Can always be added later)

target=type(self).name

If it is not a string, it would be nice if one could provide type(self) and get f'{tp.__module__}.{tp.__name__}'.

Thus, if one needs tp.__name__, then manual input is short and simple, but a bit more complex common case is automated. The above is the one that I most often choose, but maybe there is some other representation which is used more often and would be better suited.

---

Also, I sometimes need target=None, to get "(<args>)" without a name. Could be convenient to have.

[bswck]

Not sure about this. I have never used anything apart from ",". Any cases where this is needed? (Can always be added later)

Could be useful to make all arguments appear on different lines to call textwrap.indent() on it, or for skipping commas like it is done in Pydantic models as strings.

>>> kwargs = {"foo": True, "bar": False}
>>> print(reprlib.repr_call(kwargs=kwargs, sep=" "))
(foo=True bar=False)
>>> print(reprlib.repr_call(kwargs=kwargs, sep="\n"))
(foo=True
bar=False)

Or even for producing prop strings for HTML? But that necessitates a parens parameter. Maybe

>>> print(reprlib.repr_call(kwargs=kwargs, parens=False))
foo=True bar=False
>>> print(reprlib.repr_call(kwargs=kwargs, sep="\n", parens=False))
foo=True
bar=False
>>> print(reprlib.repr_call(kwargs=kwargs, sep=",\n", parens=False))
foo=True,
bar=False
>>> print(textwrap.indent(reprlib.repr_call(kwargs=kwargs, sep=",\n", parens=False), "    "))
    foo=True,
    bar=False

On the other hand, I don't want the scope to be overly broad here.
We may as well just only format the call arguments and leave it to the user to concatenate the target qualifier name to that (type(...).__name__ + repr_call(...)) and to wrap the arg list representation with .join("()") for parens, instead of adding parens according to a parens kwarg (type(...).__name__ + repr_call(...).join("()"), and document such examples as recipes).

That would be repr.repr_arglist.

Or... maybe provide 2 functions? One for arglists, and the second for entire calls.

repr_call(target, args, kwargs, sep, parens, repr_function)
-> target qualname + "(" if parens + repr_arglist(args, kwargs, sep, repr_function) + ")" if parens

repr_arglist(args, kwargs, sep, repr_function)
-> sep.join([
      *map(repr_function, args),
      *[format(k) + "=" + repr_function(v) for k, v in kwargs.items()]
   ]) 

[bswck]

cc @asottile :)

[dg-pb]

I think the best indicator would be to look at actual use cases and see what features are common enough for initial version.

Or... maybe provide 2 functions? One for arglists, and the second for entire calls.

I like this. Maybe:

def repr_arglist(args, kwargs, repr_function) -> Iterator:
   ...

So that it isn't bound to separator giving it more flexibility with less arguments.