fix(python): Add missing read_database overload

[max-muoto]

This PR adds an overload when iter_batches is a bool, as opposed to Literal[True] or Literal[False], most of the time in Polars, overloads like this aren't super helpful, as you're actually just passing in True/False. However, with top-level functions like read_database, you might want to have a wrapper over it. This is basically the situation that I am in, where I have a custom version of read_database, with some additional functionality around retrieving the DB connection, and so want to have my own overloads on that function for DataFrame, and Iterable[DataFrame], to make this possible there does need to be an overload for the non-literal case, at least with Pyright.

Here's basically an example of the issue I'm running into.

def custom_read_db(
    query: Query,
    db: str
    *,
    iter_batches: bool = False,
) -> DataFrame | Iterable[DataFrame]:
   return pl.read_database( # Pyright error, due to the fact, there's no `DataFrame | Iterable[DataFrame]` overload.
        sql,
        connections[db],
        iter_batches=iter_batches,
    )

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.86%. Comparing base (15f6b36) to head (e71f413).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #16229   +/-   ##
=======================================
  Coverage   80.85%   80.86%           
=======================================
  Files        1394     1394           
  Lines      179955   179955           
  Branches     2909     2909           
=======================================
+ Hits       145508   145525   +17     
+ Misses      33942    33925   -17     
  Partials      505      505           

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

[alexander-beedie]

Hmm, at first glance it seems odd to be overloading our typing so that something which customises it (unknown to us) doesn't have to set its own, though perhaps I'm missing something.

Feels like it could be a slippery slope where we end up unnecessarily (from our perspective) overloading some enormous number of functions just in case somebody wants to overload them and not do the typing on their end 😅

Could you better-clarify why it couldn't be done on your side instead?

[stinodego]

Thanks, this is indeed the correct way to do overloads on booleans - I have done this fix in some other places already.

@alexander-beedie you can check out this blog for some of the quirks of Python overloads, they explain it relatively well:
https://medium.com/analytics-vidhya/making-sense-of-typing-overload-437e6deecade