Mailman 3 August 2012 - docs

[issue15569] Doc doc: incorrect description of some roles as format-only
by Éric Araujo Aug. 8, 2012

Aug. 8, 2012

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- assignee: -> docs@python nosy: +docs@python, eric.araujo stage: -> needs patch title: Dev Guide format-only roles -> Doc doc: incorrect description of some roles as format-only _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15569> _______________________________________

1 0

Documentation for Signature, Parameter and signature in inspect module (issue 15151)
by andrew.svetlov＠gmail.com Aug. 8, 2012

Aug. 8, 2012

docs review http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst File Doc/library/inspect.rst (right): http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:432: provide no metadata about their arguments. maybe "metadata for their arguments"? http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:442: a modified copy put dot at end http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:547: **Example** Just remove this line. Bold looks ugly from my perspective http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:607: >>> def foo(a, b=10): Deindent example to avoid gray border around. Not sure. http://bugs.python.org/review/15151/

1 0

[issue15584] os.popen deprecation warning not in Python 3 docs
by Ramchandra Apte Aug. 8, 2012

Aug. 8, 2012

New submission from Ramchandra Apte: The os.popen deprecation warning is not in the Python 3 docs! ---------- assignee: docs@python components: Documentation messages: 167662 nosy: docs@python, ramchandra.apte priority: normal severity: normal status: open title: os.popen deprecation warning not in Python 3 docs _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15584> _______________________________________

2 1

[issue15583] Provide examples in Python doc for usage of various modules
by Sarbjit singh Aug. 8, 2012

Aug. 8, 2012

New submission from Sarbjit singh: For beginners who are learning Python, it would be very helpful if Python doc could provide examples on usage of various methods/attributes of different modules. For eg: If you look at ElementTree XMl module or take any other standard module, examples which are provided are very limited making it hard for new users to learn those modules and have to search internet for its usage. Providing examples on usage of module attributes/methods will help users to quickly understand it. ---------- assignee: docs@python components: Documentation messages: 167657 nosy: Sarbjit.singh, docs@python priority: normal severity: normal status: open title: Provide examples in Python doc for usage of various modules type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15583> _______________________________________

3 2

[issue15572] Python2 documentation of the file() built-in function
by Cherniavsky Beni Aug. 7, 2012

Aug. 7, 2012

New submission from Cherniavsky Beni: [followup for issue 12642 which only fixed it for open()] http://docs.python.org/library/functions.html#file says the arg names are: file(filename[, mode[, bufsize]]) but in practice they are: file(name[, mode[, buffering]]) ---------- assignee: docs@python components: Documentation messages: 167617 nosy: cben, docs@python priority: normal severity: normal status: open title: Python2 documentation of the file() built-in function versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15572> _______________________________________

4 3

[issue15554] correct and clarify str.splitlines() documentation
by Chris Jerdonek Aug. 6, 2012

Aug. 6, 2012

New submission from Chris Jerdonek: The documentation for str.splitlines()-- http://docs.python.org/dev/library/stdtypes.html#str.splitlines includes a statement that is not quite correct: "Unlike split(), if the string ends with line boundary characters the returned list does not have an empty last element." For example, >>> '\n'.splitlines() [''] >>> '\n\n'.splitlines() ['', ''] >>> '\r\n'.splitlines() [''] >>> '\n\r\n'.splitlines() ['', ''] >>> '\r'.splitlines() [''] >>> 'a\n\n'.splitlines() ['a', ''] Also, the note about split() only applies when split() is passed a separator. For example-- >>> 'a\n'.split('\n') ['a', ''] >>> 'a\n'.split() ['a'] Finally, the function's behavior on the empty string is another difference worth mentioning that is not covered by the existing note. I am attaching a patch that addresses these points. Notice also that the patch phrases it not as whether the list *has* an empty last element, but whether an *additional* last element should be added, which is the more important point. ---------- assignee: docs@python components: Documentation files: issue-splitlines-docs-1.patch keywords: easy, patch messages: 167394 nosy: cjerdonek, docs@python, jcea, pitrou priority: normal severity: normal stage: patch review status: open title: correct and clarify str.splitlines() documentation versions: Python 2.7, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file26680/issue-splitlines-docs-1.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15554> _______________________________________

