Mailman 3 July 2012 - docs

[issue15270] "Economy of Expression" section outdated
by Tshepang Lekhonkhobe 13 Jul '12

13 Jul '12

Changes by Tshepang Lekhonkhobe <tshepang(a)gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15270> _______________________________________

1 0

[issue15053] imp.lock_held() "Changed in Python 3.3" mention accidentally one function up
by Brett Cannon 13 Jul '12

13 Jul '12

New submission from Brett Cannon <brett(a)python.org>: If you look at http://docs.python.org/dev/py3k/library/imp.html#imp.get_tag you will notice it has the "Changed in Python 3.3" notice for imp.lock_held() in it, the function *below* imp.get_tag(). ---------- assignee: docs@python components: Documentation messages: 162694 nosy: brett.cannon, docs@python, pitrou priority: normal severity: normal stage: needs patch status: open title: imp.lock_held() "Changed in Python 3.3" mention accidentally one function up versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15053> _______________________________________

3 3

[issue14190] Minor C API documentation bugs
by Baruch Sterin 13 Jul '12

13 Jul '12

New submission from Baruch Sterin <python(a)bsterin.com>: The following functions are documented, but do not exist in the code: * PyCodec_KnownEncoding * PyRun_SimpleFileFlags The following function is documented and exists in the code, but is not exposed through any of the header files: PyParser_SimpleParseStringFlagsFilename The prototype in the documentation is incorrect: * PyOS_stricmp returns int, not char* * PyOS_strnicmp returns int, not char* * PyCode_GetNumFree accepts a PyCodeObject* not PyObject* * PyCode_NewEmpty returns a PyCodeObject* not PyObject* * PyFile_SetBufSize accepts a PyObject*, not PyCodeObject * PyGILState_GetThisThreadState returns PyThreadState* not PyThreadState * PyUnicode_EncodeRawUnicodeEscape accepts 2, not 3 arguments * PyUnicode_RichCompare returns PyObject*, not int * PyType_IS_GC needs a PyTypeObject*, not PyObject* * PyType_HasFeature needs a PyTypeObject*, not PyObject* In addition, PyLong_FromSsize_t and PyLong_FromSsize_t are documented twice in long.html. ---------- assignee: docs@python components: Documentation messages: 154879 nosy: baruch.sterin, docs@python priority: normal severity: normal status: open title: Minor C API documentation bugs type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14190> _______________________________________

4 8

[issue13686] Some notes on the docs of multiprocessing
by Eli Bendersky 13 Jul '12

13 Jul '12

New submission from Eli Bendersky <eliben(a)gmail.com>: I've decided to study the multiprocessing module a bit, and carefully went over the docs (for 2.7). Some small fixes I will commit myself, but a few issues came up on which I'd like some opinion from others. In rough order of appearance in the doc: 1. In the documentation of the 'name' argument of the multiprocessing.Process constructor, it mentions that the length of the generated name depends on the "generation", without elaborating. It could be better to briefly describe the algorithm in a sentence or two. 2. Section 16.6.2.1. is called "Process and exceptions". It only documents one exception from multiprocessing: BufferTooShort. Other exception classes exported by the module aren't documented similarly: ProcessError, TiemoutError, AuthenticationError. 3. AuthenticationError is documented as multiprocessing.connection.AuthenticationError, although in reality it exists in the root multiprocessing module, and multiprocessing.connection just imports it 4. The doc of JoinableQueue.task_done() says "Used by queue consumer threads". Shouldn't that be "consumer processes"? 5. The doc of active_children() should probably mention that it returns a list of Process objects (similarly to what current_process() says) 6. multiprocessing.freeze_support() says "If the freeze_support() line is omitted then trying to run the frozen executable will raise RuntimeError.". *Who* will raise the error? 7. class multiprocessing.Event says "This method returns..." - what method? Seems like an irrelevant documentation piece was intermixed here 8. 16.6.2.7. Managers starts by saying that Managers provide a way to create data which can be shared between different processes. Since it comes right after the section about Shared objects, I think it would be nice to mention in a sentence or two what Managers give above normal synchonized objects in multiprocessing (i.e. sharing between different machines) 9. In the programming guidelines about "Avoid shared state" it says "It is probably best to stick to using queues or pipes for communication between processes rather than using the lower level synchronization primitives from the threading module.". Surely not the "threading" module is meant here? ---------- assignee: docs@python components: Documentation messages: 150409 nosy: docs@python, eli.bendersky, pitrou priority: normal severity: normal status: open title: Some notes on the docs of multiprocessing type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13686> _______________________________________

