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.

classification
Title: Docs - difflib.SequenceMatcher quick_ratio and real_quick_ratio improved docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9
process
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:

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

real_quick_ratio
    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.
History
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