4 14

documention of list member functions
by Jens Odborg Aug. 6, 2012

Aug. 6, 2012

Hi Finding the documentaion of list functions can be a bit trikky You have to remember that members of list are documented not in library documentation but in tutorial It seems to me that more hypeer links are needed There are at least four enties 1) http://docs.python.org/tutorial/introduction.html#lists A general introduction to list No references here * Should also contain a final line like e.g.: "more info on lists in More on Lists" i.e. hyperlink to (2) 2) http://docs.python.org/tutorial/datastructures.html#more-on-lists List all member functions * Should also contain a final line like e.g.: "list creation are documented in Built-in Functions - list" i.e. hyperlink to (4) 3) http://docs.python.org/library/functions.html#list How to create a list This section references two places: a) it self (3) b) Sequence Types (4) * Maybe this should also contain a line in introduktion like e.g.: "lists members are documented in More on Lists" i.e. hyperlink to (2) 4) http://docs.python.org/library/stdtypes.html#typesseq This section reference one place related to list: a) in header list (1) * Should also contain a line like e.g.: "lists members are documented in More on Lists" i.e. hyperlink to (2) Regards Jens

1 0

[issue15482] __import__() change between 3.2 and 3.3
by Ronan Lamy Aug. 6, 2012

Aug. 6, 2012

New submission from Ronan Lamy: I noticed a change in the behaviour of __import__() between 3.2 and 3.3. It looks like in 3.2 __import__() does a Py2-style combo relative/absolute import. Here's a minimal test case: $ ls foo bar.py __init__.py __pycache__ $ cat foo/__init__.py __import__('bar', globals(), locals()) $ python3.3 -c "import foo" Traceback (most recent call last): File "<string>", line 1, in <module> File "./foo/__init__.py", line 1, in <module> __import__('bar', globals(), locals()) ImportError: No module named 'bar' $ python3.2 -c "import foo" $ I believe that 3.3 is correct and that 3.2 is wrong but can't be changed now, so I suppose that 3.2 should just document the actual behaviour of __import__() and 3.3 should document the change. (The context is that I encountered issue 15434. This looks related, but I'm not sure it is.) ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 166706 nosy: Ronan.Lamy, brett.cannon, docs@python, ncoghlan priority: normal severity: normal status: open title: __import__() change between 3.2 and 3.3 versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15482> _______________________________________

7 9

[issue15531] os.path symlink docs missing
by Dave Abrahams Aug. 5, 2012

Aug. 5, 2012

New submission from Dave Abrahams: the docs for os.path don't mention the following facts which I think are important (in fact I assumed the facts would be the reverse): os.path.realpath(l) works when l is a broken symbolic link, returning the path to the (missing) target os.path.readlink(l) causes an error when l is a broken symbolic link. ---------- assignee: docs@python components: Documentation messages: 167163 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: os.path symlink docs missing type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15531> _______________________________________

3 6

Descriptor Example
by dario.damico＠damix.it Aug. 5, 2012

Aug. 5, 2012

Hi everybody, first of all let me thank you for all the work on Python and its community. Regarding the Descriptor Example at http://docs.python.org/howto/descriptor.html I feel like there may be something wrong in the usage of self within setters and getters. According to the following sources: http://stackoverflow.com/questions/1915643/python-descriptors-sharing-value… http://martyalchin.com/2007/nov/23/python-descriptors-part-1-of-2/ http://martyalchin.com/2007/nov/24/python-descriptors-part-2-of-2/ It makes more sense to directly manipulate obj.__dict__ than altering the descriptor. I started studying Python today so I'm definitely a newbie. Sorry if this doesn't make sense. Best regards. Dario D'Amico

1 0