Enhance and clarify options for download function

[chuckwondo]

This discussion stems from this thread: #1142 (comment)

We would like to enhance the capabilities of the download function, but also want to take care not to make it more difficult/confusing to use that it may already be.

Here's the current signature:

def download(
    granules: Union[DataGranule, List[DataGranule], str, List[str]],
    local_path: Optional[Union[Path, str]] = None,
    provider: Optional[str] = None,
    threads: int = 8,
    *,
    show_progress: Optional[bool] = None,
    credentials_endpoint: Optional[str] = None,
    pqdm_kwargs: Optional[Mapping[str, Any]] = None,
) -> List[Path]:

The threads parameter is already a bit odd now that pqdm_kwargs was added (at a later point than threads was initially added), because pqdm_kwargs supports an n_jobs setting that is now what threads applies to. This implicit (and undocumented) relationship can already lead to confusion, so we should not add yet another such parameter relationship (as proposed by @ana-sher in the thread linked above for handling/ignoring download errors).

What we might want to consider at this point is some way to both deprecate some things as well as better consolidate/clarify various options that we want to support.

Specifically, I'd like to see threads somehow deprecated as a positional parameter, now that we have 3 keyword-only parameters, and pqdm_kwargs supports n_jobs which now "duplicates" the purpose of threads.

Also, show_progress effectively duplicates the pqdm_kwargs.disable boolean, so that's another implicit and undocumented relationship.

Since we have 2 parameters that duplicate the purpose of 2 pqdm_kwargs values (but with arguably better names: threads instead of n_jobs and show_progress instead of disable), perhaps we should consider surfacing some or all of the other pqdm_kwargs and deprecate pqdm_kwargs itself.

However, pqdm_kwargs supports quite a few options, which pqdm passes through to tqdm, as documented in tqdm Objects. Therefore, it might not make sense to attempt to surface them all, but then how do we choose which ones to surface? This is why providing pqdm_kwargs as a parameter completely avoids this question, allowing the user to pass anything that tqdm supports, both now and in the future.

Perhaps a happy medium would be to keep things much as they are now, but properly document that threads automatically sets pqdm_kwargs.n_jobs and show_progress automatically sets pqdm_kwargs.disable (inversely), and simply attempt to cleanly deprecate threads as a positional parameter in favor of making it a keyword-only parameter.

Beyond that, per the linked thread from @ana-sher, how might we provide a cleaner way for users to filter out any failed downloads without raising an error?

[jhkennedy]

Generally, I think this would be a better method of a results class than a stand alone method. That way, granules isn't a parameter (it'd just use self.granules or whatever), and I'd expect provider, credentials_endpoint, etc to also be handled by the class and not passed to the method.

Specifically, I'd like to see threads somehow deprecated as a positional parameter, now that we have 3 keyword-only parameters, and pqdm_kwargs supports n_jobs which now "duplicates" the purpose of threads.

Also, show_progress effectively duplicates the pqdm_kwargs.disable boolean, so that's another implicit and undocumented relationship.

These make sense to me and I think pqdm_kwargs likely makes the most sense, if we're committed to pqdm in the long term.

That said, I think it would make more sense to freeze (and eventually deprecate) this package-level method, and focus on results class method that would unburden us from the existing API.