This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Docs - difflib.SequenceMatcher quick_ratio and real_quick_ratio improved docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Lewis Ball, docs@python, tim.peters
Priority: normal Keywords: patch

Created on 2020-05-06 22:21 by Lewis Ball, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 19971 closed Lewis Ball, 2020-05-06 22:56
Messages (2)
msg368305 - (view) Author: Lewis Ball (Lewis Ball) * Date: 2020-05-06 22:21
Currently the docs for `difflib.SequenceMatcher.quick_ratio()` just says 'Return an upper bound on ratio() relatively quickly', which doesn't give much of an idea about how that upper bound is calculated. `real_quick_ratio` has similarly brief documentation.

I'll raise a PR shortly to add a more verbose description to each of these ratios, so that it is clear when each should be used.

My current suggestions would be:

    Return an upper bound on ratio() relatively quickly. This is the highest possible ratio() given these letters, regardless of their order.

    Return an upper bound on ratio() very quickly. This is the highest possible ratio() given the lengths of a and b, regardless of their letters. i.e. 2*(min(len(a), len(b))/(len(a) + len(b))
msg368319 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2020-05-07 01:21
Thanks for the effort, but I'm rejecting this.  The language deliberately defines nothing about how these are calculated.  It defines how `.ratio()` is computed, but that's all.  An implementation is free to do whatever it likes for the "quick" versions, provided only they return upper bounds on `.ratio()`.  Indeed, it's perfectly fine if an implementation merely returns 1.0 for both, regardless of the arguments.

If an implementation is cleverer than that, great, that's fine too - but it would be actively counterproductive to constrain them to be no _more_ clever than the current implementations.
Date User Action Args
2022-04-11 14:59:30adminsetgithub: 84719
2020-05-07 01:21:37tim.peterssetstatus: open -> closed

nosy: + tim.peters
messages: + msg368319

resolution: rejected
stage: patch review -> resolved
2020-05-06 22:56:02Lewis Ballsetkeywords: + patch
stage: patch review
pull_requests: + pull_request19287
2020-05-06 22:21:15Lewis Ballcreate