docs(python): Fix LazyFrame fetch method references

[edwinvehmaanpera]

Fixes #17675 and other similar problems

Removing fetch from the miscellaneous.rst listing meant that the method was still listed as a method under LazyFrame, but appeared as a dead link and the method could not be found in the docs at all. This adds it back and fixes the links. Generally depreciated functions are still in the docs and there does not seem to be an elegant way of hiding a "public" function from autodocs entirely.

What fetch looks like under LazyFrame now:

Removed some other fetch references.

I am not sure what do about the fetch part in the user-guide. Should it be removed entirely or replaced with something else?

polars/docs/user-guide/lazy/execution.md

Lines 52 to 58 in 618a710

	### Execution on a partial dataset
	While you're writing, optimizing or checking your query on a large dataset, querying all available data may lead to a slow development process.
	You can instead execute the query with the `.fetch` method. The `.fetch` method takes a parameter `n_rows` and tries to 'fetch' that number of rows at the data source. The number of rows cannot be guaranteed, however, as the lazy API does not count how many rows there are at each stage of the query.
	Here we "fetch" 100 rows from the source file and apply the predicates.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 79.89%. Comparing base (262f7bc) to head (ea5cd0c).
Report is 25 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #18033      +/-   ##
==========================================
+ Coverage   79.87%   79.89%   +0.01%     
==========================================
  Files        1519     1521       +2     
  Lines      205839   206678     +839     
  Branches     2898     2906       +8     
==========================================
+ Hits       164416   165120     +704     
- Misses      40875    41010     +135     
  Partials      548      548              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[alexander-beedie]

We actually don't want to put the fetch docs reference back in (which is a bit unusual, but it's a debug function that has acted as a major footgun, so we prefer to simply remove it from the docs so people don't come across it at all). See: #17642 (comment)

[edwinvehmaanpera]

In that case should it be excluded/delisted entirely somehow or should I just put it back and leave it as-is? Having the method listed but not documented can be confusing.

What about the other changes and the user-guide?

[coastalwhite]

It should probably be removed from the notes as it is not true anymore. LazyFrame.head will also get pushed into the scan if possible.

[edwinvehmaanpera]

Removed fetch docs reference again. As well as the fetch section in the user-guide.

[ritchie46]

Can you do a rebase? @rodrigogiraoserrao can you review this one?

[edwinvehmaanpera]

Are we good to go now? @rodrigogiraoserrao

[rodrigogiraoserrao]

Looks good to me; thanks for the help.

[ritchie46]

heads that are after an aggregation don't influence an aggregation. I don't think this sentence makes much sense. Of course head followed by aggregation influences a result.

[edwinvehmaanpera]

The suggestion is to have head at the beginning of your query so in front of the aggregations.

[edwinvehmaanpera]

E.g. in the given example

q9 = (
    pl.scan_csv(f"docs/assets/data/reddit.csv")
    .head(10)
    .with_columns(pl.col("name").str.to_uppercase())
    .filter(pl.col("comment_karma") > 0)
    .fetch(n_rows=int(100))
    .collect()
)

[edwinvehmaanpera]

Is it too obvious? Maybe a little, but I have had these types of operations fail in ways I didn't expect. Calling head(10000) and returning 0 rows might confuse someone. It is just single sentence so I feel like it is justified.

[ritchie46]

Alright, with the accompanied query it makes sense. 👍

[ritchie46]

Thanks all!