Make `_pformat_x` functions public

[nstarman]

In some custom __pdoc__ I've found it necessary to use _pformat_dataclass. Is there either a) a way to avoid this, or b) can the _pformat_X functions be made public? They are useful building blocks in a custom __pdoc__.

E.g.
https://github.com/GalacticDynamics/coordinax/blob/ea9637589f4cdff1863d4c8258ef0bc31bc7e1f8/src/coordinax/_src/vectors/base/vector.py#L546

[patrick-kidger]

These should already be accessible implicitly through calling pdoc on an object of the relevant type, if needed whilst setting respect_pdoc=False to avoid an infinite loop. Would that work?

[nstarman]

It doesn't seem to work:

        if not vector_form:
            print("HERE")
            # TODO: not use private API.
            # return wl._definitions._pformat_dataclass(self, **kwargs)
            kwargs["respect_pdoc"] = False
            return wl.pdoc(self, **kwargs)

resulting in

>>> wl.pformat(obj)
HERE
GroupDoc(child=TextDoc(text='<recursive>'))

It does work if I call

>>> wl.pformat(obj, respect_pdoc=False)
HERE
GroupDoc(child=TextDoc(text='<recursive>'))

but the internal redirect doesn't seem to work.

[patrick-kidger]

Ah, it's noticing that self has already been seen, and thinking that this is a recursive call. Also set kwargs["seen_ids"] = None :)

[nstarman]

That works, except that I do want to respect pdoc for all the fields of that dataclass!

kwargs["respect_pdoc"] = False  # <- now it doesn't use pdoc for the fields
kwargs["seen_ids"] = None
return wl.pdoc(self, **kwargs)

[patrick-kidger]

Ah bother. Hmm.

I'm a little reluctant to make specifically the _pformat_x public simply because I think the details of those might change over time. (Although admittedly probably not by very much, WL is basically stable.)

I'm not sure what the best solution is here, to be honest. Perhaps vendor a copy of the function you need into your own codebase? Maybe pdoc(self, some_kind_of_flag=True)? Maybe something else?

[nstarman]

What about allowing respect_pdoc to be a tuple of bools? Each subcall to pdoc would remove the first one until either the whole pdoc resolved or the last tuple element applies to all subcalls.

So this problem could be resolved with
pdoc(self, seen_ids=None, respect_pdoc=(False, True))

@patrick-kidger does this sound good or is it too much magic?