4 7

[issue12600] Add example of using load_tests to parameterise Test Cases
by florian-rathgeber 11 Jul '12

11 Jul '12

Changes by florian-rathgeber <florian.rathgeber(a)gmail.com>: ---------- nosy: +florian-rathgeber _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12600> _______________________________________

1 0

In difflib module name of the parameters for *_diff methods can be descriptive
by Sateesh Kumar 10 Jul '12

10 Jul '12

In the 'difflib' module the signature of the method context_diff is as below: difflib.context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) As per the documentation 'fromfile' and 'tofile' are used as names of the headers in the report generated.It is expected that the user specifies names of the files as arguments for optional parameters 'fromfile' and 'tofile'. But name of the parameter 'fromfile' ('tofile') is bit confusing as it doesn't give a clear indication that what is expected is a name of a file (and not a fileobject). So it is better to rename these parameters as 'fromfilename' and 'tofilename' which will also be in sync with other parameter names ('fromfiledate','tofiledate'). Similar change can be done in method 'difflib.unified_diff'. I am referring to documentation of this module in Python 2.7.3 http://docs.python.org/library/difflib.html thanks, sateesh

1 0

[issue15288] Clarify the pkgutil.walk_packages() note
by Chris Jerdonek 09 Jul '12

09 Jul '12

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: The note at the end of the pkgutil.walk_packages() (and iter_modules()) documentation can be improved somewhat: http://docs.python.org/dev/library/pkgutil.html#pkgutil.walk_packages For example, "importers" aren't referenced earlier in the documentation of the function, so it's not immediately clear what they are referring to. I also think that enough information should be given so that one can run the examples given and have them work. They currently don't. I can put together proposed wording. See the issue 14982 discussion for background. ---------- assignee: docs@python components: Documentation keywords: easy messages: 164916 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: Clarify the pkgutil.walk_packages() note versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15288> _______________________________________

4 5

[issue15297] pkgutil.iter_importers() includes an ImpImporter
by Chris Jerdonek 09 Jul '12

09 Jul '12

Chris Jerdonek <chris.jerdonek(a)gmail.com> added the comment: Marking this a documentation issue because the same behavior is also present in 2.7: Python 2.7.3 (default, Apr 19 2012, 00:55:09) [GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)] on darwin >>> from pkgutil import iter_importers >>> list(iter_importers())[-1] <pkgutil.ImpImporter instance at 0x10517b710> ---------- assignee: -> docs@python components: +Documentation -Library (Lib) keywords: +easy nosy: +docs@python versions: +Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15297> _______________________________________

1 0

Re: [docs] give more meaningful argument names in argparse documentation (issue 11176)
by ezio.melotti＠gmail.com 09 Jul '12

09 Jul '12

http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst File Doc/library/argparse.rst (right): http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:40: parser.add_argument('-f', '--file', type=str, default="/usr/share/dict/words", Not sure it's a good idea to provide a default here (especially one that doesn't work on all the operative systems). http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:70: text_file_lines.extend(text_file.readlines()) # start at "line 1" I would keep the lines starting from 0, and use the with statement: with open(args.file) as f: lines = list(f) http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:74: lines_to_print = (text_file_lines[args.line_numbers[0]]), Did you mean to put the comma inside the ()? http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:78: lines_to_print = itemgetter(*args.line_numbers)(text_file_lines) This is a bit tricky, I would use something like: [line for n,line in enumerate(lines) if n in args.line_numbers]? http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:84: print('Line #{0}: {1}'.format(args.line_numbers[i], line), end="") The 0 and 1 are unnecessary. http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:207: >>> pizza_parser = argparse.ArgumentParser( /me approves pizza http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:472: ... help='the sauce to use') This should be indented under the first ' of the previous line. http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:495: ... help="how man slices the pizza will be cut up into") Why a float? can you cut 7.9 slices? http://bugs.python.org/review/11176/diff/5362/Doc/library/argparse.rst#newc… Doc/library/argparse.rst:1125: >>> pizza_parser.add_argument('slices', nargs='?', type=int, default=10, The default here should be 8. http://bugs.python.org/review/11176/

1 0

[issue15270] "Economy of Expression" section outdated
by Éric Araujo 09 Jul '12

09 Jul '12

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- nosy: +eric.araujo _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15270> _______________________________________

1 0