From sandro.tosi at gmail.com  Tue Nov  1 10:37:12 2011
From: sandro.tosi at gmail.com (Sandro Tosi)
Date: Tue, 1 Nov 2011 10:37:12 +0100
Subject: [docs] A bug in the datetime module documentation
In-Reply-To: <CAFMS1CV5LM185rj=rpCbG7+tvY7qdMjazFPV34CThZ4ZxXm7zA@mail.gmail.com>
References: <CAFMS1CV5LM185rj=rpCbG7+tvY7qdMjazFPV34CThZ4ZxXm7zA@mail.gmail.com>
Message-ID: <CAPdtAj2nZGWMkj6eYyuxcwtGMV+zJ2UgmprFanWjwjke4US4UA@mail.gmail.com>

Hello Daniil,
thanks for your email.

On Sun, Oct 30, 2011 at 12:59, Daniil Shved <danshved at gmail.com> wrote:
> Hi there,
>
> I found what seems to be an error in the python 2.7.2 docs for "datetime"
> module:
>
> http://docs.python.org/library/datetime.html?highlight=datetime#tzinfo-objects
>
> In the documentation for method tzinfo.dst(self, dt) there are two code
> samples (under "most implementations of dst() will probably look like one of
> these two"). In these code samples the method is defined as "def
> dst(self):", but it should be "def dst(self, dt)".

I've just fixed it.

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

From sandro.tosi at gmail.com  Tue Nov  1 10:40:46 2011
From: sandro.tosi at gmail.com (Sandro Tosi)
Date: Tue, 1 Nov 2011 10:40:46 +0100
Subject: [docs] Python docs bug in 2.6 - 'as' is now a reserved keyword
In-Reply-To: <85B83C6EA7793D4884BF2179AC55EB1B2C23DB94@ENFICSMBX1.datcon.co.uk>
References: <85B83C6EA7793D4884BF2179AC55EB1B2C23DB94@ENFICSMBX1.datcon.co.uk>
Message-ID: <CAPdtAj3R0QDTvUZERYH=FdA5C49yTHvrHZRqi2=szjX=ZW0a8Q@mail.gmail.com>

Hello Tim,

On Mon, Oct 31, 2011 at 15:32, Tim Bellis <Tim.Bellis at metaswitch.com> wrote:
> http://docs.python.org/whatsnew/2.6.html#porting-to-python-2-6 doesn?t
> mention that ?as? is now a reserved keyword in Python 2.6 and so any
> variables named ?as? will need to be renamed.

2.6 is in security-only fixes status, so we can't fix this kind of bugs.

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

From report at bugs.python.org  Tue Nov  1 15:07:11 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 01 Nov 2011 14:07:11 +0000
Subject: [docs] [issue13302] Clarification needed in C API arg parsing
In-Reply-To: <1320057763.71.0.58387430149.issue13302@psf.upfronthosting.co.za>
Message-ID: <1320156431.44.0.975152156322.issue13302@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

It's already in the 3.x docs (but not 2.x):

?Strings and buffers

These formats allow to access an object as a contiguous chunk of memory. You don?t have to provide raw storage for the returned unicode or bytes area. Also, you won?t have to release any memory yourself, except with the es, es#, et and et# formats.?

http://docs.python.org/dev/c-api/arg.html#strings-and-buffers

----------
nosy: +pitrou

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13302>
_______________________________________

From report at bugs.python.org  Wed Nov  2 08:41:34 2011
From: report at bugs.python.org (Jyrki Pulliainen)
Date: Wed, 02 Nov 2011 07:41:34 +0000
Subject: [docs] [issue13147] Multiprocessing Pool.map_async() does not have
	an	error_callback parameter
In-Reply-To: <1318289870.89.0.681252830912.issue13147@psf.upfronthosting.co.za>
Message-ID: <1320219694.73.0.248776060968.issue13147@psf.upfronthosting.co.za>


Jyrki Pulliainen <jyrki at dywypi.org> added the comment:

Python 3.x seems to have the error_callback parameter on all *_async operations. However, 2.7 lacks it. I think adding the actual error_callback would be deemed as a new feature, so the right thing would just be removing the documentation.

I'll whip up a patch to remove this from the documentation

----------
nosy: +nailor

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13147>
_______________________________________

From report at bugs.python.org  Wed Nov  2 08:50:01 2011
From: report at bugs.python.org (Jyrki Pulliainen)
Date: Wed, 02 Nov 2011 07:50:01 +0000
Subject: [docs] [issue13147] Multiprocessing Pool.map_async() does not have
	an	error_callback parameter
In-Reply-To: <1318289870.89.0.681252830912.issue13147@psf.upfronthosting.co.za>
Message-ID: <1320220201.61.0.204516555811.issue13147@psf.upfronthosting.co.za>


Jyrki Pulliainen <jyrki at dywypi.org> added the comment:

Patch attached. This patch removes the error_callback from 2.7's documentation.

----------
keywords: +patch
Added file: http://bugs.python.org/file23589/issue13147.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13147>
_______________________________________

From report at bugs.python.org  Wed Nov  2 08:53:07 2011
From: report at bugs.python.org (Jyrki Pulliainen)
Date: Wed, 02 Nov 2011 07:53:07 +0000
Subject: [docs] [issue13147] Multiprocessing Pool.map_async() does not have
	an	error_callback parameter
In-Reply-To: <1318289870.89.0.681252830912.issue13147@psf.upfronthosting.co.za>
Message-ID: <1320220387.31.0.743737905258.issue13147@psf.upfronthosting.co.za>


Jyrki Pulliainen <jyrki at dywypi.org> added the comment:

Also: note that 2.6 does not document this error_callback, so the issue is present only in 2.7

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13147>
_______________________________________

From report at bugs.python.org  Wed Nov  2 08:55:08 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Wed, 02 Nov 2011 07:55:08 +0000
Subject: [docs] [issue13147] Multiprocessing Pool.map_async() does not have
	an	error_callback parameter
In-Reply-To: <1318289870.89.0.681252830912.issue13147@psf.upfronthosting.co.za>
Message-ID: <1320220508.67.0.833546592825.issue13147@psf.upfronthosting.co.za>


Changes by Petri Lehtinen <petri at digip.org>:


----------
keywords: +needs review
nosy: +petri.lehtinen
stage:  -> patch review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13147>
_______________________________________

From report at bugs.python.org  Wed Nov  2 09:24:16 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Wed, 02 Nov 2011 08:24:16 +0000
Subject: [docs] [issue12709] In multiprocessing,
	error_callback isn't documented for map_async
In-Reply-To: <1312798209.69.0.295149725931.issue12709@psf.upfronthosting.co.za>
Message-ID: <1320222256.58.0.43519095861.issue12709@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

Sandro: The error_callback parameter is not available on 2.7. See #13147.

----------
nosy: +petri.lehtinen

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12709>
_______________________________________

From report at bugs.python.org  Wed Nov  2 19:03:45 2011
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 02 Nov 2011 18:03:45 +0000
Subject: [docs] [issue13147] Multiprocessing Pool.map_async() does not have
	an	error_callback parameter
In-Reply-To: <1318289870.89.0.681252830912.issue13147@psf.upfronthosting.co.za>
Message-ID: <E1RLfA0-0000cE-VN@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 37e34a983d6d by Senthil Kumaran in branch '2.7':
Fix Issue13147 - Correct the Multiprocessing Pool.map_async method signature.
http://hg.python.org/cpython/rev/37e34a983d6d

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13147>
_______________________________________

From report at bugs.python.org  Wed Nov  2 19:04:54 2011
From: report at bugs.python.org (Senthil Kumaran)
Date: Wed, 02 Nov 2011 18:04:54 +0000
Subject: [docs] [issue13147] Multiprocessing Pool.map_async() does not have
	an	error_callback parameter
In-Reply-To: <1318289870.89.0.681252830912.issue13147@psf.upfronthosting.co.za>
Message-ID: <1320257094.79.0.620882923831.issue13147@psf.upfronthosting.co.za>


Senthil Kumaran <senthil at uthcode.com> added the comment:

Thanks for the report, Jakub and for the patch, Jyrki

----------
nosy: +orsenthil
resolution:  -> fixed
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13147>
_______________________________________

From report at bugs.python.org  Thu Nov  3 21:20:49 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Thu, 03 Nov 2011 20:20:49 +0000
Subject: [docs] [issue13305] datetime.strftime("%Y") not consistent for
	years < 1000
In-Reply-To: <1320091957.61.0.759691422668.issue13305@psf.upfronthosting.co.za>
Message-ID: <1320351649.51.0.916134076248.issue13305@psf.upfronthosting.co.za>


Florent Xicluna <florent.xicluna at gmail.com> added the comment:

I understand that the issue is because the C standard does not specify the length of the string returned by '%Y'.

The changeset 230f0956aaa3 adds a test to verify that either '%Y' or '%4Y' returns a 4-digits value usable to produce ISO-8601 representations.

Now it is a documentation issue: add a comment to the "%Y" specifier saying that the padding is not applicable to all platforms and in such case the "%4Y" specifier should return the 4-digit value.

----------
assignee:  -> docs at python
components: +Documentation
dependencies:  -external strftime for Python?
nosy: +docs at python
superseder:  -> external strftime for Python?

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13305>
_______________________________________

From report at bugs.python.org  Thu Nov  3 21:30:17 2011
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 03 Nov 2011 20:30:17 +0000
Subject: [docs] [issue13305] datetime.strftime("%Y") not consistent for
	years < 1000
In-Reply-To: <1320091957.61.0.759691422668.issue13305@psf.upfronthosting.co.za>
Message-ID: <1320352217.17.0.0694751160331.issue13305@psf.upfronthosting.co.za>


STINNER Victor <victor.stinner at haypocalc.com> added the comment:

Since the changeset 55a3b563f0dbed04af317f632f7f3c0f6abe175b, test_strptime is failing on "AMD64 Gentoo Wide 3.x" buildbot:

======================================================================
FAIL: test_strptime (test.test_time.TimeTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/Lib/test/test_time.py", line 159, in test_strptime
    time.strptime(strf_output, format)
ValueError: time data 'LMT' does not match format '%Z'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/Lib/test/test_time.py", line 162, in test_strptime
    (format, strf_output))
AssertionError: conversion specifier '%Z' failed with 'LMT' input.

----------------------------------------------------------------------

http://www.python.org/dev/buildbot/all/builders/AMD64%20Gentoo%20Wide%203.x/builds/2661

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13305>
_______________________________________

From report at bugs.python.org  Thu Nov  3 21:39:43 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Thu, 03 Nov 2011 20:39:43 +0000
Subject: [docs] [issue13305] datetime.strftime("%Y") not consistent for
	years < 1000
In-Reply-To: <1320091957.61.0.759691422668.issue13305@psf.upfronthosting.co.za>
Message-ID: <1320352783.86.0.848819243964.issue13305@psf.upfronthosting.co.za>


Florent Xicluna <florent.xicluna at gmail.com> added the comment:

other test_time related errors are followed with issue 13309, issue 13312 and issue 13313

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13305>
_______________________________________

From report at bugs.python.org  Fri Nov  4 14:20:14 2011
From: report at bugs.python.org (Ilya Novoselov)
Date: Fri, 04 Nov 2011 13:20:14 +0000
Subject: [docs] [issue13341] Incorrect documentation for "u" PyArg_Parse
	format unit
Message-ID: <1320412814.48.0.657162308895.issue13341@psf.upfronthosting.co.za>


New submission from Ilya Novoselov <ilya.novoselov at gmail.com>:

Documentation states that u format unit returns "buffer of 16-bit Unicode (UTF-16) data" while it returns pointer to internal buffer of unicode data, which is either UCS-16 or UCS-32

http://docs.python.org/c-api/arg.html

----------
assignee: docs at python
components: Documentation, Unicode
messages: 147002
nosy: Ilya.Novoselov, docs at python, ezio.melotti
priority: normal
severity: normal
status: open
title: Incorrect documentation for "u" PyArg_Parse format unit
type: behavior
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________

From report at bugs.python.org  Fri Nov  4 20:11:10 2011
From: report at bugs.python.org (STINNER Victor)
Date: Fri, 04 Nov 2011 19:11:10 +0000
Subject: [docs] [issue13341] Incorrect documentation for "u" PyArg_Parse
	format unit
In-Reply-To: <1320412814.48.0.657162308895.issue13341@psf.upfronthosting.co.za>
Message-ID: <1320433870.44.0.68058791537.issue13341@psf.upfronthosting.co.za>


STINNER Victor <victor.stinner at haypocalc.com> added the comment:

Can you write a patch?

----------
nosy: +haypo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________

From report at bugs.python.org  Fri Nov  4 23:40:54 2011
From: report at bugs.python.org (Ilya Novoselov)
Date: Fri, 04 Nov 2011 22:40:54 +0000
Subject: [docs] [issue13341] Incorrect documentation for "u" PyArg_Parse
	format unit
In-Reply-To: <1320412814.48.0.657162308895.issue13341@psf.upfronthosting.co.za>
Message-ID: <1320446454.25.0.884640941198.issue13341@psf.upfronthosting.co.za>


Ilya Novoselov <ilya.novoselov at gmail.com> added the comment:

No, I don't feel like I'm up to standard yet.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________

From report at bugs.python.org  Sat Nov  5 01:19:22 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 05 Nov 2011 00:19:22 +0000
Subject: [docs] [issue3067] setlocale error message is confusing
In-Reply-To: <1213013354.87.0.861327880823.issue3067@psf.upfronthosting.co.za>
Message-ID: <1320452361.93.0.974665406954.issue3067@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

Yes. I think in locale.rst (assuming that is the name)
'''
exception locale.Error 
Exception raised when setlocale() fails.

locale.setlocale(category, locale=None) 
If *locale* is specified, it may be a string, a tuple of the form (language code, encoding), or None. If it is a tuple, it is converted to a string using the locale aliasing engine.
'''
should be changed to
'''
exception locale.Error 
Exception raised when the locale passed to setlocale() is not recognized.

locale.setlocale(category, locale=None) 
If *locale* is specified, it may be a None, a string, or an iterable of two strings, language code and encoding. String pairs are converted to a single string using the locale aliasing engine.
'''
where language code and encoding are gray shaded as they are now.

----------
assignee:  -> docs at python
components: +Documentation -Library (Lib), Unicode
nosy: +docs at python
status: pending -> open

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3067>
_______________________________________

From report at bugs.python.org  Sat Nov  5 05:11:59 2011
From: report at bugs.python.org (Mike Hoy)
Date: Sat, 05 Nov 2011 04:11:59 +0000
Subject: [docs] [issue13341] Incorrect documentation for "u" PyArg_Parse
	format unit
In-Reply-To: <1320412814.48.0.657162308895.issue13341@psf.upfronthosting.co.za>
Message-ID: <1320466319.53.0.491089879622.issue13341@psf.upfronthosting.co.za>


Changes by Mike Hoy <mhoy09 at gmail.com>:


----------
nosy: +mikehoy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________

From report at bugs.python.org  Sat Nov  5 08:24:04 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Sat, 05 Nov 2011 07:24:04 +0000
Subject: [docs] [issue3067] setlocale error message is confusing
In-Reply-To: <1320452361.93.0.974665406954.issue3067@psf.upfronthosting.co.za>
Message-ID: <20111105072351.GA1970@ihaa>


Petri Lehtinen <petri at digip.org> added the comment:

> If *locale* is specified, it may be a None, a string, or an iterable of two strings, language code and encoding. String pairs are converted to a single string using the locale aliasing engine.

What about the possible None value then? Do you think that mentions to
it be dropped?

I don't think so, because setlocale(locale.LC_ALL, None) is an
explicit way of saying "Return me the current value", especially
because the function's name is SETlocale, which doesn't make it
explicit.

If None is not dropped, the ", language code and encoding" should
maybe be in parentheses insteead: "to strings (language code and
encoding), or None..."

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3067>
_______________________________________

From report at bugs.python.org  Sat Nov  5 08:30:08 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 05 Nov 2011 07:30:08 +0000
Subject: [docs] [issue3067] setlocale error message is confusing
In-Reply-To: <1213013354.87.0.861327880823.issue3067@psf.upfronthosting.co.za>
Message-ID: <1320478208.37.0.782501025752.issue3067@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

Yes, parentheses would be better.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3067>
_______________________________________

From report at bugs.python.org  Sat Nov  5 09:25:15 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 05 Nov 2011 08:25:15 +0000
Subject: [docs] [issue3067] setlocale error message is confusing
In-Reply-To: <1213013354.87.0.861327880823.issue3067@psf.upfronthosting.co.za>
Message-ID: <E1RMbYo-0004xR-Cz@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 34c9465f5023 by Petri Lehtinen in branch '2.7':
Issue #3067: Enhance the documentation and docstring of locale.setlocale()
http://hg.python.org/cpython/rev/34c9465f5023

New changeset 98806dd03506 by Petri Lehtinen in branch '3.2':
Issue #3067: Enhance the documentation and docstring of locale.setlocale()
http://hg.python.org/cpython/rev/98806dd03506

New changeset 8a27920efffe by Petri Lehtinen in branch 'default':
Issue #3067: Enhance the documentation and docstring of locale.setlocale()
http://hg.python.org/cpython/rev/8a27920efffe

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3067>
_______________________________________

From report at bugs.python.org  Sat Nov  5 09:28:26 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Sat, 05 Nov 2011 08:28:26 +0000
Subject: [docs] [issue3067] setlocale error message is confusing
In-Reply-To: <1213013354.87.0.861327880823.issue3067@psf.upfronthosting.co.za>
Message-ID: <1320481706.37.0.737239387835.issue3067@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

I decided to restructure the documentation of setlocale() a bit and I think it's better now overall. It includes Terry's suggestions.

I think this issue can now be closed. Thanks for the report and patches!

----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3067>
_______________________________________

From Daniel.Dieterle at comsoft.aero  Wed Nov  2 13:46:21 2011
From: Daniel.Dieterle at comsoft.aero (Dieterle, Daniel)
Date: Wed, 2 Nov 2011 13:46:21 +0100
Subject: [docs] Bug in documentation of module subprocess, method send_signal
Message-ID: <B8940AF89405544998A30624A584065FCD3012@CSMAIL.cs-nt-domaene.de>

Hi,

in the documentation
(http://docs.python.org/library/subprocess.html#subprocess.Popen.send_si
gnal) is a bug.

CTRL_C_EVENT can not be sent to processes started with a creationflags
parameter which includes CREATE_NEW_PROCESS_GROUP. Why can be read in
the msdn documentation
http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.
85%29.aspx .

A workaround using CTRL_C_EVENT nevertheless is described here:
http://stackoverflow.com/questions/7085604/sending-c-to-python-subproces
s-objects-on-windows/7980368#7980368
	
Bye,
Daniel.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111102/245a4399/attachment.html>

From silentsound at gmail.com  Thu Nov  3 00:40:50 2011
From: silentsound at gmail.com (Yoann Roman)
Date: Wed, 2 Nov 2011 16:40:50 -0700
Subject: [docs] Error in logging.handlers.TimedRotatingFileHandler for 2.7
Message-ID: <CALK4Bv5m_EYOFoh-wFbKEhn7neei9vdSu1sB0EyWkGtMDPy18A@mail.gmail.com>

The docs for logging.handlers.TimedRotatingFileHandler in Python 2.7 say
that the "utc" keyword argument was added in 2.7:
http://docs.python.org/library/logging.handlers.html#timedrotatingfilehandler

This isn't correct, however, since it was available as of 2.6 (I verified
the source as well):
http://docs.python.org/release/2.6/library/logging.html#timedrotatingfilehandler

It did appear to change to True/False in 2.7 instead of 0/1 in 2.6. I'd
recommend changing it to indicate this or removing the fact that this was
added in 2.7 altogether.

Thanks!

Yoann
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111102/5b41ad17/attachment.html>

From peltoju at gmail.com  Fri Nov  4 06:42:04 2011
From: peltoju at gmail.com (Jussi Peltonen)
Date: Fri, 4 Nov 2011 07:42:04 +0200
Subject: [docs] Document bug?
Message-ID: <CACDOErUWoZ_8j7us0kk9uYVB0U+W=oWqNUnXe=PkgQrBs-JQUw@mail.gmail.com>

Hello,

http://docs.python.org/tutorial/classes.html#instance-objects

I think the "counter" attribute is mentioned for the first time in the
example code, not "in Instance of MyClass created above", i.e. class
MyClass does not contain "counter" attribute.

"x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print x.counter
del x.counter"

Best Regards,
Jussi Peltonen

From report at bugs.python.org  Sat Nov  5 17:21:26 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 05 Nov 2011 16:21:26 +0000
Subject: [docs] [issue13292] missing versionadded for bytearray
In-Reply-To: <1319975533.88.0.431386848219.issue13292@psf.upfronthosting.co.za>
Message-ID: <1320510086.3.0.395057924313.issue13292@psf.upfronthosting.co.za>


Changes by ?ric Araujo <merwok at netwok.org>:


----------
assignee: docs at python -> eric.araujo
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13292>
_______________________________________

From report at bugs.python.org  Sat Nov  5 21:05:01 2011
From: report at bugs.python.org (Eric Snow)
Date: Sat, 05 Nov 2011 20:05:01 +0000
Subject: [docs] [issue10977] Concrete object C API considered harmful to
	subclasses	of builtin types
In-Reply-To: <1295653779.62.0.836506069174.issue10977@psf.upfronthosting.co.za>
Message-ID: <1320523501.58.0.643517254002.issue10977@psf.upfronthosting.co.za>


Changes by Eric Snow <ericsnowcurrently at gmail.com>:


----------
nosy: +eric.snow

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10977>
_______________________________________

From report at bugs.python.org  Sun Nov  6 04:05:55 2011
From: report at bugs.python.org (Meador Inge)
Date: Sun, 06 Nov 2011 03:05:55 +0000
Subject: [docs] [issue10977] Concrete object C API considered harmful to
	subclasses	of builtin types
In-Reply-To: <1295653779.62.0.836506069174.issue10977@psf.upfronthosting.co.za>
Message-ID: <1320548755.35.0.4715832269.issue10977@psf.upfronthosting.co.za>


Changes by Meador Inge <meadori at gmail.com>:


----------
nosy: +meador.inge

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10977>
_______________________________________

From report at bugs.python.org  Sun Nov  6 04:21:38 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 06 Nov 2011 03:21:38 +0000
Subject: [docs] [issue13352] tutorial section 9.3.3 documentation problem
Message-ID: <1320549698.37.0.353874550901.issue13352@psf.upfronthosting.co.za>


New submission from Eli Bendersky <eliben at gmail.com>:

User report on the docs@ list:

-----

http://docs.python.org/tutorial/classes.html#instance-objects

I think the "counter" attribute is mentioned for the first time in the
example code, not "in Instance of MyClass created above", i.e. class
MyClass does not contain "counter" attribute.

"x.counter = 1
while x.counter < 10:
   x.counter = x.counter * 2
print x.counter
del x.counter"

Best Regards,
Jussi Peltonen

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 147137
nosy: docs at python, eli.bendersky
priority: normal
severity: normal
status: open
title: tutorial section 9.3.3 documentation problem
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13352>
_______________________________________

From eliben at gmail.com  Sun Nov  6 04:22:03 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Sun, 6 Nov 2011 05:22:03 +0200
Subject: [docs] Document bug?
In-Reply-To: <CACDOErUWoZ_8j7us0kk9uYVB0U+W=oWqNUnXe=PkgQrBs-JQUw@mail.gmail.com>
References: <CACDOErUWoZ_8j7us0kk9uYVB0U+W=oWqNUnXe=PkgQrBs-JQUw@mail.gmail.com>
Message-ID: <CAF-Rda_v=MewWR7MOrLoLRWPbe4h+L+uWSysRq6KUiv_5sATjg@mail.gmail.com>

Hello Jussi,

Thanks for the report. I have opened Issue 13352 to track this -
http://bugs.python.org/issue13352

Eli


On Fri, Nov 4, 2011 at 07:42, Jussi Peltonen <peltoju at gmail.com> wrote:

> Hello,
>
> http://docs.python.org/tutorial/classes.html#instance-objects
>
> I think the "counter" attribute is mentioned for the first time in the
> example code, not "in Instance of MyClass created above", i.e. class
> MyClass does not contain "counter" attribute.
>
> "x.counter = 1
> while x.counter < 10:
>    x.counter = x.counter * 2
> print x.counter
> del x.counter"
>
> Best Regards,
> Jussi Peltonen
> _______________________________________________
> docs mailing list
> docs at python.org
> http://mail.python.org/mailman/listinfo/docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111106/b96b67a7/attachment.html>

From report at bugs.python.org  Sun Nov  6 04:24:02 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 06 Nov 2011 03:24:02 +0000
Subject: [docs] [issue13353] documentation problem
	in	logging.handlers.TimedRotatingFileHandler for 2.7
Message-ID: <1320549842.11.0.772766831495.issue13353@psf.upfronthosting.co.za>


New submission from Eli Bendersky <eliben at gmail.com>:

User (Yoann Roman) report on docs@ maillist:

----

The docs for logging.handlers.TimedRotatingFileHandler in Python 2.7 say that the "utc" keyword argument was added in 2.7:
http://docs.python.org/library/logging.handlers.html#timedrotatingfilehandler

This isn't correct, however, since it was available as of 2.6 (I verified the source as well):
http://docs.python.org/release/2.6/library/logging.html#timedrotatingfilehandler

It did appear to change to True/False in 2.7 instead of 0/1 in 2.6. I'd recommend changing it to indicate this or removing the fact that this was added in 2.7 altogether.

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 147138
nosy: docs at python, eli.bendersky
priority: low
severity: normal
status: open
title: documentation problem in logging.handlers.TimedRotatingFileHandler for 2.7
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13353>
_______________________________________

From eliben at gmail.com  Sun Nov  6 04:24:27 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Sun, 6 Nov 2011 05:24:27 +0200
Subject: [docs] Error in logging.handlers.TimedRotatingFileHandler for
	2.7
In-Reply-To: <CALK4Bv5m_EYOFoh-wFbKEhn7neei9vdSu1sB0EyWkGtMDPy18A@mail.gmail.com>
References: <CALK4Bv5m_EYOFoh-wFbKEhn7neei9vdSu1sB0EyWkGtMDPy18A@mail.gmail.com>
Message-ID: <CAF-Rda8KJ+MZAedjrM-3_XpbGULC2oQ2_Nrm77LeAEu9tEkP+g@mail.gmail.com>

On Thu, Nov 3, 2011 at 01:40, Yoann Roman <silentsound at gmail.com> wrote:

> The docs for logging.handlers.TimedRotatingFileHandler in Python 2.7 say
> that the "utc" keyword argument was added in 2.7:
>
> http://docs.python.org/library/logging.handlers.html#timedrotatingfilehandler
>
> This isn't correct, however, since it was available as of 2.6 (I verified
> the source as well):
>
> http://docs.python.org/release/2.6/library/logging.html#timedrotatingfilehandler
>
> It did appear to change to True/False in 2.7 instead of 0/1 in 2.6. I'd
> recommend changing it to indicate this or removing the fact that this was
> added in 2.7 altogether.
>
> Thanks!
>
>
Hello Yoann,

Thanks for the report. I have opened issue 13353 to track this -
http://bugs.python.org/issue13353

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111106/fedc115e/attachment-0001.html>

From eliben at gmail.com  Sun Nov  6 04:28:29 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Sun, 6 Nov 2011 05:28:29 +0200
Subject: [docs] Bug in documentation of module subprocess,
	method send_signal
In-Reply-To: <B8940AF89405544998A30624A584065FCD3012@CSMAIL.cs-nt-domaene.de>
References: <B8940AF89405544998A30624A584065FCD3012@CSMAIL.cs-nt-domaene.de>
Message-ID: <CAF-Rda9SRh6hG968aTa0zMdyFVpk9-6jrv5DB9T7K8FZWDcHeA@mail.gmail.com>

