feat: updates to allow users to set max_stream_count

[chalmerlowe]

Adds a function determine_requested_streams() to compare preserve_order and the new argument max_stream_count to determine how many streams to request.

preserve_order (bool): Whether to preserve the order of streams. If True,
    this limits the number of streams to one (more than one cannot guarantee order).
max_stream_count (Union[int, None]]): The maximum number of streams
    allowed. Must be a non-negative number or None, where None indicates
    the value is unset. If `max_stream_count` is set, it overrides
    `preserve_order`.

Fixes #2030 🦕

[kien-truong]

Shouldn't preserve_order take priority over max_stream_count for correctness ?

[chalmerlowe]

@kien-truong

In the question of which argument overrides which, I could probably be convinced to go either way.

I purposely chose for max_streams_count to override preserve_order and wrote the docstring to state that, because:

• max_streams_count defaults to None and any user whose in-house code currently makes the call to _download_table_bqstorage() but does NOT include max_streams_count but does have a value for preserve_order will see the same behavior.
• If however, they go to the trouble of including a value for max_streams_count I would presume that they are doing so with an understanding of the new parameter and how it will affect any previous settings for preserve_order as defined in the docstring.

[suzmue]

@chalmerlowe @kien-truong

I am also in favor of having preserve_order override the max_streams_count setting. I think this would make it easier to use and understand.

If max_streams_count >= 1 this condition would still be satisfied by setting requested_streams = 1 since max_streams_count isn't a guarantee of any number of streams even in the bq storage api and from the issue, it seems that an import use case is to limit the number of streams, not increase them (though I am sure there are use cases for that as well).

Perhaps an error for when max_streams_count == 0 and preserve_order would make sense to have if we swap to favoring preserve_order, since then they are explicitly requesting both unlimited streams and a single stream.

Edit: Actually I don't think the error is necessary for the same reason as why setting to 1 should always be ok.

[chalmerlowe]

let me cogitate on this. thanks for the input, both of you.

[chalmerlowe]

@suzmue @kien-truong

I revised the logic. Once the CI/CD checks pass, can you approve it, Suzy?