Bundles vs. instance variables

[Joshua Bronson]

I read through the https://hypothesis.readthedocs.io/en/latest/stateful.html docs several times, and am still having trouble understanding when you would use Bundles vs. instance variables. The docs say:

If you can replace use of Bundles with instance attributes of the class that is often simpler, but often Bundles are strictly more powerful.

But I'm not seeing what you can do with Bundles that you can't do with instance variables because they're not powerful enough.

For example, in https://github.com/jab/lfu-cache/blob/main/test_lfu.py I was able to use only instance variables to test several properties of an LFU cache, and I feel like plain old instance variables alone are getting me really far. Is there anything I'm missing out on by not using Bundles?

I noticed the docs also add:

Note that currently preconditions can’t access bundles; if you need to use preconditions, you should store relevant data on the instance instead.

Given that limitation, it's even less clear to me when it's worth it to use Bundles.

I also had a similar question on when to use a plain old __init__ method (as in the docs' DatabaseComparison example) vs. initializes that I might as well ask here too. Any clarification on this (or even an example of when to use one vs the other) would be helpful.

Thanks!

P.S. I asked the above in the tracker some time ago. Also posting here so it reaches more fellow users who might have time to respond. If/when I understand this better, I might be able to submit a docs PR if that would be helpful. https://github.com/HypothesisWorks/hypothesis/issues/3511

[jabr...@gmail.com]

To close the loop here, the docs have now been updated to clarify the below. Big thanks to Anne Archibald for the improvements.