[issue12148] Clarify "or-ing together" doctest option flags
New submission from ekorn <jonovik@gmail.com>: Combining multiple option flags to doctest.testmod(optionflags=...) requires the bitwise or operator |, not plain "or". I therefore suggest rewording "or-ing together individual option flags." to "or-ing together individual option flags, using the 'bitwise or' operator |.", perhaps with a link to http://docs.python.org/reference/expressions.html#binary-bitwise-operations. Example: """ Doctest option flags must be or-ed together with '|', not 'or'.
print "A B C" A B... """ import doctest
print "Combining option flags using bitwise '|'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS) print "Combining option flags using logical 'or'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE or doctest.ELLIPSIS) ---------- assignee: docs@python components: Documentation messages: 136509 nosy: docs@python, ekorn priority: normal severity: normal status: open title: Clarify "or-ing together" doctest option flags versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: I think adding the word 'bitwise' in front of "or'ed" and linking it to that section would be sufficient. ---------- nosy: +r.david.murray versions: +Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: As a non-native speaker, I found constructs such as “OR-ed” or “syncing” a bit non-obvious when I started reading docs. +1 on adding “bitwise”, +1 on changing to “combined with the | operator”. (Yes, this is an or-ed vote.) ---------- nosy: +eric.araujo versions: +Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: The basic fix is to replace the fake verb 'to or', conjugated not really properly as "or's" or "or'ing", with the real noun 'bitwise-or'. help(doctest.testmod) ... Optional keyword arg "optionflags" or's together module constants, and defaults to 0. This is new in 2.3. Possible values (see the docs for details): Eliminate 'this is new...' here and above. Suggested replacement: Optional keyword arg "optionflags" (default 0) is the bitwise-or of the following module constants (see the docs for details): help(doctest.testfile) ... Optional keyword arg "optionflags" or's together module constants, and defaults to 0. Possible values (see the docs for details): Same replacement (whatever we decide on). Lib 25.2.4. Basic API doctest.testfile entry: ... Optional argument optionflags or’s together option flags. See section Option Flags and Directives. -> Optional argument optionflags is the bitwise-or of options flags. See section Option Flags and Directives. doctest.testmode entry refers back to above. 25.2.3.5. Option Flags and Directives doctest.COMPARISON_FLAGS A bitmask or’ing together all the comparison flags above. doctest.REPORTING_FLAGS A bitmask or’ing together all the reporting flags above. A bitmask that is the bitwise-or of all the comparison flags above. ditto with 'reporting' instead. -or- A bitmask -- the bitwise-or of ... I think this is all. Searching on "or'" does not work because sphinx nicely replaces "'" with a non-ascii unicode char ;-). ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I found “bitwise OR-ed” in library/fcntl.rst library/functions.rst library/os.rst library/winsound.rst (using grep, not Sphinx :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: I like bitwise-or better than bitwise OR because 'bitwise-or' is a distinct operation from 'or', and making it hyphenated emphasizes that. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
Caelyn McAulay added the comment: I grepped for 's together' and found two instances of "or's together" in the docs which I reworded to use bitwise-or instead, in the attached patch. ---------- keywords: +patch nosy: +math_foo Added file: http://bugs.python.org/file34938/issue12148.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
Changes by Terry J. Reedy <tjreedy@udel.edu>: ---------- versions: +Python 3.4, Python 3.5 -Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
Roundup Robot added the comment: New changeset 1439619daf42 by Georg Brandl in branch '3.4': Closes #12148: clarify "or's together option flags" in doctest docs. https://hg.python.org/cpython/rev/1439619daf42 ---------- nosy: +python-dev resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________
participants (6)
-
Caelyn McAulay -
ekorn
-
R. David Murray
-
Roundup Robot
-
Terry J. Reedy
-
Éric Araujo