feat!: deprecate forget_length, add parameters to typetracer_with_report

[agoose77]

1. Deprecation of forget_length:
   This argument represents a leak of the implementation details; the function only accepts a form, which has no known length.

   • Add deprecation notice to wiki

   In future, we could add a *, length=unknown_length keyword-only argument that would be more powerful, but I can't see any examples of people needing that right now.

2. Extend typetracer_with_report parameters
   Most uses of our typetracer_with_report function immediately wrap the result with an ak.Array. We should just support that, given that the highlevel argument is so widely used in our L1 API. Although typetracer isn't exactly L1, in my view L1-L2 is more about who uses these functions, rather than how painful they can be to use. @jpivarski this might reflect a changing view of mine, I am not sure. Please weigh in you think we should keep these functions "simple".

[codecov]

Codecov Report

Merging #2671 (ad0fe30) into main (3cd54fa) will decrease coverage by 0.01%.
The diff coverage is 73.33%.

Additional details and impacted files

Files Changed	Coverage Δ
src/awkward/operations/ak_from_buffers.py	93.47% <ø> (ø)
src/awkward/typetracer.py	84.61% <73.33%> (-9.68%)	⬇️

[jpivarski]

👍

[agoose77]

@jpivarski could you sign-off on 624634f and ad0fe30 which add ak.typetracer.typetracer_from_form? I added this in ak.typetracer only, rather than ak._nplikes.typetracer because it's a public-only function. In time, that might also be true of _typetracer_with_report, but I decided not to move that yet.

[jpivarski]

I think it looks like a good idea. I looked it over while we were talking—splitting my attention, but it was on the same topic—and I can see the usefulness of having a function like this. It's public, but I think it was motivated by an external project. (Was it Tiled? Coffea? I just tried to confirm where I got this impression, but wasn't able to find direct evidence.)

[agoose77]

Both coffea and dask-awkward would benefit from a function like this (see dask-contrib/dask-awkward#351 for an initial cleanup)