Opened 7 years ago

Closed 7 years ago

#7297 closed (wontfix)

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

Reported by: akaihola 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 akaihola 7 years ago.
Failures of django.utils.text doctests
7297.1.diff (2.0 KB) - added by akaihola 7 years ago.
Work-around for #7297 doctest problem and corrections to code examples in utils.text
7297.2.diff (2.3 KB) - added by akaihola 7 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 7 years ago by akaihola

Failures of django.utils.text doctests

Changed 7 years ago by akaihola

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

Changed 7 years ago by akaihola

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

comment:1 Changed 7 years ago by russellm

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

comment:2 Changed 7 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

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