>
>
> in the documentation (*
> http://docs.python.org/library/subprocess.html#subprocess.Popen.send_signal
> *<http://docs.python.org/library/subprocess.html#subprocess.Popen.send_signal>)
> is a bug.
>
> CTRL_C_EVENT can not be sent to processes started with a creationflags
> parameter which includes* CREATE_NEW_PROCESS_GROUP*. Why can be read in
> the msdn documentation *
> http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%29.aspx
> *<http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%29.aspx>.
>
> A workaround using CTRL_C_EVENT nevertheless is described here:
> *
> http://stackoverflow.com/questions/7085604/sending-c-to-python-subprocess-objects-on-windows/7980368#7980368
> *<http://stackoverflow.com/questions/7085604/sending-c-to-python-subprocess-objects-on-windows/7980368#7980368>
>
>

Hi Daniel,

If what you say is true (and I assume it is), it may be a problem with the
implementation, not only the documentation. Could you perchance reproduce
this? Perhaps an actual bug report on subprocess should be opened, and not
only a documentation fix.

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111106/c82a2bf6/attachment.html>

From report at bugs.python.org  Sun Nov  6 05:01:35 2011
From: report at bugs.python.org (Ori Livneh)
Date: Sun, 06 Nov 2011 04:01:35 +0000
Subject: [docs] [issue13352] tutorial section 9.3.3 documentation problem
In-Reply-To: <1320549698.37.0.353874550901.issue13352@psf.upfronthosting.co.za>
Message-ID: <1320552095.25.0.87455308939.issue13352@psf.upfronthosting.co.za>


Ori Livneh <ori.livneh at gmail.com> added the comment:

That's exactly the point: in Python, data attributes don't need to be declared in the class definition.

----------
nosy: +ori.livneh

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13352>
_______________________________________

From report at bugs.python.org  Sun Nov  6 05:06:47 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 06 Nov 2011 04:06:47 +0000
Subject: [docs] [issue13352] tutorial section 9.3.3 documentation problem
In-Reply-To: <1320549698.37.0.353874550901.issue13352@psf.upfronthosting.co.za>
Message-ID: <1320552407.66.0.684409267019.issue13352@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Yep, I agree, Ori.

The paragraph immediately preceding the code sample says:

    "Data attributes need not be declared; like local variables, they spring into existence when they are first assigned to [...] the following piece of code will print the value 16, without leaving a trace"

Which is what the code sample demonstrates.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13352>
_______________________________________

From report at bugs.python.org  Sun Nov  6 05:07:24 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 06 Nov 2011 04:07:24 +0000
Subject: [docs] [issue13352] tutorial section 9.3.3 documentation problem
In-Reply-To: <1320549698.37.0.353874550901.issue13352@psf.upfronthosting.co.za>
Message-ID: <1320552444.66.0.959250153538.issue13352@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
resolution:  -> invalid
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13352>
_______________________________________

From report at bugs.python.org  Sun Nov  6 10:10:11 2011
From: report at bugs.python.org (Bas Wijnen)
Date: Sun, 06 Nov 2011 09:10:11 +0000
Subject: [docs] [issue13354] tcpserver should document non-threaded
	long-living	connections
Message-ID: <1320570611.72.0.286817751979.issue13354@psf.upfronthosting.co.za>


New submission from Bas Wijnen <wijnen at debian.org>:

http://docs.python.org/py3k/library/socketserver.html says:

The solution is to create a separate process or thread to handle each request; the ForkingMixIn and ThreadingMixIn mix-in classes can be used to support asynchronous behaviour.

There is another way, which doesn't bring multi-threading hell over you: keep a copy of the file descriptor and use it when events occur. I recall that this suggestion used to be in the documentation as well, but I can't find it anymore. It would be good to add this suggestion to the documentation.

However, there is a thing you must know before you can use this approach: tcpserver calls shutdown() on the socket when handle() returns. This means that the network connection is closed. Even dup2() doesn't keep it open (it lets you keep a file descriptor, but it returns EOF). The solution for this is to override shutdown_request of your handler to only call close_request (or not call anything at all) for sockets which must remain open. That way, as long as there is a reference to the socket, the network connection will not be shut down. Optionally the socket can be shutdown() explicitly when you're done with the connection.

Something like the paragraph above would be useful in the documentation IMO.

----------
assignee: docs at python
components: Documentation
messages: 147147
nosy: docs at python, shevek
priority: normal
severity: normal
status: open
title: tcpserver should document non-threaded long-living connections
type: feature request
versions: Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13354>
_______________________________________

From report at bugs.python.org  Sun Nov  6 16:31:32 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 06 Nov 2011 15:31:32 +0000
Subject: [docs] [issue13353] documentation problem
	in	logging.handlers.TimedRotatingFileHandler for 2.7
In-Reply-To: <1320549842.11.0.772766831495.issue13353@psf.upfronthosting.co.za>
Message-ID: <1320593492.26.0.670180481005.issue13353@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +vinay.sajip
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13353>
_______________________________________

From report at bugs.python.org  Sun Nov  6 23:42:11 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sun, 06 Nov 2011 22:42:11 +0000
Subject: [docs] [issue13353] documentation problem
	in	logging.handlers.TimedRotatingFileHandler for 2.7
In-Reply-To: <1320549842.11.0.772766831495.issue13353@psf.upfronthosting.co.za>
Message-ID: <E1RNBPd-0002jU-9W@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 0b779988e8b7 by Vinay Sajip in branch '2.7':
Closes issue #13353: version doumentation about utc parameter corrected.
http://hg.python.org/cpython/rev/0b779988e8b7

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13353>
_______________________________________

From report at bugs.python.org  Sun Nov  6 23:44:07 2011
From: report at bugs.python.org (Vinay Sajip)
Date: Sun, 06 Nov 2011 22:44:07 +0000
Subject: [docs] [issue13353] documentation problem
	in	logging.handlers.TimedRotatingFileHandler for 2.7
In-Reply-To: <1320549842.11.0.772766831495.issue13353@psf.upfronthosting.co.za>
Message-ID: <1320619447.54.0.446784974539.issue13353@psf.upfronthosting.co.za>


Changes by Vinay Sajip <vinay_sajip at yahoo.co.uk>:


----------
resolution:  -> fixed
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13353>
_______________________________________

From report at bugs.python.org  Mon Nov  7 07:53:30 2011
From: report at bugs.python.org (David Townshend)
Date: Mon, 07 Nov 2011 06:53:30 +0000
Subject: [docs] [issue12760] Add create mode to open()
In-Reply-To: <1313502559.06.0.415498401391.issue12760@psf.upfronthosting.co.za>
Message-ID: <1320648810.3.0.643250137336.issue12760@psf.upfronthosting.co.za>


David Townshend <aquavitae69 at gmail.com> added the comment:

It is already possible to write a wrapper function that does it:

def create(file):
    fd = os.open(file, os.O_EXCL | os.O_CREAT | os.O_WRONLY)
    return os.fdopen(fd)

The point it not that it can't be done, but that it is not straight forward.  The docs say this about os.open(): "This function is intended for low-level I/O. For normal usage, use the built-in function open()" 

I wouldn't call creating a new file low-level I/O, but it is normal usage.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12760>
_______________________________________

From report at bugs.python.org  Mon Nov  7 15:23:05 2011
From: report at bugs.python.org (John Feuerstein)
Date: Mon, 07 Nov 2011 14:23:05 +0000
Subject: [docs] [issue13365] str.expandtabs documentation is wrong
Message-ID: <1320675785.8.0.972158739581.issue13365@psf.upfronthosting.co.za>


New submission from John Feuerstein <john at feurix.com>:

The documentation for str.expandtabs([tabsize]) is wrong:
 
"Return a copy of the string where all tab characters are replaced by one or more spaces, depending on the current column and the given tab size. [...]"

This should read "zero or more spaces":

>>> 'a\tb'.expandtabs(0)
'ab'
>>> 'a\tb'.expandtabs(-1)
'ab'

The description in Objects/unicodeobject.c does not include this error.

----------
assignee: docs at python
components: Documentation
files: expandtabs_doc.diff
keywords: patch
messages: 147222
nosy: docs at python, john.feuerstein
priority: normal
severity: normal
status: open
title: str.expandtabs documentation is wrong
versions: Python 3.3
Added file: http://bugs.python.org/file23625/expandtabs_doc.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13365>
_______________________________________

From report at bugs.python.org  Mon Nov  7 15:47:08 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 07 Nov 2011 14:47:08 +0000
Subject: [docs] [issue13365] str.expandtabs documentation is wrong
In-Reply-To: <1320675785.8.0.972158739581.issue13365@psf.upfronthosting.co.za>
Message-ID: <1320677228.91.0.454115105781.issue13365@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

While we're at it, wouldn't it be clearer to say "... where each tab character is replaced by..."?

----------
nosy: +eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13365>
_______________________________________

From report at bugs.python.org  Mon Nov  7 15:50:08 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 07 Nov 2011 14:50:08 +0000
Subject: [docs] [issue13365] str.expandtabs documentation is wrong
In-Reply-To: <1320675785.8.0.972158739581.issue13365@psf.upfronthosting.co.za>
Message-ID: <1320677408.31.0.439393654771.issue13365@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Other than that, the patch looks good.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13365>
_______________________________________

From report at bugs.python.org  Mon Nov  7 17:15:25 2011
From: report at bugs.python.org (Jason R. Coombs)
Date: Mon, 07 Nov 2011 16:15:25 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320682525.16.0.702896256312.issue13211@psf.upfronthosting.co.za>


Changes by Jason R. Coombs <jaraco at jaraco.com>:


----------
hgrepos: +88
keywords: +needs review, patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Mon Nov  7 17:15:58 2011
From: report at bugs.python.org (Jason R. Coombs)
Date: Mon, 07 Nov 2011 16:15:58 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320682558.47.0.344289208486.issue13211@psf.upfronthosting.co.za>


Changes by Jason R. Coombs <jaraco at jaraco.com>:


Added file: http://bugs.python.org/file23627/fffeff7721c0.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Mon Nov  7 17:17:43 2011
From: report at bugs.python.org (Jason R. Coombs)
Date: Mon, 07 Nov 2011 16:17:43 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320682663.63.0.218982195865.issue13211@psf.upfronthosting.co.za>


Jason R. Coombs <jaraco at jaraco.com> added the comment:

I've created three changesets, addressing the issue in 2.7, 3.2, and 3.3, including tests. Please review and comment. If there are no objections, I'll push the changesets after 24 hours.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Mon Nov  7 17:33:59 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 07 Nov 2011 16:33:59 +0000
Subject: [docs] [issue13341] Incorrect documentation for "u" PyArg_Parse
	format unit
In-Reply-To: <1320412814.48.0.657162308895.issue13341@psf.upfronthosting.co.za>
Message-ID: <1320683639.07.0.345298227381.issue13341@psf.upfronthosting.co.za>


Changes by ?ric Araujo <merwok at netwok.org>:


----------
nosy: +loewis

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________

From report at bugs.python.org  Mon Nov  7 20:21:13 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Mon, 07 Nov 2011 19:21:13 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320693673.4.0.0513497430056.issue13211@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

Perhaps the reason should include the status code, too? It makes HTTP errors much more useful, as you'll immediately see what's going on from the status code.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Mon Nov  7 22:38:14 2011
From: report at bugs.python.org (Jason R. Coombs)
Date: Mon, 07 Nov 2011 21:38:14 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320701894.15.0.154419635988.issue13211@psf.upfronthosting.co.za>


Jason R. Coombs <jaraco at jaraco.com> added the comment:

My initial instinct was to agree - the status code is useful. However, in looking at the FTP code, it sometimes just sets other objects (socket.error for example) as the 'reason'. The docs say 'reason' is a string or another exception.

I'm tempted to leave it as is. This fix is mainly to provide a reasonable value for .reason. The __str__ and .code are already exposed, so to create a reason with a code would create yet another string representation of the error which is different from every other representation already present.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Tue Nov  8 03:54:58 2011
From: report at bugs.python.org (INADA Naoki)
Date: Tue, 08 Nov 2011 02:54:58 +0000
Subject: [docs] [issue13367] PyCapsule_New's argument *must* not a NULL.
Message-ID: <1320720898.69.0.766220401845.issue13367@psf.upfronthosting.co.za>


New submission from INADA Naoki <songofacandy at gmail.com>:

http://docs.python.org/c-api/capsule.html?highlight=capsule#PyCapsule_New

> The pointer argument may not be NULL.

I think "must not" is correct.

----------
assignee: docs at python
components: Documentation
messages: 147269
nosy: docs at python, naoki
priority: normal
severity: normal
status: open
title: PyCapsule_New's argument *must* not a NULL.
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13367>
_______________________________________

From report at bugs.python.org  Tue Nov  8 04:03:50 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 08 Nov 2011 03:03:50 +0000
Subject: [docs] [issue13367] PyCapsule_New's argument *must* not a NULL.
In-Reply-To: <1320720898.69.0.766220401845.issue13367@psf.upfronthosting.co.za>
Message-ID: <1320721430.35.0.339170458167.issue13367@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +larry

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13367>
_______________________________________

From report at bugs.python.org  Tue Nov  8 04:23:14 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 08 Nov 2011 03:23:14 +0000
Subject: [docs] [issue13368] Possible problem in documentation of module
	subprocess, method send_signal
Message-ID: <1320722594.89.0.739080107592.issue13368@psf.upfronthosting.co.za>


New submission from Eli Bendersky <eliben at gmail.com>:

docs@ list report by Daniel Dieterle:

in the documentation (http://docs.python.org/library/subprocess.html#subprocess.Popen.send_signal) is a bug.

CTRL_C_EVENT can not be sent to processes started with a creationflags parameter which includes CREATE_NEW_PROCESS_GROUP. Why can be read in the msdn documentation http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%29.aspx .

A workaround using CTRL_C_EVENT nevertheless is described here:
http://stackoverflow.com/questions/7085604/sending-c-to-python-subprocess-objects-on-windows/7980368#7980368 

--

I do not know why the subprocess.CREATE_NEW_PROCESS_GROUP parameter was introduced. But it is useless for terminating a process with os.kill() in combination with signal.SIGTERM, which corresponds to a CTRL-C-EVENT.
A CTRL-C-EVENT is only forwarded to the process if the process group is zero. Therefore the Note in the documentation on Popen.send_signal() is wrong.

----------
assignee: docs at python
components: Documentation
messages: 147272
nosy: docs at python, eli.bendersky
priority: normal
severity: normal
status: open
title: Possible problem in documentation of module subprocess, method send_signal
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13368>
_______________________________________

From eliben at gmail.com  Tue Nov  8 04:23:33 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Tue, 8 Nov 2011 05:23:33 +0200
Subject: [docs] Bug in documentation of module subprocess,
	method send_signal
In-Reply-To: <B8940AF89405544998A30624A584065FCD32F5@CSMAIL.cs-nt-domaene.de>
References: <B8940AF89405544998A30624A584065FCD3012@CSMAIL.cs-nt-domaene.de>
	<CAF-Rda9SRh6hG968aTa0zMdyFVpk9-6jrv5DB9T7K8FZWDcHeA@mail.gmail.com>
	<B8940AF89405544998A30624A584065FCD32F5@CSMAIL.cs-nt-domaene.de>
Message-ID: <CAF-Rda_UWf59UyoO0uziMFmW7dS4rZ6sYLPDZmLQ5SH3v41CAw@mail.gmail.com>

> it's not a problem of implementation, because there is no way of killing an
> individual?process with the CTRL-C-EVENT signal.
>
> I do not know why the subprocess.CREATE_NEW_PROCESS_GROUP parameter was
> introduced. But it is useless for terminating a process with os.kill() in
> combination with?signal.SIGTERM, which corresponds to a CTRL-C-EVENT.
> A CTRL-C-EVENT is only forwarded to the process if the process group is
> zero. Therefore the Note in the documentation on Popen.send_signal() is
> wrong.

Daniel,
I've opened issue http://bugs.python.org/issue13368 to track this.
Thanks for the report,
Eli

From report at bugs.python.org  Tue Nov  8 05:00:36 2011
From: report at bugs.python.org (=?utf-8?b?SmVzw7pzIENlYSBBdmnDs24=?=)
Date: Tue, 08 Nov 2011 04:00:36 +0000
Subject: [docs] [issue13367] PyCapsule_New's argument *must* not a NULL.
In-Reply-To: <1320720898.69.0.766220401845.issue13367@psf.upfronthosting.co.za>
Message-ID: <1320724836.29.0.332445048044.issue13367@psf.upfronthosting.co.za>


Changes by Jes?s Cea Avi?n <jcea at jcea.es>:


----------
nosy: +jcea

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13367>
_______________________________________

From report at bugs.python.org  Tue Nov  8 05:29:16 2011
From: report at bugs.python.org (Benjamin Peterson)
Date: Tue, 08 Nov 2011 04:29:16 +0000
Subject: [docs] [issue13367] PyCapsule_New's argument *must* not a NULL.
In-Reply-To: <1320720898.69.0.766220401845.issue13367@psf.upfronthosting.co.za>
Message-ID: <1320726556.17.0.0985916508197.issue13367@psf.upfronthosting.co.za>


Benjamin Peterson <benjamin at python.org> added the comment:

In this context, "may" means "allowed to". In other words, it is equivalent to "The pointer argument is not allowed to be NULL".

----------
nosy: +benjamin.peterson
resolution:  -> works for me
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13367>
_______________________________________

From report at bugs.python.org  Tue Nov  8 12:22:28 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Tue, 08 Nov 2011 11:22:28 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1320701894.15.0.154419635988.issue13211@psf.upfronthosting.co.za>
Message-ID: <20111108112217.GD1904@ihaa>


Petri Lehtinen <petri at digip.org> added the comment:

Ok. Sounds that you've already evaluated this alternative, so I'm fine
with it.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Tue Nov  8 13:12:11 2011
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 08 Nov 2011 12:12:11 +0000
Subject: [docs] [issue13237] subprocess docs should emphasise convenience
	functions
In-Reply-To: <1319174702.47.0.36912184976.issue13237@psf.upfronthosting.co.za>
Message-ID: <E1RNkX3-0003zc-1T@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset e929d2a96d9b by Nick Coghlan in branch '3.2':
Issue #13237: Forward port subprocess module updates and explicitly document UTF-8 encoding assumption when universal_newlines=True
http://hg.python.org/cpython/rev/e929d2a96d9b

New changeset d3b159c43ee8 by Nick Coghlan in branch '3.2':
Issue #13237: Remove duplicate data value descriptions from the subprocess docs
http://hg.python.org/cpython/rev/d3b159c43ee8

New changeset 7545f4fb450c by Nick Coghlan in branch '3.2':
Issue #13237: Fix formatting error - the legacy shell commands weren't meant to be under the Notes heading
http://hg.python.org/cpython/rev/7545f4fb450c

New changeset 0b50008bb953 by Nick Coghlan in branch 'default':
Issue #13237: Forward port from 3.2 of subprocess documentation updates. Needed quite a few adjustments to account for new features coming in 3.3
http://hg.python.org/cpython/rev/0b50008bb953

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13237>
_______________________________________

From report at bugs.python.org  Tue Nov  8 13:14:34 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Tue, 08 Nov 2011 12:14:34 +0000
Subject: [docs] [issue13237] subprocess docs should emphasise convenience
	functions
In-Reply-To: <1319174702.47.0.36912184976.issue13237@psf.upfronthosting.co.za>
Message-ID: <1320754474.8.0.160509657761.issue13237@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

Well, that forward port was definitely more complicated than I expected.

Additional reviews of both 3.2 and 3.3 (i.e. default) would be appreciated - there were quite a few adjustments needed to cope with changes between 2.7 and 3.2 and then additional changes between 3.2 and 3.3.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13237>
_______________________________________

From report at bugs.python.org  Tue Nov  8 18:33:12 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Tue, 08 Nov 2011 17:33:12 +0000
Subject: [docs] [issue13292] missing versionadded for bytearray
In-Reply-To: <1319975533.88.0.431386848219.issue13292@psf.upfronthosting.co.za>
Message-ID: <1320773592.11.0.323891841078.issue13292@psf.upfronthosting.co.za>


Florent Xicluna <florent.xicluna at gmail.com> added the comment:

Done by Eric, thank you.
Because of a typo, the message was attached to the wrong ticket.


New changeset 8ea34a74f118 by ?ric Araujo in branch '2.7':
Add missing versionadded (fixes #12392)
http://hg.python.org/cpython/rev/8ea34a74f118

----------
resolution:  -> fixed
stage: needs patch -> committed/rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13292>
_______________________________________

From report at bugs.python.org  Tue Nov  8 18:39:08 2011
From: report at bugs.python.org (Senthil Kumaran)
Date: Tue, 08 Nov 2011 17:39:08 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320773948.49.0.733111145447.issue13211@psf.upfronthosting.co.za>


Senthil Kumaran <senthil at uthcode.com> added the comment:

Hi Jason & Petri,

urllib2.HTTPError never had a reason attribute. In the docs, it is mentioned that only URLError has the reason attribute. The HTTPError sublasses URLError and addinforurl class, but the further initialization happens only in the addinforurl class atrs.

If you got confused that the HTTPError as args and not reason, the 'args' is not coming from URLError.

HTTPError is raised for peculiar conditions such like authentication failures and it is 'used' as expected failure for certain authentication conditions. URLError is not so, it is seen more as an exception like socket errors.

The example your illustrated is an Authentication failure and as per docs, it is guaranteed to have code attribute to verify the kind of HTTP error are getting. msg is corresponding HTTP error code msg.

Take this example for URLError which will have reason attribute, it will work in both 2.7,3.2 and 3.3

import urllib.request, urllib.error, urllib.parse

try:
    urllib.request.urlopen('http://aninvalidsite/something')
except urllib.error.URLError as exc:
    print(exc.reason)


Because this is a socket error, the reason as "[Errno -2] Name or service not known" and HTTPError may not be a proper exception for this. 

This is more of an IOError which urllib calls a URLError.

I am not sure, how the need for 'reason' attribute for HTTPError exception was felt as the docs just say about 'code'.  (HTTPError  is informed as a subclass of URLError, but HTTPError does not call the URLError 's  __init__ and acts standalone. 

I am not sure, how to go about with this bug. If a new .reason attribute has to be added to HTTPError, then it is a feature request though, I wonder why we need when code and msg serve an adequate purpose.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Tue Nov  8 19:54:39 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Tue, 08 Nov 2011 18:54:39 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1320773948.49.0.733111145447.issue13211@psf.upfronthosting.co.za>
Message-ID: <20111108185427.GA1852@ihaa>


Petri Lehtinen <petri at digip.org> added the comment:

My impression was that because HTTPError is a subclass of URLError, it
should have the same attributes, and maybe some extra. A user reading
the docs doesn't know whether it calls the base class __init__ or not.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Tue Nov  8 22:15:50 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 08 Nov 2011 21:15:50 +0000
Subject: [docs] [issue5904] strftime docs do not explain locale effect on
	result	string
In-Reply-To: <1241270739.12.0.286821632978.issue5904@psf.upfronthosting.co.za>
Message-ID: <1320786950.07.0.585420656263.issue5904@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +ezio.melotti
stage:  -> needs patch
versions: +Python 2.7 -Python 2.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue5904>
_______________________________________

From report at bugs.python.org  Tue Nov  8 22:39:55 2011
From: report at bugs.python.org (Jason R. Coombs)
Date: Tue, 08 Nov 2011 21:39:55 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320788395.16.0.0778504667191.issue13211@psf.upfronthosting.co.za>


Jason R. Coombs <jaraco at jaraco.com> added the comment:

That was my point. If HTTPError is a subclass of URLError, then an HTTPError _is an_ URLError, and thus should implement the same public interface.

The problem is better illustrated with this request:

try:
  urllib.request.urlopen('http://api.wordnik.com/v4/word.json/foo/examples')
except urllib2.URLError as exc:
  # We caught a URLError, what's the reason?
  print(exc.reason)

This code will fail with an attribute error, but only when the except clause catches an HTTPError (as it does in this case).

The documentation explicitly states that HTTPError is a subclass of URLError and it doesn't say anything about the addinfourl interface. The documentation strongly suggests (though implicitly) that HTTPError.reason will be present as it is with URLError.

If HTTPError does not implement the reason attribute, then there is no value in making it the subclass of URLError, and HTTPError should probably have the same parent class as URLError. However, this change is even more drastic and would almost certainly violate backward compatibility constraints.

The proposal I've made is generally backward compatible, and addresses the underlying bug (that URLError.__init__ is never called), and the symptom that a HTTPError does not implement the documented public interface.

Perhaps there's a better approach, but I believe based on the example code above, the implementation is broken.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Tue Nov  8 22:49:31 2011
From: report at bugs.python.org (Jason R. Coombs)
Date: Tue, 08 Nov 2011 21:49:31 +0000
Subject: [docs] [issue13211] urllib2.HTTPError does not have 'reason'
	attribute.
In-Reply-To: <1318943168.93.0.520705450261.issue13211@psf.upfronthosting.co.za>
Message-ID: <1320788971.97.0.150179359554.issue13211@psf.upfronthosting.co.za>


Changes by Jason R. Coombs <jaraco at jaraco.com>:


----------
components: +Library (Lib)

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13211>
_______________________________________

From report at bugs.python.org  Wed Nov  9 00:38:59 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 08 Nov 2011 23:38:59 +0000
Subject: [docs] [issue12245] Document the meaning of FLT_ROUNDS constants
	for	sys.float_info
In-Reply-To: <1307044030.93.0.176037757521.issue12245@psf.upfronthosting.co.za>
Message-ID: <1320795539.28.0.0337162461819.issue12245@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

LGTM

----------
nosy: +ezio.melotti
stage:  -> commit review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12245>
_______________________________________

From report at bugs.python.org  Fri Nov 11 09:34:54 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 11 Nov 2011 08:34:54 +0000
Subject: [docs] [issue13365] str.expandtabs documentation is wrong
In-Reply-To: <1320675785.8.0.972158739581.issue13365@psf.upfronthosting.co.za>
Message-ID: <E1ROmZO-0001QV-ML@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 84f803fdc0d2 by Eli Bendersky in branch '3.2':
Issue #13365: correct an error in the documentation of str.expandtabs
http://hg.python.org/cpython/rev/84f803fdc0d2

New changeset 25191fe10da9 by Eli Bendersky in branch 'default':
Issue #13365: correct an error in the documentation of str.expandtabs. Patch by John Feuerstein
http://hg.python.org/cpython/rev/25191fe10da9

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13365>
_______________________________________

From report at bugs.python.org  Fri Nov 11 09:35:19 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 11 Nov 2011 08:35:19 +0000
Subject: [docs] [issue13365] str.expandtabs documentation is wrong
In-Reply-To: <1320675785.8.0.972158739581.issue13365@psf.upfronthosting.co.za>
Message-ID: <1321000519.78.0.843660831286.issue13365@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Committed. Thanks for contributing.

----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13365>
_______________________________________

From report at bugs.python.org  Fri Nov 11 09:49:05 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 11 Nov 2011 08:49:05 +0000
Subject: [docs] [issue13191] Typo in argparse documentation
In-Reply-To: <1318795744.19.0.406202573511.issue13191@psf.upfronthosting.co.za>
Message-ID: <E1ROmn8-0002V7-NX@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 61976390763f by Eli Bendersky in branch '3.2':
Issue #13191: typo in argparse docs
http://hg.python.org/cpython/rev/61976390763f

New changeset edf944ab87c5 by Eli Bendersky in branch 'default':
Issue #13191: typo in argparse docs
http://hg.python.org/cpython/rev/edf944ab87c5

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13191>
_______________________________________

From report at bugs.python.org  Fri Nov 11 09:51:26 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 11 Nov 2011 08:51:26 +0000
Subject: [docs] [issue13191] Typo in argparse documentation
In-Reply-To: <1318795744.19.0.406202573511.issue13191@psf.upfronthosting.co.za>
Message-ID: <1321001486.64.0.600022536174.issue13191@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13191>
_______________________________________

From report at bugs.python.org  Fri Nov 11 09:58:48 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 11 Nov 2011 08:58:48 +0000
Subject: [docs] [issue13239] Remove <> operator from Grammar/Grammar
In-Reply-To: <1319188291.02.0.897231487042.issue13239@psf.upfronthosting.co.za>
Message-ID: <1321001928.62.0.40388720869.issue13239@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Attaching a patch with a clarifying comment in Grammar/Grammar. Should be enough for now?

----------
keywords: +patch
Added file: http://bugs.python.org/file23656/issue13239.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13239>
_______________________________________

From report at bugs.python.org  Fri Nov 11 10:24:07 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 11 Nov 2011 09:24:07 +0000
Subject: [docs] [issue13368] Possible problem in documentation of module
	subprocess, method send_signal
In-Reply-To: <1320722594.89.0.739080107592.issue13368@psf.upfronthosting.co.za>
Message-ID: <1321003447.55.0.460125503219.issue13368@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Brian, I see this text (along with the implementation) was added by you in  60197:0ab89e8bdedc

Could you state your opinion on this issue?

----------
nosy: +brian.curtin

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13368>
_______________________________________

From report at bugs.python.org  Fri Nov 11 13:24:55 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Fri, 11 Nov 2011 12:24:55 +0000
Subject: [docs] [issue13237] subprocess docs should emphasise convenience
	functions
In-Reply-To: <1319174702.47.0.36912184976.issue13237@psf.upfronthosting.co.za>
Message-ID: <1321014295.46.0.341668131483.issue13237@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

Calling this one done - any further adjustments can be handled as new tracker issues.

----------
resolution:  -> fixed
stage: needs patch -> committed/rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13237>
_______________________________________

From report at bugs.python.org  Fri Nov 11 15:19:26 2011
From: report at bugs.python.org (Brian Curtin)
Date: Fri, 11 Nov 2011 14:19:26 +0000
Subject: [docs] [issue13368] Possible problem in documentation of module
	subprocess, method send_signal
In-Reply-To: <1320722594.89.0.739080107592.issue13368@psf.upfronthosting.co.za>
Message-ID: <1321021166.05.0.563844288647.issue13368@psf.upfronthosting.co.za>


Brian Curtin <brian at python.org> added the comment:

> But it is useless for terminating a process with os.kill() in combination with signal.SIGTERM, which corresponds to a CTRL-C-EVENT.

SIGTERM does not correspond to CTRL_C_EVENT. They may be similar in what they do, but os.kill on Windows only works with exactly CTRL_C_EVENT and CTRL_BREAK_EVENT, as this uses GenerateConsoleCtrlEvent which only works with those two values. As the documentation states, anything other than those two constants is sent to TerminateProcess. If you call os.kill with signal.SIGTERM, it would kill the process with return code 15.



I will look into adjusting the text a little, and I also need to look into the tests. I currently have CTRL_C_EVENT tests skipped, probably because I am passing the wrong process stuff as he mentioned. I had it working at some point, but I may have generalized it too far.

----------
assignee: docs at python -> brian.curtin
components: +Windows
stage:  -> needs patch
type:  -> behavior
versions: +Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13368>
_______________________________________

From report at bugs.python.org  Fri Nov 11 15:32:36 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 11 Nov 2011 14:32:36 +0000
Subject: [docs] [issue13191] Typo in argparse documentation
In-Reply-To: <1318795744.19.0.406202573511.issue13191@psf.upfronthosting.co.za>
Message-ID: <E1ROs9Z-0005eG-12@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 477f633aa09d by Eli Bendersky in branch '2.7':
Issue #13191: typo in argparse docs
http://hg.python.org/cpython/rev/477f633aa09d

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13191>
_______________________________________

From report at bugs.python.org  Fri Nov 11 15:42:41 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 11 Nov 2011 14:42:41 +0000
Subject: [docs] [issue13161] problems with help() documentation of __i*__
	operators
In-Reply-To: <1318436543.45.0.46958950416.issue13161@psf.upfronthosting.co.za>
Message-ID: <E1ROsJK-0006XK-OT@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 369487785e9f by Eli Bendersky in branch '2.7':
Issue #13161: fix doc strings of __i*__ operators
http://hg.python.org/cpython/rev/369487785e9f

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13161>
_______________________________________

From report at bugs.python.org  Fri Nov 11 15:52:42 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 11 Nov 2011 14:52:42 +0000
Subject: [docs] [issue13161] problems with help() documentation of __i*__
	operators
In-Reply-To: <1318436543.45.0.46958950416.issue13161@psf.upfronthosting.co.za>
Message-ID: <E1ROsT1-0007LE-JT@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 9fbaa190f011 by Eli Bendersky in branch '3.2':
Issue #13161: fix doc strings of __i*__ operators
http://hg.python.org/cpython/rev/9fbaa190f011

New changeset d58de3e9870a by Eli Bendersky in branch 'default':
Issue #13161: fix doc strings of __i*__ operators. Closes #13161
http://hg.python.org/cpython/rev/d58de3e9870a

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13161>
_______________________________________

From report at bugs.python.org  Fri Nov 11 15:53:05 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 11 Nov 2011 14:53:05 +0000
Subject: [docs] [issue13161] problems with help() documentation of __i*__
	operators
In-Reply-To: <1318436543.45.0.46958950416.issue13161@psf.upfronthosting.co.za>
Message-ID: <1321023185.42.0.580322084114.issue13161@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13161>
_______________________________________

From report at bugs.python.org  Fri Nov 11 20:16:17 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 11 Nov 2011 19:16:17 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <E1ROwa6-00078a-OE@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 02e4d3ebbb02 by Eli Bendersky in branch '2.7':
Issue #12875: explicitly specify default value of the optional 'flags' argument to re.* functions. Closes #12875
http://hg.python.org/cpython/rev/02e4d3ebbb02

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Fri Nov 11 20:19:53 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 11 Nov 2011 19:19:53 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321039193.74.0.130869064346.issue12875@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Fri Nov 11 21:47:46 2011
From: report at bugs.python.org (Amaury Forgeot d'Arc)
Date: Fri, 11 Nov 2011 20:47:46 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321044466.89.0.263607913783.issue12875@psf.upfronthosting.co.za>


Amaury Forgeot d'Arc <amauryfa at gmail.com> added the comment:

The documentation now shows::
    match(pattern, string[, flags=0])
Is it normal to have the brackets *and* the default value?

----------
nosy: +amaury.forgeotdarc
status: closed -> open

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Fri Nov 11 22:09:24 2011
From: report at bugs.python.org (Georg Brandl)
Date: Fri, 11 Nov 2011 21:09:24 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321045764.42.0.758993951091.issue12875@psf.upfronthosting.co.za>


Georg Brandl <georg at python.org> added the comment:

No, it's not.

----------
nosy: +georg.brandl

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Fri Nov 11 23:04:21 2011
From: report at bugs.python.org (Brett Cannon)
Date: Fri, 11 Nov 2011 22:04:21 +0000
Subject: [docs] [issue13239] Remove <> operator from Grammar/Grammar
In-Reply-To: <1319188291.02.0.897231487042.issue13239@psf.upfronthosting.co.za>
Message-ID: <1321049061.38.0.414308237762.issue13239@psf.upfronthosting.co.za>


Brett Cannon <brett at python.org> added the comment:

I think the clarification should be enough.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13239>
_______________________________________

From report at bugs.python.org  Sat Nov 12 04:32:44 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 03:32:44 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321068764.24.0.892357143906.issue12875@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Amaury & Georg,

Grepping through the docs disagrees with your claims ;-) Try to grep for "\=None\]" to see what I mean. There are tons of places where default values are placed inside the brackets. For example in http://docs.python.org/library/csv.html --> look at:

    sniff(sample[, delimiters=None])

or even:

    class csv.DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])

That said, I have absolutely no objections to following an accepted convention. But what is it?

I looked around, and found the following in the documentation guide:

http://docs.python.org/dev/py3k/documenting/fromlatex.html

    There is no optional command. Just give function signatures 
    like they should appear in the output:

    .. function:: open(filename[, mode[, buffering]])

       Description.

This (taken from the 3.3 guide) mentions the 2.x guideline and doesn't mention default values.

So what should I do here? According to Ezio's earlier message, the new style (without brackets) is also being used in Python 2 now. I can do the switch for the 're' module, but can we first get the convention documented somewhere?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 04:54:57 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 12 Nov 2011 03:54:57 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321070097.1.0.586438710737.issue12875@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> but can we first get the convention documented somewhere?

+1
This was on my todo list, but feel free to open a new issue about it.

> Grepping through the docs disagrees with your claims 

That's because is not documented and not everyone is aware of the conventions and how/where they should be followed.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 05:20:28 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 04:20:28 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321071628.52.0.659912063651.issue12875@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Ezio, what do you suggest to do regarding *this* issue?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 05:50:35 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 04:50:35 +0000
Subject: [docs] [issue12767] document threading.Condition.notify
In-Reply-To: <1313548629.79.0.0632318255733.issue12767@psf.upfronthosting.co.za>
Message-ID: <1321073435.23.0.593113745004.issue12767@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

I propose the attached patch for the documentation. Any objections?

----------
keywords: +patch
Added file: http://bugs.python.org/file23657/issue12767.1.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12767>
_______________________________________

From report at bugs.python.org  Sat Nov 12 05:52:24 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 04:52:24 +0000
Subject: [docs] [issue12768] docstrings for the threading module
In-Reply-To: <1313548989.72.0.178892692878.issue12768@psf.upfronthosting.co.za>
Message-ID: <1321073544.48.0.226764189283.issue12768@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Graeme, any news on this?

If you re-do the patch for current tip and address the review comments, I think we can commit it.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12768>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:04:14 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 05:04:14 +0000
Subject: [docs] [issue12188] PEP 7 (or guide) add C style policies and
	explanation
In-Reply-To: <1306433972.91.0.882585972593.issue12188@psf.upfronthosting.co.za>
Message-ID: <1321074254.89.0.870414012731.issue12188@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
nosy:  -eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12188>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:04:41 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 05:04:41 +0000
Subject: [docs] [issue11173] Undocumented public APIs in Python 3.2
In-Reply-To: <1297351155.94.0.957592646254.issue11173@psf.upfronthosting.co.za>
Message-ID: <1321074281.29.0.882931147082.issue11173@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
nosy:  -eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11173>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:05:29 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 05:05:29 +0000
Subject: [docs] [issue3849] FUD in documentation for urllib.urlopen()
In-Reply-To: <1221246343.23.0.128587140594.issue3849@psf.upfronthosting.co.za>
Message-ID: <1321074329.29.0.955426653642.issue3849@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
nosy:  -eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3849>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:06:47 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 05:06:47 +0000
Subject: [docs] [issue5088] optparse: inconsistent default value for append
	actions
In-Reply-To: <1233140307.53.0.685208172708.issue5088@psf.upfronthosting.co.za>
Message-ID: <1321074407.4.0.613321726079.issue5088@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
nosy:  -eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue5088>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:43:04 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 12 Nov 2011 05:43:04 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321076583.92.0.622094066752.issue12875@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

I suggest removing the [].

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:49:11 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 12 Nov 2011 05:49:11 +0000
Subject: [docs] [issue12767] document threading.Condition.notify
In-Reply-To: <1313548629.79.0.0632318255733.issue12767@psf.upfronthosting.co.za>
Message-ID: <1321076951.08.0.270482807134.issue12767@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

+      This method wakes up at most *n* of the threads
+      The current implementation wakes up exactly *n* threads
+      A future, optimized implementation may occasionally wake up more than
+      one thread.

Isn't this a bit contradictory?

----------
nosy: +ezio.melotti
stage: needs patch -> patch review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12767>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:51:20 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 05:51:20 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321077080.2.0.52173967055.issue12875@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Hmm, I've just notice that this [default=val] pattern already exists in the 're' docs in 2.7, for example:

  subn(repl, string[, count=0])

So my change was consistent within the documentation of this module.

No doubt, the conventions are currently a mess ;-)

I suggest to just convert the whole 're' RST page to the new 3.x convention (i.e. model it after the same RST in the default branch). Is this acceptable? If yes, I will submit a patch for review first.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 06:53:37 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 05:53:37 +0000
Subject: [docs] [issue12767] document threading.Condition.notify
In-Reply-To: <1313548629.79.0.0632318255733.issue12767@psf.upfronthosting.co.za>
Message-ID: <1321077217.37.0.577688016025.issue12767@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Ezio, thanks for the catch. I missed that one. Attaching a new, fixed patch.

----------
Added file: http://bugs.python.org/file23658/issue12767.2.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12767>
_______________________________________

From report at bugs.python.org  Sat Nov 12 07:08:41 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 12 Nov 2011 06:08:41 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
Message-ID: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>


New submission from Ezio Melotti <ezio.melotti at gmail.com>:

AFAIU the conventions for optional argument in the doc are as follow:

If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example:
  str.splitlines(keepends=False)

If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead.  This should apply only to some C functions, for example:
  str.strip([chars])

The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted.

These rules apply to both Python 2 and Python 3.

A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function.

----------
assignee: docs at python
components: Documentation
messages: 147469
nosy: docs at python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl
priority: normal
severity: normal
stage: needs patch
status: open
title: Document documentation conventions for optional args
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Sat Nov 12 07:13:43 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 12 Nov 2011 06:13:43 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321078423.87.0.530397684862.issue12875@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

I created #13386 about the conventions that should be followed in the doc.

Converting the whole page is fine with me.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 11:53:48 2011
From: report at bugs.python.org (Eric V. Smith)
Date: Sat, 12 Nov 2011 10:53:48 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321095228.68.0.498192197786.issue13386@psf.upfronthosting.co.za>


Eric V. Smith <eric at trueblade.com> added the comment:

To your last point, I think it's important to specify the default value placeholder (basically a sentinel) in the documentation. For example, if a function takes -1 to mean "all occurrences", then the caller needs to know how what value to pass in in order to let the function compute the value. This is especially true if it's cheaper for the function to compute the value instead of the caller.

I've run into this problem before, where I wanted to pass in some sentinel value and I had to read the source to figure out what it was. I think the function was in the standard library, but now I can't recall what it was.

----------
nosy: +eric.smith

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Sat Nov 12 12:40:37 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 12 Nov 2011 11:40:37 +0000
Subject: [docs] [issue13282] the table of contents in epub file is too long
In-Reply-To: <1319796506.79.0.347343158897.issue13282@psf.upfronthosting.co.za>
Message-ID: <1321098037.18.0.989522788185.issue13282@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks for the report.  I do not know if this something that we can fix in the CPython repository by editing some template or config file or if it requires a patch to Sphinx first.  Georg?

----------
nosy: +eric.araujo, georg.brandl

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13282>
_______________________________________

From report at bugs.python.org  Sat Nov 12 14:37:34 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 12 Nov 2011 13:37:34 +0000
Subject: [docs] [issue13249] argparse.ArgumentParser() lists arguments in
	the wrong	order
In-Reply-To: <1319394759.74.0.692830705102.issue13249@psf.upfronthosting.co.za>
Message-ID: <1321105054.77.0.689204900535.issue13249@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks, I?ve made some comments on Rietveld.

> Added a recommendation to only use keywords, which seems sane given
> the number of arguments.
I looked for that but couldn?t find it.

----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13249>
_______________________________________

From report at bugs.python.org  Sat Nov 12 14:45:07 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 12 Nov 2011 13:45:07 +0000
Subject: [docs] [issue12103] Document how to use open with os.O_CLOEXEC
In-Reply-To: <1305716485.42.0.643130250278.issue12103@psf.upfronthosting.co.za>
Message-ID: <1321105507.79.0.404969270755.issue12103@psf.upfronthosting.co.za>


Changes by ?ric Araujo <merwok at netwok.org>:


----------
keywords: +easy
nosy: +eric.araujo
title: Documentation of open() does not claim 'e' support in mode string -> Document how to use open with os.O_CLOEXEC
versions: +Python 3.3 -Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12103>
_______________________________________

From report at bugs.python.org  Sat Nov 12 14:48:19 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 12 Nov 2011 13:48:19 +0000
Subject: [docs] [issue13286] PEP 3151 breaks backward compatibility: it
	should be	documented
In-Reply-To: <1319811530.69.0.689775391155.issue13286@psf.upfronthosting.co.za>
Message-ID: <1321105699.62.0.0669638521968.issue13286@psf.upfronthosting.co.za>


Changes by ?ric Araujo <merwok at netwok.org>:


----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13286>
_______________________________________

From report at bugs.python.org  Sat Nov 12 14:49:21 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 12 Nov 2011 13:49:21 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321105761.57.0.964875859354.issue13386@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

The problem is when the default placeholder is some unique object() or some _internal value (we had something similar with a socket timeout once).
Also for something like str.strip(), would you document chars=None or chars=" \n\r\t\v\f"?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Sat Nov 12 17:32:53 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 12 Nov 2011 16:32:53 +0000
Subject: [docs] [issue13239] Remove <> operator from Grammar/Grammar
In-Reply-To: <1319188291.02.0.897231487042.issue13239@psf.upfronthosting.co.za>
Message-ID: <1321115572.85.0.0460184533893.issue13239@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

+1 for a comment too.  I?d even make it shorter:

# don't look at <>, it's not a real operator (see PEP 401)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13239>
_______________________________________

From report at bugs.python.org  Sat Nov 12 17:44:50 2011
From: report at bugs.python.org (Roy Smith)
Date: Sat, 12 Nov 2011 16:44:50 +0000
Subject: [docs] [issue13249] argparse.ArgumentParser() lists arguments in
	the wrong	order
In-Reply-To: <1319394759.74.0.692830705102.issue13249@psf.upfronthosting.co.za>
Message-ID: <1321116289.5.0.6009963564.issue13249@psf.upfronthosting.co.za>


Roy Smith <roy at panix.com> added the comment:

New patch uploaded.

The added recommendation is around line 161 (look for 'Recommended usage is to only use keyword arguments')

----------
Added file: http://bugs.python.org/file23667/Issue13249-2.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13249>
_______________________________________

From report at bugs.python.org  Sat Nov 12 19:28:20 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 18:28:20 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321122500.09.0.891552780325.issue12875@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

I have converted the Doc/library/re.rst doc of 2.7 to follow the new convention of 3.x, patch attached.

----------
keywords: +patch
Added file: http://bugs.python.org/file23668/issue12875.1.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sat Nov 12 19:37:09 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 12 Nov 2011 18:37:09 +0000
Subject: [docs] [issue12767] document threading.Condition.notify
In-Reply-To: <1313548629.79.0.0632318255733.issue12767@psf.upfronthosting.co.za>
Message-ID: <E1RPIRg-0005KU-Pw@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 63a24bff6f36 by Eli Bendersky in branch '3.2':
Issue #12767: documenting threading.Condition.notify
http://hg.python.org/cpython/rev/63a24bff6f36

New changeset ac12dcea69e1 by Eli Bendersky in branch 'default':
Issue 12767: document the argument of threading.Condition.notify
http://hg.python.org/cpython/rev/ac12dcea69e1

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12767>
_______________________________________

From report at bugs.python.org  Sat Nov 12 19:42:01 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 12 Nov 2011 18:42:01 +0000
Subject: [docs] [issue12767] document threading.Condition.notify
In-Reply-To: <1313548629.79.0.0632318255733.issue12767@psf.upfronthosting.co.za>
Message-ID: <E1RPIWU-0005iO-HS@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 63a00d019bb2 by Eli Bendersky in branch '2.7':
Closes issue 12767: document the argument of threading.Condition.notify
http://hg.python.org/cpython/rev/63a00d019bb2

----------
resolution:  -> fixed
stage: patch review -> committed/rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12767>
_______________________________________

From report at bugs.python.org  Sat Nov 12 19:44:23 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 18:44:23 +0000
Subject: [docs] [issue13239] Remove <> operator from Grammar/Grammar
In-Reply-To: <1319188291.02.0.897231487042.issue13239@psf.upfronthosting.co.za>
Message-ID: <1321123463.81.0.739035837531.issue13239@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

?ric, do you feel strongly about the wording, or can I just go ahead and commit my version if I like it more :) ?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13239>
_______________________________________

