Opened 9 years ago

Closed 9 years ago

#7297 closed (wontfix)

utils.text docstrings inaccurate, not testable with doctest.testmod

Reported by: Antti Kaihola Owned by: nobody
Component: Testing framework Version: master
Severity: Keywords:
Cc: Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The code examples in the docstrings of [source:django/trunk/django/utils/text.py django.utils.text] can't be tested with doctest.testmod because of Python's issue 1108. A simple work-around would be to copy docstrings of individual functions to the module's __doc__ variable.

Also, the code examples are not accurate. Attached is a doctest.testmod run after fixing the doctest issue.

Attachments (3)

7297.doctest_run.txt (2.3 KB) - added by Antti Kaihola 9 years ago.
Failures of django.utils.text doctests
7297.1.diff (2.0 KB) - added by Antti Kaihola 9 years ago.
Work-around for #7297 doctest problem and corrections to code examples in utils.text
7297.2.diff (2.3 KB) - added by Antti Kaihola 9 years ago.
Added explanation and code examples to smart_split() to illustrate its un-escaping behavior.

Download all attachments as: .zip

Change History (5)

Changed 9 years ago by Antti Kaihola

Attachment: 7297.doctest_run.txt added

Failures of django.utils.text doctests

Changed 9 years ago by Antti Kaihola

Attachment: 7297.1.diff added

Work-around for #7297 doctest problem and corrections to code examples in utils.text

Changed 9 years ago by Antti Kaihola

Attachment: 7297.2.diff added

Added explanation and code examples to smart_split() to illustrate its un-escaping behavior.

comment:1 Changed 9 years ago by Russell Keith-Magee

(In [7581]) Refs #7297 -- Corrected some doctest strings internal to the utils.text module. Thanks, akaihola.

comment:2 Changed 9 years ago by Russell Keith-Magee

Resolution: wontfix
Status: newclosed

I'm wontfixing the last part of this patch (introducing a doc setting to get around Python 1108) because it opens a window for a future failure to creep in - if we add a new method with a doctest, it's entirely possible that we could forget to put it in the doc setting, simply because that isn't a normal requirement for such doctests.

On top of that, the actual utils.text tests are in tests.regressiontests.tests. Since these tests aren't an essential part of Django's test suite, I'm not inclined to introduce a workaround to a problem we're not really having.

Note: See TracTickets for help on using tickets.
Back to Top