Document the `pluggy._Result` API

[goodboy]

Currently pluggy._CallOutcome is implied to be part of the internal api by the leading _.

In practice it is used by hookwrappers.

An example:

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    rep = outcome.get_result() 
    ...

The outcome is accessed directly by the user.
Therefore I propose we expose it correct in plugg.__all__ and expose it in the api reference.

[RonnyPfannschmidt]

imho we should not expose it, its an internal interface, only exposed as value to the user unable to change the behavior or make sensible use of own instances

all making it public would serve is handing people footguns they arent supposed to use

[goodboy]

@RonnyPfannschmidt are you sure about that?

Don't you think that preventing "shooting one's self in the foot" could be avoided by a proper private interface (i.e. set of methods) on CallOutcome?
For example in the exposure of this object we make CallOutcome.get_result() public but force_results() private (so I guess _force_result())?

That's not even going into the detail that it only defines 2 methods - get_result() and force_result() and that the latter is probably fine as a public method considering its name.
The standard library's concurrent.Future defines something similar and includes a analogous set_result() which is exposed publicly.

Let me know what you think :)

[RonnyPfannschmidt]

@tgoodlet nonetheless we would expose something that cannot be used in a sane context without deliberation, as such i#d rather not expose it

[goodboy]

@RonnyPfannschmidt I agree deliberation is good but what do you consider a "sane context" to be if the above example is not such a case?

I'm interested to know what you're thinking should be the requirement(s) for components in pluggy to be considered part of the public API?

I do agree it's not good to expose routines that allow the user to hurt themselves but I would argue that in this case consumers of CallOutcome may in fact want to use force_result for legitimate reasons. As an example pytest does this and I would consider pytest client code which consumes pluggy's public API.

[RonnyPfannschmidt]

@tgoodlet a public method is fine, but why should we expose a class that adds no value to the user while locking us in to having it when all we really do is expose a few public methods

i would go as far as shifting the api so a call-outcome is a opaque object and the methods to interact with it are importable functions instead

[goodboy]

@RonnyPfannschmidt I really do believe that explaining how hookwrappers work is much easier when you can point in the docs to a CallOutcome definition alongside usage of processing such an instance.

Again I'll make the comparison with concurrent.Future.

It's not like a user would ever (maybe someone has?) instantiated their own Future intance for use but having it documented and exposing it as part of the stdlib's public API definitely helps with understanding how to use it in practise.

[goodboy]

@RonnyPfannschmidt you mention

but why should we expose a class that adds no value to the user while locking us in to having it when all we really do is expose a few public methods

I would argue there is no "lock in". We can always change the type of CallOutcome without changing its public interface; that's the beauty of duck typing ;)

[RonnyPfannschmidt]

implementers os a futures Executors have to instantiate them, at pluggy, only the internals ever instantiate the outcomes

it doesnt make sense to expose the type for that reason - im not aware of anything where others require it

as soon as we expose a type changing it will break some peoples code and will always require a major release

[goodboy]

@RonnyPfannschmidt you wrote:

implementers os a futures Executors have to instantiate them, at pluggy, only the internals ever instantiate the outcomes

But the docs for concurrent.Future clearly state (and I know this from practise) that,

Encapsulates the asynchronous execution of a callable. Future instances are created by Executor.submit() and should not be created directly except for testing.

So it is the same concept. Yes, the Executor.submit() creates Futures but the user should never do so.

[RonnyPfannschmidt]

@tgoodlet that bacislly holds that there is 2 cases where Future objects need to be created outside of the codebase - impelemntign Executors, and testing

those do not hold for pluggy outcomes

[RonnyPfannschmidt]

unless there is a compelling case that makes it necessary to expose the type i am strictly against providing it and "the docs" is not a case that warrants it

[goodboy]

Ok fair enough; I guess I thought docs and the standard lib's multiple examples of this was sufficient but maybe you're right.

I guess maybe we should see what others think?
If the consensus is against me I'll of course concede :)

[nicoddemus]

I agree with @RonnyPfannschmidt that we should not expose the _CallOutcome class, but we should really document the public methods properly, since this is part of the public API and is used by hookwrappers.

This is probably easy to add to Sphinx, using the automethod directive IIRC.

[goodboy]

@nicoddemus @RonnyPfannschmidt cool I'll take a look at updating the docs the way you propose then.

Another question for you both is what happens if we want to eventually add built-in asynchronous hook calling to pluggy? For example leveraging asyncio.

This current API question will become relevant as we will need to deliver a Future like object as part of the hook calling API which imho is basically the direct analogue of _CallOutcome (but obviously in a synchronous context). I would even go further to say should we eventually move _CallOutcome further towards the notion of a Future to prevent duplication and unify the concept of a "future result"?

[RonnyPfannschmidt]

hookwrappers do not share the same needs as an actual future - i would consider trying to turn them into a future a premature de-duplication

from my pov outcomes for hookwrappers have a much different life-cycle pattern than futures and we should keep it in mind and separate