From report at bugs.python.org  Sat Nov 12 19:52:15 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 12 Nov 2011 18:52:15 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321123935.4.0.082871273641.issue13386@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

You should also explicitly specify what happens in several optional but not keyword args are needed. AFAIU the convention is:

   func(arg1, arg2[, opt1, opt2])

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Sat Nov 12 20:12:25 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Sat, 12 Nov 2011 19:12:25 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321125145.44.0.402320123302.issue13387@psf.upfronthosting.co.za>


Florent Xicluna <florent.xicluna at gmail.com> added the comment:

> +1 on a doc addition (I can even volunteer a patch)

I agree we can highlight the difference between assertIs(type(obj), cls) and assertIsInstance(obj, cls) in the documentation.

Let's forget this patch and keep it simple.

----------
assignee:  -> docs at python
components: +Documentation
nosy: +docs at python
stage:  -> needs patch
title: add exact_type argument to assertIsInstance -> suggest assertIs(type(obj), cls) for exact type checking
type: feature request -> behavior

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Sun Nov 13 04:07:05 2011
From: report at bugs.python.org (Raymond Hettinger)
Date: Sun, 13 Nov 2011 03:07:05 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321153625.33.0.343168291097.issue12875@psf.upfronthosting.co.za>


Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

This patch looks fine.

----------
nosy: +rhettinger

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sun Nov 13 04:08:34 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 13 Nov 2011 03:08:34 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321153714.53.0.202579446188.issue12875@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

LGTM

----------
stage:  -> commit review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sun Nov 13 23:52:12 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sun, 13 Nov 2011 22:52:12 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <E1RPiu8-0008VU-D7@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 87ecfd5cd5d1 by Eli Bendersky in branch '2.7':
Normalize the keyword arguments documentation notation in re.rst. Closes issue #12875
http://hg.python.org/cpython/rev/87ecfd5cd5d1

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Sun Nov 13 23:53:25 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 13 Nov 2011 22:53:25 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321224805.82.0.679119978506.issue12875@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Mon Nov 14 00:08:24 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sun, 13 Nov 2011 23:08:24 +0000
Subject: [docs] [issue13239] Remove <> operator from Grammar/Grammar
In-Reply-To: <1319188291.02.0.897231487042.issue13239@psf.upfronthosting.co.za>
Message-ID: <E1RPj9o-00018Z-QE@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset a259511351d9 by Eli Bendersky in branch '3.2':
Clarify the existence of the <> operator in Grammar/Grammar with a comment, for issue 13239
http://hg.python.org/cpython/rev/a259511351d9

New changeset 410115400838 by Eli Bendersky in branch 'default':
Clarify the existence of the <> operator in Grammar/Grammar with a comment. Closes issue 13239
http://hg.python.org/cpython/rev/410115400838

----------
nosy: +python-dev
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13239>
_______________________________________

From report at bugs.python.org  Mon Nov 14 00:13:56 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 13 Nov 2011 23:13:56 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321226036.83.0.180792769739.issue13386@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Ezio, regarding your latest message:

  "The problem is when the default placeholder is some unique object() or some _internal value (we had something similar with a socket timeout once)."

I hope this should be rare enough not to present a significant problem with the _convention_. Such cases can be reviewed specifically and the best way to document will be discussed per case.

  "Also for something like str.strip(), would you document chars=None or chars=" \n\r\t\v\f"?"

I think it would be better to document chars=None, because this is a simple value the user can pass (if he wants to do it explicitly), without thinking (and forgetting) about the specific delimeters. That None actually means " \n\r\t\v\f" should be explicitly documented below the function signature, of course.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 00:24:28 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 13 Nov 2011 23:24:28 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1302623785.46.0.16009713021.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321226668.56.0.93861998362.issue11836@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Sandro - yep, the sentinels arg is also undocumented in multiprocessing.PipeConnection.recv() and further down the road...

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From report at bugs.python.org  Mon Nov 14 00:28:20 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 13 Nov 2011 23:28:20 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1302623785.46.0.16009713021.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321226900.38.0.793699754532.issue11836@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

However, sentinels *are* mentioned in the multiprocessing doc, below multiprocessing.Process:

"
sentinel

    A numeric handle of a system object which will become ?ready? when the process ends.

    On Windows, this is an OS handle usable with the WaitForSingleObject and WaitForMultipleObjects family of API calls. On Unix, this is a file descriptor usable with primitives from the select module.

    You can use this value if you want to wait on several events at once. Otherwise calling join() is simpler.

    New in version 3.3.
"

>From a cursory glance on the implementation in Lib/multiprocessing/connection.py, this is the same sentinel.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From report at bugs.python.org  Mon Nov 14 05:21:47 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 14 Nov 2011 04:21:47 +0000
Subject: [docs] [issue12875] backport re.compile flags default value
	documentation
In-Reply-To: <1314854228.49.0.163476055978.issue12875@psf.upfronthosting.co.za>
Message-ID: <1321244507.57.0.187395017771.issue12875@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
resolution:  -> fixed
stage: commit review -> committed/rejected

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12875>
_______________________________________

From report at bugs.python.org  Mon Nov 14 06:11:07 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 14 Nov 2011 05:11:07 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321247466.98.0.478442835897.issue13386@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> You should also explicitly specify what happens in several optional but 
> not keyword args are needed. AFAIU the convention is:
>   func(arg1, arg2[, opt1, opt2])

IIUC that would mean that either you pass only arg1 and arg2, or you also pass both opt1 and opt2.
I think the correct notation for that is e.g.:
  str.startswith(prefix[, start[, end]])

I also saw "func(foo[, bar][, baz])" for cases where either bar or baz can be passed, but since this requires keyword arguments, the "func(foo, bar=x, baz=y)" notation should be used instead, and the documentation should then explain that either one can be passed.

I also agree with what you said in your last message.  What can't be expressed with a notation can always be described with words.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 06:14:23 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 14 Nov 2011 05:14:23 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321247663.36.0.389972500363.issue13386@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

What you say makes sense, now I just have to dig up where I saw instances of [, opt1, opt2]

If anything, this is another proof that such conventions must be agreed upon and meticulously documented.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 11:00:20 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Mon, 14 Nov 2011 10:00:20 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321264820.07.0.432445414473.issue13386@psf.upfronthosting.co.za>


Changes by Petri Lehtinen <petri at digip.org>:


----------
nosy: +petri.lehtinen

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 11:50:26 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Mon, 14 Nov 2011 10:50:26 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321267826.64.0.460977918069.issue13386@psf.upfronthosting.co.za>


Changes by Terry J. Reedy <tjreedy at udel.edu>:


----------
nosy: +terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 13:21:30 2011
From: report at bugs.python.org (Baptiste Carvello)
Date: Mon, 14 Nov 2011 12:21:30 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321273290.66.0.751978720206.issue13386@psf.upfronthosting.co.za>


Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Hi all, here is a relevant user story. I'm afraid it won't help you much, but it highlights the importance of consistent conventions in doc.

My girlfriend is learning Python with no prior programing experience. She quite naturally got used to calling help(function), and noted the following:

1) she naturally understood the meaning of the [opt] notation

2) she did not understand the opt=default notation, as she didn't have a sufficient experience with Python to recognize the syntax

3) even after learning what it meant, she still found that notation obscure and unappealing

4) she got annoyed that two completely different notations where used for two very close concepts

5) she got annoyed that there was no user-discoverable and user-understandable document introducing those notations (if there is one, my mistake :-)

I have no ovious solutions to the annoyances. Regarding 4), maybe the [opt=default] notation has something good after all: that it reminds of the [opt] one. And regarding 5), if there is a canonical document about documentation conventions, I could try to summarize it in a language aimed at beginners.

----------
nosy: +baptiste.carvello

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 13:40:09 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 14 Nov 2011 12:40:09 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321274409.88.0.235362900008.issue13386@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

Thanks for the feedback!

> 1) she naturally understood the meaning of the [opt] notation

I guess this depends on her background, I've seen people trying to use [] in function calls because they saw them in the doc or confusing them for lists, so I guess that each notation has its pros and cons.

> 2) she did not understand the opt=default notation, as she didn't 
> have a sufficient experience with Python to recognize the syntax

I agree that at the beginning it could be a bit confusing, but keyword arguments are an important part of Python and it's among the first things that one should learn.  After that it should be even more natural than [].

> 3) even after learning what it meant, she still found that notation 
> obscure and unappealing

...or maybe not.  Can she say what in particular is obscure and unappealing?

> 4) she got annoyed that two completely different notations where used 
> for two very close concepts

This is a good point, and we are trying to move to the arg=default notation.  Unfortunately there are still places that use the old notation.  C functions that have optional arguments but don't accept keyword arguments are a bit unusual, and IIUC in most of the cases that's an implementation detail that could be removed.

> 5) she got annoyed that there was no user-discoverable and 
> user-understandable document introducing those notations (if there is > one, my mistake :-)

This brings ups another interesting point.  These conventions will probably end up in the "documenting" section, that is aimed to doc writers.  Do we need an introductory page aimed to the readers that explains the conventions used in the doc?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 14:23:42 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 14 Nov 2011 13:23:42 +0000
Subject: [docs] [issue13239] Remove <> operator from Grammar/Grammar
In-Reply-To: <1319188291.02.0.897231487042.issue13239@psf.upfronthosting.co.za>
Message-ID: <1321277021.94.0.169866167348.issue13239@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

+# <> isn't actually a valid comparison operator in Python. It's here for the
+# sake of a __future__ import described in PEP 401

If we wanted to be exact, the operator isn?t here for a __future__ import but for a feature enabled by a __future__ import.  But I don?t feel strongly about this at all :)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13239>
_______________________________________

From report at bugs.python.org  Mon Nov 14 14:46:02 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 14 Nov 2011 13:46:02 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321278362.5.0.837227592765.issue13386@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

> Do we need an introductory page aimed to the readers that explains
> the conventions used in the doc?

Explaining notational conventions at the start of a technical reference sounds like a best practice to me.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 17:29:45 2011
From: report at bugs.python.org (Baptiste Carvello)
Date: Mon, 14 Nov 2011 16:29:45 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321274409.88.0.235362900008.issue13386@psf.upfronthosting.co.za>
Message-ID: <4EC141EC.7010709@baptiste-carvello.net>


Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Le 14/11/2011 13:40, Ezio Melotti a ?crit :

>> 1) she naturally understood the meaning of the [opt] notation
>
> I guess this depends on her background, I've seen people trying to use [] in function calls because they saw them in the doc or confusing them for lists, so I guess that each notation has its pros and cons.
> 

agreed, the [] notation also has its dangers. But the current situation
doesn't avoid them, because users will meet both notations.

>> 2) she did not understand the opt=default notation, as she didn't 
>> have a sufficient experience with Python to recognize the syntax
>
> I agree that at the beginning it could be a bit confusing, but keyword arguments are an important part of Python and it's among the first things that one should learn.  After that it should be even more natural than [].
> 

the thing is, beginners need to use other people's functions before they
really get into writing their own. You need some practice with a syntax
before you are able to recognize it in another context.

>> 3) even after learning what it meant, she still found that notation 
>> obscure and unappealing
> 
> ...or maybe not.  Can she say what in particular is obscure and unappealing?
> 

I'd say the fact that the main information (that the argument is
optional) is not highlighted and only appears as a side-effect of having
a default. Inversely, a lot of importance is given to the value of the
default, which most users can ignore at first.

>> 4) she got annoyed that two completely different notations where used 
>> for two very close concepts
> 
> This is a good point, and we are trying to move to the arg=default notation.  Unfortunately there are still places that use the old notation.  C functions that have optional arguments but don't accept keyword arguments are a bit unusual, and IIUC in most of the cases that's an implementation detail that could be removed.
> 

That would would solve the problem for the stdlib, but other C libraries
also have optional arguments which don't accept keyword arguments (for
example NumPy ufuncs). Will converting to a keyword argument work for
all of them?

>> 5) she got annoyed that there was no user-discoverable and 
>> user-understandable document introducing those notations (if there is > one, my mistake :-)
> 
> This brings ups another interesting point.  These conventions will probably end up in the "documenting" section, that is aimed to doc writers.  Do we need an introductory page aimed to the readers that explains the conventions used in the doc?
> 

I would say we need one. It should probably also be part of the "help()"
tool, as the function prototype is the first information that
help(function) displays.

Cheers,
Baptiste

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 17:50:37 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 14 Nov 2011 16:50:37 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
Message-ID: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>


New submission from ?ric Araujo <merwok at netwok.org>:

I wanted to know if sys.executable was always an absolute path but the doc does not talk about that.

(My use case is that I?d like to reload a process and I wonder if I can call os.execve or if I need to use os.execvpe.)

----------
assignee: docs at python
components: Documentation
messages: 147609
nosy: docs at python, eric.araujo
priority: normal
severity: normal
status: open
title: Document absoluteness of sys.executable
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Mon Nov 14 17:58:11 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 14 Nov 2011 16:58:11 +0000
Subject: [docs] [issue13249] argparse.ArgumentParser() lists arguments in
	the wrong	order
In-Reply-To: <1319394759.74.0.692830705102.issue13249@psf.upfronthosting.co.za>
Message-ID: <1321289891.78.0.333370554336.issue13249@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

I would not use a note directive.  Notes and warnings distract and sometimes scare readers.  For a simple coding recommendation like this, I think a regular paragraph would suffice.  To make sure it?s not lost after pages of options description, maybe it could be put right after the signature?  Also, it would be nice to explicit the why of this recommendation (e.g. ?due to the number of arguments, it is recommended to always use keyword arguments for this function?).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13249>
_______________________________________

From report at bugs.python.org  Mon Nov 14 17:59:42 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Mon, 14 Nov 2011 16:59:42 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1302623785.46.0.16009713021.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321289982.83.0.348342831466.issue11836@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

Well, the sentinels argument, right now, is meant to be used internally. I don't think it's a good thing to document it, since I don't think it's a very clean API (I know, I introduced it :-)) - it's just so that concurrent.futures can detect dead processes.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From report at bugs.python.org  Mon Nov 14 20:50:20 2011
From: report at bugs.python.org (sbt)
Date: Mon, 14 Nov 2011 19:50:20 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1302623785.46.0.16009713021.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321300220.35.0.384210185231.issue11836@psf.upfronthosting.co.za>


sbt <shibturn at gmail.com> added the comment:

> Well, the sentinels argument, right now, is meant to be used 
> internally. I don't think it's a good thing to document it, 
> since I don't think it's a very clean API (I know, I introduced 
> it :-))

Wouldn't a better alternative be to have a wait function which can deal with readable pipe connections and integer handles?

On Unix this would just delegate to select().

On Windows it could work as follows:
* initiate an overlapped read on each connection
* call WaitForMultipleObjects()
* cancel each overlapped read
* continue any read which succeeded but only gave a partial message
* store read messages on associated connection objects

I did start on such a patch.  It worked, but I did not get round to writing tests for it...

----------
nosy: +sbt

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From report at bugs.python.org  Mon Nov 14 20:51:22 2011
From: report at bugs.python.org (Eric Snow)
Date: Mon, 14 Nov 2011 19:51:22 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321300282.25.0.688847778889.issue13386@psf.upfronthosting.co.za>


Eric Snow <ericsnowcurrently at gmail.com> added the comment:

>> 4) she got annoyed that two completely different notations where used 
>> for two very close concepts
>
> This is a good point, and we are trying to move to the arg=default
> notation.  Unfortunately there are still places that use the old
> notation.  C functions that have optional arguments but don't accept
> keyword arguments are a bit unusual, and IIUC in most of the cases
> that's an implementation detail that could be removed.

So would it be worth the effort to identify each such place in the built-ins/stdlib and eventually change them all?  I've seen support for doing so in other tracker issues and think it's a good idea personally.

----------
nosy: +eric.snow

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Mon Nov 14 21:44:02 2011
From: report at bugs.python.org (Roy Smith)
Date: Mon, 14 Nov 2011 20:44:02 +0000
Subject: [docs] [issue13249] argparse.ArgumentParser() lists arguments in
	the wrong	order
In-Reply-To: <1319394759.74.0.692830705102.issue13249@psf.upfronthosting.co.za>
Message-ID: <1321303441.98.0.46290300458.issue13249@psf.upfronthosting.co.za>


Roy Smith <roy at panix.com> added the comment:

Before I build another patch, would you be OK with leaving it as a note, but adding the "due to the number of arguments" language?  There's a lot of text here, and people tend to just zoom in on the bits and pieces they need right now.  I think there is value in making this stand out as a note.

If you feel strongly this should not be a note, let me know and I'll change it.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13249>
_______________________________________

From report at bugs.python.org  Mon Nov 14 21:53:37 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Mon, 14 Nov 2011 20:53:37 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1321300220.35.0.384210185231.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321303727.3282.1.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> Wouldn't a better alternative be to have a wait function which can
> deal with readable pipe connections and integer handles?
> 
> On Unix this would just delegate to select().
> 
> On Windows it could work as follows:
> * initiate an overlapped read on each connection
> * call WaitForMultipleObjects()
> * cancel each overlapped read
> * continue any read which succeeded but only gave a partial message
> * store read messages on associated connection objects

This sounds like a good direction to me.
(of course it must also preserve existing functionality;
test_concurrent_futures will check for that)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From report at bugs.python.org  Tue Nov 15 02:45:06 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Tue, 15 Nov 2011 01:45:06 +0000
Subject: [docs] [issue13249] argparse.ArgumentParser() lists arguments in
	the wrong	order
In-Reply-To: <1319394759.74.0.692830705102.issue13249@psf.upfronthosting.co.za>
Message-ID: <1321321506.0.0.795015431997.issue13249@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

I agree with Eric both as to placement (first paragraph) and wording (with explanation). I don't have time to review otherwise at the moment.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13249>
_______________________________________

From report at bugs.python.org  Tue Nov 15 06:07:40 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 15 Nov 2011 05:07:40 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321333660.49.0.964004049538.issue13386@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

""So would it be worth the effort to identify each such place in the built-ins/stdlib and eventually change them all?  I've seen support for doing so in other tracker issues and think it's a good idea personally.""

Probably, if this will bring some added value in addition to being easier to document.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From Daniel.Dieterle at comsoft.aero  Mon Nov  7 09:10:06 2011
From: Daniel.Dieterle at comsoft.aero (Dieterle, Daniel)
Date: Mon, 7 Nov 2011 09:10:06 +0100
Subject: [docs] Bug in documentation of module subprocess,
	method send_signal
In-Reply-To: <CAF-Rda9SRh6hG968aTa0zMdyFVpk9-6jrv5DB9T7K8FZWDcHeA@mail.gmail.com>
References: <B8940AF89405544998A30624A584065FCD3012@CSMAIL.cs-nt-domaene.de>
	<CAF-Rda9SRh6hG968aTa0zMdyFVpk9-6jrv5DB9T7K8FZWDcHeA@mail.gmail.com>
Message-ID: <B8940AF89405544998A30624A584065FCD32F5@CSMAIL.cs-nt-domaene.de>

Hi Eli,
 
it's not a problem of implementation, because there is no way of killing
an individual process with the CTRL-C-EVENT signal.
 
I do not know why the subprocess.CREATE_NEW_PROCESS_GROUP parameter was
introduced. But it is useless for terminating a process with os.kill()
in combination with signal.SIGTERM, which corresponds to a CTRL-C-EVENT.
A CTRL-C-EVENT is only forwarded to the process if the process group is
zero. Therefore the Note in the documentation on Popen.send_signal() is
wrong.
 
Bye,
Daniel.
 
 
________________________________

Von: Eli Bendersky [mailto:eliben at gmail.com] 
Gesendet: Sonntag, 6. November 2011 04:28
An: Dieterle, Daniel
Cc: docs at python.org
Betreff: Re: [docs] Bug in documentation of module subprocess, method
send_signal




	in the documentation
(http://docs.python.org/library/subprocess.html#subprocess.Popen.send_si
gnal
<http://docs.python.org/library/subprocess.html#subprocess.Popen.send_si
gnal> ) is a bug. 

	CTRL_C_EVENT can not be sent to processes started with a
creationflags parameter which includes CREATE_NEW_PROCESS_GROUP. Why can
be read in the msdn documentation
http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.
85%29.aspx
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs
.85%29.aspx>  .

	A workaround using CTRL_C_EVENT nevertheless is described here: 
	
http://stackoverflow.com/questions/7085604/sending-c-to-python-subproces
s-objects-on-windows/7980368#7980368
<http://stackoverflow.com/questions/7085604/sending-c-to-python-subproce
ss-objects-on-windows/7980368#7980368>          
	


Hi Daniel,

If what you say is true (and I assume it is), it may be a problem with
the implementation, not only the documentation. Could you perchance
reproduce this? Perhaps an actual bug report on subprocess should be
opened, and not only a documentation fix.

Eli
 


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111107/27d0a5a5/attachment.html>

From guanfenglin at gmail.com  Sun Nov 13 19:20:44 2011
From: guanfenglin at gmail.com (James Lin)
Date: Mon, 14 Nov 2011 07:20:44 +1300
Subject: [docs] how about adding anchor tags to the functions
Message-ID: <CAD-RA2RWFXciafCa_xQftM_669K_eHY_TEUKWL_hJkPXZupnoA@mail.gmail.com>

Hi there,

First of all, hands down to the effort for the detailed Python
documentation.

I was a long time PHP programmer and enjoyed the PHP documentation style,
single page of specific function documentation and samples, then community
contribution. While I agree Python is different to PHP, but I think the
Python ducmentation still has room to improve and the community should
still be able to "borrow" some goodies from the PHP documentation style.

Perhaps I may not be the first one who suggested this, but I do find having
the anchor tags on the function names(so google can index and provide
directly to the specific section) in the doucmentation really reduce some
frustration on reading the python documentation.

eg. if I am searching "python urllib urlretrieve" and google results page
shows the relevant information but with this link here
http://docs.python.org/library/urllib.html, then I am required to do
another page search to locate the information i want, it would be great
that if the site provides links like
http://docs.python.org/library/urllib.html#urllib.urlretrieve, so the
browser automatically scrolls to the right section? Also, it would be
awesome to have some code examples of each function, if that's too much
effort needed, how about having a collapsed community section(similar to
PHP) under each function?

Regards

James Lin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111114/8c609ee2/attachment.html>

From the.ubik at gmail.com  Mon Nov 14 14:01:55 2011
From: the.ubik at gmail.com (Mr&Mrs D)
Date: Mon, 14 Nov 2011 15:01:55 +0200
Subject: [docs] typo in tutorial 2.7/3.1.2. Strings
Message-ID: <CABRG_PG=qCBJW-=oeS_kYCU8CKcxE9Rw3kCUL_ygP6qpzuUgRg@mail.gmail.com>

The string
*The interpreter prints the result of string operations in the same way as
they are typed for input: inside quotes, and with quotes and other funny
characters escaped by backslashes, to show the precise value. The string is
enclosed in double quotes if the string contains a single quote and no
double quotes, else it?s enclosed in single quotes.*
is repeated verbatim twice

Thanks
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111114/6d631f06/attachment.html>

From ddrouin at mypublisher.com  Mon Nov 14 20:21:18 2011
From: ddrouin at mypublisher.com (David Drouin)
Date: Mon, 14 Nov 2011 19:21:18 +0000
Subject: [docs] Option Parser Typos
Message-ID: <021DE3C840C77745B0811DE2BF1327BE296D8928@exchange2.mypublisher.local>

Two typos found here:

In http://docs.python.org/library/optparse.html

Under
15.5.2.6.1. Grouping Options
...

A bit more complete example might invole using more than one group: still extendind the previous example:

Dave Drouin, MSCS
Senior Developer | MyPublisher
914.773.4312 ext. 125
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111114/d7eff18a/attachment.html>

From report at bugs.python.org  Tue Nov 15 14:40:42 2011
From: report at bugs.python.org (Baptiste Carvello)
Date: Tue, 15 Nov 2011 13:40:42 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321300282.25.0.688847778889.issue13386@psf.upfronthosting.co.za>
Message-ID: <4EC26BD0.7050004@baptiste-carvello.net>


Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Le 14/11/2011 20:51, Eric Snow a ?crit :
> 
> So would it be worth the effort to identify each such place in the built-ins/stdlib and eventually change them all?  I've seen support for doing so in other tracker issues and think it's a good idea personally.
> 

I ran a few grep searches from the root of a recent hg tip:

1) grep -n -r --include=*.py --include=*.c --exclude="topics.py" -E
'.+\(.*\[[[:space:]]*,.*\].*\)' .

This looks for variants of "function(args [, opt])". There were 231
hits, I caught no false positives.

2) grep -n -r --include=*.py --include=*.c --exclude="topics.py" -E
'.+\(.*\[.*,[[:space:]]*\].*\)' .

As this pattern is valid Python syntax, I got mostly false positives,
but also a few interesting cases such as "range([start,] stop[, step])"
or "islice(seq, [start,] stop [, step])"

I'm afraid those last examples cannot be described with valid Python syntax.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Tue Nov 15 15:01:02 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 15 Nov 2011 14:01:02 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321365662.73.0.290122962966.issue13386@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

>>> C functions that have optional arguments but don't accept keyword arguments are a bit unusual,
>>> and IIUC in most of the cases that's an implementation detail that could be removed.
>> So would it be worth the effort to identify each such place in the built-ins/stdlib and
>> eventually change them all?  I've seen support for doing so in other tracker issues and think
>> it's a good idea personally.
Me too.  (Can you give the #ids of these other issues?)

> Probably, if this will bring some added value in addition to being easier to document.
I think we should fix C functions to accept kwargs for the sake of Python programmers, not merely to ease documentation (that would just be a nice side-effect :)


> a few interesting cases such as "range([start,] stop[, step])"or "islice(seq, [start,] stop [, step])"
> I'm afraid those last examples cannot be described with valid Python syntax.
Sphinx lets us give multiple signatures.  I?ve just checked that this markup is valid and does not create duplicate index entries

  .. function:: range(stop)
                range(start, stop)
                range(start, stop, step)

:)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Tue Nov 15 15:15:32 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 15 Nov 2011 14:15:32 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321366532.24.0.684001648462.issue13386@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> Me too.  (Can you give the #ids of these other issues?)

See for example #13012.

> I think we should fix C functions to accept kwargs for the sake of 
> Python programmers, not merely to ease documentation (that would just 
> be a nice side-effect :)

And also for compatibility for other implementations like PyPy.  I'm still not sure that is a good idea to do a mass conversion of all the functions though.

> Sphinx lets us give multiple signatures.  I?ve just checked that this 
> markup is valid and does not create duplicate index entries

This is something I was considering, but I'm afraid it might get too verbose (and introduce yet another convention).  Sometimes this feature is also (mis?)used to group similar functions.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Tue Nov 15 15:20:54 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 15 Nov 2011 14:20:54 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321366854.08.0.0957593955417.issue13386@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

>> I think we should fix C functions to accept kwargs for the sake of Python programmers
> And also for compatibility for other implementations like PyPy.
Good point.

> I'm still not sure that is a good idea to do a mass conversion of all the functions though.
If there were only a handful of them it may be okay, but otherwise one issue per class or module sounds good.

>> Sphinx lets us give multiple signatures
> This is something I was considering, but I'm afraid it might get too verbose
I find my example for range much more readable that the current markup with brackets.

> (and introduce yet another convention).
I can live with this special case for the two or three functions that need it.  It becomes moot if range gets fixed to support kwargs :)

> Sometimes this feature is also (mis?)used to group similar functions.
IIUC it *is* the intended use case for the syntax, not a misuse: You tell Sphinx that you want link targets for these functions to end up here, and then you write doc.  See for example the os docs: this syntax allows for nice grouping.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Tue Nov 15 17:47:43 2011
From: report at bugs.python.org (ipatrol)
Date: Tue, 15 Nov 2011 16:47:43 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321375663.43.0.916956418058.issue10772@psf.upfronthosting.co.za>


ipatrol <ipatrol6010 at yahoo.com> added the comment:

The patch has been submitted, now we just need to apply it and update the online docs accordingly.

----------
status: open -> pending
versions: +Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Tue Nov 15 17:48:25 2011
From: report at bugs.python.org (Brian Curtin)
Date: Tue, 15 Nov 2011 16:48:25 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321375705.6.0.212116487949.issue10772@psf.upfronthosting.co.za>


