Deprecate nested given

[tybug]

Closes #4167

[Zac-HD]

Nice!

It occurs to me that some people are probably going to use .example()-inside-@given(), and if we can give a specific error message for that case it'd make more sense to them than talking about @given()-inside-@given().

[tybug]

I'm not sure how to rewrite our tests for this change without weakening them :( see e.g. test_minimise_array_shapes

[Zac-HD]

...maybe we need to add a special "internal-use-only" flag to disable this for our own tests? It's janky, but I can see a reasonable argument for it.

[tybug]

If we can't rewrite our own tests without nested givens, maybe we shouldn't be deprecating them for others? Crosshair can pretty easily detect + throw when it encounters this, and I'm not sure that "quadratic behavior" is compelling for knowledgeable developers who are setting reasonable max_examples limits, as we do.

[jobh]

I agree, nested @given() (along with .example() tbh) is nice to be able to use, it's an intuitive idiom and not always worth the effort to figure out the best or most performant alternative.

Would it be acceptable to make it into a health check failure (so that it can be turned off after being warned about the drawbacks)?

[jobh]

I looked at the five reported in-the-wild usages. Briefly,

1. Outer given is sampling from two elements (api variants) and should probably be replaced by parametrize (but relatively benign).
2. Check that it is possible to find at least one valid suffix for any fixed prefix. Seems like something that is difficult to express without nesting?
3. Indentation error (unintentional nesting).
4. Outer given selects a type, inner given fuzzes over possible values of that type. They seem to be cognizant of the issues, disabling shrink for the outer.
5. isn't nested (anymore?) afaics

2 and 4 are superficially valid uses IMO.

[Zac-HD]

Would it be acceptable to make it into a health check failure (so that it can be turned off after being warned about the drawbacks)?

🤦‍♂️ yes this is obviously the solution, now that you mention it.