remove reference to value/error when unwrapping outcome, and add .peek() method

[graingert]

Fixes #47

currently unwraping exceptions leaves a refcycle that keeps the entire traceback and any locals alive. This PR resolves that by clearing the error field when the Error is unwrapped.

For the previous behaviour of Value (eg in trio) if you receive a large bytes object in a Value that bytes object stays alive long after it's needed. This PR resolves that by clearing the value field when the Value is unwrapped.

this is a breaking change and should probably be released with a major version bump, eg outcome==2.0.0

[TeamSpen210]

This might need to be a new method for backwards compatibility, since the attributes are public, users would be able to still read them after unwrapping. Unless we're fine with that breaking change.

[graingert]

could just call it InvalidatingOutcome, InvalidatingError and InvalidatingValue

[TeamSpen210]

A parallel class hierarchy seems problematic, they'd be incompatible with the current ones. More thinking like unwrap_and_clear(), that's all we need.

[CoolCat467]

Would using a weak reference not be acceptable?

[graingert]

Would using a weak reference not be acceptable?

I think that would be more complicated and it would be odd that unwrapped values are sometimes there sometimes not and not everything can be weakref'd

[richardsheridan]

I'm +1 on "just delete the attribute on unwrap". It's understandable and minimal and the only issue is backwards compatibility, so I'd say slap a unwrap_and_clear() method on version 1.4.0 and make a 2.0.0 release for the cleaner implementation to free more users from refcycles.

[RazerM]

I'm -1 on deleting public attributes during unwrap. I don't like that accessing an attribute/property may raise, but if we go that route then I'd much prefer AlreadyUsedError over AttributeError.

The way I've always used outcome is to only .unwrap() or .send(), so I would be fine with an outcome 2.0 that doesn't have the attributes, but I know Trio does use them.

[graingert]

I was off sick and didn't have time to focus on this PR, I'd like to pick it back up again

[TeamSpen210]

I do wonder, since this is a breaking change, maybe it'd be better to make it entirely breaking - change the properties to peek_value() and peek_error() or something. That way you get type checker or runtime errors at all call sites. Though it would cause a bit of churn in cases where users only accessed attributes and never unwraped. So not sure.

[CoolCat467]

I don't see any immediate issues. Would raise the possibility of sharing peek and return, return/unwrap just being peek and then unset, but as is is still fine.

[graingert]

ok let's add peek