Changes by Brian Curtin <brian at python.org>:


----------
status: pending -> open
versions:  -Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Tue Nov 15 17:51:14 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 15 Nov 2011 16:51:14 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321375874.33.0.263141795722.issue10772@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
stage: needs patch -> patch review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Tue Nov 15 17:58:26 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 15 Nov 2011 16:58:26 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321376305.96.0.750364134533.issue10772@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Ezio made further comments, follow the ?review? link.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Tue Nov 15 21:03:00 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 15 Nov 2011 20:03:00 +0000
Subject: [docs] [issue11261] urlopen breaks when data parameter is used.
In-Reply-To: <1298239651.85.0.222287222979.issue11261@psf.upfronthosting.co.za>
Message-ID: <1321387380.38.0.574056899498.issue11261@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +ezio.melotti
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11261>
_______________________________________

From report at bugs.python.org  Tue Nov 15 21:07:03 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 15 Nov 2011 20:07:03 +0000
Subject: [docs] [issue4395] Document auto __ne__ generation;
	provide a use case for non-trivial __ne__
In-Reply-To: <1227464493.77.0.130820783094.issue4395@psf.upfronthosting.co.za>
Message-ID: <1321387623.04.0.588913961907.issue4395@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
versions: +Python 3.3 -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4395>
_______________________________________

From report at bugs.python.org  Tue Nov 15 21:47:35 2011
From: report at bugs.python.org (Eric Snow)
Date: Tue, 15 Nov 2011 20:47:35 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321390055.73.0.345969557376.issue13386@psf.upfronthosting.co.za>


Eric Snow <ericsnowcurrently at gmail.com> added the comment:

> Me too.  (Can you give the #ids of these other issues?)

#13012 is the one that I was thinking of (msg144328 specifically).  However, I'm sure there was one more recently (which I can't find now).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Tue Nov 15 21:48:02 2011
From: report at bugs.python.org (Eric Snow)
Date: Tue, 15 Nov 2011 20:48:02 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321390082.33.0.539243911132.issue13386@psf.upfronthosting.co.za>


Eric Snow <ericsnowcurrently at gmail.com> added the comment:

@msg147671

+1

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Tue Nov 15 23:42:25 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 15 Nov 2011 22:42:25 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1302623785.46.0.16009713021.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321396945.6.0.169252235058.issue11836@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Then it appears to me that Sandro's patch is good and can be committed.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From report at bugs.python.org  Tue Nov 15 23:52:53 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 15 Nov 2011 22:52:53 +0000
Subject: [docs] [issue11836] multiprocessing.queues.SimpleQueue is
	undocumented
In-Reply-To: <1321396945.6.0.169252235058.issue11836@psf.upfronthosting.co.za>
Message-ID: <1321397281.3272.15.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> Then it appears to me that Sandro's patch is good and can be committed.

The doc patch is good. However, if you start exposing SimpleQueue at the
top package level, you have to do it in 3.3 only (since that's a new
API), and also mention it somehow in the doc.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11836>
_______________________________________

From eliben at gmail.com  Wed Nov 16 00:05:14 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Wed, 16 Nov 2011 01:05:14 +0200
Subject: [docs] typo in tutorial 2.7/3.1.2. Strings
In-Reply-To: <CABRG_PG=qCBJW-=oeS_kYCU8CKcxE9Rw3kCUL_ygP6qpzuUgRg@mail.gmail.com>
References: <CABRG_PG=qCBJW-=oeS_kYCU8CKcxE9Rw3kCUL_ygP6qpzuUgRg@mail.gmail.com>
Message-ID: <CAF-Rda8cdqEEXuuwSUkZ8tSr8k_nFcSz=4iBZkqQaLfZD22wHQ@mail.gmail.com>

On Mon, Nov 14, 2011 at 15:01, Mr&Mrs D <the.ubik at gmail.com> wrote:
> The string
> The interpreter prints the result of string operations in the same way as
> they are typed for input: inside quotes, and with quotes and other funny
> characters escaped by backslashes, to show the precise value. The string is
> enclosed in double quotes if the string contains a single quote and no
> double quotes, else it?s enclosed in single quotes.
> is repeated verbatim twice
>

Hello Mr & Mrs D,
I'm not sure I understand what is repeated twice, could you be more specific?
Please note that the two sentences that constitute the paragraph you
quoted are not repetitions one of another, but rather convey somewhat
different meanings.
Eli

From report at bugs.python.org  Wed Nov 16 04:34:33 2011
From: report at bugs.python.org (Roy Smith)
Date: Wed, 16 Nov 2011 03:34:33 +0000
Subject: [docs] [issue13249] argparse.ArgumentParser() lists arguments in
	the wrong	order
In-Reply-To: <1319394759.74.0.692830705102.issue13249@psf.upfronthosting.co.za>
Message-ID: <1321414473.03.0.135896633263.issue13249@psf.upfronthosting.co.za>


Roy Smith <roy at panix.com> added the comment:

Another patch, with the most recent review suggestions incorporated.

----------
Added file: http://bugs.python.org/file23703/Issue13249-3.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13249>
_______________________________________

From eliben at gmail.com  Wed Nov 16 04:55:27 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Wed, 16 Nov 2011 05:55:27 +0200
Subject: [docs] typo in tutorial 2.7/3.1.2. Strings
In-Reply-To: <CABRG_PHyyA6=7LHjt0j5vPqOmEmGB87ikybT+zQWnX_miNPrRg@mail.gmail.com>
References: <CABRG_PG=qCBJW-=oeS_kYCU8CKcxE9Rw3kCUL_ygP6qpzuUgRg@mail.gmail.com>
	<CAF-Rda8cdqEEXuuwSUkZ8tSr8k_nFcSz=4iBZkqQaLfZD22wHQ@mail.gmail.com>
	<CABRG_PHyyA6=7LHjt0j5vPqOmEmGB87ikybT+zQWnX_miNPrRg@mail.gmail.com>
Message-ID: <CAF-Rda_WMO=J_wW+_8fy1HF7xvDFJnijkzMcnHaE70poZhJh2g@mail.gmail.com>

On Wed, Nov 16, 2011 at 01:35, Mr&Mrs D <the.ubik at gmail.com> wrote:
> Thanks for replying :)
> The italicized string in my original message is present verbatim in the text
> twice - use the browser search function and search for :
> The interpreter prints the result of string operations in the same way as
> they are typed for input: inside quotes, and with quotes and other funny
> characters escaped by backslashes, to show the precise value. The string is
> enclosed in double quotes if the string contains a single quote and no
> double quotes, else it?s enclosed in single quotes.
>
> in url : http://docs.python.org/tutorial/introduction.html
>
> Maybe intentional though I doubt it
>
> HTH - Let me know if you need anything else
>
> George
>

Thanks for the report. The 2.7 tutorial has been fixed - changeset ed8aace4db0e.

Eli

From eliben at gmail.com  Wed Nov 16 05:04:33 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Wed, 16 Nov 2011 06:04:33 +0200
Subject: [docs] Option Parser Typos
In-Reply-To: <021DE3C840C77745B0811DE2BF1327BE296D8928@exchange2.mypublisher.local>
References: <021DE3C840C77745B0811DE2BF1327BE296D8928@exchange2.mypublisher.local>
Message-ID: <CAF-Rda-XxUP4mmbYqLQwoWz9siBmCJjWrEp5=8+sKbf58xgQ3A@mail.gmail.com>

On Mon, Nov 14, 2011 at 21:21, David Drouin <ddrouin at mypublisher.com> wrote:
> Two typos found here:
>
> In http://docs.python.org/library/optparse.html
>
> Under
>
> 15.5.2.6.1. Grouping Options
>

Hi David,

Thanks for the report! Typos fixed in changesets 2a3b60d28f6c (2.7),
738c43484b47 (3.2) and 72bdfef4aea7 (3.3)

Eli

From report at bugs.python.org  Wed Nov 16 12:45:26 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 16 Nov 2011 11:45:26 +0000
Subject: [docs] [issue4246] execution model - clear and complete example
	in	documentation
In-Reply-To: <1225551571.75.0.81232740458.issue4246@psf.upfronthosting.co.za>
Message-ID: <1321443926.15.0.169931362041.issue4246@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +ezio.melotti
stage:  -> needs patch
versions: +Python 2.7, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4246>
_______________________________________

From report at bugs.python.org  Wed Nov 16 17:45:41 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Wed, 16 Nov 2011 16:45:41 +0000
Subject: [docs] [issue8913] Document that datetime.__format__ is
	datetime.strftime
In-Reply-To: <1275794779.99.0.00462382173098.issue8913@psf.upfronthosting.co.za>
Message-ID: <1321461941.22.0.133393865711.issue8913@psf.upfronthosting.co.za>


Changes by Florent Xicluna <florent.xicluna at gmail.com>:


----------
type:  -> behavior
versions: +Python 3.3 -Python 2.6, Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8913>
_______________________________________

From report at bugs.python.org  Wed Nov 16 23:48:13 2011
From: report at bugs.python.org (Nebelhom)
Date: Wed, 16 Nov 2011 22:48:13 +0000
Subject: [docs] [issue13416] Python Tutorial, Section 3,
	Minor PEP 8 adjustment
Message-ID: <1321483693.18.0.17340985314.issue13416@psf.upfronthosting.co.za>


New submission from Nebelhom <nebelhom at googlemail.com>:

Python Tutorial 3.3a

3. An informal introduction to python

example:

-------------------------------------------------------------
# this is the first comment
SPAM = 1                 # and this is the second comment
                         # ... and now a third!
STRING = "# This is not a comment."
-------------------------------------------------------------

Comment: It is probably best to use PEP 8 straight from the start.
Therefore variable names should be all lowercase with connecting underscores (if necessary)

i.e. spam = 1 and string = "#This is not a comment." instead of all uppercase.

----------
assignee: docs at python
components: Documentation
messages: 147777
nosy: Nebelhom, docs at python, ncoghlan
priority: normal
severity: normal
status: open
title: Python Tutorial, Section 3, Minor PEP 8 adjustment
versions: Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13416>
_______________________________________

From report at bugs.python.org  Thu Nov 17 00:12:10 2011
From: report at bugs.python.org (Benjamin Peterson)
Date: Wed, 16 Nov 2011 23:12:10 +0000
Subject: [docs] [issue13416] Python Tutorial, Section 3,
	Minor PEP 8 adjustment
In-Reply-To: <1321483693.18.0.17340985314.issue13416@psf.upfronthosting.co.za>
Message-ID: <1321485130.69.0.143817018959.issue13416@psf.upfronthosting.co.za>


Benjamin Peterson <benjamin at python.org> added the comment:

It's fine as it is; constants are often denoted with capital letters.

----------
nosy: +benjamin.peterson
resolution:  -> rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13416>
_______________________________________

From report at bugs.python.org  Thu Nov 17 00:53:09 2011
From: report at bugs.python.org (Marc Sibson)
Date: Wed, 16 Nov 2011 23:53:09 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321487588.94.0.6761316265.issue10772@psf.upfronthosting.co.za>


Marc Sibson <sibson at gmail.com> added the comment:

changes as per the review,

----------
Added file: http://bugs.python.org/file23713/issue10772.patch3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Thu Nov 17 09:44:40 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Thu, 17 Nov 2011 08:44:40 +0000
Subject: [docs] [issue13416] Python Tutorial, Section 3,
	Minor PEP 8 adjustment
In-Reply-To: <1321483693.18.0.17340985314.issue13416@psf.upfronthosting.co.za>
Message-ID: <1321519480.38.0.277291784897.issue13416@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
stage:  -> committed/rejected

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13416>
_______________________________________

From report at bugs.python.org  Thu Nov 17 20:02:05 2011
From: report at bugs.python.org (Georg Brandl)
Date: Thu, 17 Nov 2011 19:02:05 +0000
Subject: [docs] [issue13421] PyCFunction_* are not documented anywhere
In-Reply-To: <1321553683.63.0.825049607384.issue13421@psf.upfronthosting.co.za>
Message-ID: <1321556525.42.0.970098753404.issue13421@psf.upfronthosting.co.za>


Changes by Georg Brandl <georg at python.org>:


----------
assignee: georg.brandl -> docs at python
nosy: +docs at python

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13421>
_______________________________________

From report at bugs.python.org  Thu Nov 17 23:15:35 2011
From: report at bugs.python.org (Eric V. Smith)
Date: Thu, 17 Nov 2011 22:15:35 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321568135.54.0.373452698441.issue13386@psf.upfronthosting.co.za>


Eric V. Smith <eric at trueblade.com> added the comment:

I just ran across the other reason that having the actual default values documented is important. Sometimes I want to do this:

some_func(param if some_condition else <use the default value>)

If some_condition is False, I want the default behavior, if not, I want to pass in a parameter. If I don't know the real default value, I have to write:

if some_condition:
   some_func(param)
else:
   some_func()

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Fri Nov 18 03:06:33 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 18 Nov 2011 02:06:33 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321581992.46.0.111064082765.issue13386@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Eric,

Spot on :-) 
This is *exactly* the reason that led me to open issue 12875, which eventually led to this one.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Fri Nov 18 05:29:32 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 18 Nov 2011 04:29:32 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321590572.06.0.541036897626.issue13386@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

