Missing documentation: process.extractBests

[olek-osikowicz]

Hi I just want to report that there is a missing documentation on the process.extractBests.

Current definition:

def extractBests(query, choices, processor=default_processor, scorer=default_scorer, score_cutoff=0, limit=5):
    """
    Get a list of the best matches to a collection of choices.

    Convenience function for getting the choices with best scores.

    Args:
        query: A string to match against
        choices: A list or dictionary of choices, suitable for use with
            extract().
        processor: Optional function for transforming choices before matching.
            See extract().
        scorer: Scoring function for extract().
        score_cutoff: Optional argument for score threshold. No matches with
            a score less than this number will be returned. Defaults to 0.
        limit: Optional maximum for the number of elements returned. Defaults
            to 5.

    Returns: A a list of (match, score) tuples.
    """
    is_mapping = hasattr(choices, "items")
    is_lowered = scorer in _scorer_lowering

    query = _preprocess_query(query, processor)
    results = rprocess.extract(
        query, choices,
        processor=_get_processor(processor, scorer),
        scorer=_get_scorer(scorer),
        score_cutoff=score_cutoff,
        limit=limit
    )

    for i, (choice, score, key) in enumerate(results):
        if is_lowered:
            score = int(round(score))

        results[i] = (choice, score, key) if is_mapping else (choice, score)

    return results

As you can see the function is conditionally returning a tuple of (choice, score) or (choice, score, key).

I am not sure if this is intended behaviour but it's not complient with the doc string: Returns: A a list of (match, score) tuples.
I believe good addition would be to add "include_key" key-word argument, to specify what user wants to be returned.
Then if a no mapping is found, key should default to None.

I am happy for discussion, and open a PR to address that.