From report at bugs.python.org  Wed May  1 04:23:13 2013
From: report at bugs.python.org (Kyle Roberts)
Date: Wed, 01 May 2013 02:23:13 +0000
Subject: [docs] [issue15984] Wrong documentation for PyUnicode_FromObject()
	and	PyUnicode_FromEncodedObject()
In-Reply-To: <1348157907.35.0.947782583816.issue15984@psf.upfronthosting.co.za>
Message-ID: <1367374993.02.0.329691791268.issue15984@psf.upfronthosting.co.za>


Kyle Roberts added the comment:

I've uploaded a new patch with the obj argument properly marked up. Brian, I think *obj* is what we want based on other examples in that file. It looks like italics is typically used when discussing parameters since each parameter is italicized in the signature.

R.David and Serhiy, I thought about the use of "coercion" some more and I think the current wording is fine. "Type coercion/conversion" is a commonly used phrase with some languages, so I think the phrase is applicable here as well (for a python example: http://docs.python.org/release/2.5.2/ref/coercion-rules.html). Let me know if you'd still like to see it changed. Thanks.

----------
Added file: http://bugs.python.org/file30086/from_object_v2.patch

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

From report at bugs.python.org  Wed May  1 08:34:48 2013
From: report at bugs.python.org (anatoly techtonik)
Date: Wed, 01 May 2013 06:34:48 +0000
Subject: [docs] [issue17887] docs: summary page - generator vs iterator vs
	iterable
Message-ID: <1367390087.97.0.0883934646573.issue17887@psf.upfronthosting.co.za>


New submission from anatoly techtonik:

Docs lack a good summary page comparing three concepts. The main question is how do I tell if something is a sequence, generator, iterator or iterable? I found myself puzzled that range() is neither generator or iterator.

----------
assignee: docs at python
components: Documentation
messages: 188203
nosy: docs at python, techtonik
priority: normal
severity: normal
status: open
title: docs: summary page - generator vs iterator vs iterable

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

From report at bugs.python.org  Wed May  1 13:13:20 2013
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 01 May 2013 11:13:20 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <3b0xmb6SCJz7LjZ@mail.python.org>


Roundup Robot added the comment:

New changeset d1aa8a9eba44 by Ezio Melotti in branch '2.7':
#16518: fix links in glossary entry.
http://hg.python.org/cpython/rev/d1aa8a9eba44

----------

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

From report at bugs.python.org  Wed May  1 13:40:59 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 01 May 2013 11:40:59 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367408459.06.0.27015617379.issue16518@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

The attached patch replaces things like "object that support the buffer protocol/interface/API" with "bytes-like objects" throughout the docs.
The patch doesn't change error messages/docstrings.

I also noticed that on 2.7[0], the section about the buffer protocol in Doc/c-api/buffer.rst is called "Buffers and Memoryview Objects" and it's not as clear as the one on 3.x[1].  Should this section be backported?

[0]: http://docs.python.org/2.7/c-api/buffer.html#bufferobjects
[1]: http://docs.python.org/dev/c-api/buffer.html#bufferobjects

----------
Added file: http://bugs.python.org/file30089/issue16518-2.diff

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

From report at bugs.python.org  Wed May  1 13:42:15 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Wed, 01 May 2013 11:42:15 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1367408459.06.0.27015617379.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367408532.2541.0.camel@fsol>


Antoine Pitrou added the comment:

> I also noticed that on 2.7[0], the section about the buffer protocol
> in Doc/c-api/buffer.rst is called "Buffers and Memoryview Objects" and
> it's not as clear as the one on 3.x[1].  Should this section be
> backported?

The "buffer protocol" situation is different on 2.x, please let's
concentrate on 3.x :-)

----------

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

From report at bugs.python.org  Wed May  1 14:34:31 2013
From: report at bugs.python.org (Thomas Fenzl)
Date: Wed, 01 May 2013 12:34:31 +0000
Subject: [docs] [issue17841] Remove missing aliases from codecs documentation
In-Reply-To: <1366878629.86.0.715834730144.issue17841@psf.upfronthosting.co.za>
Message-ID: <1367411671.85.0.201343624452.issue17841@psf.upfronthosting.co.za>


Thomas Fenzl added the comment:

This is a documentation patch against 3.3 with the aliases removed.

----------
keywords: +patch
nosy: +Thomas Fenzl
Added file: http://bugs.python.org/file30091/issue17841_codecs_docu.patch

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

From report at bugs.python.org  Wed May  1 14:44:05 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 01 May 2013 12:44:05 +0000
Subject: [docs] [issue13515] Consistent documentation practices for security
	concerns	and considerations
In-Reply-To: <1322726017.57.0.923133254266.issue13515@psf.upfronthosting.co.za>
Message-ID: <1367412245.21.0.653804330933.issue13515@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Attached a patch that includes the section proposed by Nick in the first message.  I also changed "in-line text" with "a note" as suggested in msg148720.  I didn't specify a "ReST note" because I think that depending on the situation, an actual warning, a note, or even an in-line text might be acceptable.

----------
components: +Devguide -Documentation
stage: needs patch -> patch review
Added file: http://bugs.python.org/file30092/issue13515-devguide.diff

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

From report at bugs.python.org  Wed May  1 14:44:50 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 01 May 2013 12:44:50 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1367412290.62.0.304569792953.issue14097@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

If there aren't any comments I will commit this soon.

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

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

From report at bugs.python.org  Wed May  1 14:55:14 2013
From: report at bugs.python.org (anatoly techtonik)
Date: Wed, 01 May 2013 12:55:14 +0000
Subject: [docs] [issue17888] docs: more information on documentation team
Message-ID: <1367412914.06.0.588625037016.issue17888@psf.upfronthosting.co.za>


New submission from anatoly techtonik:

To help people understand that they can actually improve Python docs themselves, how about the following changes:

http://docs.python.org/3/bugs.html - rename from "Reporting Bugs" to "Dealing with Bugs".

Explain that sometimes fixing bug is easier than reporting, because it involves less time from all people in total. Link to step-by-step documentation for the process and include channel for proposals how to make the process more streamlined.

Add links to archive and docs at python.org mailing list info
http://mail.python.org/mailman/listinfo/docs

On this info page make it clear that "Python documentation team" is not a team in common narrow sense, but a group of volunteers open for everybody. Either by providing a link to team page with listed members, or by replacing the text:
- "Mailing list for the Python documentation team"
+ "Mailing list for people collaborating on Python docs"

----------
assignee: docs at python
components: Documentation
messages: 188218
nosy: docs at python, techtonik
priority: normal
severity: normal
status: open
title: docs: more information on documentation team

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

From report at bugs.python.org  Wed May  1 14:57:25 2013
From: report at bugs.python.org (Georg Brandl)
Date: Wed, 01 May 2013 12:57:25 +0000
Subject: [docs] [issue17888] docs: more information on documentation team
In-Reply-To: <1367412914.06.0.588625037016.issue17888@psf.upfronthosting.co.za>
Message-ID: <1367413045.37.0.518904808295.issue17888@psf.upfronthosting.co.za>


Georg Brandl added the comment:

Sounds good, please prepare a patch.

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

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

From report at bugs.python.org  Wed May  1 15:00:52 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 01 May 2013 13:00:52 +0000
Subject: [docs] [issue17888] docs: more information on documentation team
In-Reply-To: <1367412914.06.0.588625037016.issue17888@psf.upfronthosting.co.za>
Message-ID: <1367413252.89.0.789868113939.issue17888@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/issue17888>
_______________________________________

From report at bugs.python.org  Wed May  1 15:16:31 2013
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 01 May 2013 13:16:31 +0000
Subject: [docs] [issue17529] fix os.sendfile() documentation regarding the
	type of	file descriptor
In-Reply-To: <1364040887.67.0.333340627096.issue17529@psf.upfronthosting.co.za>
Message-ID: <3b10Vl1FT3zSPZ@mail.python.org>


Roundup Robot added the comment:

New changeset 4f45f9cde9b4 by Charles-Francois Natali in branch '3.3':
Issue #17529: Fix os.sendfile() documentation regarding the type of file
http://hg.python.org/cpython/rev/4f45f9cde9b4

New changeset 538055b28ba6 by Charles-Francois Natali in branch 'default':
Issue #17529: Fix os.sendfile() documentation regarding the type of file
http://hg.python.org/cpython/rev/538055b28ba6

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

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

From report at bugs.python.org  Wed May  1 15:17:36 2013
From: report at bugs.python.org (=?utf-8?q?Charles-Fran=C3=A7ois_Natali?=)
Date: Wed, 01 May 2013 13:17:36 +0000
Subject: [docs] [issue17529] fix os.sendfile() documentation regarding the
	type of	file descriptor
In-Reply-To: <1364040887.67.0.333340627096.issue17529@psf.upfronthosting.co.za>
Message-ID: <1367414256.43.0.468329075976.issue17529@psf.upfronthosting.co.za>


Changes by Charles-Fran?ois Natali <cf.natali at gmail.com>:


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

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

From report at bugs.python.org  Wed May  1 15:57:11 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 01 May 2013 13:57:11 +0000
Subject: [docs] [issue16523] attrgetter and itemgetter signatures in docs
	need cleanup
In-Reply-To: <1353510966.46.0.566270540705.issue16523@psf.upfronthosting.co.za>
Message-ID: <1367416631.45.0.805655457752.issue16523@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Attached an updated patch that uses the double signature.

----------
stage: patch review -> commit review
versions:  -Python 3.2
Added file: http://bugs.python.org/file30093/issue16523-2.diff

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

From report at bugs.python.org  Wed May  1 16:51:50 2013
From: report at bugs.python.org (anatoly techtonik)
Date: Wed, 01 May 2013 14:51:50 +0000
Subject: [docs] [issue17888] docs: more information on documentation team
In-Reply-To: <1367412914.06.0.588625037016.issue17888@psf.upfronthosting.co.za>
Message-ID: <1367419909.97.0.254550633534.issue17888@psf.upfronthosting.co.za>


anatoly techtonik added the comment:

May take a few days.

----------

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

From report at bugs.python.org  Wed May  1 16:58:13 2013
From: report at bugs.python.org (Kyle Roberts)
Date: Wed, 01 May 2013 14:58:13 +0000
Subject: [docs] [issue17282] document the defaultTest parameter to
	unittest.main()
In-Reply-To: <1361664894.83.0.085559336561.issue17282@psf.upfronthosting.co.za>
Message-ID: <1367420293.33.0.507325463366.issue17282@psf.upfronthosting.co.za>


Changes by Kyle Roberts <robertskyl at gmail.com>:


----------
keywords: +patch
Added file: http://bugs.python.org/file30096/default_test_3.4.patch

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

From report at bugs.python.org  Wed May  1 17:00:14 2013
From: report at bugs.python.org (Kyle Roberts)
Date: Wed, 01 May 2013 15:00:14 +0000
Subject: [docs] [issue17282] document the defaultTest parameter to
	unittest.main()
In-Reply-To: <1361664894.83.0.085559336561.issue17282@psf.upfronthosting.co.za>
Message-ID: <1367420414.67.0.563212457849.issue17282@psf.upfronthosting.co.za>


Kyle Roberts added the comment:

I've uploaded a patch documenting defaultTest in the latest branch and also in the previous branches.

----------
nosy: +kyle.roberts
Added file: http://bugs.python.org/file30097/default_test_2.7-3.3.patch

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

From report at bugs.python.org  Wed May  1 18:31:15 2013
From: report at bugs.python.org (R. David Murray)
Date: Wed, 01 May 2013 16:31:15 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1367425875.36.0.676267214237.issue14097@psf.upfronthosting.co.za>


R. David Murray added the comment:

Review comments added.

----------
nosy: +r.david.murray

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

From zachary.ware at gmail.com  Wed May  1 19:35:03 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Wed, 01 May 2013 17:35:03 -0000
Subject: [docs] attrgetter and itemgetter signatures in docs need cleanup
	(issue 16523)
Message-ID: <20130501173503.26820.1711@psf.upfronthosting.co.za>

Just a couple of nitpicks :)


http://bugs.python.org/review/16523/diff/8043/Doc/library/operator.rst
File Doc/library/operator.rst (right):

http://bugs.python.org/review/16523/diff/8043/Doc/library/operator.rst#newcode265
Doc/library/operator.rst:265: returns ``(r.name.first, r.name.last)``.
I think either the two semicolons should also be periods, or all three
punctuation marks should just be removed (and probably lower-case After,
as well) since it is a bulleted list.  Same applies to itemgetter and
methodcaller.

http://bugs.python.org/review/16523/diff/8043/Doc/library/operator.rst#newcode267
Doc/library/operator.rst:267: The function is equivalent to::
I think it is a little misleading to call attrgetter, itemgetter, and
methodcaller "functions" here.  They don't do anything that couldn't be
done with a function, and they do try to look like functions (without
going to extremes), but they are implemented as classes and, as such,
will tell you what they are if you use type() on them.  I don't think
that the ".. function:: ..." line should be changed to  class, because
that would change the way they are displayed and actually call them
classes, which also wouldn't be good, but I think the ambiguity of the
old wording ("Equivalent to::") was a good way to go.  It's not exactly
true, anyway, as there are some corner cases that these examples gloss
over, so maybe "Basically equivalent to::" or similar would be better.

http://bugs.python.org/review/16523/

From report at bugs.python.org  Wed May  1 19:38:35 2013
From: report at bugs.python.org (Zachary Ware)
Date: Wed, 01 May 2013 17:38:35 +0000
Subject: [docs] [issue16523] attrgetter and itemgetter signatures in docs
	need cleanup
In-Reply-To: <1353510966.46.0.566270540705.issue16523@psf.upfronthosting.co.za>
Message-ID: <1367429915.6.0.152431733694.issue16523@psf.upfronthosting.co.za>


Zachary Ware added the comment:

I left a couple of Rietveld comments.  Other than those nitpicks it looks good to me, and I could be convinced otherwise on the nitpicks :)

Also, thanks for catching the extra commas after the "After"s in operator.rst; I had meant to include those in the same patch that took them out of _operator.c, but apparently I missed it.

----------
nosy: +zach.ware

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

From report at bugs.python.org  Thu May  2 12:22:43 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Thu, 02 May 2013 10:22:43 +0000
Subject: [docs] [issue17851] Grammar errors in threading.Lock documentation
In-Reply-To: <1367038556.41.0.738438135734.issue17851@psf.upfronthosting.co.za>
Message-ID: <1367490163.63.0.703487417596.issue17851@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/issue17851>
_______________________________________

From report at bugs.python.org  Thu May  2 14:38:08 2013
From: report at bugs.python.org (Yogesh Chaudhari)
Date: Thu, 02 May 2013 12:38:08 +0000
Subject: [docs] [issue17871] Wrong signature of TextTestRunner's init
	function
In-Reply-To: <1367269592.44.0.115946830805.issue17871@psf.upfronthosting.co.za>
Message-ID: <1367498288.0.0.721188987085.issue17871@psf.upfronthosting.co.za>


Yogesh Chaudhari added the comment:

The changes in Docs/library/unittest.rst have been made to reflect proper arguments from Lib/unittest/runner.py

----------
keywords: +patch
nosy: +Yogesh.Chaudhari
Added file: http://bugs.python.org/file30106/mywork.patch

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

From report at bugs.python.org  Thu May  2 14:50:37 2013
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 02 May 2013 12:50:37 +0000
Subject: [docs] [issue1722] Undocumented urllib functions
In-Reply-To: <1199298780.6.0.893928826633.issue1722@psf.upfronthosting.co.za>
Message-ID: <3b1btN0G7cz7LjY@mail.python.org>


Roundup Robot added the comment:

New changeset c3656dca65e7 by Senthil Kumaran in branch '2.7':
# 1722 - Add a note on urllib helper functions like splittype, splithost etc.
http://hg.python.org/cpython/rev/c3656dca65e7

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

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

From report at bugs.python.org  Thu May  2 14:53:37 2013
From: report at bugs.python.org (Senthil Kumaran)
Date: Thu, 02 May 2013 12:53:37 +0000
Subject: [docs] [issue1722] Undocumented urllib functions
In-Reply-To: <1199298780.6.0.893928826633.issue1722@psf.upfronthosting.co.za>
Message-ID: <1367499217.0.0.26681155849.issue1722@psf.upfronthosting.co.za>


Senthil Kumaran added the comment:

I had added a note in the documentation  c3656dca65e7 conveying that splittype, splithost should not be relied upon, and urlparse should be used for parsing. Also, Python3 does not include these in __all__ - It is in Python2 for backwards compatibility purposes. It is not possible provide deprecation warning to things we leave off from __all__ from subsequent versions of python.
I consider this request as resolved. Thanks!

----------
resolution:  -> fixed
status: open -> closed
versions:  -Python 3.1, Python 3.2

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

From report at bugs.python.org  Thu May  2 15:26:29 2013
From: report at bugs.python.org (Richard Oudkerk)
Date: Thu, 02 May 2013 13:26:29 +0000
Subject: [docs] [issue17805] No such class: multiprocessing.pool.AsyncResult
In-Reply-To: <1366494249.42.0.0654021028594.issue17805@psf.upfronthosting.co.za>
Message-ID: <1367501189.72.0.878593465822.issue17805@psf.upfronthosting.co.za>


Richard Oudkerk added the comment:

It might be simplest to make the implementation match the docs by making AsyncResult an alias for ApplyResult.

----------

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

From report at bugs.python.org  Thu May  2 23:20:30 2013
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 02 May 2013 21:20:30 +0000
Subject: [docs] [issue15984] Wrong documentation for PyUnicode_FromObject()
	and	PyUnicode_FromEncodedObject()
In-Reply-To: <1348157907.35.0.947782583816.issue15984@psf.upfronthosting.co.za>
Message-ID: <1367529630.14.0.267714524218.issue15984@psf.upfronthosting.co.za>


Changes by STINNER Victor <victor.stinner at gmail.com>:


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

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

From report at bugs.python.org  Fri May  3 04:04:55 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 03 May 2013 02:04:55 +0000
Subject: [docs] [issue17546] Document the circumstances where the locals()
	dict get	updated
In-Reply-To: <1364232011.36.0.2936348393.issue17546@psf.upfronthosting.co.za>
Message-ID: <1367546695.08.0.420595391761.issue17546@psf.upfronthosting.co.za>


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


----------
nosy: +ncoghlan
stage: needs patch -> patch review

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

From report at bugs.python.org  Fri May  3 04:11:52 2013
From: report at bugs.python.org (Ned Batchelder)
Date: Fri, 03 May 2013 02:11:52 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
Message-ID: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>


New submission from Ned Batchelder:

I find the explanations in the Descriptor howto to be difficult to understand.  I took a stab at changing the first few sections to introduce the concepts in an easier-to-grasp style.

Issue 12077 also covers a little bit of this.

----------
assignee: docs at python
components: Documentation
files: descriptor_howto.patch
keywords: patch
messages: 188289
nosy: docs at python, nedbat
priority: normal
severity: normal
status: open
title: Edits to descriptor howto
versions: Python 3.4
Added file: http://bugs.python.org/file30111/descriptor_howto.patch

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

From report at bugs.python.org  Fri May  3 11:47:26 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Fri, 03 May 2013 09:47:26 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
In-Reply-To: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>
Message-ID: <1367574446.54.0.504774965593.issue17894@psf.upfronthosting.co.za>


Changes by Raymond Hettinger <raymond.hettinger at gmail.com>:


----------
assignee: docs at python -> rhettinger
nosy: +rhettinger
priority: normal -> low

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

From report at bugs.python.org  Fri May  3 11:48:34 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Fri, 03 May 2013 09:48:34 +0000
Subject: [docs] [issue12077] Harmonizing descriptor protocol documentation
In-Reply-To: <1305381385.94.0.81554539251.issue12077@psf.upfronthosting.co.za>
Message-ID: <1367574514.06.0.656402374002.issue12077@psf.upfronthosting.co.za>


Changes by Raymond Hettinger <raymond.hettinger at gmail.com>:


----------
assignee:  -> rhettinger
priority: normal -> low

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

From report at bugs.python.org  Fri May  3 17:16:41 2013
From: report at bugs.python.org (R. David Murray)
Date: Fri, 03 May 2013 15:16:41 +0000
Subject: [docs] [issue15984] Wrong documentation for PyUnicode_FromObject()
	and	PyUnicode_FromEncodedObject()
In-Reply-To: <1348157907.35.0.947782583816.issue15984@psf.upfronthosting.co.za>
Message-ID: <1367594201.57.0.289006300652.issue15984@psf.upfronthosting.co.za>


R. David Murray added the comment:

Well, while 'coercion' does refer to changing from one type to another, and technically we are doing that here, in OO we generally think of subclasses as more-or-less being of the same type as the superclass.  So I think it would be clearer to spell out that we are changing the object type to be that of the superclass.

----------

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

From report at bugs.python.org  Fri May  3 18:38:43 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Fri, 03 May 2013 16:38:43 +0000
Subject: [docs] [issue17860] subprocess docs lack info how to use output
	result
In-Reply-To: <1367159799.26.0.456231833917.issue17860@psf.upfronthosting.co.za>
Message-ID: <1367599123.57.0.721096475596.issue17860@psf.upfronthosting.co.za>


Changes by Tshepang Lekhonkhobe <tshepang at gmail.com>:


----------
nosy: +tshepang

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

From report at bugs.python.org  Fri May  3 18:44:10 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Fri, 03 May 2013 16:44:10 +0000
Subject: [docs] [issue17888] docs: more information on documentation team
In-Reply-To: <1367412914.06.0.588625037016.issue17888@psf.upfronthosting.co.za>
Message-ID: <1367599450.72.0.687213232941.issue17888@psf.upfronthosting.co.za>


Changes by Tshepang Lekhonkhobe <tshepang at gmail.com>:


----------
nosy: +tshepang

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

From report at bugs.python.org  Fri May  3 19:24:22 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 03 May 2013 17:24:22 +0000
Subject: [docs] [issue15984] Wrong documentation for PyUnicode_FromObject()
	and	PyUnicode_FromEncodedObject()
In-Reply-To: <1348157907.35.0.947782583816.issue15984@psf.upfronthosting.co.za>
Message-ID: <1367601862.28.0.345548190036.issue15984@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

In other languages usually the world "coercion" is used for implicit conversion, i.e. int->long, int->float, float->complex. str->unicode in Python 2 (that's what PyUnicode_FromObject() does). But the last conversion is not supported in Python 3. The term "coercion" has also been used in Python 2 in the narrow sense (see the __coerce__() method), and in this sense Python 3 does not support "coercion". Therefore, I believe that it is better to avoid the use of this term.

----------

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

From report at bugs.python.org  Fri May  3 20:41:12 2013
From: report at bugs.python.org (Ned Batchelder)
Date: Fri, 03 May 2013 18:41:12 +0000
Subject: [docs] [issue12077] Harmonizing descriptor protocol documentation
In-Reply-To: <1305381385.94.0.81554539251.issue12077@psf.upfronthosting.co.za>
Message-ID: <1367606472.99.0.753361980567.issue12077@psf.upfronthosting.co.za>


Changes by Ned Batchelder <ned at nedbatchelder.com>:


----------
nosy: +nedbat

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

From report at bugs.python.org  Fri May  3 22:44:10 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 03 May 2013 20:44:10 +0000
Subject: [docs] [issue17854] symmetric difference operation applicable to
	more than	two sets
In-Reply-To: <1367063240.22.0.643670001227.issue17854@psf.upfronthosting.co.za>
Message-ID: <1367613850.37.0.736891281413.issue17854@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Sets have methods that do not have operators (such as len, isdisjoint),
operators that do not have non-special methods (such as in, <), and method-operator pairs that do the same thing (such as (union, |), (symmetric_difference, ^)). For the pairs, it gives the method signature and the *equivalent* operator expression. Since .union takes multiple 'other' args, the equivalent operator expression does too. Since .symmetric_difference only takes one 'other' arg, so does the expression.

A coherent proposal would change the method code and doc to the following:

symmetric_difference(other, ...)
set ^ other ^ ...
    Return a new set with elements in an odd number of the sets.

s={1,2, 5}
t={2,3, 5}
u={3,4, 5}
print(s^t^u)
>>> 
{1, 4, 5}

I believe the proposal was once considered, and rejected. An argument for is that the effect of chained symmetric differences is not obvious, as evidenced by Amit's mistaken characterization. I had to think a bit before I was sure of the answer. An argument against is that what one actually gets is seldom wanted, so that allowing more than two inputs to the method would have little benefit. 

What might be done is to document the symmetric different of multiple sets with a parenthetical comment such as

"(The symmetric difference of multiple sets, a ^ b ^ c ^ ..., is a new set with elements appearing in an odd number of input sets.)"

This would let people know what to expect from such expressions, in a situation where the effect is less obvious than usual.

----------
nosy: +rhettinger, terry.reedy
stage:  -> patch review
versions: +Python 2.7, Python 3.4

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

From report at bugs.python.org  Fri May  3 22:56:18 2013
From: report at bugs.python.org (Aaron Oakley)
Date: Fri, 03 May 2013 20:56:18 +0000
Subject: [docs] [issue17902] Document that _elementtree C API cannot use
	custom	TreeBuilder for iterparse or IncrementalParser
Message-ID: <1367614578.64.0.34953241054.issue17902@psf.upfronthosting.co.za>


New submission from Aaron Oakley:

It would really help to document that the C API can only use the default xml.etree.ElementTree.TreeBuilder for targets with iterparse (and by extension, IncrementalParser).

I got a nice surprise about that when I went from 3.2 to 3.3 and started getting "TypeError: event handling only supported for ElementTree.TreeBuilder targets".

I included a patch to add notes to iterparse and IncrementalParser, but I'm not sure what to refer to the C module as since xml.etree.cElementTree is deprecated.

----------
assignee: docs at python
components: Documentation, XML
files: elementtree.rst-340a0.patch
keywords: patch
messages: 188329
nosy: Aaron.Oakley, docs at python
priority: normal
severity: normal
status: open
title: Document that _elementtree C API cannot use custom TreeBuilder for iterparse or IncrementalParser
type: behavior
versions: Python 3.4
Added file: http://bugs.python.org/file30119/elementtree.rst-340a0.patch

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

From report at bugs.python.org  Sat May  4 01:24:55 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Fri, 03 May 2013 23:24:55 +0000
Subject: [docs] [issue17902] Document that _elementtree C API cannot use
	custom	TreeBuilder for iterparse or IncrementalParser
In-Reply-To: <1367614578.64.0.34953241054.issue17902@psf.upfronthosting.co.za>
Message-ID: <1367623495.95.0.730283436867.issue17902@psf.upfronthosting.co.za>


Changes by Antoine Pitrou <pitrou at free.fr>:


----------
nosy: +eli.bendersky
stage:  -> patch review
versions: +Python 3.3

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

From report at bugs.python.org  Sat May  4 01:42:01 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 03 May 2013 23:42:01 +0000
Subject: [docs] [issue17887] docs: summary page - generator vs iterator vs
	iterable
In-Reply-To: <1367390087.97.0.0883934646573.issue17887@psf.upfronthosting.co.za>
Message-ID: <1367624521.32.0.89480795063.issue17887@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Briefly,
An iterable is an object that can be iterated with an iterator.
An iterator is an iterable that responds to next() calls, including the implicit calls in a for statement.
A generator is an iterator created by a generator function, which is a function with a yield keyword in its body.
A sequence is an iterable with minimal sequence methods.

The four terms are all in the glossary. The entry for iterable already points to the other three. What do you think is missing?

A range (as documented) is an immutable sequence.

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

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

From report at bugs.python.org  Sat May  4 01:51:43 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 03 May 2013 23:51:43 +0000
Subject: [docs] [issue17887] docs: summary page - generator vs iterator vs
	iterable
In-Reply-To: <1367390087.97.0.0883934646573.issue17887@psf.upfronthosting.co.za>
Message-ID: <1367625103.08.0.168332698642.issue17887@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

To make the subset relationships clear in the iterable entry, perhaps replace
  See also iterator, sequence, and generator. 
with
  Some iterables are iterators and some iterators are generators. Some iterables are sequences. For details, see iterator, sequence, and generator.

I see that 'generator' is currently used in the 3.3.1 glossary for 'generator function' and there is no entry for generator (object) proper. I thought that had been fixed after pydev discussion.

----------

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

From report at bugs.python.org  Sat May  4 12:34:40 2013
From: report at bugs.python.org (Florent Xicluna)
Date: Sat, 04 May 2013 10:34:40 +0000
Subject: [docs] [issue17904] bytes should be listed as built-in function for
	2.7
Message-ID: <1367663679.93.0.0164308850832.issue17904@psf.upfronthosting.co.za>


New submission from Florent Xicluna:

Looking into the summary table, there's no information about the `bytes` built-in alias for `str`:
http://docs.python.org/2/library/functions.html

IMHO it should appear in this table (as str, unicode, bytearray) with the appropriate `.. versionadded:`.

----------
assignee: docs at python
components: Documentation
messages: 188349
nosy: docs at python, flox
priority: normal
severity: normal
status: open
title: bytes should be listed as built-in function for 2.7
type: behavior
versions: Python 2.7

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

From report at bugs.python.org  Sat May  4 17:07:30 2013
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 04 May 2013 15:07:30 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <3b2tqQ1J92z7LjR@mail.python.org>


Roundup Robot added the comment:

New changeset 003e4eb92683 by Ezio Melotti in branch '3.3':
#16518: use "bytes-like object" throughout the docs.
http://hg.python.org/cpython/rev/003e4eb92683

New changeset d4912244cce6 by Ezio Melotti in branch 'default':
#16518: merge with 3.3.
http://hg.python.org/cpython/rev/d4912244cce6

----------

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

From report at bugs.python.org  Sat May  4 17:27:32 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 04 May 2013 15:27:32 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367681252.43.0.686278131794.issue16518@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

The attached patch uses "bytes-like objects" in the error messages.

----------
Added file: http://bugs.python.org/file30124/issue16518-3.diff

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

From report at bugs.python.org  Sat May  4 17:31:02 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Sat, 04 May 2013 15:31:02 +0000
Subject: [docs] [issue17904] bytes should be listed as built-in function for
	2.7
In-Reply-To: <1367663679.93.0.0164308850832.issue17904@psf.upfronthosting.co.za>
Message-ID: <1367681462.31.0.778019015593.issue17904@psf.upfronthosting.co.za>


Changes by Antoine Pitrou <pitrou at free.fr>:


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

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

From report at bugs.python.org  Sat May  4 18:44:11 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 04 May 2013 16:44:11 +0000
Subject: [docs] [issue17854] symmetric difference operation applicable to
	more than	two sets
In-Reply-To: <1367063240.22.0.643670001227.issue17854@psf.upfronthosting.co.za>
Message-ID: <1367685851.48.0.485740949465.issue17854@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

> Return a new set with elements in an odd number of the sets.

This wording is not really clear to me.

IMHO the documentation is fine as is.  The evaluation order works as usual, and, since the symmetric difference is an associative (and commutative) operation, the order doesn't even matter.

----------
nosy: +ezio.melotti
type: behavior -> enhancement

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

From ezio.melotti at gmail.com  Sat May  4 18:58:14 2013
From: ezio.melotti at gmail.com (ezio.melotti at gmail.com)
Date: Sat, 04 May 2013 16:58:14 -0000
Subject: [docs] Different documentation for identical methods (issue 17858)
Message-ID: <20130504165814.15554.8314@psf.upfronthosting.co.za>


http://bugs.python.org/review/17858/diff/8017/Doc/library/threading.rst
File Doc/library/threading.rst (right):

http://bugs.python.org/review/17858/diff/8017/Doc/library/threading.rst#newcode371
Doc/library/threading.rst:371: necessary waiting until it is released by
another thread (only one thread at a
These lines are too long.

http://bugs.python.org/review/17858/diff/8017/Doc/library/threading.rst#newcode377
Doc/library/threading.rst:377: unconditionally as above.
This paragraph could be simplified.
"If *blocking* is ``False``, the lock is acquired only if it can be
acquired; if it's ``True``, the lock is acquired unconditionally as
above."

http://bugs.python.org/review/17858/

From report at bugs.python.org  Sat May  4 19:19:48 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 04 May 2013 17:19:48 +0000
Subject: [docs] [issue17887] docs: summary page - generator vs iterator vs
	iterable
In-Reply-To: <1367390087.97.0.0883934646573.issue17887@psf.upfronthosting.co.za>
Message-ID: <1367687988.93.0.146687365006.issue17887@psf.upfronthosting.co.za>


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


----------
nosy: +ezio.melotti
type:  -> enhancement
versions: +Python 2.7, Python 3.3, Python 3.4

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

From report at bugs.python.org  Sat May  4 20:05:17 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 04 May 2013 18:05:17 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
In-Reply-To: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>
Message-ID: <1367690717.21.0.735055542985.issue17894@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Attached a patch that rephrases part of the suggestions made by Ned.

----------
nosy: +ezio.melotti
Added file: http://bugs.python.org/file30125/issue17894.diff

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

From ezio.melotti at gmail.com  Sat May  4 20:18:05 2013
From: ezio.melotti at gmail.com (ezio.melotti at gmail.com)
Date: Sat, 04 May 2013 18:18:05 -0000
Subject: [docs] Edits to descriptor howto (issue 17894)
Message-ID: <20130504181805.15554.98763@psf.upfronthosting.co.za>


http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst
File Doc/howto/descriptor.rst (right):

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode39
Doc/howto/descriptor.rst:39: with ``a.__dict__['x']``, then
``type(a).__dict__['x']``, and continuing
This sentence seems too detailed to me, especially in the "Introduction"

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode43
Doc/howto/descriptor.rst:43: descriptor methods are defined.
This is like the original paragraph Ned suggested, the differences with
the original one are:
1) s/The default/Typical/
2) s/may override the default behavior and/will/

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode45
Doc/howto/descriptor.rst:45: Descriptors implements a powerful, general
purpose protocol.  They are also
Here I changed "are a" with "implements".

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode48
Doc/howto/descriptor.rst:48: new style classes introduced in version
2.2.  Descriptors simplify the
This sentence could be removed in the 3.x docs.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode59
Doc/howto/descriptor.rst:59: .. method:: descr.__get__(self, obj,
type=None) -> value
Here I added .. method:: and indented the description, to make it more
readable.
I haven't changed the contents.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode65
Doc/howto/descriptor.rst:65: it is passed `None` and the class. The
value it returns will be used as
This should be ``None``.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode66
Doc/howto/descriptor.rst:66: the value of the attribute.
This would be better explained with an example IMHO, something like:
inst.attr -> attr.__get__(inst, type(inst))
cls.attr -> attr.__get__(None, cls)

This should be done for __set__ and __delete__ too.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode71
Doc/howto/descriptor.rst:71: It is passed the object and the value to
set.
I assume that like __get__, if it's called on a class attribute, None
and the class are passed instead.

http://bugs.python.org/review/17894/

From report at bugs.python.org  Sat May  4 22:23:50 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Sat, 04 May 2013 20:23:50 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367699030.69.0.204632742027.issue16518@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

> The attached patch uses "bytes-like objects" in the error messages.

I'm surprised your patch doesn't touch Python/getargs.c.

----------

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

From report at bugs.python.org  Sat May  4 22:48:23 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 04 May 2013 20:48:23 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367700503.42.0.139025601562.issue16518@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

FWIW I was grepping for buffer protocol/interface/api, and then double-checking for "buffer" in the resulting files.  Python/getargs.c doesn't seem to mention the buffer protocol/interface/api at all.

----------

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

From report at bugs.python.org  Sun May  5 00:12:48 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 04 May 2013 22:12:48 +0000
Subject: [docs] [issue17854] symmetric difference operation applicable to
	more than	two sets
In-Reply-To: <1367063240.22.0.643670001227.issue17854@psf.upfronthosting.co.za>
Message-ID: <1367705568.49.0.496832692578.issue17854@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

If you take the union/intersection/symmetric difference of n sets, the result is a set with all items that appears in one/all/an odd number of the n sets. The union and intersection methods actually accept n inputs, because the result is obvious, useful, and can be obtained faster that with n-1 binary operations. The symmetric_difference method does not, I presume because the result in not obvious (but that cuts both ways), not known to be useful, and perhaps would not be much faster than than n-1 binary operations.

----------

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

From report at bugs.python.org  Sun May  5 01:33:23 2013
From: report at bugs.python.org (Ned Batchelder)
Date: Sat, 04 May 2013 23:33:23 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
In-Reply-To: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>
Message-ID: <1367710403.72.0.666342475334.issue17894@psf.upfronthosting.co.za>


Ned Batchelder added the comment:

I worked with Ezio to make a new patch with the full edits.

I have other ideas for edits to the rest of the document, but we can discuss those if you like these...

----------
Added file: http://bugs.python.org/file30127/descriptor_howto_2.patch

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

From report at bugs.python.org  Sun May  5 04:25:29 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Sun, 05 May 2013 02:25:29 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
In-Reply-To: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>
Message-ID: <1367720729.62.0.907608566142.issue17894@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

Please don't go crazy with this.  I will look at the suggestions and make some edits to improve its readability but am not going to change it into a breezy conversational style.  Instead, I'll likely put together a separate descriptor tutorial that presents an easier on-ramp (in contrast to an authoritative document closely tied to the actually implementation details).

----------

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

From report at bugs.python.org  Sun May  5 04:37:50 2013
From: report at bugs.python.org (Ned Batchelder)
Date: Sun, 05 May 2013 02:37:50 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
In-Reply-To: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>
Message-ID: <1367721470.76.0.811986817252.issue17894@psf.upfronthosting.co.za>


Ned Batchelder added the comment:

Raymond, I'm glad you're on top of this.  I would have thought the howto should be the easy on-ramp, and deeper authoritative details should go in the reference section.

----------

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

From report at bugs.python.org  Sun May  5 08:27:42 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Sun, 05 May 2013 06:27:42 +0000
Subject: [docs] [issue17894] Edits to descriptor howto
In-Reply-To: <1367547112.04.0.920947702161.issue17894@psf.upfronthosting.co.za>
Message-ID: <1367735262.57.0.329008946351.issue17894@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

> in contrast to an authoritative document closely tied to the actually 
> implementation details

I fail to understand why a HOWTO should be an authoritative document closely tied to implementation details. If you don't want this document to be beginner-friendly, please move it into the language reference, not the HOWTO directory.

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

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

From report at bugs.python.org  Sun May  5 16:07:06 2013
From: report at bugs.python.org (Yogesh Chaudhari)
Date: Sun, 05 May 2013 14:07:06 +0000
Subject: [docs] [issue12634] Random Remarks in class documentation
In-Reply-To: <1311575810.71.0.0727071558423.issue12634@psf.upfronthosting.co.za>
Message-ID: <1367762826.36.0.0591671215318.issue12634@psf.upfronthosting.co.za>


Yogesh Chaudhari added the comment:

Based on Teery's comments, this patch makes the changes to the random remarks section of the class documentation

----------
keywords: +patch
nosy: +Yogesh.Chaudhari
Added file: http://bugs.python.org/file30134/issue12634.patch

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

From report at bugs.python.org  Sun May  5 16:08:28 2013
From: report at bugs.python.org (Yogesh Chaudhari)
Date: Sun, 05 May 2013 14:08:28 +0000
Subject: [docs] [issue12634] Random Remarks in class documentation
In-Reply-To: <1311575810.71.0.0727071558423.issue12634@psf.upfronthosting.co.za>
Message-ID: <1367762908.21.0.556365241373.issue12634@psf.upfronthosting.co.za>


Yogesh Chaudhari added the comment:

Similar changes for 2.7 branch

----------
hgrepos: +188
Added file: http://bugs.python.org/file30135/issue12634-27.patch

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

From report at bugs.python.org  Sun May  5 19:10:04 2013
From: report at bugs.python.org (Andriy Mysyk)
Date: Sun, 05 May 2013 17:10:04 +0000
Subject: [docs] [issue17858] Different documentation for identical methods
In-Reply-To: <1367103485.02.0.041609834341.issue17858@psf.upfronthosting.co.za>
Message-ID: <1367773804.82.0.141731265168.issue17858@psf.upfronthosting.co.za>


Andriy Mysyk added the comment:

Made changes suggested by Ezio Melotti in the attached patch.

----------
Added file: http://bugs.python.org/file30136/issue17858.patch

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

From report at bugs.python.org  Sun May  5 21:23:38 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 05 May 2013 19:23:38 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367781818.06.0.984235828078.issue16518@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Updated patch to include getargs.c too.

----------
stage: patch review -> commit review
Added file: http://bugs.python.org/file30138/issue16518-4.diff

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

From report at bugs.python.org  Sun May  5 22:03:50 2013
From: report at bugs.python.org (Andriy Mysyk)
Date: Sun, 05 May 2013 20:03:50 +0000
Subject: [docs] [issue17910] Usage error in multiprocessing documentation
Message-ID: <1367784230.19.0.495557167576.issue17910@psf.upfronthosting.co.za>


New submission from Andriy Mysyk:

"As mentioned above, when doing concurrent programming it is usually best to avoid using shared state as far as possible" should say "as much as possible" in multiprocessing.rst.

----------
assignee: docs at python
components: Documentation
messages: 188461
nosy: amysyk, docs at python
priority: normal
severity: normal
status: open
title: Usage error in multiprocessing documentation
type: enhancement
versions: Python 3.4

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

From report at bugs.python.org  Sun May  5 22:06:09 2013
From: report at bugs.python.org (Andriy Mysyk)
Date: Sun, 05 May 2013 20:06:09 +0000
Subject: [docs] [issue17910] Usage error in multiprocessing documentation
In-Reply-To: <1367784230.19.0.495557167576.issue17910@psf.upfronthosting.co.za>
Message-ID: <1367784369.14.0.941927593586.issue17910@psf.upfronthosting.co.za>


Andriy Mysyk added the comment:

patch attached

----------
keywords: +patch
Added file: http://bugs.python.org/file30142/issue17910.patch

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

From report at bugs.python.org  Mon May  6 00:03:33 2013
From: report at bugs.python.org (Richard Oudkerk)
Date: Sun, 05 May 2013 22:03:33 +0000
Subject: [docs] [issue17910] Usage error in multiprocessing documentation
In-Reply-To: <1367784230.19.0.495557167576.issue17910@psf.upfronthosting.co.za>
Message-ID: <1367791413.23.0.222948272176.issue17910@psf.upfronthosting.co.za>


Richard Oudkerk added the comment:

I don't see any difference in meaning:

    http://idioms.thefreedictionary.com/as+far+as+possible

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

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

From report at bugs.python.org  Mon May  6 02:38:30 2013
From: report at bugs.python.org (Andriy Mysyk)
Date: Mon, 06 May 2013 00:38:30 +0000
Subject: [docs] [issue17910] Usage error in multiprocessing documentation
In-Reply-To: <1367784230.19.0.495557167576.issue17910@psf.upfronthosting.co.za>
Message-ID: <1367800710.07.0.1763937371.issue17910@psf.upfronthosting.co.za>


Andriy Mysyk added the comment:

I found the use of "as far" (as opposed to "as much") but Richard has a good point. Let's close the issue.

----------
resolution:  -> works for me
status: open -> closed

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

From report at bugs.python.org  Mon May  6 05:00:29 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Mon, 06 May 2013 03:00:29 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367809228.92.0.684769181144.issue16518@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

At first-reading, it looks like matters were made more confusing with "bytes-like object" as a defined term.

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

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

From report at bugs.python.org  Mon May  6 05:03:19 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 06 May 2013 03:03:19 +0000
Subject: [docs] [issue16518] add "buffer protocol" to glossary
In-Reply-To: <1353477807.87.0.204584648831.issue16518@psf.upfronthosting.co.za>
Message-ID: <1367809399.51.0.545691621034.issue16518@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Can you elaborate?

----------

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

From report at bugs.python.org  Mon May  6 13:15:19 2013
From: report at bugs.python.org (Roundup Robot)
Date: Mon, 06 May 2013 11:15:19 +0000
Subject: [docs] [issue17805] No such class: multiprocessing.pool.AsyncResult
In-Reply-To: <1366494249.42.0.0654021028594.issue17805@psf.upfronthosting.co.za>
Message-ID: <3b41ZZ4DsZz7Ll2@mail.python.org>


Roundup Robot added the comment:

New changeset 2684176519ef by Richard Oudkerk in branch '2.7':
Issue #17805: Add AsyncResult alias for ApplyResult
http://hg.python.org/cpython/rev/2684176519ef

New changeset bb4bb2db6106 by Richard Oudkerk in branch '3.3':
Issue #17805: Add AsyncResult alias for ApplyResult
http://hg.python.org/cpython/rev/bb4bb2db6106

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

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

From report at bugs.python.org  Mon May  6 13:27:26 2013
From: report at bugs.python.org (Richard Oudkerk)
Date: Mon, 06 May 2013 11:27:26 +0000
Subject: [docs] [issue17805] No such class: multiprocessing.pool.AsyncResult
In-Reply-To: <1366494249.42.0.0654021028594.issue17805@psf.upfronthosting.co.za>
Message-ID: <1367839646.14.0.813300685938.issue17805@psf.upfronthosting.co.za>


Changes by Richard Oudkerk <shibturn at gmail.com>:


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

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

From report at bugs.python.org  Mon May  6 18:48:53 2013
From: report at bugs.python.org (Zachary Ware)
Date: Mon, 06 May 2013 16:48:53 +0000
Subject: [docs] [issue14187] add "function annotation" entry to Glossary
In-Reply-To: <1330805957.18.0.748865462478.issue14187@psf.upfronthosting.co.za>
Message-ID: <1367858933.29.0.148308514628.issue14187@psf.upfronthosting.co.za>


Zachary Ware added the comment:

Would anyone mind committing this?  It was approved by Raymond almost a year ago now, and is still accurate.

The patch still applies cleanly to 3.3 and default, though with some fuzz.

----------
versions:  -Python 3.2

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

From report at bugs.python.org  Mon May  6 18:59:26 2013
From: report at bugs.python.org (Roundup Robot)
Date: Mon, 06 May 2013 16:59:26 +0000
Subject: [docs] [issue14187] add "function annotation" entry to Glossary
In-Reply-To: <1330805957.18.0.748865462478.issue14187@psf.upfronthosting.co.za>
Message-ID: <3b49Cf0TlNzMp1@mail.python.org>


Roundup Robot added the comment:

New changeset e2a805281d26 by R David Murray in branch '3.3':
#14187: Add glossary entry for 'function annotations'.
http://hg.python.org/cpython/rev/e2a805281d26

New changeset 3e1c45f5c585 by R David Murray in branch 'default':
Merge #14187: Add glossary entry for 'function annotations'.
http://hg.python.org/cpython/rev/3e1c45f5c585

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

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

From report at bugs.python.org  Mon May  6 19:00:11 2013
From: report at bugs.python.org (R. David Murray)
Date: Mon, 06 May 2013 17:00:11 +0000
Subject: [docs] [issue14187] add "function annotation" entry to Glossary
In-Reply-To: <1330805957.18.0.748865462478.issue14187@psf.upfronthosting.co.za>
Message-ID: <1367859611.9.0.0106732312501.issue14187@psf.upfronthosting.co.za>


R. David Murray added the comment:

Done.  Thanks for the ping.  And thanks for the suggestion and patch, Chris.

----------
nosy: +r.david.murray
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed

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

From report at bugs.python.org  Mon May  6 22:22:51 2013
From: report at bugs.python.org (abcdef)
Date: Mon, 06 May 2013 20:22:51 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
Message-ID: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>


New submission from abcdef:

The set documentation [http://docs.python.org/3.4/library/stdtypes.html] states

"The subset and equality comparisons do not generalize to a complete ordering function. For example, any two disjoint sets are not equal and are not subsets of each other..."

Could "complete ordering" be changed to "total ordering"? This is the correct mathematical terminology. A total ordering is one where every pair is comparable. A complete ordering is one where each bounded subset has a supremum/infimum (for example, reals form a complete ordered field). This can be verified at Wikipedia [http://en.wikipedia.org/wiki/Total_order] and essentially every set theory book.

----------
assignee: docs at python
components: Documentation
messages: 188585
nosy: abcdef, docs at python
priority: normal
severity: normal
status: open
title: Documentation: "complete ordering" should be "total ordering"
type: enhancement
versions: Python 2.7, Python 3.3, Python 3.4

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

From report at bugs.python.org  Mon May  6 22:32:24 2013
From: report at bugs.python.org (abcdef)
Date: Mon, 06 May 2013 20:32:24 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
In-Reply-To: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>
Message-ID: <1367872344.64.0.0846869555779.issue17920@psf.upfronthosting.co.za>


abcdef added the comment:

Another small thing: "For example, any two disjoint sets are not equal and are not subsets of each other, so all of the following return False: a<b, a==b, or a>b." It should be "any two nonempty disjoint sets".

----------

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

From report at bugs.python.org  Tue May  7 00:45:45 2013
From: report at bugs.python.org (paul j3)
Date: Mon, 06 May 2013 22:45:45 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1367880345.27.0.562116113891.issue14191@psf.upfronthosting.co.za>


paul j3 added the comment:

This is a revision of the test_intermixed.py that I submitted earlier.  Now `parse_intermixed_args` acts like `parse_args', and calls `parse_known_intermixed_args`.  Again it is form that can exercise the idea without modifying `argparse.py`.

If the parser has incompatible features (REMAINDER, PARSER, or certain exclusive groups), it raises an error.  However to facilitate testing I included a `_fallback` backdoor.  If not default None it will be called instead of raising the error.

While making documentation changes, I got to wondering whether 'interspersed' would be a better term than 'intermixed'.  optparse has an 'interspersed' option and api.  However the getopt documentation does use 'intermixed'.

----------
Added file: http://bugs.python.org/file30159/test_intermixed.py

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

From report at bugs.python.org  Tue May  7 00:51:33 2013
From: report at bugs.python.org (paul j3)
Date: Mon, 06 May 2013 22:51:33 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1367880692.77.0.168236530924.issue14191@psf.upfronthosting.co.za>


paul j3 added the comment:

This is the formal patch corresponding to the `test_intermixed.py`.  It includes changes to `argparse.rst`, plus tests in `test_argparse.py`.  These tests are near the end, after those for `parse_known_args`.  They are roughly equivalent to the examples in `test_intermixed.py`.
 -----------------
The new documentation section is:

Some users expect to freely intermix optional and positional argument strings. For example, optparse, by default, allows interspersed argument strings. GNU getopt() permutes the argument strings so non-options are at the end. The parse_intermixed_args() method emulates this behavior by first calling parse_known_args() with just the optional arguments being active. It is then called a second time to parse the list of remaining argument strings using the positional arguments.

parse_intermixed_args() raises an error if the parser uses features that are incompatible with this two step parsing. These include subparsers, argparse.REMAINDER, and mutually exclusive groups that include both optionals and positionals.

In this example, parse_known_args() returns an unparsed list of arguments [?2?, ?3?], while parse_intermixed_args() returns rest=[1, 2, 3].

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo')
    >>> parser.add_argument('cmd')
    >>> parser.add_argument('rest', nargs='*', type=int)
    >>> parser.parse_known_args('cmd1 1 --foo bar 2 3'.split())
    (Namespace(cmd='cmd1', foo='bar', rest=[1]), ['2', '3']) 
    >>> parser.parse_intermixed_args('cmd1 1 --foo bar 2 3'.split())
    Namespace(cmd='cmd1', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() method, returns a two item tuple containing the populated namespace and the list of remaining argument strings. parse_intermixed_args() raises an error if there are any remaining unparsed argument strings.

----------
Added file: http://bugs.python.org/file30160/intermixed.patch

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

From report at bugs.python.org  Tue May  7 03:18:35 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 07 May 2013 01:18:35 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
In-Reply-To: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>
Message-ID: <1367889515.56.0.423216130718.issue17920@psf.upfronthosting.co.za>


Changes by Raymond Hettinger <raymond.hettinger at gmail.com>:


----------
assignee: docs at python -> rhettinger
nosy: +rhettinger

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

From report at bugs.python.org  Tue May  7 03:21:18 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 07 May 2013 01:21:18 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
In-Reply-To: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>
Message-ID: <3b4NLk0rKlzRpW@mail.python.org>


Roundup Robot added the comment:

New changeset a285ce18bd55 by Raymond Hettinger in branch '2.7':
Issue 17920:  Fix-up terminology in the set documentation
http://hg.python.org/cpython/rev/a285ce18bd55

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

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

From report at bugs.python.org  Tue May  7 03:23:22 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 07 May 2013 01:23:22 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
In-Reply-To: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>
Message-ID: <3b4NP52v37zSj9@mail.python.org>


Roundup Robot added the comment:

New changeset 6ec04c5dae6e by Raymond Hettinger in branch '3.3':
Issue 17920:  Fix-up terminology in the set documentation
http://hg.python.org/cpython/rev/6ec04c5dae6e

----------

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

From report at bugs.python.org  Tue May  7 08:47:18 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 07 May 2013 06:47:18 +0000
Subject: [docs] [issue17871] Wrong signature of TextTestRunner's init
	function
In-Reply-To: <1367269592.44.0.115946830805.issue17871@psf.upfronthosting.co.za>
Message-ID: <3b4WZs3MFrzNFJ@mail.python.org>


Roundup Robot added the comment:

New changeset 5dd076d441ec by Ezio Melotti in branch '3.3':
#17871: fix unittest.TextTestRunner signature in the docs.  Patch by Yogesh Chaudhari.
http://hg.python.org/cpython/rev/5dd076d441ec

New changeset 15ed67602ddf by Ezio Melotti in branch 'default':
#17871: merge with 3.3.
http://hg.python.org/cpython/rev/15ed67602ddf

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

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

From report at bugs.python.org  Tue May  7 08:47:54 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 07 May 2013 06:47:54 +0000
Subject: [docs] [issue17871] Wrong signature of TextTestRunner's init
	function
In-Reply-To: <1367269592.44.0.115946830805.issue17871@psf.upfronthosting.co.za>
Message-ID: <1367909274.6.0.0892955053973.issue17871@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Fixed, thanks for the patch!

----------
assignee: docs at python -> ezio.melotti
resolution:  -> fixed
stage: needs patch -> committed/rejected
status: open -> closed
versions: +Python 3.3

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

From report at bugs.python.org  Tue May  7 10:14:38 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 07 May 2013 08:14:38 +0000
Subject: [docs] [issue17714] str.encode('base64') add trailing new line
	character. It	is not documented.
In-Reply-To: <1365867569.46.0.547710519327.issue17714@psf.upfronthosting.co.za>
Message-ID: <3b4YWd4twdzQ1v@mail.python.org>


Roundup Robot added the comment:

New changeset 8b764c3521fa by Ezio Melotti in branch '2.7':
#17714: document that the base64 codec adds a trailing newline.
http://hg.python.org/cpython/rev/8b764c3521fa

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

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

From report at bugs.python.org  Tue May  7 10:16:56 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 07 May 2013 08:16:56 +0000
Subject: [docs] [issue17714] str.encode('base64') add trailing new line
	character. It	is not documented.
In-Reply-To: <1365867569.46.0.547710519327.issue17714@psf.upfronthosting.co.za>
Message-ID: <1367914616.26.0.814681769103.issue17714@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

The str.encode() doc is the wrong place where to document this, since the '\n' is added only for the base64 codec.  I added a note about this in the codecs docs[0].

[0]: http://docs.python.org/2/library/codecs.html#standard-encodings

----------
assignee: docs at python -> ezio.melotti
resolution:  -> fixed
stage: patch review -> committed/rejected
status: open -> closed

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

From report at bugs.python.org  Tue May  7 10:21:33 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 07 May 2013 08:21:33 +0000
Subject: [docs] [issue17714] str.encode('base64') add trailing new line
	character. It	is not documented.
In-Reply-To: <1365867569.46.0.547710519327.issue17714@psf.upfronthosting.co.za>
Message-ID: <3b4Ygc4dw1zR8T@mail.python.org>


Roundup Robot added the comment:

New changeset cbb23e40e0d7 by Ezio Melotti in branch '3.3':
#17714: document that the base64 codec adds a trailing newline.
http://hg.python.org/cpython/rev/cbb23e40e0d7

New changeset b3e1be1493a5 by Ezio Melotti in branch 'default':
#17714: merge with 3.3.
http://hg.python.org/cpython/rev/b3e1be1493a5

----------

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

From report at bugs.python.org  Tue May  7 10:26:30 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 07 May 2013 08:26:30 +0000
Subject: [docs] [issue13515] Consistent documentation practices for security
	concerns	and considerations
In-Reply-To: <1322726017.57.0.923133254266.issue13515@psf.upfronthosting.co.za>
Message-ID: <1367915190.57.0.169597429132.issue13515@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/issue13515>
_______________________________________

From report at bugs.python.org  Tue May  7 14:05:20 2013
From: report at bugs.python.org (Christian Heimes)
Date: Tue, 07 May 2013 12:05:20 +0000
Subject: [docs] [issue17924] Deprecate stat.S_IF* integer constants
Message-ID: <1367928320.73.0.37418131168.issue17924@psf.upfronthosting.co.za>


New submission from Christian Heimes:

Related to #11016
I like to deprecate the S_IF* constants in favor of the S_IS*() functions.

rationals:
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html

No new S_IFMT symbolic names for the file type values of mode_t will be defined by POSIX.1-2008; if new file types are required, they will only be testable through S_ISxx() or S_TYPEISxxx() macros instead.

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 188641
nosy: christian.heimes, docs at python
priority: normal
severity: normal
status: open
title: Deprecate stat.S_IF* integer constants
type: behavior
versions: Python 3.4

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

From report at bugs.python.org  Tue May  7 14:36:49 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Tue, 07 May 2013 12:36:49 +0000
Subject: [docs] [issue13515] Consistent documentation practices for security
	concerns	and considerations
In-Reply-To: <1322726017.57.0.923133254266.issue13515@psf.upfronthosting.co.za>
Message-ID: <1367930209.22.0.363149354189.issue13515@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

The new section looks good to me.

Would it be appropriate to explicitly note that this is a relatively recent change of policy, so most of the stdlib docs don't actually follow it? (and patches to bring them into line would be reasonable)

----------

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

From report at bugs.python.org  Tue May  7 14:49:24 2013
From: report at bugs.python.org (R. David Murray)
Date: Tue, 07 May 2013 12:49:24 +0000
Subject: [docs] [issue13515] Consistent documentation practices for security
	concerns	and considerations
In-Reply-To: <1322726017.57.0.923133254266.issue13515@psf.upfronthosting.co.za>
Message-ID: <1367930964.45.0.0586056109665.issue13515@psf.upfronthosting.co.za>


R. David Murray added the comment:

Probably.  Otherwise people are going to go look at the subprocess docs as an example...and they don't follow it.

----------
nosy: +r.david.murray

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

From report at bugs.python.org  Tue May  7 15:11:26 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 07 May 2013 13:11:26 +0000
Subject: [docs] [issue13515] Consistent documentation practices for security
	concerns	and considerations
In-Reply-To: <1322726017.57.0.923133254266.issue13515@psf.upfronthosting.co.za>
Message-ID: <1367932286.1.0.0611549089544.issue13515@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

Patch looks fine to me.

----------

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

From report at bugs.python.org  Tue May  7 16:02:57 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Tue, 07 May 2013 14:02:57 +0000
Subject: [docs] [issue13515] Consistent documentation practices for security
	concerns	and considerations
In-Reply-To: <1322726017.57.0.923133254266.issue13515@psf.upfronthosting.co.za>
Message-ID: <1367935377.87.0.423180274173.issue13515@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

We could use the SSL docs[0] as example instead of subprocess.

[0]: http://docs.python.org/3/library/ssl.html#security-considerations

----------

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

From report at bugs.python.org  Tue May  7 20:50:13 2013
From: report at bugs.python.org (Glenn Linderman)
Date: Tue, 07 May 2013 18:50:13 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1367952613.26.0.671753949626.issue14191@psf.upfronthosting.co.za>


Glenn Linderman added the comment:

Paul, thanks for your continued work.

I had reworked your prior patch into a subclass of Argument Parser, and tweaking the code to get parse_intermixed_args to adjust the behaviors I had reported.

Now substituting exactly your more flexible new code into my subclass from your latest test_intermixed.py (you should delete your old patches), I can quickly confirm that it works with my applications that used to use my wrapper class, and expect and use intermixed functionality.

I also read through all your code and comments and it looks good to me.

Regarding parse_fallback_args, I do not see documentation for it. If that is intentional, you might want to add comments in the code regarding its use for testing only... and might want to rename it to _parse_fallback_args. I personally don't see a lot of value to the function, or the new parameter; tests for parse_intermixed_args and parse_known_intermixed_args should be (and have been, thanks) added to the tests for argparse, and should suffice for testing. In non-test code, I see no benefit: either the user uses features that are incompatible with parse_intermixed_args, and thus uses the other features of argparse, or the user, for compatibility reasons, needs to use parse_intermixed_args, and thus is prevented from successfully using the incompatible features. If I'm missing some benefit of parse_fallback_args, it should be explained in either the documentation or the comments.

Regarding the terminology: both intermixed and interspersed would be correct English words to describe the use case. So would intermingled :)

Because Stephen "blessed" intermixed, and because it is used by getopt documentation (getopt has not been deprecated, optparse has), it seems to be the best term to use. Should optparse someday be removed, along with its documentation, the use of the term interspersed would also disappear, leaving more consistency in terminology.

Alternative:

Because optparse uses "interspersed" in an API, we cannot fix it to use "intermixed". However, we could fix the uses of "intermixed" to be "interspersed" prior to or at the time of accepting your patch to argparse... afterwards, it would be too late.  Personally, I see no problem with the use of both terms in the documentation, and "intermixed" is the shortest, so I have a slight preference for that.

----------

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

From report at bugs.python.org  Wed May  8 09:57:05 2013
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 08 May 2013 07:57:05 +0000
Subject: [docs] [issue16523] attrgetter and itemgetter signatures in docs
	need cleanup
In-Reply-To: <1353510966.46.0.566270540705.issue16523@psf.upfronthosting.co.za>
Message-ID: <3b594w3rCmz7LjM@mail.python.org>


Roundup Robot added the comment:

New changeset 6f2412f12bfd by Ezio Melotti in branch '3.3':
#16523: improve attrgetter/itemgetter/methodcaller documentation.
http://hg.python.org/cpython/rev/6f2412f12bfd

New changeset c2000ce25fe8 by Ezio Melotti in branch 'default':
#16523: merge with 3.3.
http://hg.python.org/cpython/rev/c2000ce25fe8

New changeset 5885c02120f0 by Ezio Melotti in branch '2.7':
#16523: improve attrgetter/itemgetter/methodcaller documentation.
http://hg.python.org/cpython/rev/5885c02120f0

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

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

From report at bugs.python.org  Wed May  8 09:57:36 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 08 May 2013 07:57:36 +0000
Subject: [docs] [issue16523] attrgetter and itemgetter signatures in docs
	need cleanup
In-Reply-To: <1353510966.46.0.566270540705.issue16523@psf.upfronthosting.co.za>
Message-ID: <1367999856.17.0.594422818873.issue16523@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Fixed, thanks for the review!

----------
assignee: docs at python -> ezio.melotti
resolution:  -> fixed
stage: commit review -> committed/rejected
status: open -> closed

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

From rdmurray at bitdance.com  Wed May  8 13:36:12 2013
From: rdmurray at bitdance.com (rdmurray at bitdance.com)
Date: Wed, 08 May 2013 11:36:12 -0000
Subject: [docs] Different documentation for identical methods (issue
	17858)
Message-ID: <20130508113612.32685.2426@psf.upfronthosting.co.za>


http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst
File Doc/library/threading.rst (right):

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode373
Doc/library/threading.rst:373: reason for existence).
I don't think this parenthetical is completely accurate.  For a Lock,
even the same thread cannot acquire it (that's why RLock was later
added).  Probably just drop the parenthetical, I don't think it really
adds anything helpful.

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode375
Doc/library/threading.rst:375: If *blocking* is ``False``, the lock is
acquired only if it can be
This wording is an improvement in general, but I'm not sure a new reader
would know what "the lock is acquired only if it can be acquired" means.
 The original had "immediately without waiting" in there as well, which
while a bit redundant was also a bit more comprehensible.  Perhaps a
better wording than either would be "If *blocking* is ``False`` the call
returns immediately; the return value indicates whether or not the lock
was acquired."

Then this paragraph can be re-combined with the preceding one, since
that one describes the behavior when blocking is True.

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode379
Doc/library/threading.rst:379: specifies the maximum wait time in
seconds before returning.  A negative
I think it would be good to add "; the return value indicates whether or
not the lock was acquired." here as well.

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode380
Doc/library/threading.rst:380: *timeout* argument specifies an unbounded
wait.  You cannot specify
This immediately raises the question of what a 0 timeout means (and yes
I see that the original does not answer that question).  Seems like we
could have avoided having a 'blocking' keyword if we'd had timeout from
the start instead :)

So, a negative timeout is the same as not specifying a timeout and also
specifying blocking=True, and a zero timeout is the same as not
specifying a timeout and also specifying blocking=False.  We're stuck
with the API, but as long as we are perhaps we should document it that
way?

http://bugs.python.org/review/17858/

From report at bugs.python.org  Wed May  8 13:39:04 2013
From: report at bugs.python.org (R. David Murray)
Date: Wed, 08 May 2013 11:39:04 +0000
Subject: [docs] [issue17858] Different documentation for identical methods
In-Reply-To: <1367103485.02.0.041609834341.issue17858@psf.upfronthosting.co.za>
Message-ID: <1368013144.64.0.545436459083.issue17858@psf.upfronthosting.co.za>


R. David Murray added the comment:

Added review comments with suggestions on improving the wording further.  Once we agree on wording we could apply this to the _thread docs as well, I suppose.

Ah, I see that one of the changes I found problematic was suggested by Ezio :)

----------

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

From report at bugs.python.org  Wed May  8 23:27:11 2013
From: report at bugs.python.org (Stefan Chrobot)
Date: Wed, 08 May 2013 21:27:11 +0000
Subject: [docs] [issue17938] Duplicate text in docs/reference/import
	statement
Message-ID: <1368048430.97.0.564979420355.issue17938@psf.upfronthosting.co.za>


New submission from Stefan Chrobot:

http://docs.python.org/3/reference/simple_stmts.html#the-import-statement

After the "Examples", there's a duplicated paragraph:

The public names defined by a module are determined by checking the module?s namespace for a variable named __all__; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module?s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).

The from form with * may only occur in a module scope. Attempting to use it in class or function definitions will raise a SyntaxError.

The public names defined by a module are determined by checking the module?s namespace for a variable named __all__; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module?s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).

The from form with * may only occur in a module scope. The wild card form of import ? import * ? is only allowed at the module level. Attempting to use it in class or function definitions will raise a SyntaxError.

----------
assignee: docs at python
components: Documentation
messages: 188737
nosy: docs at python, stefanchrobot
priority: normal
severity: normal
status: open
title: Duplicate text in docs/reference/import statement
type: enhancement
versions: Python 3.3

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

From report at bugs.python.org  Wed May  8 23:31:40 2013
From: report at bugs.python.org (Stefan Chrobot)
Date: Wed, 08 May 2013 21:31:40 +0000
Subject: [docs] [issue17939] Misleading information about slice assignment
	in docs
Message-ID: <1368048699.98.0.203661524608.issue17939@psf.upfronthosting.co.za>


New submission from Stefan Chrobot:

http://docs.python.org/3/reference/simple_stmts.html#assignment-statements

The docs says:

"If the target is a slicing: The primary expression in the reference is evaluated. It should yield a mutable sequence object (such as a list). The assigned object should be a sequence object of the same type."

This seems wrong, because the assigned object can be any iterable:

a = [4, 5, 6]
a[0:0] = range(1, 4)
# a is now [1, 2, 3, 4, 5, 6]

----------
assignee: docs at python
components: Documentation
messages: 188738
nosy: docs at python, stefanchrobot
priority: normal
severity: normal
status: open
title: Misleading information about slice assignment in docs
type: enhancement
versions: Python 3.3

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

From report at bugs.python.org  Wed May  8 23:47:44 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 08 May 2013 21:47:44 +0000
Subject: [docs] [issue17938] Duplicate text in docs/reference/import
	statement
In-Reply-To: <1368048430.97.0.564979420355.issue17938@psf.upfronthosting.co.za>
Message-ID: <1368049664.56.0.0771725602674.issue17938@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/issue17938>
_______________________________________

From report at bugs.python.org  Wed May  8 23:48:01 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 08 May 2013 21:48:01 +0000
Subject: [docs] [issue17939] Misleading information about slice assignment
	in docs
In-Reply-To: <1368048699.98.0.203661524608.issue17939@psf.upfronthosting.co.za>
Message-ID: <1368049681.05.0.820673295211.issue17939@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/issue17939>
_______________________________________

From report at bugs.python.org  Thu May  9 00:20:31 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Wed, 08 May 2013 22:20:31 +0000
Subject: [docs] [issue17576] PyNumber_Index() is not int-subclass friendly
	(or	operator.index() docos lie)
In-Reply-To: <1364595911.19.0.826873230127.issue17576@psf.upfronthosting.co.za>
Message-ID: <1368051631.56.0.241844031499.issue17576@psf.upfronthosting.co.za>


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


----------
versions:  -Python 3.1, Python 3.2

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

From report at bugs.python.org  Thu May  9 11:47:18 2013
From: report at bugs.python.org (Amit Saha)
Date: Thu, 09 May 2013 09:47:18 +0000
Subject: [docs] [issue17583] IDLE HOWTO
In-Reply-To: <1364685156.29.0.769214841654.issue17583@psf.upfronthosting.co.za>
Message-ID: <1368092838.41.0.63936035321.issue17583@psf.upfronthosting.co.za>


Amit Saha added the comment:

Hello, I just wanted to check if I should attach the image files separately and submit the text as a diff? 

Thanks.

----------

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

From report at bugs.python.org  Thu May  9 14:34:23 2013
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 09 May 2013 12:34:23 +0000
Subject: [docs] [issue17938] Duplicate text in docs/reference/import
	statement
In-Reply-To: <1368048430.97.0.564979420355.issue17938@psf.upfronthosting.co.za>
Message-ID: <3b5vBM3wbWzRKZ@mail.python.org>


Roundup Robot added the comment:

New changeset 844c6442a39e by Ezio Melotti in branch '3.3':
#17938: remove duplicate paragraphs.
http://hg.python.org/cpython/rev/844c6442a39e

New changeset ebc296bf23d1 by Ezio Melotti in branch 'default':
#17938: merge with 3.3.
http://hg.python.org/cpython/rev/ebc296bf23d1

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

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

From report at bugs.python.org  Thu May  9 14:34:55 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Thu, 09 May 2013 12:34:55 +0000
Subject: [docs] [issue17938] Duplicate text in docs/reference/import
	statement
In-Reply-To: <1368048430.97.0.564979420355.issue17938@psf.upfronthosting.co.za>
Message-ID: <1368102895.86.0.707405891141.issue17938@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Fixed, thanks for the report!

----------
assignee: docs at python -> ezio.melotti
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed
versions: +Python 3.4

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

From report at bugs.python.org  Thu May  9 14:37:50 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Thu, 09 May 2013 12:37:50 +0000
Subject: [docs] [issue17700] Update Curses HOWTO for 3.4
In-Reply-To: <1365719687.97.0.644773548697.issue17700@psf.upfronthosting.co.za>
Message-ID: <1368103070.48.0.478893200069.issue17700@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

I've just verified that I still have commit access to the repo, so unless someone has any further suggested changes to the patch, I'll go ahead and commit it to trunk.  Should I also commit it to the 3.3 branch?

Victor: I'm willing to improve the HOWTO's discussion of Unicode/wide characters if you can point me at some references.

----------

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

From report at bugs.python.org  Thu May  9 14:45:52 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Thu, 09 May 2013 12:45:52 +0000
Subject: [docs] [issue17700] Update Curses HOWTO for 3.4
In-Reply-To: <1365719687.97.0.644773548697.issue17700@psf.upfronthosting.co.za>
Message-ID: <1368103552.39.0.631903465981.issue17700@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Patch LGTM.
You should commit it to 3.3 and then merge it with default (unless the patch contains parts that are specific to 3.4).

----------

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

From report at bugs.python.org  Thu May  9 17:19:20 2013
From: report at bugs.python.org (Andriy Mysyk)
Date: Thu, 09 May 2013 15:19:20 +0000
Subject: [docs] [issue17858] Different documentation for identical methods
In-Reply-To: <1367103485.02.0.041609834341.issue17858@psf.upfronthosting.co.za>
Message-ID: <1368112760.69.0.421852947371.issue17858@psf.upfronthosting.co.za>


Andriy Mysyk added the comment:

Incorporated R. David Murray's feedback...

   .. method:: acquire(blocking=True, timeout=-1)

      Without any optional argument, this method acquires the lock
      unconditionally, if necessary waiting until it is released by another
      thread (only one thread at a time can acquire a lock).

      If *blocking* is ``False``, the call returns immediately.  If *blocking*
      is ``True``, the lock is acquired unconditionally. In both cases
      the return value indicates whether or not the lock was acquired.

      If the floating-point *timeout* argument is present and positive, it
      specifies the maximum wait time in seconds before returning; the return
      value indicates whether or not the lock was acquired.  A negative
      *timeout* argument specifies an unbounded wait and is the same as not
      specifying a *timeout* and also setting *blocking* to ``True``.  A zero
      *timeout* is the same as not specifying a *timeout* and setting *blocking*
      to ``False``.  You cannot specify a *timeout* if *blocking* is ``False``.

      The return value is ``True`` if the lock is acquired successfully,
      ``False`` if not.

----------
Added file: http://bugs.python.org/file30184/issue17858.patch

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

From report at bugs.python.org  Fri May 10 00:09:29 2013
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 09 May 2013 22:09:29 +0000
Subject: [docs] [issue17576] PyNumber_Index() is not int-subclass friendly
	(or	operator.index() docos lie)
In-Reply-To: <1364595911.19.0.826873230127.issue17576@psf.upfronthosting.co.za>
Message-ID: <1368137369.75.0.921014905671.issue17576@psf.upfronthosting.co.za>


STINNER Victor added the comment:

Alex> In my opinion that should use PyLong_CheckExact

+1

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

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

From report at bugs.python.org  Fri May 10 02:14:50 2013
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 10 May 2013 00:14:50 +0000
Subject: [docs] [issue17700] Update Curses HOWTO for 3.4
In-Reply-To: <1365719687.97.0.644773548697.issue17700@psf.upfronthosting.co.za>
Message-ID: <3b6Bkc2b3vz7Llj@mail.python.org>


Roundup Robot added the comment:

New changeset 1fa70b797973 by Andrew Kuchling in branch '3.3':
#17700: update the curses HOWTO for 3.x
http://hg.python.org/cpython/rev/1fa70b797973

New changeset 70f530161b9b by Andrew Kuchling in branch 'default':
#17700: merge with 3.3
http://hg.python.org/cpython/rev/70f530161b9b

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

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

From report at bugs.python.org  Fri May 10 02:16:55 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Fri, 10 May 2013 00:16:55 +0000
Subject: [docs] [issue17700] Update Curses HOWTO for 3.4
In-Reply-To: <1365719687.97.0.644773548697.issue17700@psf.upfronthosting.co.za>
Message-ID: <1368145014.9.0.666161614149.issue17700@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

Applied to 3.3 and 3.4.  I'll leave this issue open for a week so that Victor can comment on Unicode/wide-characters.

----------

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

From report at bugs.python.org  Fri May 10 02:55:46 2013
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 10 May 2013 00:55:46 +0000
Subject: [docs] [issue14878] Improve documentation for generator.send method
In-Reply-To: <1337662493.01.0.380911981252.issue14878@psf.upfronthosting.co.za>
Message-ID: <3b6Cds2vxzz7LjP@mail.python.org>


Roundup Robot added the comment:

New changeset 7b8c0bf8fcb8 by Andrew Kuchling in branch '2.7':
#14878: add cross-reference to the yield statement.
http://hg.python.org/cpython/rev/7b8c0bf8fcb8

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

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

From report at bugs.python.org  Fri May 10 02:56:12 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Fri, 10 May 2013 00:56:12 +0000
Subject: [docs] [issue14878] Improve documentation for generator.send method
In-Reply-To: <1337662493.01.0.380911981252.issue14878@psf.upfronthosting.co.za>
Message-ID: <1368147372.87.0.801652147466.issue14878@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

Thanks for the patch!

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

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

From report at bugs.python.org  Fri May 10 03:19:45 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 01:19:45 +0000
Subject: [docs] [issue14878] Improve documentation for generator.send method
In-Reply-To: <1337662493.01.0.380911981252.issue14878@psf.upfronthosting.co.za>
Message-ID: <1368148785.97.0.469170108909.issue14878@psf.upfronthosting.co.za>


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


----------
stage: needs patch -> committed/rejected
type:  -> enhancement
versions:  -Python 3.2, Python 3.3

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

From report at bugs.python.org  Fri May 10 04:22:27 2013
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 10 May 2013 02:22:27 +0000
Subject: [docs] [issue17841] Remove missing aliases from codecs documentation
In-Reply-To: <1366878629.86.0.715834730144.issue17841@psf.upfronthosting.co.za>
Message-ID: <3b6FYv1F8bzR2w@mail.python.org>


Roundup Robot added the comment:

New changeset ead47bc3a763 by Ezio Melotti in branch '3.3':
#17841: remove missing codecs aliases from the documentation.  Patch by Thomas Fenzl.
http://hg.python.org/cpython/rev/ead47bc3a763

New changeset eafff38a56cc by Ezio Melotti in branch 'default':
#17841: merge with 3.3.
http://hg.python.org/cpython/rev/eafff38a56cc

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

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

From report at bugs.python.org  Fri May 10 04:29:06 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 02:29:06 +0000
Subject: [docs] [issue17841] Remove missing aliases from codecs documentation
In-Reply-To: <1366878629.86.0.715834730144.issue17841@psf.upfronthosting.co.za>
Message-ID: <1368152946.2.0.898167439877.issue17841@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Fixed, thanks for the patch!

@Nick
While this works as a short-term solution, I think it would be good to
 1) reintroduce the aliases in 3.4 (so that codecs.encode(b'foo', 'base64') works without spelling out the full codec name);
 2) either separate these codecs from the others, or tweak the error message of str.encode/bytes.decode to point to codecs.encode/decode.
Should I create a new issue and/or ask python-dev about this?

----------
assignee: docs at python -> ezio.melotti
resolution:  -> fixed
stage: needs patch -> committed/rejected
status: open -> closed
type: behavior -> enhancement
versions: +Python 3.4

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

From report at bugs.python.org  Fri May 10 06:45:14 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 04:45:14 +0000
Subject: [docs] [issue17282] document the defaultTest parameter to
	unittest.main()
In-Reply-To: <1361664894.83.0.085559336561.issue17282@psf.upfronthosting.co.za>
Message-ID: <1368161114.74.0.314613521668.issue17282@psf.upfronthosting.co.za>


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


----------
stage: needs patch -> patch review
versions:  -Python 3.2

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

From report at bugs.python.org  Fri May 10 08:03:37 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 10 May 2013 06:03:37 +0000
Subject: [docs] [issue17576] PyNumber_Index() is not int-subclass friendly
	(or	operator.index() docos lie)
In-Reply-To: <1364595911.19.0.826873230127.issue17576@psf.upfronthosting.co.za>
Message-ID: <1368165817.7.0.49653127526.issue17576@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

if (PyLong_CheckExact(item) || (PyLong_Check(item) &&
    item->ob_type->tp_as_number->nb_index == PyLong_Type.tp_as_number->nb_index))

----------
nosy: +serhiy.storchaka

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

From report at bugs.python.org  Fri May 10 08:50:01 2013
From: report at bugs.python.org (Ethan Furman)
Date: Fri, 10 May 2013 06:50:01 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
Message-ID: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>


New submission from Ethan Furman:

PEP-0435 has been approved!

Now for lots of code review.

----------
assignee: docs at python
components: Documentation, Library (Lib), Tests
files: ref435.py
hgrepos: 189
messages: 188812
nosy: barry, docs at python, eli.bendersky, stoneleaf
priority: normal
severity: normal
status: open
title: Code, test, and doc review for PEP-0435 Enum
versions: Python 3.4
Added file: http://bugs.python.org/file30191/ref435.py

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

From report at bugs.python.org  Fri May 10 08:55:46 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Fri, 10 May 2013 06:55:46 +0000
Subject: [docs] [issue17841] Remove missing aliases from codecs documentation
In-Reply-To: <1366878629.86.0.715834730144.issue17841@psf.upfronthosting.co.za>
Message-ID: <1368168946.39.0.214714675619.issue17841@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

For anyone else reading the issue and wondering about Ezio's question above - this issue was actually spun out from issue 7475, which covers the long saga of getting these codecs fully restored in the new world order of Python 3 :)

----------

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

From report at bugs.python.org  Fri May 10 08:58:11 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 06:58:11 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368169091.93.0.250092444312.issue17947@psf.upfronthosting.co.za>


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


----------
nosy: +ezio.melotti
stage:  -> patch review
type:  -> enhancement

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

From report at bugs.python.org  Fri May 10 09:01:10 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 07:01:10 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368169270.2.0.463214846124.issue17947@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Can you upload the patch as a diff against the CPython repo?

----------

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

From report at bugs.python.org  Fri May 10 09:09:04 2013
From: report at bugs.python.org (Ethan Furman)
Date: Fri, 10 May 2013 07:09:04 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368169743.23.0.07951913795.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Here it is (I hope ;) .

----------
keywords: +patch
Added file: http://bugs.python.org/file30192/pep-435.patch

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

From report at bugs.python.org  Fri May 10 15:19:21 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 10 May 2013 13:19:21 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368191961.5.0.295612621501.issue17947@psf.upfronthosting.co.za>


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


Removed file: http://bugs.python.org/file30191/ref435.py

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

From report at bugs.python.org  Fri May 10 15:21:38 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 10 May 2013 13:21:38 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368192098.91.0.138348876038.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

I don't see docs in the patch, but perhaps that should be a separate patch to keep reviewing easier.

Also, Ethan, number the patch files in some way (like pep-435.1.patch, pep-435.N.patch) as they go through rounds of reviews.

----------
assignee: docs at python -> 

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

From report at bugs.python.org  Fri May 10 16:01:01 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Fri, 10 May 2013 14:01:01 +0000
Subject: [docs] [issue5901] missing meta-info in documentation pdf
In-Reply-To: <1241246578.79.0.771794251259.issue5901@psf.upfronthosting.co.za>
Message-ID: <1368194461.48.0.850274393487.issue5901@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

This seems to be fixed now.  I downloaded python-3.3.1-docs-pdf-letter.tar.bz2 and ran pdfinfo on using.pdf:

Title:          Python Setup and Usage
Subject:        
Keywords:       
Author:         Guido van Rossum, Fred L. Drake, Jr., editor
Creator:        LaTeX with hyperref package
Producer:       pdfTeX-1.40.10
CreationDate:   Fri May 10 09:42:17 2013
ModDate:        Fri May 10 09:42:17 2013
Tagged:         no
Pages:          65
Encrypted:      no
Page size:      612 x 792 pts (letter)
File size:      432316 bytes
Optimized:      no
PDF version:    1.4

We could fill in Subject and Keywords, but the basic fields of Title and Author seem to be present.  (Do we need to change author to 'Python Development Group' or 'PSF'?)

----------
nosy: +akuchling

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

From eliben at gmail.com  Fri May 10 16:02:43 2013
From: eliben at gmail.com (eliben at gmail.com)
Date: Fri, 10 May 2013 14:02:43 -0000
Subject: [docs] Code, test, and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510140243.28617.53528@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8105/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode2
Lib/enum.py:2: =========
Yeah, remove this :-)

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode19
Lib/enum.py:19: """
PEP257-ify

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode23
Lib/enum.py:23: # Used to provide access to the `name` and `value`
properties of enum
This class is quite generic though, and doesn't mention name or value
properties. Document it in a generic way, and then inside the enum class
document how StealthProperty is actually being used.

Also, _StealthProperty as this is an internal class.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode84
Lib/enum.py:84: if key[:2] == key[-2:] == '__' or hasattr(something,
'__get__'):
parenthesize the parts of the or

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode85
Lib/enum.py:85: if key in self._enum_names:
Wait what? This also contradicts the docstring. And why should we do
that? 

I see no reason to provide more safeguards in enum than regular Python
classes provide

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode92
Lib/enum.py:92: dict.__setitem__(self, key, something)
Perhaps using super() here would be cleaner and more future-proof

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode94
Lib/enum.py:94: Enum = None  # dummy value until replaced
beefier comment that explains why this dummy is needed. Also, would this
need a docstring? I'm thinking of 

>> import enum
>> help(enum.Enum)

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode97
Lib/enum.py:97: class EnumMeta(type):
Should this be _EnumMeta too?

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode98
Lib/enum.py:98: """Metaclass for Enum
There's no point in repeating the docs here - *how* an enum behaves
belongs there. I'd suggest a detailed imlementation explanation instead
here in the code. I.e. how a new enum gets created, which metaclass
methods get invoked and what they do.

I'm not saying to put a metaclass tutorial here, but a bit of details to
help follow the flow of what happens when:

class Color(Enum):
  red = 1
  blue = 2

is defined

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode100
Lib/enum.py:100: Pure enumerations can take any value, but the
enumeration item will not
It's not clear what a "pure" enum is

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode107
Lib/enum.py:107: resulting psuedenums must all be of that mixed-in type.
psuedenums?

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode116
Lib/enum.py:116: # an Enum class is final once enumeration items have
been defined;
Explain in more detail what a "data type" is

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode118
Lib/enum.py:118: # __new__ unless a new __new__ is defined (or the
resulting class
Hmm, this __new__ protocol has to be documented on a higher level first
(in the docs?)

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode127
Lib/enum.py:127: and issubclass(base, Enum)
indentation

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode130
Lib/enum.py:130: if not issubclass(base, Enum):
make it more explicit that base here is the last base!

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode133
Lib/enum.py:133: # get correct mixin_type (either mixin type of Enum
subclass,
theres no mixin_type in the code. also close the paren )

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode159
Lib/enum.py:159: if __new__ is None:
if would be great to make this method shorter. helper methods with
well-defined functionality and well-chosen names go a long way towards
code readability

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode240
Lib/enum.py:240: def __call__(cls, value, names=None, *,
module_name=None, type=None):
Hmm, PEP 435 says "module" not "module_name". While the latter is more
explicit, the former is shorter and it's a rather specialized case. I'll
be on the fence about this.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode244
Lib/enum.py:244: class_name = value  # better name for a name than value
;)
I'd suggest a new method here:

_make_enum_from_names(name, member_names, ....)

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode280
Lib/enum.py:280: return cls._enum_map.copy()
why copy?

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode318
Lib/enum.py:318: enum_member = cls._enum_map[enum_name]
why don't you just search enum_map directly?

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode344
Lib/enum.py:344: @StealthProperty
OK, here a brief explanation of how _StealthProperty is actually used
*in Enum* and why

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode356
Lib/enum.py:356: if __name__ == '__main__':
remove this

http://bugs.python.org/review/17947/

From report at bugs.python.org  Fri May 10 16:03:17 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 10 May 2013 14:03:17 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368194597.22.0.625248946443.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

OK, I sent another batch of reviews through the code review system - Ethan you should've gotten an email about it.

----------

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

From report at bugs.python.org  Fri May 10 16:05:21 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Fri, 10 May 2013 14:05:21 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368194721.2.0.250087702798.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Regarding module vs. module_name for the extra param in the functional API, Guido rightly points out in issue 17941 that __module__ is the class attribute, so "module" is a consistent choice.

----------

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

From report at bugs.python.org  Fri May 10 16:42:08 2013
From: report at bugs.python.org (Alex Gaynor)
Date: Fri, 10 May 2013 14:42:08 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368196928.07.0.71842686459.issue17947@psf.upfronthosting.co.za>


Changes by Alex Gaynor <alex.gaynor at gmail.com>:


----------
nosy: +alex

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

From berker.peksag at gmail.com  Fri May 10 16:46:19 2013
From: berker.peksag at gmail.com (berker.peksag at gmail.com)
Date: Fri, 10 May 2013 14:46:19 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510144619.28734.78728@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8105/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode17
Lib/enum.py:17: 
Nit: Two blank lines. (see PEP 8 E302)

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode18
Lib/enum.py:18: class StealthProperty():
Is there a reason not to write `class StealthProperty:` (without the
brackets) here?

http://bugs.python.org/review/17947/

From report at bugs.python.org  Fri May 10 17:21:24 2013
From: report at bugs.python.org (Ethan Furman)
Date: Fri, 10 May 2013 15:21:24 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368199283.22.0.141003833512.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Incorporated comments.

----------
Added file: http://bugs.python.org/file30195/pep-0435_2.patch

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

From report at bugs.python.org  Fri May 10 17:24:58 2013
From: report at bugs.python.org (Ethan Furman)
Date: Fri, 10 May 2013 15:24:58 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368199498.14.0.50832283245.issue17947@psf.upfronthosting.co.za>


Changes by Ethan Furman <ethan at stoneleaf.us>:


----------
hgrepos:  -189

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

From zachary.ware at gmail.com  Fri May 10 17:30:54 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Fri, 10 May 2013 15:30:54 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510153054.28616.68328@psf.upfronthosting.co.za>

Just a few comments on the test module.


http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode1
Lib/test/test_enum.py:1: #!/usr/bin/python3.3
3.4

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode8
Lib/test/test_enum.py:8: print('Using Python', sys.version)
Extra output isn't very well appreciated in the test suite output.

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode54
Lib/test/test_enum.py:54: print(exc)
Since all of these above are simply creating enums without any kind of
special trickery going on, they really really shouldn't raise any
exceptions.  If they do, we should just let unittest handle them and
flag the test as a failure.  Taking out the try/excepts will also make
Question's line short enough :)

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode103
Lib/test/test_enum.py:103: '<Season.{0}: {1}>'.format(season, i))
Whitespace between methods

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode634
Lib/test/test_enum.py:634: '''stub for testing one at a time'''
This should be removed.

http://bugs.python.org/review/17947/

From report at bugs.python.org  Fri May 10 17:33:11 2013
From: report at bugs.python.org (Zachary Ware)
Date: Fri, 10 May 2013 15:33:11 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368199991.22.0.109587526433.issue17947@psf.upfronthosting.co.za>


Changes by Zachary Ware <zachary.ware at gmail.com>:


----------
nosy: +zach.ware

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

From report at bugs.python.org  Fri May 10 18:26:22 2013
From: report at bugs.python.org (Martijn Pieters)
Date: Fri, 10 May 2013 16:26:22 +0000
Subject: [docs] [issue17949] operator documentation mixup
Message-ID: <1368203182.3.0.318883699217.issue17949@psf.upfronthosting.co.za>


New submission from Martijn Pieters:

Rev 83684 (http://hg.python.org/cpython/rev/5885c02120f0) managed to move the `attrgetter()` `versionadded` and `versionchanged` notes down to the `itemgetter()` documentation instead, by moving the `itemgetter()` signature *up* above these lines.

Now the docs claim `itemgetter()` gained support for dotted attributes in version 2.6, which makes no sense, and there is another set of added and changed notes lower down in the same section.

This patch puts the `itemgetter()` signature back in the correct location.

----------
assignee: docs at python
components: Documentation
files: operator_documentation_fix.patch
keywords: patch
messages: 188846
nosy: docs at python, mjpieters
priority: normal
severity: normal
status: open
title: operator documentation mixup
versions: Python 2.7
Added file: http://bugs.python.org/file30198/operator_documentation_fix.patch

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

From report at bugs.python.org  Fri May 10 18:31:59 2013
From: report at bugs.python.org (Martijn Pieters)
Date: Fri, 10 May 2013 16:31:59 +0000
Subject: [docs] [issue16523] attrgetter and itemgetter signatures in docs
	need cleanup
In-Reply-To: <1353510966.46.0.566270540705.issue16523@psf.upfronthosting.co.za>
Message-ID: <1368203519.9.0.15883661165.issue16523@psf.upfronthosting.co.za>


Martijn Pieters added the comment:

The 2.7 patch shifted the `itemgetter()` signature to above the `attrgetter()` change and new notes.

New patch to fix that in issue #17949: http://bugs.python.org/issue17949

----------
nosy: +mjpieters

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

From report at bugs.python.org  Fri May 10 18:57:16 2013
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 10 May 2013 16:57:16 +0000
Subject: [docs] [issue17949] operator documentation mixup
In-Reply-To: <1368203182.3.0.318883699217.issue17949@psf.upfronthosting.co.za>
Message-ID: <3b6czH3b6vzQTH@mail.python.org>


Roundup Robot added the comment:

New changeset 9c93a631e95a by Ezio Melotti in branch '2.7':
#17949: fix merge glitch in itemgetter signature.  Patch by Martijn Pieters.
http://hg.python.org/cpython/rev/9c93a631e95a

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

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

From report at bugs.python.org  Fri May 10 18:57:50 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 16:57:50 +0000
Subject: [docs] [issue17949] operator documentation mixup
In-Reply-To: <1368203182.3.0.318883699217.issue17949@psf.upfronthosting.co.za>
Message-ID: <1368205070.41.0.110354567946.issue17949@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Fixed, thanks for the report and the patch!

----------
assignee: docs at python -> ezio.melotti
nosy: +ezio.melotti
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed
type:  -> enhancement

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

From report at bugs.python.org  Fri May 10 19:33:48 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 17:33:48 +0000
Subject: [docs] [issue17904] bytes should be listed as built-in function for
	2.7
In-Reply-To: <1367663679.93.0.0164308850832.issue17904@psf.upfronthosting.co.za>
Message-ID: <1368207228.14.0.176335305113.issue17904@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Here's a patch.  Do you think it should be added under the string signature too?  It will make linking easier, but it might be more confusing for users.

----------
keywords: +patch
nosy: +chris.jerdonek, ezio.melotti
stage: needs patch -> patch review
type: behavior -> enhancement
Added file: http://bugs.python.org/file30201/issue17904.diff

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

From report at bugs.python.org  Fri May 10 19:39:51 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Fri, 10 May 2013 17:39:51 +0000
Subject: [docs] [issue17468] Generator memory leak
In-Reply-To: <1363638865.27.0.0312549957802.issue17468@psf.upfronthosting.co.za>
Message-ID: <1368207590.89.0.742405301639.issue17468@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

The issue17807 patch has now been committed and should solve this issue. I would like to encourage anyone to test this change, as it is quite a significant departure from the previous semantics:
http://mail.python.org/pipermail/python-dev/2013-May/126102.html

----------
assignee: docs at python -> 
components: +Interpreter Core -Documentation
resolution:  -> duplicate
status: open -> closed
superseder:  -> Generator cleanup without tp_del

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

From report at bugs.python.org  Fri May 10 19:50:36 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Fri, 10 May 2013 17:50:36 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
In-Reply-To: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>
Message-ID: <1368208236.66.0.887481938312.issue17920@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Raymond, since this has been merged to default too in e163c13b941c, can the issue be closed or is there something else left to do?

----------
nosy: +ezio.melotti

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

From report at bugs.python.org  Fri May 10 19:55:00 2013
From: report at bugs.python.org (Ethan Furman)
Date: Fri, 10 May 2013 17:55:00 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368208499.92.0.321999639783.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

More adjustments due to review.

----------
Added file: http://bugs.python.org/file30202/pep-0435_3.patch

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

From report at bugs.python.org  Fri May 10 21:38:01 2013
From: report at bugs.python.org (paul j3)
Date: Fri, 10 May 2013 19:38:01 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1368214681.22.0.10713055322.issue14191@psf.upfronthosting.co.za>


paul j3 added the comment:

'parse_fallback_args()' function is only in the 'test_intermixed.py' file, not the patch.  It should be in the 'if __name__' section of that file, along with the modified 'exit()' method, since it is part of these testing suit, not meant to be imported.  'test_intermixed.py' is more of an example and discussion tool, not a formal test.

I added the '_fallback' optional argument because the normal exit from 'parse_args' using SystemExit is remarkably uninformative.  It's hard to distinguish between the 'fallback' errors, and the ones generated by 'parse_known_args' (that have more to do with the argument strings).  One is a programming error, the other a user generated error.

It is possible to redefine ArgumentParser.error() so it gives more information, for example by raising an Exception(message).  I have added to test_intermixed.py an alternative 'parse_fallback_args' that uses such a modified error rather than the _fallback option.  But that ends up modifying the normal parsing error generation as well.

I used the 'fallback' idea to test 'parse_intermixed_args' against the whole set 'test_argparse.py' tests.  It would nice to have a way of doing that automatically anytime other features are added to 'parse_args'.  But I can't think of a clean way of doing that.

Regarding earlier versions of these files - I do not see a way of deleting them.  

I have attached a modified test_intermixed.py that has these changes.  I also modified how 'parse_known_intermixed_args' restores the original value of self.usage, using an outer 'try:finally:' block.  I need to make a note to myself to put that in the patch.

----------
Added file: http://bugs.python.org/file30204/test_intermixed.py

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

From report at bugs.python.org  Fri May 10 21:45:39 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 10 May 2013 19:45:39 +0000
Subject: [docs] [issue17939] Misleading information about slice assignment
	in docs
In-Reply-To: <1368048699.98.0.203661524608.issue17939@psf.upfronthosting.co.za>
Message-ID: <1368215139.65.0.111265653015.issue17939@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Since range objects have a known length, that example is not enough to show 'any iterable'. However, generators do not even have a __length_hint__ and they work too.

a = [1,2,3]
a[0:1] = (i for i in range(4))
print(a)
>>> 
[0, 1, 2, 3, 2, 3]

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

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

From report at bugs.python.org  Fri May 10 21:50:20 2013
From: report at bugs.python.org (Glenn Linderman)
Date: Fri, 10 May 2013 19:50:20 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1368215420.0.0.305894140227.issue14191@psf.upfronthosting.co.za>


Glenn Linderman added the comment:

paul j3: Regarding earlier versions of these files - I do not see a way of deleting them. 

Click on edit, then there is an option to unlink. I don't know if they ever actually get deleted, but it clears out the clutter when looking for the latest version.

Will check out the newest code shortly.

----------

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

From report at bugs.python.org  Fri May 10 23:04:09 2013
From: report at bugs.python.org (Ethan Furman)
Date: Fri, 10 May 2013 21:04:09 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368219848.3.0.732047528729.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Round 4.  I wonder if I should have used two digits to number the patches.  ;)

----------
Added file: http://bugs.python.org/file30209/pep-0435_4.patch

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

From report at bugs.python.org  Sat May 11 00:39:01 2013
From: report at bugs.python.org (paul j3)
Date: Fri, 10 May 2013 22:39:01 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1368225541.72.0.704146742925.issue14191@psf.upfronthosting.co.za>


paul j3 added the comment:

I should note one caveat:

As a consequence of setting nargs to 0 for the first 'parse_know_args' step, all positional entries in the namespace get an empty list value ([]).  This is produced by 'ArgumentParser._get_values'.  With the builtin action classes this does not cause any problems.

However a custom action class might have problems with this [] value.
For example in 'test_argparse.py', TestActionUserDefined the PositionalAction class does check the values and throws an error with this [] value.

The positional arguments are removed from the namespace before it is passed on to the 2nd 'parse_known_args', so these [] in the first don't affect the final namespace.

I don't think anything about this should be added to main documentation, since it could confuse most readers.  I might add a note of warning to the code itself.

----------

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

From report at bugs.python.org  Sat May 11 05:03:35 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 11 May 2013 03:03:35 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368241415.14.0.341369098099.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

By the way, if anyone is willing to take on the documentation, that could be of great help. It shouldn't be very hard since PEP 435 is extremely detailed. The stdlib .rst doc would be the descriptions from PEP 435 plus a reference of the exposed classes which is pretty minimal.

We'll need the documentation patch available by the time the code is done reviewing.

----------

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

From report at bugs.python.org  Sat May 11 05:09:06 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sat, 11 May 2013 03:09:06 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368241746.54.0.0191259394505.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Two requests:

1. Lose the frame hack. With the explicit "module=__name__" API available, the implicit fragile magic isn't necessary and leads to Enum instances that may or may not support pickling depending on the implementation. Better to say "if you use the functional API without passing the module name, your Enum instances won't support pickling".

2. Mike Bayer (SQL Alchemy author) has requested the ability to derive a custom metaclass that turns off the Enums-with-members-are-final subclassing restriction (relaxing the rule that members of an enum are instances of that enum to "members of an enum are instances of that enum, or one of its parent enums", but otherwise keeping the same behaviour as the standard enums).

Barry would probably appreciate this capability, too ;)

We don't need to explicitly support this for the initial patch (besides, as I read the current code, you can get something like this already just by overriding EnumMeta._get_mixins), but we may want to revisit it as a supported subclassing API at some point in the future.

----------
nosy: +ncoghlan

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

From report at bugs.python.org  Sat May 11 05:26:11 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 11 May 2013 03:26:11 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368241746.54.0.0191259394505.issue17947@psf.upfronthosting.co.za>
Message-ID: <CAF-Rda9A1v1TD9YQAyY389OvbszkCy3so9C_6mAnt784JnnDTw@mail.gmail.com>


Eli Bendersky added the comment:

On Fri, May 10, 2013 at 8:09 PM, Nick Coghlan <report at bugs.python.org>wrote:

>
> Nick Coghlan added the comment:
>
> Two requests:
>
> 1. Lose the frame hack. With the explicit "module=__name__" API available,
> the implicit fragile magic isn't necessary and leads to Enum instances that
> may or may not support pickling depending on the implementation. Better to
> say "if you use the functional API without passing the module name, your
> Enum instances won't support pickling".
>
>
Strong -1 from me on this. The PEP has been accepted. Feel free to raise
this for discussion if you want to change the decision. With all due
respect to IronPython, most users can write simpler code and have pickling
work just fine.
_______

----------

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

From report at bugs.python.org  Sat May 11 05:28:32 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 11 May 2013 03:28:32 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368241746.54.0.0191259394505.issue17947@psf.upfronthosting.co.za>
Message-ID: <CAF-Rda9QNxHewsQa0LCcOxrjubOmPGH9ju-mMSV6jZfUb9HjBQ@mail.gmail.com>


Eli Bendersky added the comment:

> 2. Mike Bayer (SQL Alchemy author) has requested the ability to derive a
> custom metaclass that turns off the Enums-with-members-are-final
> subclassing restriction (relaxing the rule that members of an enum are
> instances of that enum to "members of an enum are instances of that enum,
> or one of its parent enums", but otherwise keeping the same behaviour as
> the standard enums).
>

Nick, after you read the whole code, please consider whether it's not
already complex enough even without catering to every other need out there.

----------

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

From report at bugs.python.org  Sat May 11 08:52:40 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Sat, 11 May 2013 06:52:40 +0000
Subject: [docs] [issue17920] Documentation: "complete ordering" should be
	"total	ordering"
In-Reply-To: <1367871771.49.0.425606433106.issue17920@psf.upfronthosting.co.za>
Message-ID: <1368255160.89.0.815126503908.issue17920@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

It can be closed now.
Thanks for the reminder.

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

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

From report at bugs.python.org  Sat May 11 09:23:44 2013
From: report at bugs.python.org (Glenn Linderman)
Date: Sat, 11 May 2013 07:23:44 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1368257024.35.0.829212688566.issue14191@psf.upfronthosting.co.za>


Glenn Linderman added the comment:

OK, I've been running with the new code most the day, and it seems functional in my testing.

I only "sort of" follow your discussion about the "custom action class" caveat, probably because I haven't used "custom action classes"... I tried once, but failed to achieve my goal, as it was more ambitious than they presently support. If the [] value is significantly problematical in some manner, could positional nargs be set to a sentinal value that would avoid the assignment of the [] value? I realize that would require code changes in some other function or functions, in addition to the added new functions, so that would make the patch a bit more intrusive.

If _fallback helps some folks with understanding errors clearly, I won't object to it. I guess it would only be programmers that would be confused, because they would be the ones interpreting the errors... and with adequate testing, should fix the programming errors before the users get a chance to be confused.

So maybe your next .patch will be ready to ship!

----------

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

From report at bugs.python.org  Sat May 11 15:58:44 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sat, 11 May 2013 13:58:44 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368280724.65.0.936927151551.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

The accepted PEP states that the frame hack should be removed: "To support pickling of these enums, the module name can be specified using the module keyword-only argument."

Ergo, if you don't specify it, they cannot be pickled. Explicit is better than implicit, and this hack should not propagate beyond namedtuple (it should actually be deprecated in namedtuple as well).

As far as the second point goes, I had already reviewed the PEP implementation before making the comment (that's why I am reasonably sure you can already do it just by overriding _get_mixins). I see it as similar to the changes that were already made to support autonumbered subtypes.

However, also note that I said we should wait before doing anything about providing a supported mechanism for that customisation. I've now created issue 17954 to cover a possible refactoring and documentation of that part of the implementation.

----------

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

From report at bugs.python.org  Sat May 11 17:59:22 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Sat, 11 May 2013 15:59:22 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
Message-ID: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>


New submission from A.M. Kuchling:

I read through the 3.x Functional HOWTO, and it only seems to require a few minor updates.  The attached patch:

* adds a forward link to skip the theoretical discussion in the first section.
* remove stray extra comma
* clarify what filterfalse() is the opposite of.
* (more significant) Describe compress(), the combinatoric functions in their own section, and accumulate().

----------
assignee: docs at python
components: Documentation
files: functional.txt
messages: 188931
nosy: akuchling, docs at python
priority: low
severity: normal
stage: patch review
status: open
title: Minor updates to Functional HOWTO
type: enhancement
versions: Python 3.4
Added file: http://bugs.python.org/file30219/functional.txt

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

From report at bugs.python.org  Sat May 11 19:10:42 2013
From: report at bugs.python.org (Guido van Rossum)
Date: Sat, 11 May 2013 17:10:42 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368292242.21.0.755004457231.issue17947@psf.upfronthosting.co.za>


Guido van Rossum added the comment:

Sorry everyone, the frame hack needs to stay.  This is not negotiable.

----------
nosy: +gvanrossum

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

From report at bugs.python.org  Sat May 11 20:12:08 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 11 May 2013 18:12:08 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
In-Reply-To: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>
Message-ID: <1368295928.12.0.513176059038.issue17955@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/issue17955>
_______________________________________

From ezio.melotti at gmail.com  Sat May 11 20:20:12 2013
From: ezio.melotti at gmail.com (ezio.melotti at gmail.com)
Date: Sat, 11 May 2013 18:20:12 -0000
Subject: [docs] Minor updates to Functional HOWTO (issue 17955)
Message-ID: <20130511182012.28734.92362@psf.upfronthosting.co.za>


http://bugs.python.org/review/17955/diff/8120/Doc/howto/functional.rst
File Doc/howto/functional.rst (right):

http://bugs.python.org/review/17955/diff/8120/Doc/howto/functional.rst#newcode886
Doc/howto/functional.rst:886: (1,), (2,), (3,), (4,), (5,)
This example doesn't seem too useful to me, maybe something like
itertools.combinations('abcd', 2) is better.
Showing how different functions behave given the same input might also
be a good idea, since it shows how the output changes (e.g. if there are
repetitions, if the order matters).

http://bugs.python.org/review/17955/diff/8120/Doc/howto/functional.rst#newcode894
Doc/howto/functional.rst:894: *iterable* returned them.  For example, in
the examples above 1 is
I would add a comma after above.

http://bugs.python.org/review/17955/diff/8120/Doc/howto/functional.rst#newcode896
Doc/howto/functional.rst:896: :func:`itertools.permutations(iterable,
N=None) <itertools.permutations>`,
'N' is actually 'r'.

http://bugs.python.org/review/17955/

From report at bugs.python.org  Sat May 11 20:38:21 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sat, 11 May 2013 18:38:21 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368297500.93.0.937180949293.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Why we need two ways to do it? If "module=__name__" is available, what's the rationale for providing the option of leaving it out when pickling support is required? (The only times the frame hack will work to enable pickling, the explicit fix will also work).

----------

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

From report at bugs.python.org  Sat May 11 21:10:46 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 11 May 2013 19:10:46 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368299446.38.0.717430522814.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Ethan, something is wrong with _StealthProperty. Well, two things. First, it's way too general and can be cut to just what Enum needs. Second, this is enough to make the tests pass:

class _StealthProperty():
    """
    Returns the value in the instance, or the virtual attribute on the class.

    A virtual attribute is one that is looked up by __getattr__, as opposed to
    one that lives in __class__.__dict__

    """

    def __init__(self, fget):
        self.fget = fget

    def __get__(self, obj, objtype=None):
        return self.fget(obj)

    def __set__(self, obj, value):
        raise AttributeError("can't set attribute")

    def __delete__(self, obj):
        raise AttributeError("can't delete attribute")

Now  this is fishy because __get__ gets obj=None when called on a class and therefore self.fget(obj) raises an exception. But this gets caught somewhere in your code or tests and ignored. However, the right thing is still returned. I didn't have more time to investigate, but this must be cleaned out.

----------

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

From report at bugs.python.org  Sat May 11 21:11:30 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 11 May 2013 19:11:30 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368299490.03.0.339200892123.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Also, your test must run within the regrtest framework. Currently I get:

./python -mtest.regrtest test_enum
[1/1] test_enum
test test_enum failed -- Traceback (most recent call last):
  File "/home/eliben/python-src/default/Lib/test/test_enum.py", line 245, in test_pickle_enum_function_with_module
    self.assertIs(Question.who, loads(dumps(Question.who)))
_pickle.PicklingError: Can't pickle <enum 'Question'>: attribute lookup __main__.Question failed

1 test failed:
    test_enum

----------

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

From report at bugs.python.org  Sat May 11 22:06:53 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 11 May 2013 20:06:53 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1368302813.43.0.0461521299344.issue14097@psf.upfronthosting.co.za>


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


----------
nosy: +akuchling

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

From report at bugs.python.org  Sat May 11 23:11:04 2013
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 11 May 2013 21:11:04 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <3b7LYg3wYVz7Ljc@mail.python.org>


Roundup Robot added the comment:

New changeset 1b595399e070 by Benjamin Peterson in branch 'default':
simplify #17947 test with weakrefs
http://hg.python.org/cpython/rev/1b595399e070

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

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

From report at bugs.python.org  Sat May 11 23:24:25 2013
From: report at bugs.python.org (Benjamin Peterson)
Date: Sat, 11 May 2013 21:24:25 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368307465.83.0.944660643548.issue17947@psf.upfronthosting.co.za>


Benjamin Peterson added the comment:

I copied the wrong bug number. should have been #17927. sorry

----------
nosy: +benjamin.peterson

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

From report at bugs.python.org  Sat May 11 23:38:04 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 11 May 2013 21:38:04 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368308284.22.0.923443552262.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Benjamin, I guess you can just unlink the message from the issue? [and then your clarification, and when again this message from me ;-)]

----------

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

From report at bugs.python.org  Sat May 11 23:41:08 2013
From: report at bugs.python.org (Benjamin Peterson)
Date: Sat, 11 May 2013 21:41:08 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368308468.89.0.931620799851.issue17947@psf.upfronthosting.co.za>


Changes by Benjamin Peterson <benjamin at python.org>:


----------
Removed message: http://bugs.python.org/msg188954

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

From report at bugs.python.org  Sat May 11 23:41:25 2013
From: report at bugs.python.org (Benjamin Peterson)
Date: Sat, 11 May 2013 21:41:25 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368308485.33.0.889468995297.issue17947@psf.upfronthosting.co.za>


Changes by Benjamin Peterson <benjamin at python.org>:


----------
Removed message: http://bugs.python.org/msg188955

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

From report at bugs.python.org  Sat May 11 23:41:32 2013
From: report at bugs.python.org (Benjamin Peterson)
Date: Sat, 11 May 2013 21:41:32 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368308492.33.0.197251905511.issue17947@psf.upfronthosting.co.za>


Changes by Benjamin Peterson <benjamin at python.org>:


----------
Removed message: http://bugs.python.org/msg188956

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

From report at bugs.python.org  Sun May 12 00:02:13 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sat, 11 May 2013 22:02:13 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368309732.89.0.161501092783.issue16805@psf.upfronthosting.co.za>


Tshepang Lekhonkhobe added the comment:

ping

----------

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

From report at bugs.python.org  Sun May 12 00:03:03 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 11 May 2013 22:03:03 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368309783.52.0.629025408116.issue16805@psf.upfronthosting.co.za>


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


----------
nosy: +ezio.melotti
stage:  -> patch review
type:  -> behavior
versions:  -Python 3.2

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

From report at bugs.python.org  Sun May 12 00:09:15 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sat, 11 May 2013 22:09:15 +0000
Subject: [docs] [issue15130] remove redundant paragraph in socket howto
In-Reply-To: <1340311752.3.0.940656841103.issue15130@psf.upfronthosting.co.za>
Message-ID: <1368310155.06.0.45166204239.issue15130@psf.upfronthosting.co.za>


Tshepang Lekhonkhobe added the comment:

ping

----------

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

From report at bugs.python.org  Sun May 12 00:20:43 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sat, 11 May 2013 22:20:43 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
Message-ID: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>


New submission from Tshepang Lekhonkhobe:

The first part looks incomplete, and the second part is outdated. The whole paragraph doesn't add much value I believe, so should just go.

----------
assignee: docs at python
components: Documentation
files: diff
messages: 188962
nosy: docs at python, tshepang
priority: normal
severity: normal
status: open
title: remove outdated (and unexcellent) paragraph in whatsnew
versions: Python 2.6, Python 2.7, Python 3.2, Python 3.3, Python 3.4
Added file: http://bugs.python.org/file30227/diff

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

From report at bugs.python.org  Sun May 12 00:27:28 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sat, 11 May 2013 22:27:28 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368311248.04.0.835550366937.issue16805@psf.upfronthosting.co.za>


Tshepang Lekhonkhobe added the comment:

@ezio why remove 3.2 from applicable versions

----------

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

From report at bugs.python.org  Sun May 12 00:29:53 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 11 May 2013 22:29:53 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368311393.55.0.33055921146.issue16805@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

3.2 only gets security fixes.

----------

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

From report at bugs.python.org  Sun May 12 00:31:57 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 11 May 2013 22:31:57 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
In-Reply-To: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>
Message-ID: <1368311517.49.0.796426705453.issue17957@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

The patch you uploaded is wrong.

----------
nosy: +ezio.melotti
stage:  -> needs patch
type:  -> enhancement
versions:  -Python 3.2

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

From report at bugs.python.org  Sun May 12 07:25:21 2013
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 12 May 2013 05:25:21 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368336320.95.0.52763307146.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Eli,

The original _StealthProperty checked to see if it was being called on instance or class, and if it was the class it invoked __getattr__ to attempt a lookup for an enum member.  Your version does not check, but, ironically, the exception raised is AttributeError, and so Python is calling __getattr__ anyway and so finds the virtual enum member.

While this is cool, and it works, I think it's much less mysterious, magical, and downright confusing to keep the original behavior and call __getattr__ from _StealthProperty.  On the other hand, it might make somebody think, and that's always good, so I'm happy to leave it your way.

----------

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

From report at bugs.python.org  Sun May 12 07:39:20 2013
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 12 May 2013 05:39:20 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368337160.55.0.895944472021.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

regrtest framework now supported  (had to change the module name I was passing in from '__main__' to __name__).

----------

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

From report at bugs.python.org  Sun May 12 08:25:55 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 12 May 2013 06:25:55 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368339955.73.0.263511969426.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Guido has promised an explanation for why he wants to keep the frame hack once he is back at work next week. To help him target that reply appropriately for my concrete objections to retaining it, I'd like to explain a bit more about why I think it's fundamentally impossible to create a robust stack inspection mechanism for implicit pickling support. Even if a dedicated mechanism for it is added, the information the interpreter needs to make a sensible reliable decision simply isn't there.

Consider the following:

    # In utils.py
    def enum_helper(name, prefix, fields):
        if isinstance(fields, str): fields = fields.split()
        e = Enum(name, (prefix + field for field in fields))
        return e

    # In some other module
    from utils import enum_helper
    MyEnum = enum_helper(MyEnum, "st_", "mtime atime ctime")

This breaks the frame hack, but would work correctly if enum_helper was redesigned to accept an explicit module name, or if we adopted something like the "name binding protocol" discussed on Python ideas.

If we adopted a simplistic rule of ignoring function scopes and only look at module and class scopes, then we break the semantics of the global keyword.

I consider the frame hack fundamentally broken, since there's currently no way the interpreter can distinguish between an incidental assignment (like the "e = Enum..." call in util.py) and a destination assignment (like the "MyEnum = enum_helper..." call), and if we *do* add a different syntax for "this supports pickling" assignments (like the def name = expr syntax on Python ideas), then a name binding protocol makes more sense than implicit contextual magic.

----------

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

From report at bugs.python.org  Sun May 12 08:52:47 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 12 May 2013 06:52:47 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368341567.62.0.492464716804.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

I also created issue 17959 to track a legitimate concern with the current aliasing design, without impacting incorporation of the accepted PEP.

----------

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

From report at bugs.python.org  Sun May 12 11:41:23 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sun, 12 May 2013 09:41:23 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1368311393.55.0.33055921146.issue16805@psf.upfronthosting.co.za>
Message-ID: <CAA77j2AwdLNnPK5-RMHAVUB-2jLXBo76qFHrLdZ_3i=7cDefZw@mail.gmail.com>


Tshepang Lekhonkhobe added the comment:

Ok. I thought doc fixes were exempt. Strange policy there.

----------

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

From report at bugs.python.org  Sun May 12 11:42:13 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sun, 12 May 2013 09:42:13 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
In-Reply-To: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>
Message-ID: <1368351733.79.0.345606060974.issue17957@psf.upfronthosting.co.za>


Changes by Tshepang Lekhonkhobe <tshepang at gmail.com>:


Removed file: http://bugs.python.org/file30227/diff

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

From report at bugs.python.org  Sun May 12 11:42:29 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sun, 12 May 2013 09:42:29 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
In-Reply-To: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>
Message-ID: <1368351749.31.0.936535878671.issue17957@psf.upfronthosting.co.za>


Changes by Tshepang Lekhonkhobe <tshepang at gmail.com>:


Added file: http://bugs.python.org/file30230/diff

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

From report at bugs.python.org  Sun May 12 11:43:17 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sun, 12 May 2013 09:43:17 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
In-Reply-To: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>
Message-ID: <1368351797.91.0.179436202496.issue17957@psf.upfronthosting.co.za>


Tshepang Lekhonkhobe added the comment:

uploaded the correct one; sori

----------

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

From report at bugs.python.org  Sun May 12 12:02:03 2013
From: report at bugs.python.org (Georg Brandl)
Date: Sun, 12 May 2013 10:02:03 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368352922.96.0.652109722524.issue16805@psf.upfronthosting.co.za>


Georg Brandl added the comment:

Please do not comment on policies if you don't understand our release system.

----------

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

From report at bugs.python.org  Sun May 12 12:59:53 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 12 May 2013 10:59:53 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368356393.3.0.125711914449.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Another post-incorporation proposal (issue 17961) relating to the values used for the functional API.

----------

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

From report at bugs.python.org  Sun May 12 13:24:44 2013
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 12 May 2013 11:24:44 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368357884.5.0.421027540351.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

After more thought, I think we should leave the shortened version of _StealthProperty as is.

The reasoning being that if _StealthProperty does the __getattr__ lookup itself, and fails, it will return an AttributeError... and then Python will use __getattr__ again to try and find the attribute.

So I'll add a comment into the shortened version and leave it at that.

----------

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

From report at bugs.python.org  Sun May 12 14:17:47 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 12 May 2013 12:17:47 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368361067.01.0.42031520252.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Nick, could you open a separate issue for the frame hack discussion, like you did for the other things? You can make this one depend on it, if you feel it's a "blocker", but let's please not intermix more discussion here.

----------

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

From report at bugs.python.org  Sun May 12 14:54:50 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 12 May 2013 12:54:50 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368363290.7.0.625084021145.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Ethan, I pasted the minimized version to point out the problem; I fully agree it should do the getattr lookup because otherwise it's very difficult to understand what's going on. Let's keep exceptions for actual exceptional situations and explicitly code the normal path.

Also, _MemberOrProperty is probably a more descriptive name.

----------

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

From report at bugs.python.org  Sun May 12 15:09:36 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 12 May 2013 13:09:36 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368364176.41.0.861689473179.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Eli: done, created as #17963

----------

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

From report at bugs.python.org  Sun May 12 16:25:00 2013
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 12 May 2013 14:25:00 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368368699.61.0.987758075805.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Here's the latest patch.

Note that the functional API portion is broken, and I'll get back to that this evening.  Please only comment on the working code.  ;)

I'll make that _MemborOrProperty name change then as well.

----------
Added file: http://bugs.python.org/file30231/pep-0435.05.patch

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

From report at bugs.python.org  Mon May 13 01:24:59 2013
From: report at bugs.python.org (Yogesh Chaudhari)
Date: Sun, 12 May 2013 23:24:59 +0000
Subject: [docs] [issue12634] Random Remarks in class documentation
In-Reply-To: <1311575810.71.0.0727071558423.issue12634@psf.upfronthosting.co.za>
Message-ID: <1368401099.69.0.378346605548.issue12634@psf.upfronthosting.co.za>


Changes by Yogesh Chaudhari <mr.yogesh at gmail.com>:


----------
hgrepos:  -188

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

From report at bugs.python.org  Mon May 13 06:08:36 2013
From: report at bugs.python.org (Paul Jurczak)
Date: Mon, 13 May 2013 04:08:36 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
Message-ID: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>


New submission from Paul Jurczak:

This may be too subjective, but here it goes:

PEP 8 discourages vertical alignment: "More than one space around an assignment (or other) operator to align it with another", but contrary to this rule, vertical alignment is used many times in the same paragraph, e.g.:
Yes: spam(1)
No:  spam (1)
If vertical alignment is so evil, the above should be changed to:
Yes: spam(1)
No: spam (1)

Disclosure: I use vertical alignment in my code quite often.

http://www.python.org/dev/peps/pep-0008/

----------
assignee: docs at python
components: Documentation
messages: 189093
nosy: docs at python, pauljurczak
priority: normal
severity: normal
status: open
title: Lack of consistency in PEP 8 -- Style Guide for Python Code
type: enhancement
versions: Python 2.7, Python 3.3

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

From report at bugs.python.org  Mon May 13 08:18:47 2013
From: report at bugs.python.org (Georg Brandl)
Date: Mon, 13 May 2013 06:18:47 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368425927.46.0.130402916621.issue17966@psf.upfronthosting.co.za>


Georg Brandl added the comment:

Interesting observation :)  However, the alignment in the PEP is in prose, not code.

----------
assignee: docs at python -> 
nosy: +georg.brandl

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

From report at bugs.python.org  Mon May 13 08:47:27 2013
From: report at bugs.python.org (paul j3)
Date: Mon, 13 May 2013 06:47:27 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1368427647.32.0.150499958354.issue14191@psf.upfronthosting.co.za>


Changes by paul j3 <ajipanca at gmail.com>:


Removed file: http://bugs.python.org/file29880/mixed.patch

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

From report at bugs.python.org  Mon May 13 10:24:58 2013
From: report at bugs.python.org (Paul Jurczak)
Date: Mon, 13 May 2013 08:24:58 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368433498.77.0.443045911581.issue17966@psf.upfronthosting.co.za>


Paul Jurczak added the comment:

Correct, it is in mixed prose and code. However, the underlying principle in this PEP is: "guidelines provided here are intended to improve the readability of code". The author used vertical alignment (for mixed prose and code), because of its superior readability. Many others had found that aligning long columns of data improves readability, from newsprint and spreadsheets to multiple assignment statements.

----------

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

From report at bugs.python.org  Mon May 13 12:09:13 2013
From: report at bugs.python.org (Antoine Pitrou)
Date: Mon, 13 May 2013 10:09:13 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368439753.89.0.0856293570326.issue17966@psf.upfronthosting.co.za>


Changes by Antoine Pitrou <pitrou at free.fr>:


----------
nosy: +gvanrossum

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

From report at bugs.python.org  Mon May 13 15:29:39 2013
From: report at bugs.python.org (Guido van Rossum)
Date: Mon, 13 May 2013 13:29:39 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368451779.74.0.148925028479.issue17966@psf.upfronthosting.co.za>


Guido van Rossum added the comment:

This is a silly argument.

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

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

From report at bugs.python.org  Mon May 13 16:08:16 2013
From: report at bugs.python.org (Barry A. Warsaw)
Date: Mon, 13 May 2013 14:08:16 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368454096.54.0.727516163139.issue17966@psf.upfronthosting.co.za>


Changes by Barry A. Warsaw <barry at python.org>:


----------
nosy: +barry

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

From report at bugs.python.org  Mon May 13 16:13:30 2013
From: report at bugs.python.org (Barry A. Warsaw)
Date: Mon, 13 May 2013 14:13:30 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368454410.44.0.463670627278.issue17966@psf.upfronthosting.co.za>


Barry A. Warsaw added the comment:

It's not *particularly* silly[1], but I think that with Government backing, he could make it very silly.

[1] I mean, the right hand side isn't silly at all and the left hand side merely does a forward aerial half turn every alternative assignment.

----------

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

From report at bugs.python.org  Mon May 13 19:05:36 2013
From: report at bugs.python.org (Phil Connell)
Date: Mon, 13 May 2013 17:05:36 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368464736.77.0.188530213298.issue17947@psf.upfronthosting.co.za>


Changes by Phil Connell <pconnell at gmail.com>:


----------
nosy: +isoschiz, pconnell

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

From report at bugs.python.org  Mon May 13 20:03:09 2013
From: report at bugs.python.org (Paul Jurczak)
Date: Mon, 13 May 2013 18:03:09 +0000
Subject: [docs] [issue17966] Lack of consistency in PEP 8 -- Style Guide for
	Python	Code
In-Reply-To: <1368418116.32.0.199767602115.issue17966@psf.upfronthosting.co.za>
Message-ID: <1368468189.87.0.276372816665.issue17966@psf.upfronthosting.co.za>


Paul Jurczak added the comment:

I admit, it is somewhat silly, but not entirely silly.

----------

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

From report at bugs.python.org  Mon May 13 20:32:50 2013
From: report at bugs.python.org (Guido van Rossum)
Date: Mon, 13 May 2013 18:32:50 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368469970.49.0.194089170746.issue17947@psf.upfronthosting.co.za>


Guido van Rossum added the comment:

Here's the promised explanation why I want to keep the getframe hack.  I'm sure it won't satisfy everyone, but this will have to do.

There are two parts to my argument.  TL;DR: (a) by implementing this hack, we will maximize user happiness; (b) I expect that all Python implementations can provide the functionality needed.

So why does this maximize user happiness?  First of all, enums are such simple objects that it's a disgrace to have an enum that isn't picklable.  But most users are lazy and lack imagination, so if they find they have to do extra work to ensure that something is picklable, they will make a judgement call -- is the extra work to make it picklable worth it?  Unfortunately they will try to make this judgment call in a fraction of a second, and they limited imagination they may well say "I can't imagine ever pickling this", save themselves the work, and move on.  If you think more than a second about the decision, you've wasted more time than it takes to type "module=__name__", so it's going to be a split-second decision.  But nevertheless, having to think about it and typing it is a distraction, and when you're "in the zone" you may prefer to spend your time thinking about the perfect names for your enum class and values rather than the red tape of making in picklable.

So, in my mind, it's a given that there will be many enums that are missing the module=__name__ keyword argument.  Moreover, it's likely that most of the time this will be fine -- you can get through most days just fine without ever reading or writing a pickle.  (For example, I very much doubt that I've ever pickled one of the flag values used by the socket module to define e.g. the address family, socket type, or protocol.)

But now you enter a different phase of your project, or one of your collaborators does, or perhaps you've released your code on PyPI and one of your users does.  So someone tries to pickle some class instance that happens to contain an unpicklable enum.  That's not a great experience.  Pickling and unpickling errors are often remarkably hard to debug.  (Especially the latter, so I have privately admonished Ethan to ensure that if the getframe hack doesn't work, the pickle failure should happen at pickling time, not at unpickle time.)  Once you've tracked down the source, you have to figure out the fix -- hopefully just typing the error message into Google will link back to a StackOverflow answer explaining the need to say "module=__name__".  But the damage is done, especially if the person encountering the pickling error is not the original author of the code defining the enum.  (Often the person downloading and using a package from PyPI has less advanced Python knowledge than the package author, so they may have a hard time debugging the situation.)

You can see how having the getframe hack in place makes life more pleasant for many people -- the package user won't have to debug the pickling problem, and the package author won't have to deal with the bug report and fix.

But what about other Python implementations?  Well, TBH, they have plenty of other issues.  The reality is that you can't take a large package that hasn't been tested on Jython, or IronPython, or PyPy, and expect it to just work on any of those.  Sure, things are getting better.  But there are still tons of differences between the various Python implementations (as there are between different versions of CPython), and whether you like it or not, CPython is still the Python version of choice for most people.  The long and short of it is that porting any significant package to another implementation is a bit of work, and keeping the port working probably requires adding some set of additional line items to the style guide used by its developers -- don't use feature X, don't depend on behavior Y, always use pattern Z...


However, I don't expect that "always pass module=__name__ when using the enum convenience API" won't have to be added to that list.  sys._getframe() is way more powerful than what's needed.  Even on platforms where sys._getframe() is unimplementable (or disabled by default in favor of a 10% speedup), it should still be possible to provide an API that *just* gets the module name of the caller, at least in case the call site is top-level module code (and for anything else, the getframe hack doesn't work anyway).  After all, we're talking about a full Python implementation, right?  That's a dynamic language with lots of introspection APIs, and any implementation worth its salt will have to deal with that, even if full-fledged sys._getframe() is explicitly excluded.

So I propose that we use sys._getframe() for the time being, and the authors of Jython, IronPython and PyPy can get together and figure out how to implement something like sys.get_calling_module_name().  They have plenty of time -- at least until they pledge support for Python 3.4.  To make it easy for them we should probably add that API to CPython 3.4.  And it's fine with me if the function only works if the caller is top-level code in a module.

Which reminds me.  Nick offered another use case where using sys._getframe() breaks down: a wrapper function that constructs an enum for its caller.  First of all, I think this is a pretty rare use case.  But additionally, that wrapper could just use sys.get_calling_module_name(), and everything would be fine.

PS. Whoever adds sys.get_calling_module_name() to CPython, please pick a shorter name. :-)

----------

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

From report at bugs.python.org  Mon May 13 20:40:23 2013
From: report at bugs.python.org (Alex Gaynor)
Date: Mon, 13 May 2013 18:40:23 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368470423.07.0.858190323531.issue17947@psf.upfronthosting.co.za>


Alex Gaynor added the comment:

>From PyPy's perspective we don't really care what you name this particular bikeshed, and it's probably not that important to us (in this particular case).

As far as I know IronPython is the only Python VM that doesn't have _getframe() support by default (you need a CLI flag at startup, IIRC). In PyPy calling _getframe (right now) has a negative performance impact, but it's local to wherever you're calling it, so unless you create Enum in frequent loops (as opposed to just once at module level), this doesn't really matter to us.

If someone wants to invent a more narrow, tailored API for stack introspection, logging is a much better target (right now each call to logging.{info,error,etc.} calls _getframe(), which does have a real performance impact. (We'll eventually invent enough engineering to fix this ourselves, but in the meantime if somewhere were to pain this bikeshed, we certainly wouldn't object ;)).

----------

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

From report at bugs.python.org  Mon May 13 22:17:26 2013
From: report at bugs.python.org (Zachary Ware)
Date: Mon, 13 May 2013 20:17:26 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368476246.75.0.836362831038.issue17947@psf.upfronthosting.co.za>


Zachary Ware added the comment:

I've come across something in the implementation here that I'd like some clarification on.  What is the purpose of overriding __dir__ in Enum and EnumMeta?  It doesn't change any behavior that I'm aware of, just makes things look a little nicer when someone calls dir() on their Enum.  And, in fact, it can make things a little confusing.  For example:

>>> class Test(enum.Enum):
...     foo = 1
...     bar = 2
...     baz = 3
...
>>> dir(Test)
['__class__', '__doc__', '__members__', 'bar', 'baz', 'foo']
>>> Test.mro
<built-in method mro of EnumMeta object at 0x01D94D20>

This brings up another interesting case:

>>> class Test2(enum.Enum):
...     mro = 1
...     _create = 2
...
>>> dir(Test2)
['__class__', '__doc__', '__members__', '_create', 'mro']
>>> Test2.__members__
mappingproxy(OrderedDict([('mro', <Test2.mro: 1>), ('_create', <Test2._create: 2>)]))
>>> Test2['mro']
<Test2.mro: 1>
>>> Test2.mro
<built-in method mro of EnumMeta object at 0x01D90210>
>>> Test2._create
<bound method type._create of <class 'enum.EnumMeta'>>
>>>

>From using "mro" or "_create", I would have expected either ValueError or for them to work properly.  I don't know whether this should be fixed (one way or the other), documented, or just left alone; those kind of names really shouldn't ever be used anyway.  It's something I stumbled across, though, and I just wanted to make sure that those who do have opinions that matter are aware of it :)

----------

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

From report at bugs.python.org  Tue May 14 01:21:26 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 13 May 2013 23:21:26 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368469970.49.0.194089170746.issue17947@psf.upfronthosting.co.za>
Message-ID: <CADiSq7dZOa7kV37SDDjBK_SiAgSF8gLLDpizEBVO659KtX0tug@mail.gmail.com>


Nick Coghlan added the comment:

Thanks Guido, now that I fully understand your reasoning, I can accept that
this is a valid "practicality beats purity" situation.

----------

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

From report at bugs.python.org  Tue May 14 05:11:08 2013
From: report at bugs.python.org (xiaobing jiang)
Date: Tue, 14 May 2013 03:11:08 +0000
Subject: [docs] [issue17972] inspect module leak docs
Message-ID: <1368501068.91.0.677640111487.issue17972@psf.upfronthosting.co.za>


New submission from xiaobing jiang:

the inspect module leak docs.
all these functions have no doc.
getlineno
getabsfile
getblock
formatannotation
walktree
findsource
indentsize
getargs
formatannotationrelativeto
classify_class_attrs

----------
assignee: docs at python
components: Documentation
messages: 189193
nosy: docs at python, s7v7nislands at gmail.com
priority: normal
severity: normal
status: open
title: inspect module leak docs
type: enhancement
versions: Python 3.3

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

From report at bugs.python.org  Tue May 14 16:14:28 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Tue, 14 May 2013 14:14:28 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
In-Reply-To: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>
Message-ID: <1368540868.86.0.359112531446.issue17955@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

Updated version of the patch:

* uses 'r' instead of 'N'.
* removes the old outline and some notes at the end.
* minor rewriting.

----------
Added file: http://bugs.python.org/file30257/functional.txt

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

From report at bugs.python.org  Wed May 15 04:28:28 2013
From: report at bugs.python.org (Ethan Furman)
Date: Wed, 15 May 2013 02:28:28 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368584907.94.0.365614056161.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Got the pickle issues worked out.  Added super to the metaclass' __new__.  Checking for illegal names of members and raising ValueError if any are found (I know, I know, safety checks!  But such an enum is broken from the getgo so I see no reason to allow those names through).

Thanks everyone for the excellent feed back.  I really appreciate it.  Hopefully we're almost done!  :)

----------
assignee:  -> ethan.furman
Added file: http://bugs.python.org/file30265/pep-0435.06.patch

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

From report at bugs.python.org  Wed May 15 05:08:25 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 15 May 2013 03:08:25 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
In-Reply-To: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>
Message-ID: <1368587305.64.0.879042689259.issue17955@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

LGTM.

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

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

From report at bugs.python.org  Wed May 15 23:23:42 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Wed, 15 May 2013 21:23:42 +0000
Subject: [docs] [issue17972] inspect module docs omits many functions
In-Reply-To: <1368501068.91.0.677640111487.issue17972@psf.upfronthosting.co.za>
Message-ID: <1368653022.43.0.98174614549.issue17972@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

I do not know what you mean by 'leak docs' so I changed the title to something that makes more sense. It is possible that these functions are considered private to the module, but then their names should be preceded by '_', or else there should be an '__all__' list that omits them. So the omission may be a mistake. I do not know.

----------
nosy: +terry.reedy
stage:  -> needs patch
title: inspect module leak docs -> inspect module docs omits many functions

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

From report at bugs.python.org  Wed May 15 23:30:23 2013
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Wed, 15 May 2013 21:30:23 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
Message-ID: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>


New submission from Fred L. Drake, Jr.:

The captured_stderr and captured_stdin context managers aren't documented, and should be.

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 189311
nosy: docs at python, fdrake
priority: normal
severity: normal
stage: needs patch
status: open
title: test.support.captured_stderr, captured_stdin not documented
type: enhancement
versions: Python 3.3, Python 3.4, Python 3.5

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

From report at bugs.python.org  Thu May 16 04:33:23 2013
From: report at bugs.python.org (xiaobing jiang)
Date: Thu, 16 May 2013 02:33:23 +0000
Subject: [docs] [issue17972] inspect module docs omits many functions
In-Reply-To: <1368501068.91.0.677640111487.issue17972@psf.upfronthosting.co.za>
Message-ID: <1368671603.92.0.263604877295.issue17972@psf.upfronthosting.co.za>


xiaobing jiang added the comment:

when I read the memory_profiler source code, I find it using inspect.getblock(). so I check the doc, but can't find the function's doc. 

these functions are found not in doc. I want to known which function should in doc or not? in inspect module has no __all__ variable.

sorry for poor english!

----------

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

From report at bugs.python.org  Thu May 16 14:54:40 2013
From: report at bugs.python.org (Arfrever Frehtes Taifersar Arahesis)
Date: Thu, 16 May 2013 12:54:40 +0000
Subject: [docs] [issue17589] Make documentation about macros in C API
	explicit about	rvalue vs statement
In-Reply-To: <1364758755.79.0.998719447408.issue17589@psf.upfronthosting.co.za>
Message-ID: <1368708880.73.0.547087212819.issue17589@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/issue17589>
_______________________________________

From report at bugs.python.org  Thu May 16 22:36:42 2013
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 16 May 2013 20:36:42 +0000
Subject: [docs] [issue17700] Update Curses HOWTO for 3.4
In-Reply-To: <1365719687.97.0.644773548697.issue17700@psf.upfronthosting.co.za>
Message-ID: <1368736602.07.0.802271897182.issue17700@psf.upfronthosting.co.za>


STINNER Victor added the comment:

> Applied to 3.3 and 3.4.  I'll leave this issue open
> for a week so that Victor can comment on Unicode/wide-characters.

I don't know (n)curses, but I tried to improve the curses module of Python. I added an encoding attribute which is the locale encoding by default, so it should work without special configuration. But it's good to know what the default encoding is. (It was UTF-8 on older Python 3 release, maybe in Python < 3.3.)

I also added functions like unget_wch() and get_wch().

The problem is that unget_wch() and get_wch() are not always available, it depends on the platform. If I remember correctly, it depends if libreadline is linked to libncursesw (and not libncurses).

Ah yes, and the Python curses modules uses Unicode versions of C curses functions if available. It is still possible to use thes bytes versions if you pass bytes strings. For example:

 * window.addstr("abc"): use *add_wstr() functions if available, *addstr() otherwise
 * window.addstr(b"abc"): always use *addstr() functions

I don't know enough the C libncursesw library to write an HOWTO or something like that.

I just would like to say that you should prefer get_wch() over getch() if get_wch() is available. But I don't understand exactly how curses behave with control characters ("keys"?) like "up" or "left".

----------

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

From report at bugs.python.org  Fri May 17 12:49:04 2013
From: report at bugs.python.org (Donald Stufft)
Date: Fri, 17 May 2013 10:49:04 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368787744.0.0.559769872588.issue17947@psf.upfronthosting.co.za>


Changes by Donald Stufft <donald.stufft at gmail.com>:


----------
nosy: +dstufft

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

From report at bugs.python.org  Fri May 17 13:19:40 2013
From: report at bugs.python.org (Donald Stufft)
Date: Fri, 17 May 2013 11:19:40 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1368789579.9.0.458423505099.issue17947@psf.upfronthosting.co.za>


Donald Stufft added the comment:

Small nitpick, weakref is imported but not used in the latest patch.

----------

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

From report at bugs.python.org  Fri May 17 16:31:08 2013
From: report at bugs.python.org (R. David Murray)
Date: Fri, 17 May 2013 14:31:08 +0000
Subject: [docs] [issue15125] argparse: positional arguments containing - in
	name not	handled well
In-Reply-To: <1340292847.64.0.123942573403.issue15125@psf.upfronthosting.co.za>
Message-ID: <1368801068.64.0.206359433224.issue15125@psf.upfronthosting.co.za>


Changes by R. David Murray <rdmurray at bitdance.com>:


----------
nosy: +paul.j3

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

From report at bugs.python.org  Fri May 17 18:23:46 2013
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 17 May 2013 16:23:46 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
In-Reply-To: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>
Message-ID: <1368807826.39.0.647380752.issue17957@psf.upfronthosting.co.za>


?ric Araujo added the comment:

I don?t see any benefit at all in changing this paragraph of a whatsnew document.  It was useful and accurate for the 2.6 release, it?s still accessible for the record, let?s keep it.

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

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

From report at bugs.python.org  Sat May 18 04:12:56 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sat, 18 May 2013 02:12:56 +0000
Subject: [docs] [issue17957] remove outdated (and unexcellent) paragraph in
	whatsnew
In-Reply-To: <1368310843.47.0.442601461472.issue17957@psf.upfronthosting.co.za>
Message-ID: <1368843176.53.0.438106590081.issue17957@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Agreed.

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

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

From report at bugs.python.org  Sat May 18 17:45:02 2013
From: report at bugs.python.org (Simon Nicolussi)
Date: Sat, 18 May 2013 15:45:02 +0000
Subject: [docs] [issue18007] CookieJar expects request objects with
	origin_req_host	attribute instead of method
Message-ID: <1368891902.97.0.967044954731.issue18007@psf.upfronthosting.co.za>


New submission from Simon Nicolussi:

A fix for a DeprecationWarning (#17678) had the unfortunate side effect of changing the expected interface of the request object higher up in the call stack.

For example, the documentation for CookieJar.add_cookie_header(request) states that the request object must support the methods get_full_url(), get_host(), get_type(), unverifiable(), get_origin_req_host(), has_header(), get_header(), header_items(), and add_unredirected_header(). The patch for #17678, however, changes the requirement for a get_origin_req_host() method to an origin_req_host attribute.

This breaks at least one notable third-party library (Kenneth Reitz' Requests).

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 189523
nosy: docs at python, orsenthil, sinic
priority: normal
severity: normal
status: open
title: CookieJar expects request objects with origin_req_host attribute instead of method
type: behavior
versions: Python 3.3

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

From report at bugs.python.org  Sat May 18 20:47:28 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sat, 18 May 2013 18:47:28 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1368902848.34.0.835276540282.issue17844@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Any opinions?

----------

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

From report at bugs.python.org  Sun May 19 01:18:18 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 18 May 2013 23:18:18 +0000
Subject: [docs] [issue17902] Document that _elementtree C API cannot use
	custom	TreeBuilder for iterparse or IncrementalParser
In-Reply-To: <1367614578.64.0.34953241054.issue17902@psf.upfronthosting.co.za>
Message-ID: <1368919098.59.0.977991821926.issue17902@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Aaron, could you please sign the PSF CLA (http://www.python.org/psf/contrib/contrib-form/) - this will make it accepting patches from you easier.

Other than that, I agree it's a legit patch. The alternative would be to fix _elementtree to actually allow arbitrary TreeBuilders there, although I'm not sure it's worth the effort.

----------

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

From report at bugs.python.org  Sun May 19 10:19:09 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 19 May 2013 08:19:09 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
Message-ID: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>


New submission from Serhiy Storchaka:

b32decode() documentation says: "A TypeError is raised if s were incorrectly padded or if there are non-alphabet characters present in the string."

b32decode() docstring says: "binascii.Error is raised if the input is incorrectly padded or if there are non-alphabet characters present in the input."

Actually binascii.Error (which is a ValueError subtype) is raised if the input is incorrectly padded and TypeError is raised if there are non-alphabet characters present in the input.

At least 2 of 3 (documentation, docstring and implementation) should be corrected.

Base32 support was originally added in 3cc0d8fd4e2b (TypeError was used everywhere) and then modified in eb45f85c4c79 (TypeError was partially changed to binascii.Error).

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 189571
nosy: barry, docs at python, gvanrossum, serhiy.storchaka
priority: normal
severity: normal
status: open
title: Inconsistency between b32decode() documentation, docstring and code
type: behavior
versions: Python 3.3, Python 3.4

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

From report at bugs.python.org  Sun May 19 12:11:22 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 19 May 2013 10:11:22 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1368958282.85.0.792373415567.issue18011@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Here is a patch which changes TypeError to binascii.Error in b32decode() and fixes the documentation and tests.

----------
keywords: +patch
stage:  -> patch review
Added file: http://bugs.python.org/file30310/b32decode_exception.patch

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

From report at bugs.python.org  Sun May 19 12:14:26 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 19 May 2013 10:14:26 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1368958466.65.0.562178951303.issue18011@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Here is a patch which changes TypeError to binascii.Error in b32decode() and fixes the documentation and tests.

----------
Added file: http://bugs.python.org/file30311/b32decode_exception.patch

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

From report at bugs.python.org  Sun May 19 12:15:54 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 19 May 2013 10:15:54 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1368958554.89.0.931286531323.issue18011@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
Removed message: http://bugs.python.org/msg189577

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

From report at bugs.python.org  Sun May 19 12:16:05 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 19 May 2013 10:16:05 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1368958565.72.0.824569181206.issue18011@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


Removed file: http://bugs.python.org/file30311/b32decode_exception.patch

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

From report at bugs.python.org  Sun May 19 13:09:13 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 19 May 2013 11:09:13 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1368961753.01.0.721870020987.issue17844@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

I like this, both because it quite clearly defines the encode and decode directions, and allows notes the more direct entry points if the codec isn't being specified as an input string.

So +1 from me.

----------

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

From report at bugs.python.org  Sun May 19 13:31:36 2013
From: report at bugs.python.org (Marc-Andre Lemburg)
Date: Sun, 19 May 2013 11:31:36 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1368961753.01.0.721870020987.issue17844@psf.upfronthosting.co.za>
Message-ID: <5198B80F.4090705@egenix.com>


Marc-Andre Lemburg added the comment:

Not a bad idea. More information is always better when it comes to
documentation :-)

----------

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

From report at bugs.python.org  Sun May 19 14:21:39 2013
From: report at bugs.python.org (R. David Murray)
Date: Sun, 19 May 2013 12:21:39 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368966098.96.0.577684692629.issue16805@psf.upfronthosting.co.za>


R. David Murray added the comment:

Tshepang: see the 'Development Cycle' section of the devguide.  Only security related commits are allowed to security branches, and since the docs are part of the source tree, that means no doc commits.  One reason for this is the same reason we only have one maintenance release (ignoring 2.7, it is an exception), and is a matter of practicality: reducing the load on developers.

----------
nosy: +r.david.murray

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

From report at bugs.python.org  Sun May 19 15:28:24 2013
From: report at bugs.python.org (Tshepang Lekhonkhobe)
Date: Sun, 19 May 2013 13:28:24 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368970104.06.0.901635239436.issue16805@psf.upfronthosting.co.za>


Tshepang Lekhonkhobe added the comment:

@murray thanks for the clarification; I saw that part of the devguide, but wasn't sure if doc fixes/improvements were exempt (even if not mentioned)

----------

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

From report at bugs.python.org  Sun May 19 19:08:38 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 19 May 2013 17:08:38 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1368983317.6.0.419322951055.issue14097@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Here is an updated patch.

----------
Added file: http://bugs.python.org/file30312/issue14097-3.diff

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

From report at bugs.python.org  Sun May 19 19:24:09 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Sun, 19 May 2013 17:24:09 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1368984249.42.0.594318690019.issue14097@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

Please restore the section "A value can be assigned to several variables simultaneously".  This is easy to teach in this context and there's no other good place to put it.

Also, I'm unclear why you took out the Mark Lemburg's section on Unicode.

----------

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

From report at bugs.python.org  Sun May 19 19:44:26 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 19 May 2013 17:44:26 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1368985466.18.0.546302957148.issue14097@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

> Please restore the section "A value can be assigned to several
> variables simultaneously".

The reason for removing it are:
 * generally it's not really useful/used IMHO;
 * it has potentially confusing side effects (e.g. x = y = 0 is the same as x = 0; y = 0, but a = b = [] is not the same as a = []; b = []);
 * and more confusing side effects (http://mail.python.org/pipermail/python-dev/2012-November/122552.html ;);

IOW I think that teaching this (especially at this point of the tutorial where you can't/shouldn't yet explain the side effects) does more harm than good.
It could be mentioned later in the tutorial when object identity is explained in more detail (I'm planning to work on this next), and should be also covered in the language reference (if it's not there already).

> Also, I'm unclear why you took out the Mark Lemburg's section
> on Unicode.

I'm planning to write something about Unicode when bytes are introduced.  That section has been written with Python 2 in mind, where byte strings are the default but "there are also Unicode strings".  For Python 3, users already naturally associate strings with text and explaining the text/bytes dichotomy and Unicode can be postponed.

----------

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

From report at bugs.python.org  Sun May 19 20:49:18 2013
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Sun, 19 May 2013 18:49:18 +0000
Subject: [docs] [issue16805] when building docs on Debian 7 --> ERROR: Error
	in	"note" directive
In-Reply-To: <1356739435.76.0.304211925624.issue16805@psf.upfronthosting.co.za>
Message-ID: <1368989358.47.0.389587565814.issue16805@psf.upfronthosting.co.za>


?ric Araujo added the comment:

An additional reason is that docs of branches in security mode are not rebuilt and published, so changes would be useless.

----------

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

From report at bugs.python.org  Mon May 20 02:38:39 2013
From: report at bugs.python.org (=?utf-8?q?Marc_Br=C3=BCnink?=)
Date: Mon, 20 May 2013 00:38:39 +0000
Subject: [docs] [issue18017] ctypes.PyDLL documentation
Message-ID: <1369010319.69.0.913023030404.issue18017@psf.upfronthosting.co.za>


New submission from Marc Br?nink:

The documentation for is not very clear regarding the usage of CDLL and PyDLL. Especially it is not obvious that you should use PyDLL whenever you call any function of the Python/C API. Since calling a Python/C API function without owning the GIL will most likely cause latent segfaults, I think it warrants a warning box in section 16.17.2.2 and maybe also somewhere prominent in http://docs.python.org/dev/c-api/intro.html.

For section 16.17.2.2 I would put a box next the decription of CDLL saying something like: "The Python GIL is released before a function call. It is not safe to call any Pyhon/C API function within the loaded library without acquiring the GIL first. Thus, if the loaded library calls functions of the Python/C API, for example in case it creates and returns a new Python object, and does not manually acquire and release the GIL, use PyDLL instead."

----------
assignee: docs at python
components: Documentation
messages: 189629
nosy: Marc.Br?nink, docs at python
priority: normal
severity: normal
status: open
title: ctypes.PyDLL documentation
versions: Python 3.5

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

From report at bugs.python.org  Mon May 20 04:15:31 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Mon, 20 May 2013 02:15:31 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1369016131.18.0.555810416194.issue14097@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

Please add the "x = y = z = 0" example back.  It doesn't improve the tutorial to dumb it down or to leave out basic knowledge.  You may not like the feature but it is a long standing part of the core language.

----------

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

From report at bugs.python.org  Mon May 20 04:27:24 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 20 May 2013 02:27:24 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1369016843.94.0.248259972953.issue14097@psf.upfronthosting.co.za>


Ezio Melotti added the comment:

Is it OK if I add it back to the next page, when I explain object identity?

----------

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

From report at bugs.python.org  Mon May 20 04:30:48 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Mon, 20 May 2013 02:30:48 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <1369017048.74.0.537128796073.issue14097@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

> Is it OK if I add it back to the next page, 
> when I explain object identity?

Yes.  That would work.

----------

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

From report at bugs.python.org  Mon May 20 07:14:26 2013
From: report at bugs.python.org (Roundup Robot)
Date: Mon, 20 May 2013 05:14:26 +0000
Subject: [docs] [issue14097] Improve the "introduction" page of the tutorial
In-Reply-To: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
Message-ID: <3bDSvk0MCKzRwP@mail.python.org>


Roundup Robot added the comment:

New changeset 796d1371605d by Ezio Melotti in branch '3.3':
#14097: improve the "introduction" page of the tutorial.
http://hg.python.org/cpython/rev/796d1371605d

New changeset 42dda22a6f8c by Ezio Melotti in branch 'default':
#14097: merge with 3.3.
http://hg.python.org/cpython/rev/42dda22a6f8c

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

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

From report at bugs.python.org  Mon May 20 13:47:51 2013
From: report at bugs.python.org (Ethan Furman)
Date: Mon, 20 May 2013 11:47:51 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1369050471.67.0.120789620152.issue18011@psf.upfronthosting.co.za>


Changes by Ethan Furman <ethan at stoneleaf.us>:


----------
nosy: +ethan.furman

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

From report at bugs.python.org  Mon May 20 15:21:26 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 20 May 2013 13:21:26 +0000
Subject: [docs] [issue14009] Clearer documentation for cElementTree
In-Reply-To: <1329233203.38.0.944311933185.issue14009@psf.upfronthosting.co.za>
Message-ID: <1369056086.11.0.246558896945.issue14009@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

The ET docs have been significantly revamped in 3.3

I don't think cET needs to be documented. It's just confusing.

----------
resolution:  -> wont fix
stage: commit review -> committed/rejected
status: open -> closed

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

From report at bugs.python.org  Mon May 20 16:15:21 2013
From: report at bugs.python.org (Roundup Robot)
Date: Mon, 20 May 2013 14:15:21 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
In-Reply-To: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>
Message-ID: <3bDhvr4GPWz7Lm2@mail.python.org>


Roundup Robot added the comment:

New changeset 20409786cf8e by Andrew Kuchling in branch 'default':
#17955: minor updates to Functional howto
http://hg.python.org/cpython/rev/20409786cf8e

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

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

From report at bugs.python.org  Mon May 20 16:15:43 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Mon, 20 May 2013 14:15:43 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
In-Reply-To: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>
Message-ID: <1369059343.39.0.949645822266.issue17955@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <lists at amk.ca>:


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

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

From report at bugs.python.org  Mon May 20 16:16:03 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Mon, 20 May 2013 14:16:03 +0000
Subject: [docs] [issue17955] Minor updates to Functional HOWTO
In-Reply-To: <1368287962.52.0.951274382256.issue17955@psf.upfronthosting.co.za>
Message-ID: <1369059363.91.0.229061613606.issue17955@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <lists at amk.ca>:


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

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

From storchaka at gmail.com  Mon May 20 20:53:23 2013
From: storchaka at gmail.com (storchaka at gmail.com)
Date: Mon, 20 May 2013 18:53:23 -0000
Subject: [docs] Inconsistency between b32decode() documentation,
 docstring and code (issue 18011)
Message-ID: <20130520185323.3384.75291@psf.upfronthosting.co.za>

Reviewers: stoneleaf,


http://bugs.python.org/review/18011/diff/8191/Lib/base64.py
File Lib/base64.py (right):

http://bugs.python.org/review/18011/diff/8191/Lib/base64.py#newcode225
Lib/base64.py:225: raise binascii.Error('Non-base32 digit found')
On 2013/05/20 13:47:00, stoneleaf wrote:
> Should we add a `from None` here to suppress the double exception
traceback?

Indeed.



Please review this at http://bugs.python.org/review/18011/

Affected files:
  Doc/library/base64.rst
  Lib/base64.py
  Lib/test/test_base64.py


diff -r 1b5ef05d6ced Doc/library/base64.rst
--- a/Doc/library/base64.rst	Sun May 19 11:49:32 2013 +0300
+++ b/Doc/library/base64.rst	Sun May 19 13:02:47 2013 +0300
@@ -103,7 +103,7 @@
    digit 0 is always mapped to the letter O).  For security purposes the default is
    ``None``, so that 0 and 1 are not allowed in the input.
 
-   The decoded byte string is returned.  A :exc:`TypeError` is raised if *s* were
+   The decoded byte string is returned.  A :exc:`binascii.Error` is raised if *s* were
    incorrectly padded or if there are non-alphabet characters present in the
    string.
 
diff -r 1b5ef05d6ced Lib/base64.py
--- a/Lib/base64.py	Sun May 19 11:49:32 2013 +0300
+++ b/Lib/base64.py	Sun May 19 13:02:47 2013 +0300
@@ -222,7 +222,7 @@
             for c in quanta:
                 acc = (acc << 5) + b32rev[c]
         except KeyError:
-            raise TypeError('Non-base32 digit found')
+            raise binascii.Error('Non-base32 digit found')
         decoded += acc.to_bytes(5, 'big')
     # Process the last, partial quanta
     if padchars:
diff -r 1b5ef05d6ced Lib/test/test_base64.py
--- a/Lib/test/test_base64.py	Sun May 19 11:49:32 2013 +0300
+++ b/Lib/test/test_base64.py	Sun May 19 13:02:47 2013 +0300
@@ -244,8 +244,8 @@
             eq(base64.b32decode(data, True), res)
             eq(base64.b32decode(data.decode('ascii'), True), res)
 
-        self.assertRaises(TypeError, base64.b32decode, b'me======')
-        self.assertRaises(TypeError, base64.b32decode, 'me======')
+        self.assertRaises(binascii.Error, base64.b32decode, b'me======')
+        self.assertRaises(binascii.Error, base64.b32decode, 'me======')
 
         # Mapping zero and one
         eq(base64.b32decode(b'MLO23456'), b'b\xdd\xad\xf3\xbe')
@@ -262,9 +262,11 @@
             eq(base64.b32decode(data_str, map01=map01), res)
             eq(base64.b32decode(data, map01=map01_str), res)
             eq(base64.b32decode(data_str, map01=map01_str), res)
+            self.assertRaises(binascii.Error, base64.b32decode, data)
+            self.assertRaises(binascii.Error, base64.b32decode, data_str)
 
     def test_b32decode_error(self):
-        for data in [b'abc', b'ABCDEF==']:
+        for data in [b'abc', b'ABCDEF==', b'==ABCDEF']:
             with self.assertRaises(binascii.Error):
                 base64.b32decode(data)
             with self.assertRaises(binascii.Error):



From report at bugs.python.org  Mon May 20 23:06:37 2013
From: report at bugs.python.org (Jakub Wilk)
Date: Mon, 20 May 2013 21:06:37 +0000
Subject: [docs] [issue18026] Typo in ctypes documentation
Message-ID: <1369083997.94.0.835709293593.issue18026@psf.upfronthosting.co.za>


New submission from Jakub Wilk:

http://docs.python.org/3/library/ctypes.html#finding-shared-libraries reads:
"If wrapping a shared library with ctypes, it may be better to determine the shared library name at development type, and hardcode ..."

Shouldn't that be "... at development time, ..."?

----------
assignee: docs at python
components: Documentation
messages: 189693
nosy: docs at python, jwilk
priority: normal
severity: normal
status: open
title: Typo in ctypes documentation

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

From report at bugs.python.org  Mon May 20 23:33:45 2013
From: report at bugs.python.org (Roundup Robot)
Date: Mon, 20 May 2013 21:33:45 +0000
Subject: [docs] [issue18026] Typo in ctypes documentation
In-Reply-To: <1369083997.94.0.835709293593.issue18026@psf.upfronthosting.co.za>
Message-ID: <3bDtdh2cpmz7Llc@mail.python.org>


Roundup Robot added the comment:

New changeset 7937f5c56924 by Ned Deily in branch '2.7':
Issue #18026: fix ctypes doc typo
http://hg.python.org/cpython/rev/7937f5c56924

New changeset cac83b62b0de by Ned Deily in branch '3.3':
Issue #18026: fix ctypes doc typo
http://hg.python.org/cpython/rev/cac83b62b0de

New changeset 1f388bbc8917 by Ned Deily in branch 'default':
Issue #18026: merge
http://hg.python.org/cpython/rev/1f388bbc8917

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

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

From report at bugs.python.org  Mon May 20 23:34:49 2013
From: report at bugs.python.org (Ned Deily)
Date: Mon, 20 May 2013 21:34:49 +0000
Subject: [docs] [issue18026] Typo in ctypes documentation
In-Reply-To: <1369083997.94.0.835709293593.issue18026@psf.upfronthosting.co.za>
Message-ID: <1369085689.41.0.268223325888.issue18026@psf.upfronthosting.co.za>


Ned Deily added the comment:

It should. Thanks!

----------
nosy: +ned.deily
resolution:  -> fixed
stage:  -> committed/rejected
status: open -> closed
versions: +Python 2.7, Python 3.2, Python 3.3

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

From report at bugs.python.org  Tue May 21 12:20:00 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 21 May 2013 10:20:00 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369131600.76.0.237810331745.issue17844@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

> Not a bad idea.

How about implementation? Here is updated patches for 3.x and 2.7. Note that in 2.7 I split codecs table as in 3.x.

----------
Added file: http://bugs.python.org/file30331/doc_codecs_impl.patch

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

From report at bugs.python.org  Tue May 21 12:20:49 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 21 May 2013 10:20:49 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369131649.45.0.332805901967.issue17844@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


Added file: http://bugs.python.org/file30332/doc_codecs_impl-2.7.patch

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

From report at bugs.python.org  Tue May 21 12:21:20 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 21 May 2013 10:21:20 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369131680.28.0.970661054324.issue17844@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


Removed file: http://bugs.python.org/file30013/doc_codecs_impl.patch

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

From report at bugs.python.org  Tue May 21 13:14:27 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Tue, 21 May 2013 11:14:27 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369134867.38.0.625712907705.issue17844@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

I like the idea of splitting the table in 2.7 rather than using a result type column. However, the two intro paragraphs need a bit of work. How does the following sound:

1. Create a new subheading at the same level as the current "Standard Encodings" heading: "Python Specific Encodings"

2. Split out rot-13 to its own table in Python 2.7 as well

3. Under the new subheading, have the following text introducing the tables:

----
A number of predefined codecs are specific to Python, so their codec names have no meaning outside Python. These are listed in the tables below based on the expected input and output types (note that while text encodings are the most common use case for codecs, the underlying codec infrastructure supports arbitrary data transforms rather than just text encodings).  For asymmetric codecs, the stated purpose describes the encoding direction.

The following codecs provide text-to-binary encoding and binary-to-text decoding, similar to the Unicode text encodings.
----
The following codecs provide binary-to-binary encoding and decoding.
----
The following codecs provide text-to-text encoding and decoding.
----

----------

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

From report at bugs.python.org  Tue May 21 14:39:04 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 21 May 2013 12:39:04 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369139944.85.0.436449420415.issue17844@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

> However, the two intro paragraphs need a bit of work.

Yes, it's a help which I needed. Thank you.

However your wording is not entirely correct. In 2.7 binary-to-binary codecs and rot-13 works with Unicode strings (only ascii-compatible) as with bytes strings.

>>> u'Python'.encode('base64')
'UHl0aG9u\n'
>>> u'UHl0aG9u'.decode('base64')
'Python'
>>> u'Python\u20ac'.encode('base64')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/serhiy/py/cpython-2.7/Lib/encodings/base64_codec.py", line 24, in base64_encode
    output = base64.encodestring(input)
  File "/home/serhiy/py/cpython-2.7/Lib/base64.py", line 315, in encodestring
    pieces.append(binascii.b2a_base64(chunk))
UnicodeEncodeError: 'ascii' codec can't encode character u'\u20ac' in position 6: ordinal not in range(128)

Rot-13 works as common text-to-binary encoding (encode returns str, decode returns unicode).

>>> u'Python'.encode('rot13')
'Clguba'
>>> u'Python'.decode('rot13')
u'Clguba'
>>> 'Python'.encode('rot13')
'Clguba'
>>> 'Python'.decode('rot13')
u'Clguba'
>>> u'Python\u20ac'.encode('rot13')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/serhiy/py/cpython-2.7/Lib/encodings/rot_13.py", line 17, in encode
    return codecs.charmap_encode(input,errors,encoding_map)
UnicodeEncodeError: 'charmap' codec can't encode character u'\u20ac' in position 6: character maps to <undefined>
>>> u'Python\u20ac'.decode('rot13')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/serhiy/py/cpython-2.7/Lib/encodings/rot_13.py", line 20, in decode
    return codecs.charmap_decode(input,errors,decoding_map)
UnicodeEncodeError: 'ascii' codec can't encode character u'\u20ac' in position 6: ordinal not in range(128)

----------

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

From report at bugs.python.org  Tue May 21 15:12:11 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Tue, 21 May 2013 13:12:11 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369141931.45.0.202348318231.issue17844@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

While the Python 2 text model was almost certainly a necessary transition step to full unicode support, it is things like this that highlight how fundamentally broken implicit conversion turned out to be at a conceptual level :P

Perhaps the following would work for 2.7 then (with rot-13 in the first table), with footnotes added to cover the quirks of the implicit type conversions between str and unicode:

----
A number of predefined codecs are specific to Python, so their codec names have no meaning outside Python. These are listed in the tables below based on the expected input and output types (note that while text encodings are the most common use case for codecs, the underlying codec infrastructure supports arbitrary data transforms rather than just text encodings).  For asymmetric codecs, the stated purpose describes the encoding direction.

The following codecs provide unicode-to-str encoding [#1] and str-to-unicode decoding [#2], similar to the Unicode text encodings.
----
The following codecs provide str-to-str encoding and decoding [#2].
----

.. [#1] str objects are also accepted as input in place of unicode objects. They are implicitly converted to unicode by decoding them using the default encoding. If this conversion fails, it may lead to encoding operations raising :exc:`UnicodeDecodeError`.

.. [#2] unicode objects are also accepted as input in place of str objects. They are implicitly converted to str by encoding them using the default encoding. If this conversion fails, it may lead to decoding operations raising :exc:`UnicodeEncodeError`.

----------

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

From report at bugs.python.org  Tue May 21 16:28:18 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 21 May 2013 14:28:18 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369146498.57.0.886563224728.issue17844@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Thank you Nick. Here is an updated patch for 2.7.

----------
Added file: http://bugs.python.org/file30333/doc_codecs_impl-2.7_2.patch

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

From report at bugs.python.org  Tue May 21 16:30:16 2013
From: report at bugs.python.org (Florent Xicluna)
Date: Tue, 21 May 2013 14:30:16 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369146616.52.0.915572761564.issue17844@psf.upfronthosting.co.za>


Changes by Florent Xicluna <florent.xicluna at gmail.com>:


----------
nosy: +flox

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

From report at bugs.python.org  Tue May 21 16:32:19 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 21 May 2013 14:32:19 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369146739.52.0.231516677821.issue17844@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


Removed file: http://bugs.python.org/file30332/doc_codecs_impl-2.7.patch

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

From report at bugs.python.org  Tue May 21 19:48:48 2013
From: report at bugs.python.org (Simon Nicolussi)
Date: Tue, 21 May 2013 17:48:48 +0000
Subject: [docs] [issue18007] CookieJar expects request objects with
	origin_req_host	attribute instead of method
In-Reply-To: <1368891902.97.0.967044954731.issue18007@psf.upfronthosting.co.za>
Message-ID: <1369158528.77.0.699793996341.issue18007@psf.upfronthosting.co.za>


Simon Nicolussi added the comment:

Requests 1.2.1 has been released to address this issue. An origin_req_host property has been added to the request object as a workaround.

The original problem of mismatched documentation and behaviour still persists.

----------

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

From report at bugs.python.org  Wed May 22 07:58:22 2013
From: report at bugs.python.org (Carlos Nepomuceno)
Date: Wed, 22 May 2013 05:58:22 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
Message-ID: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>


New submission from Carlos Nepomuceno:

It[1] says:
"Since str.format() is quite new, a lot of Python code still uses the % operator. However, because this old style of formatting will eventually be removed from the language, str.format() should generally be used."

[1] http://docs.python.org/2/tutorial/inputoutput.html#old-string-formatting

----------
assignee: docs at python
components: Documentation
messages: 189791
nosy: Carlos.Nepomuceno, docs at python
priority: normal
severity: normal
status: open
title: The Python Tutorial says % string formatting will be removed
versions: Python 2.7

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

From report at bugs.python.org  Wed May 22 08:09:53 2013
From: report at bugs.python.org (Senthil Kumaran)
Date: Wed, 22 May 2013 06:09:53 +0000
Subject: [docs] [issue18007] CookieJar expects request objects with
	origin_req_host	attribute instead of method
In-Reply-To: <1368891902.97.0.967044954731.issue18007@psf.upfronthosting.co.za>
Message-ID: <1369202993.19.0.942147082331.issue18007@psf.upfronthosting.co.za>


Senthil Kumaran added the comment:

Hello Simon,

Thanks for bringing this to attention. Since get_origin_req_host has been under deprecation was a release, I thought it was safe to remove that. Agree that documentation of "cookiejar" methods, which had a dependency on the change should have been fixed.

Here is patch attempting to do that. If this is okay, I shall go with committing this change in 3.3 and 3.4.

----------
assignee: docs at python -> orsenthil
keywords: +patch
stage:  -> patch review
versions: +Python 3.4
Added file: http://bugs.python.org/file30336/18007.patch

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

From report at bugs.python.org  Wed May 22 08:32:10 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 22 May 2013 06:32:10 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <1369204330.13.0.231473974237.issue18031@psf.upfronthosting.co.za>


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


----------
nosy: +ezio.melotti
type:  -> enhancement
versions: +Python 3.3, Python 3.4

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

From report at bugs.python.org  Wed May 22 09:42:44 2013
From: report at bugs.python.org (=?utf-8?q?Martin_v=2E_L=C3=B6wis?=)
Date: Wed, 22 May 2013 07:42:44 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <1369208564.17.0.815422936464.issue18031@psf.upfronthosting.co.za>


Martin v. L?wis added the comment:

Can you please provide some context for this report?

On the abstract, I agree that there is an error in the tutorial: it is not decided whether the % formatting will be eventually removed, and I would also personally disagree with the recommendation to prefer .format.

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

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

From report at bugs.python.org  Wed May 22 10:11:34 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Wed, 22 May 2013 08:11:34 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369210294.09.0.797021409126.issue17844@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Thanks Serhiy, that version looks great.

----------

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

From report at bugs.python.org  Wed May 22 12:01:01 2013
From: report at bugs.python.org (Carlos Nepomuceno)
Date: Wed, 22 May 2013 10:01:01 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <1369216861.06.0.0543861815413.issue18031@psf.upfronthosting.co.za>


Carlos Nepomuceno added the comment:

According to what I have been told at python-list at python.org str.__mod__() is not going to be deprecated and that seems to be a myth created by Python's own documentation.

I do remember to have read previously in another page that it would be deprecated but that seems to be already corrected. Today I just found it in the tutorial.

----------

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

From report at bugs.python.org  Wed May 22 13:16:56 2013
From: report at bugs.python.org (Ned Batchelder)
Date: Wed, 22 May 2013 11:16:56 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <1369221416.74.0.239675824813.issue18031@psf.upfronthosting.co.za>


Changes by Ned Batchelder <ned at nedbatchelder.com>:


----------
nosy: +nedbat

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

From report at bugs.python.org  Wed May 22 13:58:43 2013
From: report at bugs.python.org (Abafei)
Date: Wed, 22 May 2013 11:58:43 +0000
Subject: [docs] [issue18032] set methods should specify whether they
	consume	iterators "lazily"
Message-ID: <1369223923.83.0.620034016791.issue18032@psf.upfronthosting.co.za>


New submission from Abafei:

It says here (http://docs.python.org/2/library/stdtypes.html#set-types-set-frozenset) that some of the set methods take iterables as a parameter.

Usually, the expected behavior is for a iterator consumer to consume only as much data as it needs. For example, for the code `any(itertools.repeat(True))`, the code will complete speedily, in contrast to when all() is used instead of any(), in which case the code will go forever.

A least some of the set methods have semantics such that they can consume only some of the input; for example, "issubset" only needs to make sure that all of the items in the set are in the iterable, and once this is the case, it can return "True".

However in such a case, the methods will *still* go forever.

The docs should specify that this is the case, to disambiguate the semantics.

(Tested on Python 3.2.3 and 2.7.3).

----------
assignee: docs at python
components: Documentation
messages: 189806
nosy: Abafei, docs at python
priority: normal
severity: normal
status: open
title: set methods should specify whether they consume iterators "lazily"
type: behavior
versions: Python 2.7, Python 3.2

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

From report at bugs.python.org  Wed May 22 14:36:17 2013
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 22 May 2013 12:36:17 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <3bFtcc2RZ3z7Ljr@mail.python.org>


Roundup Robot added the comment:

New changeset 85c04fdaa404 by Serhiy Storchaka in branch '2.7':
Issue #17844: Refactor a documentation of Python specific encodings.
http://hg.python.org/cpython/rev/85c04fdaa404

New changeset 039dc6dd2bc0 by Serhiy Storchaka in branch '3.3':
Issue #17844: Add links to encoders and decoders for bytes-to-bytes codecs.
http://hg.python.org/cpython/rev/039dc6dd2bc0

New changeset 9afdd88fe33a by Serhiy Storchaka in branch 'default':
Issue #17844: Add links to encoders and decoders for bytes-to-bytes codecs.
http://hg.python.org/cpython/rev/9afdd88fe33a

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

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

From report at bugs.python.org  Wed May 22 14:40:01 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Wed, 22 May 2013 12:40:01 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369226401.55.0.470968332929.issue17844@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Thank you Nick. It's mainly your patch.

Do you want to foreport your changes (a "Python Specific Encodings" subheading and followed paragraph) to 3.x?

----------

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

From report at bugs.python.org  Wed May 22 16:50:57 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Wed, 22 May 2013 14:50:57 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369234257.91.0.14776864806.issue17844@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

That sounds like a good idea. Yay for not needing those arcane footnotes, though :)

----------

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

From report at bugs.python.org  Wed May 22 17:01:26 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Wed, 22 May 2013 15:01:26 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369234886.32.0.0955834482446.issue17844@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/issue17844>
_______________________________________

From report at bugs.python.org  Wed May 22 17:12:38 2013
From: report at bugs.python.org (Jough Dempsey)
Date: Wed, 22 May 2013 15:12:38 +0000
Subject: [docs] [issue18033] Example for Profile Module shows incorrect
	method
Message-ID: <1369235558.14.0.532987051887.issue18033@psf.upfronthosting.co.za>


New submission from Jough Dempsey:

The example on this page:
http://docs.python.org/2/library/profile.html?highlight=pstats#profile.Profile

Shows:

import cProfile, pstats, io
pr = cProfile.Profile()
pr.enable()
... do something ...
pr.disable()
s = io.StringIO()
ps = pstats.Stats(pr, stream=s)
ps.print_results()

Where "ps.print_results()" should be "ps.print_stats()"

----------
assignee: docs at python
components: Documentation
messages: 189823
nosy: docs at python, jough
priority: normal
severity: normal
status: open
title: Example for Profile Module shows incorrect method
type: enhancement
versions: Python 2.7

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

From report at bugs.python.org  Wed May 22 19:26:55 2013
From: report at bugs.python.org (Eric V. Smith)
Date: Wed, 22 May 2013 17:26:55 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <1369243615.62.0.0078260829326.issue18031@psf.upfronthosting.co.za>


Eric V. Smith added the comment:

I agree that we should not say that %-formatting will be removed from the language. Not until Python 5000, anyway.

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

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

From report at bugs.python.org  Wed May 22 19:35:15 2013
From: report at bugs.python.org (R. David Murray)
Date: Wed, 22 May 2013 17:35:15 +0000
Subject: [docs] [issue18034] Last two entries in the programming FAQ are out
	of date	(import related)
Message-ID: <1369244115.61.0.298181094271.issue18034@psf.upfronthosting.co.za>


New submission from R. David Murray:

The second to last talks about the __import__ quirk with out calling __import__ out as deprecated.  The last uses the imp module for reload.

----------
assignee: docs at python
components: Documentation
messages: 189827
nosy: brett.cannon, docs at python, eric.snow, r.david.murray
priority: normal
severity: normal
stage: needs patch
status: open
title: Last two entries in the programming FAQ are out of date (import related)
type: behavior
versions: Python 3.3, Python 3.4

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

From report at bugs.python.org  Thu May 23 09:12:45 2013
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 23 May 2013 07:12:45 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <3bGMNr2Q62zSQ6@mail.python.org>


Roundup Robot added the comment:

New changeset ef037ad304c1 by Raymond Hettinger in branch '2.7':
Issue #18031:  %-formatting isn't dead yet and might pull through.
http://hg.python.org/cpython/rev/ef037ad304c1

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

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

From report at bugs.python.org  Thu May 23 09:15:48 2013
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 23 May 2013 07:15:48 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <3bGMSM2Rlxz7Ljg@mail.python.org>


Roundup Robot added the comment:

New changeset e1d6140b02f0 by Raymond Hettinger in branch '3.3':
Issue #18031:  %-formatting isn't dead yet and might pull through.
http://hg.python.org/cpython/rev/e1d6140b02f0

----------

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

From report at bugs.python.org  Thu May 23 09:16:04 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Thu, 23 May 2013 07:16:04 +0000
Subject: [docs] [issue18031] The Python Tutorial says % string formatting
	will be	removed
In-Reply-To: <1369202302.43.0.537534312315.issue18031@psf.upfronthosting.co.za>
Message-ID: <1369293364.42.0.81419375442.issue18031@psf.upfronthosting.co.za>


Changes by Raymond Hettinger <raymond.hettinger at gmail.com>:


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

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

From report at bugs.python.org  Thu May 23 12:25:22 2013
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 23 May 2013 10:25:22 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <3bGRg562MfzNKZ@mail.python.org>


Roundup Robot added the comment:

New changeset 85e8414060b4 by Nick Coghlan in branch '3.3':
Issue 17844: Clarify meaning of different codec tables
http://hg.python.org/cpython/rev/85e8414060b4

New changeset 801567d6302c by Nick Coghlan in branch 'default':
Merge issue 17844 from 3.3
http://hg.python.org/cpython/rev/801567d6302c

----------

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

From report at bugs.python.org  Thu May 23 12:26:34 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Thu, 23 May 2013 10:26:34 +0000
Subject: [docs] [issue17844] Add link to alternatives for bytes-to-bytes
	codecs
In-Reply-To: <1366889842.88.0.0886939266057.issue17844@psf.upfronthosting.co.za>
Message-ID: <1369304794.15.0.900788458396.issue17844@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Thanks for initiating this Serhiy :)

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

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

From report at bugs.python.org  Thu May 23 13:28:57 2013
From: report at bugs.python.org (Ram Rachum)
Date: Thu, 23 May 2013 11:28:57 +0000
Subject: [docs] [issue18043] No mention of `match.regs` in `re` documentation
Message-ID: <1369308537.81.0.515783227267.issue18043@psf.upfronthosting.co.za>


New submission from Ram Rachum:

There's no mention of `match.regs` in the documentation of the `re` module.

----------
assignee: docs at python
components: Documentation
messages: 189859
nosy: cool-RR, docs at python
priority: normal
severity: normal
status: open
title: No mention of `match.regs` in `re` documentation
type: behavior
versions: Python 2.7

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

From report at bugs.python.org  Thu May 23 13:57:36 2013
From: report at bugs.python.org (Tim Rawlinson)
Date: Thu, 23 May 2013 11:57:36 +0000
Subject: [docs] [issue18044] Email headers do not properly decode to unicode.
Message-ID: <1369310256.22.0.862828757307.issue18044@psf.upfronthosting.co.za>


New submission from Tim Rawlinson:

In Python 3.3 decoding of headers to unicode is supposed to be automatic but fails in several cases, including one shown as successful in the documentation:

   >>> msg = message_from_string('Subject: =?utf-8?q?=C3=89ric?=\n\n', policy=default)
   >>> msg['Subject']
   '=?utf-8?q?=C3=89ric?='

   >>> msg = message_from_string('To: =?utf-8?q?=C3=89ric <foo at example.com>\n\n', policy=default)
   >>> msg['To']
   '=?utf-8?q?=C3=89ric?= <foo at example.com>'

Although the following works:

   >>> msg = message_from_string('Subject: =?utf-8?q?Eric?=\n\n', policy=default)
   >>> msg['Subject']
   'Eric'

Though this does not:

   >>> msg = message_from_string('To: =?utf-8?q?Eric?= <foo at example.com>\n\n', policy=default)
   >>> msg['To']
   '=?utf-8?q?Eric?= <foo at example.com>'

And just to prove some things are working as they should:

    >>> msg = message_from_string("Subject: =?gb2312?b?1eLKx9bQzsSy4srUo6E=?=\n\n", policy=default)
    >>> msg['Subject']
    '???????'

----------
assignee: docs at python
components: Documentation, email
messages: 189862
nosy: Tim.Rawlinson, barry, docs at python, r.david.murray
priority: normal
severity: normal
status: open
title: Email headers do not properly decode to unicode.
type: behavior
versions: Python 3.3

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

From report at bugs.python.org  Thu May 23 14:28:39 2013
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 23 May 2013 12:28:39 +0000
Subject: [docs] [issue18007] CookieJar expects request objects with
	origin_req_host	attribute instead of method
In-Reply-To: <1368891902.97.0.967044954731.issue18007@psf.upfronthosting.co.za>
Message-ID: <3bGVPL3XcMz7Ljb@mail.python.org>


Roundup Robot added the comment:

New changeset 26ac5b9cffda by Senthil Kumaran in branch '3.3':
Fix #18007 : Document CookieJar.add_cookie_header request parameter changes in 3.3
http://hg.python.org/cpython/rev/26ac5b9cffda

New changeset f7992397e98d by Senthil Kumaran in branch 'default':
merge from 3.3
http://hg.python.org/cpython/rev/f7992397e98d

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

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

From report at bugs.python.org  Thu May 23 14:29:15 2013
From: report at bugs.python.org (Senthil Kumaran)
Date: Thu, 23 May 2013 12:29:15 +0000
Subject: [docs] [issue18007] CookieJar expects request objects with
	origin_req_host	attribute instead of method
In-Reply-To: <1368891902.97.0.967044954731.issue18007@psf.upfronthosting.co.za>
Message-ID: <1369312155.63.0.177444696386.issue18007@psf.upfronthosting.co.za>


Senthil Kumaran added the comment:

This change is documented. Thanks for the report.

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

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

From report at bugs.python.org  Thu May 23 22:14:18 2013
From: report at bugs.python.org (Zachary Ware)
Date: Thu, 23 May 2013 20:14:18 +0000
Subject: [docs] [issue17326] Windows build docs still referring to VS 2008
	in 3.3
In-Reply-To: <1362142705.89.0.367756520949.issue17326@psf.upfronthosting.co.za>
Message-ID: <1369340058.82.0.365385509304.issue17326@psf.upfronthosting.co.za>


Zachary Ware added the comment:

Here's a simple patch to clear up the first paragraph of PCbuild/readme.txt, applicable to 3.3 and default.

----------
keywords: +patch
nosy: +zach.ware
Added file: http://bugs.python.org/file30352/issue17326.diff

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

From report at bugs.python.org  Thu May 23 23:45:20 2013
From: report at bugs.python.org (David Wolever)
Date: Thu, 23 May 2013 21:45:20 +0000
Subject: [docs] [issue17701] Improving strftime documentation
In-Reply-To: <1365725163.24.0.249924950016.issue17701@psf.upfronthosting.co.za>
Message-ID: <1369345520.5.0.0643318767458.issue17701@psf.upfronthosting.co.za>


Changes by David Wolever <wolever at cs.toronto.edu>:


Added file: http://bugs.python.org/file30353/102b3e257dca.diff

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

From report at bugs.python.org  Thu May 23 23:53:28 2013
From: report at bugs.python.org (David Wolever)
Date: Thu, 23 May 2013 21:53:28 +0000
Subject: [docs] [issue17701] Improving strftime documentation
In-Reply-To: <1365725163.24.0.249924950016.issue17701@psf.upfronthosting.co.za>
Message-ID: <1369346008.42.0.931930577878.issue17701@psf.upfronthosting.co.za>


Changes by David Wolever <wolever at cs.toronto.edu>:


Removed file: http://bugs.python.org/file30353/102b3e257dca.diff

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

From report at bugs.python.org  Fri May 24 00:01:20 2013
From: report at bugs.python.org (David Wolever)
Date: Thu, 23 May 2013 22:01:20 +0000
Subject: [docs] [issue17701] Improving strftime documentation
In-Reply-To: <1365725163.24.0.249924950016.issue17701@psf.upfronthosting.co.za>
Message-ID: <1369346480.85.0.405157054477.issue17701@psf.upfronthosting.co.za>


Changes by David Wolever <wolever at cs.toronto.edu>:


Added file: http://bugs.python.org/file30354/0f4d971b0cee.diff

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

From report at bugs.python.org  Fri May 24 09:35:28 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 24 May 2013 07:35:28 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1369380928.24.0.75788318451.issue18011@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Are there any objections?

----------
assignee: docs at python -> serhiy.storchaka

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

From report at bugs.python.org  Fri May 24 18:16:33 2013
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Fri, 24 May 2013 16:16:33 +0000
Subject: [docs] [issue17701] Improving strftime documentation
In-Reply-To: <1365725163.24.0.249924950016.issue17701@psf.upfronthosting.co.za>
Message-ID: <1369412193.02.0.199025679527.issue17701@psf.upfronthosting.co.za>


?ric Araujo added the comment:

Looks good.

----------

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

From report at bugs.python.org  Fri May 24 22:35:39 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Fri, 24 May 2013 20:35:39 +0000
Subject: [docs] [issue1554133] PyOS_InputHook() and related API funcs. not
	documented
Message-ID: <1369427739.26.0.218963704767.issue1554133@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

Here's a proposed patch to the c-api manual that describes these two pointers.  I put them in the 'very high-level API' section. Maybe they belong in the Operating System Utilities section instead, but I think they're intertwined with the interpreter loop and therefore belong in the 'very high-level' section.

----------
Added file: http://bugs.python.org/file30362/inputhook.txt

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

From report at bugs.python.org  Fri May 24 22:46:40 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 24 May 2013 20:46:40 +0000
Subject: [docs] [issue1554133] PyOS_InputHook() and related API funcs. not
	documented
Message-ID: <1369428400.36.0.19195166407.issue1554133@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

I am not a C-api user, but the entries are pretty clear to me and seem ready to apply. The usage examples are a nice touch. OS Utilites is not where I would expect interpreter loop hooks, so I think the current location is better.

----------
stage:  -> commit review
versions: +Python 3.4 -Python 3.1, Python 3.2

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

From report at bugs.python.org  Fri May 24 23:20:22 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Fri, 24 May 2013 21:20:22 +0000
Subject: [docs] [issue1554133] PyOS_InputHook() and related API funcs. not
	documented
Message-ID: <1369430422.56.0.868632603267.issue1554133@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

One question about the patch: how to give the prototype expected for the function?  I currently have it as:

char *(*PyOS_ReadlineFunctionPointer)(FILE *stdin, FILE *stdout, char *prompt)

Would it be better with a trivial function name, as in:

char *func(FILE *stdin, FILE *stdout, char *prompt)

----------

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

From report at bugs.python.org  Sat May 25 00:27:32 2013
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 24 May 2013 22:27:32 +0000
Subject: [docs] [issue1554133] PyOS_InputHook() and related API funcs. not
	documented
Message-ID: <1369434452.51.0.831788782743.issue1554133@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Can one of you three answer Kuchling's question about formatting a data entry that consists of a function pointer with function signature?

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

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

From report at bugs.python.org  Sat May 25 11:09:12 2013
From: report at bugs.python.org (Phil Connell)
Date: Sat, 25 May 2013 09:09:12 +0000
Subject: [docs] [issue18032] set methods should specify whether they
	consume	iterators "lazily"
In-Reply-To: <1369223923.83.0.620034016791.issue18032@psf.upfronthosting.co.za>
Message-ID: <1369472952.26.0.359092403577.issue18032@psf.upfronthosting.co.za>


Changes by Phil Connell <pconnell at gmail.com>:


----------
nosy: +pconnell

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

From report at bugs.python.org  Sat May 25 11:10:12 2013
From: report at bugs.python.org (Phil Connell)
Date: Sat, 25 May 2013 09:10:12 +0000
Subject: [docs] [issue18033] Example for Profile Module shows incorrect
	method
In-Reply-To: <1369235558.14.0.532987051887.issue18033@psf.upfronthosting.co.za>
Message-ID: <1369473012.03.0.362014192478.issue18033@psf.upfronthosting.co.za>


Changes by Phil Connell <pconnell at gmail.com>:


----------
nosy: +pconnell

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

From report at bugs.python.org  Sat May 25 11:31:38 2013
From: report at bugs.python.org (Phil Connell)
Date: Sat, 25 May 2013 09:31:38 +0000
Subject: [docs] [issue18043] No mention of `match.regs` in `re` documentation
In-Reply-To: <1369308537.81.0.515783227267.issue18043@psf.upfronthosting.co.za>
Message-ID: <1369474298.57.0.121500382796.issue18043@psf.upfronthosting.co.za>


Changes by Phil Connell <pconnell at gmail.com>:


----------
nosy: +pconnell

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

From report at bugs.python.org  Sat May 25 23:05:07 2013
From: report at bugs.python.org (W. Owen Parry)
Date: Sat, 25 May 2013 21:05:07 +0000
Subject: [docs] [issue16580] Add examples to int.to_bytes and int.from_bytes
In-Reply-To: <1354217109.61.0.534443148437.issue16580@psf.upfronthosting.co.za>
Message-ID: <1369515907.34.0.379857181404.issue16580@psf.upfronthosting.co.za>


W. Owen Parry added the comment:

Patch adding examples + tests for equivalence. Comments appreciated.

In particular, I'm not sure that the from_bytes example is simple enough to be useful:

def from_bytes(bytes, byteorder, signed=False):
    if byteorder == 'little':
        little_ordered = list(bytes)
    elif byteorder == 'big':
        little_ordered = list(reversed(bytes))
     n = sum(little_ordered[i] << i*8 for i in range(len(little_ordered)))
    if signed and little_ordered and (little_ordered[-1] & 0x80):
         n -= 1 << 8*len(little_ordered)
    return n

----------
keywords: +patch
nosy: +woparry
Added file: http://bugs.python.org/file30372/issue16580.patch

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

From report at bugs.python.org  Sat May 25 23:39:18 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sat, 25 May 2013 21:39:18 +0000
Subject: [docs] [issue16580] Add examples to int.to_bytes and int.from_bytes
In-Reply-To: <1354217109.61.0.534443148437.issue16580@psf.upfronthosting.co.za>
Message-ID: <1369517958.79.0.514940765486.issue16580@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

I don't call it the examples. Here is the examples:

>>> (1234).to_bytes(2, 'big')
b'\x04\xd2'
>>> (1234).to_bytes(2, 'little')
b'\xd2\x04'
>>> (-1234).to_bytes(2, 'big', signed=True)
b'\xfb.'
>>> int.from_bytes(b'\xde\xad\xbe\xef', 'big')
3735928559
>>> int.from_bytes(b'\xde\xad\xbe\xef', 'little')
4022250974
>>> int.from_bytes(b'\xde\xad\xbe\xef', 'big', signed=True)
-559038737

----------
nosy: +serhiy.storchaka

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

From report at bugs.python.org  Sun May 26 01:06:04 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sat, 25 May 2013 23:06:04 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369523164.28.0.661995388244.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Ethan, just a reminder to write that documentation...

It's basically a stripped down version of PEP 435 (leave all the philosophy and history out), with a few concrete "reference" sections explaining the API precisely.

----------

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

From report at bugs.python.org  Sun May 26 12:35:19 2013
From: report at bugs.python.org (Mark Dickinson)
Date: Sun, 26 May 2013 10:35:19 +0000
Subject: [docs] [issue16580] Add examples to int.to_bytes and int.from_bytes
In-Reply-To: <1354217109.61.0.534443148437.issue16580@psf.upfronthosting.co.za>
Message-ID: <1369564519.03.0.293486843314.issue16580@psf.upfronthosting.co.za>


Mark Dickinson added the comment:

The `from_bytes` example code looks fine to me, except that I'd probably use `enumerate` in the iteration;  i.e.,

    sum(b << 8*i for i, b in enumerate(little_ordered))

instead of

    sum(little_ordered[i] << i*8 for i in range(len(little_ordered)))

Also, in:

   if signed and little_ordered and (little_ordered[-1] & 0x80):

I wondered why you needed the `little_ordered` check.  But I see that `int.from_bytes(b'', 'little', signed=True)` produces `0`, which is a little bit disappointing:  I was expecting an exception.  (A signed format should have a sign bit, which is impossible if the length of the byte string is 0.)

The `to_bytes` example code is missing range checks for the input.  It may be clearer to simply state that in the docs, instead of modifying the example code to add the range checks.

----------
nosy: +mark.dickinson

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

From report at bugs.python.org  Sun May 26 15:36:13 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 26 May 2013 13:36:13 +0000
Subject: [docs] [issue18034] Last two entries in the programming FAQ are out
	of date	(import related)
In-Reply-To: <1369244115.61.0.298181094271.issue18034@psf.upfronthosting.co.za>
Message-ID: <1369575373.48.0.636775475957.issue18034@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/issue18034>
_______________________________________

From report at bugs.python.org  Sun May 26 15:41:13 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 26 May 2013 13:41:13 +0000
Subject: [docs] [issue18044] Email headers do not properly decode to unicode.
In-Reply-To: <1369310256.22.0.862828757307.issue18044@psf.upfronthosting.co.za>
Message-ID: <1369575673.94.0.714781225978.issue18044@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/issue18044>
_______________________________________

From report at bugs.python.org  Sun May 26 15:41:29 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 26 May 2013 13:41:29 +0000
Subject: [docs] [issue18043] No mention of `match.regs` in `re` documentation
In-Reply-To: <1369308537.81.0.515783227267.issue18043@psf.upfronthosting.co.za>
Message-ID: <1369575689.71.0.614002175471.issue18043@psf.upfronthosting.co.za>


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


----------
components: +Regular Expressions
nosy: +ezio.melotti, mrabarnett

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

From report at bugs.python.org  Sun May 26 15:44:25 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 26 May 2013 13:44:25 +0000
Subject: [docs] [issue18033] Example for Profile Module shows incorrect
	method
In-Reply-To: <1369235558.14.0.532987051887.issue18033@psf.upfronthosting.co.za>
Message-ID: <1369575865.74.0.702958446665.issue18033@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/issue18033>
_______________________________________

From report at bugs.python.org  Sun May 26 15:45:02 2013
From: report at bugs.python.org (Ezio Melotti)
Date: Sun, 26 May 2013 13:45:02 +0000
Subject: [docs] [issue18032] set methods should specify whether they
	consume	iterators "lazily"
In-Reply-To: <1369223923.83.0.620034016791.issue18032@psf.upfronthosting.co.za>
Message-ID: <1369575902.72.0.897055381042.issue18032@psf.upfronthosting.co.za>


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


----------
keywords: +easy
nosy: +ezio.melotti
stage:  -> needs patch
versions: +Python 3.3, Python 3.4 -Python 3.2

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

From report at bugs.python.org  Sun May 26 16:56:39 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Sun, 26 May 2013 14:56:39 +0000
Subject: [docs] [issue17700] Update Curses HOWTO for 3.4
In-Reply-To: <1365719687.97.0.644773548697.issue17700@psf.upfronthosting.co.za>
Message-ID: <1369580199.88.0.721269555885.issue17700@psf.upfronthosting.co.za>


A.M. Kuchling added the comment:

I can't make sense of unget_wch.  I used this test program:

--------

import curses

def main(stdscr):
    stdscr.addstr(0,0, "Key")
    stdscr.refresh()
    curses.ungetch(0x0149)
    while True:
        ch = stdscr.get_wch()
        stdscr.addstr(1,1, repr(ch) + '      ')
        if ch == 'q':
            break
        
curses.wrapper(main)

--------

If I use curses.unget_wch(chr(0x0149)), the following get_wch() call returns -119, not 0x149.

The whole area of wide character support in curses is just a mystery, and I don't know how to resolve my questions.  I'll close this item, since I have nothing further to add to the curses howto.

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

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

From report at bugs.python.org  Sun May 26 18:04:22 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 26 May 2013 16:04:22 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369584260.79.0.902076558686.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

I tweaked the code a bit (no functionality changes, mostly cleanups and a bit of refactoring). Figured it will be easier to just send an updated patch than another review. The diff from patch 06 can be seen via the Rietveld interface.

Also, after reading the code more carefully, I think we're doing a mistake by over-complicating it for the sake of custom enum metaclasses and over-customization (like auto numbering). The original point Guido raised against auto-numbering was too much magic in the implementation. Well, we already have that in Lib/enum.py - the code is so complex it seems fragile because of the tight coupling with many class and metaclass related protocols. Just defining a wholly new enum implementation that does something very specific seems simpler than customizing the existing one.

I'd suggest we stick to the existing Enum + IntEnum, giving up the more complex customizations for now. It can always be added in the future if we see it's very important.

----------
Added file: http://bugs.python.org/file30384/pep-0435.07.eliben.patch

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

From report at bugs.python.org  Sun May 26 18:52:27 2013
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 26 May 2013 16:52:27 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369587147.42.0.877699818497.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Wow.  I definitely felt like an apprentice after reading the changes.  Thanks, Eli, that looks worlds better!

----------

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

From report at bugs.python.org  Sun May 26 22:56:09 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Sun, 26 May 2013 20:56:09 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369601769.16.0.354457557401.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Thanks Ethan :)

>From my point of view this is LGTM, as long as:

* There's ReST documentation
* You remove the code to support extensions and customizations not mandated by PEP 435. As I mentioned before, this seems to be a YAGNI that complicates the code needlessly. It's find to keep the changes in some external repo and at a later point discuss their gradual addition similarly to the way Nick has been pushing enhancements through additional issues.

We can always add more capabilities to Enum. We can "never" take them away once added, and this complicated code will remain with us forever even if no one ends up using it.

----------

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

From report at bugs.python.org  Mon May 27 00:31:41 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 26 May 2013 22:31:41 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1369601769.16.0.354457557401.issue17947@psf.upfronthosting.co.za>
Message-ID: <CADiSq7efQSOwW2mPfFMxALknxk8xaz1e=X8=J8XYL19dk8LNMw@mail.gmail.com>


Nick Coghlan added the comment:

Supporting extensions was one of the things that got Ethan's version
through review. So -1 on going back on our promise to support those
variants. They have been reviewed and tested just as thoroughly as the rest
of the design.

----------

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

From report at bugs.python.org  Mon May 27 00:33:16 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Sun, 26 May 2013 22:33:16 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <CADiSq7efQSOwW2mPfFMxALknxk8xaz1e=X8=J8XYL19dk8LNMw@mail.gmail.com>
Message-ID: <CADiSq7fjt+KMUsGVcuMX+3zS-RioxGqieVQqkje1CSiHDAeBmw@mail.gmail.com>


Nick Coghlan added the comment:

Also, we know for a fact that people plan to use the customisation features
- it was making their code work that drove the current extension design.

----------

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

From report at bugs.python.org  Mon May 27 03:12:50 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 27 May 2013 01:12:50 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369617170.58.0.442243248429.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

I'm not sure which promises you're referring to Nick, and to whom they were made; the only formal promise we made is PEP 435 - and it doesn't mention this extensibility.

I won't argue beyond this comment, since I know I'm part of the minority opinion here. However, I still think this is a mistake.

The most important original goal of Enum (as discussed during the language summit) was to replace all the custom enum implementations by one that is standard. A far fledged extension mechanism will just make it so we'll have a fleet of bastardized "extended enums", each with its own capabilities, each different from the others. With one standard Enum, when you're reading someone's code and you see:

class Foo(Enum):
  ...

You know very well what Foo is. Restricted extensions like IntEnum and even your @enum.unique are still tolerable because they're explicit:

# enum.unique is standard and says what it is explicitly
@enum.unique
class Foo(Enum):
  ...

But if we open the gates on customization, we'll have:

class Foo(AutoEnum):
  Red, White, Black

And:

class Bar(SomeOtherAutoEnum):
  Red = ...
  White = ...
  Black = ...

And:

class Baz(SomeEvenOtherMagicEnum):
  ... # whatever goes here

And we're back to square 1, because these Enums are not standard, and each framework will have its own clever customization one will need to understand in order to read code with Enums.

Exposing and documenting the metaclass and customizations of __new__ is a whole coffin for the "there is only one way to do it" decision of stdlib's Enum. It might have been better to just define AutoNumberedEnum, BitfieldEnum and Magic42Enum as part of the enum package in stdlib and be over with it; but this was strongly rejected by others and particularly Guido during the summit and later. Now we're just creating a back-door to get into the same situation.

----------

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

From report at bugs.python.org  Mon May 27 03:40:44 2013
From: report at bugs.python.org (Guido van Rossum)
Date: Mon, 27 May 2013 01:40:44 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369618844.77.0.92464272893.issue17947@psf.upfronthosting.co.za>


Guido van Rossum added the comment:

Eli, what's wrong with having a backdoor?  Python is literally *full* of backdoors.  I have a feeling that somehow you are trying to build an Enum class that is unpythonic in its desire to enforce some kind of "ideal enum" behavior.

----------

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

From report at bugs.python.org  Mon May 27 04:24:55 2013
From: report at bugs.python.org (Todd Rovito)
Date: Mon, 27 May 2013 02:24:55 +0000
Subject: [docs] [issue16278] os.rename documentation slightly inaccurate
In-Reply-To: <1350581776.08.0.668682100781.issue16278@psf.upfronthosting.co.za>
Message-ID: <1369621495.58.0.541482300692.issue16278@psf.upfronthosting.co.za>


Todd Rovito added the comment:

Ping!!!

I have not heard anything about this patch so I wanted to ping it to get more feedback.  Thanks!

----------

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

From report at bugs.python.org  Mon May 27 04:32:40 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Mon, 27 May 2013 02:32:40 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369621960.34.0.805111751877.issue17947@psf.upfronthosting.co.za>


Eli Bendersky added the comment:

Guido, IMHO back-doors are fine in many cases, just not this one. The way I see it, our main goal here is to collect a bunch of custom implementations of enums under a single umbrella. This is not very different from what was done with OrderedDict and namedtuple at some point. There were probably a bunch of custom implementations, along with more and less commonly used recipes. At some point a single implementation was added to the stdlib, without (AFAICS) major back-doors.

Yes, the Enum case is vastly more complex than either OrderedDict or namedtuple, and there is a multitude of different behaviors that can be anticipated (as the lengthy discussions leading to the acceptance of PEP 435 demonstrated). And yet, I was also hoping to have a single canonical implementation, so that people eventually accept it as "the one". Stdlib modules tend to win over in the long run.

The other point is that I think the implementation could be much simpler without having these back doors. As it stands now, the code is complex and hence brittle. Any change will be difficult to do because we're locked down very strictly by a set of intrusive and deep, yet externally "promised" interfaces. The same can be said, again, about OrderedDict and namedtuple, the code of which is very straightforward.

Maybe I'm blowing this out of proportions, maybe not. I'm not sure. As I said, I don't want to strongly argue about this. If both you and Nick are OK with keeping the customization mechanisms in, I defer to your judgment.

----------

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

From report at bugs.python.org  Mon May 27 06:06:11 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 27 May 2013 04:06:11 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369627571.45.0.489856699816.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Eli, remember that TOOWTDI stands for "There's one *obvious* way to do it" rather than "There's *only* one way to do it". The latter interpretation leads to insanely complex APIs that attempt to solve everyone's problems, while the former favours 80% solutions that cover most use cases, with extension hooks that let people handle the other 20% as they see fit.

The point of the enum standardisation is to have a conventional way that enums *behave*, and then allow variations on that theme for those cases where the stdlib implementation is "close, but not quite what I need or want".

The whole metaclass machinery is built around this concept of letting people create domain specific behaviour, that is still somewhat unified due to conventions like the descriptor protocol. You can do a *lot* with just descriptors, so if you don't need a custom metaclass, you shouldn't use one.

PEP 422's class initialisation hook is aimed specifically at certain cases that currently need a metaclass and providing a simpler way to do them that lets you just use "type" as the metaclass instead.

It's the same with enums - if you don't need to customise the metaclass, you shouldn't. But there are some use cases (such as syncing the Python level enum definition with a database level one) where additional customisation will be needed. We also want to give people the freedom they need to experiment with different forms of definition time syntactic sugar to see if they can come up with one we like enough to add to the standard library in 3.5.

Does documenting these definition time extension points constrain what we're allowed to do in the future? Yes, it does. But, at the same time, it takes a lot of pressure off us to add more features to the standard enum type over time - if people have niche use cases that aren't handled well by the standard solution (and we already know they do), we can point them at the supported extension interface and say "go for it". For the majority of users though, the standard enum type will work fine, just as ordinary classes are adequate for the vast majority of object oriented code.

----------

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

From report at bugs.python.org  Mon May 27 06:10:05 2013
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 27 May 2013 04:10:05 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369627805.71.0.290715526663.issue17947@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Somewhat related, I *know* you've read type.__new__. Compared to that, enum.EnumMeta.__new__ is still pretty straightforward ;)

----------

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

From report at bugs.python.org  Mon May 27 09:03:14 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Mon, 27 May 2013 07:03:14 +0000
Subject: [docs] [issue18032] set methods should specify whether they
	consume	iterators "lazily"
In-Reply-To: <1369223923.83.0.620034016791.issue18032@psf.upfronthosting.co.za>
Message-ID: <1369638194.37.0.880298995125.issue18032@psf.upfronthosting.co.za>


Changes by Raymond Hettinger <raymond.hettinger at gmail.com>:


----------
assignee: docs at python -> rhettinger
nosy: +rhettinger

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

From report at bugs.python.org  Mon May 27 09:59:28 2013
From: report at bugs.python.org (Raymond Hettinger)
Date: Mon, 27 May 2013 07:59:28 +0000
Subject: [docs] [issue18032] set methods should specify whether they
	consume	iterators "lazily"
In-Reply-To: <1369223923.83.0.620034016791.issue18032@psf.upfronthosting.co.za>
Message-ID: <1369641568.61.0.0872321476433.issue18032@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

We don't normally document implementation details or the presences or absence of internal optimizations.  This gives us freedom to change the implementation and it allows freedom for other implementations (such as Jython, IronPython, and PyPy) to make their own choices.  Often those implementations start out with the simplest correct approach and then become increasingly optimized over time. 

I'm leaving this one open as a possible CPythhon performance enhancement, adding early-out behavior to issubset() when the argument is a non-set, non-dict iterable:

    def issubset(self, iterable):
        n = len(self)
        seen = set() 
        for x in iterable:
            if x not in seen and x in self:
                seen.add(x)
                n -= 1
                if not n:
                    return True             # early-out
        return False

----------
components: +Interpreter Core -Documentation
type: behavior -> performance
versions:  -Python 2.7, Python 3.3

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

From report at bugs.python.org  Mon May 27 19:47:42 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Mon, 27 May 2013 17:47:42 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369676862.54.0.506454708276.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Added a patch

----------
keywords: +patch
nosy: +dmi.baranov
Added file: http://bugs.python.org/file30387/issue17987.patch

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

From report at bugs.python.org  Mon May 27 20:09:39 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Mon, 27 May 2013 18:09:39 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369678179.31.0.966572752723.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Sorry for noise, missed changes in Doc/library/test.rst. Updated patch added

----------
hgrepos: +192
Added file: http://bugs.python.org/file30389/issue17987_2.patch

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

From report at bugs.python.org  Mon May 27 20:30:20 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Mon, 27 May 2013 18:30:20 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369679420.89.0.40593384362.issue17987@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Print to stdin?

----------
nosy: +serhiy.storchaka

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

From report at bugs.python.org  Mon May 27 20:51:11 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Mon, 27 May 2013 18:51:11 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369680671.3.0.744855248142.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Yes, I agree that this is not an obvious sample, but:

$ ./python -m test.test_support | grep test_captured_stdin
test_captured_stdin (__main__.TestSupport) ... ok

What's about that?

with captured_stdin() as s:
    s.write('hello\n')
    s.seek(0)
    captured = input()

assert captured == 'hello'

----------

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

From report at bugs.python.org  Mon May 27 22:42:41 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Mon, 27 May 2013 20:42:41 +0000
Subject: [docs] [issue18033] Example for Profile Module shows incorrect
	method
In-Reply-To: <1369235558.14.0.532987051887.issue18033@psf.upfronthosting.co.za>
Message-ID: <1369687361.63.0.548158121186.issue18033@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Added py3 patch

----------
keywords: +patch
nosy: +dmi.baranov
versions: +Python 3.4
Added file: http://bugs.python.org/file30390/issue18033_py3.patch

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

From report at bugs.python.org  Mon May 27 22:42:59 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Mon, 27 May 2013 20:42:59 +0000
Subject: [docs] [issue18033] Example for Profile Module shows incorrect
	method
In-Reply-To: <1369235558.14.0.532987051887.issue18033@psf.upfronthosting.co.za>
Message-ID: <1369687379.61.0.207786701287.issue18033@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

py2

----------
Added file: http://bugs.python.org/file30391/issue18033_py2.patch

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

From report at bugs.python.org  Tue May 28 09:26:22 2013
From: report at bugs.python.org (arbour)
Date: Tue, 28 May 2013 07:26:22 +0000
Subject: [docs] [issue18079] documentation tutorial 3.1.3 typo
Message-ID: <1369725982.22.0.36331305671.issue18079@psf.upfronthosting.co.za>


New submission from arbour:

documentation tutorial 3.1.3 typo

at page 15 (21/127)

>>> p[0]
['a','b','c']
>>> p[0][1]
'b'

should be:

>>> x[0]
['a','b','c']
>>> x[0][1]
'b'

----------
assignee: docs at python
components: Documentation
files: tutorial.pdf
messages: 190178
nosy: arbour, docs at python
priority: normal
severity: normal
status: open
title: documentation tutorial 3.1.3 typo
versions: Python 3.3
Added file: http://bugs.python.org/file30394/tutorial.pdf

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

From report at bugs.python.org  Tue May 28 11:46:10 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 09:46:10 +0000
Subject: [docs] [issue18079] documentation tutorial 3.1.3 typo
In-Reply-To: <1369725982.22.0.36331305671.issue18079@psf.upfronthosting.co.za>
Message-ID: <1369734370.03.0.089682282118.issue18079@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
assignee: docs at python -> serhiy.storchaka
nosy: +serhiy.storchaka
versions: +Python 3.4

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

From report at bugs.python.org  Tue May 28 11:53:27 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 28 May 2013 09:53:27 +0000
Subject: [docs] [issue18079] documentation tutorial 3.1.3 typo
In-Reply-To: <1369725982.22.0.36331305671.issue18079@psf.upfronthosting.co.za>
Message-ID: <3bKVjz04kqzPSZ@mail.python.org>


Roundup Robot added the comment:

New changeset bde91dddbcbc by Serhiy Storchaka in branch '3.3':
Issue #18079: Fix a typo in the tutorial.
http://hg.python.org/cpython/rev/bde91dddbcbc

New changeset 09b88b5bebd0 by Serhiy Storchaka in branch 'default':
Issue #18079: Fix a typo in the tutorial.
http://hg.python.org/cpython/rev/09b88b5bebd0

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

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

From report at bugs.python.org  Tue May 28 11:57:11 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 09:57:11 +0000
Subject: [docs] [issue18079] documentation tutorial 3.1.3 typo
In-Reply-To: <1369725982.22.0.36331305671.issue18079@psf.upfronthosting.co.za>
Message-ID: <1369735031.39.0.0663264870679.issue18079@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Fixed. Thank you for your report.

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

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

From report at bugs.python.org  Tue May 28 12:22:06 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 10:22:06 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369736526.0.0.679260176391.issue17987@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

I believe it is a mechanical mistake in test_captured_stdin().

----------
nosy: +eli.bendersky
versions:  -Python 3.5

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

From report at bugs.python.org  Tue May 28 13:44:49 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Tue, 28 May 2013 11:44:49 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369741489.42.0.368716090486.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

`captured_stdin` test changed, docs updated.

----------
Added file: http://bugs.python.org/file30396/issue17987_3.patch

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

From report at bugs.python.org  Tue May 28 14:12:32 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 12:12:32 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369743152.31.0.793357457987.issue17987@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

I think it will be better to describe all three functions together (as sys.stdin/stdout/stderr).

.. function:: captured_stdin()
              captured_stdout()
              captured_stderr()

... description ...

   Example use::

      ... example for captured_stdin() ...

      ... example for captured_stdout() ...

----------

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

From report at bugs.python.org  Tue May 28 14:25:35 2013
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Tue, 28 May 2013 12:25:35 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369743935.1.0.586954762302.issue17987@psf.upfronthosting.co.za>


Fred L. Drake, Jr. added the comment:

Joining the documentation for captured_stderr and captured_stdout makes
sense, as they can really use a single example, and the usage is
completely parallel.

I'd rather see captured_stdin handled separately, perhaps with some
additional comments in the example, to emphasize the intended usage
pattern:

     with support.captured_stdin() as s:
         # Prepare simulated input:
         s.write('hello\n')
         s.seek(0)
         # Call test code that consumes from stdin:
         captured = input()
     self.assertEqual(captured, "hello")

----------

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

From report at bugs.python.org  Tue May 28 14:35:30 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 28 May 2013 12:35:30 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <3bKZJx2mYQzRmp@mail.python.org>


Roundup Robot added the comment:

New changeset 0b9bcb2ac145 by Serhiy Storchaka in branch '3.3':
Issue #18011: base64.b32decode() now raises a binascii.Error if there are
http://hg.python.org/cpython/rev/0b9bcb2ac145

New changeset 7446f53ba2d2 by Serhiy Storchaka in branch 'default':
Issue #18011: base64.b32decode() now raises a binascii.Error if there are
http://hg.python.org/cpython/rev/7446f53ba2d2

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

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

From report at bugs.python.org  Tue May 28 14:36:41 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 12:36:41 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <1369744601.24.0.174420928119.issue18011@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


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

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

From report at bugs.python.org  Tue May 28 14:43:16 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 28 May 2013 12:43:16 +0000
Subject: [docs] [issue18011] Inconsistency between b32decode() documentation,
	docstring and code
In-Reply-To: <1368951549.72.0.00589705304437.issue18011@psf.upfronthosting.co.za>
Message-ID: <3bKZTv1nXjzP9n@mail.python.org>


Roundup Robot added the comment:

New changeset 29a823f31465 by Serhiy Storchaka in branch 'default':
Issue #18011: Silence an unrelated noise introduced in changeset 1b5ef05d6ced.
http://hg.python.org/cpython/rev/29a823f31465

----------

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

From report at bugs.python.org  Tue May 28 15:04:48 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Tue, 28 May 2013 13:04:48 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369746288.71.0.67320619573.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Amended, as discussed. Also changed documentation from "how to use a context managers with that" to "how it works".

----------
Added file: http://bugs.python.org/file30398/issue17987_4.patch

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

From report at bugs.python.org  Tue May 28 15:18:35 2013
From: report at bugs.python.org (Eli Bendersky)
Date: Tue, 28 May 2013 13:18:35 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369747115.84.0.144157930765.issue17987@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/issue17987>
_______________________________________

From report at bugs.python.org  Tue May 28 15:27:56 2013
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Tue, 28 May 2013 13:27:56 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369747676.57.0.756090159809.issue17987@psf.upfronthosting.co.za>


Fred L. Drake, Jr. added the comment:

+1 for issue17987_4.patch

Thanks, Dmi!

----------

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

From storchaka at gmail.com  Tue May 28 15:37:20 2013
From: storchaka at gmail.com (storchaka at gmail.com)
Date: Tue, 28 May 2013 13:37:20 -0000
Subject: [docs] test.support.captured_stderr,
	captured_stdin not documented (issue 17987)
Message-ID: <20130528133720.30125.53598@psf.upfronthosting.co.za>


http://bugs.python.org/review/17987/diff/8258/Doc/library/test.rst
File Doc/library/test.rst (right):

http://bugs.python.org/review/17987/diff/8258/Doc/library/test.rst#newcode365
Doc/library/test.rst:365: .. function:: captured_stderr()
I think functions should be mentioned in order of it's fd numbers (0 -
stdin, 1 - stdout, 2 - stderr).

http://bugs.python.org/review/17987/diff/8258/Doc/library/test.rst#newcode373
Doc/library/test.rst:373: with captured_stderr() as s:
captured_stdout() is much more used and stdout usually mentioned before
stderr.

http://bugs.python.org/review/17987/

From report at bugs.python.org  Tue May 28 15:42:33 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 13:42:33 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369748553.27.0.798893328597.issue17987@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

> I'd rather see captured_stdin handled separately, perhaps with some
> additional comments in the example, to emphasize the intended usage
> pattern:

However all three functions share a description.

sys.stdin also has totally different usage pattern than sys.stdout/stderr, but it's documentation joined with documentation of all sys.std* streams.

I think functions should be mentioned in order of it's fd numbers (0 - stdin, 1
- stdout, 2 - stderr). And example for capture_stdout() looks more appropriate then for capture_stderr().

----------

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

From report at bugs.python.org  Tue May 28 16:41:39 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Tue, 28 May 2013 14:41:39 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369752099.52.0.399302125535.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Thanks for review, Serhiy - updated.

----------
Added file: http://bugs.python.org/file30400/issue17987_5.patch

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

From report at bugs.python.org  Tue May 28 20:28:56 2013
From: report at bugs.python.org (=?utf-8?q?=C3=89ric_Araujo?=)
Date: Tue, 28 May 2013 18:28:56 +0000
Subject: [docs] [issue14616] subprocess docs should mention
	pipes.quote/shlex.quote
In-Reply-To: <1334769157.78.0.557014485739.issue14616@psf.upfronthosting.co.za>
Message-ID: <1369765736.75.0.716695581937.issue14616@psf.upfronthosting.co.za>


?ric Araujo added the comment:

> .. deprecated:: 1.6

This looks weird to me.

----------

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

From report at bugs.python.org  Tue May 28 20:41:01 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 18:41:01 +0000
Subject: [docs] [issue11468] Improve unittest basic example in the doc
In-Reply-To: <1299867342.41.0.388080450116.issue11468@psf.upfronthosting.co.za>
Message-ID: <1369766461.61.0.382588094131.issue11468@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
nosy:  -serhiy.storchaka
stage: commit review -> patch review
versions: +Python 3.4 -Python 3.2

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

From report at bugs.python.org  Tue May 28 21:22:38 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 28 May 2013 19:22:38 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
Message-ID: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>


New submission from Serhiy Storchaka:

I found one error in Doc/data/refcounts.dat (see issue9369, second argument of PyObject_CallMethodObjArgs is `PyObject*`, not `char*`). Perhaps there are other errors. How this file was generated first? Is it possible to write a tool which will automatically verify at least signatures of functions?

----------
assignee: docs at python
components: Documentation
messages: 190236
nosy: docs at python, serhiy.storchaka, skip.montanaro
priority: normal
severity: normal
status: open
title: Verifying refcounts.dat
type: behavior
versions: Python 2.7, Python 3.3, Python 3.4

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

From report at bugs.python.org  Tue May 28 21:48:07 2013
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 28 May 2013 19:48:07 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>
Message-ID: <3bKlw663JDz7Lq8@mail.python.org>


Roundup Robot added the comment:

New changeset 0889ab0d0da1 by Serhiy Storchaka in branch '3.3':
Issue #18085: Fix PyObject_CallMethodObjArgs()'s entry in refcounts.dat.
http://hg.python.org/cpython/rev/0889ab0d0da1

New changeset ef9d42b98a3d by Serhiy Storchaka in branch '2.7':
Issue #18085: Fix PyObject_CallMethodObjArgs()'s entry in refcounts.dat.
http://hg.python.org/cpython/rev/ef9d42b98a3d

New changeset 6d0fd113a2e4 by Serhiy Storchaka in branch 'default':
Issue #18085: Fix PyObject_CallMethodObjArgs()'s entry in refcounts.dat.
http://hg.python.org/cpython/rev/6d0fd113a2e4

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

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

From report at bugs.python.org  Tue May 28 21:55:16 2013
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Tue, 28 May 2013 19:55:16 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>
Message-ID: <1369770916.49.0.0424203137522.issue18085@psf.upfronthosting.co.za>


Fred L. Drake, Jr. added the comment:

I'm a little surprised that still exists.

The first version was generated manually.

----------
nosy: +fdrake

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

From report at bugs.python.org  Tue May 28 22:23:07 2013
From: report at bugs.python.org (Brett Cannon)
Date: Tue, 28 May 2013 20:23:07 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>
Message-ID: <1369772587.88.0.986847562975.issue18085@psf.upfronthosting.co.za>


Brett Cannon added the comment:

Wow, I didn't even know that file existed. It could actually help with some static analysis of the C code to verify that the refcounts are as expected w/o actually having to do inter-procedural analysis to figure out all of the refcount values. I wonder if Dave's gcc work could help either verify the file or benefit from it?

----------
nosy: +brett.cannon, dmalcolm

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

From report at bugs.python.org  Tue May 28 22:26:36 2013
From: report at bugs.python.org (Skip Montanaro)
Date: Tue, 28 May 2013 20:26:36 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>
Message-ID: <1369772796.31.0.527755341755.issue18085@psf.upfronthosting.co.za>


Skip Montanaro added the comment:

As far as I can tell that file is still manually maintained.  I see it mentioned in Doc/conf.py, but nowhere else.  It shouldn't be hard to deal with manually, as the C API doesn't change that often.

A verifier shouldn't be terribly difficult to write, as Python C source is pretty consistently structured.  I'm not volunteering for the task though. <wink>

----------

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

From report at bugs.python.org  Tue May 28 22:52:15 2013
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Tue, 28 May 2013 20:52:15 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369772796.31.0.527755341755.issue18085@psf.upfronthosting.co.za>
Message-ID: <CAFT4OTGC7aQ+7J=h7O4_3+bMezpzGX8F4o9w6CVroHcxhmiYnA@mail.gmail.com>


Fred L. Drake, Jr. added the comment:

Were I adding that today, I'd use a more verbose (but more standard)
format, like configparser or JSON.  If any further use is going to be
made of it, that should be considered.  Colon-delimited is a pretty
fragile format.

----------

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

From report at bugs.python.org  Tue May 28 22:55:55 2013
From: report at bugs.python.org (Skip Montanaro)
Date: Tue, 28 May 2013 20:55:55 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <CAFT4OTGC7aQ+7J=h7O4_3+bMezpzGX8F4o9w6CVroHcxhmiYnA@mail.gmail.com>
Message-ID: <CANc-5UwJzB_rCe=gx9LhDbySXWerLtyvTieq+etiy3218grwWg@mail.gmail.com>


Skip Montanaro added the comment:

> Fred L. Drake, Jr. added the comment:
>
> Were I adding that today, I'd use a more verbose (but more standard)
> format, like configparser or JSON.  If any further use is going to be
> made of it, that should be considered.  Colon-delimited is a pretty
> fragile format.

Given the context, it should be okay until Python is rewritten in C++. :-)

I don't know where this is consumed.  Presumably by Sphinx somewhere.

----------

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

From report at bugs.python.org  Wed May 29 03:48:44 2013
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 29 May 2013 01:48:44 +0000
Subject: [docs] [issue1554133] PyOS_InputHook() and related API funcs. not
	documented
Message-ID: <3bKvwC132Xz7LkV@mail.python.org>


Roundup Robot added the comment:

New changeset 672614d809a1 by Andrew Kuchling in branch 'default':
#1554133: Document PyOS_InputHook, PyOS_ReadlineFunctionPointer
http://hg.python.org/cpython/rev/672614d809a1

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

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

From report at bugs.python.org  Wed May 29 03:50:33 2013
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 29 May 2013 01:50:33 +0000
Subject: [docs] [issue1554133] PyOS_InputHook() and related API funcs. not
	documented
Message-ID: <1369792233.59.0.566672877119.issue1554133@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <lists at amk.ca>:


----------
resolution:  -> fixed
stage: commit review -> committed/rejected
status: open -> closed
versions:  -Python 2.7, Python 3.3

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

From report at bugs.python.org  Wed May 29 12:52:23 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Wed, 29 May 2013 10:52:23 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369824743.39.0.996188740389.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Fred or Serhiy - any news here? I'm signed Contributor Agreement few days ago, just waiting a change in my profile here, please don't worry about copyright :-)

----------

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

From report at bugs.python.org  Wed May 29 13:16:24 2013
From: report at bugs.python.org (Amaury Forgeot d'Arc)
Date: Wed, 29 May 2013 11:16:24 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>
Message-ID: <1369826184.39.0.385990860361.issue18085@psf.upfronthosting.co.za>


Amaury Forgeot d'Arc added the comment:

And is it necessary to list all functions there?
Many functions share the same behavior: they don't change the ownership of PyObject* passed as argument, and return a new reference.

Only document functions that don't conform to this rule, like PyTuple_SET_ITEM and PyImport_AddModule.

----------
nosy: +amaury.forgeotdarc

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

From report at bugs.python.org  Wed May 29 14:32:00 2013
From: report at bugs.python.org (Fred L. Drake, Jr.)
Date: Wed, 29 May 2013 12:32:00 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369830720.49.0.293425430539.issue17987@psf.upfronthosting.co.za>


Fred L. Drake, Jr. added the comment:

>From v5 of the patch:
+   A context managers that temporarily replaces the :data:`sys.stdin` /
+   :data:`sys.stdout` / :data:`sys.stderr` stream with :class:`io.StringIO`
+   object.

I'd go with singular nouns instead of trying to map across them with plurals:

  Context manager that temporarily replaces the named stream with an
  :class:`io.StringIO` object.

----------

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

From report at bugs.python.org  Wed May 29 14:48:46 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Wed, 29 May 2013 12:48:46 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369831726.57.0.135034227245.issue17987@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

LGTM with Fred's suggestion.

----------
assignee: docs at python -> fdrake

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

From report at bugs.python.org  Wed May 29 17:12:06 2013
From: report at bugs.python.org (Ethan Furman)
Date: Wed, 29 May 2013 15:12:06 +0000
Subject: [docs] [issue17947] Code, test, and doc review for PEP-0435 Enum
In-Reply-To: <1368168600.94.0.409104207023.issue17947@psf.upfronthosting.co.za>
Message-ID: <1369840326.48.0.969268689097.issue17947@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Working on documentation...

----------

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

From report at bugs.python.org  Wed May 29 18:46:46 2013
From: report at bugs.python.org (Skip Montanaro)
Date: Wed, 29 May 2013 16:46:46 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369826184.39.0.385990860361.issue18085@psf.upfronthosting.co.za>
Message-ID: <CANc-5UxTcqjYpYPnfiwam05LB9ptH-X_CWqWYnfkoLY_rxJpAQ@mail.gmail.com>


Skip Montanaro added the comment:

> And is it necessary to list all functions there?

Probably not.  However, BITD, I was figuring this stuff out as I was
going along by examining the source code and writing down what I
found.  No regard for common or special cases.

S

----------

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

From report at bugs.python.org  Thu May 30 07:40:39 2013
From: report at bugs.python.org (paul j3)
Date: Thu, 30 May 2013 05:40:39 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1369892438.91.0.461861579324.issue14191@psf.upfronthosting.co.za>


paul j3 added the comment:

This is a refinement of the patch with Message188609.

In parse_known_intermixed_args, the temporary capture of formatted usage has been put in a try/finally structure.

Positionals are now 'deactivated' with

    action.nargs = SUPPRESS
    action.default = SUPPRESS

To use this, a 'nargs==SUPPRESS' case has been added to the relevant methods.  In _get_args_pattern() it acts just like 'nargs=0'.  In '_get_values()' it returns 'value=SUPPRESS'.  The net effect is that, in take_action(), 'action' is not invoked, and that positional is not added to the namespace.

Previously I used nargs=0, which put a [] value in the namespace, which then had to be deleted.

I have not added anything about this SUPPRESS option to the documentation (PARSER isn't there either).

When the parser uses incompatible features (e.g. REMAINDER), this now raises a TypeError.  The effect is similar to giving add_argument incompatible definitions.  The 'fallback' that I used earlier can be implemented with a simple 'try/except TypeError'.  Other parsing errors go through the usual ArgumentParser.error() method.

test_argparse.py has been changed to handle this TypeError.

----------
Added file: http://bugs.python.org/file30422/intermixed.patch

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

From report at bugs.python.org  Thu May 30 07:49:34 2013
From: report at bugs.python.org (Glenn Linderman)
Date: Thu, 30 May 2013 05:49:34 +0000
Subject: [docs] [issue14191] argparse doesn't allow optionals within
	positionals
In-Reply-To: <1330843053.88.0.983162018395.issue14191@psf.upfronthosting.co.za>
Message-ID: <1369892974.8.0.923885649687.issue14191@psf.upfronthosting.co.za>


Glenn Linderman added the comment:

These sound like good refinements. You've been thinking.  By making the fallback happen externally, it simplifies the implementation of parse_intermixed_args, and forces the application to accept responsibility for calling it with a consistent set of arguments, or calling something else. I like that. I don't really see the fallback as a particularly useful feature, so pushing it outside the stdlib, yet still making it simple to implement for any that do find it to be useful, seems like a good tradeoff.

----------

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

From report at bugs.python.org  Thu May 30 11:36:34 2013
From: report at bugs.python.org (moijes12)
Date: Thu, 30 May 2013 09:36:34 +0000
Subject: [docs] [issue17375] Add docstrings to methods in the threading
	module
In-Reply-To: <1362648255.88.0.520762515957.issue17375@psf.upfronthosting.co.za>
Message-ID: <1369906593.95.0.483967943708.issue17375@psf.upfronthosting.co.za>


moijes12 added the comment:

Attached is a patch built against Python 3.3. I've taken karlcow's patch and used it for Python 3.  I have run the test suite(./python -m test -j3) and the sanity check (make patchcheck) and they worked fine.

----------
nosy: +moijes12
Added file: http://bugs.python.org/file30425/issue-17375-python33.patch

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

From report at bugs.python.org  Thu May 30 18:31:09 2013
From: report at bugs.python.org (Dmi Baranov)
Date: Thu, 30 May 2013 16:31:09 +0000
Subject: [docs] [issue17987] test.support.captured_stderr,
	captured_stdin not documented
In-Reply-To: <1368653423.88.0.898801742943.issue17987@psf.upfronthosting.co.za>
Message-ID: <1369931469.46.0.321672729743.issue17987@psf.upfronthosting.co.za>


Dmi Baranov added the comment:

Amended

----------
Added file: http://bugs.python.org/file30430/issue17987_6.patch

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

From report at bugs.python.org  Fri May 31 11:41:45 2013
From: report at bugs.python.org (Cherniavsky Beni)
Date: Fri, 31 May 2013 09:41:45 +0000
Subject: [docs] [issue10224] Build 3.x documentation using python3.x
In-Reply-To: <1288304199.49.0.7053863257.issue10224@psf.upfronthosting.co.za>
Message-ID: <1369993305.57.0.262076810834.issue10224@psf.upfronthosting.co.za>


Cherniavsky Beni added the comment:

I was only thinking of 3.4, which will have venv and a pip bootstrapper.
Is changing the doc build / doctest in scope for minor releases of 3.3 (or even earlier)?

The commands I listed (using setup_distribute.py) also work with 3.3.
(But they're unsecure -- https://bitbucket.org/tarek/distribute/issue/374/)
3.2 is harder as it doesn't even have builtin venv.

----------

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

From report at bugs.python.org  Fri May 31 22:20:02 2013
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 31 May 2013 20:20:02 +0000
Subject: [docs] [issue18085] Verifying refcounts.dat
In-Reply-To: <1369768958.38.0.697954786488.issue18085@psf.upfronthosting.co.za>
Message-ID: <1370031601.84.0.0718585665567.issue18085@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Since creating refcounts.dat many functions changed their argument's types from `char*` to `const char*`. Here is a patch which fixes mismatches (perhaps not all).

refcounts.dat in 3.x contains PyInt_* functions which don't exist in 3.x.

----------
keywords: +patch
Added file: http://bugs.python.org/file30436/refcounts_const_char.patch

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

From chrismeono1022 at gmail.com  Wed May  1 03:11:38 2013
From: chrismeono1022 at gmail.com (Christina Meono)
Date: Wed, 01 May 2013 01:11:38 -0000
Subject: [docs] hashlib - Missing FAQ section for hash collisions
Message-ID: <268B6C97-096A-4251-9B57-FF25401A4DF8@gmail.com>

Hello Python.org:

I was reading the docs for hashlib and there is a reference to algorithm
hash collisions, which the document specified would be addressed in an FAQ at the end of the doc, but said FAQ section cannot be found. Check it out here: 

http://docs.python.org/2/library/hashlib.html

Please let me know if you have any questions. 

Chris Meono
chrismeono1022 at gmail.com




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130501/8b360c1d/attachment.html>

From ezio.melotti at gmail.com  Wed May  1 22:50:41 2013
From: ezio.melotti at gmail.com (ezio.melotti at gmail.com)
Date: Wed, 01 May 2013 20:50:41 -0000
Subject: [docs] Improve the "introduction" page of the tutorial (issue
	14097)
Message-ID: <20130501205040.3838.49640@psf.upfronthosting.co.za>


http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (left):

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode110
Doc/tutorial/introduction.rst:110: Complex numbers are also supported;
imaginary numbers are written with a suffix
On 2013/05/01 18:30:31, r.david.murray wrote:
> The problem with completely omitting this is that the 'j' notation is
a special
> feature of the syntax, unlike Decimal or Fraction, which are "just"
specialized
> classes.

This could go in a footnote.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode551
Doc/tutorial/introduction.rst:551: object!  We'll come back to *object
semantics* later.
On 2013/05/01 18:30:31, r.david.murray wrote:
> On 2013/04/02 01:19:18, ezio.melotti wrote:
> > This is a fundamental concept, and this lighthearted introduction
only serves
> to
> > add more confusion IMHO.
> > I removed the example for now, but this should be covered at a later
point.
> 
> I think maybe you could (should) cover it at an *earlier* point, in
the
> discussion of [:] and what makes it a copy.

I think this should be presented in the second page, so that people can
first digest what they learned here.
If we put this at the end of the page they might end up reading it while
their brain is still overheating from the amount of information they
just learned and risk to misunderstand it.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (right):

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode69
Doc/tutorial/introduction.rst:69: >>>
On 2013/05/01 18:30:31, r.david.murray wrote:
> Why the "blank" line?  i fear the reader will wonder :)

That's because the following 3 commands are related, since they are
basically doing a divmod() and proving that it worked.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode76
Doc/tutorial/introduction.rst:76: 
On 2013/05/01 18:30:31, r.david.murray wrote:
> I know this is early in the tutorial, but should divmod be mentioned
here?

Maybe in a footnote, functions haven't even be introduced yet, and
divmod() is not really common.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode77
Doc/tutorial/introduction.rst:77: With Python is also possible to use
the ``**`` operator to calculate powers::
On 2013/05/01 18:30:31, r.david.murray wrote:
> "With Python it is also", but I'm not sure why "also"?  It doesn't
seem to be
> related to the discussion of division.
> 

Most of the other languages only provide the 4 basic operations, but
Python also provides **.

> The other problem with introducing ** here is that any discussion of
** should
> include a discussion of operator precedence and why -1**2 == -1.

That's too advanced/specific for now, I think it could be explained
somewhere else if necessary (or maybe in another footnote?).

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode92
Doc/tutorial/introduction.rst:92: If a variable is not "defined"
(assigned a value), trying to use it will
On 2013/05/01 18:30:31, r.david.murray wrote:
> I really don't like the use of the word 'defined' here.  I'd prefer
something
> like "A name must be assigned an initial value before it can be used. 
Trying to
> use a name that hasn't been assigned a value will give you an error:"

That doesn't sound too well to me.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode125
Doc/tutorial/introduction.rst:125: In addition to :class:`int` and
:class:`float`, Python supports other type of
On 2013/05/01 18:30:31, r.david.murray wrote:
> types

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode126
Doc/tutorial/introduction.rst:126: numbers, like :class:`complex`,
:class:`~decimal.Decimal`, and
On 2013/05/01 18:30:31, r.david.murray wrote:
> such as

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode137
Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the
same result.  ``\`` can be used to escape
On 2013/05/01 18:30:31, r.david.murray wrote:
> I'm not sure "with the same result" is at all clear, here.  I think it
would be
> better to just say "They can be enclosed in either single quotes
(``'...''') or
> double quotes (``"..."``)" and then have the next sentence read "``\``
can be
> used to escape a quote character in a string that is surrounded by
that same
> type of quote character::" which the examples with then make concrete.

"with the same result" is supposed to indicate that apart from the
(obvious) differences regarding the escaping of \' and \", they behave
the same.  In other languages there are differences between the two --
e.g. chars like \n and \t and variable interpolation only work with one
kind of quotes.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode141
Doc/tutorial/introduction.rst:141: 'spam eggs'
On 2013/05/01 18:30:31, r.david.murray wrote:
> I don't think the comments add any value.

They are useful for people who read only the examples, and to link part
of the description with the examples.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode153
Doc/tutorial/introduction.rst:153: By default, the interpreter encloses
the string output in quotes and escapes special characters with
backslashes.  The string is enclosed in
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would narrow this further, and say "At the command prompt, ...", or
"In the
> interactive interpreter" (shell?) since there really is no "default". 

s/By default/In the interactive interpreter/ SGTM.

> I also
> would prefer to retain the sense of the 'in the same way'
phrase...perhaps "in a
> way that they could be typed at the input prompt"?

"In the same way" is not totally accurate, because "s might end up
replaced with 's or the other way around.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode154
Doc/tutorial/introduction.rst:154: double quotes if the string contains
a single quote and no double quotes, else
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would rewrite this as "otherwise it is"

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode156
Doc/tutorial/introduction.rst:156: readable output, by removing the
enclosing quotes and by printing escaped and
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would say "omitting" rather than 'removing'.

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode166
Doc/tutorial/introduction.rst:166: >>> print(s)  # with print(), the
newline is printed
On 2013/05/01 18:30:31, r.david.murray wrote:
> Rather than "is printed", I would say "the newline produces a new line
in the
> output".

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode170
Doc/tutorial/introduction.rst:170: If you don't want to use special
characters, you can use *raw strings* by adding
On 2013/05/01 18:30:31, r.david.murray wrote:
> "If you don't want characters prefaced by ``\`` to be interpreted as
special
> characters, you can use..."

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode180
Doc/tutorial/introduction.rst:180: triple-quotes: ``"""..."""`` or
``'''...'''``.  End of lines are automatically
On 2013/05/01 18:30:31, r.david.murray wrote:
> "End of lines are automatically..." This is confusing without the
preceding
> example of escaping the ends of lines in a single quoted string.

This is presented in the next example though.
The idea is that first I introduce """...""" and \ and explain what they
do, then I show an example and its output, pointing out what """..."""
and \ did there.

>  That section
> should be retained, IMO. Despite the fact that it is not "best
practice" to
> write code that way, pedagogically it explains the concepts better.

The problem with that is that if people see it, it's likely they are
going to copy it and use it in their code.
Even if \ actually works even outside strings, the examples shows one of
the very few places where it's ok using it (IMHO).

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode208
Doc/tutorial/introduction.rst:208: >>> 'Py' 'thon'  # these string
literals are concatenated automatically
On 2013/05/01 18:30:31, r.david.murray wrote:
> comment is redundant.

The reason I added this was to show that those are string literals, even
if indeed it's already mentioned before.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode211
Doc/tutorial/introduction.rst:211: This only works with two literals
though, not with variables::
On 2013/05/01 18:30:31, r.david.murray wrote:
> "arbitrary string expressions" is more correct here than "variables".

It's more correct but less clear.  "variables or expressions" might be
OK though.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode213
Doc/tutorial/introduction.rst:213: >>> prefix = 'Py'
On 2013/05/01 18:30:31, r.david.murray wrote:
> I think you should include an expression example as well, such as
showing that
> the multiplication example doesn't work with string concatenation. 
(But you
> should reverse it, 'un' *3 'ium')

I preferred to show only one example, because each "failing" example
takes 5 more line, and having two tracebacks one after the other might
be confusing.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode252
Doc/tutorial/introduction.rst:252: Note that since -0 is really the same
as 0, negative indices start from -1.
On 2013/05/01 18:30:31, r.david.murray wrote:
> Perhaps "mathematically" rather than "really"?  Or just drop "really".
 And I'd
> start the sentence with "Because ``-0`` is the same as ``0``..."

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode254
Doc/tutorial/introduction.rst:254: In addition to indexing, *slicing* is
also supported. As the name says,
On 2013/05/01 18:30:31, r.david.murray wrote:
> Here again I prefer the original exposition, though we should drop the
reference
> to the Icon programming language.  I think most people will know what
a
> "substring" is, and if they don't the example will quickly make it
clear.

Using the term substring is OK.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode307
Doc/tutorial/introduction.rst:307: However these values are handled
gracefully when used for slicing::
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would write this "However, out of range slice indexes are handled
gracefully"

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode326
Doc/tutorial/introduction.rst:326: If you need a different string, you
can always create a new one::
On 2013/05/01 18:30:31, r.david.murray wrote:
> s/can always/should/

OK

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode367
Doc/tutorial/introduction.rst:367: items of different types, but usually
the items all have the same type. ::
On 2013/05/01 18:30:31, r.david.murray wrote:
> You are losing something here by omitting the example of items of
different
> type.  How about having both examples, and prefacing the second one
with,
> "Normally, however, lists elements will all be of the same type"?

I think it's not necessary, and it's better to keep the tutorial short.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode384
Doc/tutorial/introduction.rst:384: means that the following slice
returns a new (shallow) copy of the list::
On 2013/05/01 18:30:31, r.david.murray wrote:
> We probably ought to link this to "shallow copy" in the glossary...and
make an
> entry for it :)

OK (was there an issue for this?)

http://bugs.python.org/review/14097/

From cat at vv.carleton.ca  Sun May  5 07:23:42 2013
From: cat at vv.carleton.ca (Catalin Patulea)
Date: Sun, 05 May 2013 05:23:42 -0000
Subject: [docs] urlparse second example wrong output?
Message-ID: <CAE2LqH+1FYm-14fai2uj6KaPnwgsvc+oPB3s1Gf72-RUzyqweA@mail.gmail.com>

In the second example for urlparse:
http://docs.python.org/3.4/library/urllib.parse.html?highlight=urlparse

>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl:80/%7Eguido/Python.html',
           params='', query='', fragment='')

I think the "path=" component is wrong. ":80" shouldn't be there. Here
is what happens in 2.7:

In [2]: urlparse('www.cwi.nl/%7Eguido/Python.html')
Out[2]: ParseResult(scheme='', netloc='',
path='www.cwi.nl/%7Eguido/Python.html', params='', query='',
fragment='')

From ezio.melotti at gmail.com  Fri May 10 20:18:59 2013
From: ezio.melotti at gmail.com (ezio.melotti at gmail.com)
Date: Fri, 10 May 2013 18:18:59 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510181859.28616.97351@psf.upfronthosting.co.za>

Added a few comments, mostly about style.


http://bugs.python.org/review/17947/diff/8108/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode2
Lib/enum.py:2: Provides the Enum class, which can be subclassed to
create new, static, enumerations.
Line too long.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode86
Lib/enum.py:86: if key in self._enum_names and self[key] != something:
Does this mean than defining the same element twice with the same value
is allowed?
Is there any reason to allow this?

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode87
Lib/enum.py:87: raise TypeError('Attempted to reuse key: %s' % key)
Using %r is probably better.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode207
Lib/enum.py:207: + list(self.__members__))
The operator should go at the end of the previous line.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode244
Lib/enum.py:244: and base._enum_names):
The operator should go at the end of the previous line.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode270
Lib/enum.py:270: return obj_type, first_enum
You could simplify this a bit and save some indentation by doing:
if not bases:
    return object, Enum
for base in bases:
    ...

The same could also be done at line 252.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode284
Lib/enum.py:284: for possible in (obj_type, first_enum):
You could use sets here.

http://bugs.python.org/review/17947/

From ezio.melotti at gmail.com  Fri May 10 20:34:34 2013
From: ezio.melotti at gmail.com (ezio.melotti at gmail.com)
Date: Fri, 10 May 2013 18:34:34 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510183434.28617.46448@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode54
Lib/test/test_enum.py:54: class Test_Enum(unittest.TestCase):
TestEnum

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode100
Lib/test/test_enum.py:100: self.assertTrue(type(e) is Season)
assertIs

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode164
Lib/test/test_enum.py:164: self.assertEqual([k for k,v in
Season.__members__.items() if v.name != k], ['FALL', 'ANOTHER_SPRING'])
Line too long.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode174
Lib/test/test_enum.py:174: self.assertTrue(type(Huh.name) is Huh)
assertIs

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode216
Lib/test/test_enum.py:216: self.assertTrue(WeekDay.TEUSDAY is
WeekDay.TUESDAY)
assertIs

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode218
Lib/test/test_enum.py:218: self.assertEqual([k for k,v in
WeekDay.__members__.items() if v.name != k], ['TEUSDAY', ])
Line too long.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode227
Lib/test/test_enum.py:227: self.assertTrue(FloatStooges.CURLY is
loads(dumps(FloatStooges.CURLY)))
There are more assertTrue that should be converted to assertIs and
others.  In general assertTrue/False should be avoided if possible or a
message should be added, otherwise in case of failure, a non-informative
"False is not true" will be reported.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode377
Lib/test/test_enum.py:377: self.assertFalse(type(whatever.really) is
whatever)
assertIsNot

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode389
Lib/test/test_enum.py:389: self.assertFalse(Why.question in Why)
assertNotIn

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode534
Lib/test/test_enum.py:534: if isinstance( self, NamedInt ) and
isinstance( other, NamedInt ):
There are extra spaces here.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode543
Lib/test/test_enum.py:543: y = ('the-y', 2 )
Here too.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode556
Lib/test/test_enum.py:556: self.assertTrue(isinstance(SomeTuple.second,
tuple))
assertIsInstance

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode559
Lib/test/test_enum.py:559:
self.assertTrue(loads(dumps(SomeTuple.first)), SomeTuple.first)
I think you want an assertIs here too (as it is, SomeTuple.first is the
error message).

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode634
Lib/test/test_enum.py:634: self.assertTrue(Grade.B >= Grade.B)
You can use assertGreater and friends here.

http://bugs.python.org/review/17947/

From flash.is.dead at gmail.com  Tue May 21 07:08:57 2013
From: flash.is.dead at gmail.com (flash is dead)
Date: Tue, 21 May 2013 05:08:57 -0000
Subject: [docs] [Minor/Small] Documentation Bugs in "Idioms and Anti-Idioms
	in Python"
Message-ID: <CALi+P8C_t6g-fZ1LcfwGon1LG4qDJHQ4YWtsK6Hw5HpQ+=Np6g@mail.gmail.com>

Hello, I am a beginner in Python.
While reading through the documentation located at
http://docs.python.org/2/howto/doanddont.html section
http://docs.python.org/2/howto/doanddont.html#when-it-is-just-fine, I
found in that page a phrase said:

"When the module advertises itself as from import * safe."

Is that correct or I am not understand correctly since in the previous
sentences it says:
"from module import * "

Thank you.

From lyall.pearce at hp.com  Thu May  9 01:32:52 2013
From: lyall.pearce at hp.com (Pearce, Lyall)
Date: Wed, 08 May 2013 23:32:52 -0000
Subject: [docs] Documentation Bug: PythonHosted.org: feedparser 5.1.3 : HTTP
 Features
Message-ID: <922523C8EC4BC94DA3EF25CAEC14C77C1A0CB974@G2W2527.americas.hpqcorp.net>

I hope this is the right place to send this...

http://pythonhosted.org/feedparser/http-other.html#sending-custom-http-request-headers

>>> import feedparser
>>> d = feedparser.parse('http://feedparser.org/docs/examples/atom03.xml',
                          extra_headers={'Cache-control': 'max-age=0'})


Should be

>>> import feedparser
>>> d = feedparser.parse('http://feedparser.org/docs/examples/atom03.xml',
                          request_headers={'Cache-control': 'max-age=0'})


Lyall Pearce
Application Services

Lyall.Pearce at HP.com<mailto:Lyall.Pearce at HP.com>
T +61 8 8464 1356<tel:+61%208%208464%201356>
M+61 419 811 701<tel:+61%20419%20811%20701>
Hewlett-Packard Enterprise Services - South Pacific<http://hp.com/>
Level 10, 108 North Terrace
Adelaide, South Australia, 5000<http://maps.google.com/maps?q=106+North+Terrace,+Adelaide,+South+Australia,+Australia&hl=en&ll=-34.922118,138.596099&spn=0.001324,0.003184&sll=-34.92185,138.59571&sspn=0.001324,0.003184&hnear=106+North+Terrace,+Adelaide+South+Australia+5000,+Australia&t=m&z=19>
Australia<http://maps.google.com/maps?q=106+North+Terrace,+Adelaide,+South+Australia,+Australia&hl=en&ll=-27.916767,133.505859&spn=45.822563,104.326172&sll=-34.92185,138.59571&sspn=0.001324,0.003184&hnear=106+North+Terrace,+Adelaide+South+Australia+5000,+Australia&t=m&z=4>
Timezone: ACDT<http://timeanddate.com/library/abbreviations/timezones/au/cdt.html> +9:30

[Description: HP logo]

Please print thoughtfully

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130508/1dd1b8ea/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 2361 bytes
Desc: image001.png
URL: <http://mail.python.org/pipermail/docs/attachments/20130508/1dd1b8ea/attachment-0001.png>

From joe.jan21 at gmail.com  Fri May 10 01:08:48 2013
From: joe.jan21 at gmail.com (Joe Aikkaravelil)
Date: Thu, 09 May 2013 23:08:48 -0000
Subject: [docs] Broken link in http://docs.python.org/2/install/index.html
Message-ID: <CAGC3EamsO2v9MtVcQOkq5n2vtCF5VMoqc3DaOha=V3YVF4rHOA@mail.gmail.com>

I found a broken link in
http://docs.python.org/2/install/index.html#older-versions-of-python-and-mingw


"Older Versions of Python and
MinGW?<http://docs.python.org/2/install/index.html#older-versions-of-python-and-mingw>

The following instructions only apply if you?re using a version of Python
inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with
binutils-2.13.90-20030111-1).
These compilers require some special libraries. This task is more complex
than for Borland?s C++, because there is no program to convert the library.
First you have to create a list of symbols which the Python DLL exports.
(You can find a good program for this task at
http://www.emmestech.com/software/pexports-0.43/download_pexports.html)."

Thanks,
Joe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130509/1a7859cf/attachment-0001.html>

From alex.gaynor at gmail.com  Fri May 10 20:24:06 2013
From: alex.gaynor at gmail.com (alex.gaynor at gmail.com)
Date: Fri, 10 May 2013 18:24:06 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510182406.28616.49782@psf.upfronthosting.co.za>

A few small notes (I didn't do a complete review yet)


http://bugs.python.org/review/17947/diff/8110/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8110/Lib/enum.py#newcode55
Lib/enum.py:55: return self
Real properties don't mutate on setter/deleter/getter, but rather return
a new instance, I think this should probably mimic that behavior.

http://bugs.python.org/review/17947/diff/8110/Lib/enum.py#newcode68
Lib/enum.py:68: def __setitem__(self, key, something):
I think `value` is a more common name to use than `something`.

http://bugs.python.org/review/17947/

From alex.gaynor at gmail.com  Sat May 11 05:08:28 2013
From: alex.gaynor at gmail.com (alex.gaynor at gmail.com)
Date: Sat, 11 May 2013 03:08:28 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130511030827.28734.71723@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode57
Lib/enum.py:57: return self.__class__(self.fget, self.fset, self.fdel,
self.__doc__)
These don't seem to correctly mix the new func in.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode223
Lib/enum.py:223: raise AttributeError(name) from None
Is there a reason to use __getattr__ over descriptors?

http://bugs.python.org/review/17947/

From eliben at gmail.com  Sat May 11 05:23:58 2013
From: eliben at gmail.com (eliben at gmail.com)
Date: Sat, 11 May 2013 03:23:58 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130511032357.28617.74654@psf.upfronthosting.co.za>

Please use the code-review tool to either mark comments "Done" or
explain/disagree/discuss, before uploading the next patch.


http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode1
Lib/enum.py:1: """\
Again, *please* use PEP 257 convention. Even if you don't find the
multi-line convention pretty (I personally don't), it's far more
important for the code base to be consistently formatted than any
particular style.

One of the best things of Python as an open-source project is the
relative consistency of its source code due in terms of style.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode13
Lib/enum.py:13: """
PEP 257 everywhere...

"""First line of multi-line docstring.
Second line.
Third line. getting boring. Before the closing triple-quote we have an
empty line

"""

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode101
Lib/enum.py:101: """\
"""Metaclass for Enum"""

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode115
Lib/enum.py:115: __new__, save_new, use_args =
metacls._find_new(classdict, obj_type, first_enum)
80-column violation

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode174
Lib/enum.py:174: def __call__(cls, value, names=None, *, module=None,
type=None):
Explain the semantics of __call__ in detail in a docstring

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode214
Lib/enum.py:214: return cls._enum_map.copy()
I still don't like this copy(). Can you say what it is for? If someone
wants to screw an Enum up he can access _enum_map directly - Python
doesn't excel at data hiding. OTOH, copy needlessly makes innocent code
(99.99% of the code) slower.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode217
Lib/enum.py:217: """Return the enum item matching `name`"""
s/item/member/

Use members consistently everywhere

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode218
Lib/enum.py:218: if name[:2] == name[-2:] == '__':
You have this more than once in the code. Have a helper method
_is_dundername or something

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode275
Lib/enum.py:275: # now find the correct __new__, checking to see of one
was defined
Here and everywhere - use docstrings to provide a method documentation
note. Explain what each argument needs.

Inside the method you can use comments freely

http://bugs.python.org/review/17947/

From ethan at stoneleaf.us  Sun May 12 14:47:01 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Sun, 12 May 2013 12:47:01 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130512124700.9130.70651@psf.upfronthosting.co.za>

Reviewers: eli.bendersky, berkerpeksag, zach.ware, eric.araujo, ezio.melotti, alex,

Message:
Okay, just discovered the publish and mail portion.  This explains why
nobody was responding to my replies.  ;)


http://bugs.python.org/review/17947/diff/8105/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode2
Lib/enum.py:2: =========
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Yeah, remove this :-)

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode17
Lib/enum.py:17: 
On 2013/05/10 16:46:19, berkerpeksag wrote:
> Nit: Two blank lines. (see PEP 8 E302)

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode18
Lib/enum.py:18: class StealthProperty():
On 2013/05/10 16:46:19, berkerpeksag wrote:
> Is there a reason not to write `class StealthProperty:` (without the
brackets)
> here?

I just always use them.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode23
Lib/enum.py:23: # Used to provide access to the `name` and `value`
properties of enum
On 2013/05/10 16:02:43, eli.bendersky wrote:
> This class is quite generic though, and doesn't mention name or value
> properties. Document it in a generic way, and then inside the enum
class
> document how StealthProperty is actually being used.
> 
> Also, _StealthProperty as this is an internal class.

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode84
Lib/enum.py:84: if key[:2] == key[-2:] == '__' or hasattr(something,
'__get__'):
On 2013/05/10 16:02:43, eli.bendersky wrote:
> parenthesize the parts of the or

like:

if (key[:2] == key[-2:] == '__') or (hasattr(something, '__get__')):

?

Why?

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode85
Lib/enum.py:85: if key in self._enum_names:
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Wait what? This also contradicts the docstring. And why should we do
that? 
> 
> I see no reason to provide more safeguards in enum than regular Python
classes
> provide

Thought I had fixed the docstring.  Fixed now.

More safeguards for internal consistency: if we don't remove the name
from _enum_names then the descriptor would become an enum member, and
this is explicitly not allowed.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode92
Lib/enum.py:92: dict.__setitem__(self, key, something)
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Perhaps using super() here would be cleaner and more future-proof

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode94
Lib/enum.py:94: Enum = None  # dummy value until replaced
On 2013/05/10 16:02:43, eli.bendersky wrote:
> beefier comment that explains why this dummy is needed. Also, would
this need a
> docstring? I'm thinking of 
> 
> >> import enum
> >> help(enum.Enum)

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode97
Lib/enum.py:97: class EnumMeta(type):
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Should this be _EnumMeta too?

Whatever this name is will show up in `type(Color)`, and I think '<class
'enum._EnumMeta'> looks tacky.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode98
Lib/enum.py:98: """Metaclass for Enum
On 2013/05/10 16:02:43, eli.bendersky wrote:
> There's no point in repeating the docs here - *how* an enum behaves
belongs
> there. I'd suggest a detailed imlementation explanation instead here
in the
> code. I.e. how a new enum gets created, which metaclass methods get
invoked and
> what they do.
> 
> I'm not saying to put a metaclass tutorial here, but a bit of details
to help
> follow the flow of what happens when:
> 
> class Color(Enum):
>   red = 1
>   blue = 2
> 
> is defined

Hmmm.  This will take some thinking -- I'll come back to it.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode116
Lib/enum.py:116: # an Enum class is final once enumeration items have
been defined;
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Explain in more detail what a "data type" is

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode118
Lib/enum.py:118: # __new__ unless a new __new__ is defined (or the
resulting class
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Hmm, this __new__ protocol has to be documented on a higher level
first (in the
> docs?)

It's the same __new__ you find in the normal Python docs.  The
mind-bending part is that it's only used for construction of the enum
members -- after that it is replaced with Enum's __new__ (but saved in
case of subclassing)

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode127
Lib/enum.py:127: and issubclass(base, Enum)
On 2013/05/10 16:02:43, eli.bendersky wrote:
> indentation

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode130
Lib/enum.py:130: if not issubclass(base, Enum):
On 2013/05/10 16:02:43, eli.bendersky wrote:
> make it more explicit that base here is the last base!

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode133
Lib/enum.py:133: # get correct mixin_type (either mixin type of Enum
subclass,
On 2013/05/10 16:02:43, eli.bendersky wrote:
> theres no mixin_type in the code. also close the paren )

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode159
Lib/enum.py:159: if __new__ is None:
On 2013/05/10 16:02:43, eli.bendersky wrote:
> if would be great to make this method shorter. helper methods with
well-defined
> functionality and well-chosen names go a long way towards code
readability

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode240
Lib/enum.py:240: def __call__(cls, value, names=None, *,
module_name=None, type=None):
On 2013/05/10 16:02:43, eli.bendersky wrote:
> Hmm, PEP 435 says "module" not "module_name". While the latter is more
explicit,
> the former is shorter and it's a rather specialized case. I'll be on
the fence
> about this.

Changed back to `module`.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode244
Lib/enum.py:244: class_name = value  # better name for a name than value
;)
On 2013/05/10 16:02:43, eli.bendersky wrote:
> I'd suggest a new method here:
> 
> _make_enum_from_names(name, member_names, ....)

Not much happens before this point, and everything after this is about
making the enum class -- I don't see that breaking off 90% of this
method into another buys us much.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode280
Lib/enum.py:280: return cls._enum_map.copy()
On 2013/05/10 16:02:43, eli.bendersky wrote:
> why copy?

If we return the actual map, and it gets modified, our Enum class just
got destroyed (or at least corrupted).

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode318
Lib/enum.py:318: enum_member = cls._enum_map[enum_name]
On 2013/05/10 16:02:43, eli.bendersky wrote:
> why don't you just search enum_map directly?
> 

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode344
Lib/enum.py:344: @StealthProperty
On 2013/05/10 16:02:43, eli.bendersky wrote:
> OK, here a brief explanation of how _StealthProperty is actually used
*in Enum*
> and why

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode356
Lib/enum.py:356: if __name__ == '__main__':
On 2013/05/10 16:02:43, eli.bendersky wrote:
> remove this

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode1
Lib/test/test_enum.py:1: #!/usr/bin/python3.3
On 2013/05/10 18:30:30, eric.araujo wrote:
> I?d just delete the shebang actually, it won?t be useful in the
stdlib.

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode8
Lib/test/test_enum.py:8: print('Using Python', sys.version)
On 2013/05/10 17:30:54, zach.ware wrote:
> Extra output isn't very well appreciated in the test suite output.

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode54
Lib/test/test_enum.py:54: print(exc)
On 2013/05/10 17:30:54, zach.ware wrote:
> Since all of these above are simply creating enums without any kind of
special
> trickery going on, they really really shouldn't raise any exceptions. 
If they
> do, we should just let unittest handle them and flag the test as a
failure. 
> Taking out the try/excepts will also make Question's line short enough
:)

They shouldn't fail, but they have. ;)  They have to be in the module
name space for pickle tests, and if they raise an exception there no
other test will run.

Removed all the print statements.

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode103
Lib/test/test_enum.py:103: '<Season.{0}: {1}>'.format(season, i))
On 2013/05/10 17:30:54, zach.ware wrote:
> Whitespace between methods

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/test/test_enum.py#newcode634
Lib/test/test_enum.py:634: '''stub for testing one at a time'''
On 2013/05/10 17:30:54, zach.ware wrote:
> This should be removed.

Done.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode2
Lib/enum.py:2: Provides the Enum class, which can be subclassed to
create new, static, enumerations.
On 2013/05/10 20:18:59, ezio.melotti wrote:
> Line too long.

Done.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode8
Lib/enum.py:8: __all__ = ('Enum', 'IntEnum')
On 2013/05/10 18:30:30, eric.araujo wrote:
> Some tools (pydoc?) have issues if __all__ is not a list.

Done.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode86
Lib/enum.py:86: if key in self._enum_names and self[key] != something:
On 2013/05/10 20:18:59, ezio.melotti wrote:
> Does this mean than defining the same element twice with the same
value is
> allowed?
> Is there any reason to allow this?

Probably not, took it back out.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode87
Lib/enum.py:87: raise TypeError('Attempted to reuse key: %s' % key)
On 2013/05/10 20:18:59, ezio.melotti wrote:
> Using %r is probably better.

Done.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode207
Lib/enum.py:207: + list(self.__members__))
On 2013/05/10 20:18:59, ezio.melotti wrote:
> The operator should go at the end of the previous line.

Done.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode244
Lib/enum.py:244: and base._enum_names):
On 2013/05/10 20:18:59, ezio.melotti wrote:
> The operator should go at the end of the previous line.

Done.

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode270
Lib/enum.py:270: return obj_type, first_enum
On 2013/05/10 20:18:59, ezio.melotti wrote:
> You could simplify this a bit and save some indentation by doing:
> if not bases:
>     return object, Enum
> for base in bases:
>     ...
> 
> The same could also be done at line 252.

Good call.  Done.  (Couldn't do it at 252, though.)

http://bugs.python.org/review/17947/diff/8108/Lib/enum.py#newcode284
Lib/enum.py:284: for possible in (obj_type, first_enum):
On 2013/05/10 20:18:59, ezio.melotti wrote:
> You could use sets here.

I'm not sure how -- example?

http://bugs.python.org/review/17947/diff/8110/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8110/Lib/enum.py#newcode55
Lib/enum.py:55: return self
On 2013/05/10 20:24:06, alex wrote:
> Real properties don't mutate on setter/deleter/getter, but rather
return a new
> instance, I think this should probably mimic that behavior.

There's a getter as well?

http://bugs.python.org/review/17947/diff/8110/Lib/enum.py#newcode68
Lib/enum.py:68: def __setitem__(self, key, something):
On 2013/05/10 20:24:06, alex wrote:
> I think `value` is a more common name to use than `something`.

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode54
Lib/test/test_enum.py:54: class Test_Enum(unittest.TestCase):
On 2013/05/10 20:34:34, ezio.melotti wrote:
> TestEnum

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode64
Lib/test/test_enum.py:64: self.assertFalse(_errors)
On 2013/05/10 22:43:10, zach.ware wrote:
> This is better, but now any exceptions that are raised are masked. 
How about
> instead of assertFalse, do (untested):
> """
> for e in _errors:
>     with self.subTest():
>         raise e
> """
> 
> This is also going to cause a lot of NameErrors in the tests that use
these
> Enums, so it would be nice to set dummy values in the except clauses
and skip
> the tests that don't have the necessary Enum available.
> 
> On the other hand, I still think it would be just a whole lot simpler
to lose
> the try/excepts.  If actually creating the Enum is broken, I'd be more
concerned
> with getting that fixed than running the tests that can be run on
non-broken
> Enums.

Saving exceptions and reraising them in the appropriate test (good call,
thanks).

I like that better than having the entire module die, as sometimes
knowing what works is just as valuable as knowing what doesn't when
trying to track down a bug.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode100
Lib/test/test_enum.py:100: self.assertTrue(type(e) is Season)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> assertIs

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode164
Lib/test/test_enum.py:164: self.assertEqual([k for k,v in
Season.__members__.items() if v.name != k], ['FALL', 'ANOTHER_SPRING'])
On 2013/05/10 20:34:34, ezio.melotti wrote:
> Line too long.

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode174
Lib/test/test_enum.py:174: self.assertTrue(type(Huh.name) is Huh)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> assertIs

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode216
Lib/test/test_enum.py:216: self.assertTrue(WeekDay.TEUSDAY is
WeekDay.TUESDAY)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> assertIs

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode218
Lib/test/test_enum.py:218: self.assertEqual([k for k,v in
WeekDay.__members__.items() if v.name != k], ['TEUSDAY', ])
On 2013/05/10 20:34:34, ezio.melotti wrote:
> Line too long.

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode227
Lib/test/test_enum.py:227: self.assertTrue(FloatStooges.CURLY is
loads(dumps(FloatStooges.CURLY)))
On 2013/05/10 20:34:34, ezio.melotti wrote:
> There are more assertTrue that should be converted to assertIs and
others.  In
> general assertTrue/False should be avoided if possible or a message
should be
> added, otherwise in case of failure, a non-informative "False is not
true" will
> be reported.

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode377
Lib/test/test_enum.py:377: self.assertFalse(type(whatever.really) is
whatever)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> assertIsNot

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode389
Lib/test/test_enum.py:389: self.assertFalse(Why.question in Why)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> assertNotIn

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode534
Lib/test/test_enum.py:534: if isinstance( self, NamedInt ) and
isinstance( other, NamedInt ):
On 2013/05/10 20:34:34, ezio.melotti wrote:
> There are extra spaces here.

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode543
Lib/test/test_enum.py:543: y = ('the-y', 2 )
On 2013/05/10 20:34:34, ezio.melotti wrote:
> Here too.

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode556
Lib/test/test_enum.py:556: self.assertTrue(isinstance(SomeTuple.second,
tuple))
On 2013/05/10 20:34:34, ezio.melotti wrote:
> assertIsInstance

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode559
Lib/test/test_enum.py:559:
self.assertTrue(loads(dumps(SomeTuple.first)), SomeTuple.first)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> I think you want an assertIs here too (as it is, SomeTuple.first is
the error
> message).  

Done.

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode634
Lib/test/test_enum.py:634: self.assertTrue(Grade.B >= Grade.B)
On 2013/05/10 20:34:34, ezio.melotti wrote:
> You can use assertGreater and friends here.

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode1
Lib/enum.py:1: """\
On 2013/05/11 05:23:57, eli.bendersky wrote:
> Again, *please* use PEP 257 convention. Even if you don't find the
multi-line
> convention pretty (I personally don't), it's far more important for
the code
> base to be consistently formatted than any particular style.
> 
> One of the best things of Python as an open-source project is the
relative
> consistency of its source code due in terms of style.

Hadn't gotten that far yet.  ;)  Is it good now?

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode13
Lib/enum.py:13: """
On 2013/05/11 05:23:57, eli.bendersky wrote:
> PEP 257 everywhere...
> 
> """First line of multi-line docstring.
> Second line.
> Third line. getting boring. Before the closing triple-quote we have an
empty
> line
> 
> """

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode57
Lib/enum.py:57: return self.__class__(self.fget, self.fset, self.fdel,
self.__doc__)
On 2013/05/11 05:08:27, alex wrote:
> These don't seem to correctly mix the new func in.

Sorry, was on auto-pilot.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode101
Lib/enum.py:101: """\
On 2013/05/11 05:23:57, eli.bendersky wrote:
> """Metaclass for Enum"""

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode115
Lib/enum.py:115: __new__, save_new, use_args =
metacls._find_new(classdict, obj_type, first_enum)
On 2013/05/11 05:23:57, eli.bendersky wrote:
> 80-column violation

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode174
Lib/enum.py:174: def __call__(cls, value, names=None, *, module=None,
type=None):
On 2013/05/11 05:23:57, eli.bendersky wrote:
> Explain the semantics of __call__ in detail in a docstring

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode214
Lib/enum.py:214: return cls._enum_map.copy()
On 2013/05/11 05:23:57, eli.bendersky wrote:
> I still don't like this copy(). Can you say what it is for? If someone
wants to
> screw an Enum up he can access _enum_map directly - Python doesn't
excel at data
> hiding. OTOH, copy needlessly makes innocent code (99.99% of the code)
slower.

Doc string added.  I don't think speed is an issue.  I do think that
innocent user code shouldn't have to worry that removing an item, or
combining with another dict, will corrupt the enumeration.

If they access the private structure it's on them; if they access the
public interface we shouldn't be handing them a time-bomb.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode217
Lib/enum.py:217: """Return the enum item matching `name`"""
On 2013/05/11 05:23:57, eli.bendersky wrote:
> s/item/member/
> 
> Use members consistently everywhere

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode218
Lib/enum.py:218: if name[:2] == name[-2:] == '__':
On 2013/05/11 05:23:57, eli.bendersky wrote:
> You have this more than once in the code. Have a helper method
_is_dundername or
> something

Are you sure?  Seems like this would a much bigger performance hit than
the much rarer call on __members__... and I'm only using it twice.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode223
Lib/enum.py:223: raise AttributeError(name) from None
On 2013/05/11 05:08:27, alex wrote:
> Is there a reason to use __getattr__ over descriptors?

Yup, docstring added.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode275
Lib/enum.py:275: # now find the correct __new__, checking to see of one
was defined
On 2013/05/11 05:23:57, eli.bendersky wrote:
> Here and everywhere - use docstrings to provide a method documentation
note.
> Explain what each argument needs.
> 
> Inside the method you can use comments freely

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py#newcode9
Lib/test/test_enum.py:9: _errors = []
On 2013/05/11 06:42:08, zach.ware wrote:
> No longer needed.

Done.

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py#newcode16
Lib/test/test_enum.py:16: Stooges = exc
On 2013/05/11 06:42:08, zach.ware wrote:
> Not quite what I had in mind, but it does seem to work.  But may I ask
what your
> justification for keeping all the try/excepts and now the extra type
checking in
> the tests is?  If you've got a good reason, this method works for me;
I just
> think it could all be a whole lot simpler.

It is entirely possible (and, indeed, it happened to me ;) that only
some of these tests will fail.  If that happens, I still want the rest
to run so we can see what, if anything, is still working.  The whole
point of unit testing is to test everything, not shutdown on the first
failure.

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py#newcode64
Lib/test/test_enum.py:64: self.assertFalse(_errors)
On 2013/05/11 06:42:08, zach.ware wrote:
> This test is now useless, it can go.

Done.



Please review this at http://bugs.python.org/review/17947/

Affected files:
  Lib/enum.py
  Lib/test/test_enum.py



From ethan at stoneleaf.us  Sun May 12 14:49:55 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Sun, 12 May 2013 12:49:55 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130512124955.9130.43305@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8105/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode244
Lib/enum.py:244: class_name = value  # better name for a name than value
;)
On 2013/05/12 14:47:01, stoneleaf wrote:
> On 2013/05/10 16:02:43, eli.bendersky wrote:
> > I'd suggest a new method here:
> > 
> > _make_enum_from_names(name, member_names, ....)
> 
> Not much happens before this point, and everything after this is about
making
> the enum class -- I don't see that breaking off 90% of this method
into another
> buys us much.

Okay, it buys us better subclassing support.  Made new helper method
`_create`

http://bugs.python.org/review/17947/

From eliben at gmail.com  Sun May 12 15:02:00 2013
From: eliben at gmail.com (eliben at gmail.com)
Date: Sun, 12 May 2013 13:02:00 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130512130200.1275.63714@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8105/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode18
Lib/enum.py:18: class StealthProperty():
On 2013/05/12 14:47:00, stoneleaf wrote:
> On 2013/05/10 16:46:19, berkerpeksag wrote:
> > Is there a reason not to write `class StealthProperty:` (without the
brackets)
> > here?
> 
> I just always use them.

Remove them - they're not needed in Python 3 and their presence is
confusing.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode84
Lib/enum.py:84: if key[:2] == key[-2:] == '__' or hasattr(something,
'__get__'):
On 2013/05/12 14:47:00, stoneleaf wrote:
> On 2013/05/10 16:02:43, eli.bendersky wrote:
> > parenthesize the parts of the or
> 
> like:
> 
> if (key[:2] == key[-2:] == '__') or (hasattr(something, '__get__')):
> 
> ?
> 
> Why?

Because it's easier to read. The problem is that you have multiple
operators there. If you encapsulate the dunder check in a method, you
can keep it without the parens.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode280
Lib/enum.py:280: return cls._enum_map.copy()
On 2013/05/12 14:47:01, stoneleaf wrote:
> On 2013/05/10 16:02:43, eli.bendersky wrote:
> > why copy?
> 
> If we return the actual map, and it gets modified, our Enum class just
got
> destroyed (or at least corrupted).

That's tough life, no doubt ;-), but appropriate in Python. You can do
much worse things to objects and classes - we don't do safeguards here.
Consenting adults.

http://bugs.python.org/review/17947/

From eliben at gmail.com  Sun May 12 15:21:31 2013
From: eliben at gmail.com (eliben at gmail.com)
Date: Sun, 12 May 2013 13:21:31 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130512132130.9130.68068@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode214
Lib/enum.py:214: return cls._enum_map.copy()
On 2013/05/12 14:47:01, stoneleaf wrote:
> On 2013/05/11 05:23:57, eli.bendersky wrote:
> > I still don't like this copy(). Can you say what it is for? If
someone wants
> to
> > screw an Enum up he can access _enum_map directly - Python doesn't
excel at
> data
> > hiding. OTOH, copy needlessly makes innocent code (99.99% of the
code) slower.
> 
> Doc string added.  I don't think speed is an issue.  I do think that
innocent
> user code shouldn't have to worry that removing an item, or combining
with
> another dict, will corrupt the enumeration.
> 
> If they access the private structure it's on them; if they access the
public
> interface we shouldn't be handing them a time-bomb.

I see what you're saying and it makes sense in C++, but not in Python.
In Python it's so easy to screw everything up, such protections are not
usually done. You can start but you will never stop, because there're so
many. You can replace any method on an existing Python object, and
that's a "public interface".

>>> class Foo:
...   def bar(self): return 2
... 
>>> f = Foo()
>>> f.bar()
2
>>> f.bar = 10
>>> f.bar
10

I think that a documentation note that says the returned dict should not
be mucked with is good enough for __members__. If someone does care
about performance, the usual assumption is that copies are not being
made behind the back.

http://bugs.python.org/review/17947/

From eliben at gmail.com  Sun May 12 15:38:28 2013
From: eliben at gmail.com (eliben at gmail.com)
Date: Sun, 12 May 2013 13:38:28 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130512133828.9129.46450@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode214
Lib/enum.py:214: return cls._enum_map.copy()
On 2013/05/12 15:28:03, Nick Coghlan wrote:
> This kind of use case is exactly why types.MappingProxyType was made
visible at
> the Python layer (it's the impl of the read-only mappings used for
class
> dictionaries, and we use them there for a similar reason: modifying
the class
> contents without going through the class machinery simply isn't
something we
> want to allow).
> 
> So, rather than copying, I suggest returning
> types.MappingProxyType(cls._enum_map)
> 
> http://docs.python.org/3/library/types#types.MappingProxyType

Oh cool, I didn't know that existed (*blush*). Looks like a great
solution that addresses both concerns.

http://bugs.python.org/review/17947/

From alex.gaynor at gmail.com  Mon May 13 19:35:53 2013
From: alex.gaynor at gmail.com (alex.gaynor at gmail.com)
Date: Mon, 13 May 2013 17:35:53 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513173553.9130.27798@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode355
Lib/enum.py:355: return member
I would have assumed that that creating an enum from a value would be
O(1), not O(n), is there no way we can improve this?

http://bugs.python.org/review/17947/

From ethan at stoneleaf.us  Mon May 13 20:32:37 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Mon, 13 May 2013 18:32:37 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513183237.9130.85686@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8105/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode18
Lib/enum.py:18: class StealthProperty():
On 2013/05/12 15:02:00, eli.bendersky wrote:
> On 2013/05/12 14:47:00, stoneleaf wrote:
> > On 2013/05/10 16:46:19, berkerpeksag wrote:
> > > Is there a reason not to write `class StealthProperty:` (without
the
> brackets)
> > > here?
> > 
> > I just always use them.
> 
> Remove them - they're not needed in Python 3 and their presence is
confusing.

Done.

http://bugs.python.org/review/17947/diff/8105/Lib/enum.py#newcode280
Lib/enum.py:280: return cls._enum_map.copy()
On 2013/05/12 15:02:00, eli.bendersky wrote:
> On 2013/05/12 14:47:01, stoneleaf wrote:
> > On 2013/05/10 16:02:43, eli.bendersky wrote:
> > > why copy?
> > 
> > If we return the actual map, and it gets modified, our Enum class
just got
> > destroyed (or at least corrupted).
> 
> That's tough life, no doubt ;-), but appropriate in Python. You can do
much
> worse things to objects and classes - we don't do safeguards here.
Consenting
> adults.

That's not actually correct.  We don't do many, but we do do some.  dict
is a good example of a class with safeguards (which I just learned from
a PyCon 2013 talk by Raymond, I believe).

Furthermore, the whole Enum concept is based in part on safeguards, else
why the fuss about Animal instances not comparing equal to Shape
instances?

Plus, I'm not disallowing access to _enum_map -- if a user really wants
to, one can get to it and do whatever one wants for good or ill --
that's what consenting adults means to me... not "here's your drink, but
don't eat the ice, they're poisoned".  ;)

What it comes down to for me is, is the performance benefit of a rarely
called property worth the inevitable bugs caused by returning the actual
internal data structure?

The answer, again for me, is No.

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode214
Lib/enum.py:214: return cls._enum_map.copy()
On 2013/05/12 15:28:03, Nick Coghlan wrote:
> This kind of use case is exactly why types.MappingProxyType was made
visible at
> the Python layer (it's the impl of the read-only mappings used for
class
> dictionaries, and we use them there for a similar reason: modifying
the class
> contents without going through the class machinery simply isn't
something we
> want to allow).
> 
> So, rather than copying, I suggest returning
> types.MappingProxyType(cls._enum_map)
> 
> http://docs.python.org/3/library/types#types.MappingProxyType

Thanks, Nick -- that I can do.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode1
Lib/enum.py:1: """\
On 2013/05/13 19:06:12, zach.ware wrote:
> It's ok to lose the backslash here, but start the text on line 2.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode8
Lib/enum.py:8: from types import MappingProxyType
On 2013/05/13 19:06:12, zach.ware wrote:
> It looks better to order by 'import ...', then 'from ... import ...'
rather than
> intermixing.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode14
Lib/enum.py:14: """ Returns the value in the instance, raises
AtttributeError on the class.
On 2013/05/13 19:06:12, zach.ware wrote:
> Missed a space before Returns.  

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode14
Lib/enum.py:14: """ Returns the value in the instance, raises
AtttributeError on the class.
On 2013/05/13 19:25:49, isoschiz wrote:
> (minor) typo in "AtttributeError"

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode49
Lib/enum.py:49: """ Changes anything not dundered or that doesn't have
__get__.
On 2013/05/13 19:06:12, zach.ware wrote:
> Missed another space.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode56
Lib/enum.py:56: error is raised.
On 2013/05/13 19:25:49, isoschiz wrote:
> This sentence is not true (though it might be nicer if it was! i.e.
sometimes it
> might be easier when using the Functional API to just leave duplicates
in than
> round trip via an "OrderedSet").

Forgot to update the docstring. Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode85
Lib/enum.py:85: def __new__(metacls, cls, bases, classdict):
On 2013/05/13 19:06:12, zach.ware wrote:
> This method really just looks like a giant wall of code to me, not
very
> readable.  PEP 8 suggests "[Using] blank lines in functions,
sparingly, to
> indicate logical sections", which I would take to mean roughly before
and/or
> after each top-level (within the method) for or if statement,
thereabouts.  Or,
> in this case, before each comment block would seem appropriate.

I was wondering if I could add some blank lines.  Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode92
Lib/enum.py:92: metacls._find_new(classdict, obj_type, first_enum)
On 2013/05/13 19:06:12, zach.ware wrote:
> PEP 8 recommends avoiding backslashes for line continuation; it would
be better
> to split the line in the _find_new call, I think.
> 
> """
>         __new__, save_new, use_args = metacls._findnew(classdict,
>                                                        obj_type,
>                                                        first_enum)
> """

How about:

"""
        __new__, save_new, use_args = (
                metacls._find_new(classdict, obj_type, first_enum)
                )
"""

?

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/13 19:25:49, isoschiz wrote:
> Shouldn't this technically be a use of super()? Not that I guess
complex type
> hierarchies of Metaclasses are common.

__new__ is one of the few things (the only thing?) that cannot be shared
-- you can only create an object once.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode114
Lib/enum.py:114: if not isinstance(value, tuple):
On 2013/05/13 19:25:49, isoschiz wrote:
> Doesn't this produce weird behaviour for the following definition:
> 
> class MyEnum(Enum):
>     FOO = 7
>     BAR = (42, 8)
>     BAZ = "hello"

Did you try it?
"""
--> class MyEnum(Enum): FOO = 7; BAR = (42, 8); BAZ = "hello"
... 
--> MyEnum
<enum 'MyEnum'>
--> list(MyEnum)
[<MyEnum.FOO: 7>, <MyEnum.BAR: (42, 8)>, <MyEnum.BAZ: 'hello'>]
--> MyEnum.BAR
<MyEnum.BAR: (42, 8)>
--> MyEnum.BAR.value == (42, 8)
True
"""

Looks good to me. ;)

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode123
Lib/enum.py:123: enum_item = __new__(enum_class, *args)
On 2013/05/13 19:25:49, isoschiz wrote:
> Is it explicitly forbidden to have multi type enums (i.e. ones where
different
> items have different values)? This code assumes that the __new__ from
the first
> type can cope with the args from the latter ones. I believe the
__new__ needs to
> be re-calculated on each enum item in order to correctly cope.

If it's a mixed enum (like IntEnum) all the values must be of the mixed
in type; if it's a plain Enum, object.__new__ is used and the value set
afterwards.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode224
Lib/enum.py:224: def _create(cls, class_name, names=None, *,
module=None, type=None):
On 2013/05/13 19:06:12, zach.ware wrote:
> This one could also do with a touch of whitespace to make it more
readable.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode258
Lib/enum.py:258: def _get_mixins(bases):
On 2013/05/13 19:06:12, zach.ware wrote:
> Whitespace wouldn't be amiss.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode300
Lib/enum.py:300: def _find_new(classdict, obj_type, first_enum):
On 2013/05/13 19:06:12, zach.ware wrote:
> Another whitespace request.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode323
Lib/enum.py:323: Enum.__new__):
On 2013/05/13 19:25:49, isoschiz wrote:
> This should be a set literal, not a tuple.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode341
Lib/enum.py:341: """valueless, unordered enumeration class"""
On 2013/05/13 19:06:12, zach.ware wrote:
> Capitalize "Valueless"

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode355
Lib/enum.py:355: return member
On 2013/05/13 19:35:53, alex wrote:
> I would have assumed that that creating an enum from a value would be
O(1), not
> O(n), is there no way we can improve this?

Sure, but it would add a bunch of complexity, and is it worth it for a
one time operation?

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode5
Lib/test/test_enum.py:5: import sys
On 2013/05/13 19:06:12, zach.ware wrote:
> Same comment here as on the enum.py imports.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode100
Lib/test/test_enum.py:100: '<Season.{0}: {1}>'.format(season, i))
On 2013/05/13 19:06:12, zach.ware wrote:
> PEP 8 violation; this line should either move over to match repr(e),
or repr(e)
> should move to the next line.
> 
> (Nitpicking, ahoy!)

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode161
Lib/test/test_enum.py:161: if v.name != k], ['FALL', 'ANOTHER_SPRING'])
On 2013/05/13 19:06:12, zach.ware wrote:
> This could be broken into separate lines better; the listcomp could
start on the
> second line, and the list could be on a third line.  Breaking the
listcomp into
> two lines confused me for a bit when I saw it.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode192
Lib/test/test_enum.py:192: THURSDAY FRIDAY SATURDAY'''.split(), 1):
On 2013/05/13 19:06:12, zach.ware wrote:
> I think this might be made more readable by creating a list from the
"SUNDAY
> MONDAY..." string before the loop statement and passing it in to
enumerate.

Done.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode285
Lib/test/test_enum.py:285: self.assertEqual([SummerMonth.june,
SummerMonth.july, SummerMonth.august], lst)
On 2013/05/13 19:06:12, zach.ware wrote:
> Line too long, there's a few cases of this here and below.

Done.

http://bugs.python.org/review/17947/

From alex.gaynor at gmail.com  Mon May 13 20:34:50 2013
From: alex.gaynor at gmail.com (alex.gaynor at gmail.com)
Date: Mon, 13 May 2013 18:34:50 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513183450.9130.67085@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode355
Lib/enum.py:355: return member
On 2013/05/13 20:32:37, stoneleaf wrote:
> On 2013/05/13 19:35:53, alex wrote:
> > I would have assumed that that creating an enum from a value would
be O(1),
> not
> > O(n), is there no way we can improve this?
> 
> Sure, but it would add a bunch of complexity, and is it worth it for a
one time
> operation?

Why do you think it's a one time operation? Everytime you do something
like "turn a C errono into an enum" you go through this.

http://bugs.python.org/review/17947/

From ethan at stoneleaf.us  Mon May 13 20:39:24 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Mon, 13 May 2013 18:39:24 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513183924.1275.61948@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode355
Lib/enum.py:355: return member
On 2013/05/13 20:34:50, alex wrote:
> On 2013/05/13 20:32:37, stoneleaf wrote:
> > On 2013/05/13 19:35:53, alex wrote:
> > > I would have assumed that that creating an enum from a value would
be O(1),
> > not
> > > O(n), is there no way we can improve this?
> > 
> > Sure, but it would add a bunch of complexity, and is it worth it for
a one
> time
> > operation?
> 
> Why do you think it's a one time operation? Everytime you do something
like
> "turn a C errono into an enum" you go through this.

Sorry, saw the __new__ and thought you were talking about the initial
class creation.

I would say this is worth optimizing.  I'll get something in place.

http://bugs.python.org/review/17947/

From ethan at stoneleaf.us  Tue May 14 00:09:15 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Mon, 13 May 2013 22:09:15 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513220915.9130.71055@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 00:01:06, isoschiz wrote:
> On 2013/05/13 20:32:37, stoneleaf wrote:
> > On 2013/05/13 19:25:49, isoschiz wrote:
> > > Shouldn't this technically be a use of super()? Not that I guess
complex
> type
> > > hierarchies of Metaclasses are common.
> > 
> > __new__ is one of the few things (the only thing?) that cannot be
shared --
> you
> > can only create an object once.
> 
> And yet in this instance you are deferring to your superclass'
__new__. If
> someone mixes in an extension type with a custom __new__ as well as
Enum, then
> this will break. Using super() will make that possible.

I don't understand.  Can you provide an example?

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode114
Lib/enum.py:114: if not isinstance(value, tuple):
On 2013/05/14 00:01:06, isoschiz wrote:
> On 2013/05/13 20:32:37, stoneleaf wrote:
> > On 2013/05/13 19:25:49, isoschiz wrote:
> > > Doesn't this produce weird behaviour for the following definition:
> > > 
> > > class MyEnum(Enum):
> > >     FOO = 7
> > >     BAR = (42, 8)
> > >     BAZ = "hello"
> > 
> > Did you try it?
> > """
> > --> class MyEnum(Enum): FOO = 7; BAR = (42, 8); BAZ = "hello"
> > ... 
> > --> MyEnum
> > <enum 'MyEnum'>
> > --> list(MyEnum)
> > [<MyEnum.FOO: 7>, <MyEnum.BAR: (42, 8)>, <MyEnum.BAZ: 'hello'>]
> > --> MyEnum.BAR
> > <MyEnum.BAR: (42, 8)>
> > --> MyEnum.BAR.value == (42, 8)
> > True
> > """
> > 
> > Looks good to me. ;)
> 
> I must confess I didn't try it - apologies. :-)
> 
> Although as a corollary, the code is dense enough that I can't work
out in a
> straightforward way why this works! Perhaps some more comments would
help?

Probably because it doesn't work straight-forwardly. ;-)

I'll add some comments when I get some time, and figure out how to
detail the convoluted path involved.

http://bugs.python.org/review/17947/

From ethan at stoneleaf.us  Tue May 14 01:41:47 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Mon, 13 May 2013 23:41:47 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513234145.9129.68973@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 01:29:56, isoschiz wrote:
> On 2013/05/14 00:09:15, stoneleaf wrote:
> > On 2013/05/14 00:01:06, isoschiz wrote:
> > > On 2013/05/13 20:32:37, stoneleaf wrote:
> > > > On 2013/05/13 19:25:49, isoschiz wrote:
> > > > > Shouldn't this technically be a use of super()? Not that I
guess complex
> > > type
> > > > > hierarchies of Metaclasses are common.
> > > > 
> > > > __new__ is one of the few things (the only thing?) that cannot
be shared
> --
> > > you
> > > > can only create an object once.
> > > 
> > > And yet in this instance you are deferring to your superclass'
__new__. If
> > > someone mixes in an extension type with a custom __new__ as well
as Enum,
> then
> > > this will break. Using super() will make that possible.
> > 
> > I don't understand.  Can you provide an example?
> 
> It requires writing an extension type (i.e. a type defined in C in an
extension
> module), which will have its own __new__ - let's call this type
ext.Parent
> 
> class MyEnumMeta(Enum, ext.Parent): pass
> 
> will now not do what is expected. Even though in the mro ext.Parent
comes before
> type, the __new__ in Enum delegates directly to type, bypassing
ext.Parent.
> Using super() here produces the desired behaviour.
> 
> In either case, your statement about __new__ only being able to be
called once
> is true. The question though is which __new__ actually gets to do the
work. We
> shouldn't presuppose that type.__new__ is what the user needs.
> 
> (I must confess I've not tried this with "type", but it definitely
fails when
> deferring to "object.__new__" instead of the extension class' __new__)

I think you are confusing the metaclass __new__ with the class __new__. 
There is already support to find (right above this code, actually) the
correct __new__ to use to create the class instances (aka members): 
first it looks in the Enum hierarchy for a custom __new__, then it looks
in the mixed-in type (ext.Parent in your case) for a __new__ to use.  If
there is no custom __new__ and no other type was mixed in,
object.__new__ gets used.

Or maybe you made a typo, and meant `class MyEnumMeta(EnumMeta,
ext.Parent)`; I have no experience with extension classes so I'm not
sure what happens metaclass wise when one is mixed with a native python
type.

Decimal now has a C version, doesn't it?  I'll a test with that and see
what happens.

http://bugs.python.org/review/17947/

From michael.karpeles at gmail.com  Tue May 14 10:48:01 2013
From: michael.karpeles at gmail.com (Michael Karpeles)
Date: Tue, 14 May 2013 08:48:01 -0000
Subject: [docs] Typo in http://docs.python.org/2/extending/extending.htm
Message-ID: <CAHhJ=PsTytSZRF1_qF1HSGWHXMkZdCxu_reU8LBf39B1kY7qxQ@mail.gmail.com>

Howdy friends,

In document http://docs.python.org/2/extending/extending.html, the last
code snippet at the bottom of section The Module's Method Table and
Initialization Function:

intmain(int argc, char *argv[]){
    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(argv[0]);

    /* Initialize the Python interpreter.  Required. */
    Py_Initialize();

    /* Add a static module */
    initspam();

The function is missing a terminating }

best wishes + happy hacking,

- mek
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130514/c2ccdd5a/attachment-0001.html>

From ethan at stoneleaf.us  Tue May 14 20:18:48 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Tue, 14 May 2013 18:18:48 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130514181848.9129.49152@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 20:12:43, isoschiz wrote:
> 
> Sorry - I did typo: I meant MyEnumMeta, as you indicated.
> 
> The Decimal implementation may indeed exhibit the problem. However, I
think it
> can easily be solved by just replacing type with super() in that line.
It will
> work identically in all of the simple cases, but should also work
should anyone
> want to do anything "weird".
> 
> Also note that this can also apply if the __new__ methods are doing
some extra
> work (either before or after the actual allocation), exactly like this
function.
> So even if ext.Parent wasn't an extension class, it might want it's
__new__
> called so it could, say, add a new property into the classdict or
similar.

One of us is confused -- and I don't know which of us it is! ;)

I'll try it both ways with cDecimal as soon as I get a chance, but as
far as cooperitive _new__'s how would that work?  If A calls B's
__new__, which creates an object, and B calls C's __new__ which creates
an object, which one am I getting back? If we reverse that, and B and C
call the next __new__ before creating an object, won't we eventually hit
type, and definitely not have the correct object?

http://bugs.python.org/review/17947/

From jjlemire at gmail.com  Tue May 14 21:00:00 2013
From: jjlemire at gmail.com (JJ Lemire)
Date: Tue, 14 May 2013 19:00:00 -0000
Subject: [docs] Sotfware version and documentation slightly out of sync.
Message-ID: <CAO3SRehppE-43UhxGzayghv6zucRDj+6YQ0iD_P2nT_0Ksh4FQ@mail.gmail.com>

As of 2014.May.14 at 14:57 the current version of python is 3.3.1
but the documentation is 3.3.2, no the same.

I usually download the html version for speed.

Just let you know.

Thanks -- J Lemire
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130514/c5f210f5/attachment-0001.html>

From ethan at stoneleaf.us  Tue May 14 21:04:03 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Tue, 14 May 2013 19:04:03 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130514190402.31536.33759@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 20:40:09, isoschiz wrote:
> 
> It is clearly not desirable to not let Foo have a go, just because Baz
got in
> the way. Without super() in this line of EnumMeta, you have the same
possibility
> of breaking some folks using the metaclass, if EnumMeta is passed as
the first
> base.

Ah, now I understand.  Thank you for taking the time to explain!  Change
made.

Of course, now I have to make a test with another metaclass mixed in...
*sigh*.  ;)

http://bugs.python.org/review/17947/

From jmsachs at gmail.com  Thu May 16 19:04:43 2013
From: jmsachs at gmail.com (Jason Sachs)
Date: Thu, 16 May 2013 17:04:43 -0000
Subject: [docs] typo in http://docs.python.org/2/howto/argparse.html
Message-ID: <CAOo6sOOaXyyw9b0vrM5DjPjjF3RYN8xM8sFOm_5uoEEfT7k47Q@mail.gmail.com>

minor grammatical typo:

?how it works simply by reading it?s help text?: ?it?s? should be ?its?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130516/15c33237/attachment-0001.html>

From alex.gaynor at gmail.com  Fri May 17 15:59:33 2013
From: alex.gaynor at gmail.com (alex.gaynor at gmail.com)
Date: Fri, 17 May 2013 13:59:33 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130517135933.15529.63273@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8161/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode146
Lib/enum.py:146: enum_class.__module__ = 'uh uh'
Can we use a slightly more formal value here?

http://bugs.python.org/review/17947/

From ethan at stoneleaf.us  Fri May 17 17:40:14 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Fri, 17 May 2013 15:40:14 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130517154014.15593.51221@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8161/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode7
Lib/enum.py:7: import weakref
On 2013/05/17 15:37:11, zach.ware wrote:
> As pointed out by Donald Stufft on the issue, weakref is unused.
> 
> (Just to have a comment on it :))

Yeah, I was going to use it, then didn't.  Removed.

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode37
Lib/enum.py:37: def dunder(name):
On 2013/05/17 15:37:11, zach.ware wrote:
> Might be better named "is_dunder" since you're asking if it is, not
making it
> so.

Done.

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode52
Lib/enum.py:52: raise TypeError('%r cannot be pickled' % self)
Done.

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode123
Lib/enum.py:123: "'_find_new' cannot be used for members")
I'd rather not -- seems like it would be easy to miss a trailing
underscore.  Also, in the tuple case the _as_dict method is actually
public -- these aren't.

If we're going to reserve an entire namespace, how about '_somename_' ?

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode146
Lib/enum.py:146: enum_class.__module__ = 'uh uh'
If you insist. ;)

Went with 'not picklable'.

http://bugs.python.org/review/17947/diff/8161/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8161/Lib/test/test_enum.py#newcode2
Lib/test/test_enum.py:2: import sys
On 2013/05/17 15:37:11, zach.ware wrote:
> Turns out sys isn't used here, either.

Done.

http://bugs.python.org/review/17947/

From huohuarong at gmail.com  Mon May 20 12:21:24 2013
From: huohuarong at gmail.com (huarong huo)
Date: Mon, 20 May 2013 10:21:24 -0000
Subject: [docs] report a document bug in module tempfile
Message-ID: <CAFRex6xEWt+-55FiCmpWGr4M8PDX0J496EKm7FFXpve5a7RhYw@mail.gmail.com>

The document<file:///C:/Users/Dell/Dropbox/Documents/python-2.7.4-docs-html/python-2.7.4-docs-html/library/tempfile.html>
 says:

tempfile.NamedTemporaryFile([*mode='w+b'*[, *bufsize=-1*[, *suffix=''*[, *
prefix='tmp'*[, *dir=None*[,
*delete=True*]]]]]])<file:///C:/Users/Dell/Dropbox/Documents/python-2.7.4-docs-html/python-2.7.4-docs-html/library/tempfile.html#tempfile.NamedTemporaryFile>

This function operates exactly as
TemporaryFile()<file:///C:/Users/Dell/Dropbox/Documents/python-2.7.4-docs-html/python-2.7.4-docs-html/library/tempfile.html#tempfile.TemporaryFile>
does,
except that the file is guaranteed to have a visible name in the file
system(on Unix, the directory entry is not unlinked). That name can be
retrieved
from the name attribute of the file object.

But They both have a name attribute as follow:

In [1]: import tempfile

In [2]: a = tempfile.TemporaryFile()

In [3]: a.name
Out[3]: 'c:\\users\\dell\\appdata\\local\\temp\\tmptkebgx'

In [4]: b = tempfile.NamedTemporaryFile()

In [5]: b.name
Out[5]: 'c:\\users\\dell\\appdata\\local\\temp\\tmpwqmonk'

So what's the difference?

my machine:
python: 2.7.4
os: windows 7 (32bit)

Thank you!

Huo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130520/3f651ea4/attachment-0001.html>

From ethan at stoneleaf.us  Mon May 20 13:47:00 2013
From: ethan at stoneleaf.us (ethan at stoneleaf.us)
Date: Mon, 20 May 2013 11:47:00 -0000
Subject: [docs] Inconsistency between b32decode() documentation,
 docstring and code (issue 18011)
Message-ID: <20130520114700.3384.93289@psf.upfronthosting.co.za>


http://bugs.python.org/review/18011/diff/8191/Lib/base64.py
File Lib/base64.py (right):

http://bugs.python.org/review/18011/diff/8191/Lib/base64.py#newcode225
Lib/base64.py:225: raise binascii.Error('Non-base32 digit found')
Should we add a `from None` here to suppress the double exception
traceback?

http://bugs.python.org/review/18011/

From ZerbeB at humgen.ucsf.edu  Thu May 23 08:49:56 2013
From: ZerbeB at humgen.ucsf.edu (Zerbe, Brandon)
Date: Thu, 23 May 2013 06:49:56 -0000
Subject: [docs] from email import message_from_file
Message-ID: <18D8F2D99B52764489A4808889E71CE323B0C857@ex05.net.ucsf.edu>

To others with more experience and knowledge about python than I:

I was unable to run virtualenv due to an error.  Logging into an interactive session on Centos 6.2, I was able to recreate it:

>>>import distutils.dist
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/mnt/iscsi_speed/devel/Python-2.7.3_2/lib/python2.7/distutils/dist.py", line 10, in <module>
   from email import message_from_file
ImportError: cannot import name message_from_file

I get the same error for >>>from email import message_for_file.  However, >>>import email works fine, and email.message_from_file then works.

For my installation, I changed the code in /mnt/iscsi_speed/devel/Python-2.7.3_2/lib/python2.7/distutils/dist.py to import email and then the call to message_from_file to email.message_from_file.  After doing this, I could run virtualenv.  However, I am relatively new to python, and do not complete understand the cause of this issue (perhaps something with packaging?)

Sorry if this is a re-post, but I thought you might like to know.

Thanks,

B
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130523/0e071da4/attachment-0001.html>

From harjolgoo at gmail.com  Fri May 24 11:30:10 2013
From: harjolgoo at gmail.com (Harjol Goo)
Date: Fri, 24 May 2013 09:30:10 -0000
Subject: [docs] Reporting Bugs on The Python Tutorial by version 3.3.2
Message-ID: <CAChBgGxtOw_XdJJNFQ6o4NnUsRqp8EAr71XbFoiiG9-s=OCgPA@mail.gmail.com>

Hi,

When I red the Python Tutorial on this website
http://docs.python.org/3/tutorial/controlflow.html
I found a example in
4.4. break <http://docs.python.org/3/reference/simple_stmts.html#break> and
continue <http://docs.python.org/3/reference/simple_stmts.html#continue>
Statements,
and else <http://docs.python.org/3/reference/compound_stmts.html#else> Clauses
on Loops
worked out a different output on my local IDLE

The example is :

>>> 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')

and the first output you gave is :

2 is a prime number

How come? when n is 2, then range(2,n) becomes range(2,2), it has none
element, thus '2 is a prime number' cannot be print out.

On my local IDLE, the output is:

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

Seems that break does not work too.

Best Regards,
Harjol Goo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130524/11ff0823/attachment-0001.html>

From iannucci at google.com  Fri May 24 22:50:09 2013
From: iannucci at google.com (Robert Iannucci)
Date: Fri, 24 May 2013 20:50:09 -0000
Subject: [docs] Bug in documentation for argparse type.
Message-ID: <CA+q_oBdzFnYZH1aLQ_h3M_X=jgVqL9t_g4QTLF26DPB1tAMGGg@mail.gmail.com>

Hello!

In the very first example for argparse type, there's a type being set to
'open' (the python builtin). However, immediately following that, the
documentation suggests using argparse.FileType instead.

http://docs.python.org/dev/library/argparse.html#type

While open technically works for type (for read-only files), it may make
sense for the first example to demonstrate the 'right' way so users aren't
tempted to do type=lambda x: open(x, 'w') instead of argparse.FileType('w').

Cheers,
Robbie
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130524/43547ee0/attachment-0001.html>

From jason.scherer at gmail.com  Thu May 30 11:58:02 2013
From: jason.scherer at gmail.com (Jason Scherer)
Date: Thu, 30 May 2013 09:58:02 -0000
Subject: [docs] doc bug: confusing table of values
Message-ID: <CAOaTG=63P-5B04GDz2mCyoEgC01yio6bXGwCxvBgfrfXJk6i+A@mail.gmail.com>

On this page:

http://docs.python.org/2/library/xml.html

The table of truth values is a bit confusing because it's not clear from
the context what it's actually saying is true, or false.

It might be better to replace the words "true" and "false" with
"vulnerable" and "protected" or something like that.  Otherwise, I can't
tell if "true" means "yes, this parser is vulnerable to this attack" or if
"true" means "yes, this parser is protected from this attack"
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130530/16619927/attachment-0001.html>

From rdmurray at bitdance.com  Wed May  1 18:30:31 2013
From: rdmurray at bitdance.com (rdmurray at bitdance.com)
Date: Wed, 01 May 2013 16:30:31 -0000
Subject: [docs] Improve the "introduction" page of the tutorial (issue
	14097)
Message-ID: <20130501163031.26820.7319@psf.upfronthosting.co.za>

Sorry, Ezio, I do have comments :)


http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (left):

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode110
Doc/tutorial/introduction.rst:110: Complex numbers are also supported;
imaginary numbers are written with a suffix
The problem with completely omitting this is that the 'j' notation is a
special feature of the syntax, unlike Decimal or Fraction, which are
"just" specialized classes.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode551
Doc/tutorial/introduction.rst:551: object!  We'll come back to *object
semantics* later.
On 2013/04/02 01:19:18, ezio.melotti wrote:
> This is a fundamental concept, and this lighthearted introduction only
serves to
> add more confusion IMHO.
> I removed the example for now, but this should be covered at a later
point.

I think maybe you could (should) cover it at an *earlier* point, in the
discussion of [:] and what makes it a copy.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (right):

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode63
Doc/tutorial/introduction.rst:63: Classic division (``/``) always
returns a float.  To do integer division and
"Classic" sounds wrong here.  Perhaps "normal" (as opposed to
"integer")?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode69
Doc/tutorial/introduction.rst:69: >>>
Why the "blank" line?  i fear the reader will wonder :)

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode76
Doc/tutorial/introduction.rst:76: 
I know this is early in the tutorial, but should divmod be mentioned
here?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode77
Doc/tutorial/introduction.rst:77: With Python is also possible to use
the ``**`` operator to calculate powers::
"With Python it is also", but I'm not sure why "also"?  It doesn't seem
to be related to the discussion of division.

The other problem with introducing ** here is that any discussion of **
should include a discussion of operator precedence and why -1**2 == -1.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode84
Doc/tutorial/introduction.rst:84: The equal sign (``'='``) is used to
assign a value to a variable. Afterwards, no
I agree with the comments in the issue that 'name' should be used
instead of variable, but that can be a separate patch :)

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode92
Doc/tutorial/introduction.rst:92: If a variable is not "defined"
(assigned a value), trying to use it will
I really don't like the use of the word 'defined' here.  I'd prefer
something like "A name must be assigned an initial value before it can
be used.  Trying to use a name that hasn't been assigned a value will
give you an error:"

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode125
Doc/tutorial/introduction.rst:125: In addition to :class:`int` and
:class:`float`, Python supports other type of
types

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode126
Doc/tutorial/introduction.rst:126: numbers, like :class:`complex`,
:class:`~decimal.Decimal`, and
such as

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode137
Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the
same result.  ``\`` can be used to escape
I'm not sure "with the same result" is at all clear, here.  I think it
would be better to just say "They can be enclosed in either single
quotes (``'...''') or double quotes (``"..."``)" and then have the next
sentence read "``\`` can be used to escape a quote character in a string
that is surrounded by that same type of quote character::" which the
examples with then make concrete.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode141
Doc/tutorial/introduction.rst:141: 'spam eggs'
I don't think the comments add any value.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode153
Doc/tutorial/introduction.rst:153: By default, the interpreter encloses
the string output in quotes and escapes special characters with
backslashes.  The string is enclosed in
I would narrow this further, and say "At the command prompt, ...", or
"In the interactive interpreter" (shell?) since there really is no
"default".  I also would prefer to retain the sense of the 'in the same
way' phrase...perhaps "in a way that they could be typed at the input
prompt"?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode154
Doc/tutorial/introduction.rst:154: double quotes if the string contains
a single quote and no double quotes, else
I would rewrite this as "otherwise it is"

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode156
Doc/tutorial/introduction.rst:156: readable output, by removing the
enclosing quotes and by printing escaped and
I would say "omitting" rather than 'removing'.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode166
Doc/tutorial/introduction.rst:166: >>> print(s)  # with print(), the
newline is printed
Rather than "is printed", I would say "the newline produces a new line
in the output".

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode170
Doc/tutorial/introduction.rst:170: If you don't want to use special
characters, you can use *raw strings* by adding
"If you don't want characters prefaced by ``\`` to be interpreted as
special characters, you can use..."

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode179
Doc/tutorial/introduction.rst:179: String literals can span multiple
lines in several ways.  One way is using
You say "several ways" but then only discuss one of them.  Probably just
drop the "several ways"...although, see next note.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode180
Doc/tutorial/introduction.rst:180: triple-quotes: ``"""..."""`` or
``'''...'''``.  End of lines are automatically
"End of lines are automatically..." This is confusing without the
preceding example of escaping the ends of lines in a single quoted
string.  That section should be retained, IMO. Despite the fact that it
is not "best practice" to write code that way, pedagogically it explains
the concepts better.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode190
Doc/tutorial/introduction.rst:190: produces the following output (note
that the initial newline is not included):
I think the original exposition ("So the following example uses one
escape to avoid an unwanted initial blank line") is better than this
comment.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode208
Doc/tutorial/introduction.rst:208: >>> 'Py' 'thon'  # these string
literals are concatenated automatically
comment is redundant.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode211
Doc/tutorial/introduction.rst:211: This only works with two literals
though, not with variables::
"arbitrary string expressions" is more correct here than "variables".

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode213
Doc/tutorial/introduction.rst:213: >>> prefix = 'Py'
I think you should include an expression example as well, such as
showing that the multiplication example doesn't work with string
concatenation.  (But you should reverse it, 'un' *3 'ium')

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode252
Doc/tutorial/introduction.rst:252: Note that since -0 is really the same
as 0, negative indices start from -1.
Perhaps "mathematically" rather than "really"?  Or just drop "really". 
And I'd start the sentence with "Because ``-0`` is the same as ``0``..."

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode254
Doc/tutorial/introduction.rst:254: In addition to indexing, *slicing* is
also supported. As the name says,
Here again I prefer the original exposition, though we should drop the
reference to the Icon programming language.  I think most people will
know what a "substring" is, and if they don't the example will quickly
make it clear.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode262
Doc/tutorial/introduction.rst:262: Note how the start is always
included, and the end always excluded.  This
This is a good addition, though.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode280
Doc/tutorial/introduction.rst:280: One way to remember how slices work
is to think of the indices as pointing
On 2013/04/02 01:19:18, ezio.melotti wrote:
> While this is useful for slicing, it doesn't work too well for
indexing, where
> placing the index *below* (rather than *in between*) works better.
> Should I show both the examples?

I don't think so.  We are talking about slicing here. indexing is very
straightforward, so I don't think not mentioning it here will confuse
anyone.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode307
Doc/tutorial/introduction.rst:307: However these values are handled
gracefully when used for slicing::
I would write this "However, out of range slice indexes are handled
gracefully"

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode312
Doc/tutorial/introduction.rst:312: ''
You should include the -100 slice example here as well, as well as the
[2:1] example...which probably means you need to reintroduce the
sentence about what is actually done with the out of range indexes.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode326
Doc/tutorial/introduction.rst:326: If you need a different string, you
can always create a new one::
s/can always/should/

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode367
Doc/tutorial/introduction.rst:367: items of different types, but usually
the items all have the same type. ::
You are losing something here by omitting the example of items of
different type.  How about having both examples, and prefacing the
second one with, "Normally, however, lists elements will all be of the
same type"?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode384
Doc/tutorial/introduction.rst:384: means that the following slice
returns a new (shallow) copy of the list::
We probably ought to link this to "shallow copy" in the glossary...and
make an entry for it :)

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode387
Doc/tutorial/introduction.rst:387: [1, 2, 4, 9, 16, 25]
It would be nice to show what it means that this is a copy...which I
think means moving this bit down below the demonstration of the fact
that lists are mutable.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode411
Doc/tutorial/introduction.rst:411: 
[:] as copy could go here.

http://bugs.python.org/review/14097/

From rdmurray at bitdance.com  Wed May  8 14:23:56 2013
From: rdmurray at bitdance.com (rdmurray at bitdance.com)
Date: Wed, 08 May 2013 12:23:56 -0000
Subject: [docs] Improve the "introduction" page of the tutorial (issue
	14097)
Message-ID: <20130508122353.32685.61518@psf.upfronthosting.co.za>

On 2013/05/01 22:50:41, ezio.melotti wrote:
>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode110
> Doc/tutorial/introduction.rst:110: Complex numbers are also supported;
imaginary
> numbers are written with a suffix
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > The problem with completely omitting this is that the 'j' notation
is a
> special
> > feature of the syntax, unlike Decimal or Fraction, which are "just"
> specialized
> > classes.
> 
> This could go in a footnote.

Because it is part of the language syntax I think there should be at
least a one line mention in the main text.  It could then have a 'for
more information' link.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode551
> Doc/tutorial/introduction.rst:551: object!  We'll come back to *object
> semantics* later.
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > On 2013/04/02 01:19:18, ezio.melotti wrote:
> > > This is a fundamental concept, and this lighthearted introduction
only
> serves
> > to
> > > add more confusion IMHO.
> > > I removed the example for now, but this should be covered at a
later point.
> > 
> > I think maybe you could (should) cover it at an *earlier* point, in
the
> > discussion of [:] and what makes it a copy.
> 
> I think this should be presented in the second page, so that people
can first
> digest what they learned here.
> If we put this at the end of the page they might end up reading it
while their
> brain is still overheating from the amount of information they just
learned and
> risk to misunderstand it.

That seems fine, if you also move the [:] example to that page.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode76
> Doc/tutorial/introduction.rst:76: 
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I know this is early in the tutorial, but should divmod be mentioned
here?
> 
> Maybe in a footnote, functions haven't even be introduced yet, and
divmod() is
> not really common.

Probably even a footnote isn't appropriate.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode77
> Doc/tutorial/introduction.rst:77: With Python is also possible to use
the ``**``
> operator to calculate powers::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > "With Python it is also", but I'm not sure why "also"?  It doesn't
seem to be
> > related to the discussion of division.
> > 
> 
> Most of the other languages only provide the 4 basic operations, but
Python also
> provides **.

Without having created that context for 'also' in the text, I think it
would
be better to just drop it.

> > The other problem with introducing ** here is that any discussion of
** should
> > include a discussion of operator precedence and why -1**2 == -1.
> 
> That's too advanced/specific for now, I think it could be explained
somewhere
> else if necessary (or maybe in another footnote?).

A footnote would be fine.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode92
> Doc/tutorial/introduction.rst:92: If a variable is not "defined"
(assigned a
> value), trying to use it will
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I really don't like the use of the word 'defined' here.  I'd prefer
something
> > like "A name must be assigned an initial value before it can be
used.  Trying
> to
> > use a name that hasn't been assigned a value will give you an
error:"
> 
> That doesn't sound too well to me.

What about it doesn't sound good?  "defined" just feels *wrong* to me
for
Python.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode137
> Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the
same
> result.  ``\`` can be used to escape
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I'm not sure "with the same result" is at all clear, here.  I think
it would
> be
> > better to just say "They can be enclosed in either single quotes
(``'...''')
> or
> > double quotes (``"..."``)" and then have the next sentence read
"``\`` can be
> > used to escape a quote character in a string that is surrounded by
that same
> > type of quote character::" which the examples with then make
concrete.
> 
> "with the same result" is supposed to indicate that apart from the
(obvious)
> differences regarding the escaping of \' and \", they behave the same.
 In other
> languages there are differences between the two -- e.g. chars like \n
and \t and
> variable interpolation only work with one kind of quotes.

How about putting that note that other languages do make distinctions
in a footnote?  (Or as a separate sentence.)

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode141
> Doc/tutorial/introduction.rst:141: 'spam eggs'
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I don't think the comments add any value.
> 
> They are useful for people who read only the examples, and to link
part of the
> description with the examples.

OK.  I don't like them personally, but I can deal with that as personal
preference.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode153
> Doc/tutorial/introduction.rst:153: By default, the interpreter
encloses the
> string output in quotes and escapes special characters with
backslashes.  The
> string is enclosed in
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I would narrow this further, and say "At the command prompt, ...",
or "In the
> > interactive interpreter" (shell?) since there really is no
"default". 
> 
> s/By default/In the interactive interpreter/ SGTM.
> 
> > I also
> > would prefer to retain the sense of the 'in the same way'
phrase...perhaps "in
> a
> > way that they could be typed at the input prompt"?
> 
> "In the same way" is not totally accurate, because "s might end up
replaced with
> 's or the other way around.

That's why my suggested replacement uses the word "could" :)

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode180
> Doc/tutorial/introduction.rst:180: triple-quotes: ``"""..."""`` or
> ``'''...'''``.  End of lines are automatically
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > "End of lines are automatically..." This is confusing without the
preceding
> > example of escaping the ends of lines in a single quoted string.
> 
> This is presented in the next example though.
> The idea is that first I introduce """...""" and \ and explain what
they do,
> then I show an example and its output, pointing out what """...""" and
\ did
> there.

Right, and I'm saying that I don't think that exposition works as well.

> >  That section
> > should be retained, IMO. Despite the fact that it is not "best
practice" to
> > write code that way, pedagogically it explains the concepts better.
> 
> The problem with that is that if people see it, it's likely they are
going to
> copy it and use it in their code.
> Even if \ actually works even outside strings, the examples shows one
of the
> very few places where it's ok using it (IMHO).

The text linking the two examples can say that the second one is the
better
way to do it.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode211
> Doc/tutorial/introduction.rst:211: This only works with two literals
though, not
> with variables::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > "arbitrary string expressions" is more correct here than
"variables".
> 
> It's more correct but less clear.  "variables or expressions" might be
OK
> though.

That sounds fine.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode213
> Doc/tutorial/introduction.rst:213: >>> prefix = 'Py'
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I think you should include an expression example as well, such as
showing that
> > the multiplication example doesn't work with string concatenation. 
(But you
> > should reverse it, 'un' *3 'ium')
> 
> I preferred to show only one example, because each "failing" example
takes 5
> more line, and having two tracebacks one after the other might be
confusing.

You could use the '...' notation and only show the SyntaxError.  That
should
be typographically clear even to a beginner.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode367
> Doc/tutorial/introduction.rst:367: items of different types, but
usually the
> items all have the same type. ::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > You are losing something here by omitting the example of items of
different
> > type.  How about having both examples, and prefacing the second one
with,
> > "Normally, however, lists elements will all be of the same type"?
> 
> I think it's not necessary, and it's better to keep the tutorial
short.

Well, I still think you are losing something valuable, but I won't block
on it
:)

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode384
> Doc/tutorial/introduction.rst:384: means that the following slice
returns a new
> (shallow) copy of the list::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > We probably ought to link this to "shallow copy" in the
glossary...and make an
> > entry for it :)
> 
> OK (was there an issue for this?)

I don't think so.


http://bugs.python.org/review/14097/

From pgacv2 at gmail.com  Wed May  8 22:18:52 2013
From: pgacv2 at gmail.com (Pedro G. Acevedo)
Date: Wed, 08 May 2013 20:18:52 -0000
Subject: [docs] Possible documentation bug
Message-ID: <CAKn5Yw55pGZg+Wg_LcRQbE0r+q+Ob6zoApyfR7e0OMveB7k91g@mail.gmail.com>

Hello,

I'm not sure if this is a bug per se, but it can throw you off so I would
think it's at least counter-intuitive. On IE 8 (have not tested on other
browsers), the Python version in the drop-down at the top of a
documentation page does not match the version in the URL, which is the real
version that I'm browsing. This happens if you have used the drop-down to
switch versions.

To reproduce:
1. Go to http://docs.python.org/3/library/index.html
2. Use the drop-down at the top of the page to switch to version 2.6.
3. See that the URL now reads 2.6, but the drop-down continues to display
3.4. This could make you think that you're browsing the 3.4 documentation
when in reality you aren't.

The string "(3.4)" is found nowhere in the page's source code so I assume
it's being generated by an imported Javascript file. If this is a regular
<select> element, then I assume the correct version could be displayed by
adding the "selected" attribute to the <option> element of whichever
version is currently being browsed.

Cheers.

Pedro G. Acevedo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130508/07df3b84/attachment-0001.html>

From zachary.ware at gmail.com  Fri May 10 22:43:10 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Fri, 10 May 2013 20:43:10 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130510204310.28617.80446@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8110/Lib/test/test_enum.py#newcode64
Lib/test/test_enum.py:64: self.assertFalse(_errors)
This is better, but now any exceptions that are raised are masked.  How
about instead of assertFalse, do (untested):
"""
for e in _errors:
    with self.subTest():
        raise e
"""

This is also going to cause a lot of NameErrors in the tests that use
these Enums, so it would be nice to set dummy values in the except
clauses and skip the tests that don't have the necessary Enum available.

On the other hand, I still think it would be just a whole lot simpler to
lose the try/excepts.  If actually creating the Enum is broken, I'd be
more concerned with getting that fixed than running the tests that can
be run on non-broken Enums.

http://bugs.python.org/review/17947/

From zachary.ware at gmail.com  Sat May 11 06:42:08 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Sat, 11 May 2013 04:42:08 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130511044207.28616.14081@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py#newcode9
Lib/test/test_enum.py:9: _errors = []
No longer needed.

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py#newcode16
Lib/test/test_enum.py:16: Stooges = exc
Not quite what I had in mind, but it does seem to work.  But may I ask
what your justification for keeping all the try/excepts and now the
extra type checking in the tests is?  If you've got a good reason, this
method works for me; I just think it could all be a whole lot simpler.

http://bugs.python.org/review/17947/diff/8113/Lib/test/test_enum.py#newcode64
Lib/test/test_enum.py:64: self.assertFalse(_errors)
This test is now useless, it can go.

http://bugs.python.org/review/17947/

From ncoghlan at gmail.com  Sun May 12 15:28:03 2013
From: ncoghlan at gmail.com (ncoghlan at gmail.com)
Date: Sun, 12 May 2013 13:28:03 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130512132802.9130.75600@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8113/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8113/Lib/enum.py#newcode214
Lib/enum.py:214: return cls._enum_map.copy()
This kind of use case is exactly why types.MappingProxyType was made
visible at the Python layer (it's the impl of the read-only mappings
used for class dictionaries, and we use them there for a similar reason:
modifying the class contents without going through the class machinery
simply isn't something we want to allow).

So, rather than copying, I suggest returning
types.MappingProxyType(cls._enum_map)

http://docs.python.org/3/library/types#types.MappingProxyType

http://bugs.python.org/review/17947/

From zachary.ware at gmail.com  Mon May 13 19:06:12 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Mon, 13 May 2013 17:06:12 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513170612.1275.64092@psf.upfronthosting.co.za>

Being mostly satisfied with the state of the test module, I've started
attacking your style ;).  A lot of things I've pointed out here are just
nitpicks, but some are more important (like adding whitespace to
EnumMeta.__new__; it really is intimidating to read as is).


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode1
Lib/enum.py:1: """\
It's ok to lose the backslash here, but start the text on line 2.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode8
Lib/enum.py:8: from types import MappingProxyType
It looks better to order by 'import ...', then 'from ... import ...'
rather than intermixing.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode14
Lib/enum.py:14: """ Returns the value in the instance, raises
AtttributeError on the class.
Missed a space before Returns.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode49
Lib/enum.py:49: """ Changes anything not dundered or that doesn't have
__get__.
Missed another space.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode85
Lib/enum.py:85: def __new__(metacls, cls, bases, classdict):
This method really just looks like a giant wall of code to me, not very
readable.  PEP 8 suggests "[Using] blank lines in functions, sparingly,
to indicate logical sections", which I would take to mean roughly before
and/or after each top-level (within the method) for or if statement,
thereabouts.  Or, in this case, before each comment block would seem
appropriate.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode92
Lib/enum.py:92: metacls._find_new(classdict, obj_type, first_enum)
PEP 8 recommends avoiding backslashes for line continuation; it would be
better to split the line in the _find_new call, I think.

"""
        __new__, save_new, use_args = metacls._findnew(classdict,
                                                       obj_type,
                                                       first_enum)
"""

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode224
Lib/enum.py:224: def _create(cls, class_name, names=None, *,
module=None, type=None):
This one could also do with a touch of whitespace to make it more
readable.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode258
Lib/enum.py:258: def _get_mixins(bases):
Whitespace wouldn't be amiss.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode300
Lib/enum.py:300: def _find_new(classdict, obj_type, first_enum):
Another whitespace request.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode341
Lib/enum.py:341: """valueless, unordered enumeration class"""
Capitalize "Valueless"

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode5
Lib/test/test_enum.py:5: import sys
Same comment here as on the enum.py imports.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode100
Lib/test/test_enum.py:100: '<Season.{0}: {1}>'.format(season, i))
PEP 8 violation; this line should either move over to match repr(e), or
repr(e) should move to the next line.

(Nitpicking, ahoy!)

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode161
Lib/test/test_enum.py:161: if v.name != k], ['FALL', 'ANOTHER_SPRING'])
This could be broken into separate lines better; the listcomp could
start on the second line, and the list could be on a third line. 
Breaking the listcomp into two lines confused me for a bit when I saw
it.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode192
Lib/test/test_enum.py:192: THURSDAY FRIDAY SATURDAY'''.split(), 1):
I think this might be made more readable by creating a list from the
"SUNDAY MONDAY..." string before the loop statement and passing it in to
enumerate.

http://bugs.python.org/review/17947/diff/8131/Lib/test/test_enum.py#newcode285
Lib/test/test_enum.py:285: self.assertEqual([SummerMonth.june,
SummerMonth.july, SummerMonth.august], lst)
Line too long, there's a few cases of this here and below.

http://bugs.python.org/review/17947/

From mm at ensoft.co.uk  Mon May 13 19:25:50 2013
From: mm at ensoft.co.uk (mm at ensoft.co.uk)
Date: Mon, 13 May 2013 17:25:50 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513172549.9130.27323@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode14
Lib/enum.py:14: """ Returns the value in the instance, raises
AtttributeError on the class.
(minor) typo in "AtttributeError"

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode56
Lib/enum.py:56: error is raised.
This sentence is not true (though it might be nicer if it was! i.e.
sometimes it might be easier when using the Functional API to just leave
duplicates in than round trip via an "OrderedSet").

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
Shouldn't this technically be a use of super()? Not that I guess complex
type hierarchies of Metaclasses are common.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode114
Lib/enum.py:114: if not isinstance(value, tuple):
Doesn't this produce weird behaviour for the following definition:

class MyEnum(Enum):
    FOO = 7
    BAR = (42, 8)
    BAZ = "hello"

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode123
Lib/enum.py:123: enum_item = __new__(enum_class, *args)
Is it explicitly forbidden to have multi type enums (i.e. ones where
different items have different values)? This code assumes that the
__new__ from the first type can cope with the args from the latter ones.
I believe the __new__ needs to be re-calculated on each enum item in
order to correctly cope.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode323
Lib/enum.py:323: Enum.__new__):
This should be a set literal, not a tuple.

http://bugs.python.org/review/17947/

From mm at ensoft.co.uk  Tue May 14 00:01:07 2013
From: mm at ensoft.co.uk (mm at ensoft.co.uk)
Date: Mon, 13 May 2013 22:01:07 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513220106.9129.75834@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/13 20:32:37, stoneleaf wrote:
> On 2013/05/13 19:25:49, isoschiz wrote:
> > Shouldn't this technically be a use of super()? Not that I guess
complex type
> > hierarchies of Metaclasses are common.
> 
> __new__ is one of the few things (the only thing?) that cannot be
shared -- you
> can only create an object once.

And yet in this instance you are deferring to your superclass' __new__.
If someone mixes in an extension type with a custom __new__ as well as
Enum, then this will break. Using super() will make that possible.

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode114
Lib/enum.py:114: if not isinstance(value, tuple):
On 2013/05/13 20:32:37, stoneleaf wrote:
> On 2013/05/13 19:25:49, isoschiz wrote:
> > Doesn't this produce weird behaviour for the following definition:
> > 
> > class MyEnum(Enum):
> >     FOO = 7
> >     BAR = (42, 8)
> >     BAZ = "hello"
> 
> Did you try it?
> """
> --> class MyEnum(Enum): FOO = 7; BAR = (42, 8); BAZ = "hello"
> ... 
> --> MyEnum
> <enum 'MyEnum'>
> --> list(MyEnum)
> [<MyEnum.FOO: 7>, <MyEnum.BAR: (42, 8)>, <MyEnum.BAZ: 'hello'>]
> --> MyEnum.BAR
> <MyEnum.BAR: (42, 8)>
> --> MyEnum.BAR.value == (42, 8)
> True
> """
> 
> Looks good to me. ;)

I must confess I didn't try it - apologies. :-)

Although as a corollary, the code is dense enough that I can't work out
in a straightforward way why this works! Perhaps some more comments
would help?

http://bugs.python.org/review/17947/

From mm at ensoft.co.uk  Tue May 14 01:29:57 2013
From: mm at ensoft.co.uk (mm at ensoft.co.uk)
Date: Mon, 13 May 2013 23:29:57 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130513232956.9129.95191@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 00:09:15, stoneleaf wrote:
> On 2013/05/14 00:01:06, isoschiz wrote:
> > On 2013/05/13 20:32:37, stoneleaf wrote:
> > > On 2013/05/13 19:25:49, isoschiz wrote:
> > > > Shouldn't this technically be a use of super()? Not that I guess
complex
> > type
> > > > hierarchies of Metaclasses are common.
> > > 
> > > __new__ is one of the few things (the only thing?) that cannot be
shared --
> > you
> > > can only create an object once.
> > 
> > And yet in this instance you are deferring to your superclass'
__new__. If
> > someone mixes in an extension type with a custom __new__ as well as
Enum, then
> > this will break. Using super() will make that possible.
> 
> I don't understand.  Can you provide an example?

It requires writing an extension type (i.e. a type defined in C in an
extension module), which will have its own __new__ - let's call this
type ext.Parent

class MyEnumMeta(Enum, ext.Parent): pass

will now not do what is expected. Even though in the mro ext.Parent
comes before type, the __new__ in Enum delegates directly to type,
bypassing ext.Parent. Using super() here produces the desired behaviour.

In either case, your statement about __new__ only being able to be
called once is true. The question though is which __new__ actually gets
to do the work. We shouldn't presuppose that type.__new__ is what the
user needs.

(I must confess I've not tried this with "type", but it definitely fails
when deferring to "object.__new__" instead of the extension class'
__new__)

http://bugs.python.org/review/17947/

From quentin at box.com  Tue May 14 18:58:04 2013
From: quentin at box.com (Quentin de Metz)
Date: Tue, 14 May 2013 16:58:04 -0000
Subject: [docs] Python 2.7 Profile module documentation
In-Reply-To: <CAPQdHqupBoZ1aRQYECinTyoezL-UXtn93dWbVkjiEe1S5R+TRQ@mail.gmail.com>
References: <CAPQdHqupBoZ1aRQYECinTyoezL-UXtn93dWbVkjiEe1S5R+TRQ@mail.gmail.com>
Message-ID: <CAPQdHqvUKudRVV=C3MBmPE3d+Bu98gz3S8W+a0GQOX7yae1MPA@mail.gmail.com>

Hello again,

I have not received any sign of life since I suggested this modification.
What is your current status?

Is this the right place to ask?

Thanks,

Quentin




On Fri, Apr 19, 2013 at 3:59 PM, Quentin de Metz <quentin at box.com> wrote:

> Hello to the Python documentation team,
>
> I work in a software company in the Silicon Valley and we are using Python
> (2.7) for one of our upcoming releases.
>
> I'm working on performance testing for this software and have been
> fiddling quite a bit with the profiling modules available. I believe there
> is a lack of information in the official documentation and would like to
> report it.
>
> I've been trying to profile our software to see where CPU bottlenecks are.
> Despite reports of being able to use cProfile to measure CPU time, all of
> the documentation I found on the internet seems to portray cProfile
> measuring "wall time" - that is, time elapsed during a function, regardless
> of actual CPU usage. (Have a look at the UNIX "time" command if you don't
> know what I'm talking about.)
>
> For example, take the following snippet:
>
> import cProfile
> import time
>
> def sleep():
>     time.sleep(2)
>
> def count():
>     for i in xrange(100000000):
>         pass
>
> def test():
>     sleep()
>     count()
>
> *profiler = cProfile.Profile()*
> profiler.run('test()')
> profiler.print_stats
>
> Let's take a look at the functions defined here.
> Obviously the sleep function uses no CPU time, however the count function
> should generate some CPU usage.
>
> The output I get from this script is the following:
>
>    ncalls  tottime  percall  cumtime  percall filename:lineno(function)
>         1    2.045    2.045    2.045    2.045 <stdin>:1(count)
>         1    0.000    0.000    2.001    2.001 <stdin>:1(sleep)
> *        1    0.000    0.000    4.046    4.046 <stdin>:1(test)*
>         1    0.000    0.000    4.046    4.046 <string>:1(<module>)
>         1    0.000    0.000    0.000    0.000 {method 'disable' of
> '_lsprof.Profiler' objects}
>         1    2.001    2.001    2.001    2.001 {time.sleep}
>
> And reading the *line* corresponding to the "test" function does not show
> the results I expect (I expect approx 2.045).
> Once again I have scoured the Internet and found no clues as to how to
> leverage cProfile to measure only CPU time.
>
> I wrote to Mike Mueller from Python Academy who was able to provide me
> with some useful information on how to obtain what I was looking for.
>
> *On a UNIX system,* writing
> profiler = cProfile.Profile(time.clock)
> achieves the desired effet:
>
>    ncalls  tottime  percall  cumtime  percall filename:lineno(function)
>         1    1.988    1.988    1.988    1.988 <stdin>:1(count)
>         1    0.000    0.000    0.000    0.000 <stdin>:1(sleep)
> *        1    0.000    0.000    1.989    1.989 <stdin>:1(test)*
>         1    0.000    0.000    1.989    1.989 <string>:1(<module>)
>         1    0.000    0.000    0.000    0.000 {method 'disable' of
> '_lsprof.Profiler' objects}
>         1    0.000    0.000    0.000    0.000 {time.sleep}
>
>
> *On Windows*, one must first define:
> def win_clock():     return os.times()[0]
> and write
> profiler = cProfile.Profile(win_clock)
>
> which also achieves the desired effect:
> ncalls  tottime  percall  cumtime  percall filename:lineno(function)
>     1    1.404    1.404    1.404    1.404 <stdin>:1(count)
>     1    0.000    0.000    0.000    0.000 <stdin>:1(sleep)
> *    1    0.000    0.000    1.404    1.404 <stdin>:1(test)*
>     1    0.000    0.000    1.404    1.404 <string>:1(<module>)
>     1    0.000    0.000    0.000    0.000 {method 'disable' of
> '_lsprof.Profiler' objects}
>     1    0.000    0.000    0.000    0.000 {time.sleep}
>
>
> I sincerely believe some of this information belongs in the official
> Python documentation. Without Mike Mueller I think I would never have found
> it. I hope my description has been thorough and that you will have
> sufficient information to complete the existing documentation which has
> never disappointed me.
>
> Thank you very much for your consideration,
> Hoping to hear from you soon,
>
> Quentin de Metz
> Box, Inc
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130514/712d9c00/attachment-0001.html>

From mm at ensoft.co.uk  Tue May 14 20:12:45 2013
From: mm at ensoft.co.uk (mm at ensoft.co.uk)
Date: Tue, 14 May 2013 18:12:45 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130514181243.1275.16610@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 01:41:45, stoneleaf wrote:
> On 2013/05/14 01:29:56, isoschiz wrote:
> > On 2013/05/14 00:09:15, stoneleaf wrote:
> > > On 2013/05/14 00:01:06, isoschiz wrote:
> > > > On 2013/05/13 20:32:37, stoneleaf wrote:
> > > > > On 2013/05/13 19:25:49, isoschiz wrote:
> > > > > > Shouldn't this technically be a use of super()? Not that I
guess
> complex
> > > > type
> > > > > > hierarchies of Metaclasses are common.
> > > > > 
> > > > > __new__ is one of the few things (the only thing?) that cannot
be shared
> > --
> > > > you
> > > > > can only create an object once.
> > > > 
> > > > And yet in this instance you are deferring to your superclass'
__new__. If
> > > > someone mixes in an extension type with a custom __new__ as well
as Enum,
> > then
> > > > this will break. Using super() will make that possible.
> > > 
> > > I don't understand.  Can you provide an example?
> > 
> > It requires writing an extension type (i.e. a type defined in C in
an
> extension
> > module), which will have its own __new__ - let's call this type
ext.Parent
> > 
> > class MyEnumMeta(Enum, ext.Parent): pass
> > 
> > will now not do what is expected. Even though in the mro ext.Parent
comes
> before
> > type, the __new__ in Enum delegates directly to type, bypassing
ext.Parent.
> > Using super() here produces the desired behaviour.
> > 
> > In either case, your statement about __new__ only being able to be
called once
> > is true. The question though is which __new__ actually gets to do
the work. We
> > shouldn't presuppose that type.__new__ is what the user needs.
> > 
> > (I must confess I've not tried this with "type", but it definitely
fails when
> > deferring to "object.__new__" instead of the extension class'
__new__)
> 
> I think you are confusing the metaclass __new__ with the class
__new__.  There
> is already support to find (right above this code, actually) the
correct __new__
> to use to create the class instances (aka members):  first it looks in
the Enum
> hierarchy for a custom __new__, then it looks in the mixed-in type
(ext.Parent
> in your case) for a __new__ to use.  If there is no custom __new__ and
no other
> type was mixed in, object.__new__ gets used.
> 
> Or maybe you made a typo, and meant `class MyEnumMeta(EnumMeta,
ext.Parent)`; I
> have no experience with extension classes so I'm not sure what happens
metaclass
> wise when one is mixed with a native python type.
> 
> Decimal now has a C version, doesn't it?  I'll a test with that and
see what
> happens.

Sorry - I did typo: I meant MyEnumMeta, as you indicated.

The Decimal implementation may indeed exhibit the problem. However, I
think it can easily be solved by just replacing type with super() in
that line. It will work identically in all of the simple cases, but
should also work should anyone want to do anything "weird".

Also note that this can also apply if the __new__ methods are doing some
extra work (either before or after the actual allocation), exactly like
this function. So even if ext.Parent wasn't an extension class, it might
want it's __new__ called so it could, say, add a new property into the
classdict or similar.

http://bugs.python.org/review/17947/

From mm at ensoft.co.uk  Tue May 14 20:40:10 2013
From: mm at ensoft.co.uk (mm at ensoft.co.uk)
Date: Tue, 14 May 2013 18:40:10 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130514184009.31536.50211@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode103
Lib/enum.py:103: enum_class = type.__new__(metacls, cls, bases,
classdict)
On 2013/05/14 20:18:48, stoneleaf wrote:
> On 2013/05/14 20:12:43, isoschiz wrote:
> > 
> > Sorry - I did typo: I meant MyEnumMeta, as you indicated.
> > 
> > The Decimal implementation may indeed exhibit the problem. However,
I think it
> > can easily be solved by just replacing type with super() in that
line. It will
> > work identically in all of the simple cases, but should also work
should
> anyone
> > want to do anything "weird".
> > 
> > Also note that this can also apply if the __new__ methods are doing
some extra
> > work (either before or after the actual allocation), exactly like
this
> function.
> > So even if ext.Parent wasn't an extension class, it might want it's
__new__
> > called so it could, say, add a new property into the classdict or
similar.
> 
> One of us is confused -- and I don't know which of us it is! ;)
> 
> I'll try it both ways with cDecimal as soon as I get a chance, but as
far as
> cooperitive _new__'s how would that work?  If A calls B's __new__,
which creates
> an object, and B calls C's __new__ which creates an object, which one
am I
> getting back? If we reverse that, and B and C call the next __new__
before
> creating an object, won't we eventually hit type, and definitely not
have the
> correct object?

Because in all cases we pass metacls up as the first argument, the
ultimate object created *will* be of the right type (that is, an
extension class' __new__ knows also how to allocated subtypes, and this
applies equally to type's __new__).

Here is an example using object, but the same applies if everything
subclassed from type (i.e. was a metaclass).

>>> class Foo:
...     def __new__(cls, *args, **kwargs):
...             o = super().__new__(cls, *args, **kwargs)
...             o.been_fooed = True
...             return o
... 
>>> class Bar:
...     def __new__(cls, *args, **kwargs):
...             o = super().__new__(cls, *args, **kwargs)
...             o.been_barred = True
...             return o
... 
>>> class Baz:
...     def __new__(cls, *args, **kwargs):
...             o = object.__new__(cls, *args, **kwargs)
...             o.been_bazzed = True
...             return o
... 
>>> class Quux(Foo, Bar): pass
... 
>>> q = Quux()
>>> q.been_fooed
True
>>> q.been_barred
True
>>> class Quux(Foo, Baz): pass
... 
>>> q = Quux()
>>> q.been_fooed
True
>>> q.been_bazzed
True
>>> class Quux(Baz, Foo): pass
... 
>>> q = Quux()
>>> q.been_bazzed
True
>>> q.been_fooed
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'Quux' object has no attribute 'been_fooed'

It is clearly not desirable to not let Foo have a go, just because Baz
got in the way. Without super() in this line of EnumMeta, you have the
same possibility of breaking some folks using the metaclass, if EnumMeta
is passed as the first base.

http://bugs.python.org/review/17947/

From zachary.ware at gmail.com  Fri May 17 15:37:11 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Fri, 17 May 2013 13:37:11 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130517133711.15970.77941@psf.upfronthosting.co.za>

Here's the latest nitpicks from me :)


http://bugs.python.org/review/17947/diff/8131/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8131/Lib/enum.py#newcode92
Lib/enum.py:92: metacls._find_new(classdict, obj_type, first_enum)
On 2013/05/13 20:32:37, stoneleaf wrote:
> On 2013/05/13 19:06:12, zach.ware wrote:
> > PEP 8 recommends avoiding backslashes for line continuation; it
would be
> better
> > to split the line in the _find_new call, I think.
> > 
> > """
> >         __new__, save_new, use_args = metacls._findnew(classdict,
> >                                                        obj_type,
> >                                                        first_enum)
> > """
> 
> How about:
> 
> """
>         __new__, save_new, use_args = (
>                 metacls._find_new(classdict, obj_type, first_enum)
>                 )
> """
> 
> ?

That's not my preference, but I suppose it's better than the backslash.

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode7
Lib/enum.py:7: import weakref
As pointed out by Donald Stufft on the issue, weakref is unused.

(Just to have a comment on it :))

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode37
Lib/enum.py:37: def dunder(name):
Might be better named "is_dunder" since you're asking if it is, not
making it so.

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode52
Lib/enum.py:52: raise TypeError('%r cannot be pickled' % self)
These two functions should be made private unless there's good reason
for them to be public.  Hard to change later if they're public (even if
they're left out of __all__).

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode123
Lib/enum.py:123: "'_find_new' cannot be used for members")
I wonder if it would be better to explicitly disallow any _name?  Or, I
think I read somewhere (possibly in the enum discussions, though I don't
remember for sure :)) that the implementer of namedtuple later wished
they had used names_ instead of _names and reserved that whole
namespace_; perhaps that would be a good idea here.

http://bugs.python.org/review/17947/diff/8161/Lib/test/test_enum.py
File Lib/test/test_enum.py (right):

http://bugs.python.org/review/17947/diff/8161/Lib/test/test_enum.py#newcode2
Lib/test/test_enum.py:2: import sys
Turns out sys isn't used here, either.

http://bugs.python.org/review/17947/

From zachary.ware at gmail.com  Fri May 17 18:01:40 2013
From: zachary.ware at gmail.com (zachary.ware at gmail.com)
Date: Fri, 17 May 2013 16:01:40 -0000
Subject: [docs] Code, test,
	and doc review for PEP-0435 Enum (issue 17947)
Message-ID: <20130517160139.15970.20296@psf.upfronthosting.co.za>


http://bugs.python.org/review/17947/diff/8161/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8161/Lib/enum.py#newcode123
Lib/enum.py:123: "'_find_new' cannot be used for members")
On 2013/05/17 17:40:14, stoneleaf wrote:
> I'd rather not -- seems like it would be easy to miss a trailing
underscore. 
> Also, in the tuple case the _as_dict method is actually public --
these aren't.
> 
> If we're going to reserve an entire namespace, how about '_somename_'
?

That would be fine with me, I'm not aware of any existing conventions
with _names_ and they seem unlikely to be used for enum names.  But
then, _names don't seem terribly likely for that purpose either.

My main purpose to a change here is just to make it easy to
extend/change things later by not limiting ourselves to those 4 names,
I'm not too bothered by which names are reserved :).

http://bugs.python.org/review/17947/

From naroom at gmail.com  Tue May 21 20:14:36 2013
From: naroom at gmail.com (Theo Walker)
Date: Tue, 21 May 2013 18:14:36 -0000
Subject: [docs] Bug: multiprocessing documentation
Message-ID: <CAAFD466JfteTXpm717GOSNMVDk0kZ_TG=+u5Ps2V+cnO5wgO5g@mail.gmail.com>

http://docs.python.org/2/library/multiprocessing.html

Section:
16.6.1.3. Synchronization between processes

Sample code doesn't work, as processes may exit before releasing the lock.
Adding a join() on each process fixes the problem. Corrected code below:

from multiprocessing import Process, Lock


def f(l, i):

#single process executes the block at a time

l.acquire()

print 'hello world', i

l.release()


if __name__ == '__main__':

lock = Lock()


 #spawn 10 processes, each with an arg that says their index

for num in range(10):

p = Process(target=f, args=(lock, num))

p.start()

p.join()


Thanks for maintaining the doc, for the betterment of all mankind!

--Theo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130521/bce0b8c0/attachment-0001.html>

From shane.cousins at gmail.com  Wed May 22 06:11:18 2013
From: shane.cousins at gmail.com (Shane Cousins)
Date: Wed, 22 May 2013 04:11:18 -0000
Subject: [docs] clarity in unicode howto
Message-ID: <CAMZmp-bW0T3tChAqev5uB=Ak87gT32iEok0ehYiYR01KCzRVEw@mail.gmail.com>

I'm coming from python 2 and just peeking into the python 3 docs.
I thought I had a pretty good grasp of how text encoding is handled, but in
reading
http://docs.python.org/3.3/howto/unicode.html#reading-and-writing-unicode-dataI
was a little confused.

It shows in the example:

Reading Unicode from a file is therefore simple:

with open('unicode.rst', encoding='utf-8') as f:
    for line in f:
        print(repr(line))


My understanding here is that "unicode.rst" is a utf-8 encoded file and
open() will be performing decode of utf-8 to unicode on read(), where line
here is in *unicode*.

If this is the case, there are two minor improvements that would help
dispel confusion for me in this example:

1. change the filename to something like, "utf8.txt"
--> Yes ".rst" is understood by most python programmers to be text, but for
new users not yet accustomed to python, ".txt" is more clear
2. add the mode, "r" to open().

So the example would then be:

with open('utf8.txt', mode='r', encoding='utf-8') as f:
    for line in f:
        print(repr(line))

If I'm mistaken, please ignore this mail.

Best Regards,

Shane


Also, while I understand that "for line in f" will iterate over the file
object returning lines, it may be clearer to new python programmers if "for
line in f.readlines()" is used.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130522/2e9064b2/attachment-0001.html>

From pkzweber at gmail.com  Mon May 27 23:13:18 2013
From: pkzweber at gmail.com (Peter Zweber)
Date: Mon, 27 May 2013 21:13:18 -0000
Subject: [docs] Bug in nested list documentation example
Message-ID: <CAGz7YWHGU_H8yqveL_1S6B_ZbAAy9yDZOwokcjjezMrNxWJzDQ@mail.gmail.com>

In Section 3.1.3 of http://docs.python.org/3.3/tutorial/introduction.html,
the nested list example has two bugs.  It uses p[0] and p[0][1].  The
variable p is not defined in this example.  It should be x[0] and x[0][1].

Sincerely,
Peter Zweber
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130527/9f07576b/attachment-0001.html>

From odraencoded at gmail.com  Tue May 28 22:36:18 2013
From: odraencoded at gmail.com (Leonardo Pereira)
Date: Tue, 28 May 2013 20:36:18 -0000
Subject: [docs] Tutorial bug
Message-ID: <CA+ks6EcsB3A3+DHXh6Fnd0RG8dNiSgj1Ubx0GSJ03iY6sJxvFw@mail.gmail.com>

http://docs.python.org/3.3/tutorial/datastructures.html does not list
.clear() and .copy() methods introduced in 3.3
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130528/687a521b/attachment-0001.html>

From ryan.w.landon at jpmorgan.com  Thu May 30 00:07:44 2013
From: ryan.w.landon at jpmorgan.com (Landon, Ryan W)
Date: Wed, 29 May 2013 22:07:44 -0000
Subject: [docs] Bug Found
Message-ID: <C2586E5D2BF8984B81CDBFA87551E80AA81CC6@SEGCMX052.exchad.jpmchase.net>

I was looking through your site when a non fatal java script error occurred. I figured I would let you know.

Site I was viewing: http://docs.python.org/2/tutorial/errors.html

Bug Screenshot:
[cid:image001.png at 01CE5C82.E8C547B0]




This email is confidential and subject to important disclaimers and
conditions including on offers for the purchase or sale of
securities, accuracy and completeness of information, viruses,
confidentiality, legal privilege, and legal entity disclaimers,
available at http://www.jpmorgan.com/pages/disclosures/email.  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130529/3128ce5d/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 35970 bytes
Desc: image001.png
URL: <http://mail.python.org/pipermail/docs/attachments/20130529/3128ce5d/attachment-0001.png>

From eddy at chaos.org.uk  Thu May  9 22:21:52 2013
From: eddy at chaos.org.uk (Edward Welbourne)
Date: Thu, 09 May 2013 20:21:52 -0000
Subject: [docs] I suspect a reversal
Message-ID: <E1UaWu7-0005Om-OO@utter.chaos.org.uk>

Hi doc-team,

On
http://docs.python.org/3/library/codecs.html
under codecs.register, I see the description: <quote>

streamreader and streamwriter: These have to be factory functions
providing the following interface:

  factory(stream, errors='strict')

The factory functions must return objects providing the interfaces
defined by the base classes StreamWriter and StreamReader, respectively.

</quote> and am instantly suspicious: apparently, streamreader should
have the interface of StreamWriter and streamwrite that of StreamReader.
This is either a doc bug or a horribly bad choice of names for the
.register() function's parameters !

	Eddy.

From ulf.renman at gmail.com  Thu May  2 21:39:00 2013
From: ulf.renman at gmail.com (Ulf Renman)
Date: Thu, 02 May 2013 19:39:00 -0000
Subject: [docs] Minor bug in ArgumentParser doc?
Message-ID: <CALtvpowCz_R3-XL-ckmwPjkBt6MAdN0Qi0XVLeZFbMSr-0Y5+A@mail.gmail.com>

Hi

In section 15.4.2.11 http://docs.python.org/2/library/argparse.html#add-help

The last sentance reads "In this case, the first character in prefix_chars
is used to prefix the help options:", but that is not what the example code
following it shows.

I have not tried this code myself, but there is clearly selfcontradiction
in the documentation here.

/Ulf Renman
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130502/12e58fe5/attachment-0001.html>

From terencelz90 at gmail.com  Wed May 15 03:55:42 2013
From: terencelz90 at gmail.com (Terence Lewis)
Date: Wed, 15 May 2013 01:55:42 -0000
Subject: [docs] Small mistake in documentation
Message-ID: <CAE_bDQnyA_OEjFXBwfyz56a=XELVhwFBr=mSnRtCLwKdEah4-w@mail.gmail.com>

Hi,

I was reading through the tutorial of Argparse module and found a small
mistake.

http://docs.python.org/2/howto/argparse.html#getting-a-little-more-advanced

Notice that so far we?ve been using verbosity level to *change* the text
that gets displayed. The following example instead uses verbosity level to
display *more* text instead:

import argparseparser =
argparse.ArgumentParser()parser.add_argument("x", type=int, help="the
base")parser.add_argument("y", type=int, help="the
exponent")parser.add_argument("-v", "--verbosity", action="count",
default=0)args = parser.parse_args()answer = args.x**args.yif
args.verbosity >= 2:
    print "Running '{}'".format(__file__)if args.verbosity >= 1:
    print "{}^{} ==".format(args.x, args.y),print answer

The second last line should be


    print "{}^{} == {}".format(args.x, args.y, answer)

as stated in other similar paragraphs.

Terence
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130515/33ad9291/attachment.html>

From wtq1990 at gmail.com  Wed May 15 18:33:32 2013
From: wtq1990 at gmail.com (Tanky Woo)
Date: Wed, 15 May 2013 16:33:32 -0000
Subject: [docs] [BUG]About `add_mutually_exclusive_group' in argparse module
	doc
Message-ID: <5193B8D1.8050106@gmail.com>

Today, I read the argparse doc and find the Mutual exclusion
section(http://docs.python.org/2/library/argparse.html#mutual-exclusion)
has a problem


The function `*add_mutually_exclusive_group*' in the section is :

*argparse.add_mutually_exclusive_group(required=False)*

but add_mutually_exclusive_group belongs to *ArgumentParser* object, not
direct to *argparse*, maybe this is a bug?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130515/0c91cd89/attachment.html>

From wbjaymale at gmail.com  Sun May 26 21:45:08 2013
From: wbjaymale at gmail.com (Jay Mail)
Date: Sun, 26 May 2013 19:45:08 -0000
Subject: [docs] Tutorial: Lists - Errors and Question
Message-ID: <CAESX_p-MOtD=YZCwPsGX7JnyuLca4g6nHiJeKng-d_Xagj8bVQ@mail.gmail.com>

Hello,

I'm learning Python and going through you're online tutorial (for the
current/3.3.2 documentation).
Specifically, the one section I'll be referencing is:
http://docs.python.org/3/tutorial/introduction.html#lists

There are 2 errors I spotted in the documentation:
1) The text writes:
"
All slice operations return a new list containing the requested elements.
This means that the following slice returns a new (shallow) copy of the
list:

>>> squares[:][1, 2, 4, 9, 16, 25]

"

Though I believe the "new (shallow) copy" text should display "new (deep)
copy".

The reason is because it looks like 'not' performing the splice (i.e.
referencing just the variable name as the operand) performs the shallow
copy. The slice operations--including [:]--return a deep copy.
Take a look at this session I had (with the 3.3.2 interpreter):

>>> numbers = [1, 2, 3, 4, 5]
>>> numbers
[1, 2, 3, 4, 5]
>>> shallowCopy = numbers
>>> deepCopy = numbers[:]
>>> shallowCopy
[1, 2, 3, 4, 5]
>>> deepCopy
[1, 2, 3, 4, 5]
>>> 'Now that we have that established...'
'Now that we have that established...'
>>> shallowCopy[0] = 6
>>> shallowCopy
[6, 2, 3, 4, 5]
>>> numbers
[6, 2, 3, 4, 5]
>>> 'So "shallowCopy" is indeed a shallow copy of "numbers"'
'So "shallowCopy" is indeed a shallow copy of "numbers"'
>>> deepCopy[0] = 7
>>> deepCopy
[7, 2, 3, 4, 5]
>>> numbers
[6, 2, 3, 4, 5]
>>> 'And here we notice "deepCopy" (which was created with a splice of
"numbers"
) is indeed a deep copy of "numbers"'

2) The other issue a small one at the bottom of the section, where it reads:
"
It is possible to nest lists (create lists containing other lists), for
example:

>>> a = ['a', 'b', 'c']>>> n = [1, 2, 3]>>> x = [a, n]>>> x[['a', 'b', 'c'], [1, 2, 3]]>>> p[0]['a', 'b', 'c']>>> p[0][1]'b'

"

Here, the "p" list is not defined, so the user sees an error.
Using the "x" list in p's place would fix it.

- - - - -

And, if you have the time, I just have a quick question I'm hoping you
might be able to help with--it may even involve an update to the
documentation as well.
It goes back to the text that I referenced in the first error: "All slice
operations return a new list containing the requested elements."

The thing I find a bit confusing is that later, the documentation mentions
"Assignment to slices is also possible," and gives some examples, such as:

>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']>>> letters['a', 'b', 'c', 'd', 'e', 'f', 'g']>>> # replace some values>>> letters[2:5] = ['C', 'D', 'E']>>> letters['a', 'b', 'C', 'D', 'E', 'f', 'g']>>> # now remove them>>> letters[2:5] = []>>> letters['a', 'b', 'f', 'g']


Well, my question is: if the slice operations return new lists, how would
assignment operators change the original list?
Of course, I see that in practice, the slice operation returns the original
(or a portion of the original) list when it's not the operand, though I'm
just wondering if the wording needs to be updated, or if some addition bit
of text might clear things up.

Let me know if I'm wrong, or if you need any information.

Thanks!
A Python explorer.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130526/19481cc4/attachment-0001.html>

From turners at ieca.com  Tue May 21 05:01:33 2013
From: turners at ieca.com (Sean Turner)
Date: Tue, 21 May 2013 03:01:33 -0000
Subject: [docs] some RFC references could be updated
Message-ID: <519ADE01.7090104@ieca.com>

Hi,

Just starting to learn python and have noted that at the bottom of this 
page:

http://docs.python.org/3/library/ssl.html

There's a couple of out of date references:

0) RFC 1750 has been been obsoleted by RFC 4086 so maybe this is a 
better reference (and I prefer the datatracker view as opposed to the 
tools view):

http://datatracker.ietf.org/doc/rfc4086/

Same could be done on this link:

http://docs.python.org/3.4/library/ssl.html

1) RFC 3280 has been obsoleted by RFC 5280 so maybe:

http://datatracker.ietf.org/doc/rfc5280/

Same could be done on this link:

http://docs.python.org/3.4/library/ssl.html

2) RFC 4366 has been obsoleted by RFC 6066 so maybe:

http://datatracker.ietf.org/doc/rfc6066/

On http://docs.python.org/3.4/library/ssl.html you could probably just 
drop the reference and change in the ssl.HAS_SNI section.


3) The link to TLS seems broken maybe just point to:

TLS 1.0 http://datatracker.ietf.org/doc/rfc2246/
TLS 1.1 http://datatracker.ietf.org/doc/rfc4346/
TLS 1.2 http://datatracker.ietf.org/doc/rfc5246/
SSL 3.0 http://datatracker.ietf.org/doc/rfc6101/

Actually the same link is broken on:

http://docs.python.org/3.4/library/ssl.html

4) (this is a shameless plug) Might be worth adding a reference in the 
ssl.PROTOCOL_SSLv2 section that points to:

http://datatracker.ietf.org/doc/rfc6146/

Cheers,

spt