>From Ezio's original post: '''
If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead. ... The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted.
'''

In the following, I give objections to this PO (position only) rule and suggest an alternative ND (no default) rule: use 'name=default' when there is a default and '[name]' when there is not'.

The issue of whether an argument is required or optional is orthogonal to whether it can be passed by both position and name, only by name, or only by position. All combinations are possible. Optional arguments may or may not have a definition-time (or even run-time) default value, regardless of how passed. (In Python, use of *args and **kwds allows args to be optional without default.)

In the CPython stdlib, I think position-only arguments only occur with some, but only some, C functions. One can emulate such C functions in Python by doing the equivalent of what is going on with such C functions. Use a collective *varargs in the definition while naming the required and optional components of varargs in the doc as if they were the actual parameters. But I think we agree that emulating a limitation of C in Python is a bad idea.

So by using [] to mean both 'argument is optional' and 'function only take parameters by position' (or at least 'this parameter can only be passed to this function by position'), we are simultaneously documenting an intended and permanent feature of the Python function and a possibly temporary and unwanted side-effect of the current CPython implementation of that function. I think a separate PO indication might be better.

1: The PO rule goes against the effort to separate the Python language from the CPython implementation. With it, the doc for a function does not apply to other implementations that do not have the PO limitation for that function.

2: The PO rule is incomplete. It only marks an arg as position-only if it is optional, but not if it is required. And even if marking one arg as PO means that other args of the function might be, so 'watch out', there is still no special marking for a function with only required PO args. 

A separate sentence like "For CPython, all args must be passed by position." would solve both of the above problems.

3: The PO rule does not account for the possibility that an argument can be passed by keyword, perhaps only by keyword, but have no default. This is possibly in Python with **kwds in the def and recognized optional names in the doc. With 'name=default' and '[name]' not allowed, how should such an argument be documented is a signature?

4: The PO rule omits useful information on defaults from the place of prominence - the signature header for the entry. Sometimes the information, needed by some users and all implementers, gets omitted altogether. For example, the doc string and manual entry give the signature for str.startwith as
  str.startswith(prefix[, start[, end]])
The unmentioned defaults are None, None.

In summary, the PO rule primarily indicates, but only for optional args, whether the arg can be passed by keyword or not. It secondarily indicates, but only if it can be passed by keyword, what its default is. But if fails if the arg can be passed by keyword but does not have a default. It also fails, in its primary role, for required args.

To me, this is all mixed up. Method of passing is not related to optionality. What is special about optional args, regardless of how passed, is the default value, if it has one. The ND rule is to give exactly this information. With an implementation-independent signature and a separate note on passing method, when needed, it solves all the problems listed above. For .startswith, I would like to see something like
   str.startswith(prefix, start=None, end=None) ...
   CPython: pass args by position only.

---
#13355 illustrates Eric's point with a twist.
"random.triangular(low, high, mode) 
Return a random floating point number N such that low <= N <= high and with the specified mode between those bounds. The low and high bounds default to zero and one. The mode argument defaults to the midpoint between the bounds, giving a symmetric distribution."

The *actual* default for mode is None. The function *usually* acts if the default were as described. Twist 1 is that it does not actually calculate the midpoint, as it is not actually needed. Twist 2 is that there is currently a bug (easily fixed) such that triangular does not work if low>=high and mode is not specified, whereas it does work if the true default None is passed ;-). So one needs to know the real default to avoid the bug.

Of course, as I said on the issue, all defaults should be given in the signature (by either PO or ND rule):
"random.triangular(low=0.0, high=1.0, mode=None) ..."

And yes, +1 to documenting visible document conventions both in the documenting howto *and* in the docs themselves.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Fri Nov 18 08:11:43 2011
From: report at bugs.python.org (Baptiste Carvello)
Date: Fri, 18 Nov 2011 07:11:43 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321590572.06.0.541036897626.issue13386@psf.upfronthosting.co.za>
Message-ID: <4EC60527.5080409@baptiste-carvello.net>


Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Le 18/11/2011 05:29, Terry J. Reedy a ?crit :
> 
> In the following, I give objections to this PO (position only) rule and suggest an alternative ND (no default) rule: use 'name=default' when there is a default and '[name]' when there is not'.
> 
> The issue of whether an argument is required or optional is orthogonal to whether it can be passed by both position and name, only by name, or only by position.

With this logic, you would need to use '[name=default]' when an argument
is optional *and* can be passed by name.

Sure, this notation is inherently redundant, but is has the advantage of
conveying both informations immediately to the user. It is also more
coherent with '[name]'.

But this is a big change from the current philosophy...

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Fri Nov 18 10:17:28 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 18 Nov 2011 09:17:28 +0000
Subject: [docs] [issue13386] Document documentation conventions for optional
	args
In-Reply-To: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
Message-ID: <1321607848.87.0.0232920222185.issue13386@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> From Ezio's original post: '''
> If a function has optional arguments but it doesn't accept keyword 
> arguments, the "func([arg1])" notation is used instead. ... The 
> notation "func([arg=default])" should never be used, and "func([arg])" 
> should be used only when keyword args are not accepted.
> '''
>
> In the following, I give objections to this PO (position only) rule and > suggest an alternative ND (no default) rule: use 'name=default' when
> there is a default and '[name]' when there is not'.

Maybe we should try to keep it simple and just document the signature of the function.
Everything that can not be described in the signature can be explained by words.

I tried to write down all the combinations of optional/non optional, with/without default, works/doesn't work with keywords to see how to represent them, but it started being a bit messy.  The "problematic" combinations (for example a function that accepts an optional arguments with no default but that doesn't work with keywords) seem quite rare, and for them we could just write down what's special about them.

There are two more cases that could be solved with a specific notation though:
1) optional arg, with default, doesn't work with keywords (e.g. range, startswith):
   func(arg1)
   func(arg1, arg2)
   *arg2* defaults to <default>.
2) optional arg, with no default, that works only with keywords:
   func(arg1, *, arg2)

The keyword-only *, and the multiple signatures "tricks" can also be used for other similar cases.

func(arg1, **kwargs) can be used for functions that accept kwargs without expecting any specific value; if the values are known and have defaults they could be included in the signature (even if the default is like foo = kwargs.get('foo', default)).

This should cover most of the cases, it only uses valid Python syntax and avoids potentially confusing [].

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________

From report at bugs.python.org  Fri Nov 18 10:52:13 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 09:52:13 +0000
Subject: [docs] =?utf-8?q?=5Bissue13424=5D_Add_examples_for_open=E2=80=99s?=
 =?utf-8?q?_new_opener_argument?=
Message-ID: <1321609933.89.0.531165464334.issue13424@psf.upfronthosting.co.za>


New submission from ?ric Araujo <merwok at netwok.org>:

The new opener argument to open and TextIOWrapper closed two bugs on this tracker: using O_CLOEXEC and replacing the unofficial 'c' mode (O_CREATE).  I think it?d be nice to have these as examples (maybe not in the docs of TextIOWrapper which are already huge, but for example in the os docs after the O_* constants).

----------
assignee: docs at python
components: Documentation
messages: 147840
nosy: docs at python, eric.araujo
priority: normal
severity: normal
status: open
title: Add examples for open?s new opener argument
versions: Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13424>
_______________________________________

From report at bugs.python.org  Fri Nov 18 10:55:29 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 09:55:29 +0000
Subject: [docs] [issue12760] Add create mode to open()
In-Reply-To: <1313502559.06.0.415498401391.issue12760@psf.upfronthosting.co.za>
Message-ID: <1321610129.16.0.414444179943.issue12760@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

See #13424 for a doc request about this.

----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12760>
_______________________________________

From report at bugs.python.org  Fri Nov 18 10:55:53 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 09:55:53 +0000
Subject: [docs] =?utf-8?q?=5Bissue13424=5D_Add_examples_for_open=E2=80=99s?=
 =?utf-8?q?_new_opener_argument?=
In-Reply-To: <1321609933.89.0.531165464334.issue13424@psf.upfronthosting.co.za>
Message-ID: <1321610153.05.0.11321467341.issue13424@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

s/TextIOWrapper/FileIO/

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13424>
_______________________________________

From report at bugs.python.org  Fri Nov 18 12:29:59 2011
From: report at bugs.python.org (Nebelhom)
Date: Fri, 18 Nov 2011 11:29:59 +0000
Subject: [docs] [issue13426] The Python Standard Library >> 11. Data
	Persistence
Message-ID: <1321615799.02.0.0403291741181.issue13426@psf.upfronthosting.co.za>


New submission from Nebelhom <nebelhom at googlemail.com>:

------------------------------
Python v3.3a0 documentation >> The Python Standard Library >> 11. Data
Persistence

Section 11.1 pickle module

#1
11.1.3. Module Interface

exception pickle.UnpicklingError

   Error raised when there a problem unpickling an object, such as a data corruption or a security violation.
   It inherits PickleError.

TYPO: Error raised when there IS a problem unpickling an object

------------------------------
#2
11.1.3. Module Interface

persistent_load(pid)

   Raise an UnpickingError by default.

TYPO: Should be "Unpick"l"ingError" as wrtten earlier in the section

--------------------------------
#3
11.1.4 What can be pickled and unpickled

Note that functions (built-in and user-defined) are pickled by >>fully
qualified<< name reference, not by value.
This means that only the function name is pickled, along with the name of module the function is defined in.

TYPO: along with the name of "THE" module the function is defined in.

--------------------------------
#4
11.1.5.1. Persistence of External Objects

In Windows XP SP3, example does not work out of the box as sqlite3 is not included when compiling python3.3a following the Getting Set Up directions in the Developer's Guide

Is this an issue?

Code works in Ubuntu 10.04 lucid.

When run from Terminal, it gives the following output:

Pickled records:
[MemoRecord(key=1, task='give food to fish'),
 MemoRecord(key=2, task='prepare group meeting'),
 MemoRecord(key=3, task='fight with a zebra')]
Unpickled records:
[MemoRecord(key=1, task='learn italian'),
 MemoRecord(key=2, task='prepare group meeting'),
 MemoRecord(key=3, task='fight with a zebra')]


 Should that not be given afterwards as a reference to the user, so that
(s)he knows, that the code is right?

--------------------------------
#5
11.1.6 Restricting Globals

Thus it is possible to either forbid completely globals

NOTE: should be "either completely forbid globals"

--------------------------------

----------
assignee: docs at python
components: Documentation
messages: 147851
nosy: Nebelhom, docs at python
priority: normal
severity: normal
status: open
title: The Python Standard Library >> 11. Data Persistence
versions: Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13426>
_______________________________________

From report at bugs.python.org  Fri Nov 18 12:53:06 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 18 Nov 2011 11:53:06 +0000
Subject: [docs] [issue13426] The Python Standard Library >> 11. Data
	Persistence
In-Reply-To: <1321615799.02.0.0403291741181.issue13426@psf.upfronthosting.co.za>
Message-ID: <E1RRN01-00015T-H1@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset ce34e9223450 by Ezio Melotti in branch '2.7':
#13426: fix typo in pickle doc.
http://hg.python.org/cpython/rev/ce34e9223450

New changeset 1f31061afdaf by Ezio Melotti in branch '3.2':
#13426: fix typos in pickle doc.
http://hg.python.org/cpython/rev/1f31061afdaf

New changeset 7992f3247447 by Ezio Melotti in branch 'default':
#13426: merge with 3.2.
http://hg.python.org/cpython/rev/7992f3247447

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13426>
_______________________________________

From report at bugs.python.org  Fri Nov 18 12:58:54 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 18 Nov 2011 11:58:54 +0000
Subject: [docs] [issue13426] The Python Standard Library >> 11. Data
	Persistence
In-Reply-To: <1321615799.02.0.0403291741181.issue13426@psf.upfronthosting.co.za>
Message-ID: <1321617534.73.0.127194901162.issue13426@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

This is fixed now, thanks for the report!
Regarding #4, sqlite3 is included in the official installer provided for Windows, so that shouldn't be a problem.
Regarding the output, I don't think is necessary to add it.
The example is fairly complex, so people that need it will probably have to try it and experiment a bit anyway, rather than just reading 100 lines of code and trying to understand how they work without actually trying it.

----------
assignee: docs at python -> ezio.melotti
nosy: +ezio.melotti
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed
versions: +Python 2.7, Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13426>
_______________________________________

From report at bugs.python.org  Fri Nov 18 13:23:59 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 12:23:59 +0000
Subject: [docs] [issue13426] Typos in pickle docs
In-Reply-To: <1321615799.02.0.0403291741181.issue13426@psf.upfronthosting.co.za>
Message-ID: <1321619039.88.0.183007102821.issue13426@psf.upfronthosting.co.za>


Changes by ?ric Araujo <merwok at netwok.org>:


----------
nosy: +eric.araujo
title: The Python Standard Library >> 11. Data Persistence -> Typos in pickle docs

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13426>
_______________________________________

From report at bugs.python.org  Fri Nov 18 13:25:02 2011
From: report at bugs.python.org (Nebelhom)
Date: Fri, 18 Nov 2011 12:25:02 +0000
Subject: [docs] [issue13426] The Python Standard Library >> 11. Data
	Persistence
In-Reply-To: <1321617534.73.0.127194901162.issue13426@psf.upfronthosting.co.za>
Message-ID: <CAHw0e=vWryZei6ru4=_y-3=fOd8AsgVFWfhFhzFQhFxQYs_HHg@mail.gmail.com>


Nebelhom <nebelhom at googlemail.com> added the comment:

Hi Ezio,

"Regarding the output, I don't think is necessary to add it."

I left it in because of a discussion in core-mentorship, where they
mentioned that it would be beneficial to have it in. I pasted the exchange
below if you are interested.

Thanks for looking at it,

Johannes

-------------------------------------
Pasted content:

Message: 2
Date: Fri, 18 Nov 2011 04:15:03 +0200
From: Eli Bendersky <eliben at gmail.com>
To: Python Core Development Mentorship <core-mentorship at python.org>
Subject: Re: [Core-mentorship] What classes as an issue in
       documentation?
Message-ID:
       <CAF-Rda-U5Jya999K=FW6Xe8VGrSpj1pHq0EtcMZ277x2JDtv0Q at mail.gmail.com>
Content-Type: text/plain; charset=windows-1252

trying
> to gauge what is relevant and what is just a little overly picky.
>
> I applied the standard, I use when proofreading scientific texts of fellow
> researchers (which raises the bar into infinity as you may always
encounter
> someone who is willing to split hairs over a comma in the wrong position
> just to be right). I would be grateful, if you could just quickly scan
over
> the list and say in each case (I numbered them) if it is relevant or not.
>
> thanks a bundle.
>
> Johannes
>
> P.S. Also, one issue for all issues in one section (like Nick Coghlan
> suggested)
>
> ------------------------------
> Python v3.3a0 documentation ? The Python Standard Library ? 11. Data
> Persistence ?
>
> Section 11.1 pickle module
>
> #1
> 11.1.3. Module Interface
>
> exception pickle.UnpicklingError
>
> ??? Error raised when there a problem unpickling an object, such as a data
> corruption or a security violation.
> ??? It inherits PickleError.
>
> TYPO: Error raised when there IS a problem unpickling an object
>
> ------------------------------
> #2
> 11.1.3. Module Interface
>
> persistent_load(pid)
>
> ??? Raise an UnpickingError by default.
>
> TYPO: Should be "Unpick"l"ingError" as wrtten earlier in the section
>
> ------------------------------
--
> #3
> 11.1.4 What can be pickled and unpickled
>
> Note that functions (built-in and user-defined) are pickled by ?fully
> qualified? name reference, not by value.
> This means that only the function name is pickled, along with the name of
> module the function is defined in.
>
> TYPO: along with the name of "THE" module the function is defined in.
>
> --------------------------------
> #4
> 11.1.5.1. Persistence of External Objects
>
> In Windows XP SP3, example does not work out of the box as sqlite3 is not
> included when compiling python3.3a
> following the Getting Set Up directions in the Developer's Guide
>
> Is this an issue?
>
> Code works in Ubuntu 10.04 lucid.
>
> When run from Terminal, it gives the following output:
>
> Pickled records:
> [MemoRecord(key=1, task='give food to fish'),
> ?MemoRecord(key=2, task='prepare group meeting'),
> ?MemoRecord(key=3, task='fight with a zebra')]
> Unpickled records:
> [MemoRecord(key=1, task='learn italian'),
> ?MemoRecord(key=2, task='prepare group meeting'),
> ?MemoRecord(key=3, task='fight with a zebra')]
>
>
> ?Should that not be given afterwards as a reference to the user, so that
> (s)he knows, that the code is right?
>
> --------------------------------
> #5
> 11.1.6 Restricting Globals
>
> Thus it is possible to either forbid completely globals
>
> NOTE: should be "either completely forbid globals"
>

Johannes,

These look perfectly valid to me. Even the smallest typos mentioned
here are worth fixing. The next step is opening an issue in the
tracker (http://bugs.python.org/) and submitting a patch.

Eli

------------------------------

Message: 3
Date: Fri, 18 Nov 2011 13:17:11 +1000
From: Nick Coghlan <ncoghlan at gmail.com>
To: Python Core Development Mentorship <core-mentorship at python.org>
Subject: Re: [Core-mentorship] What classes as an issue in
       documentation?
Message-ID:
       <CADiSq7cH_inw_3MUM8huro4GFT=uT7XOF04DE-cSb+BnjKRumg at mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1

On Fri, Nov 18, 2011 at 12:15 PM, Eli Bendersky <eliben at gmail.com> wrote:
> Johannes,
>
> These look perfectly valid to me. Even the smallest typos mentioned
> here are worth fixing. The next step is opening an issue in the
> tracker (http://bugs.python.org/) and submitting a patch.

Although I'll note that even if you're not yet ready to make the patch
yourself, a detailed report like this one makes it very easy for
someone *else* to produce a patch, so the tracker issue is the most
important next step.

Lots of things have to happen for a change to get into the source
tree, and the reason we have tools like the tracker around is so that
the work can be coordinated amongst multiple people.

Even as core devs, we'll still often post changes we design, code and
commit ourselves as tracker issues for a while, just so we have a
venue to coordinate reviews and gather feedback.

Cheers,
Nick.

----------
title: Typos in pickle docs -> The Python Standard Library >> 11. Data Persistence

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13426>
_______________________________________

From report at bugs.python.org  Fri Nov 18 13:31:13 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 12:31:13 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321619472.98.0.185795513224.issue10772@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Looks good to me.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Fri Nov 18 13:35:10 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 18 Nov 2011 12:35:10 +0000
Subject: [docs] [issue10772] Several actions for argparse arguments missing
	from docs
In-Reply-To: <1293327184.11.0.454888760887.issue10772@psf.upfronthosting.co.za>
Message-ID: <1321619710.59.0.575158698709.issue10772@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
stage: patch review -> commit review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10772>
_______________________________________

From report at bugs.python.org  Fri Nov 18 15:11:23 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 14:11:23 +0000
Subject: [docs] [issue13426] Typos in pickle docs
In-Reply-To: <1321615799.02.0.0403291741181.issue13426@psf.upfronthosting.co.za>
Message-ID: <1321625483.49.0.576253354666.issue13426@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

>> Regarding the output, I don't think is necessary to add it.
> I left it in because of a discussion in core-mentorship, where they
> mentioned that it would be beneficial to have it in.

Well, people can have diverging opinions.  Terry?s was that ?having the output, perhaps in a separate box, will also help to analyze the code to understand it?, but Ezio judged that ?the example is fairly complex, so people that need it will probably have to try it and experiment a bit anyway?.  I think I agree with Ezio.

----------
nosy: +terry.reedy
title: The Python Standard Library >> 11. Data Persistence -> Typos in pickle docs

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13426>
_______________________________________

From report at bugs.python.org  Fri Nov 18 15:19:08 2011
From: report at bugs.python.org (Ross Lagerwall)
Date: Fri, 18 Nov 2011 14:19:08 +0000
Subject: [docs] =?utf-8?q?=5Bissue13424=5D_Add_examples_for_open=E2=80=99s?=
 =?utf-8?q?_new_opener_argument?=
In-Reply-To: <1321609933.89.0.531165464334.issue13424@psf.upfronthosting.co.za>
Message-ID: <1321625948.52.0.964759266282.issue13424@psf.upfronthosting.co.za>


Changes by Ross Lagerwall <rosslagerwall at gmail.com>:


----------
nosy: +rosslagerwall

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13424>
_______________________________________

From report at bugs.python.org  Fri Nov 18 15:19:20 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 14:19:20 +0000
Subject: [docs] [issue12779] Update packaging documentation
In-Reply-To: <1313686169.0.0.406072932055.issue12779@psf.upfronthosting.co.za>
Message-ID: <1321625960.72.0.185563787327.issue12779@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

I worked on this a bit more and the current boring diff has more than 1000 deleted lines and more than 1000 added lines.  After thinking about it, maybe I should not make a mega-patch with markup/boring changes first but rather fix markup as part of more consistent wording and reorganization changes.  The series of changesets could look like this:

- Update and improve Doc/install (the end-user guide, a few files)
- Update and improve the commands reference in Doc/packaging
- Improve introduction material in Doc/packaging
- Fix X in Doc/library/packaging.foo
- Add missing doc for packaging.spam in Doc/library
- etc.

I think that will make more sense to review.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12779>
_______________________________________

From report at bugs.python.org  Fri Nov 18 15:32:51 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 14:32:51 +0000
Subject: [docs] [issue4395] Document auto __ne__ generation;
	provide a use case for non-trivial __ne__
In-Reply-To: <1227464493.77.0.130820783094.issue4395@psf.upfronthosting.co.za>
Message-ID: <1321626771.02.0.478199242564.issue4395@psf.upfronthosting.co.za>


Changes by ?ric Araujo <merwok at netwok.org>:


----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4395>
_______________________________________

From report at bugs.python.org  Fri Nov 18 15:53:48 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 14:53:48 +0000
Subject: [docs] [issue13292] missing versionadded for bytearray
In-Reply-To: <1319975533.88.0.431386848219.issue13292@psf.upfronthosting.co.za>
Message-ID: <1321628028.93.0.308870551699.issue13292@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks for cleaning up the reports.  I?m not a numbers person :)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13292>
_______________________________________

From report at bugs.python.org  Fri Nov 18 18:01:23 2011
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 18 Nov 2011 17:01:23 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <E1RRRoL-0005vX-KC@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset fd9d7a8e45bc by Ezio Melotti in branch '2.7':
#13387: add note about checking the exact type in assertIsInstance doc.
http://hg.python.org/cpython/rev/fd9d7a8e45bc

New changeset 583aff635ce1 by Ezio Melotti in branch '3.2':
#13387: add note about checking the exact type in assertIsInstance doc.
http://hg.python.org/cpython/rev/583aff635ce1

New changeset 196d485ed26d by Ezio Melotti in branch 'default':
#13387: merge with 3.2.
http://hg.python.org/cpython/rev/196d485ed26d

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Fri Nov 18 18:01:52 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 18 Nov 2011 17:01:52 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321635712.51.0.887553979946.issue13387@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

Fixed.

----------
assignee: docs at python -> ezio.melotti
resolution:  -> fixed
stage: needs patch -> committed/rejected
status: open -> closed
versions: +Python 2.7, Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Fri Nov 18 18:06:25 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 18 Nov 2011 17:06:25 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321635985.63.0.832356331352.issue13387@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

+ To check for a specific type (without including superclasses) use
+ :func:`assertIs(type(obj), cls) <assertIs>`.

Don?t you mean ?without accepting subclasses?, not superclasses?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Fri Nov 18 18:15:33 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 18 Nov 2011 17:15:33 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321636533.62.0.452991276521.issue13387@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> + To check for a specific type (without including superclasses) use
> + :func:`assertIs(type(obj), cls) <assertIs>`.
>
> Don?t you mean ?without accepting subclasses?, not superclasses?

I mean:
>>> class MyInt(int): pass     # my specific type
...
>>> isinstance(MyInt(5), int)  # int superclass included
True
>>> type(MyInt(5)) is int      # int superclass not included
False
>>> type(MyInt(5)) is MyInt    # check for specific type
True

Do you think I should rephrase it (or maybe just remove the (...))?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Sat Nov 19 11:50:21 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Sat, 19 Nov 2011 10:50:21 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1321699821.57.0.609755770625.issue13402@psf.upfronthosting.co.za>


Changes by Petri Lehtinen <petri at digip.org>:


----------
nosy: +petri.lehtinen

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From allan at tactileint.com  Wed Nov 16 10:04:54 2011
From: allan at tactileint.com (Allan Bonadio)
Date: Wed, 16 Nov 2011 01:04:54 -0800
Subject: [docs] 3.2.2 epub docs broken
Message-ID: <D2CF50D0-FF9E-4EA3-80C8-EE26B4026A32@tactileint.com>

the epub versions of the 3.2.2 docs are really zip files.  As  
downloaded from this dir:
http://docs.python.org/py3k/download.html

iTunes wouldn't accept them for my iPad.  And, after de-bunzip2 or  
unzip, you get a dir with Python.epub in it.  But that file seems to  
be a zip archive, with HTML files inside.  The filename list is very  
similar to the html version of the docs (which I also downloaded,  
which works well for my laptop).

(now maybe epub is really a zip file with html, not sure, but unzip  
worked on both.)

Thanks for all the work, I like the docs!


From avi.kaps at gmail.com  Fri Nov 18 12:08:20 2011
From: avi.kaps at gmail.com (Avi Kapoor)
Date: Fri, 18 Nov 2011 16:38:20 +0530
Subject: [docs] Bug reporting in documentation
Message-ID: <CAGW0F_kZ1qzqmDLf74WPe5W4uO93b8tucf_swe9x9hqEqadsCw@mail.gmail.com>

Sir,

I''ve started learning python 2.4 as its supports the other tools related
to my project.
Lately i found a bug on *Section 4.4 "break and continue Statements "*
*
*
*>>> for n in range(2, 10): *
*... for x in range(2, n): *
*... if n % x == 0: *
*... print n, 'equals', x, '*', n/x *
*... break *
*... else: *
*... # loop fell through without finding a factor *
*... print n, 'is a prime number'*
* *
The actual output when you perform on the shell is like this
*
*
*
3 is a prime number
4 equals 2 * 2
5 is a prime number
5 is a prime number
5 is a prime number
6 equals 2 * 3
7 is a prime number
7 is a prime number
7 is a prime number
7 is a prime number
7 is a prime number
8 equals 2 * 4
9 is a prime number
9 equals 3 * 3
*


it doesn't include 2 as its prime number !!

Suggestions are : Working on it currently...will intimate you soon
-- 
*With Regards
Avi Kapoor *
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111118/43b95894/attachment.html>

From peter at pelican.ucsd.edu  Fri Nov 18 05:28:12 2011
From: peter at pelican.ucsd.edu (Peter Rowat)
Date: Thu, 17 Nov 2011 20:28:12 -0800 (PST)
Subject: [docs] Bug in import/documentation ??
Message-ID: <201111180428.pAI4SCQV025137@pelican.ucsd.edu>

My problem is probably not a bug, only my stupidity:

After

"import numpy as np"

I can use np.array successfully, interactively.

Then I import my own script that calls "np.array" in a function definition.
When I call that function I get error message:

***NameError: global name 'np' is not defined***

I do not understand what I have done wrong:
*****
I can use "np.array" interactively, but not when it is used in a 
function definition that is imported !!
*****
Obviously I am missing something.
Can you help?
Thanks,  Peter Rowat

=====================================
=====================================
In more detail:
=====================================

Here is some code:

# these are in pythonstartup:
import numpy as np
import scipy
from scipy import spatial
#

# Then I type in a function definition:

>>> def mmapfn(su_scores):
...     su, scores = su_scores
...     dists = np.array( [spatial.distance.euclidean(scores[k], ec_center) for k in range(scores.shape[0]) ])
...     return [ su,dists]
... 

# I can use this function and everything works OK. e.g. as in
>>> map(mmapfn, some array or list).
===========
# BUT    (beginning to build up a script)
# I put this very same function defined (with a different name) in a file abc.py:

def mapfn(su_scores):
    su, scores = su_scores
    dists = np.array( [spatial.distance.euclidean(scores[k], ec_center) for k in range(scores.shape[0]) ])
    return [ su,dists]

# and I import it:
>>> import abc

# or even
>>> from abc import mapfn

# when I try to call it as before, e.g.

>>> map(mapfn, some array or list) 

# I get an error message: 

>>> mapfn(ee_pd[4])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "more.py", line 3, in mapfn
    dists = np.array( [spatial.distance.euclidean(scores[k], ec_center) for k in range(scores.shape[0]) ])
NameError: global name 'np' is not defined
======





From sandro.tosi at gmail.com  Sat Nov 19 12:42:13 2011
From: sandro.tosi at gmail.com (Sandro Tosi)
Date: Sat, 19 Nov 2011 12:42:13 +0100
Subject: [docs] Bug reporting in documentation
In-Reply-To: <CAGW0F_kZ1qzqmDLf74WPe5W4uO93b8tucf_swe9x9hqEqadsCw@mail.gmail.com>
References: <CAGW0F_kZ1qzqmDLf74WPe5W4uO93b8tucf_swe9x9hqEqadsCw@mail.gmail.com>
Message-ID: <CAPdtAj0Uw5Qh09kOU31UmSZSnD0q8q_ZKSvWmfAXuZo3y=BsAw@mail.gmail.com>

Hello Avi,

On Fri, Nov 18, 2011 at 12:08, Avi Kapoor <avi.kaps at gmail.com> wrote:
> Sir,
> I''ve started learning python 2.4 as its supports the other tools related to
> my project.

2.4 is a rather old version of python. If you're completely new to the
Python language, I strongly suggest to start with Python 3 (3.2 is the
latest release) since it's the future of the language and where we're
moving to. If instead you're requirements forces you on the 2.x
series, then the suggestion goes to use Python 2.7 (which is the
latest and last version of Python 2.x).

> Lately i found a bug on?Section?4.4 "break and continue Statements "

As said, 2.4 is and old version of python and we don't change its
documentation, but since what you reported is a common
mis-understanding of the code example, we did actually add a note to
clarify the code snippet:
http://docs.python.org/tutorial/controlflow.html#break-and-continue-statements-and-else-clauses-on-loops

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

From sandro.tosi at gmail.com  Sat Nov 19 12:54:31 2011
From: sandro.tosi at gmail.com (Sandro Tosi)
Date: Sat, 19 Nov 2011 12:54:31 +0100
Subject: [docs] 3.2.2 epub docs broken
In-Reply-To: <D2CF50D0-FF9E-4EA3-80C8-EE26B4026A32@tactileint.com>
References: <D2CF50D0-FF9E-4EA3-80C8-EE26B4026A32@tactileint.com>
Message-ID: <CAPdtAj26+-D9bCK1BtTqmsSBNQwF-N5T50J0EejNk5pTDuuo+A@mail.gmail.com>

Hello Allan,

On Wed, Nov 16, 2011 at 10:04, Allan Bonadio <allan at tactileint.com> wrote:
> the epub versions of the 3.2.2 docs are really zip files. ?As downloaded
> from this dir:
> http://docs.python.org/py3k/download.html
>
> iTunes wouldn't accept them for my iPad. ?And, after de-bunzip2 or unzip,
> you get a dir with Python.epub in it. ?But that file seems to be a zip
> archive, with HTML files inside. ?The filename list is very similar to the
> html version of the docs (which I also downloaded, which works well for my
> laptop).
>
> (now maybe epub is really a zip file with html, not sure, but unzip worked
> on both.)

Indeed, the EPUB file is actual a zip archive on XHTML pages placed in
specific directories, you can look at [1] and the references from that
page.

[1] http://en.wikipedia.org/wiki/EPUB#Version_3.0_.28current_version.29

I don't know about EPUB support on Apple devices, but on the wikipedia
pages there are mentioned some application able to read EPUB files on
iOS systems.

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

From report at bugs.python.org  Sat Nov 19 14:01:32 2011
From: report at bugs.python.org (Christian Iversen)
Date: Sat, 19 Nov 2011 13:01:32 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
Message-ID: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>


New submission from Christian Iversen <ci at sikkerhed.org>:

The documentation for string format options state that both %f, %g and %e default to 6 digits after the decimal point. In fact, %g always seems to use 5 digits by default:

>>> "%g" % 2.1234567
'2.12346'
>>> "%f" % 2.1234567
'2.123457'
>>> "%e" % 2.1234567
'2.123457e+00'

But something much more insidious is wrong, because even when explicitly told how many digits to have, %g is one off:

>>> "%.6g" % 2.1234567
'2.12346'
>>> "%.6f" % 2.1234567
'2.123457'
>>> "%.6e" % 2.1234567
'2.123457e+00'

This can't be right?

----------
assignee: docs at python
components: Documentation
messages: 147940
nosy: Christian.Iversen, docs at python
priority: normal
severity: normal
status: open
title: String format documentation contains error regarding %g
type: behavior
versions: Python 2.6, Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 19 14:26:24 2011
From: report at bugs.python.org (Mark Dickinson)
Date: Sat, 19 Nov 2011 13:26:24 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321709184.04.0.466428984851.issue13433@psf.upfronthosting.co.za>


Mark Dickinson <dickinsm at gmail.com> added the comment:

Yep, there's an oddity here that's directly inherited from C's sprintf family of functions, namely that in %e-style formatting you give the number of digits after the point (= one less than the total number of significant digits), and in %g-style formatting you give the total number of significant digits instead.

Can you give a pointer, or link, to the documentation section you were looking at?

The description at:

http://docs.python.org/library/stdtypes.html#string-formatting-operations

looks fine to me.  Note 3, which relates to the '%e' and '%f'-style formatting, talks about number of places after the point.  Note 4, which relates to '%g' formatting, talks about the total number of significant digits.

----------
nosy: +mark.dickinson

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 19 14:31:17 2011
From: report at bugs.python.org (Christian Iversen)
Date: Sat, 19 Nov 2011 13:31:17 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321709477.1.0.888531920721.issue13433@psf.upfronthosting.co.za>


Christian Iversen <ci at sikkerhed.org> added the comment:

That was exactly the page I was looking at, and after some discussion on #python, I can see how they differ.

Perhaps this could be clarified in the documentation? It's very easy to miss as it is now. Maybe a note describing that %g is different from the others in this regard?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 19 14:38:38 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 19 Nov 2011 13:38:38 +0000
Subject: [docs] [issue11908] Weird `slice.stop or sys.maxint`
In-Reply-To: <1303493846.17.0.214651551769.issue11908@psf.upfronthosting.co.za>
Message-ID: <1321709918.83.0.927706068958.issue11908@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
keywords: +easy
nosy: +ezio.melotti
stage:  -> needs patch
versions:  -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11908>
_______________________________________

From report at bugs.python.org  Sat Nov 19 14:56:41 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 19 Nov 2011 13:56:41 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1321711001.43.0.759141700543.issue10318@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

?ric, what's the status of this?

----------
nosy: +ezio.melotti

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Sat Nov 19 15:05:23 2011
From: report at bugs.python.org (Mark Dickinson)
Date: Sat, 19 Nov 2011 14:05:23 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321711523.56.0.58943237409.issue13433@psf.upfronthosting.co.za>


Mark Dickinson <dickinsm at gmail.com> added the comment:

> Maybe a note describing that %g is different from the others in this regard?

-1 from me;  I don't really see that that would improve the documentation.  Maybe that's just me, but I expect reference documentation to be clean, and uncluttered with too many warnings.  All the necessary information is already there, and adding extra notes like this just increases the total number of words to be read without adding new information.

In a tutorial, that would be different ... :-)

Leaving this open---others may have different takes on this.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 19 15:05:36 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 19 Nov 2011 14:05:36 +0000
Subject: [docs] [issue5066] IDLE documentation for Unix obsolete/incorrect
In-Reply-To: <1232942217.99.0.191249551049.issue5066@psf.upfronthosting.co.za>
Message-ID: <1321711536.12.0.436915744775.issue5066@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +ezio.melotti
stage: needs patch -> patch review
versions: +Python 3.3 -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue5066>
_______________________________________

From report at bugs.python.org  Sat Nov 19 15:08:36 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 19 Nov 2011 14:08:36 +0000
Subject: [docs] [issue11842] slice.indices with negative step and default
	stop
In-Reply-To: <1302727853.06.0.703796407001.issue11842@psf.upfronthosting.co.za>
Message-ID: <1321711716.85.0.367283736293.issue11842@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
keywords: +easy
stage:  -> needs patch
versions: +Python 2.7, Python 3.3 -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11842>
_______________________________________

From report at bugs.python.org  Sat Nov 19 15:09:03 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 19 Nov 2011 14:09:03 +0000
Subject: [docs] =?utf-8?q?=5Bissue13424=5D_Add_examples_for_open=E2=80=99s?=
 =?utf-8?q?_new_opener_argument?=
In-Reply-To: <1321609933.89.0.531165464334.issue13424@psf.upfronthosting.co.za>
Message-ID: <1321711743.18.0.429322823606.issue13424@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
keywords: +easy
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13424>
_______________________________________

From report at bugs.python.org  Sat Nov 19 17:27:51 2011
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 19 Nov 2011 16:27:51 +0000
Subject: [docs] [issue12245] Document the meaning of FLT_ROUNDS constants
	for	sys.float_info
In-Reply-To: <1307044030.93.0.176037757521.issue12245@psf.upfronthosting.co.za>
Message-ID: <E1RRnlR-0005nv-Io@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset de1ecda2afa2 by Mark Dickinson in branch '2.7':
Issue #12245: Document sys.float_info.rounds better.
http://hg.python.org/cpython/rev/de1ecda2afa2

New changeset 795c184b0282 by Mark Dickinson in branch '3.2':
Issue #12245: Document sys.float_info.rounds better.
http://hg.python.org/cpython/rev/795c184b0282

New changeset 5e45dfc421e4 by Mark Dickinson in branch 'default':
Issue #12245 merge.
http://hg.python.org/cpython/rev/5e45dfc421e4

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12245>
_______________________________________

From report at bugs.python.org  Sat Nov 19 17:28:16 2011
From: report at bugs.python.org (Mark Dickinson)
Date: Sat, 19 Nov 2011 16:28:16 +0000
Subject: [docs] [issue12245] Document the meaning of FLT_ROUNDS constants
	for	sys.float_info
In-Reply-To: <1307044030.93.0.176037757521.issue12245@psf.upfronthosting.co.za>
Message-ID: <1321720096.66.0.213714992758.issue12245@psf.upfronthosting.co.za>


Changes by Mark Dickinson <dickinsm at gmail.com>:


----------
resolution:  -> fixed
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12245>
_______________________________________

From report at bugs.python.org  Sat Nov 19 18:42:23 2011
From: report at bugs.python.org (Robert Lehmann)
Date: Sat, 19 Nov 2011 17:42:23 +0000
Subject: [docs] [issue13435] Copybutton does not hide tracebacks
Message-ID: <1321724543.66.0.854276029391.issue13435@psf.upfronthosting.co.za>


New submission from Robert Lehmann <lehmannro at gmail.com>:

The recently added copybutton.js (r18bbfed9aafa) does not work with the 2.7 docs since they are deployed with JQuery 1.2 (which is shipped with Sphinx 0.6).

Copybutton is an unobtrusive Javascript feature which adds a little button to all doctests that removes the interactive prompts in order to copy the code as-is into Python scripts.  I think that feature could well be ported to Sphinx itself.

In line 44 and 51 of Doc/tools/sphinxext/static/copybutton.js the code uses jQuery.nextUntil(), which is new in JQuery 1.4.  That results in tracebacks being only partially hidden.  Reproduce the error at http://docs.python.org/tutorial/errors.html#exceptions for example.

The Python 3.2+ documentation is not affected as it is built with Sphinx 1.0, which ships with JQuery 1.4.  JQuery Untils are available as a separate plugin (http://benalman.com/projects/jquery-untils-plugin/).

----------
assignee: docs at python
components: Documentation
messages: 147962
nosy: docs at python, ezio.melotti, lehmannro
priority: normal
severity: normal
status: open
title: Copybutton does not hide tracebacks
type: behavior
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13435>
_______________________________________

From report at bugs.python.org  Sat Nov 19 19:24:51 2011
From: report at bugs.python.org (Eric V. Smith)
Date: Sat, 19 Nov 2011 18:24:51 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321727091.12.0.0389448299002.issue13433@psf.upfronthosting.co.za>


Changes by Eric V. Smith <eric at trueblade.com>:


----------
nosy: +eric.smith

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From sandro.tosi at gmail.com  Sat Nov 19 19:27:18 2011
From: sandro.tosi at gmail.com (Sandro Tosi)
Date: Sat, 19 Nov 2011 19:27:18 +0100
Subject: [docs] how about adding anchor tags to the functions
In-Reply-To: <CAD-RA2RWFXciafCa_xQftM_669K_eHY_TEUKWL_hJkPXZupnoA@mail.gmail.com>
References: <CAD-RA2RWFXciafCa_xQftM_669K_eHY_TEUKWL_hJkPXZupnoA@mail.gmail.com>
Message-ID: <CAPdtAj0vr75qcD78LO8Y8=0LfptXAjgwWHxt0+y8tMKWKow37A@mail.gmail.com>

Hello James,
thanks for your feedback.

On Sun, Nov 13, 2011 at 19:20, James Lin <guanfenglin at gmail.com> wrote:
> Hi there,
>
> First of all, hands down to the effort for the detailed Python
> documentation.
>
> I was a long time PHP programmer and enjoyed the PHP documentation style,
> single page of specific function documentation and samples, then community
> contribution.

this is just my opinion, but the the times I needed to look up how to
use a php function, I tended to find those comments quite confusing,
and actually hiding the real information I was looking for.

Community contributions are important and for sure valuable (that's
what we're here for after all :)) , but I think some kind of
"filtering" to provide high quality documentation is important too.

> While I agree Python is different to PHP, but I think the
> Python ducmentation still has room to improve and the community should still
> be able to "borrow" some goodies from the PHP documentation style.
>
> Perhaps I may not be the first one who suggested this, but I do find having
> the anchor tags on the function names(so google can index and provide
> directly to the specific section) in the doucmentation really reduce some
> frustration on reading the python documentation.
>
> eg. if I am searching "python urllib urlretrieve" and google results page
> shows the relevant information but with this link here
> http://docs.python.org/library/urllib.html, then I am required to do another
> page search to locate the information i want, it would be great that if the
> site provides links like
> http://docs.python.org/library/urllib.html#urllib.urlretrieve

I don't think I understand: this link is actually provided, or are you
asking to split every function/class/method in a separate page?

>, so the
> browser automatically scrolls to the right section? Also, it would be
> awesome to have some code examples of each function, if that's too much

The python documentation provides some examples, but most often the
function usage is straightforward, and doesn't require any additional
examples, that's at least my experience.

> effort needed, how about having a collapsed community section(similar to
> PHP) under each function?

That's more difficult than what may seem: the documentation provided
at docs.python.org is generated from files maintained along the python
source code. They are reviewed and expanded also from users
suggestions, but I don't think allowing free-editing from anyone would
actual provide a better doc that the one we have.

Thanks for your interest in making Python doc better,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

From report at bugs.python.org  Sat Nov 19 19:35:09 2011
From: report at bugs.python.org (Mark Dickinson)
Date: Sat, 19 Nov 2011 18:35:09 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321727709.25.0.0902620211177.issue13433@psf.upfronthosting.co.za>


Changes by Mark Dickinson <dickinsm at gmail.com>:


----------
versions: +Python 3.2, Python 3.3 -Python 2.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 19 19:48:41 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 19 Nov 2011 18:48:41 +0000
Subject: [docs] [issue13435] Copybutton does not hide tracebacks
In-Reply-To: <1321724543.66.0.854276029391.issue13435@psf.upfronthosting.co.za>
Message-ID: <1321728521.62.0.288956503068.issue13435@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
assignee: docs at python -> ezio.melotti
nosy: +georg.brandl
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13435>
_______________________________________

From report at bugs.python.org  Sat Nov 19 20:07:46 2011
From: report at bugs.python.org (Nebelhom)
Date: Sat, 19 Nov 2011 19:07:46 +0000
Subject: [docs] [issue12779] Update packaging documentation
In-Reply-To: <1313686169.0.0.406072932055.issue12779@psf.upfronthosting.co.za>
Message-ID: <1321729666.93.0.996396730289.issue12779@psf.upfronthosting.co.za>


Changes by Nebelhom <nebelhom at googlemail.com>:


----------
nosy: +Nebelhom

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12779>
_______________________________________

From report at bugs.python.org  Sun Nov 20 01:04:39 2011
From: report at bugs.python.org (=?utf-8?q?Janosch_Gr=C3=A4f?=)
Date: Sun, 20 Nov 2011 00:04:39 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
Message-ID: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>


New submission from Janosch Gr?f <janosch.graef at gmx.net>:

The documentation for ast says that arguments that are marked with a '?' in the abstract grammar are optional and can therefore be None.
When I try to compile a Module node which contains an ImportFrom node with attribute level=None compile() throws an exception:

Module(body=[ImportFrom(module='time', names=[alias(name='sleep', asname=None), alias(name='time', asname=None)], level=None, lineno=0, col_offset=0)])

Traceback (most recent call last):
  File "g0.py", line 423, in <module>
    p.main()
  File "g0.py", line 65, in main
    self.reproduce("g1.pyc")
  File "g0.py", line 85, in reproduce
    co = self.generate_bytecode(st, genome)
  File "g0.py", line 243, in generate_bytecode
    co = compile(st, id, "exec")
ValueError: invalid integer value: ????????

So, I tried to set level=0:
Module(body=[ImportFrom(module='time', names=[alias(name='sleep', asname=None), alias(name='time', asname=None)], level=0, lineno=0, col_offset=0)])

and everything worked fine.

BTW: The unprintable bytes in the error message are:
ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd

----------
assignee: docs at python
components: Documentation, Interpreter Core
messages: 147972
nosy: Janosch.Gr?f, docs at python
priority: normal
severity: normal
status: open
title: compile() doesn't work on ImportFrom with level=None
type: behavior
versions: Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Sun Nov 20 01:29:31 2011
From: report at bugs.python.org (Julian Berman)
Date: Sun, 20 Nov 2011 00:29:31 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
Message-ID: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>


New submission from Julian Berman <Julian+Python.org at GrayVines.com>:

The documentation occasionally contains a link to the source code for a module in the stdlib. See for instance http://docs.python.org/library/urlparse.html and http://docs.python.org/library/collections.html , or many others.

With a quick perusal, I couldn't immediately guess as to which ones managed to have one and which ones don't, but it'd be convenient to have a link in as many places as possible, which is certainly more than we have now. (See e.g. http://docs.python.org/library/json.html and http://docs.python.org/library/itertools.html and many others for examples of pages that lack a link).

Perhaps putting it in a more conspicuous but still consistent location would be reasonable (the sidebar?).

----------
assignee: docs at python
components: Documentation
messages: 147973
nosy: Julian, docs at python
priority: normal
severity: normal
status: open
title: Provide links to the source code for every module in the documentation
type: feature request
versions: Python 2.7, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Sun Nov 20 11:02:05 2011
From: report at bugs.python.org (=?utf-8?q?Martin_v=2E_L=C3=B6wis?=)
Date: Sun, 20 Nov 2011 10:02:05 +0000
Subject: [docs] [issue13416] Python Tutorial, Section 3,
	Minor PEP 8 adjustment
In-Reply-To: <1321483693.18.0.17340985314.issue13416@psf.upfronthosting.co.za>
Message-ID: <1321783325.26.0.532618097896.issue13416@psf.upfronthosting.co.za>


Martin v. L?wis <martin at v.loewis.de> added the comment:

Indeed, PEP 8 mandates that constants be written in all uppercase, so changing it would actually make it deviate from PEP 8. Also, using a lower-case variable name "string" would be a bad choice because it collides with a module name.

----------
nosy: +loewis

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13416>
_______________________________________

From report at bugs.python.org  Sun Nov 20 13:12:54 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sun, 20 Nov 2011 12:12:54 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321791174.41.0.127587448869.issue13433@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

I agree with Mark.  The Documenting Python docs were recently updated by Raymond Hettinger to recommend not abusing notes and warnings, and the doc maintainer Georg Brandl approved it: d5d91b14b238 (#12047).

----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sun Nov 20 13:21:55 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sun, 20 Nov 2011 12:21:55 +0000
Subject: [docs] [issue13435] Copybutton does not hide tracebacks
In-Reply-To: <1321724543.66.0.854276029391.issue13435@psf.upfronthosting.co.za>
Message-ID: <1321791715.59.0.00482393588175.issue13435@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Another way to fix this would be to use Sphinx 1.0 for Python 2.7, but I don?t know what?s the status of that, given the amount of changes needed.

----------
nosy: +eric.araujo, sandro.tosi

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13435>
_______________________________________

From report at bugs.python.org  Sun Nov 20 13:26:20 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sun, 20 Nov 2011 12:26:20 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
In-Reply-To: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>
Message-ID: <1321791980.58.0.569869427096.issue13437@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Hi Julian, thanks for your interest in improving Python and welcome!  It is Raymond who initially added these links, and I helped porting them between versions.  The criterion can be read in the commit message: ?Provide links to Python source in a handful of cases where the source is a generally helpful adjunct to the docs? (from http://hg.python.org/cpython/rev/fdd3681b1439/).  Not all modules have source code that is easy or helpful to read; not all modules have Python source code (itertools doesn?t).  I think Raymond is not willing to add links for all modules, but if you have a list of specific names which would benefit from source links, I?m sure he will consider them.

----------
assignee: docs at python -> rhettinger
nosy: +eric.araujo, rhettinger
versions: +Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Sun Nov 20 15:20:19 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sun, 20 Nov 2011 14:20:19 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1321798819.2.0.523111456654.issue10318@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

The patches I?ve discussed and committed were actually peripheral.  The original bug reported here is that shebangs shouldn?t use ?/usr/bin/env python? with an altinstall installation, as in that case you?re not creating a python (or python3) binary but a pythonx.y, so the shebangs should refer to that exact x.y versions.

The few scripts from Tools/scripts (idle, pydoc, 2to3, python-config) are installed with an x.y suffix and hard-code the Python version and location at build time, by using distutils.  (That?s why Nick reports the only matches for ?3.2? found by grep are in the build/scripts directory.)

The stdlib modules do use ?/usr/bin/env python[3]?.  I see various ways to handle that:
a) Reject the bug as works for me: these are stdlib modules, not scripts, they can be imported or executed with -m, they?re not symlinked (by us) from anywhere so the bug, while technically valid, has no real effect.

b) Further complicate the build/install machinery to update shebangs in altinstall mode.

c) Remove useless shebangs and execute bit in the stdlib.

My preference is to do c) for 3.3 and nothing for the stable versions.

(About wrongly using python in Python 3 docs: I?ll open another bug for that).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Sun Nov 20 15:28:03 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sun, 20 Nov 2011 14:28:03 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321799283.89.0.184550843994.issue13387@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

No, I?m not talking about a rephrasing, but on a full change of meaning.  I don?t understand your use of ?superclasses? at all; isinstance(x, T) checks if x is an instance of T or any subclass, am I wrong?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Sun Nov 20 17:09:15 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 20 Nov 2011 16:09:15 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321805355.67.0.387635276945.issue13387@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

Is "To check for the exact type, use :func:`assertIs(type(obj), cls) <assertIs>`." better?
I think the problem this solves is clear enough even without mentioning sub/superclasses.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Sun Nov 20 18:07:29 2011
From: report at bugs.python.org (=?utf-8?b?SmVzw7pzIENlYSBBdmnDs24=?=)
Date: Sun, 20 Nov 2011 17:07:29 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1321808849.45.0.529352267658.issue10318@psf.upfronthosting.co.za>


Jes?s Cea Avi?n <jcea at jcea.es> added the comment:

+1 to "c".

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Sun Nov 20 21:02:48 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 20 Nov 2011 20:02:48 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
In-Reply-To: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>
Message-ID: <1321819368.58.0.47410691055.issue13437@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +ezio.melotti

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Sun Nov 20 21:09:08 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Sun, 20 Nov 2011 20:09:08 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1321819748.3.0.595686705692.issue13402@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

Attached a patch.

----------
keywords: +patch
Added file: http://bugs.python.org/file23738/issue13402.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Sun Nov 20 21:41:24 2011
From: report at bugs.python.org (Amaury Forgeot d'Arc)
Date: Sun, 20 Nov 2011 20:41:24 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <1321821684.8.0.380665793442.issue13436@psf.upfronthosting.co.za>


Amaury Forgeot d'Arc <amauryfa at gmail.com> added the comment:

Here is a patch for the bad error message (PyBytes_AS_BYTES after PyObject_Repr, bah)

----------
keywords: +patch
nosy: +amaury.forgeotdarc
Added file: http://bugs.python.org/file23739/issue13436.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Sun Nov 20 21:43:09 2011
From: report at bugs.python.org (Amaury Forgeot d'Arc)
Date: Sun, 20 Nov 2011 20:43:09 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <1321821789.29.0.712551651995.issue13436@psf.upfronthosting.co.za>


Changes by Amaury Forgeot d'Arc <amauryfa at gmail.com>:


----------
nosy: +benjamin.peterson

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Sun Nov 20 22:24:19 2011
From: report at bugs.python.org (=?utf-8?q?Bo=C5=A1tjan_Mejak?=)
Date: Sun, 20 Nov 2011 21:24:19 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1307439951.32.0.810805209718.issue12277@psf.upfronthosting.co.za>
Message-ID: <1321824259.73.0.145768237856.issue12277@psf.upfronthosting.co.za>


Bo?tjan Mejak <bostjan.mejak at gmail.com> added the comment:

http://docs.python.org/release/2.6.7/library/os.html?highlight=os.walk#os.walk

Please fix Python 2.6 branch of docs as well. Thanks.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From report at bugs.python.org  Sun Nov 20 22:25:12 2011
From: report at bugs.python.org (=?utf-8?q?Bo=C5=A1tjan_Mejak?=)
Date: Sun, 20 Nov 2011 21:25:12 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1307439951.32.0.810805209718.issue12277@psf.upfronthosting.co.za>
Message-ID: <1321824312.12.0.412501459432.issue12277@psf.upfronthosting.co.za>


Changes by Bo?tjan Mejak <bostjan.mejak at gmail.com>:


----------
status: closed -> open
versions: +Python 2.6 -Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From michal at pykonik.org  Sun Nov 20 20:33:37 2011
From: michal at pykonik.org (=?ISO-8859-2?Q?Micha=B3_Cha=B3upczak?=)
Date: Sun, 20 Nov 2011 20:33:37 +0100
Subject: [docs] bug in Functional Programming HOWTO
Message-ID: <CAHyGSXhKALtbB4BWyUvNJ29zd7k6H2UxODwjk-8aTgk-e7TuBQ@mail.gmail.com>

Hi,

I have found small bug in Functional Programming HOWTO. In section
http://docs.python.org/howto/functional.html#python-specific In the last
sentence there are some links given. The two first point to resource that
does not exist.

The first link, "part 1", points to
http://www.ibm.com/developerworks/library/l-prog.html but should point to
http://www.ibm.com/developerworks/linux/library/l-prog.html.
The second link, "part 2" points to
http://www.ibm.com/developerworks/library/l-prog2.html but should point to
http://www.ibm.com/developerworks/linux/library/l-prog2/index.html.

Those are really small mistakes and I am sure that everyone fix them on
their own when reading documentation. Nevertheless it would be nice if
there are no errors in python doc at all.

Regards,
micha? cha?upczak
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111120/66ef6d71/attachment.html>

From report at bugs.python.org  Mon Nov 21 01:00:40 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 21 Nov 2011 00:00:40 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1321833640.78.0.966514783482.issue10318@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

+1 to 'c', but it should come with an update to PEP 8 to say "don't do that".

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Mon Nov 21 01:24:28 2011
From: report at bugs.python.org (Benjamin Peterson)
Date: Mon, 21 Nov 2011 00:24:28 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <1321835068.84.0.248673059646.issue13436@psf.upfronthosting.co.za>


Benjamin Peterson <benjamin at python.org> added the comment:

LGTM.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Mon Nov 21 01:24:36 2011
From: report at bugs.python.org (Benjamin Peterson)
Date: Mon, 21 Nov 2011 00:24:36 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <1321835076.49.0.00973185222612.issue13436@psf.upfronthosting.co.za>


Changes by Benjamin Peterson <benjamin at python.org>:


----------
assignee: docs at python -> 

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Mon Nov 21 01:47:20 2011
From: report at bugs.python.org (Julian Berman)
Date: Mon, 21 Nov 2011 00:47:20 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
In-Reply-To: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>
Message-ID: <1321836440.43.0.763426033211.issue13437@psf.upfronthosting.co.za>


Julian Berman <Julian+Python.org at GrayVines.com> added the comment:

Here's first a quick list from one pass over the docs. I've attempted to limit myself to a few like you've suggested, though I'll wait for confirmation that Raymond is not willing to simply add them to everything once we're at it :).

http://docs.python.org/library/difflib.html
http://docs.python.org/library/stringio.html
http://docs.python.org/library/codecs.html
http://docs.python.org/library/stringprep.html
http://docs.python.org/library/datetime.html
http://docs.python.org/library/math.html
http://docs.python.org/library/cmath.html
http://docs.python.org/library/decimal.html
http://docs.python.org/library/itertools.html
http://docs.python.org/library/os.path.html
http://docs.python.org/library/csv.html
http://docs.python.org/library/configparser.html
http://docs.python.org/library/logging.html
http://docs.python.org/library/getpass.html
http://docs.python.org/library/json.html
http://docs.python.org/library/urllib2.html
http://docs.python.org/library/unittest.html
http://docs.python.org/library/code.html

When I hit the docs to diagnose a problem, it's usually to take a quick look, and then to hit the source code to read that too, since most of the stuff that's in general use is common enough for me to know how it works in a general sense, so the source code is typically where I go pretty quickly after reading what the docs have to say.

It's not a huge deal obviously, hg.python.com is not the furthest thing away. Just seems convenient, especially since like I said a lot of the other ones I peek at already have links.


As for non-python modules, I really would like to say that linking to C source sounds just as reasonable to me, a little C never killed anyone :), but I don't want to push my luck, so I'll stick with whatever I can get here I guess (I know I put some non-python modules on the list).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Mon Nov 21 02:22:49 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 21 Nov 2011 01:22:49 +0000
Subject: [docs] [issue13442] Better support for pipe I/O encoding in
	subprocess
Message-ID: <1321838568.9.0.683093502178.issue13442@psf.upfronthosting.co.za>


New submission from Nick Coghlan <ncoghlan at gmail.com>:

Currently, pipes in the subprocess module work strictly with bytes I/O, *unless* you set "universal newlines=True". In that case, it assumes an output encoding of UTF-8 for stdout and stderr and applies universal newlines process.

When stdin/out/err are remapped to ordinary I/O streams then 'encoding' and 'errors' can be specified as usual, but it is currently challenging to do this for pipes. Since they're created internally by the subprocess module, user code doesn't get the opportunity to wrap them when using the convenience APIs. When using Popen objects, you have to create the object, then wrap each stream individually (rebinding the attributes as you go).

My suggestion is that we add a new option for the stdin/out/err arguments:

    class TextPipe:
        def __init__(self, encoding, errors='strict'):
            self.encoding = encoding
            self.errors = errors

So to read UTF-8 encoded data from a subprocess, you could just do:

    data = check_stdout(cmd, stdout=TextPipe('utf-8'), stderr=STDOUT)

There are at least a couple of other alternatives here:

- separate out the pipe creation logic from the Popen logic so it is possible to create and wrap the pipe objects explicitly and then pass the wrapped pipe object to the subprocess invocation APIs. 'TextPipe' would then actually be such a wrapped pipe, rather than merely instructions to tell Popen what kind of pipe to create.
- instead of adding 'TextPipe', just re-use the PIPE name (with the class itself still being used as a marker constant to request implicit creation of a binary PIPE)

----------
assignee: docs at python
components: Documentation
messages: 148022
nosy: docs at python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Better support for pipe I/O encoding in subprocess
versions: Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13442>
_______________________________________

From report at bugs.python.org  Mon Nov 21 02:25:27 2011
From: report at bugs.python.org (STINNER Victor)
Date: Mon, 21 Nov 2011 01:25:27 +0000
Subject: [docs] [issue13442] Better support for pipe I/O encoding in
	subprocess
In-Reply-To: <1321838568.9.0.683093502178.issue13442@psf.upfronthosting.co.za>
Message-ID: <1321838727.23.0.0528033923546.issue13442@psf.upfronthosting.co.za>


STINNER Victor <victor.stinner at haypocalc.com> added the comment:

This issue looks as a duplicate of #6135.

----------
nosy: +haypo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13442>
_______________________________________

From report at bugs.python.org  Mon Nov 21 02:32:26 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 21 Nov 2011 01:32:26 +0000
Subject: [docs] [issue13442] Better support for pipe I/O encoding in
	subprocess
In-Reply-To: <1321838568.9.0.683093502178.issue13442@psf.upfronthosting.co.za>
Message-ID: <1321839146.49.0.387612326674.issue13442@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

Indeed, I'll add my suggestions over there.

----------
assignee: docs at python -> 
resolution:  -> duplicate
stage: needs patch -> committed/rejected
status: open -> closed
superseder:  -> subprocess seems to use local 8-bit encoding and gives no choice

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13442>
_______________________________________

From eliben at gmail.com  Mon Nov 21 05:25:59 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Mon, 21 Nov 2011 06:25:59 +0200
Subject: [docs] bug in Functional Programming HOWTO
In-Reply-To: <CAHyGSXhKALtbB4BWyUvNJ29zd7k6H2UxODwjk-8aTgk-e7TuBQ@mail.gmail.com>
References: <CAHyGSXhKALtbB4BWyUvNJ29zd7k6H2UxODwjk-8aTgk-e7TuBQ@mail.gmail.com>
Message-ID: <CAF-Rda_7oXd3aoxpWgiiQWF+CjY1s4Sxw04YoaXeUcCVij63xw@mail.gmail.com>

2011/11/20 Micha? Cha?upczak <michal at pykonik.org>:
> Hi,
>
> I have found small bug in Functional Programming HOWTO. In section
> http://docs.python.org/howto/functional.html#python-specific In the last
> sentence there are some links given. The two first point to resource that
> does not exist.
>
> The first link, "part 1", points to
> http://www.ibm.com/developerworks/library/l-prog.html but should point to
> http://www.ibm.com/developerworks/linux/library/l-prog.html.
> The second link, "part 2" points to
> http://www.ibm.com/developerworks/library/l-prog2.html but should point to
> http://www.ibm.com/developerworks/linux/library/l-prog2/index.html.
>
> Those are really small mistakes and I am sure that everyone fix them on
> their own when reading documentation. Nevertheless it would be nice if there
> are no errors in python doc at all.
>
> Regards,
> micha? cha?upczak

Hi Micha?,

Thanks for the report - the links are indeed broken. However, I wonder
whether there's sense to provide these links at all, given that the
article was written in 2001. The code samples there don't work with
Python 3.x at all, AFAICS. Perhaps it will be best to remove these
links altogether?

Eli

From report at bugs.python.org  Mon Nov 21 05:28:26 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 21 Nov 2011 04:28:26 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1321849706.68.0.534188456735.issue13402@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

LGTM

----------
nosy: +eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Mon Nov 21 05:40:04 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 21 Nov 2011 04:40:04 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
Message-ID: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>


New submission from Eli Bendersky <eliben at gmail.com>:

Micha? Cha?upczak reported in this docs@ list that the links to IBM developerworks articles are wrong.

>From some additional observation, the code samples on the 3.x page use the external `functional` module, which was not ported to Python 3 at all.

I wonder whether it makes sense to use external modules in official Python documentation, since these are not guaranteed to be ported. This issue is a good example of this happening.

The HOWTO should be probably rewritten to use only the stdlib. The links to IBM developerworks should be, IMHO, removed, since they point to articles written in 2001 and have code samples that won't work on Python 3.x

----------
assignee: docs at python
components: Documentation
messages: 148030
nosy: akuchling, docs at python, eli.bendersky
priority: normal
severity: normal
status: open
title: wrong links and examples in the functional HOWTO
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From eliben at gmail.com  Mon Nov 21 05:40:18 2011
From: eliben at gmail.com (Eli Bendersky)
Date: Mon, 21 Nov 2011 06:40:18 +0200
Subject: [docs] bug in Functional Programming HOWTO
In-Reply-To: <CAF-Rda_7oXd3aoxpWgiiQWF+CjY1s4Sxw04YoaXeUcCVij63xw@mail.gmail.com>
References: <CAHyGSXhKALtbB4BWyUvNJ29zd7k6H2UxODwjk-8aTgk-e7TuBQ@mail.gmail.com>
	<CAF-Rda_7oXd3aoxpWgiiQWF+CjY1s4Sxw04YoaXeUcCVij63xw@mail.gmail.com>
Message-ID: <CAF-Rda_1x+r-vZsOaSOU0x=cNVOJvozf7hJHdZSSH5jJeyYk+A@mail.gmail.com>

2011/11/21 Eli Bendersky <eliben at gmail.com>:
> 2011/11/20 Micha? Cha?upczak <michal at pykonik.org>:
>> Hi,
>>
>> I have found small bug in Functional Programming HOWTO. In section
>> http://docs.python.org/howto/functional.html#python-specific In the last
>> sentence there are some links given. The two first point to resource that
>> does not exist.
>>
>> The first link, "part 1", points to
>> http://www.ibm.com/developerworks/library/l-prog.html but should point to
>> http://www.ibm.com/developerworks/linux/library/l-prog.html.
>> The second link, "part 2" points to
>> http://www.ibm.com/developerworks/library/l-prog2.html but should point to
>> http://www.ibm.com/developerworks/linux/library/l-prog2/index.html.
>>
>> Those are really small mistakes and I am sure that everyone fix them on
>> their own when reading documentation. Nevertheless it would be nice if there
>> are no errors in python doc at all.
>>
>> Regards,
>> micha? cha?upczak
>
> Hi Micha?,
>
> Thanks for the report - the links are indeed broken. However, I wonder
> whether there's sense to provide these links at all, given that the
> article was written in 2001. The code samples there don't work with
> Python 3.x at all, AFAICS. Perhaps it will be best to remove these
> links altogether?
>

Looking a bit more into it, there's a deeper problem. The 'functional'
module mentioned all over this HOWTO doesn't appear to have been
ported to Python 3 at all,
(http://oakwinter.com/code/functional/download.html), so (at least)
the 3.x version of the HOWTO is wrong not only in terms of links.

I have opened http://bugs.python.org/issue13443 to track this.

Eli

From report at bugs.python.org  Mon Nov 21 06:31:40 2011
From: report at bugs.python.org (Georg Brandl)
Date: Mon, 21 Nov 2011 05:31:40 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1307439951.32.0.810805209718.issue12277@psf.upfronthosting.co.za>
Message-ID: <1321853500.46.0.437872822508.issue12277@psf.upfronthosting.co.za>


Changes by Georg Brandl <georg at python.org>:


----------
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From report at bugs.python.org  Mon Nov 21 08:00:24 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Mon, 21 Nov 2011 07:00:24 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1307439951.32.0.810805209718.issue12277@psf.upfronthosting.co.za>
Message-ID: <1321858824.83.0.376381619213.issue12277@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

> Please fix Python 2.6 branch of docs as well. Thanks.

2.6 only receives security fixes any more.

----------
versions: +Python 2.7, Python 3.2, Python 3.3 -Python 2.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From report at bugs.python.org  Mon Nov 21 11:03:05 2011
From: report at bugs.python.org (Christian Iversen)
Date: Mon, 21 Nov 2011 10:03:05 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1321869785.22.0.201160047082.issue13433@psf.upfronthosting.co.za>


Christian Iversen <ci at sikkerhed.org> added the comment:

Certainly, I don't think we should be peppering the docs with warnings and notes, either.

However, the elements in question _already have_ notes. I propose that the note for %g (4) simply be updated for clarity. Something like this, perhaps:

"""Unlike the other floating-point formats, the precision determines the number of significant digits before and after the decimal point and defaults to 6."""

Simply adding "Unlike the other floating-point formats," at the beginning of the second line makes it much clearer that this is a different beast.

If you feel that is not the right solution, then feel free to close this issue.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Mon Nov 21 13:06:16 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 21 Nov 2011 12:06:16 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
In-Reply-To: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>
Message-ID: <1321877176.15.0.736980552965.issue13437@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

There are usually two cases that lead me to check the code:
1) The documentation is incomplete, not clear, missing, or plain wrong;
2) I want to check how something is implemented, mostly just out of curiosity;

Regarding the first case, in theory the docs should be informative and correct enough to not require you to go and check the code.  If they aren't you can report issues and we can improve it.
The second case applies to pretty much any module.  Linking to the code might also expose some internal details that should be just ignored by the user.  The code in some modules is also pretty old and might be a "bad" example (because it doesn't use modern conventions).
Some of the modules you listed are actually packages, so that would require to link to several files.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Mon Nov 21 13:07:31 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 21 Nov 2011 12:07:31 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1321877251.34.0.548313654253.issue13443@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
keywords: +easy
nosy: +ezio.melotti
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Mon Nov 21 14:46:39 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 21 Nov 2011 13:46:39 +0000
Subject: [docs] [issue13387] suggest assertIs(type(obj),
	cls) for exact type checking
In-Reply-To: <1321101802.89.0.94542095022.issue13387@psf.upfronthosting.co.za>
Message-ID: <1321883199.59.0.0367137961792.issue13387@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Your latest proposal is better.  I would prefer mentioning subclasses, but don?t feel strongly about it.  One markup nit: I?d use ``code`` instead of (ab)using :func:; the doc for assertIs is just a few paragraphs above, it won?t be hard to find.

----------
resolution: fixed -> 
stage: committed/rejected -> commit review
status: closed -> open

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13387>
_______________________________________

From report at bugs.python.org  Mon Nov 21 14:50:03 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 21 Nov 2011 13:50:03 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1321883403.49.0.00560350977728.issue13402@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Patch looks good, but are you 100% sure that sys.executable is always absolute?  (On all OSes, under multiprocessing, etc?)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Mon Nov 21 15:20:04 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Mon, 21 Nov 2011 14:20:04 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321883403.49.0.00560350977728.issue13402@psf.upfronthosting.co.za>
Message-ID: <20111121141949.GD9731@p16>


Petri Lehtinen <petri at digip.org> added the comment:

?ric Araujo wrote:
> Patch looks good, but are you 100% sure that sys.executable is
> always absolute? (On all OSes, under multiprocessing, etc?)

Well, its value is computed by a function named
Py_GetProgramFullPath(), so I'm quite sure. I had a quick look on what
the function is doing, but it was quite complicated. I can check it
better if needed.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Mon Nov 21 16:01:01 2011
From: report at bugs.python.org (=?utf-8?q?Bo=C5=A1tjan_Mejak?=)
Date: Mon, 21 Nov 2011 15:01:01 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1321858824.83.0.376381619213.issue12277@psf.upfronthosting.co.za>
Message-ID: <CAEt-fFwpLq1Kse_zopStX5cw1Mv=wRb28pRzPt2k3GLXnSZyVQ@mail.gmail.com>


Bo?tjan Mejak <bostjan.mejak at gmail.com> added the comment:

That is simply idiotic. Your way of fixing things is idiotic. When you
clearly see the missing comma and you fix it everywhere else but 2.6
because "2.6 only receives security fixes" as if adding a comma to the
documentation would create a big security hole. That's an act of an idiot.
I am sorry, but that is how I see it.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From report at bugs.python.org  Mon Nov 21 16:04:12 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 21 Nov 2011 15:04:12 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1307439951.32.0.810805209718.issue12277@psf.upfronthosting.co.za>
Message-ID: <1321887852.36.0.0425221686383.issue12277@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

It's not because of the security risk, but simply because the docs for 2.6 are not rebuilt automatically anymore.  So, even if we fix it on 2.6, no one will see the change unless someone goes and triggers a full doc rebuild manually.  A missing comma is not enough to justify this extra work.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From report at bugs.python.org  Mon Nov 21 19:06:16 2011
From: report at bugs.python.org (Benjamin Peterson)
Date: Mon, 21 Nov 2011 18:06:16 +0000
Subject: [docs] [issue12277] Missing comma in os.walk docs
In-Reply-To: <1307439951.32.0.810805209718.issue12277@psf.upfronthosting.co.za>
Message-ID: <1321898776.4.0.329083493844.issue12277@psf.upfronthosting.co.za>


Benjamin Peterson <benjamin at python.org> added the comment:

The reason is simply that 2.6 basically unmaintained.

----------
nosy: +benjamin.peterson

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12277>
_______________________________________

From miguel.barao at gmail.com  Mon Nov 21 15:39:02 2011
From: miguel.barao at gmail.com (=?iso-8859-1?Q?Miguel_Bar=E3o?=)
Date: Mon, 21 Nov 2011 14:39:02 +0000
Subject: [docs] improvement sugestion on python 2.7.2 documentation:
	__builtin__ vs __builtins__
Message-ID: <6126884F-9350-4D9E-9851-87D3F1B76F43@gmail.com>

Section 6.3 of the tutorial says that "dir() does not list the names of built-in functions and variables", and recommends running

	import __builtin__
	dir(__builtin__)

It it not clear if there is any difference between this and just

	dir(__builtins__)



Best regards
Miguel Bar?o


From gcbirzan at gmail.com  Mon Nov 21 20:03:00 2011
From: gcbirzan at gmail.com (=?UTF-8?Q?George=2DCristian_B=C3=AErzan?=)
Date: Mon, 21 Nov 2011 21:03:00 +0200
Subject: [docs] % deprecation
Message-ID: <CALaqNZM_KS6HO+tJSU-qqDwDs87oQcT4qS76NngB_ZRq9BQueg@mail.gmail.com>

On http://docs.python.org/py3k/whatsnew/3.0.html it is mentioned that
% may get deprecated for string formatting in 3.1. This seems to not
be the case, as even in 3.3, there's no indication of it getting
deprecated, and while I haven't checked the mailing lists (google
doesn't like searching for %), but that should be fixed to reflect the
current plans.

-- 
George-Cristian B?rzan

From report at bugs.python.org  Mon Nov 21 21:08:03 2011
From: report at bugs.python.org (Eric Snow)
Date: Mon, 21 Nov 2011 20:08:03 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1321906083.62.0.320769753075.issue13402@psf.upfronthosting.co.za>


Changes by Eric Snow <ericsnowcurrently at gmail.com>:


----------
nosy: +eric.snow

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Tue Nov 22 01:53:09 2011
From: report at bugs.python.org (STINNER Victor)
Date: Tue, 22 Nov 2011 00:53:09 +0000
Subject: [docs] [issue8646] PyUnicode_EncodeDecimal is undocumented
In-Reply-To: <1273247945.7.0.702043835904.issue8646@psf.upfronthosting.co.za>
Message-ID: <1321923189.74.0.40761565821.issue8646@psf.upfronthosting.co.za>


STINNER Victor <victor.stinner at haypocalc.com> added the comment:

I added tests for PyUnicode_EncodeDecimal() and PyUnicode_TransformDecimalToASCII() in Python 2.7, 3.2 and 3.3 (see also issue #13093).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8646>
_______________________________________

From report at bugs.python.org  Tue Nov 22 15:37:08 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 22 Nov 2011 14:37:08 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1321972627.97.0.718346349827.issue10318@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Patch to PEP 8 attached.

----------
Added file: http://bugs.python.org/file23755/pep8-shebangs.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Tue Nov 22 16:13:40 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 22 Nov 2011 15:13:40 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1321974820.29.0.641087261311.issue13443@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Broken links should obviously be fixed, either to their newer location if it can be found or to Web Archive links.

I think that it?s a good thing to link to some outside articles and code from the official docs; we acknowledge that the stdlib is not the whole of the Python world and we put good writings/code into the spotlight.  Here, even if the code is 2.x-only, the ideas and examples it contains can IMO still be valuable for readers, even if they can?t be directly used, so my vote is to keep them.

----------
nosy: +eric.araujo, rhettinger

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Tue Nov 22 20:02:14 2011
From: report at bugs.python.org (R. David Murray)
Date: Tue, 22 Nov 2011 19:02:14 +0000
Subject: [docs] [issue13456] Providing a custom HTTPResponse class to
	HTTPConnection
Message-ID: <1321988533.96.0.72454390842.issue13456@psf.upfronthosting.co.za>


New submission from R. David Murray <rdmurray at bitdance.com>:

The doc string for HTTPConnection.getresponse mentions (in broken English) that the instance's response_class attribute determines what class gets instantiated for a response.  The docs do not mention this attribute, nor any other way to control what class is used.

Since this attribute already exists and is mentioned in the doc string, can we consider this a doc error and just document it?

----------
assignee: docs at python
components: Documentation
messages: 148136
nosy: docs at python, orsenthil, r.david.murray
priority: normal
severity: normal
status: open
title: Providing a custom HTTPResponse class to HTTPConnection
versions: Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13456>
_______________________________________

From report at bugs.python.org  Tue Nov 22 22:02:30 2011
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 22 Nov 2011 21:02:30 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <E1RSxTr-0007vp-JM@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset ffcdfc534942 by Amaury Forgeot d'Arc in branch '3.2':
Issue #13436: Fix a bogus error message when an AST object was passed
http://hg.python.org/cpython/rev/ffcdfc534942

New changeset 470f7d7c57ce by Amaury Forgeot d'Arc in branch '3.2':
Issue #13436: commit regenerated Python-ast.c
http://hg.python.org/cpython/rev/470f7d7c57ce

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Tue Nov 22 22:04:59 2011
From: report at bugs.python.org (Amaury Forgeot d'Arc)
Date: Tue, 22 Nov 2011 21:04:59 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <1321995899.81.0.0481003219769.issue13436@psf.upfronthosting.co.za>


Amaury Forgeot d'Arc <amauryfa at gmail.com> added the comment:

I fixed the bogus error message, but "level=None" is still not allowed, whereas the docs promise that optional values can be None.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Tue Nov 22 22:30:59 2011
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 22 Nov 2011 21:30:59 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <E1RSxvQ-0001zU-Qm@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 2e5506d9a079 by Victor Stinner in branch '3.2':
Issue #13436: Fix unsetenv() test on Windows
http://hg.python.org/cpython/rev/2e5506d9a079

New changeset 029ad97883ef by Victor Stinner in branch 'default':
(Merge 3.2) Issue #13436: Fix unsetenv() test on Windows
http://hg.python.org/cpython/rev/029ad97883ef

New changeset e66ef9fa55de by Victor Stinner in branch '2.7':
Issue #13436: Fix unsetenv() test on Windows
http://hg.python.org/cpython/rev/e66ef9fa55de

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Wed Nov 23 01:08:58 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Wed, 23 Nov 2011 00:08:58 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1322006938.72.0.537914542127.issue10318@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

Hmm, my initial reaction is that that specific wording is stronger than I had in mind - there's nothing really wrong with having a shebang line and execute bit set on a top level module and symlinking it from /usr/bin. The problem is that we're doing those things for modules that we *don't* install as binaries, and that's silly (particularly when the shebang lines are wrong on altinstall). However, that concern can specifically by addressed by moving the new section down to be a subheading in the "Rules that apply only to the standard library" section.

I'd also mention the justification that this is due to such shebang lines creating a maintenance problem for handling parallel installations of different Python versions.

Also, with PEP 397 a viable candidate, we may as well make the wording OS neutral. Something like:

=======================
Executable Files and Shebang Lines

   Standard library modules (including test modules) should not be
   flagged as executable files nor contain a shebang line.

   Including shebang lines in standard library modules is an issue, as
   they create a maintenance problem when multiple versions of Python
   are installed in parallel. The easiest way to avoid accidentally
   invoking the wrong version of Python is to simply not include such
   lines at all.

   If a module provides command-line functionality, it can be used with
   ``python -m module`` or via a small script (in a different file) that
   imports the module and calls one of its functions (e.g. the ``pydoc``
   script imports the ``pydoc`` module and calls ``pydoc.cli()``).

   Any installed scripts should use a shebang line of the form::

        #!/usr/bin/env pythonX.Y

   where ``X.Y`` is the specific Python version being installed.
   Updating these lines to the correct Python version should be
   automated, either as part of the installation process or as part
   of the version update process (see PEP 101).
=======================

The PEP 8 update should be run by the wider audience of python-dev before it gets committed, though.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Wed Nov 23 02:17:34 2011
From: report at bugs.python.org (Mike Fogel)
Date: Wed, 23 Nov 2011 01:17:34 +0000
Subject: [docs] [issue13459] logger.propagate=True behavior clarification
Message-ID: <1322011053.76.0.547589220073.issue13459@psf.upfronthosting.co.za>


New submission from Mike Fogel <mike at fogel.ca>:

Hi, there's been a fair amount of confusion over the interaction between logger.propagate and the ancestor logger's handlers and level.

http://bugs.python.org/issue7535
http://bugs.python.org/issue8327
http://bugs.python.org/issue9606

I think most this confusion could be avoided if the documentation for logger.propagate were expanded to explain clearly what happens when propagate evaluates to True - right now it just explains clearly what happens when it evaluates to False.

Attached is a documentation patch that does this.

Thanks for your consideration!

----------
assignee: docs at python
components: Documentation
files: logger_propagate_doc.diff
keywords: patch
messages: 148164
nosy: docs at python, mfogel, vinay.sajip
priority: normal
severity: normal
status: open
title: logger.propagate=True behavior clarification
versions: Python 2.7, Python 3.3
Added file: http://bugs.python.org/file23761/logger_propagate_doc.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13459>
_______________________________________

From report at bugs.python.org  Wed Nov 23 07:30:42 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Wed, 23 Nov 2011 06:30:42 +0000
Subject: [docs] [issue13439] turtle docstring for onkeyrelease references
	onkey, not onkeyrelease
In-Reply-To: <1321802124.14.0.262913683551.issue13439@psf.upfronthosting.co.za>
Message-ID: <1322029842.28.0.639032044212.issue13439@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

onkey and onkeyrelease are the same function, so you still get exactly the same behavior with the example in the docstring. This also makes it hard to have different docstrings for them.

Closing as wontfix.

----------
assignee:  -> docs at python
components: +Documentation
nosy: +docs at python, gregorlingl
resolution:  -> wont fix
stage:  -> committed/rejected
status: open -> closed
type:  -> behavior
versions: +Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13439>
_______________________________________

From report at bugs.python.org  Wed Nov 23 09:56:28 2011
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 23 Nov 2011 08:56:28 +0000
Subject: [docs] [issue13459] logger.propagate=True behavior clarification
In-Reply-To: <1322011053.76.0.547589220073.issue13459@psf.upfronthosting.co.za>
Message-ID: <E1RT8co-00055e-5m@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 2c173769a957 by Vinay Sajip in branch '2.7':
Closes #13459: Clarified documentation on Logger.propagate. Thanks to Mike Fogel for the patch.
http://hg.python.org/cpython/rev/2c173769a957

New changeset a9f5639e18a1 by Vinay Sajip in branch '3.2':
Closes #13459: Clarified documentation on Logger.propagate. Thanks to Mike Fogel for the patch.
http://hg.python.org/cpython/rev/a9f5639e18a1

New changeset cc6693fdf6d5 by Vinay Sajip in branch 'default':
Closes #13459: Merged fix from 3.2.
http://hg.python.org/cpython/rev/cc6693fdf6d5

----------
nosy: +python-dev
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13459>
_______________________________________

From report at bugs.python.org  Wed Nov 23 10:49:15 2011
From: report at bugs.python.org (Christopher Smith)
Date: Wed, 23 Nov 2011 09:49:15 +0000
Subject: [docs] [issue13439] turtle docstring for onkeyrelease references
	onkey, not onkeyrelease
In-Reply-To: <1321802124.14.0.262913683551.issue13439@psf.upfronthosting.co.za>
Message-ID: <1322041755.38.0.669431539169.issue13439@psf.upfronthosting.co.za>


Christopher Smith <smichr at users.sourceforge.net> added the comment:

Sorry for the misdirection:

The docstring example for onkeypress is written using onkey instead of onkeypress. (There is no problem for onkey and onkeyrelease.)

----------
resolution: wont fix -> 
status: closed -> open

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13439>
_______________________________________

From report at bugs.python.org  Wed Nov 23 18:04:59 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Wed, 23 Nov 2011 17:04:59 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1322067897.01.0.0183869407517.issue10318@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

> Hmm, my initial reaction is that that specific wording is stronger than I had in mind -
> there's nothing really wrong with having a shebang line and execute bit set on a top level
> module and symlinking it from /usr/bin.
Okay.  (On that topic, http://lists.debian.org/debian-python/2011/11/msg00058.html may interest you.)

> The problem is that we're doing those things for modules that we *don't* install as binaries,
> and that's silly
Yep.  Attached patch removes them for 3.3.

> I'd also mention the justification that this is due to such shebang lines creating a
> maintenance problem for handling parallel installations of different Python versions.
I?d rather just say that it?s unneeded.  With all due respect to the original poster, I don?t think this really caused problems.


I will move my addition to the stdlib-only section.  I?m not sure about OS-neutrality; the executable bit is Unix-specific and I?d rather use that exact term than a vague ?flagged as executable?.  I?ll make the part about shebangs neutral however, it won?t be hard.

About this part of your proposal:
> Any installed scripts should use a shebang line of the form::
>        #!/usr/bin/env pythonX.Y
Due to the use of distutils? build_scripts that hard-codes one path, I?m not sure it?s time yet to make that recommendation.  For packaging, I intend to launch a discussion about that behavior, which is often unhelpful.

I really appreciate your taking time to review, and will submit the next revision of the patch here before going to python-dev.

----------
Added file: http://bugs.python.org/file23763/no-shebangs-for-stdlib.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Wed Nov 23 18:20:24 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Wed, 23 Nov 2011 17:20:24 +0000
Subject: [docs] [issue12779] Update packaging documentation
In-Reply-To: <1313686169.0.0.406072932055.issue12779@psf.upfronthosting.co.za>
Message-ID: <1322068824.68.0.667242410844.issue12779@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Making this a release blocker for d2 1.0a4.

----------
priority: normal -> release blocker

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12779>
_______________________________________

From report at bugs.python.org  Wed Nov 23 20:58:43 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Wed, 23 Nov 2011 19:58:43 +0000
Subject: [docs] [issue13439] turtle: Errors in docstrings of onkey and
	onkeypress
In-Reply-To: <1321802124.14.0.262913683551.issue13439@psf.upfronthosting.co.za>
Message-ID: <1322078323.86.0.610707410155.issue13439@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

There are actually many problems with docstrings of both onkey() and onkeypress().

Both:

- "Turtle instance named turtle" isn't used in the example

- The repl/doctest syntax is weird

onkeypress only:

- "key-press event" vs. "key-press-event"

- The example uses onkey() instead of onkeypress()

- The bottom comment says that the example draws a hexagon, but it actually draws a straight line.

----------
stage: committed/rejected -> 
title: turtle docstring for onkeyrelease references onkey, not onkeyrelease -> turtle: Errors in docstrings of onkey and onkeypress

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13439>
_______________________________________

From report at bugs.python.org  Wed Nov 23 21:01:50 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Wed, 23 Nov 2011 20:01:50 +0000
Subject: [docs] [issue13439] turtle: Errors in docstrings of onkey and
	onkeypress
In-Reply-To: <1321802124.14.0.262913683551.issue13439@psf.upfronthosting.co.za>
Message-ID: <1322078510.07.0.511525955303.issue13439@psf.upfronthosting.co.za>


Petri Lehtinen <petri at digip.org> added the comment:

The problems with onkey() are also there in 2.7. onkeypress() is new in 3.x.

----------
keywords: +easy
stage:  -> needs patch
versions: +Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13439>
_______________________________________

From report at bugs.python.org  Wed Nov 23 22:00:19 2011
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 23 Nov 2011 21:00:19 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322082019.87.0.764544362818.issue13443@psf.upfronthosting.co.za>


A.M. Kuchling <lists at amk.ca> added the comment:

Here's a patch against the 3.3 trunk.

----------
Added file: http://bugs.python.org/file23765/functional-patch.txt

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Wed Nov 23 23:26:08 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Wed, 23 Nov 2011 22:26:08 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1322087167.85.0.126098373052.issue10318@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

Hmm, interesting mailing list post - I hadn't thought about how the auto-initialisation of sys.path[0] aligns with the Windows vs Unix difference in PATH handling (i.e. whether or not the current directory is considered to be on PATH), with Python coming down in favour of the usually-more-convenient-but-less-secure Windows approach.

We have -S to disable all site processing, -s to disable user site packages and -E to ignore PYTHONPATH and PYTHONHOME - perhaps there should be another flag to skip the auto-initialisation of sys.path[0]. I may include something along those lines in PEP 395.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Thu Nov 24 03:38:26 2011
From: report at bugs.python.org (INADA Naoki)
Date: Thu, 24 Nov 2011 02:38:26 +0000
Subject: [docs] [issue13467] Typo in doc for library/sysconfig
Message-ID: <1322102306.14.0.426447482004.issue13467@psf.upfronthosting.co.za>


New submission from INADA Naoki <songofacandy at gmail.com>:

http://docs.python.org/library/sysconfig.html#sysconfig.get_path

> If scheme is provided, it must be a value from the list returned by get_path_names().

s/get_path_names/get_scheme_names/

----------
assignee: docs at python
components: Documentation
messages: 148223
nosy: docs at python, naoki
priority: normal
severity: normal
status: open
title: Typo in doc for library/sysconfig
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13467>
_______________________________________

From report at bugs.python.org  Thu Nov 24 05:52:14 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Thu, 24 Nov 2011 04:52:14 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322110334.37.0.59802972179.issue13443@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Andrew, thanks, but I still think it's a bigger problem that the page discusses a module which is not available on Python 3.x - this means that a user following the page can't just type in the code and make it run.

The links can be fixed and kept there, as ?ric suggests, perhaps with a disclaimer, but code on the page itself should be valid - this is part of our official documentation, after all.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Thu Nov 24 08:26:00 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Thu, 24 Nov 2011 07:26:00 +0000
Subject: [docs] [issue13470] A user may need ... when she has ...
Message-ID: <1322119560.63.0.526352282157.issue13470@psf.upfronthosting.co.za>


New submission from Florent Xicluna <florent.xicluna at gmail.com>:

http://docs.python.org/library/sys.html#sys.setrecursionlimit
http://docs.python.org/dev/library/sys.html#sys.setrecursionlimit

Doc for Python 2.7 says:
"A user may need to set the limit higher when she has ..."

Doc for Python 3.3 says:
"A user may need to set the limit higher when they have ..."


IMHO "she" and "they" are not right here.
Is it an initiative of the "Python diversity" group :-)

----------
assignee: docs at python
components: Documentation
messages: 148231
nosy: docs at python, flox
priority: low
severity: normal
stage: needs patch
status: open
title: A user may need ... when she has ...
type: behavior
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13470>
_______________________________________

From report at bugs.python.org  Thu Nov 24 12:31:03 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Thu, 24 Nov 2011 11:31:03 +0000
Subject: [docs] [issue13470] A user may need ... when she has ...
In-Reply-To: <1322119560.63.0.526352282157.issue13470@psf.upfronthosting.co.za>
Message-ID: <1322134263.83.0.597766458132.issue13470@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

"they" is right and "she" is actually right too.

See http://en.wikipedia.org/wiki/Singular_they

----------
nosy: +pitrou
resolution:  -> works for me
status: open -> pending

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13470>
_______________________________________

From report at bugs.python.org  Thu Nov 24 15:56:59 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Thu, 24 Nov 2011 14:56:59 +0000
Subject: [docs] [issue13470] A user may need ... when she has ...
In-Reply-To: <1322119560.63.0.526352282157.issue13470@psf.upfronthosting.co.za>
Message-ID: <1322146619.05.0.397199122913.issue13470@psf.upfronthosting.co.za>


Florent Xicluna <florent.xicluna at gmail.com> added the comment:

This explanation is enough. Thanks.

----------
resolution: works for me -> invalid
stage: needs patch -> committed/rejected
status: pending -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13470>
_______________________________________

From report at bugs.python.org  Thu Nov 24 16:59:47 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Thu, 24 Nov 2011 15:59:47 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322150387.5.0.428766839273.issue13443@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks for the fixed links amk.  I think they can be fixed in the repo right now.

[Eli]
> I still think it's a bigger problem that the page discusses a module which
> is not available on Python 3.x - this means that a user following the page
> can't just type in the code and make it run.
It?s only one section that?s affected, so +1 to replacing its contents with just a link and short description (?the functional module does X and Y for Python 2?).  Before doing that, would you have the time to contact its author and inquire about porting plans?

(BTW, the file is also inconsistent in its use of :: vs. implicit code blocks; I wonder if that affects doctest or the ?hide prompts? button.)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Thu Nov 24 17:16:14 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Thu, 24 Nov 2011 16:16:14 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322151374.81.0.921846844286.issue13443@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

> Before doing that, would you have the time to contact its author and inquire about porting plans?

I hope to find the time. I was also thinking about an alternative - since the HOWTO probably uses just a handful of functions from that module perhaps they can just be re-implemented and placed in the HOWTO. This can remove the unhealthy dependency on an external module, as well as provide some extra examples.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Thu Nov 24 17:28:12 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Thu, 24 Nov 2011 16:28:12 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322152092.44.0.572694257749.issue13443@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Good idea.  The functions used are: compose, partial (which we have in functools), flip, foldl.

I will disagree with ?unhealthy?: I?m sure adding this link was a deliberate exposure of an external module, to put a well-written solution to the spotlight as a service to the users and an acknowledgment to the author.  If the cost is a little links bookkeeping for us, it is small :)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Thu Nov 24 21:10:59 2011
From: report at bugs.python.org (Eric Snow)
Date: Thu, 24 Nov 2011 20:10:59 +0000
Subject: [docs] [issue13474] Mention of "-m" Flag Missing From Doc on
	Execution Model
Message-ID: <1322165458.97.0.989343856998.issue13474@psf.upfronthosting.co.za>


New submission from Eric Snow <ericsnowcurrently at gmail.com>:

The doc on code execution[1] leaves out mention of the -m flag.  Seems like it belongs there too.

[1] Doc/reference/executionmodel.rst

----------
assignee: docs at python
components: Documentation
messages: 148288
nosy: docs at python, eric.snow
priority: normal
severity: normal
status: open
title: Mention of "-m" Flag Missing From Doc on Execution Model
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13474>
_______________________________________

From report at bugs.python.org  Thu Nov 24 21:32:26 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Thu, 24 Nov 2011 20:32:26 +0000
Subject: [docs] [issue13474] Mention of "-m" Flag Missing From Doc on
	Execution Model
In-Reply-To: <1322165458.97.0.989343856998.issue13474@psf.upfronthosting.co.za>
Message-ID: <1322166746.95.0.438448488267.issue13474@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +ezio.melotti
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13474>
_______________________________________

From fmartinez at syscom.com.mx  Wed Nov 23 20:25:44 2011
From: fmartinez at syscom.com.mx (Ing. Felipe Martinez)
Date: Wed, 23 Nov 2011 12:25:44 -0700
Subject: [docs] found an error in documentation
Message-ID: <4ECD48B8.1060303@syscom.com.mx>

in 20.17.4.2. SocketServer.UDPServer Example? 
http://docs.python.org/library/socketserver.html#examples

on the line 13 have a error :

This is the server side:

1 import SocketServer

2 class MyUDPHandler(SocketServer.BaseRequestHandler):
3    """
4   This class works similar to the TCP handler class, except that
5   self.request consists of a pair of data and client socket, and since
6   there is no connection the client address must be given explicitly
7   when sending data back via sendto().
8   """

9   def handle(self):
10       data = self.request[0].strip()
11       socket = self.request[1]
13       print "{} wrote:".format(self.client_address[0])    # on this 
line have the error, you concatenate whit . and need to be whit +
         print data
         socket.sendto(data.upper(), self.client_address)

if __name__ == "__main__":
     HOST, PORT = "localhost", 9999
     server = SocketServer.UDPServer((HOST, PORT), MyUDPHandler)
     server.serve_forever()



i speak a litle english, have a nice day.

-- 
Ing. Felipe Martinez
Tel: (614) 415-2525 ext 1358
Email: fmartinez at syscom.com.mx
www.syscom.com.mx


From cocoatomo77 at gmail.com  Thu Nov 24 13:43:23 2011
From: cocoatomo77 at gmail.com (tomo cocoa)
Date: Thu, 24 Nov 2011 21:43:23 +0900
Subject: [docs] documentation bug in library/httplib.rst
Message-ID: <CAN_7T0LJvgaeTC5L0=2WM4_k3YZX=KiJVjiMx0pXZs9jOK2Ryg@mail.gmail.com>

Hello

I am a Japanese Pythonista, who am translating ver2.7 document into Japanese.

I found a miscellaneous document bug in library/httplib.rst.

At the explanation about "HTTPConnection.set_tunnel(host,port=None,
headers=None)",
"extra HTTP headers to to sent" would be "extra HTTP headers to sent", I think.

Regards,
cocoatomo

-- 
class Cocoatomo:
? ? name = 'cocoatomo'
? ? email_address = 'cocoatomo77 at gmail.com'
? ? twitter_id = '@cocoatomo'

From report at bugs.python.org  Fri Nov 25 01:47:11 2011
From: report at bugs.python.org (Nick Coghlan)
Date: Fri, 25 Nov 2011 00:47:11 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1322182031.01.0.613767294443.issue10318@psf.upfronthosting.co.za>


Nick Coghlan <ncoghlan at gmail.com> added the comment:

I created #13475 to discuss the idea of a command line option to override sys.path[0] initialisation.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Fri Nov 25 05:44:45 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 25 Nov 2011 04:44:45 +0000
Subject: [docs] [issue4966] Improving Lib Doc Sequence Types Section
In-Reply-To: <1232149418.64.0.0450574767427.issue4966@psf.upfronthosting.co.za>
Message-ID: <1322196285.82.0.586594359817.issue4966@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
versions:  -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4966>
_______________________________________

From report at bugs.python.org  Fri Nov 25 09:13:35 2011
From: report at bugs.python.org (Sandro Tosi)
Date: Fri, 25 Nov 2011 08:13:35 +0000
Subject: [docs] [issue13478] No documentation for timeit.default_timer
Message-ID: <1322208815.17.0.598781679655.issue13478@psf.upfronthosting.co.za>


New submission from Sandro Tosi <sandro.tosi at gmail.com>:

Hello,
timeit documentation doesn't mention default_timer, while the module exposes it publicly and there's code snippets on the web using it. It should be documented then.


ps: adding Georg to nosy as per Experts list

----------
assignee: docs at python
components: Documentation
messages: 148307
nosy: docs at python, georg.brandl, sandro.tosi
priority: normal
severity: normal
stage: needs patch
status: open
title: No documentation for timeit.default_timer
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13478>
_______________________________________

From report at bugs.python.org  Fri Nov 25 16:00:08 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 25 Nov 2011 15:00:08 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1322233208.53.0.636778099863.issue13402@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

This is the bug I was thinking about: #7774.  Adding some people from that discussion to nosy.

----------
nosy: +flox, haypo, pitrou, ronaldoussoren, schmir

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Fri Nov 25 16:22:09 2011
From: report at bugs.python.org (Silvan Jegen)
Date: Fri, 25 Nov 2011 15:22:09 +0000
Subject: [docs] [issue9708] cElementTree iterparse does not support "parser"
	argument
In-Reply-To: <1283032296.54.0.54816594665.issue9708@psf.upfronthosting.co.za>
Message-ID: <1322234528.94.0.959215612769.issue9708@psf.upfronthosting.co.za>


Silvan Jegen <s.jegen at gmail.com> added the comment:

I changed a few lines in the glue code of the _elementtree.c Module of Python 3.3.0a0 to add support for the "parser" argument. I do have to admit though that I am not familiar with the Python/C-API so this solution may not be ideal (i. e. it may be falling back to the Python implementation of iterparse without me realizing).

Please note that it is not possible to give an ElementTree.XMLParser instance as a parameter to the cElementTree.iterparse function (which may not be desirable in any case) using this patch.

I assume that the patch will be applicable to Python 2.7.x as well, but I did not try it. I can apply/adapt it to Python 2.7.x, if you think that would be useful.

----------
keywords: +patch
nosy: +Shugyousha
Added file: http://bugs.python.org/file23777/issue9708.Python330a0.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue9708>
_______________________________________

From report at bugs.python.org  Fri Nov 25 20:51:32 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Fri, 25 Nov 2011 19:51:32 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1322250692.25.0.319491621705.issue13402@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

LGTM too.
You could also add a test to test_sys ensuring that sys.executable is always executable.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Fri Nov 25 21:04:24 2011
From: report at bugs.python.org (STINNER Victor)
Date: Fri, 25 Nov 2011 20:04:24 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1321289437.84.0.982753479785.issue13402@psf.upfronthosting.co.za>
Message-ID: <1322251464.7.0.338952798709.issue13402@psf.upfronthosting.co.za>


STINNER Victor <victor.stinner at haypocalc.com> added the comment:

> You could also add a test to test_sys ensuring that sys.executable
> is always executable.

And that sys.executable is absolute?

sys.executable is an empty string if sys.argv[0] has been changed and Python is unable to retrieve the real path to the Python executable. See the issue #7774. The fact that sys.executable can be empty should be documented.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Fri Nov 25 21:11:41 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Fri, 25 Nov 2011 20:11:41 +0000
Subject: [docs] [issue13402] Document absoluteness of sys.executable
In-Reply-To: <1322251464.7.0.338952798709.issue13402@psf.upfronthosting.co.za>
Message-ID: <1322251603.3272.35.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> > You could also add a test to test_sys ensuring that sys.executable
> > is always executable.
> 
> And that sys.executable is absolute?

Er, yes, that's what I meant. Sorry.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13402>
_______________________________________

From report at bugs.python.org  Sat Nov 26 01:08:48 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 26 Nov 2011 00:08:48 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1322266128.44.0.41917762925.issue13433@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

I find the doc for g/G less than clear.

1. (main entry) "Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise."

'not less' means 'equal or greater', which to me is clearer. Even better and clearer to me would be "Uses decimal format if -4 <= exponent < precision, exponential format otherwise."


2. (note 4) "The precision determines the number of significant digits before and after the decimal point and defaults to 6."

>>> format(.001, 'g')
'0.001'

I only count 4, not 6.

Whoops, that is sort of documented, but in a really backwards way, by saying what the alternate form is. "The alternate form ... trailing zeroes are not removed as they would otherwise be."

>>> format(.001, '.3g')
'0.001'

Now I count 4, not 3.

3. (several notes) 'The alternate form'? I initially though this meant one of the two forms for g/G but then saw it used for other formats with just one form. It took too much searching to find the entry for '#', which I had never noticed before. Please expand to "The alternate '#' form" or add "(Alternate forms are selected by the '#' flag.)" after "Notes:".

I agree with C.I. that we could give some subtle emphasis that g/G treat precision differently. But the difference is more than just including the minimum 1 char before the decimal point in the precision.

>>> format(.001, 'f')
'0.001000'

----------
nosy: +terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 26 01:15:58 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 26 Nov 2011 00:15:58 +0000
Subject: [docs] [issue13436] compile() doesn't work on ImportFrom with
	level=None
In-Reply-To: <1321747479.31.0.688458511993.issue13436@psf.upfronthosting.co.za>
Message-ID: <1322266558.56.0.558920162624.issue13436@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

Does this apply to 2.7 as well?

I believe msg148146 is due to a commit message typo.

----------
nosy: +haypo, terry.reedy
versions: +Python 3.2, Python 3.3 -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13436>
_______________________________________

From report at bugs.python.org  Sat Nov 26 01:18:38 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 26 Nov 2011 00:18:38 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
In-Reply-To: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>
Message-ID: <1322266718.51.0.189888678198.issue13437@psf.upfronthosting.co.za>


Changes by Terry J. Reedy <tjreedy at udel.edu>:


----------
nosy: +terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Sat Nov 26 01:26:08 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 26 Nov 2011 00:26:08 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322267168.67.0.427650137439.issue13443@psf.upfronthosting.co.za>


Changes by Terry J. Reedy <tjreedy at udel.edu>:


----------
nosy: +terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Sat Nov 26 10:17:01 2011
From: report at bugs.python.org (Christian Iversen)
Date: Sat, 26 Nov 2011 09:17:01 +0000
Subject: [docs] [issue13433] String format documentation contains error
	regarding %g
In-Reply-To: <1321707692.58.0.601543510069.issue13433@psf.upfronthosting.co.za>
Message-ID: <1322299021.47.0.79408462963.issue13433@psf.upfronthosting.co.za>


Christian Iversen <ci at sikkerhed.org> added the comment:

Terry, the %g format always trims trailing zeroes, so you'd have to try with a number that doesn't end in zero.

I had to make a re-implementation of format for javascript:

http://paste.pocoo.org/show/513078/

If you look at the %g case, you can clearly see how much more complex and different it is, not that that itself indicates a bug. But it is different for sure :)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13433>
_______________________________________

From report at bugs.python.org  Sat Nov 26 14:04:05 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 26 Nov 2011 13:04:05 +0000
Subject: [docs] [issue13467] Typo in doc for library/sysconfig
In-Reply-To: <1322102306.14.0.426447482004.issue13467@psf.upfronthosting.co.za>
Message-ID: <1322312645.58.0.651313369297.issue13467@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks, I?ll fix this.

----------
assignee: docs at python -> eric.araujo
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13467>
_______________________________________

From report at bugs.python.org  Sat Nov 26 14:06:48 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sat, 26 Nov 2011 13:06:48 +0000
Subject: [docs] [issue13474] Mention of "-m" Flag Missing From Doc on
	Execution Model
In-Reply-To: <1322165458.97.0.989343856998.issue13474@psf.upfronthosting.co.za>
Message-ID: <1322312808.79.0.667399763603.issue13474@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

I guess you?re suggesting adding a mention of -m in the section near the top that says that a script file and code passed to -c are blocks?  Makes sense.  The same commit could also improve the markup to link to the description of script, -c and -m in using/cmdline.  (I think we have another doc bug open about cross-linking using/cmdline and other parts, but I don?t have the number at hand.)

----------
nosy: +eric.araujo, ncoghlan

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13474>
_______________________________________

From report at bugs.python.org  Sun Nov 27 01:03:47 2011
From: report at bugs.python.org (Arfrever Frehtes Taifersar Arahesis)
Date: Sun, 27 Nov 2011 00:03:47 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1322352227.72.0.218915410018.issue10318@psf.upfronthosting.co.za>


Changes by Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA at GMail.Com>:


----------
nosy: +Arfrever

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Sun Nov 27 01:21:44 2011
From: report at bugs.python.org (Julian Berman)
Date: Sun, 27 Nov 2011 00:21:44 +0000
Subject: [docs] [issue13437] Provide links to the source code for every
	module in the	documentation
In-Reply-To: <1321748971.83.0.182041155467.issue13437@psf.upfronthosting.co.za>
Message-ID: <1322353304.47.0.371102522026.issue13437@psf.upfronthosting.co.za>


Julian Berman <Julian+Python.org at GrayVines.com> added the comment:

Well, if there's opposition I don't know how strongly I feel about this then, but I generally agree with you Ezio, if there's an occasion where 1) applies fixing the docs is certainly reasonable. If I'm checking the source though, it's not necessarily since the documentation is unclear, just that it's often easier to read code than English.

But, I guess if no one else feels it'd be helpful feel free to close this then.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13437>
_______________________________________

From report at bugs.python.org  Sun Nov 27 06:01:50 2011
From: report at bugs.python.org (Shawn Ligocki)
Date: Sun, 27 Nov 2011 05:01:50 +0000
Subject: [docs] [issue13489] collections.Counter doc does not list added
	version
Message-ID: <1322370110.24.0.847856523325.issue13489@psf.upfronthosting.co.za>


New submission from Shawn Ligocki <sligocki at gmail.com>:

collections.Counter doc does not list added version:

http://docs.python.org/library/collections.html

It appears to only have been added in 2.7 (while the rest of the doc says it is valid since 2.4)

----------
assignee: docs at python
components: Documentation
messages: 148443
nosy: docs at python, sligocki
priority: normal
severity: normal
status: open
title: collections.Counter doc does not list added version
versions: Python 2.6, Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13489>
_______________________________________

From report at bugs.python.org  Sun Nov 27 06:18:25 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 27 Nov 2011 05:18:25 +0000
Subject: [docs] [issue13489] collections.Counter doc does not list added
	version
In-Reply-To: <1322370110.24.0.847856523325.issue13489@psf.upfronthosting.co.za>
Message-ID: <1322371105.19.0.0418949125885.issue13489@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

I see the note just after the sausage example and in the table at the top of the page, from the link you provided.

----------
nosy: +ezio.melotti
resolution:  -> invalid
stage:  -> committed/rejected
status: open -> closed
versions:  -Python 2.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13489>
_______________________________________

From report at bugs.python.org  Sun Nov 27 07:43:40 2011
From: report at bugs.python.org (Shawn Ligocki)
Date: Sun, 27 Nov 2011 06:43:40 +0000
Subject: [docs] [issue13489] collections.Counter doc does not list added
	version
In-Reply-To: <1322370110.24.0.847856523325.issue13489@psf.upfronthosting.co.za>
Message-ID: <1322376220.39.0.738602997173.issue13489@psf.upfronthosting.co.za>


Shawn Ligocki <sligocki at gmail.com> added the comment:

Ah, I see, it seems like that would be better suited directly after the section title, don't you?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13489>
_______________________________________

From report at bugs.python.org  Sun Nov 27 07:56:35 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 27 Nov 2011 06:56:35 +0000
Subject: [docs] [issue13489] collections.Counter doc does not list added
	version
In-Reply-To: <1322370110.24.0.847856523325.issue13489@psf.upfronthosting.co.za>
Message-ID: <1322376995.69.0.154408627167.issue13489@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

The convention is to put the note at the end of the section.  For this specific case the section about Counter is immediately followed by the documentation of its methods, so it's indeed hard to notice.  Maybe a different CSS would make this more evident.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13489>
_______________________________________

From report at bugs.python.org  Sun Nov 27 11:33:48 2011
From: report at bugs.python.org (Nebelhom)
Date: Sun, 27 Nov 2011 10:33:48 +0000
Subject: [docs] [issue13491] sqlite3 code adjustments
Message-ID: <1322390027.54.0.855055968281.issue13491@psf.upfronthosting.co.za>


New submission from Nebelhom <nebelhom at googlemail.com>:

The code examples for the sqlite3 library were in some cases non-functional.

With the help of Petri Lehtinen from core-mentorship, the following fixes are suggested.

NOTE: Last issue is not resolved yet, but suggestions have been made. Could you please review and decide what to do. The remaining issues have suggested fixes in the patch.

-------------------------------------------------------

Connection.create_function(name, num_params, func)

    Creates a user-defined function that you can later use from within SQL statements under the function name name. num_params is the number of parameters the function accepts, and func is a Python callable that is called as the SQL function.

    The function can return any of the types supported by SQLite: bytes, str, int, float and None.

    Example:

    import sqlite3
    import hashlib

    def md5sum(t):
        return hashlib.md5(t).hexdigest()

    con = sqlite3.connect(":memory:")
    con.create_function("md5", 1, md5sum)
    cur = con.cursor()
    cur.execute("select md5(?)", ("foo",))
    print(cur.fetchone()[0])

This script raises error:

Traceback (most recent call last):
  File "sqlexample.py", line 12, in <module>
    cur.execute("select md5(?)", ("foo",))
sqlite3.OperationalError: user-defined function raised exception

When md5sum is then run separately, the following traceback is given

>>> md5sum(("foo",))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "sqlexample.py", line 7, in md5sum
    return hashlib.md5(t).hexdigest()
TypeError: object supporting the buffer API required


Suggested fix:

Change ("foo") to (b"foo")

--------------------------------------------------------

Connection.text_factory?

    Using this attribute you can control what objects are returned for the TEXT data type. By default, this attribute is set to str and the sqlite3 module will return Unicode objects for TEXT. If you want to return bytestrings instead, you can set it to bytes.

    For efficiency reasons, there?s also a way to return str objects only for non-ASCII data, and bytes otherwise. To activate it, set this attribute to sqlite3.OptimizedUnicode.

    You can also set it to any other callable that accepts a single bytestring parameter and returns the resulting object.

    See the following example code for illustration:

    import sqlite3

    con = sqlite3.connect(":memory:")
    cur = con.cursor()

    # Create the table
    con.execute("create table person(lastname, firstname)")

    AUSTRIA = "\xd6sterreich"

    # by default, rows are returned as Unicode
    cur.execute("select ?", (AUSTRIA,))
    row = cur.fetchone()
    assert row[0] == AUSTRIA

    # but we can make sqlite3 always return bytestrings ...
    con.text_factory = str
    cur.execute("select ?", (AUSTRIA,))
    row = cur.fetchone()
    assert type(row[0]) == str
    # the bytestrings will be encoded in UTF-8, unless you stored garbage in the
    # database ...
    assert row[0] == AUSTRIA.encode("utf-8")

    # we can also implement a custom text_factory ...
    # here we implement one that will ignore Unicode characters that cannot be
    # decoded from UTF-8
    con.text_factory = lambda x: str(x, "utf-8", "ignore")
    cur.execute("select ?", ("this is latin1 and would normally create errors" +
                             "\xe4\xf6\xfc".encode("latin1"),))
    row = cur.fetchone()
    assert type(row[0]) == str

    # sqlite3 offers a built-in optimized text_factory that will return bytestring
    # objects, if the data is in ASCII only, and otherwise return unicode objects
    con.text_factory = sqlite3.OptimizedUnicode
    cur.execute("select ?", (AUSTRIA,))
    row = cur.fetchone()
    assert type(row[0]) == str

    cur.execute("select ?", ("Germany",))
    row = cur.fetchone()
    assert type(row[0]) == str

The code example returns the following error traceback

Traceback (most recent call last):
  File "sqlexample.py", line 23, in <module>
    assert row[0] == AUSTRIA.encode("utf-8")
AssertionError

Suggested fixes:
- #Create table... -> removed as not used
- all "assert type ... str" changed to "assert type ... bytes"
- # we can also implement... code block removed
- add ":meth:`[parameters]` needs to be a bytes type otherwise a TypeError will be raised." to the doc

-----------------------------------------------------------------------------
Cursor.executemany(sql, seq_of_parameters)

    Executes an SQL command against all parameter sequences or mappings found in the sequence sql. The sqlite3 module also allows using an iterator yielding parameters instead of a sequence.

    Here?s a shorter example using a generator:

    import sqlite3

    def char_generator():
        import string
        for c in string.letters[:26]:
            yield (c,)

    con = sqlite3.connect(":memory:")
    cur = con.cursor()
    cur.execute("create table characters(c)")

    cur.executemany("insert into characters(c) values (?)", char_generator())

    cur.execute("select c from characters")
    print(cur.fetchall())

Traceback (most recent call last):
  File "sqlexample.py", line 12, in <module>
    cur.executemany("insert into characters(c) values (?)", char_generator())
  File "sqlexample.py", line 5, in char_generator
    for c in string.letters[:26]:
AttributeError: 'module' object has no attribute 'letters'

suggested fixes
- import string outside function
- string.letters changed to string.ascii_letters_lowercase

-------------------------------------------------------------------------------

11.6.5.3. Converting SQLite values to custom Python types?

Writing an adapter lets you send custom Python types to SQLite. But to make it really useful we need to make the Python to SQLite to Python roundtrip work.

Enter converters.

Let?s go back to the Point class. We stored the x and y coordinates separated via semicolons as strings in SQLite.

First, we?ll define a converter function that accepts the string as a parameter and constructs a Point object from it.

Note

Converter functions always get called with a string, no matter under which data type you sent the value to SQLite.

def convert_point(s):
    x, y = map(float, s.split(";"))
    return Point(x, y)

Now you need to make the sqlite3 module know that what you select from the database is actually a point. There are two ways of doing this:

    * Implicitly via the declared type
    * Explicitly via the column name

Both ways are described in section Module functions and constants, in the entries for the constants PARSE_DECLTYPES and PARSE_COLNAMES.

The following example illustrates both approaches.

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return "(%f;%f)" % (self.x, self.y)

def adapt_point(point):
    return "%f;%f" % (point.x, point.y)

def convert_point(s):
    x, y = list(map(float, s.split(";")))
    return Point(x, y)

# Register the adapter
sqlite3.register_adapter(Point, adapt_point)

# Register the converter
sqlite3.register_converter("point", convert_point)

p = Point(4.0, -3.2)

#########################
# 1) Using declared types
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.cursor()
cur.execute("create table test(p point)")

cur.execute("insert into test(p) values (?)", (p,))
cur.execute("select p from test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

#######################
# 1) Using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(p)")

cur.execute("insert into test(p) values (?)", (p,))
cur.execute('select p as "p [point]" from test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

The given code gives the following error:

Traceback (most recent call last):
  File "sqlexample.py", line 32, in <module>
    cur.execute("select p from test")
  File "sqlexample.py", line 14, in convert_point
    x, y = list(map(float, s.split(";")))
TypeError: Type str doesn't support the buffer API

suggested fixes:

def adapt_point(point):
   return ("%f;%f" % (point.x, point.y)).encode('ascii')

def convert_point(s):
   x, y = list(map(float, s.split(b";")))
   return Point(x, y)

------------------------------------------------------------------------------

11.6.7.2. Accessing columns by name instead of by index?

One useful feature of the sqlite3 module is the built-in sqlite3.Row class designed to be used as a row factory.

Rows wrapped with this class can be accessed both by index (like tuples) and case-insensitively by name:

import sqlite3

con = sqlite3.connect("mydb")
con.row_factory = sqlite3.Row

cur = con.cursor()
cur.execute("select name_last, age from people")
for row in cur:
    assert row[0] == row["name_last"]
    assert row["name_last"] == row["nAmE_lAsT"]
    assert row[1] == row["age"]
    assert row[1] == row["AgE"]

Gives following error:

Traceback (most recent call last):
  File "sqlexample.py", line 7, in <module>
    cur.execute("select name_last, age from people")
sqlite3.OperationalError: no such table: people

"Same error in 11.6.3 Cursor.execute() description"

Suggested fixes:
- None yet. I feel these should be standalone examples out of the box. the sqlite3 includes have a "createdb.py" file which would create the tablem but it is not referenced in the documentary. I do not know the reasoning behind this, but I would like to have standalone examples in these cases.

----------
assignee: docs at python
components: Documentation
files: sqlite_code_update.patch
keywords: patch
messages: 148448
nosy: Nebelhom, docs at python
priority: normal
severity: normal
status: open
title: sqlite3 code adjustments
versions: Python 3.3
Added file: http://bugs.python.org/file23793/sqlite_code_update.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13491>
_______________________________________

From report at bugs.python.org  Mon Nov 28 00:55:01 2011
From: report at bugs.python.org (A.M. Kuchling)
Date: Sun, 27 Nov 2011 23:55:01 +0000
Subject: [docs] [issue13443] wrong links and examples in the functional HOWTO
In-Reply-To: <1321850404.45.0.767133152656.issue13443@psf.upfronthosting.co.za>
Message-ID: <1322438101.35.0.713724350459.issue13443@psf.upfronthosting.co.za>


A.M. Kuchling <lists at amk.ca> added the comment:

Yes, linking to the functional module was to point people to a module that might be useful, even if it's not in the stdlib.  A numeric processing or socket handling HOWTO would also pretty much have to link to non-stdlib sources.  The purpose of documentation is to be useful to the reader, so I think if linking to something external would be reasonably useful, we should do it.

Another motivation for linking was to provide alternative explanations; if the reader finds the Functional HOWTO boring or too superficial or too complicated, maybe an alternative discussion like Mertz's "Text Processing" will fit their brain better.  (At least until those alternative sources become so outdated that they're useless...)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13443>
_______________________________________

From report at bugs.python.org  Mon Nov 28 15:01:09 2011
From: report at bugs.python.org (Mark Dickinson)
Date: Mon, 28 Nov 2011 14:01:09 +0000
Subject: [docs] [issue13494] 'cast' any value to a Boolean?
Message-ID: <1322488868.96.0.430179402239.issue13494@psf.upfronthosting.co.za>


New submission from Mark Dickinson <dickinsm at gmail.com>:

Docs nit:  at http://docs.python.org/dev/library/stdtypes.html#boolean-values we have

"""
The built-in function bool() can be used to cast any value to a Boolean ...
"""

It's a little unusual to talk about casting in Python.  Any objections to replacing 'cast' with 'convert'?

----------
assignee: docs at python
components: Documentation
messages: 148480
nosy: docs at python, mark.dickinson
priority: normal
severity: normal
status: open
title: 'cast' any value to a Boolean?
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13494>
_______________________________________

From report at bugs.python.org  Mon Nov 28 15:02:16 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 28 Nov 2011 14:02:16 +0000
Subject: [docs] [issue13494] 'cast' any value to a Boolean?
In-Reply-To: <1322488868.96.0.430179402239.issue13494@psf.upfronthosting.co.za>
Message-ID: <1322488936.84.0.862474836788.issue13494@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

+1

----------
nosy: +ezio.melotti
stage:  -> needs patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13494>
_______________________________________

From report at bugs.python.org  Mon Nov 28 15:37:08 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 28 Nov 2011 14:37:08 +0000
Subject: [docs] [issue10318] "make altinstall" installs many files with
	incorrect	shebangs
In-Reply-To: <1288926610.35.0.932494150274.issue10318@psf.upfronthosting.co.za>
Message-ID: <1322491028.45.0.79992607693.issue10318@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Can I removed the shebangs in the 3.3 stdlib or do I need to go through with the PEP 8 patch on python-dev first?

----------
versions:  -Python 2.7, Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10318>
_______________________________________

From report at bugs.python.org  Mon Nov 28 16:04:08 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 28 Nov 2011 15:04:08 +0000
Subject: [docs] [issue13491] Fixes for sqlite3 doc
In-Reply-To: <1322390027.54.0.855055968281.issue13491@psf.upfronthosting.co.za>
Message-ID: <1322492648.72.0.621901435496.issue13491@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

It is very helpful that you review the docs.  Some obvious fixes were made when moving to Python 3 (print, etc.) but apparently the examples were not run.  Sphinx can let us run the code blocks in reST files as doctests, but it is currently not done because the docs are built with a Python 2 version.

I have reviewed your patch on our code review tool; I did not check your message (a patch is much easier :).

> I feel these should be standalone examples out of the box. the sqlite3 includes have a
> "createdb.py" file which would create the tables but it is not referenced in the
> documenta[tion]. I do not know the reasoning behind this, but I would like to have standalone
> examples in these cases.

I think the examples do not stand alone because their author wanted to create and populate a database with many entries, to demonstrate querying, and it was easier to write one script once than to either clutter the examples with long table creation code or having examples with so few rows that it would not be realistic/interesting.  To help people wanting to run the examples in the docs, we could explain that createdb.py needs to be run first.

The createdb script and other sqlite3 doc examples were added when sqlite3 was added in Python 2.5; I?m adding the module author and then-doc lead (hi Gerhard and Fred), maybe they can shed more light on this.

----------
nosy: +eric.araujo, fdrake, ghaering, petri.lehtinen
title: sqlite3 code adjustments -> Fixes for sqlite3 doc
versions: +Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13491>
_______________________________________

From report at bugs.python.org  Mon Nov 28 16:32:27 2011
From: report at bugs.python.org (Meador Inge)
Date: Mon, 28 Nov 2011 15:32:27 +0000
Subject: [docs] [issue13494] 'cast' any value to a Boolean?
In-Reply-To: <1322488868.96.0.430179402239.issue13494@psf.upfronthosting.co.za>
Message-ID: <1322494347.23.0.588335551056.issue13494@psf.upfronthosting.co.za>


Meador Inge <meadori at gmail.com> added the comment:

+1

----------
nosy: +meador.inge

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13494>
_______________________________________

From report at bugs.python.org  Mon Nov 28 17:05:04 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Mon, 28 Nov 2011 16:05:04 +0000
Subject: [docs] [issue12832] The documentation for the print function
	should	explain/point to how to control the sys.stdout encoding
In-Reply-To: <1314191894.1.0.666645625262.issue12832@psf.upfronthosting.co.za>
Message-ID: <1322496303.96.0.303846070038.issue12832@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks for the patch.  It was reviewed on our code review tool; if you did not get an email (there are glitches), follow the link on the right of your patch in the list of files.

----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12832>
_______________________________________

From skidbladnir at pyrohawk.com  Fri Nov 25 06:44:49 2011
From: skidbladnir at pyrohawk.com (Travis DePrato)
Date: Thu, 24 Nov 2011 23:44:49 -0600
Subject: [docs] Incorrect pickle Documentation
Message-ID: <CAFzWFoWR3dxndK-q2u-W04sV7vd2xd8hPJKy0AYQvd1ckP2joA@mail.gmail.com>

Pickle, by default, uses the ascii encoding, but it is changeable.
 However, this is not mentioned in the documentation.  (The option is
pickle.pickle(obj, encoding="utf8") and I'm not sure if it is present in
other functions/classes in the pickle module)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111124/e07d5025/attachment.html>

From report at bugs.python.org  Mon Nov 28 19:54:19 2011
From: report at bugs.python.org (Stefan Behnel)
Date: Mon, 28 Nov 2011 18:54:19 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322506459.35.0.757622498929.issue11379@psf.upfronthosting.co.za>


Stefan Behnel <scoder at users.sourceforge.net> added the comment:

Ok, so, what do we make of this? I proposed improvements to the wording in the documentation, which make it much clearer for users what they are buying into when they start using minidom. I still think that "factually correct" but clearly misleading documentation is not helpful and that it needs fixing. Here is an updated phrasing that I hope we can settle on:

"""
:mod:`xml.dom.minidom` --- Pure Python DOM implementation

[...]

:mod:`xml.dom.minidom` is a pure Python implementation of the Document Object Model interface, as known from other programming languages. It is intended to provide a smaller and simpler API than the full W3C DOM.

Note that MiniDOM has a several times larger memory footprint than :mod:`xml.etree.ElementTree`, the light-weight Python XML library in the standard library. If you do not need a (mostly) compliant W3C DOM implementation, but a fast and memory friendly XML tree implementation with an easy to learn API, use that instead.
"""

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 03:43:48 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 29 Nov 2011 02:43:48 +0000
Subject: [docs] [issue13494] 'cast' any value to a Boolean?
In-Reply-To: <1322488868.96.0.430179402239.issue13494@psf.upfronthosting.co.za>
Message-ID: <1322534627.93.0.868198292393.issue13494@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

'bool' is just one of many conversion functions that convert their argument to the type they designate. Does this doc problem only exist for 'bool' or also for 'int', 'float' and others?

----------
nosy: +eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13494>
_______________________________________

From report at bugs.python.org  Tue Nov 29 07:12:10 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 29 Nov 2011 06:12:10 +0000
Subject: [docs] [issue11001] Various obvious errors in cookies documentation
In-Reply-To: <1295908065.55.0.221906287574.issue11001@psf.upfronthosting.co.za>
Message-ID: <1322547130.02.0.839085623057.issue11001@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
keywords: +easy
nosy: +petri.lehtinen
stage:  -> patch review
versions: +Python 3.3 -Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11001>
_______________________________________

From report at bugs.python.org  Tue Nov 29 07:32:40 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 29 Nov 2011 06:32:40 +0000
Subject: [docs] [issue1040439] Missing documentation on How To Link With
	libpython
Message-ID: <1322548360.01.0.79238913189.issue1040439@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy:  -BreamoreBoy
stage:  -> needs patch
versions: +Python 2.7, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 08:30:33 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 29 Nov 2011 07:30:33 +0000
Subject: [docs] [issue1040439] Missing documentation on How To Link With
	libpython
Message-ID: <1322551833.02.0.0314362584592.issue1040439@psf.upfronthosting.co.za>


Changes by Eli Bendersky <eliben at gmail.com>:


----------
nosy: +eli.bendersky

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 14:05:48 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 29 Nov 2011 13:05:48 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322571947.99.0.425607072672.issue11379@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Is memory footprint something important enough to put in the doc?  Ease of use is IMO more important, but then it becomes subjective..

----------
nosy: +eric.araujo

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 14:39:50 2011
From: report at bugs.python.org (Stefan Behnel)
Date: Tue, 29 Nov 2011 13:39:50 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322573990.15.0.344504923607.issue11379@psf.upfronthosting.co.za>


Stefan Behnel <scoder at users.sourceforge.net> added the comment:

I find a factor of an order of magnitude worth mentioning, because it prevents certain kinds of usages.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 14:41:14 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 29 Nov 2011 13:41:14 +0000
Subject: [docs] [issue9196] Improve docs for string interpolation "%s" re
	Unicode	strings
In-Reply-To: <1278572830.17.0.148747735024.issue9196@psf.upfronthosting.co.za>
Message-ID: <1322574074.29.0.0239596275808.issue9196@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

More info on this thread: http://mail.python.org/pipermail/python-dev/2006-December/070237.html

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue9196>
_______________________________________

From report at bugs.python.org  Tue Nov 29 14:42:03 2011
From: report at bugs.python.org (R. David Murray)
Date: Tue, 29 Nov 2011 13:42:03 +0000
Subject: [docs] [issue13498] os.makedirs exist_ok documentation is incorrect,
	as is some of the behavior
Message-ID: <1322574123.12.0.756700598965.issue13498@psf.upfronthosting.co.za>


New submission from R. David Murray <rdmurray at bitdance.com>:

The documentation for os.makedirs says:

  If the target directory with the same mode as specified already exists, raises an OSError exception if exist_ok is False, otherwise no exception is raised.

This is not correct.  If the file exists but the mode is different than that specified (or defaulted) after applying the umask, then an error is raised regardless of the value of exist_ok.  The above wording also implies that if the directory exists but has a different mode, that the mode will be changed.  Again, this is not what the code does.

It's not clear how useful this raise behavior is, but reading the original issue that added this option it is clearly intentional.  The documented behavior does seem useful, but if it actually reset the mode that would be a fairly significant behavior change, and would not be a good idea if the user had not specified a mode.  However, at the very least exists_ok should not raise if no mode was specified in the call.

The error message raised is also wrong in this case, since it says that the error is that the file already exists when we've said that that is OK.  A custom error message for this case would be better.

----------
assignee: docs at python
components: Documentation, Library (Lib)
keywords: easy
messages: 148564
nosy: docs at python, r.david.murray
priority: normal
severity: normal
stage: needs patch
status: open
title: os.makedirs exist_ok documentation is incorrect, as is some of the behavior
type: behavior
versions: Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13498>
_______________________________________

From report at bugs.python.org  Tue Nov 29 14:46:54 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 29 Nov 2011 13:46:54 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322574414.38.0.328404703738.issue11379@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

Usually we don't talk about performance in the doc, and in my personal experience I didn't notice any major difference between the different implementations (but than again I haven't used them much).
Talking about the other implementations and their advantages/disadvantages is fine, but things like "MiniDOM has a several times larger memory footprint" seems like FUD to me (see also http://docs.python.org/dev/documenting/style.html#affirmative-tone).

----------
nosy: +ezio.melotti

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 14:49:08 2011
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Tue, 29 Nov 2011 13:49:08 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322574548.83.0.103950845174.issue11379@psf.upfronthosting.co.za>


Fred L. Drake, Jr. <fred at fdrake.net> added the comment:

Removing "Lightweight" and changing the first paragraph to (something like)

:mod:`xml.dom.minidom` is an implementation of the Document Object Model
interface.  The API is slightly simpler than the full W3C DOM, but the
implementation has a significantly higher memory footprint than
:mod:`xml.dom.etree`.

would be entirely reasonable.

(I don't think it's wrong to discuss relative memory footprints in comparison to other modules in the standard library.)

----------
nosy: +fdrake

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 15:05:05 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 29 Nov 2011 14:05:05 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322575505.82.0.151090701844.issue1040439@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

I did not found all these Google hist.  Most of the links on the first page for ?link libpython? are bug reports which are rejected by maintainers.  Related: http://mail.python.org/pipermail/python-dev/2006-February/060549.html

So, what do people link with libpython for?

----------
nosy: +eric.araujo
title: Missing documentation on How To Link With libpython -> Missing documentation on how to link with libpython

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 15:12:25 2011
From: report at bugs.python.org (Stefan Behnel)
Date: Tue, 29 Nov 2011 14:12:25 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322575945.15.0.823673439388.issue11379@psf.upfronthosting.co.za>


Stefan Behnel <scoder at users.sourceforge.net> added the comment:

I don't think "FUD" is a suitable term for the rather minidom-friendly wording in my last proposal. Seriously, minidom is widely known for being extremely slow and extremely memory hungry. And that is backed by basically any benchmark that has ever been done on the subject. If 4DOM, which Martin cites, is really worse in terms of performance (I never used it), it must truly be the only existing species of that kind.

Still, here's a cleaned up version of Fred's proposal that I could live with:

"""
:mod:`xml.dom.minidom` --- Pure Python DOM implementation

:mod:`xml.dom.minidom` is an implementation of the Document Object Model interface.  The API is (intentionally) slightly simpler than the full W3C DOM, but the implementation has a significantly higher memory footprint than the XML tree library in :mod:`xml.etree.ElementTree`.
"""

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 15:13:37 2011
From: report at bugs.python.org (Petri Lehtinen)
Date: Tue, 29 Nov 2011 14:13:37 +0000
Subject: [docs] [issue13499] uuid documentation example uses invalid
	REPL/doctest	syntax
Message-ID: <1322576016.96.0.843898665466.issue13499@psf.upfronthosting.co.za>


New submission from Petri Lehtinen <petri at digip.org>:

See http://docs.python.org/library/uuid.html#example.

Comments are output lines, i.e. not prefixed with >>>, which breaks the ">>>" button that makes the example copy-pasteable.

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 148571
nosy: docs at python, petri.lehtinen
priority: normal
severity: normal
status: open
title: uuid documentation example uses invalid REPL/doctest syntax
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13499>
_______________________________________

From report at bugs.python.org  Tue Nov 29 15:14:31 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 14:14:31 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1322575945.15.0.823673439388.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322575767.3292.0.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> I don't think "FUD" is a suitable term for the rather minidom-friendly
> wording in my last proposal. Seriously, minidom is widely known for
> being extremely slow and extremely memory hungry. And that is backed
> by basically any benchmark that has ever been done on the subject.

If it's both slow and memory-hungry, perhaps use the more generic
"performance" instead of "memory footprint"?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 15:44:29 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 29 Nov 2011 14:44:29 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322577869.86.0.916744711715.issue1040439@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

?ric, this is for embedding a Python interpreter in a C/C++ application. I tend to agree that the official doc page (http://docs.python.org/extending/embedding.html) on this topic is somewhat lacking in the area of the configuration/compilation procedure. There's some info scattered around the web in tutorials, though.

So I'd say it's a valid issue.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 16:26:35 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 29 Nov 2011 15:26:35 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322580395.84.0.75986901515.issue11379@psf.upfronthosting.co.za>


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> Seriously, minidom is widely known for being extremely slow and 
> extremely memory hungry. And that is backed by basically any benchmark 
> that has ever been done on the subject.

Do you have any link?
My point is that if you say thing like "significantly/several times higher memory footprint than X" you are basically scaring the users away from the module.  If for an average documents it takes, say, 30-50MB of memory, it seems perfectly reasonable to me, even if ElementTree takes 3-5MB.  I would actually consider 100-200MB still ok too, unless I have to parse lot of documents or I'm running low of memory for other reasons.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 16:33:05 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 15:33:05 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1322580395.84.0.75986901515.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322580480.3292.7.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> My point is that if you say thing like "significantly/several times
> higher memory footprint than X" you are basically scaring the users
> away from the module.

Only those users who know they'll be processing significantly large
documents.
I don't think "scaring away people" is a good enough reason *not* to
document performance characteristics. For example, we already mention
that string joining is faster than repeated concatenation; I haven't
heard anyone complain that it scared people away from string
concatenation. And while it's true that we shouldn't try to document
performance characteristics *too precisely*, it is still a good thing to
document the most outstanding facts (for examples, C accelerator modules
are clearly superior in performance to pure Python modules; should we
shy away from documenting that, and instead present it as some kind of
neutral choice?).

And, of course, if minidom gets some serious performance attention, the
claims will have to be revisited. But given the amount of attention
minidom gets at all, it sounds rather implausible.

> If for an average documents it takes, say, 30-50MB of memory, it seems
> perfectly reasonable to me, even if ElementTree takes 3-5MB.  I would
> actually consider 100-200MB still ok too

Some use cases would not really like a 100-200MB memory consumption, or
even 50MB. Think a long-running daemon, for instance.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 17:15:07 2011
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 29 Nov 2011 16:15:07 +0000
Subject: [docs] [issue13467] Typo in doc for library/sysconfig
In-Reply-To: <1322102306.14.0.426447482004.issue13467@psf.upfronthosting.co.za>
Message-ID: <E1RVQKn-0001IU-QZ@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset a7d38a969132 by ?ric Araujo in branch '3.2':
Fix typo (#13467)
http://hg.python.org/cpython/rev/a7d38a969132

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13467>
_______________________________________

From report at bugs.python.org  Tue Nov 29 17:18:09 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 29 Nov 2011 16:18:09 +0000
Subject: [docs] [issue13467] Typo in doc for library/sysconfig
In-Reply-To: <1322102306.14.0.426447482004.issue13467@psf.upfronthosting.co.za>
Message-ID: <1322583489.61.0.0281132133409.issue13467@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Done for 3.2 and 3.3, will backport to 2.7 later.

----------
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13467>
_______________________________________

From report at bugs.python.org  Tue Nov 29 17:26:23 2011
From: report at bugs.python.org (Stefan Behnel)
Date: Tue, 29 Nov 2011 16:26:23 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1322580395.84.0.75986901515.issue11379@psf.upfronthosting.co.za>
Message-ID: <4ED507A2.5000004@users.sourceforge.net>


Stefan Behnel <scoder at users.sourceforge.net> added the comment:

Ezio Melotti, 29.11.2011 16:26:
>> Seriously, minidom is widely known for being extremely slow and
>> extremely memory hungry. And that is backed by basically any benchmark
>> that has ever been done on the subject.
>
> Do you have any link?

I just did a quick Google search for "python minidom benchmark" and found 
these:

http://www.opensourcetutorials.com/tutorials/Server-Side-Coding/Python/xml-matters/page2.html

http://effbot.org/zone/celementtree.htm#benchmarks

http://blog.ianbicking.org/2008/03/30/python-html-parser-performance/

Note that all three authors risk being biased, but given how similar the 
results are, I tend to believe them.

Stefan

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 17:45:18 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 16:45:18 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <4ED507A2.5000004@users.sourceforge.net>
Message-ID: <1322584811.3292.8.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> I just did a quick Google search for "python minidom benchmark" and found 
> these:
> 
> http://www.opensourcetutorials.com/tutorials/Server-Side-Coding/Python/xml-matters/page2.html
> 
> http://effbot.org/zone/celementtree.htm#benchmarks
> 
> http://blog.ianbicking.org/2008/03/30/python-html-parser-performance/
> 
> Note that all three authors risk being biased, but given how similar the 
> results are, I tend to believe them.

Thanks for the links. The performance gap looks significant enough to be
mentioned, at least generically.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 18:37:48 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 17:37:48 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322588268.86.0.288784549722.issue1040439@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

There is (outdated, incomplete and clumsy) documentation about using distutils.sysconfig from the command-line. I'll try to work on a small patch. It will probably be Unix-only, though.

----------
nosy: +pitrou

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 19:04:14 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 18:04:14 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322589854.57.0.707804233468.issue1040439@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

Attached patch rewrites the offending paragraphs.

----------
keywords: +patch
stage: needs patch -> patch review
Added file: http://bugs.python.org/file23807/docembed.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 19:16:21 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 18:16:21 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322590580.96.0.709804112969.issue1040439@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

Updated markup.

----------
Added file: http://bugs.python.org/file23808/docembed.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 19:16:32 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 18:16:32 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322590592.01.0.976778501009.issue1040439@psf.upfronthosting.co.za>


Changes by Antoine Pitrou <pitrou at free.fr>:


Removed file: http://bugs.python.org/file23807/docembed.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 19:29:43 2011
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 29 Nov 2011 18:29:43 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322591383.74.0.354358502098.issue1040439@psf.upfronthosting.co.za>


Eli Bendersky <eliben at gmail.com> added the comment:

Antoine, this is a big improvement - LGTM.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Tue Nov 29 20:02:16 2011
From: report at bugs.python.org (Stefan Behnel)
Date: Tue, 29 Nov 2011 19:02:16 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322593336.53.0.81931729438.issue11379@psf.upfronthosting.co.za>


Stefan Behnel <scoder at users.sourceforge.net> added the comment:

Given that the links were generally somewhat dated and used Py2.x instead of the post-PEP393 Py3.3, here is another little benchmark, comparing the parser performance of minidom to lxml.etree (latest), ElementTree and cElementTree (stdlib) in a recent Py3.3 build (e66b7c62eec0), everything properly optimised for my platform (Linux 64bit). I used os.fork() to start a new process after importing everything and reading the file a couple of times, and before parsing. The memory usage is measured inside of the forked child using the resource module's ru_maxrss value, so it correlates with the growth of CPython's memory heap after parsing, thus giving an estimate of the maximum amount of memory used during parsing and tree building.

Parsing hamlet.xml in English, 274KB:

Memory usage: 7284
xml.etree.ElementTree.parse done in 0.104 seconds
Memory usage: 14240 (+6956)
xml.etree.cElementTree.parse done in 0.022 seconds
Memory usage: 9736 (+2452)
lxml.etree.parse done in 0.014 seconds
Memory usage: 11028 (+3744)
minidom tree read in 0.152 seconds
Memory usage: 30360 (+23076)

Parsing the old testament in English (ot.xml, 3.4MB) into memory:

Memory usage: 20444
xml.etree.ElementTree.parse done in 0.385 seconds
Memory usage: 46088 (+25644)
xml.etree.cElementTree.parse done in 0.056 seconds
Memory usage: 32628 (+12184)
lxml.etree.parse done in 0.041 seconds
Memory usage: 37500 (+17056)
minidom tree read in 0.672 seconds
Memory usage: 110428 (+89984)

A 25MB XML file with Slavic Unicode text content:

Memory usage: 57368
xml.etree.ElementTree.parse done in 3.274 seconds
Memory usage: 223720 (+166352)
xml.etree.cElementTree.parse done in 0.459 seconds
Memory usage: 154012 (+96644)
lxml.etree.parse done in 0.454 seconds
Memory usage: 135720 (+78352)
minidom tree read in 6.193 seconds
Memory usage: 604860 (+547492)

And a contrived 4.5MB XML file with lot more structure than data:

Memory usage: 13308
xml.etree.ElementTree.parse done in 4.178 seconds
Memory usage: 222088 (+208780)
xml.etree.cElementTree.parse done in 0.478 seconds
Memory usage: 103056 (+89748)
lxml.etree.parse done in 0.199 seconds
Memory usage: 101860 (+88552)
minidom tree read in 8.705 seconds
Memory usage: 810964 (+797656)

Things to note: The factor of 5-10 for the memory overhead compared to cET depends heavily on the data. Also, minidom is consistently slower by more than a factor of 10 compared to the fastest parser (apparently the one in libxml2/lxml.etree, both of which surely can't be said to provide less features than the DOM that minidom implements).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 20:27:38 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Tue, 29 Nov 2011 19:27:38 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322594858.72.0.401107266361.issue11379@psf.upfronthosting.co.za>


Changes by Florent Xicluna <florent.xicluna at gmail.com>:


----------
nosy: +flox
type:  -> performance

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 20:28:06 2011
From: report at bugs.python.org (Florent Xicluna)
Date: Tue, 29 Nov 2011 19:28:06 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322594886.08.0.419793660697.issue11379@psf.upfronthosting.co.za>


Changes by Florent Xicluna <florent.xicluna at gmail.com>:


----------
components: +XML

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 20:57:27 2011
From: report at bugs.python.org (Stefan Behnel)
Date: Tue, 29 Nov 2011 19:57:27 +0000
Subject: [docs] [issue11379] Remove "lightweight" from minidom description
In-Reply-To: <1299093908.17.0.828802315354.issue11379@psf.upfronthosting.co.za>
Message-ID: <1322596647.5.0.369930925821.issue11379@psf.upfronthosting.co.za>


Stefan Behnel <scoder at users.sourceforge.net> added the comment:

Hmm, looks like I messed up the last example. I accidentally left in the formatting whitespace, thus growing the file to 6.2 MB. Removing that, I get this for the (now really) 4.5 MB XML file with lots of structure and very little data:

Memory usage: 11600
xml.etree.ElementTree.parse done in 3.374 seconds
Memory usage: 203420 (+191820)
xml.etree.cElementTree.parse done in 0.192 seconds
Memory usage: 36444 (+24844)
lxml.etree.parse done in 0.131 seconds
Memory usage: 62648 (+51048)
minidom tree read in 5.935 seconds
Memory usage: 527684 (+516084)

It's actually surprising how much of a difference trailing whitespace content makes in minidom (from 2MB on disk to 300MB in memory???), most likely due to the usage of dedicated DOM text nodes in the tree.

PS: I think the "XML/performance" tags on this bug would hint at a separate ticket. This is really meant as a documentation bug.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________

From report at bugs.python.org  Tue Nov 29 21:45:16 2011
From: report at bugs.python.org (R. David Murray)
Date: Tue, 29 Nov 2011 20:45:16 +0000
Subject: [docs] [issue13502] Documentation for Event.wait return value is
	either	wrong or incomplete
Message-ID: <1322599516.14.0.0239672713193.issue13502@psf.upfronthosting.co.za>


New submission from R. David Murray <rdmurray at bitdance.com>:

The documentation for Event.wait says:

  This method returns the internal flag on exit, so it will always return True except if a timeout is given and the operation times out.

In fact, however, if the thread that sets the flag immediately clears it, wait will return False.  Antoine looking at the code says that this appears to be intentional, and that would make sense since originally wait returned no value.

My use case is one thread waiting on another to complete a work loop.  Normally the worker thread goes to sleep after clearing the flag, but sometimes it immediately starts a new work loop.  In either case I want the monitoring loop to take an action when the work loop completes, and raise an error if the wait times out.  It looked to me like Event.wait would work in the scenario.

----------
assignee: docs at python
components: Documentation
messages: 148604
nosy: docs at python, pitrou, r.david.murray, tim_one
priority: normal
severity: normal
stage: needs patch
status: open
title: Documentation for Event.wait return value is either wrong or incomplete
type: behavior
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13502>
_______________________________________

From report at bugs.python.org  Tue Nov 29 21:50:57 2011
From: report at bugs.python.org (R. David Murray)
Date: Tue, 29 Nov 2011 20:50:57 +0000
Subject: [docs] [issue13502] Documentation for Event.wait return value is
	either	wrong or incomplete
In-Reply-To: <1322599516.14.0.0239672713193.issue13502@psf.upfronthosting.co.za>
Message-ID: <1322599857.5.0.788259659048.issue13502@psf.upfronthosting.co.za>


R. David Murray <rdmurray at bitdance.com> added the comment:

Thinking about it, if the flag's state if the wait does not expire is not guaranteed to be True, then what I really need is some way to know, when the wait call completes, whether or not it terminated because of a timeout or not.  I can always query the value of the flag separately if its value can in any case be changed by another thread.

I am perhaps using the wrong tool, I'll have to look at the docs further.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13502>
_______________________________________

From report at bugs.python.org  Tue Nov 29 21:55:54 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 29 Nov 2011 20:55:54 +0000
Subject: [docs] [issue13502] Documentation for Event.wait return value is
	either	wrong or incomplete
In-Reply-To: <1322599516.14.0.0239672713193.issue13502@psf.upfronthosting.co.za>
Message-ID: <1322600154.01.0.466604364798.issue13502@psf.upfronthosting.co.za>


Antoine Pitrou <pitrou at free.fr> added the comment:

Ok, so digging a bit, the feature dates back to issue1674032. 
Interestingly, the OP in that issue had already envisioned that race condition and had precisely proposed the feature to avoid it: ?Note that in the above case, the event could be cleared between the return from x.wait and the execution of x.isSet (in another thread), and so this would operate as though x.wait had just timed out?.

So I'm changing my mind and saying it seems desireable to return True if the wait succeeded before the timeout's end, even though the flag may have been reset in the meantime.
In 3.2, Condition.wait also returns a boolean, meaning the check in Event.wait can be atomic.

----------
nosy: +neologix

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13502>
_______________________________________

From report at bugs.python.org  Tue Nov 29 22:00:44 2011
From: report at bugs.python.org (R. David Murray)
Date: Tue, 29 Nov 2011 21:00:44 +0000
Subject: [docs] [issue13502] Event.wait sometimes returns False even when no
	timeout	has occurred
In-Reply-To: <1322599516.14.0.0239672713193.issue13502@psf.upfronthosting.co.za>
Message-ID: <1322600443.98.0.00911991237771.issue13502@psf.upfronthosting.co.za>


R. David Murray <rdmurray at bitdance.com> added the comment:

Changing the title and component to reflect Antoine's new understanding :)

----------
components: +Library (Lib) -Documentation
title: Documentation for Event.wait return value is either wrong or incomplete -> Event.wait sometimes returns False even when no timeout has occurred

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13502>
_______________________________________

From report at bugs.python.org  Tue Nov 29 22:43:27 2011
From: report at bugs.python.org (Shawn Ligocki)
Date: Tue, 29 Nov 2011 21:43:27 +0000
Subject: [docs] [issue13489] collections.Counter doc does not list added
	version
In-Reply-To: <1322370110.24.0.847856523325.issue13489@psf.upfronthosting.co.za>
Message-ID: <1322603006.91.0.31084203182.issue13489@psf.upfronthosting.co.za>


Shawn Ligocki <sligocki at gmail.com> added the comment:

It doesn't seem like the styling is the issue, but the placement. You say that the standard style is to put this at the end of the section, is there somewhere it would be appropriate to bring this up for discussion? I think it would be much more intuitive if it was always placed right after the section name.

----------
keywords: +patch
Added file: http://bugs.python.org/file23811/collections.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13489>
_______________________________________

From report at bugs.python.org  Tue Nov 29 23:08:42 2011
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 29 Nov 2011 22:08:42 +0000
Subject: [docs] [issue13489] collections.Counter doc does not list added
	version
In-Reply-To: <1322370110.24.0.847856523325.issue13489@psf.upfronthosting.co.za>
Message-ID: <1322604522.05.0.559578813968.issue13489@psf.upfronthosting.co.za>


Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

FWIW, the version added is also prominently shown at the top of the page:
http://docs.python.org/library/collections.html#module-collections

I don't think the CSS should be changed or that versionadded should become more prominent -- this is usually one of the least important parts of the documentation for a function or class.

----------
nosy: +rhettinger

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13489>
_______________________________________

From report at bugs.python.org  Wed Nov 30 04:59:36 2011
From: report at bugs.python.org (Zachary Richey)
Date: Wed, 30 Nov 2011 03:59:36 +0000
Subject: [docs] [issue12832] The documentation for the print function
	should	explain/point to how to control the sys.stdout encoding
In-Reply-To: <1314191894.1.0.666645625262.issue12832@psf.upfronthosting.co.za>
Message-ID: <1322625575.95.0.418725543545.issue12832@psf.upfronthosting.co.za>


Zachary Richey <mach1723 at gmail.com> added the comment:

I've reworded the patch and fixed the issues in the patch pointed out by eric.araujo.

----------
Added file: http://bugs.python.org/file23815/functions_print_doc_2.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12832>
_______________________________________

From report at bugs.python.org  Wed Nov 30 08:44:31 2011
From: report at bugs.python.org (=?utf-8?q?Charles-Fran=C3=A7ois_Natali?=)
Date: Wed, 30 Nov 2011 07:44:31 +0000
Subject: [docs] [issue13502] Documentation for Event.wait return value is
	either	wrong or incomplete
In-Reply-To: <1322600154.01.0.466604364798.issue13502@psf.upfronthosting.co.za>
Message-ID: <CAH_1eM3GhXAMbwD+__3ojjdXF5yMVf54QwyD3BjkS5j4t59vug@mail.gmail.com>


Charles-Fran?ois Natali <neologix at free.fr> added the comment:

> So I'm changing my mind and saying it seems desireable to return True if the wait succeeded before the timeout's end, even though the flag may have been reset in the meantime.

Agreed. What matters is that the event has been signaled, not that
it's currently signaled.

----------
title: Event.wait sometimes returns False even when no timeout has occurred -> Documentation for Event.wait return value is either wrong or incomplete

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13502>
_______________________________________

From report at bugs.python.org  Wed Nov 30 16:25:09 2011
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Wed, 30 Nov 2011 15:25:09 +0000
Subject: [docs] [issue12832] The documentation for the print function
	should	explain/point to how to control the sys.stdout encoding
In-Reply-To: <1314191894.1.0.666645625262.issue12832@psf.upfronthosting.co.za>
Message-ID: <1322666709.15.0.533641376377.issue12832@psf.upfronthosting.co.za>


?ric Araujo <merwok at netwok.org> added the comment:

Thanks.  Here?s another take: I think the wording is better, but it?s longer.  I removed the reference to sys.stdin, which you don?t print to: I haven?t checked if the doc for the input function should talk about the encoding too.

----------
assignee: docs at python -> eric.araujo
Added file: http://bugs.python.org/file23818/print-encoding.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12832>
_______________________________________

From report at bugs.python.org  Wed Nov 30 18:42:30 2011
From: report at bugs.python.org (Peter Otten)
Date: Wed, 30 Nov 2011 17:42:30 +0000
Subject: [docs] [issue13510] Clarify that readlines() is not needed to
	iterate over a	file
Message-ID: <1322674949.97.0.856520026774.issue13510@psf.upfronthosting.co.za>


New submission from Peter Otten <__peter__ at web.de>:

I've been looking at code on the tutor mailing list for some time, and

for line in file.readlines(): ...

is a common idiom there. I suppose this is because the readlines() method is easily discoverable while the proper way (iterate over the file object directly) is not.

A note added to the readlines() documentation might help:

"""
You don't need the readlines() method to loop over the lines of a file.
for line in file: process(line)
consumes less memory and is often faster.
"""

----------
assignee: docs at python
components: Documentation
messages: 148679
nosy: docs at python, potten
priority: normal
severity: normal
status: open
title: Clarify that readlines() is not needed to iterate over a file
type: feature request

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13510>
_______________________________________

From report at bugs.python.org  Wed Nov 30 19:09:19 2011
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 30 Nov 2011 18:09:19 +0000
Subject: [docs] [issue13510] Clarify that readlines() is not needed to
	iterate over a	file
In-Reply-To: <1322674949.97.0.856520026774.issue13510@psf.upfronthosting.co.za>
Message-ID: <1322676559.39.0.545668181969.issue13510@psf.upfronthosting.co.za>


Changes by Ezio Melotti <ezio.melotti at gmail.com>:


----------
nosy: +eric.araujo, ezio.melotti
stage:  -> needs patch
versions: +Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13510>
_______________________________________

From report at bugs.python.org  Wed Nov 30 21:25:11 2011
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 30 Nov 2011 20:25:11 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <E1RVqiM-0006Dx-EG@dinsdale.python.org>


Roundup Robot <devnull at psf.upfronthosting.co.za> added the comment:

New changeset 2c05b8a6cdd1 by Antoine Pitrou in branch '3.2':
Issue #1040439: better document how to compile and link an embedded Python interpreter.
http://hg.python.org/cpython/rev/2c05b8a6cdd1

New changeset 528abe272856 by Antoine Pitrou in branch 'default':
Issue #1040439: better document how to compile and link an embedded Python interpreter.
http://hg.python.org/cpython/rev/528abe272856

----------
nosy: +python-dev

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Wed Nov 30 21:38:59 2011
From: report at bugs.python.org (Ray)
Date: Wed, 30 Nov 2011 20:38:59 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
Message-ID: <1322685539.27.0.844666346033.issue1040439@psf.upfronthosting.co.za>


Ray <rpqpro at hotmail.com> added the comment:

I think mentioning that you can export CFLAGS and LDFLAGS would be particularly useful.  I was able to compile some of the missing packages that were deemed 'missing' at the end of 'make' by updating setup.py and having CFLAGS and LDFLAGS point to the desired packages' directories...  Unfortunately for linux, the ability to specify *multiple* lib/ and include/ paths using this method is currently not available unless you modify setup.py.  I opened a ticket in relation to this: Issue13511 if anyone cares.

----------
nosy: +rpq

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Wed Nov 30 21:48:01 2011
From: report at bugs.python.org (Antoine Pitrou)
Date: Wed, 30 Nov 2011 20:48:01 +0000
Subject: [docs] [issue1040439] Missing documentation on how to link with
	libpython
In-Reply-To: <1322685539.27.0.844666346033.issue1040439@psf.upfronthosting.co.za>
Message-ID: <1322685774.3512.4.camel@localhost.localdomain>


Antoine Pitrou <pitrou at free.fr> added the comment:

> I think mentioning that you can export CFLAGS and LDFLAGS would be
> particularly useful.  I was able to compile some of the missing
> packages that were deemed 'missing' at the end of 'make' by updating
> setup.py and having CFLAGS and LDFLAGS point to the desired packages'
> directories...

Unless I'm missing something, this is slightly off-topic for this issue,
which is about using Python as an embedded interpreter, not compiling
it. Embedding Python assumes it has already been built.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue1040439>
_______________________________________

From report at bugs.python.org  Wed Nov 30 23:54:26 2011
From: report at bugs.python.org (Terry J. Reedy)
Date: Wed, 30 Nov 2011 22:54:26 +0000
Subject: [docs] [issue13510] Clarify that readlines() is not needed to
	iterate over a	file
In-Reply-To: <1322674949.97.0.856520026774.issue13510@psf.upfronthosting.co.za>
Message-ID: <1322693666.58.0.787455210926.issue13510@psf.upfronthosting.co.za>


Terry J. Reedy <tjreedy at udel.edu> added the comment:

This current line is
"Read and return a list of lines from the stream. hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint."

I would like to see added
"Since a file is a line iterator, file.readlines() == list(file). To save time and space, iterate over lines of a file with for line in file: process(line)."
(with code markup for the two snippets).

----------
nosy: +terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13510>
_______________________________________

From bill.murphy at oracle.com  Tue Nov 29 22:49:14 2011
From: bill.murphy at oracle.com (bill murphy)
Date: Tue, 29 Nov 2011 14:49:14 -0700
Subject: [docs] slight bug in the docs
Message-ID: <4ED5535A.1040700@oracle.com>


Hi,

I'm not sure if this is a version difference, or simply a bug in the docs.

Here's what your docs say: 
(http://docs.python.org/release/2.3.5/tut/node5.html)

>>>  # Integer division returns the floor:
... 7/3


Here's what python on my machine says:

C:\waggle\qa\server_auto>python
Python 3.2.2 (default, Sep  4 2011, 09:51:08) [MSC v.1500 32 bit 
(Intel)] on win
32
Type "help", "copyright", "credits" or "license" for more information.
 >>> 7/3
2.3333333333333335

Seems not to be integer division going on... Though I'm not at all clear 
if this is my particular version, or some configuration thing.

--Bill