From jjraiche at gmail.com  Mon Dec  1 18:16:38 2014
From: jjraiche at gmail.com (Josiah Raiche)
Date: Mon, 1 Dec 2014 12:16:38 -0500
Subject: [docs] python documentation issue
Message-ID: <CAAmMsU500QeLg8Cj3oXXjy_gUQNCMVRg8ED1KB7taGj++n2D+Q@mail.gmail.com>

The change in print() has rendered the beginner project docs 20.2 (CGI)
inoperative. Copy and paste of the script gives a 500 error.

Simply adding parentheses works but this isn't obvious from the error logs.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141201/ff1f89a0/attachment.html>

From report at bugs.python.org  Mon Dec  1 21:22:12 2014
From: report at bugs.python.org (Chris Rebert)
Date: Mon, 01 Dec 2014 20:22:12 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417465332.61.0.494972634705.issue21557@psf.upfronthosting.co.za>


Chris Rebert added the comment:

Here is a patch that adds the necessary warnings from issue 7950.
Please review it when you get a chance.

----------
keywords: +patch
Added file: http://bugs.python.org/file37338/fix-21557.patch

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

From zachary.ware+pydocs at gmail.com  Mon Dec  1 21:35:13 2014
From: zachary.ware+pydocs at gmail.com (Zachary Ware)
Date: Mon, 1 Dec 2014 14:35:13 -0600
Subject: [docs] python documentation issue
In-Reply-To: <CAAmMsU500QeLg8Cj3oXXjy_gUQNCMVRg8ED1KB7taGj++n2D+Q@mail.gmail.com>
References: <CAAmMsU500QeLg8Cj3oXXjy_gUQNCMVRg8ED1KB7taGj++n2D+Q@mail.gmail.com>
Message-ID: <CAKJDb-PDZXGbrO7xbNj9V0863rBwq4Uw0A1dSKE0SpTSsnwHGA@mail.gmail.com>

Hi Josiah,

On Mon, Dec 1, 2014 at 11:16 AM, Josiah Raiche <jjraiche at gmail.com> wrote:
> The change in print() has rendered the beginner project docs 20.2 (CGI)
> inoperative. Copy and paste of the script gives a 500 error.
>
> Simply adding parentheses works but this isn't obvious from the error logs.

Could you please reply with the version of Python that you're using
and a link to the page that you believe has a problem?  It sound to me
like you're using Python 3, but using the Python 2 documentation.
Compare https://docs.python.org/3/library/cgi.html and
https://docs.python.org/2/library/cgi.html.

Regards,
-- 
Zach

From report at bugs.python.org  Mon Dec  1 21:46:34 2014
From: report at bugs.python.org (Chris Rebert)
Date: Mon, 01 Dec 2014 20:46:34 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1410110444.5.0.966357232963.issue22356@psf.upfronthosting.co.za>
Message-ID: <1417466794.79.0.570243222504.issue22356@psf.upfronthosting.co.za>


Chris Rebert added the comment:

Ping. This small patch has been waiting nearly 3 months for a review.

----------

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

From jjraiche at gmail.com  Mon Dec  1 21:43:07 2014
From: jjraiche at gmail.com (Josiah Raiche)
Date: Mon, 1 Dec 2014 15:43:07 -0500
Subject: [docs] python documentation issue
In-Reply-To: <CAKJDb-PDZXGbrO7xbNj9V0863rBwq4Uw0A1dSKE0SpTSsnwHGA@mail.gmail.com>
References: <CAAmMsU500QeLg8Cj3oXXjy_gUQNCMVRg8ED1KB7taGj++n2D+Q@mail.gmail.com>
 <CAKJDb-PDZXGbrO7xbNj9V0863rBwq4Uw0A1dSKE0SpTSsnwHGA@mail.gmail.com>
Message-ID: <CAAmMsU4S80qAaH4mcMR82gds9+pYTJzr0XYu8Btv+ytUndoeew@mail.gmail.com>

That's probably why. I went to the documentation link, probably via google,
when setting up my apache server. Sorry to clutter the mailing list with
non-bugs.

Josiah
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141201/f0c61fbb/attachment.html>

From zachary.ware+pydocs at gmail.com  Mon Dec  1 21:57:29 2014
From: zachary.ware+pydocs at gmail.com (Zachary Ware)
Date: Mon, 1 Dec 2014 14:57:29 -0600
Subject: [docs] python documentation issue
In-Reply-To: <CAAmMsU4S80qAaH4mcMR82gds9+pYTJzr0XYu8Btv+ytUndoeew@mail.gmail.com>
References: <CAAmMsU500QeLg8Cj3oXXjy_gUQNCMVRg8ED1KB7taGj++n2D+Q@mail.gmail.com>
 <CAKJDb-PDZXGbrO7xbNj9V0863rBwq4Uw0A1dSKE0SpTSsnwHGA@mail.gmail.com>
 <CAAmMsU4S80qAaH4mcMR82gds9+pYTJzr0XYu8Btv+ytUndoeew@mail.gmail.com>
Message-ID: <CAKJDb-NE1s9xzAvgn8DfBpKvSrpeevEpUj3qWCm2WQdpzYf_GQ@mail.gmail.com>

On Mon, Dec 1, 2014 at 2:43 PM, Josiah Raiche <jjraiche at gmail.com> wrote:
> That's probably why. I went to the documentation link, probably via google,
> when setting up my apache server. Sorry to clutter the mailing list with
> non-bugs.

No problem!  That's what this list is here for: determining what's a
bug, what's not, and how to fix the bugs.

Regards,
-- 
Zach

From report at bugs.python.org  Mon Dec  1 22:02:13 2014
From: report at bugs.python.org (Ned Deily)
Date: Mon, 01 Dec 2014 21:02:13 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1410110444.5.0.966357232963.issue22356@psf.upfronthosting.co.za>
Message-ID: <1417467733.64.0.135394712553.issue22356@psf.upfronthosting.co.za>


Changes by Ned Deily <nad at acm.org>:


----------
nosy: +belopolsky

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

From report at bugs.python.org  Mon Dec  1 22:32:52 2014
From: report at bugs.python.org (Alexander Belopolsky)
Date: Mon, 01 Dec 2014 21:32:52 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1410110444.5.0.966357232963.issue22356@psf.upfronthosting.co.za>
Message-ID: <1417469572.79.0.885593324312.issue22356@psf.upfronthosting.co.za>


Alexander Belopolsky added the comment:

I don't like the proposed note.

1. It is not the job of the time module documentation to warn about "many functions in the stdlib."  What are these functions, BTW?

2. What is "calendar time in POSIX encoding"? This sounds like what time.asctime() returns.

I think an improvement would be to spell Epoch with a capital E and define it as "The time zero hours, zero minutes, zero seconds, on January 1, 1970 Coordinated Universal Time (UTC)."  See <http://pubs.opengroup.org/onlinepubs/9699919799>.

----------

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

From report at bugs.python.org  Mon Dec  1 23:36:03 2014
From: report at bugs.python.org (Akira Li)
Date: Mon, 01 Dec 2014 22:36:03 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1417469572.79.0.885593324312.issue22356@psf.upfronthosting.co.za>
 (Alexander Belopolsky's message of "Mon,
 01 Dec 2014 21:32:52 +0000")
Message-ID: <87egsj9eyn.fsf@gmail.com>


Akira Li added the comment:

> Alexander Belopolsky added the comment:
>
> 1. It is not the job of the time module documentation to warn about
> "many functions in the stdlib."  What are these functions, BTW?

The e-mail linked in the first message of this issue msg226539
enumerates some of the functions:

  https://mail.python.org/pipermail/python-ideas/2014-September/029228.html

> 2. What is "calendar time in POSIX encoding"? This sounds like what time.asctime() returns.

It is the language used by C standard for time() function:

  The time function determines the current calendar time. The encoding
  of the value is unspecified.

> I think an improvement would be to spell Epoch with a capital E and
> define it as "The time zero hours, zero minutes, zero seconds, on
> January 1, 1970 Coordinated Universal Time (UTC)."  See
> <http://pubs.opengroup.org/onlinepubs/9699919799>.
>

The word *epoch* (lowercase) is used by C standard.

It is not enough to say that time module uses POSIX epoch (Epoch) e.g.,
a machine may use "right" zoneinfo (the same epoch year 1970) but the
timestamp for the same UTC time are different by number of leap seconds
(10+25 since 2012).

POSIX encoding implies that the formula works:

  utc_time = datetime(1970, 1,  1) + timedelta(seconds=posix_timestamp)

if time.time() doesn't return posix_timestamp than "many functions in
the stdlib" will break.

It is possible to inspect all stdlib functions that use time module and
determine for some of them whether they will break if gmtime(0) is not
1970 or "right" zoneinfo is used or any non-POSIX time encoding is
used. But it is hard to maintain such a list because any future code
change may affect the behavior. I prefer a vague statement ("many
functions") over a possible lie (the documentation shouldn't make
promises that the implementation can't keep).

POSIX language is (intentionally) vague and avoids SI seconds vs. UT1
(mean solar) seconds distinction. I don't consider systems where
"seconds" doesn't mean SI seconds used by UTC time scale.

----------

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

From report at bugs.python.org  Mon Dec  1 23:46:42 2014
From: report at bugs.python.org (Demian Brecht)
Date: Mon, 01 Dec 2014 22:46:42 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417474002.88.0.975188658858.issue21557@psf.upfronthosting.co.za>


Demian Brecht added the comment:

Left a comment in Rietveld.

----------
nosy: +demian.brecht

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

From report at bugs.python.org  Tue Dec  2 00:18:03 2014
From: report at bugs.python.org (Alexander Belopolsky)
Date: Mon, 01 Dec 2014 23:18:03 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1410110444.5.0.966357232963.issue22356@psf.upfronthosting.co.za>
Message-ID: <1417475883.55.0.627965515414.issue22356@psf.upfronthosting.co.za>


Alexander Belopolsky added the comment:

In the context of Python library documentation, the word "encoding" strongly suggests that you are dealing with string/bytes.  The situation may be different in C. If you want to refer to something that is defined by the POSIX standard you should use the words that can actually be found in that standard.  

When I search for "encoding" at <http://pubs.opengroup.org/onlinepubs/9699919799/>, I get

crypt - string encoding function (CRYPT) 
encrypt - encoding function (CRYPT) 
setkey - set encoding key (CRYPT)

and nothing related to time.

----------

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

From report at bugs.python.org  Tue Dec  2 00:33:35 2014
From: report at bugs.python.org (Akira Li)
Date: Mon, 01 Dec 2014 23:33:35 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1417475883.55.0.627965515414.issue22356@psf.upfronthosting.co.za>
 (Alexander Belopolsky's message of "Mon,
 01 Dec 2014 23:18:03 +0000")
Message-ID: <87a9379caq.fsf@gmail.com>


Akira Li added the comment:

> Alexander Belopolsky added the comment:
>
> In the context of Python library documentation, the word "encoding"
> strongly suggests that you are dealing with string/bytes.  The
> situation may be different in C. If you want to refer to something
> that is defined by the POSIX standard you should use the words that
> can actually be found in that standard.
>
> When I search for "encoding" at <http://pubs.opengroup.org/onlinepubs/9699919799/>, I get
>
> crypt - string encoding function (CRYPT) 
> encrypt - encoding function (CRYPT) 
> setkey - set encoding key (CRYPT)
>
> and nothing related to time.
>

I've provide the direct quote from *C* standard in my previous message msg231957:

  > 2. What is "calendar time in POSIX encoding"? This sounds like what time.asctime() returns.

  It is the language used by C standard for time() function:

    The time function determines the current calendar time. The encoding
    of the value is unspecified.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ <- from the C standard

notice the word *encoding* in the quote.

----------

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

From report at bugs.python.org  Tue Dec  2 01:07:12 2014
From: report at bugs.python.org (Alexander Belopolsky)
Date: Tue, 02 Dec 2014 00:07:12 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1410110444.5.0.966357232963.issue22356@psf.upfronthosting.co.za>
Message-ID: <1417478832.05.0.394256656764.issue22356@psf.upfronthosting.co.za>


Alexander Belopolsky added the comment:

> It is possible to inspect all stdlib functions that use time module and
> determine for some of them whether they will break if gmtime(0) is not
> 1970 or "right" zoneinfo is used or any non-POSIX time encoding is
> used. But it is hard to maintain such a list because any future code
> change may affect the behavior.

Let's not confuse the issue of gmtime(0) not being 1970-01-01T00 and localtime() expecting non-POSIX time_t.  Since gmtime(0) is the same on all platforms supported by Python, it is a fair game to rely on this fact in Python code.

The issue of "right" zoneinfo is different: at least two major Python platforms (OS X and Linux) can be configured in a non-POSIX way.  The decision not to support these configurations in the datetime module was deliberate, but some partial support can be added.  For example, datetime.astimezone() cannot work correctly in the "right" timezone because datetime.second cannot be 60, but if it returns values that are off by some 20 seconds in other times, I would call it a bug, but many will disagree.

I don't know how popular configurations with right timezones are, but testing Python stdlib in those configurations can only help the overall stdlib quality.
(Unfortunately, at the moment we have have very few tests even for the mainstream timezones such as Europe/Moscow.)

----------

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

From report at bugs.python.org  Tue Dec  2 01:38:57 2014
From: report at bugs.python.org (Alexander Belopolsky)
Date: Tue, 02 Dec 2014 00:38:57 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1410110444.5.0.966357232963.issue22356@psf.upfronthosting.co.za>
Message-ID: <1417480737.76.0.402866431002.issue22356@psf.upfronthosting.co.za>


Alexander Belopolsky added the comment:

> I've provide the direct quote from *C* standard ...

I understand that C standard uses the word "encoding", but it does so for a reason that is completely unrelated to the choice of epoch.  "Encoding" is how the bytes in memory should be interpreted as "number of seconds" or some other notion of time.  For, example "two's complement little-endian 32-bit signed int" is an example of valid time_t encoding, another example would be IEEE 754 big-endian 64-bit double.  Note that these choices are valid for both C and POSIX standards.

If you google for your phrase "time in POSIX encoding", this issue is the only hit.  This strongly suggests that your choice of words is not the most natural.

----------

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

From demianbrecht at gmail.com  Mon Dec  1 23:46:04 2014
From: demianbrecht at gmail.com (demianbrecht at gmail.com)
Date: Mon, 01 Dec 2014 22:46:04 -0000
Subject: [docs] os.popen & os.system lack shell-related security warnings
	(issue 21557)
Message-ID: <20141201224604.19187.45512@psf.upfronthosting.co.za>


http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst
File Doc/library/os.rst (right):

http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode2905
Doc/library/os.rst:2905: .. warning::
This warning is a little confusing to me. If input sanitization is the
issue (which is a perfectly valid concern), why not explain the issue
and how to plug the hole rather than discouraging its use altogether?

As is, this reads a little strange to me given you're discouraging the
use due to a specific case and then in the next paragraph explaining how
to fix it. I'd rather just see an explanation of the possible security
hole and how to account for it to make the usage here safe.

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

From report at bugs.python.org  Tue Dec  2 09:02:15 2014
From: report at bugs.python.org (Akira Li)
Date: Tue, 02 Dec 2014 08:02:15 +0000
Subject: [docs] [issue22356] mention explicitly that stdlib assumes
	gmtime(0) epoch	is 1970
In-Reply-To: <1417480737.76.0.402866431002.issue22356@psf.upfronthosting.co.za>
 (Alexander Belopolsky's message of "Tue,
 02 Dec 2014 00:38:57 +0000")
Message-ID: <8761dua3bh.fsf@gmail.com>


Akira Li added the comment:

> Alexander Belopolsky added the comment:
>
>> I've provide the direct quote from *C* standard ...
>
> I understand that C standard uses the word "encoding", but it does so
> for a reason that is completely unrelated to the choice of epoch.
> "Encoding" is how the bytes in memory should be interpreted as "number
> of seconds" or some other notion of time.  For, example "two's
> complement little-endian 32-bit signed int" is an example of valid
> time_t encoding, another example would be IEEE 754 big-endian 64-bit
> double.  Note that these choices are valid for both C and POSIX
> standards.

I agree one *part* of "encoding" is how time_t is *represented* in
memory but it is not the only part e.g.:

  The mktime function converts the broken-down time, expressed as local
  time, in the structure pointed to by timeptr into a calendar time
  value with the same encoding as that of the values returned by the
  time function.

notice: "the same encoding as ... returned by the time function".

time() function can return values with different epoch (implementation
defined). mktime() is specified to use the *same* encoding i.e., the
same epoch, etc.

i.e., [in simple words] we have calendar time (Gregorian date, time) and
we can convert it to a number (e.g., Python integer), we can call that
number "seconds" and we can represent that number as some (unspecified)
bit-pattern in C.

I consider the whole process of converting "time" to a bit-pattern in
memory as "encoding" i.e., "32/64, un/signed int/754 double" is just
*part* of it e.g.,

1. specify that 1970-01-01T00:00:00Z is zero (0)
2. specify 0 has time_t type
3. specify how time_t type is represented in memory.

I may be wrong that C standard includes the first item in time
"encoding".

> If you google for your phrase "time in POSIX encoding", this issue is
> the only hit.  This strongly suggests that your choice of words is not
> the most natural.

I've googled the phrase (no surrounding quotes) and the links talk about
time encoded as POSIX time [1] and some *literally* contain the phrase
*POSIX encoding* [2] because *Python* documentation for calendar.timegm
contains it [3]:

  [timegm] returns the corresponding Unix timestamp value, assuming an
  epoch of 1970, and the POSIX encoding. In fact, time.gmtime() and
  timegm() are each others? inverse.

In an effort to avoid personal influence, I've repeated the expreriment
using Tor browser and other search engines -- the result is the same.

timegm() documentation might be the reason why I've used the phrase.

I agree "POSIX encoding" might be unclear. The patch could be replaced
by any phrase that expresses that some functions in stdlib assume that
time.time() returns (+/- fractional part) "seconds since the Epoch" as
defined by POSIX [4].

[1] http://en.wikipedia.org/wiki/Unix_time#Encoding_time_as_a_number
[2] http://ruslanspivak.com/2011/07/20/how-to-convert-python-utc-datetime-object-to-unix-timestamp/
[3] https://docs.python.org/3/library/calendar.html#calendar.timegm
[4]
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_15

----------

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

From report at bugs.python.org  Tue Dec  2 17:53:13 2014
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 02 Dec 2014 16:53:13 +0000
Subject: [docs] [issue22473] The gloss on asyncio "future with run_forever"
	example	is confusing
In-Reply-To: <1411515975.42.0.282827755318.issue22473@psf.upfronthosting.co.za>
Message-ID: <20141202165304.69793.2925@psf.io>


Roundup Robot added the comment:

New changeset a4b58e779a16 by Victor Stinner in branch '3.4':
Close #22473: asyncio doc: rephrase Future with run_forever() example
https://hg.python.org/cpython/rev/a4b58e779a16

----------
nosy: +python-dev
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

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

From report at bugs.python.org  Tue Dec  2 17:54:03 2014
From: report at bugs.python.org (STINNER Victor)
Date: Tue, 02 Dec 2014 16:54:03 +0000
Subject: [docs] [issue22473] The gloss on asyncio "future with run_forever"
	example	is confusing
In-Reply-To: <1411515975.42.0.282827755318.issue22473@psf.upfronthosting.co.za>
Message-ID: <1417539243.21.0.917708299061.issue22473@psf.upfronthosting.co.za>


STINNER Victor added the comment:

I rephrase the explanation of the example and I removed the useless note. Thanks for your feedback David. Don't hesitate to propose other enhancements to the documentation!

----------

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

From report at bugs.python.org  Tue Dec  2 18:02:49 2014
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 02 Dec 2014 17:02:49 +0000
Subject: [docs] [issue22475] asyncio task get_stack documentation seems to
	contradict	itself
In-Reply-To: <1411519909.22.0.512722932689.issue22475@psf.upfronthosting.co.za>
Message-ID: <20141202170134.69793.53588@psf.io>


Roundup Robot added the comment:

New changeset 4b6b03c1f4ff by Victor Stinner in branch '3.4':
Closes #22475: asyncio doc, fix Task.get_stack() doc
https://hg.python.org/cpython/rev/4b6b03c1f4ff

----------
nosy: +python-dev
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

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

From report at bugs.python.org  Tue Dec  2 18:04:23 2014
From: report at bugs.python.org (STINNER Victor)
Date: Tue, 02 Dec 2014 17:04:23 +0000
Subject: [docs] [issue22475] asyncio task get_stack documentation seems to
	contradict	itself
In-Reply-To: <1411519909.22.0.512722932689.issue22475@psf.upfronthosting.co.za>
Message-ID: <1417539863.33.0.388957988983.issue22475@psf.upfronthosting.co.za>


STINNER Victor added the comment:

I fixed the most obvious issue in the documentation. I don't know the function enough to propose a better documentation, sorry.

Don't hesitate to write a patch on the documentation if you have a better explanation of how get_stack() behaves.

It is correct that get_stack() only returns 1 frame if the task is suspended, whereas it returns more frames if get_stack() is called while the task is running.

----------

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

From report at bugs.python.org  Tue Dec  2 22:41:56 2014
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 02 Dec 2014 21:41:56 +0000
Subject: [docs] [issue17401] io.FileIO closefd parameter is not documented
	nor shown	in repr
In-Reply-To: <1363057927.36.0.00381165430664.issue17401@psf.upfronthosting.co.za>
Message-ID: <20141202214149.105523.53174@psf.io>


Roundup Robot added the comment:

New changeset fd80195b920f by Serhiy Storchaka in branch 'default':
Issue #17401: Output the closefd attribute as boolean.
https://hg.python.org/cpython/rev/fd80195b920f

----------

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

From report at bugs.python.org  Tue Dec  2 22:44:07 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 02 Dec 2014 21:44:07 +0000
Subject: [docs] [issue17401] io.FileIO closefd parameter is not documented
	nor shown	in repr
In-Reply-To: <1363057927.36.0.00381165430664.issue17401@psf.upfronthosting.co.za>
Message-ID: <1417556647.89.0.800434211097.issue17401@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Committed the first patch (showing closefd always) with additional test from second path.

----------
versions:  -Python 3.4

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

From report at bugs.python.org  Tue Dec  2 22:58:49 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Tue, 02 Dec 2014 21:58:49 +0000
Subject: [docs] [issue17401] io.FileIO closefd parameter is not documented
	nor shown	in repr
In-Reply-To: <1363057927.36.0.00381165430664.issue17401@psf.upfronthosting.co.za>
Message-ID: <1417557529.72.0.549043410153.issue17401@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
resolution:  -> fixed
stage: commit review -> resolved
status: open -> closed

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

From hassru at outlook.com  Tue Dec  2 09:09:24 2014
From: hassru at outlook.com (harry newton)
Date: Tue, 2 Dec 2014 19:09:24 +1100
Subject: [docs] Python documentation download error
Message-ID: <SNT150-W84433CD856347462A6D5C3D27A0@phx.gbl>

Hello



Recently, I have decided to download some of your python documentation 
for 2.7.9rc1 and the browser gives me an error saying "404 not found" 
and under that saying "nginx". hope your can fix this. I have attached a file to let you know what it looks like.



cheers.

 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141202/194a71e2/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screenshot from 2014-12-02 180839.png
Type: image/png
Size: 16122 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/docs/attachments/20141202/194a71e2/attachment-0001.png>

From pybugs at rebertia.com  Wed Dec  3 00:44:45 2014
From: pybugs at rebertia.com (pybugs at rebertia.com)
Date: Tue, 02 Dec 2014 23:44:45 -0000
Subject: [docs] os.popen & os.system lack shell-related security
	warnings (issue 21557)
Message-ID: <20141202234445.15416.22233@psf.upfronthosting.co.za>

Reviewers: demian,


http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst
File Doc/library/os.rst (right):

http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode2905
Doc/library/os.rst:2905: .. warning::
On 2014/12/01 23:46:04, demian wrote:
> This warning is a little confusing to me. If input sanitization is the
issue
> (which is a perfectly valid concern), why not explain the issue and
how to plug
> the hole rather than discouraging its use altogether?
>
> As is, this reads a little strange to me given you're discouraging the
use due
> to a specific case and then in the next paragraph explaining how to
fix it. I'd
> rather just see an explanation of the possible security hole and how
to account
> for it to make the usage here safe.

A. The patch doesn't discourage it altogether, it discourages it
specifically "in cases where the command string is constructed from
external input".

B. os.popen() deserves to be discouraged. It *defaults to being
insecure* and you must specifically remember to actively do the escaping
yourself every time. This makes it usage pretty error-prone. History has
shown that it's all too easy to overlook the need to do escaping.
The subprocess module (when shell=False, which is by default) is not
error-prone in this way, and is thus superior.
subprocess is also more flexible and featureful. I know of no
countervailing advantages whatsoever to using os.popen(). Users often do
not need / do not make use of shell features in their commands.
IMO, there's currently no good reason to ever use os.popen() instead of
the subprocess module. Legacy code is the only reason to still be using
it.



Please review this at http://bugs.python.org/review/21557/

Affected files:
  Doc/library/os.rst


diff -r 62a058c76869 Doc/library/os.rst
--- a/Doc/library/os.rst	Mon Dec 01 13:10:12 2014 +0200
+++ b/Doc/library/os.rst	Mon Dec 01 12:15:45 2014 -0800
@@ -2899,8 +2899,23 @@
    contains the signed integer return code from the child process.
 
    This is implemented using :class:`subprocess.Popen`; see that class's
-   documentation for more powerful ways to manage and communicate with
-   subprocesses.
+   documentation for safer and more powerful ways to manage and communicate
+   with subprocesses.
+
+   .. warning::
+
+      The use of :func:`popen` is **strongly discouraged** in cases where the
+      command string is constructed from external input.  Executing shell
+      commands that incorporate unsanitized input from an untrusted source
+      makes a program vulnerable to `shell injection
+      <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_,
+      a serious security flaw which can result in arbitrary command execution.
+      For greater safety, consider using :mod:`subprocess` with
+      ``shell=False`` instead.
+
+      :func:`shlex.quote` can be used to properly escape whitespace and shell
+      metacharacters in strings that are going to be used to construct shell
+      commands.
 
 
 .. function:: spawnl(mode, path, ...)
@@ -3046,10 +3061,25 @@
    status of the command run; on systems using a non-native shell, consult your
    shell documentation.
 
-   The :mod:`subprocess` module provides more powerful facilities for spawning
-   new processes and retrieving their results; using that module is preferable
-   to using this function.  See the :ref:`subprocess-replacements` section in
-   the :mod:`subprocess` documentation for some helpful recipes.
+   The :mod:`subprocess` module provides safer and more powerful facilities
+   for spawning new processes and retrieving their results; using that module
+   is preferable to using this function.  See the :ref:`subprocess-replacements`
+   section in the :mod:`subprocess` documentation for some helpful recipes.
+
+   .. warning::
+
+      The use of :func:`system` is **strongly discouraged** in cases where the
+      command string is constructed from external input.  Executing shell
+      commands that incorporate unsanitized input from an untrusted source
+      makes a program vulnerable to `shell injection
+      <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_,
+      a serious security flaw which can result in arbitrary command execution.
+      For greater safety, consider using :mod:`subprocess` with
+      ``shell=False`` instead.
+
+      :func:`shlex.quote` can be used to properly escape whitespace and shell
+      metacharacters in strings that are going to be used to construct shell
+      commands.
 
    Availability: Unix, Windows.
 



From paula.weir at rte.ie  Tue Dec  2 15:42:52 2014
From: paula.weir at rte.ie (Paula Weir)
Date: Tue, 2 Dec 2014 14:42:52 +0000
Subject: [docs] Re Python documentation 2.7
Message-ID: <CAHT-S-NQP97p_2d4qiVDkXPWa5A6jixu-iKTMPOvTeXUofbkjg@mail.gmail.com>

Hi
I have been trying to download the python documentation zip for 2.7 and I
get a 404 error.

Could you advise where else I might get a PDF of the tutorial from this
documentation.

Thanks
Paula


[image: RTE Logo]*PAULA WEIR* Aertel Developer *RT?* DigitalDonnybrook,
Dublin 4 *T: *+353 1 208 3111  *M: *  *E: *paula.weir at rte.ie  *| *
www.rte.ie  *| *  *| *  *| *LinkedIn/RT?
<http://www.linkedin.com/company/rte>

-- 
*Disclaimer:* The information in this e-mail is confidential and may be 
legally privileged. It is intended solely for the addressee. Access to this 
e-mail by anyone else is unauthorised. If you are not the intended 
recipient, any disclosure, copying, distribution, or any action taken or 
omitted to be taken in reliance on it, is prohibited and may be unlawful. 
Please note that emails to, from and within RT? may be subject to the 
Freedom of Information Act 1997 and may be liable to disclosure.

T? an t-eolas sa r?omhphost seo faoi r?n agus d'fh?adfadh s? a bheith faoi 
phribhl?id dhl?thi?il. Is ar an seola? amh?in at? s? d?rithe. N?l cead ag 
aon duine eile rochtain a fh?il ar an r?omhphost seo. Mura t? an faighteoir 
beartaithe, t? cosc ar aon nochtadh, c?ip?ail, d?ileadh, n? aon ghn?omh a 
dh?anamh n? a fh?g?il ar l?r i dtaca leis an r?omhphost agus d'fh?adfadh 
sin a bheith m?dhleathach. Tabhair ar aird le do thoil, d'fh?adfadh 
r?omhphost chuig, ? agus laistigh de RT? a bheith faoi r?ir an Achta um 
Shaor?il Faisn?ise 1997, agus d'fh?adfadh go nd?anfa? ? a nochtadh.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141202/0d7374f6/attachment.html>

From report at bugs.python.org  Wed Dec  3 08:28:46 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Wed, 03 Dec 2014 07:28:46 +0000
Subject: [docs] [issue17401] io.FileIO closefd parameter is not documented
	nor shown	in repr
In-Reply-To: <1363057927.36.0.00381165430664.issue17401@psf.upfronthosting.co.za>
Message-ID: <1417591726.49.0.652194225632.issue17401@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Arfrever have suggested on IRC to backport documentation part of the patch to 3.4.

----------

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

From report at bugs.python.org  Wed Dec  3 14:15:58 2014
From: report at bugs.python.org (Kali Kaneko)
Date: Wed, 03 Dec 2014 13:15:58 +0000
Subject: [docs] [issue22987] ssl module documentation: incorrect
	compatibility matrix
Message-ID: <1417612558.33.0.597958584531.issue22987@psf.upfronthosting.co.za>


New submission from Kali Kaneko:

The SSLv23 row that can be read in the socket creation section in the documentation for the ssl module looks incorrect:
https://docs.python.org/2.7/library/ssl.html#socket-creation

by my tests (with python 2.7.8) that row should read:

yes no yes yes yes yes

instead of:

yes no yes no no no 

as it does now.

Since a client specifying SSLv23 should be (and it seems to be) able to negotiate the highest available version that the server can offer, no matter if the server has chosen a tls version.

Is this an error in the documentation, or is there any situation in which the current values hold true?

----------
assignee: docs at python
components: Documentation
messages: 232078
nosy: docs at python, kali
priority: normal
severity: normal
status: open
title: ssl module documentation: incorrect compatibility matrix
versions: Python 2.7

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

From report at bugs.python.org  Wed Dec  3 17:05:05 2014
From: report at bugs.python.org (Alex Gaynor)
Date: Wed, 03 Dec 2014 16:05:05 +0000
Subject: [docs] [issue22987] ssl module documentation: incorrect
	compatibility matrix
In-Reply-To: <1417612558.33.0.597958584531.issue22987@psf.upfronthosting.co.za>
Message-ID: <1417622705.12.0.262773504719.issue22987@psf.upfronthosting.co.za>


Alex Gaynor added the comment:

I agree this is a bug, but I believe the correct output is:

no yes yes yes yes yes

----------
nosy: +alex, christian.heimes, dstufft, giampaolo.rodola, janssen, pitrou

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

From report at bugs.python.org  Wed Dec  3 17:13:44 2014
From: report at bugs.python.org (Antoine Pitrou)
Date: Wed, 03 Dec 2014 16:13:44 +0000
Subject: [docs] [issue22987] ssl module documentation: incorrect
	compatibility matrix
In-Reply-To: <1417612558.33.0.597958584531.issue22987@psf.upfronthosting.co.za>
Message-ID: <1417623224.61.0.286231210035.issue22987@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

Alex is right. The current doc was valid for older OpenSSL versions, which sent a SSLv2 hello with SSLv23.

Reference from the OpenSSL docs:

"""If the cipher list does not contain any SSLv2 ciphersuites (the default cipher list does not) or extensions are required (for example server name) a client will send out TLSv1 client hello messages including extensions and will indicate that it also understands TLSv1.1, TLSv1.2 and permits a fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols."""

(https://www.openssl.org/docs/ssl/SSL_CTX_new.html)

----------

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

From report at bugs.python.org  Wed Dec  3 19:45:17 2014
From: report at bugs.python.org (Paul Hartmann)
Date: Wed, 03 Dec 2014 18:45:17 +0000
Subject: [docs] [issue22989] HTTPResponse.msg not as documented
Message-ID: <1417632317.82.0.906874710781.issue22989@psf.upfronthosting.co.za>


New submission from Paul Hartmann:

HTTPResponse.msg is documented as a http.client.HTTPMessage object containing the headers of the response [1].

But in fact this is a string containing the status code:

>>> import urllib.request
>>> req=urllib.request.urlopen('http://heise.de')
>>> content = req.read()
>>> type(req.msg)
<class 'str'>
>>> req.msg
'OK'

This value is apparently overriden in urllib/request.py:

./urllib/request.py:1246:        # This line replaces the .msg attribute of the HTTPResponse
./urllib/request.py-1247-        # with .headers, because urllib clients expect the response to
./urllib/request.py:1248:        # have the reason in .msg.  It would be good to mark this
./urllib/request.py-1249-        # attribute is deprecated and get then to use info() or
./urllib/request.py-1250-        # .headers.
./urllib/request.py:1251:        r.msg = r.reason

Anyhow, it should be documented, that is not safe to retrieve the headers with HTTPResponse.msg and maybe add HTTPResponse.headers to the documentation.

[1] https://docs.python.org/3/library/http.client.html

----------
assignee: docs at python
components: Documentation
messages: 232083
nosy: bastik, docs at python
priority: normal
severity: normal
status: open
title: HTTPResponse.msg not as documented
versions: Python 3.4

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

From report at bugs.python.org  Wed Dec  3 19:49:57 2014
From: report at bugs.python.org (R. David Murray)
Date: Wed, 03 Dec 2014 18:49:57 +0000
Subject: [docs] [issue22988] No error when yielding from `finally`
In-Reply-To: <1417629074.29.0.62488033247.issue22988@psf.upfronthosting.co.za>
Message-ID: <1417632597.7.0.681785594826.issue22988@psf.upfronthosting.co.za>


R. David Murray added the comment:

FIlipe, in case you hadn't noticed, the reason for the error in the other issue is that the generator was closed when it got garbage collected, and it ignored the close (executed a yield after the close).  Thus the error message there is accurate and expected, just as (as Guido said) the behavior here is consistent with the combined semantics of generators and try/finally.

Do you want to suggest an improvement to the docs?  It may be that we'll decide a change is more confusing than helpful, but we'll need someone to suggest a wording to decide that.

----------
assignee:  -> docs at python
components: +Documentation -Interpreter Core
nosy: +docs at python, r.david.murray
versions: +Python 3.5

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

From report at bugs.python.org  Wed Dec  3 19:56:51 2014
From: report at bugs.python.org (R. David Murray)
Date: Wed, 03 Dec 2014 18:56:51 +0000
Subject: [docs] [issue22989] HTTPResponse.msg not as documented
In-Reply-To: <1417632317.82.0.906874710781.issue22989@psf.upfronthosting.co.za>
Message-ID: <1417633011.36.0.871565998977.issue22989@psf.upfronthosting.co.za>


Changes by R. David Murray <rdmurray at bitdance.com>:


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

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

From report at bugs.python.org  Wed Dec  3 20:04:04 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 03 Dec 2014 19:04:04 +0000
Subject: [docs] [issue22987] ssl module documentation: incorrect
	compatibility matrix
In-Reply-To: <1417612558.33.0.597958584531.issue22987@psf.upfronthosting.co.za>
Message-ID: <20141203190354.105527.19779@psf.io>


Roundup Robot added the comment:

New changeset 7af5d5493497 by Antoine Pitrou in branch '2.7':
Fix #22987: update the compatibility matrix for a SSLv23 client.
https://hg.python.org/cpython/rev/7af5d5493497

New changeset 9f03572690d2 by Antoine Pitrou in branch '3.4':
Fix #22987: update the compatibility matrix for a SSLv23 client.
https://hg.python.org/cpython/rev/9f03572690d2

New changeset 7509a0607c40 by Antoine Pitrou in branch 'default':
Fix #22987: update the compatibility matrix for a SSLv23 client.
https://hg.python.org/cpython/rev/7509a0607c40

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

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

From report at bugs.python.org  Wed Dec  3 20:05:41 2014
From: report at bugs.python.org (Ethan Furman)
Date: Wed, 03 Dec 2014 19:05:41 +0000
Subject: [docs] [issue22988] No error when yielding from `finally`
In-Reply-To: <1417629074.29.0.62488033247.issue22988@psf.upfronthosting.co.za>
Message-ID: <1417633541.42.0.915549597985.issue22988@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Here's the excerpt from the docs:
--------------------------------
> Yield expressions are allowed in the try clause of a try ... finally construct.
> If the generator is not resumed before it is finalized (by reaching a zero reference
> count or by being garbage collected), the generator-iterator?s close() method will be
> called, allowing any pending finally clauses to execute.

This certainly makes it sound like 'yield' is okay in the 'try' portion, but not the 'finally' portion.

So 'yield' is allowed in the 'try' portion, and it's allowed in the 'finally' portion -- is it also allowed in the 'except' portion?  If so, we could simplify the first line to:

> Yield expressions are allowed in try ... except ... finally constructs.

----------

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

From report at bugs.python.org  Wed Dec  3 20:11:10 2014
From: report at bugs.python.org (Antoine Pitrou)
Date: Wed, 03 Dec 2014 19:11:10 +0000
Subject: [docs] [issue22987] ssl module documentation: incorrect
	compatibility matrix
In-Reply-To: <1417612558.33.0.597958584531.issue22987@psf.upfronthosting.co.za>
Message-ID: <1417633870.72.0.693228781187.issue22987@psf.upfronthosting.co.za>


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


----------
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
versions: +Python 3.4, Python 3.5

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

From report at bugs.python.org  Wed Dec  3 20:37:42 2014
From: report at bugs.python.org (Felipe)
Date: Wed, 03 Dec 2014 19:37:42 +0000
Subject: [docs] [issue22988] No error when yielding from `finally`
In-Reply-To: <1417629074.29.0.62488033247.issue22988@psf.upfronthosting.co.za>
Message-ID: <1417635462.26.0.321311362467.issue22988@psf.upfronthosting.co.za>


Felipe added the comment:

Thanks for the clarification; sorry I misread issue #14718.

I agree with Ethan's point. Though I would say "Yield expressions are allowed anywhere in try ... except ... finally constructs."

I'd also like to explicitly add a point about the exception-handling machinery getting frozen, but I'm not sure how to phrase it clearly and accurately. Here's an attempt (my adds in square brackets):

"By suspended, we mean that all local state is retained, including the current bindings of local variables, the instruction pointer, the internal evaluation stack, [active exception handlers, and paused exceptions in finally blocks]."

Another approach would be:
"By suspended, we mean that all local state is retained, including the current bindings of local variables, the instruction pointer, and the internal evaluation stack. [The state of any exception-handling code is also retained when yielding from a try ... except ... finally statement.]"

----------

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

From report at bugs.python.org  Wed Dec  3 20:39:15 2014
From: report at bugs.python.org (Guido van Rossum)
Date: Wed, 03 Dec 2014 19:39:15 +0000
Subject: [docs] [issue22988] No error when yielding from `finally`
In-Reply-To: <1417629074.29.0.62488033247.issue22988@psf.upfronthosting.co.za>
Message-ID: <1417635555.29.0.570487108427.issue22988@psf.upfronthosting.co.za>


Changes by Guido van Rossum <guido at python.org>:


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

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

From report at bugs.python.org  Wed Dec  3 20:48:41 2014
From: report at bugs.python.org (Demian Brecht)
Date: Wed, 03 Dec 2014 19:48:41 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417636121.92.0.773386061422.issue21557@psf.upfronthosting.co.za>


Demian Brecht added the comment:

After discussion in Rietveld, the patch looks good to me.

----------

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

From report at bugs.python.org  Wed Dec  3 22:32:25 2014
From: report at bugs.python.org (R. David Murray)
Date: Wed, 03 Dec 2014 21:32:25 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417642345.9.0.793059048881.issue21557@psf.upfronthosting.co.za>


R. David Murray added the comment:

Since Raymond is the person who tends to object most strongly to warning boxes in the docs, let's get his opinion on this.  I'm not sure that the warning box is necessary, the text may be sufficient.  On the other hand, this *is* a significant insecurity vector.

As far as the text goes, I'd combine the two paragraphs and introduce the text from the second one with "Alternatively, ...".  And if it isn't a warning box, the the language should be refocused to be positive: "Use the Popen module with shell=False to avoid the common security issues involved in using unsanitized input from untrusted sources..."

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

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

From report at bugs.python.org  Thu Dec  4 02:52:05 2014
From: report at bugs.python.org (Josh Rosenberg)
Date: Thu, 04 Dec 2014 01:52:05 +0000
Subject: [docs] [issue20692] Tutorial and FAQ: how to call a method on an int
In-Reply-To: <1392850224.09.0.571764135364.issue20692@psf.upfronthosting.co.za>
Message-ID: <1417657925.84.0.26845379277.issue20692@psf.upfronthosting.co.za>


Changes by Josh Rosenberg <shadowranger+python at gmail.com>:


----------
nosy: +josh.r

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

From report at bugs.python.org  Thu Dec  4 06:56:10 2014
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 04 Dec 2014 05:56:10 +0000
Subject: [docs] [issue16893] Generate Idle help from Doc/library/idle.rst
In-Reply-To: <1357663512.19.0.739336896498.issue16893@psf.upfronthosting.co.za>
Message-ID: <20141204055607.95980.11946@psf.io>


Roundup Robot added the comment:

New changeset 6db65ff985b6 by Terry Jan Reedy in branch '3.4':
Issue #16893: For Idle doc, move index entries, copy no-subprocess section
https://hg.python.org/cpython/rev/6db65ff985b6

New changeset feec1ea55127 by Terry Jan Reedy in branch '2.7':
Issue #16893: Update 2.7 version of Idle doc to match 3.4 doc as of the just
https://hg.python.org/cpython/rev/feec1ea55127

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

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

From report at bugs.python.org  Thu Dec  4 18:10:19 2014
From: report at bugs.python.org (Simeon Visser)
Date: Thu, 04 Dec 2014 17:10:19 +0000
Subject: [docs] [issue22997] Minor improvements to "Functional API" section
	of Enum	documentation
Message-ID: <1417713019.92.0.36560038902.issue22997@psf.upfronthosting.co.za>


New submission from Simeon Visser:

This patch contributes two changes to the "Functional API" section of the Enum documentation:

- Early in the section it mentions four different ways of creating an Enum but later it only lists three different ways (the "sequence of names" approach wasn't listed anymore).

- The use of "Animal" and "Animals" wasn't consistent.

This issue is mainly to test my ability to make a (trivial) patch.

----------
assignee: docs at python
components: Documentation
messages: 232142
nosy: docs at python, simeon.visser
priority: normal
severity: normal
status: open
title: Minor improvements to "Functional API" section of Enum documentation
type: enhancement
versions: Python 3.5

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

From report at bugs.python.org  Thu Dec  4 18:11:27 2014
From: report at bugs.python.org (Simeon Visser)
Date: Thu, 04 Dec 2014 17:11:27 +0000
Subject: [docs] [issue22997] Minor improvements to "Functional API" section
	of Enum	documentation
In-Reply-To: <1417713019.92.0.36560038902.issue22997@psf.upfronthosting.co.za>
Message-ID: <1417713087.91.0.25550823071.issue22997@psf.upfronthosting.co.za>


Changes by Simeon Visser <simeon87 at gmail.com>:


----------
keywords: +patch
Added file: http://bugs.python.org/file37360/issue22997.patch

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

From report at bugs.python.org  Thu Dec  4 18:14:20 2014
From: report at bugs.python.org (Ethan Furman)
Date: Thu, 04 Dec 2014 17:14:20 +0000
Subject: [docs] [issue22997] Minor improvements to "Functional API" section
	of Enum	documentation
In-Reply-To: <1417713019.92.0.36560038902.issue22997@psf.upfronthosting.co.za>
Message-ID: <1417713260.17.0.528640732675.issue22997@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/issue22997>
_______________________________________

From report at bugs.python.org  Thu Dec  4 18:20:48 2014
From: report at bugs.python.org (Ethan Furman)
Date: Thu, 04 Dec 2014 17:20:48 +0000
Subject: [docs] [issue22997] Minor improvements to "Functional API" section
	of Enum	documentation
In-Reply-To: <1417713019.92.0.36560038902.issue22997@psf.upfronthosting.co.za>
Message-ID: <1417713648.31.0.420918754101.issue22997@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Simeon, the patch looks decent; I'll review it more carefully later.

If you are going to contribute non-trivial patches, you'll need to sign the CLA:  https://www.python.org/psf/contrib/contrib-form/ .

Thanks for helping!

----------

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

From report at bugs.python.org  Thu Dec  4 18:26:17 2014
From: report at bugs.python.org (Kali Kaneko)
Date: Thu, 04 Dec 2014 17:26:17 +0000
Subject: [docs] [issue22987] ssl module documentation: incorrect
	compatibility matrix
In-Reply-To: <1417612558.33.0.597958584531.issue22987@psf.upfronthosting.co.za>
Message-ID: <1417713977.76.0.909690881711.issue22987@psf.upfronthosting.co.za>


Kali Kaneko added the comment:

my bad, I had not actually tested the sslv2 and sslv3 options, since they were not available in the python in debian sid.

thanks for the quick fix!

----------

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

From report at bugs.python.org  Fri Dec  5 15:11:20 2014
From: report at bugs.python.org (Brett Cannon)
Date: Fri, 05 Dec 2014 14:11:20 +0000
Subject: [docs] [issue22394] Update documentation building to use venv and
	pip
In-Reply-To: <1410532646.93.0.821580086561.issue22394@psf.upfronthosting.co.za>
Message-ID: <1417788680.07.0.180805589311.issue22394@psf.upfronthosting.co.za>


Changes by Brett Cannon <brett at python.org>:


----------
assignee: georg.brandl -> brett.cannon

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

From report at bugs.python.org  Fri Dec  5 16:29:30 2014
From: report at bugs.python.org (R. David Murray)
Date: Fri, 05 Dec 2014 15:29:30 +0000
Subject: [docs] [issue22581] Other mentions of the buffer protocol
In-Reply-To: <1412785100.97.0.773176507587.issue22581@psf.upfronthosting.co.za>
Message-ID: <1417793370.54.0.631171882867.issue22581@psf.upfronthosting.co.za>


R. David Murray added the comment:

Made some review comments.  The last comment change (deletion) in unicodeobject.c is not as obvious as the other changes were; I'm not familiar enough with the C API to know why it is correct.  I trust you on that, though :)

----------

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

From report at bugs.python.org  Fri Dec  5 17:25:03 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 05 Dec 2014 16:25:03 +0000
Subject: [docs] [issue22581] Other mentions of the buffer protocol
In-Reply-To: <1412785100.97.0.773176507587.issue22581@psf.upfronthosting.co.za>
Message-ID: <1417796702.95.0.131301349919.issue22581@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Thank you David.

I have left enumerations of concrete bytes-like classes (bytes and bytearray) because I thought that it is good to be more verbose in the documentation. I left the decision how write it to you: ":class:`bytes`, :class:`bytearray` or :term:`bytes-like object`", ":term:`bytes-like object` such as :class:`bytes` and :class:`bytearray`", or just ":term:`bytes-like object`".

I don't understand your comment about unicodeobject.c. This change doesn't differ from others. May be you mean unicodeobject.h? Yes, "char buffer" is Python 2 term and doesn't make sense in 3.x.

----------

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

From report at bugs.python.org  Fri Dec  5 17:47:45 2014
From: report at bugs.python.org (R. David Murray)
Date: Fri, 05 Dec 2014 16:47:45 +0000
Subject: [docs] [issue22581] Other mentions of the buffer protocol
In-Reply-To: <1412785100.97.0.773176507587.issue22581@psf.upfronthosting.co.za>
Message-ID: <1417798065.38.0.89272709535.issue22581@psf.upfronthosting.co.za>


R. David Murray added the comment:

Yeah, just ignore the unicodeobject.c comment comment.

It seems to me that the stuff in the parens is supposed to be a precise description of what the format code handles, with elaboration in the following text.  So I'd prefer to just use the :term: in those lists.  But like I said I'm not that familiar with the C api, so I'm not sure how much weight my opinion should carry :)  

The biggest thing is consistency.  If you want to keep all of them in the list, I'd favor the "such as" formulation.

----------

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

From report at bugs.python.org  Fri Dec  5 21:17:47 2014
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 05 Dec 2014 20:17:47 +0000
Subject: [docs] [issue22394] Update documentation building to use venv and
	pip
In-Reply-To: <1410532646.93.0.821580086561.issue22394@psf.upfronthosting.co.za>
Message-ID: <20141205201742.73388.84127@psf.io>


Roundup Robot added the comment:

New changeset 888103600e72 by Brett Cannon in branch 'default':
Issue #22394: Add a 'venv' command to Doc/Makefile.
https://hg.python.org/cpython/rev/888103600e72

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

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

From report at bugs.python.org  Fri Dec  5 21:18:01 2014
From: report at bugs.python.org (Brett Cannon)
Date: Fri, 05 Dec 2014 20:18:01 +0000
Subject: [docs] [issue22394] Update documentation building to use venv and
	pip
In-Reply-To: <1410532646.93.0.821580086561.issue22394@psf.upfronthosting.co.za>
Message-ID: <1417810681.27.0.90062747151.issue22394@psf.upfronthosting.co.za>


Changes by Brett Cannon <brett at python.org>:


----------
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

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

From report at bugs.python.org  Fri Dec  5 21:30:51 2014
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 05 Dec 2014 20:30:51 +0000
Subject: [docs] [issue22581] Other mentions of the buffer protocol
In-Reply-To: <1412785100.97.0.773176507587.issue22581@psf.upfronthosting.co.za>
Message-ID: <20141205203037.27495.40177@psf.io>


Roundup Robot added the comment:

New changeset 853e3e115db4 by Serhiy Storchaka in branch '3.4':
Issue #22581: Use more "bytes-like object" throughout the docs and comments.
https://hg.python.org/cpython/rev/853e3e115db4

New changeset 450a025b1669 by Serhiy Storchaka in branch 'default':
Issue #22581: Use more "bytes-like object" throughout the docs and comments.
https://hg.python.org/cpython/rev/450a025b1669

----------

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

From report at bugs.python.org  Fri Dec  5 21:35:28 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 05 Dec 2014 20:35:28 +0000
Subject: [docs] [issue22581] Other mentions of the buffer protocol
In-Reply-To: <1412785100.97.0.773176507587.issue22581@psf.upfronthosting.co.za>
Message-ID: <1417811728.78.0.750723737816.issue22581@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Committed with just "bytes-like object". Thank you David for your review.

----------

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

From report at bugs.python.org  Fri Dec  5 21:36:17 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Fri, 05 Dec 2014 20:36:17 +0000
Subject: [docs] [issue22581] Other mentions of the buffer protocol
In-Reply-To: <1412785100.97.0.773176507587.issue22581@psf.upfronthosting.co.za>
Message-ID: <1417811777.59.0.701342337452.issue22581@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

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

From report at bugs.python.org  Fri Dec  5 22:33:59 2014
From: report at bugs.python.org (STINNER Victor)
Date: Fri, 05 Dec 2014 21:33:59 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417815239.94.0.830089391319.issue21557@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/issue21557>
_______________________________________

From report at bugs.python.org  Fri Dec  5 22:37:40 2014
From: report at bugs.python.org (STINNER Victor)
Date: Fri, 05 Dec 2014 21:37:40 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417815460.63.0.113242150461.issue21557@psf.upfronthosting.co.za>


STINNER Victor added the comment:

Python 3.5 doc has no red warning in the subprocess module, but a nice section:
https://docs.python.org/dev/library/subprocess.html#security-considerations

Why not simply copying the note of the subprocess doc?
"Note: Read the Security Considerations section before using shell=True."

----------

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

From report at bugs.python.org  Fri Dec  5 22:38:35 2014
From: report at bugs.python.org (STINNER Victor)
Date: Fri, 05 Dec 2014 21:38:35 +0000
Subject: [docs] [issue21557] os.popen & os.system lack shell-related
	security warnings
In-Reply-To: <1400794428.31.0.170474236819.issue21557@psf.upfronthosting.co.za>
Message-ID: <1417815515.31.0.162604296255.issue21557@psf.upfronthosting.co.za>


STINNER Victor added the comment:

subprocess.getstatusoutput(cmd) needs also this note (or warning).

----------

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

From report at bugs.python.org  Fri Dec  5 23:51:03 2014
From: report at bugs.python.org (Martin Panter)
Date: Fri, 05 Dec 2014 22:51:03 +0000
Subject: [docs] [issue22989] HTTPResponse.msg not as documented
In-Reply-To: <1417632317.82.0.906874710781.issue22989@psf.upfronthosting.co.za>
Message-ID: <1417819863.55.0.702333447273.issue22989@psf.upfronthosting.co.za>


Martin Panter added the comment:

See Issue 21228 for a patch which documents the ?.msg? hack, and that the info() method is available for HTTP responses.

I think documenting the ?.headers? attribute would be a bad idea, because it is introducing yet another way to do what the almost-documented info() method already does.

----------
nosy: +vadmium

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

From report at bugs.python.org  Sat Dec  6 00:32:59 2014
From: report at bugs.python.org (Berker Peksag)
Date: Fri, 05 Dec 2014 23:32:59 +0000
Subject: [docs] [issue21228] Missing enumeration of HTTPResponse Objects
	methods of	urllib.request.urlopen's http.client.HTTPResponse?
In-Reply-To: <1397520483.48.0.224250148615.issue21228@psf.upfronthosting.co.za>
Message-ID: <1417822379.9.0.152584394625.issue21228@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


----------
nosy: +berker.peksag
stage:  -> patch review
versions:  -Python 3.2, Python 3.3

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

From report at bugs.python.org  Sat Dec  6 00:53:07 2014
From: report at bugs.python.org (Martin Panter)
Date: Fri, 05 Dec 2014 23:53:07 +0000
Subject: [docs] [issue22153] Documentation of TestCase.runTest is incorrect
	and	confusing
In-Reply-To: <1407301202.17.0.719208246986.issue22153@psf.upfronthosting.co.za>
Message-ID: <1417823587.7.0.76562915989.issue22153@psf.upfronthosting.co.za>


Martin Panter added the comment:

Updated patch with indentation fixed and new wording. I am just guessing the RST syntax based on the surrounding text, so please review :)

----------
Added file: http://bugs.python.org/file37372/runtest.patch

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

From report at bugs.python.org  Sat Dec  6 02:26:51 2014
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 06 Dec 2014 01:26:51 +0000
Subject: [docs] [issue16893] Generate Idle help from Doc/library/idle.rst
In-Reply-To: <1357663512.19.0.739336896498.issue16893@psf.upfronthosting.co.za>
Message-ID: <20141206012641.27511.2487@psf.io>


Roundup Robot added the comment:

New changeset 283c364c372a by Terry Jan Reedy in branch '2.7':
Issue #16893: Update Idle doc chapter to match current Idle and add new
https://hg.python.org/cpython/rev/283c364c372a

New changeset 2fc341c6e314 by Terry Jan Reedy in branch '3.4':
Issue #16893: Update Idle doc chapter to match current Idle and add new
https://hg.python.org/cpython/rev/2fc341c6e314

----------

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

From report at bugs.python.org  Sat Dec  6 02:32:18 2014
From: report at bugs.python.org (R. David Murray)
Date: Sat, 06 Dec 2014 01:32:18 +0000
Subject: [docs] [issue22998] inspect.Signature and default arguments
In-Reply-To: <1417724041.66.0.201313804397.issue22998@psf.upfronthosting.co.za>
Message-ID: <1417829538.21.0.754195135155.issue22998@psf.upfronthosting.co.za>


R. David Murray added the comment:

I'm good with your solution, but I'm going to adjust the resolution by changing the component :)

----------
assignee:  -> docs at python
components: +Documentation -Library (Lib)
nosy: +docs at python
resolution: wont fix -> fixed
stage:  -> resolved

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

From report at bugs.python.org  Sat Dec  6 17:31:43 2014
From: report at bugs.python.org (Berker Peksag)
Date: Sat, 06 Dec 2014 16:31:43 +0000
Subject: [docs] [issue22153] Documentation of TestCase.runTest is incorrect
	and	confusing
In-Reply-To: <1407301202.17.0.719208246986.issue22153@psf.upfronthosting.co.za>
Message-ID: <1417883503.02.0.208804555406.issue22153@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


----------
nosy: +berker.peksag
stage: patch review -> commit review

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

From report at bugs.python.org  Sun Dec  7 00:58:20 2014
From: report at bugs.python.org (Martin Panter)
Date: Sat, 06 Dec 2014 23:58:20 +0000
Subject: [docs] [issue22153] Documentation of TestCase.runTest is incorrect
	and	confusing
In-Reply-To: <1407301202.17.0.719208246986.issue22153@psf.upfronthosting.co.za>
Message-ID: <1417910300.23.0.797109348929.issue22153@psf.upfronthosting.co.za>


Martin Panter added the comment:

Updated patch, which applies to current tip of the default branch, and includes the formatting fix. Also including a version that applies to the 3.4 branch. Alternatively, if you patch the 3.4 branch it looks like merging to default automatically gives the correct result.

----------
Added file: http://bugs.python.org/file37376/runTest2-default.patch

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

From report at bugs.python.org  Sun Dec  7 00:58:33 2014
From: report at bugs.python.org (Martin Panter)
Date: Sat, 06 Dec 2014 23:58:33 +0000
Subject: [docs] [issue22153] Documentation of TestCase.runTest is incorrect
	and	confusing
In-Reply-To: <1407301202.17.0.719208246986.issue22153@psf.upfronthosting.co.za>
Message-ID: <1417910313.37.0.296054692106.issue22153@psf.upfronthosting.co.za>


Changes by Martin Panter <vadmium+py at gmail.com>:


Added file: http://bugs.python.org/file37377/runTest2-3.4.patch

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

From report at bugs.python.org  Sun Dec  7 19:54:32 2014
From: report at bugs.python.org (Ned Deily)
Date: Sun, 07 Dec 2014 18:54:32 +0000
Subject: [docs] [issue23005] typos on heapq doc
In-Reply-To: <1417978054.94.0.0217424241667.issue23005@psf.upfronthosting.co.za>
Message-ID: <1417978472.59.0.845778126779.issue23005@psf.upfronthosting.co.za>


Changes by Ned Deily <nad at acm.org>:


----------
assignee:  -> docs at python
components: +Documentation -Library (Lib)
nosy: +docs at python -ned.deily
versions:  -Python 3.2, Python 3.3

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

From report at bugs.python.org  Sun Dec  7 21:02:51 2014
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 07 Dec 2014 20:02:51 +0000
Subject: [docs] [issue9536] defaultdict doc makes incorrect reference to
	__missing__	method
In-Reply-To: <1281106528.37.0.0435364267174.issue9536@psf.upfronthosting.co.za>
Message-ID: <1417982571.96.0.645152320475.issue9536@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/issue9536>
_______________________________________

From report at bugs.python.org  Sun Dec  7 21:49:30 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sun, 07 Dec 2014 20:49:30 +0000
Subject: [docs] [issue23006] Improve the doc and indexing of
	adict.__missing__.
Message-ID: <1417985369.96.0.326358204226.issue23006@psf.upfronthosting.co.za>


New submission from Terry J. Reedy:

Currently, the only index entry for __missing__ is  "__missing__() (collections.defaultdict method)".  This entry should probably not exist -- see #9536, which inspired this issue.  The method is not mentioned in the special-methods doc, and the explanation in the dict doc is not indexed.  Two suggestions:

https://docs.python.org/3/reference/datamodel.html#emulating-container-types

After __getitem__ entry, add automatically indexed entry, something like 

object.__missing__(self, key):
   When present in a dict subclass, called by dict.__getitem__ for missing keys.

https://docs.python.org/3/library/stdtypes.html#mapping-types-dict

Before the d[key] paragraph starting "If a subclass of dict defines a method __missing__()" add explicit __missing__ index directive.  The last sentence of the paragraph

"See collections.Counter for a complete implementation including other methods helpful for accumulating and managing tallies."

is confusing because the linked entry makes no mention of __missing__ (as it should not).  Change sentence to something like

"There are two stdlib dict subclasses that use (different) __missing__ methods as part of their implementation: collections.Counter and collections.defaultdict."

I will work on a patch and try to get the markup correct.

----------
assignee: docs at python
components: Documentation
messages: 232279
nosy: docs at python, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Improve the doc and indexing of adict.__missing__.
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5

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

From report at bugs.python.org  Sun Dec  7 22:02:30 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sun, 07 Dec 2014 21:02:30 +0000
Subject: [docs] [issue9536] defaultdict doc makes incorrect reference to
	__missing__	method
In-Reply-To: <1281106528.37.0.0435364267174.issue9536@psf.upfronthosting.co.za>
Message-ID: <1417986150.74.0.497588278431.issue9536@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

I agree that the patch is not acceptable as is.  The public attribute *defaultdict* should be explicitly documented as it is now, so that it is indexed.  On the other hand, users should not directly call .__missing__, and it is not normal to document the private special method implementation of classes. For example, a collections.Counter returns 0 for missing keys but the doc makes no mention of .__missing__ as the implementation.  It simply describe how a counter works.

John is correct that people writing other subclasses with __missing__ should usually subclass dict.  This might be clearer if that special method were properly documented and indexed.  I opened #23006 for this.

----------
nosy: +terry.reedy
resolution: not a bug -> 
stage: resolved -> needs patch

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

From report at bugs.python.org  Sun Dec  7 23:07:33 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sun, 07 Dec 2014 22:07:33 +0000
Subject: [docs] [issue23006] Improve the doc and indexing of
	adict.__missing__.
In-Reply-To: <1417985369.96.0.326358204226.issue23006@psf.upfronthosting.co.za>
Message-ID: <1417990053.97.0.0825161240939.issue23006@psf.upfronthosting.co.za>


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


----------
keywords: +patch
Added file: http://bugs.python.org/file37383/__missing__.diff

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

From report at bugs.python.org  Sun Dec  7 23:17:54 2014
From: report at bugs.python.org (Ethan Furman)
Date: Sun, 07 Dec 2014 22:17:54 +0000
Subject: [docs] [issue23006] Improve the doc and indexing of
	adict.__missing__.
In-Reply-To: <1417985369.96.0.326358204226.issue23006@psf.upfronthosting.co.za>
Message-ID: <1417990674.07.0.426409464752.issue23006@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/issue23006>
_______________________________________

From gdreynolds at gmail.com  Wed Dec  3 11:28:55 2014
From: gdreynolds at gmail.com (Glenn Reynolds)
Date: Wed, 3 Dec 2014 18:28:55 +0800
Subject: [docs] Docs for 2.7.9
Message-ID: <CANKd2gxSa+mk_nT_p4ZZsOOPes_eHUrE4CTSpDjLaRZbZQhP_A@mail.gmail.com>

Hi!


All PDF and HTML links (A4/Letter, zip/bz2)are giving me 404s.



Cheers

Glenn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141203/00c607b4/attachment-0001.html>

From demianbrecht at gmail.com  Wed Dec  3 19:05:12 2014
From: demianbrecht at gmail.com (demianbrecht at gmail.com)
Date: Wed, 03 Dec 2014 18:05:12 -0000
Subject: [docs] os.popen & os.system lack shell-related security
	warnings (issue 21557)
Message-ID: <20141203180512.15416.40019@psf.upfronthosting.co.za>

I stand corrected, the patched docs do look good and are consistent with
the warning in "Frequently Used Arguments" section in the subprocess
module docs. Just a minor point about linking to subprocess.Popen rather
than the subprocess module.


http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst
File Doc/library/os.rst (right):

http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode2905
Doc/library/os.rst:2905: .. warning::
Fair points. I also hadn't previously seen the warning in the frequently
used arguments section
(https://docs.python.org/2/library/subprocess.html#frequently-used-arguments)
and do like that this is consistent with it.

http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode2913
Doc/library/os.rst:2913: For greater safety, consider using
:mod:`subprocess` with
This should point to subprocess.Popen
(https://docs.python.org/2/library/subprocess.html#subprocess.Popen)
rather than the module, no?

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

From pybugs at rebertia.com  Wed Dec  3 20:45:43 2014
From: pybugs at rebertia.com (pybugs at rebertia.com)
Date: Wed, 03 Dec 2014 19:45:43 -0000
Subject: [docs] os.popen & os.system lack shell-related security
	warnings (issue 21557)
Message-ID: <20141203194543.15415.11765@psf.upfronthosting.co.za>


http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst
File Doc/library/os.rst (right):

http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode2913
Doc/library/os.rst:2913: For greater safety, consider using
:mod:`subprocess` with
On 2014/12/03 19:05:13, demian wrote:
> This should point to subprocess.Popen
> (https://docs.python.org/2/library/subprocess.html#subprocess.Popen)
rather than
> the module, no?

The subprocess module's convenience functions (subprocess.call(), etc.)
are also reasonable alternatives, so I just referred to the entire
subprocess module generally.

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

From turakdoruk at windowslive.com  Thu Dec  4 22:20:16 2014
From: turakdoruk at windowslive.com (Doruk Turak)
Date: Thu, 4 Dec 2014 23:20:16 +0200
Subject: [docs] Download links not working for documentation of 2.7.
Message-ID: <DUB126-W775ED53C83582B94C621CAC2780@phx.gbl>

Hello there.
Title sums it all up. 404 not found.
Looking forward to a solution for this, I genuinely need the docs to be on my phone.
Best regards, Thanks in advance! 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141204/4e037538/attachment-0001.html>

From archarachne at gmail.com  Thu Dec  4 23:08:19 2014
From: archarachne at gmail.com (archarachne)
Date: Thu, 4 Dec 2014 23:08:19 +0100
Subject: [docs] Download: 404 Not Found
Message-ID: <CAJO4eRKUsbLPVL8fhkaPgCMbUgpyj5R_pP=xSU7vbSAM0xyeMQ@mail.gmail.com>

Hello!

When trying to download the docs from
https://docs.python.org/2/download.html I get 404 for every file I
choose. Is it temporary?

Katherine Ostrowicz
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141204/b38fa923/attachment-0001.html>

From jwarren116 at gmail.com  Fri Dec  5 06:28:38 2014
From: jwarren116 at gmail.com (James Warren)
Date: Thu, 04 Dec 2014 21:28:38 -0800
Subject: [docs] Download Python Docs 2.7
Message-ID: <54814286.7040300@gmail.com>

Good evening!

I was attempting to download the Docs for 2.7 but all the files seem to 
be missing. Just a heads up! Link to one of the missing files:

https://docs.python.org/2/archives/python-2.7.9rc1-docs-pdf-letter.tar.bz2

James

From rdmurray at bitdance.com  Fri Dec  5 16:26:34 2014
From: rdmurray at bitdance.com (rdmurray at bitdance.com)
Date: Fri, 05 Dec 2014 15:26:34 -0000
Subject: [docs] Other mentions of the buffer protocol (issue 22581)
Message-ID: <20141205152634.15385.80152@psf.upfronthosting.co.za>


http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst
File Doc/c-api/arg.rst (right):

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode73
Doc/c-api/arg.rst:73: ``s*`` (:class:`str`, :class:`bytes`,
:class:`bytearray` or :term:`bytes-like object`) [Py_buffer]
bytes and bytearray are bytes-like object, so wouldn't it be better to
just say :class:`str` or :term:`bytes-like object`?

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode79
Doc/c-api/arg.rst:79: ``s#`` (:class:`str`, :class:`bytes` or read-only
:term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`]
again, drop :class:`bytes`?  Or, since 'read-only' is a restriction on
bytes-like object that I don't think is covered in the description of
the term, perhaps it should say "read-only :term:`bytes-like object`
such as :class:`bytes`".

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode90
Doc/c-api/arg.rst:90: ``z*`` (:class:`str`, :class:`bytes`,
:class:`bytearray`, :term:`bytes-like object` or ``None``) [Py_buffer]
as above

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode94
Doc/c-api/arg.rst:94: ``z#`` (:class:`str`, :class:`bytes`, read-only
:term:`bytes-like object` or ``None``) [const char \*, int]
as above

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode98
Doc/c-api/arg.rst:98: ``y`` (:class:`bytes` or read-only
:term:`bytes-like object`) [const char \*]
as above

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode104
Doc/c-api/arg.rst:104: ``y*`` (:class:`bytes`, :class:`bytearray` or
:term:`bytes-like object`) [Py_buffer]
as above

http://bugs.python.org/review/22581/diff/13303/Doc/c-api/arg.rst#newcode109
Doc/c-api/arg.rst:109: ``y#`` (:class:`bytes` or read-only
:term:`bytes-like object`) [const char \*, int]
as above

http://bugs.python.org/review/22581/diff/13303/Doc/library/socket.rst
File Doc/library/socket.rst (right):

http://bugs.python.org/review/22581/diff/13303/Doc/library/socket.rst#newcode1126
Doc/library/socket.rst:1126: non-ancillary data as an iterable of
bytes-like objects
missing :term:

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

From curious000cat at gmail.com  Sat Dec  6 10:42:48 2014
From: curious000cat at gmail.com (curious cat)
Date: Sat, 6 Dec 2014 17:42:48 +0800
Subject: [docs] Broken Documenation Download Link
Message-ID: <CAKO8=nmabNzET1vZMY9Ja1Pi0tb+_xo=E4HbsWKV5z_28rH3cA@mail.gmail.com>

Hi!


Seems like this link is not working..none of the other links as well. Is
there any other way I can download the documentation?

[image: Inline image 1]

Thanks!

curiousCat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141206/e7c03d1b/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image.png
Type: image/png
Size: 35887 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/docs/attachments/20141206/e7c03d1b/attachment-0001.png>

From berker.peksag at gmail.com  Sat Dec  6 17:31:20 2014
From: berker.peksag at gmail.com (berker.peksag at gmail.com)
Date: Sat, 06 Dec 2014 16:31:20 -0000
Subject: [docs] There is no standard TestCase.runTest implementation
	(issue 22153)
Message-ID: <20141206163120.15385.94687@psf.upfronthosting.co.za>

LGTM.


http://bugs.python.org/review/22153/diff/13362/Doc/library/unittest.rst
File Doc/library/unittest.rst (right):

http://bugs.python.org/review/22153/diff/13362/Doc/library/unittest.rst#newcode1561
Doc/library/unittest.rst:1561: A test case instance is created for each
method named by
This part does not apply to the correct place:

    $ hg imp --no-c http://bugs.python.org/file37372/runtest.patch
    applying http://bugs.python.org/file37372/runtest.patch
    patching file Doc/library/unittest.rst
    Hunk #2 succeeded at 1554 with fuzz 2 (offset -6 lines).
    applied to working directory

And here is the output of "hg diff":

    :class:`TestLoader` objects have the following attributes:
 
+      A test case instance is created for each method named by
+      :meth:`getTestCaseNames`. By default these are the method names
+      beginning with *test*. If :meth:`getTestCaseNames` returns no
methods,
+      but the :meth:`runTest` method is implemented, a single test case
is
+      created for that method instead.
 
    .. attribute:: errors

http://bugs.python.org/review/22153/diff/13362/Doc/library/unittest.rst#newcode1563
Doc/library/unittest.rst:1563: beginning with *test*. If
:meth:`getTestCaseNames` returns no methods,
*test* -> ``test``

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

From fong.ch75 at gmail.com  Sat Dec  6 21:52:26 2014
From: fong.ch75 at gmail.com (Christine Fong)
Date: Sat, 6 Dec 2014 21:52:26 +0100
Subject: [docs] Doc files not found
Message-ID: <CAB=iT1CmsYHp8YtVCo8rch45-CjyUhJjTm56RFGA4xn8Gi-nAg@mail.gmail.com>

Hi,

I wanted to download documentation files for Python 2 (here
<https://docs.python.org/2/download.html>), but found that the links are
broken (404 Not Found).

Thanks
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141206/97c49282/attachment.html>

From report at bugs.python.org  Mon Dec  8 15:08:55 2014
From: report at bugs.python.org (berndca)
Date: Mon, 08 Dec 2014 14:08:55 +0000
Subject: [docs] [issue23011] Duplicate Paragraph in documentation for json
	module
Message-ID: <1418047735.37.0.83441849339.issue23011@psf.upfronthosting.co.za>


New submission from berndca:

There is a duplication of the first section of 18.2.2 (JSON) Encoders and Decoders of the python 2.7.9RC1 doc as well of the corresponding paragraph in 19.2.2 of the Python 3 docs.

----------
assignee: docs at python
components: Documentation
messages: 232303
nosy: berndca, docs at python
priority: normal
severity: normal
status: open
title: Duplicate Paragraph in documentation for json module
type: enhancement
versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5

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

From report at bugs.python.org  Mon Dec  8 15:20:10 2014
From: report at bugs.python.org (Simeon Visser)
Date: Mon, 08 Dec 2014 14:20:10 +0000
Subject: [docs] [issue23011] Duplicate Paragraph in documentation for json
	module
In-Reply-To: <1418047735.37.0.83441849339.issue23011@psf.upfronthosting.co.za>
Message-ID: <1418048410.64.0.955397709896.issue23011@psf.upfronthosting.co.za>


Simeon Visser added the comment:

What paragraph are you referring to? Various documented parameters are similar but I don't see duplicate paragraphs.

----------
nosy: +simeon.visser

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

From report at bugs.python.org  Mon Dec  8 22:29:34 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Mon, 08 Dec 2014 21:29:34 +0000
Subject: [docs] [issue19164] Update uuid.UUID TypeError exception: integer
	should not	be an argument.
In-Reply-To: <1380885490.13.0.480584034262.issue19164@psf.upfronthosting.co.za>
Message-ID: <1418074174.13.0.184505888629.issue19164@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
keywords: +needs review
stage: needs patch -> patch review
versions: +Python 3.4, Python 3.5

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

From report at bugs.python.org  Tue Dec  9 09:09:41 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 09 Dec 2014 08:09:41 +0000
Subject: [docs] [issue23006] Improve the doc and indexing of
	adict.__missing__.
In-Reply-To: <1417985369.96.0.326358204226.issue23006@psf.upfronthosting.co.za>
Message-ID: <1418112581.66.0.632451375676.issue23006@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

These edits look reasonable, useful and correct.

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

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

From report at bugs.python.org  Tue Dec  9 09:52:07 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 09 Dec 2014 08:52:07 +0000
Subject: [docs] [issue23005] typos on heapq doc
In-Reply-To: <1417978054.94.0.0217424241667.issue23005@psf.upfronthosting.co.za>
Message-ID: <1418115126.96.0.311662685028.issue23005@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

This change looks reasonable and correct.

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

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

From report at bugs.python.org  Tue Dec  9 11:09:15 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 09 Dec 2014 10:09:15 +0000
Subject: [docs] [issue9536] defaultdict doc makes incorrect reference to
	__missing__	method
In-Reply-To: <1281106528.37.0.0435364267174.issue9536@psf.upfronthosting.co.za>
Message-ID: <1418119755.16.0.313799366707.issue9536@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

[John Posner]
> The fact is that a programmer using defaultdict does not need 
> to know anything about __missing__.

I disagree.  It seems to help people understand the defaultdict which otherwise seems more magical that it actually is.  Also, it is a part of the description of how the default_factory attribute is used.  Further, it helps explain why the factory is only called by __getitem__ rather than by get() or other methods.



[David Murray]
> I believe the description of __missing__ is there for those who 
> want to subclass defaultdict, but I'll let Raymond confirm.

Yes, it serves that purpose but it also serves to make clear what the actual mechanics are for the defaultdict.   I think there is no downside to keeping the current wording which provides some insights and hasn't seemed to cause any problems in practice (this has been around since Python 2.5).

Terry's proposed changes in issue 23006 do seem like a good idea.

I recommend against OP's proposed patch or any variant of it.  That patch is predicated on the notion that __missing__ is an irrelevant, unnecessary, and confusing implementation detail.  I don't agree that sentiment at all.

Please keep in mind that this part of the documentation was written by Guido van Rossum and it clearly expresses what he had it mind when he implemented the defaultdict back in 2006.  I really don't think we should throw away this text because 8 or 9 years later John has opined that Guido was fundamentally misguided when he wrote the documentation (back in the days when the docs were all in TeX markup).

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

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

From report at bugs.python.org  Tue Dec  9 11:18:56 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 09 Dec 2014 10:18:56 +0000
Subject: [docs] [issue22918] Doc for __iter__ makes inexact comment
	about	dict.__iter__
In-Reply-To: <1416689379.36.0.290921977035.issue22918@psf.upfronthosting.co.za>
Message-ID: <1418120336.47.0.838319993149.issue22918@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

> I think the first half of the sentence is enough: 
> ?For mappings, it should iterate over the keys of the container.?

That should do it :-)

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

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

From report at bugs.python.org  Tue Dec  9 11:42:44 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 09 Dec 2014 10:42:44 +0000
Subject: [docs] [issue9536] defaultdict doc makes incorrect reference to
	__missing__	method
In-Reply-To: <1281106528.37.0.0435364267174.issue9536@psf.upfronthosting.co.za>
Message-ID: <1418121764.61.0.0884764329105.issue9536@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

http://svn.python.org/view/python/branches/release25-maint/Doc/lib/libcollections.tex?r1=38658&r2=42573

----------

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

From report at bugs.python.org  Tue Dec  9 14:33:49 2014
From: report at bugs.python.org (=?utf-8?q?Walter_D=C3=B6rwald?=)
Date: Tue, 09 Dec 2014 13:33:49 +0000
Subject: [docs] [issue22998] inspect.Signature and default arguments
In-Reply-To: <1417724041.66.0.201313804397.issue22998@psf.upfronthosting.co.za>
Message-ID: <1418132029.44.0.11153520637.issue22998@psf.upfronthosting.co.za>


Walter D?rwald added the comment:

The updated code in the documentation still doesn't set the * and ** parameters. I would have preferred the following code:

  for param in sig.parameters.values():
    if param.name not in ba.arguments:
      if param.kind is inspect.Parameter.VAR_POSITIONAL:
        default = ()
      elif param.kind is inspect.Parameter.VAR_KEYWORD:
        default = {}
      else:
        default = param.default
      ba.arguments[param.name] = default

----------

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

From report at bugs.python.org  Tue Dec  9 16:14:34 2014
From: report at bugs.python.org (R. David Murray)
Date: Tue, 09 Dec 2014 15:14:34 +0000
Subject: [docs] [issue23017] string.printable.isprintable() returns False
In-Reply-To: <1418097121.16.0.891016494417.issue23017@psf.upfronthosting.co.za>
Message-ID: <1418138074.52.0.237452082674.issue23017@psf.upfronthosting.co.za>


R. David Murray added the comment:

This is a bit of a conundrum.  Our (string module) definition of printable is very clear, and it includes the other whitespace characters.

We could document that this does not match the posix definition of printable.  It also does not match the RFC 5822 definition of printable (for example), which does *not* include whitespace characters (not even space), but the posix definition is a more likely source of confusion.

isprintable is a newer function than string.printable, and serves a different purpose.  I suppose that when PEP 3138 was written and implemented the disconnect between the two definitions was not noticed.

For backward compatibility reasons I suspect we are stuck with the discrepancy, but perhaps others will think it worth the pain of changing string.printable.  I kind of doubt it, though.

----------
assignee:  -> docs at python
components: +Documentation
nosy: +docs at python, r.david.murray

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

From report at bugs.python.org  Tue Dec  9 16:38:49 2014
From: report at bugs.python.org (STINNER Victor)
Date: Tue, 09 Dec 2014 15:38:49 +0000
Subject: [docs] [issue23017] string.printable.isprintable() returns False
In-Reply-To: <1418097121.16.0.891016494417.issue23017@psf.upfronthosting.co.za>
Message-ID: <1418139529.34.0.192853549267.issue23017@psf.upfronthosting.co.za>


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


----------
components: +Unicode
nosy: +ezio.melotti, haypo

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

From report at bugs.python.org  Tue Dec  9 18:45:54 2014
From: report at bugs.python.org (Pablo Aguiar)
Date: Tue, 09 Dec 2014 17:45:54 +0000
Subject: [docs] [issue14787] pkgutil.walk_packages returns extra modules
In-Reply-To: <1336813271.29.0.464157696844.issue14787@psf.upfronthosting.co.za>
Message-ID: <1418147154.68.0.259772203888.issue14787@psf.upfronthosting.co.za>


Changes by Pablo Aguiar <scorphus at gmail.com>:


----------
nosy: +scorphus

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

From report at bugs.python.org  Wed Dec 10 00:47:44 2014
From: report at bugs.python.org (Roundup Robot)
Date: Tue, 09 Dec 2014 23:47:44 +0000
Subject: [docs] [issue12602] Missing cross-references in Doc/using
In-Reply-To: <1311249393.53.0.190511112739.issue12602@psf.upfronthosting.co.za>
Message-ID: <20141209234739.118676.89670@psf.io>


Roundup Robot added the comment:

New changeset bd14c4e5ef00 by Berker Peksag in branch '3.4':
Issue #12602: Add missing cross-references to runpy and using/cmdline docs.
https://hg.python.org/cpython/rev/bd14c4e5ef00

New changeset 3a648b3d1694 by Berker Peksag in branch 'default':
Issue #12602: Add missing cross-references to runpy and using/cmdline docs.
https://hg.python.org/cpython/rev/3a648b3d1694

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

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

From report at bugs.python.org  Wed Dec 10 01:06:58 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 10 Dec 2014 00:06:58 +0000
Subject: [docs] [issue12602] Missing cross-references in Doc/using
In-Reply-To: <1311249393.53.0.190511112739.issue12602@psf.upfronthosting.co.za>
Message-ID: <20141210000655.50285.47905@psf.io>


Roundup Robot added the comment:

New changeset 078dbecf2e2c by Berker Peksag in branch '2.7':
Issue #12602: Add missing cross-references to runpy and using/cmdline docs.
https://hg.python.org/cpython/rev/078dbecf2e2c

----------

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

From report at bugs.python.org  Wed Dec 10 01:08:31 2014
From: report at bugs.python.org (Berker Peksag)
Date: Wed, 10 Dec 2014 00:08:31 +0000
Subject: [docs] [issue12602] Missing cross-references in Doc/using
In-Reply-To: <1311249393.53.0.190511112739.issue12602@psf.upfronthosting.co.za>
Message-ID: <1418170111.34.0.862203074397.issue12602@psf.upfronthosting.co.za>


Berker Peksag added the comment:

Thanks for the patch, ?ric.

----------
assignee: eric.araujo -> berker.peksag
nosy: +berker.peksag
resolution:  -> fixed
stage: commit review -> resolved
status: open -> closed
type: behavior -> enhancement

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

From report at bugs.python.org  Wed Dec 10 11:51:40 2014
From: report at bugs.python.org (Chaitanya agrawal)
Date: Wed, 10 Dec 2014 10:51:40 +0000
Subject: [docs] [issue22918] Doc for __iter__ makes inexact comment
	about	dict.__iter__
In-Reply-To: <1416689379.36.0.290921977035.issue22918@psf.upfronthosting.co.za>
Message-ID: <1418208700.93.0.923312113592.issue22918@psf.upfronthosting.co.za>


Changes by Chaitanya agrawal <chaitiagrawal at gmail.com>:


----------
keywords: +patch
Added file: http://bugs.python.org/file37407/issue22918-inexactComment.diff

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

From report at bugs.python.org  Wed Dec 10 15:36:44 2014
From: report at bugs.python.org (R. David Murray)
Date: Wed, 10 Dec 2014 14:36:44 +0000
Subject: [docs] [issue23019] pyexpat.errors wrongly bound to message strings
	instead	of message codes
In-Reply-To: <1418111127.16.0.333870475533.issue23019@psf.upfronthosting.co.za>
Message-ID: <1418222204.04.0.936976772319.issue23019@psf.upfronthosting.co.za>


R. David Murray added the comment:

Actually, I'm going to reopen it as a doc issue. This should be explained in the 2.7 docs.

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

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

From report at bugs.python.org  Wed Dec 10 15:46:57 2014
From: report at bugs.python.org (Berker Peksag)
Date: Wed, 10 Dec 2014 14:46:57 +0000
Subject: [docs] [issue23019] pyexpat.errors wrongly bound to message strings
	instead	of message codes
In-Reply-To: <1418111127.16.0.333870475533.issue23019@psf.upfronthosting.co.za>
Message-ID: <1418222817.65.0.184265733128.issue23019@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


----------
keywords: +easy
stage: resolved -> needs patch

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

From report at bugs.python.org  Wed Dec 10 15:51:48 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 10 Dec 2014 14:51:48 +0000
Subject: [docs] [issue22918] Doc for __iter__ makes inexact comment
	about	dict.__iter__
In-Reply-To: <1416689379.36.0.290921977035.issue22918@psf.upfronthosting.co.za>
Message-ID: <20141210145145.50271.65291@psf.io>


Roundup Robot added the comment:

New changeset 743ebaba14db by R David Murray in branch '3.4':
#22918: Drop obsolete mention of 'keys' in datamodel __iter__ docs.
https://hg.python.org/cpython/rev/743ebaba14db

New changeset 1a1f577ca647 by R David Murray in branch 'default':
Merge: #22918: Drop obsolete mention of 'keys' in datamodel __iter__ docs.
https://hg.python.org/cpython/rev/1a1f577ca647

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

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

From report at bugs.python.org  Wed Dec 10 15:52:41 2014
From: report at bugs.python.org (R. David Murray)
Date: Wed, 10 Dec 2014 14:52:41 +0000
Subject: [docs] [issue22918] Doc for __iter__ makes inexact comment
	about	dict.__iter__
In-Reply-To: <1416689379.36.0.290921977035.issue22918@psf.upfronthosting.co.za>
Message-ID: <1418223161.18.0.528340534286.issue22918@psf.upfronthosting.co.za>


R. David Murray added the comment:

Thanks, Chaitanya.

----------
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed
type:  -> behavior

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

From report at bugs.python.org  Wed Dec 10 19:16:06 2014
From: report at bugs.python.org (Alex Gaynor)
Date: Wed, 10 Dec 2014 18:16:06 +0000
Subject: [docs] [issue23025] ssl.RAND_bytes docs should mention os.urandom
Message-ID: <1418235366.16.0.20927959194.issue23025@psf.upfronthosting.co.za>


New submission from Alex Gaynor:

For almost any conceivable application, os.urandom is a preferable way to access a CSPRNG, and is less error prone, the docs should point this out.

----------
assignee: docs at python
components: Documentation
files: rand.diff
keywords: patch
messages: 232436
nosy: alex, docs at python
priority: normal
severity: normal
status: open
title: ssl.RAND_bytes docs should mention os.urandom
Added file: http://bugs.python.org/file37410/rand.diff

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

From report at bugs.python.org  Wed Dec 10 19:23:32 2014
From: report at bugs.python.org (Donald Stufft)
Date: Wed, 10 Dec 2014 18:23:32 +0000
Subject: [docs] [issue23025] ssl.RAND_bytes docs should mention os.urandom
In-Reply-To: <1418235366.16.0.20927959194.issue23025@psf.upfronthosting.co.za>
Message-ID: <1418235812.48.0.464938550086.issue23025@psf.upfronthosting.co.za>


Donald Stufft added the comment:

I agree completely. This is something that should generally be discouraged all together. See: http://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/

----------
nosy: +dstufft

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

From report at bugs.python.org  Thu Dec 11 00:50:57 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 10 Dec 2014 23:50:57 +0000
Subject: [docs] [issue23006] Improve the doc and indexing of
	adict.__missing__.
In-Reply-To: <1417985369.96.0.326358204226.issue23006@psf.upfronthosting.co.za>
Message-ID: <20141210235048.54572.86169@psf.io>


Roundup Robot added the comment:

New changeset 0fe3fb886c38 by Terry Jan Reedy in branch '2.7':
Issue #23006: Improve the documentation and indexing of dict.__missing__.
https://hg.python.org/cpython/rev/0fe3fb886c38

New changeset 31875b244bdf by Terry Jan Reedy in branch '3.4':
Issue #23006: Improve the documentation and indexing of dict.__missing__.
https://hg.python.org/cpython/rev/31875b244bdf

New changeset 41b172fd4479 by Terry Jan Reedy in branch '3.4':
Issue #23006 whitespace
https://hg.python.org/cpython/rev/41b172fd4479

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

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

From report at bugs.python.org  Thu Dec 11 01:02:50 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Thu, 11 Dec 2014 00:02:50 +0000
Subject: [docs] [issue23006] Improve the doc and indexing of
	adict.__missing__.
In-Reply-To: <1417985369.96.0.326358204226.issue23006@psf.upfronthosting.co.za>
Message-ID: <1418256170.08.0.805781951886.issue23006@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

I made a couple more minor revisions to the 3.4 stdtypes text and copied the revised paragraph, with the code example, to 2.7

----------
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed

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

From report at bugs.python.org  Thu Dec 11 11:32:34 2014
From: report at bugs.python.org (Antoine Pitrou)
Date: Thu, 11 Dec 2014 10:32:34 +0000
Subject: [docs] [issue23025] ssl.RAND_bytes docs should mention os.urandom
In-Reply-To: <1418235366.16.0.20927959194.issue23025@psf.upfronthosting.co.za>
Message-ID: <1418293954.21.0.968699618752.issue23025@psf.upfronthosting.co.za>


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


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

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

From report at bugs.python.org  Thu Dec 11 12:45:40 2014
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 11 Dec 2014 11:45:40 +0000
Subject: [docs] [issue23025] ssl.RAND_bytes docs should mention os.urandom
In-Reply-To: <1418235366.16.0.20927959194.issue23025@psf.upfronthosting.co.za>
Message-ID: <1418298340.35.0.866199120398.issue23025@psf.upfronthosting.co.za>


STINNER Victor added the comment:

RAND_bytes() has an annoying bug: it can produces the same byte sequence in two different processes if they get the same identifier (yes, it occurs sometimes). See the issue #18747 and warnings about fork in the ssl module. I don't know if it is now fixed in OpenSSL or maybe in LibreSSL. I was surprised that such bug exist in a serious library designed for cryptography. The usual reply to bug report is that users have to inject entropy manually at fork. It may be possible in an application, the issue #18747 explains why it is not a good idea to that in Python. /dev/urandom doesn't have such issue...

I made the change to expose RAND_bytes(). I made it for my Hasard program (expermental tool to learn PRNG), to easily test the OpenSSL library in Python. That's how I "discovered" the fork issue (it was already known in fact..). I never used ssl.RAND_bytes() in a (real) Python application.

http://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/ gives good reasons to not use ssl.RAND_bytes. So rand.diff looks good to me.

----------

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

From report at bugs.python.org  Thu Dec 11 12:46:52 2014
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 11 Dec 2014 11:46:52 +0000
Subject: [docs] [issue23025] ssl.RAND_bytes docs should mention os.urandom
In-Reply-To: <1418235366.16.0.20927959194.issue23025@psf.upfronthosting.co.za>
Message-ID: <1418298412.32.0.932494258862.issue23025@psf.upfronthosting.co.za>


STINNER Victor added the comment:

Note: ssl.RAND_bytes() doesn't exist in Python 2 (even in Python 2.7.9!).

----------
versions: +Python 3.4, Python 3.5

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

From odragora at gmail.com  Mon Dec  8 14:16:17 2014
From: odragora at gmail.com (odragora at gmail.com)
Date: Mon, 8 Dec 2014 13:16:17 +0000
Subject: [docs] =?utf-8?q?Broken_links_on_Python_2=2E7=2E9rc1_offline_docu?=
	=?utf-8?q?mentation?=
Message-ID: <5485a533.ca08980a.1da3.fffff7f2@mx.google.com>

Hi!


I?m trying to download Python docs ( https://docs.python.org/2/download.html), but links seems to be broken.


Regards!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141208/6945c5db/attachment-0001.html>

From bocajnotnef at gmail.com  Tue Dec  9 02:26:26 2014
From: bocajnotnef at gmail.com (Jake Fenton)
Date: Tue, 09 Dec 2014 01:26:26 +0000
Subject: [docs] 2.7.9rc1 Doc Links 404'ing
Message-ID: <CADKLxK-=bQ2kfQFieX=jTnAwuOYfKFL+d-mZmsRpv5jQJL77MA@mail.gmail.com>

Hello! I was recently trying to download the full docs for the 2.7 release
(I will be off the grid for a bit) and found that all the download links
for the current release are 404-ing.

The relevant page is here: https://docs.python.org/2.7/download.html

--JF
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141209/f9520a40/attachment-0001.html>

From jaysinhp at gmail.com  Tue Dec  9 13:28:09 2014
From: jaysinhp at gmail.com (Jaysinh shukla)
Date: Tue, 9 Dec 2014 12:28:09 +0000
Subject: [docs] Regarding Broken link of Python-2.7.9rc1 documentation.
Message-ID: <CAPPZTOH8DLZyTXqeXoHsyyXWvH2mL6cRvyr8Lqb=1qSKzsodmQ@mail.gmail.com>

Respected Sir / Madam,
        Recently I was trying to download documentation of
"Python-2.7.9rc1" from this <https://docs.python.org/2/download.html> page.
I found non of the downloading links available on the page are working.
They all throws "404 - Not Found". Requesting to update it accordingly.
Thanking you.

-- 

      Jaysinh :)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141209/15dd3191/attachment-0001.html>

From 1670009590 at qq.com  Tue Dec  9 14:32:09 2014
From: 1670009590 at qq.com (=?gb18030?B?U6iho/kgptij6KihptM=?=)
Date: Tue, 9 Dec 2014 21:32:09 +0800
Subject: [docs] python2.7 docs download
Message-ID: <tencent_28A61468169B3D0C04BFD366@qq.com>

Hi, I wanna download python2.7 docs, but all links are 404.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141209/25e87f21/attachment-0001.html>

From JohnJPosner at verizon.net  Tue Dec  9 15:44:53 2014
From: JohnJPosner at verizon.net (JohnJPosner at verizon.net)
Date: Tue, 09 Dec 2014 14:44:53 -0000
Subject: [docs] Improve the doc and indexing of adict.__missing__.
	(issue 23006)
Message-ID: <20141209144453.8280.60428@psf.upfronthosting.co.za>

The term "subdict" at line 1910 of datamodel.rst seems to be a shorthand
way of saying "instance of a dict subclass", but that's kind of obscure.
The term "subdict" does not appear anywhere else in this document.

I suggest changing "subdict" to "dictionary".

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

From deva.seetharam at gmail.com  Tue Dec  9 20:31:34 2014
From: deva.seetharam at gmail.com (deva seetharam)
Date: Wed, 10 Dec 2014 01:01:34 +0530
Subject: [docs] download links are not working
Message-ID: <CAGU6BDk3LdUUhT-1jqLO4_G1CB7WGuzXUzPE+K80Q3V1RzvsUg@mail.gmail.com>

none of the  links on the docs download page (
https://docs.python.org/2.7/download.html) are working. pls. help.

-- 
best regards,
Deva P. Seetharam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141210/83805cac/attachment-0001.html>

From drcspot at gmail.com  Tue Dec  9 23:37:05 2014
From: drcspot at gmail.com (drc)
Date: Tue, 09 Dec 2014 15:37:05 -0700
Subject: [docs] Download Python 2.7.9rc1 Documentation
Message-ID: <54877991.3040302@gmail.com>

Hi,

    I was unable to download the documents for 2.7.9rcl. Click on any of 
the files and a page appears with "404 Not Found"

    I'm using Firefox in Linux. I was able to download the latest 
version of the docs.

Thanks

From noha00 at hotmail.com  Wed Dec 10 10:02:05 2014
From: noha00 at hotmail.com (Noha H)
Date: Wed, 10 Dec 2014 10:02:05 +0100
Subject: [docs] docs can not be downloaded
Message-ID: <DUB127-W904B06B8D6035F1F22BB1CC7620@phx.gbl>

Hello, all the links for documentation download is broken. 404 error is giventhank you https://docs.python.org/2/download.html

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

"Don't
say you don't have enough time. You have exactly the same hours per day that
were given to Helen Keller, Pasteur, Michelangelo, Mother Teresa, Leonardo Da
Vinci, Thomas Jefferson and Albert Einstein."  		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141210/de2c8cb4/attachment-0001.html>

From pesy at outlook.com  Tue Dec  9 21:16:20 2014
From: pesy at outlook.com (Petros)
Date: Tue, 9 Dec 2014 22:16:20 +0200
Subject: [docs] Documentation
Message-ID: <DUB405-EAS2880F6FB9286466E76D8EBCC3620@phx.gbl>

https://docs.python.org/2/archives/python-2.7.9rc1-docs-pdf-a4.zip 

 

fails to work 404 etc.

 

give me a heads up if you care when it gets back online

 

Regards

Petros

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141209/074fdaab/attachment-0001.html>

From ajeebkp23 at gmail.com  Wed Dec 10 12:43:42 2014
From: ajeebkp23 at gmail.com (Ajeeb K P)
Date: Wed, 10 Dec 2014 17:13:42 +0530
Subject: [docs] Doc Download link not working
Message-ID: <CAJY-6aa-9PiqDwQZi0mBsywPNWPozhAvGnBB0tCzoA947qrkMw@mail.gmail.com>

Dear sir,

Many of the download links of the python doc downloads are not working

For eg:-
https://www.python.org/ftp/python/doc/3.5.0a0/python-3.5.0a0-docs-pdf-a4.zip
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141210/c944a61d/attachment-0001.html>

From mathias.kemmler at gmail.com  Wed Dec 10 16:14:55 2014
From: mathias.kemmler at gmail.com (Mathias Kemmler)
Date: Wed, 10 Dec 2014 16:14:55 +0100
Subject: [docs] Download Python 2.7.9rc1 Documentation
Message-ID: <CAE6LAfWua98c8gRRi-2Ox3JQ_Y_VYmaK-EoLJYf31SjcGySM-w@mail.gmail.com>

Dear Python-team,

I just tried to download the documentation for python, but got a 404 error
when I tried to download the zip file. After a quick try it seems as if non
of the files are accessible. Any chance this could be corrected in the near
future?

Kind regards,

Mathias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141210/bd5a656c/attachment-0001.html>

From Woody at mail.python.org  Wed Dec 10 17:29:41 2014
From: Woody at mail.python.org (Woody at mail.python.org)
Date: Thu, 11 Dec 2014 00:29:41 +0800 (HKT)
Subject: [docs] Link to Python 2.7.9rc1 documentation dead
Message-ID: <20141211.002941.1214713056956668029.hckiang@riseup.net>

Dear maintainer,

The links to documentations here is dead:

     https://docs.python.org/2/download.html

Please update it, and thanks for your kind work. :-)


Best regards,
Haochi Kiang

From samuel--102 at hotmail.com  Wed Dec 10 18:08:56 2014
From: samuel--102 at hotmail.com (samuel eewewew)
Date: Wed, 10 Dec 2014 12:08:56 -0500
Subject: [docs] (no subject)
Message-ID: <BAY173-W17ACA621B13C3205314C94FF620@phx.gbl>


I can not download the documentation, have some alternate link:
https://docs.python.org/2/archives/python-2.7.9rc1-docs-pdf-letter.zip404 Not Found 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141210/55e36cfc/attachment-0001.html>

From lucivaldocb at gmail.com  Wed Dec 10 22:53:45 2014
From: lucivaldocb at gmail.com (Lucivaldo Castro)
Date: Wed, 10 Dec 2014 18:53:45 -0300
Subject: [docs] Problem with link
Message-ID: <CAH3S5YcoarEmTxaGxZV7cxS_rRNN22fxFxXbk-zRngYv44zG5g@mail.gmail.com>

Hello,

Have a problem with the link that target to page of the downloads of the
documentation of the latest version of the release of the Python 2.7.x.

I am Brazilian, forgive me for typos.

Link: https://docs.python.org/2/download.html

Thanks!!!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141210/cef967b9/attachment-0001.html>

From report at bugs.python.org  Fri Dec 12 08:56:05 2014
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 12 Dec 2014 07:56:05 +0000
Subject: [docs] [issue23005] typos on heapq doc
In-Reply-To: <1417978054.94.0.0217424241667.issue23005@psf.upfronthosting.co.za>
Message-ID: <20141212075600.20697.11279@psf.io>


Roundup Robot added the comment:

New changeset cb085b07ea34 by Raymond Hettinger in branch '2.7':
Issue 23005: Fix typos
https://hg.python.org/cpython/rev/cb085b07ea34

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

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

From report at bugs.python.org  Fri Dec 12 08:57:14 2014
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 12 Dec 2014 07:57:14 +0000
Subject: [docs] [issue23005] typos on heapq doc
In-Reply-To: <1417978054.94.0.0217424241667.issue23005@psf.upfronthosting.co.za>
Message-ID: <20141212075700.95330.16849@psf.io>


Roundup Robot added the comment:

New changeset 7f2cf63cf95a by Raymond Hettinger in branch '3.4':
Issue 23005: Fix typos
https://hg.python.org/cpython/rev/7f2cf63cf95a

----------

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

From report at bugs.python.org  Fri Dec 12 08:58:50 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Fri, 12 Dec 2014 07:58:50 +0000
Subject: [docs] [issue23005] typos on heapq doc
In-Reply-To: <1417978054.94.0.0217424241667.issue23005@psf.upfronthosting.co.za>
Message-ID: <1418371130.14.0.76462999119.issue23005@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/issue23005>
_______________________________________

From report at bugs.python.org  Fri Dec 12 09:00:36 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Fri, 12 Dec 2014 08:00:36 +0000
Subject: [docs] [issue9536] defaultdict doc makes incorrect reference to
	__missing__	method
In-Reply-To: <1281106528.37.0.0435364267174.issue9536@psf.upfronthosting.co.za>
Message-ID: <1418371236.86.0.167037876244.issue9536@psf.upfronthosting.co.za>


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


----------
resolution:  -> rejected
status: open -> closed

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

From report at bugs.python.org  Fri Dec 12 15:44:33 2014
From: report at bugs.python.org (Collin Anderson)
Date: Fri, 12 Dec 2014 14:44:33 +0000
Subject: [docs] [issue23038] #python.web irc channel is dead
Message-ID: <1418395473.68.0.943574829813.issue23038@psf.upfronthosting.co.za>


New submission from Collin Anderson:

Can we remove references to #python.web? I assume it was a flourishing channel at some point.

https://docs.python.org/3/howto/webservers.html#other-notable-frameworks

----------
assignee: docs at python
components: Documentation
messages: 232550
nosy: collinanderson, docs at python
priority: normal
severity: normal
status: open
title: #python.web irc channel is dead
versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6

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

From report at bugs.python.org  Fri Dec 12 15:57:32 2014
From: report at bugs.python.org (Roundup Robot)
Date: Fri, 12 Dec 2014 14:57:32 +0000
Subject: [docs] [issue23038] #python.web irc channel is dead
In-Reply-To: <1418395473.68.0.943574829813.issue23038@psf.upfronthosting.co.za>
Message-ID: <20141212145704.54586.55445@psf.io>


Roundup Robot added the comment:

New changeset 1edff7001f58 by Benjamin Peterson in branch '2.7':
remove reference to dead irc channel (closes #23038)
https://hg.python.org/cpython/rev/1edff7001f58

New changeset aba5f771f5ec by Benjamin Peterson in branch '3.4':
remove reference to dead irc channel (closes #23038)
https://hg.python.org/cpython/rev/aba5f771f5ec

----------
nosy: +python-dev
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

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

From report at bugs.python.org  Fri Dec 12 16:34:59 2014
From: report at bugs.python.org (Wojtek Ruszczewski)
Date: Fri, 12 Dec 2014 15:34:59 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
Message-ID: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>


New submission from Wojtek Ruszczewski:

The documentation for urlencode() [1] isn't very clear on how the safe parameter is used, it would better not list it together with encoding and error as only applying to strings.

[1] https://docs.python.org/3.5/library/urllib.parse.html#urllib.parse.urlencode

----------
assignee: docs at python
components: Documentation
files: urlencode-safe.diff
keywords: patch
messages: 232556
nosy: docs at python, wrwrwr
priority: normal
severity: normal
status: open
title: Better documentation for the urlencode safe parameter
type: enhancement
versions: Python 3.5
Added file: http://bugs.python.org/file37426/urlencode-safe.diff

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

From report at bugs.python.org  Fri Dec 12 17:26:16 2014
From: report at bugs.python.org (R. David Murray)
Date: Fri, 12 Dec 2014 16:26:16 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <1418401576.95.0.586795102276.issue23040@psf.upfronthosting.co.za>


R. David Murray added the comment:

The current documentation looks very clear to me, and I don't understand your changed version.  Can you give an example of how the existing text is inaccurate or results in confusion?

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

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

From report at bugs.python.org  Fri Dec 12 18:04:37 2014
From: report at bugs.python.org (Berker Peksag)
Date: Fri, 12 Dec 2014 17:04:37 +0000
Subject: [docs] [issue9536] defaultdict doc makes incorrect reference to
	__missing__	method
In-Reply-To: <1281106528.37.0.0435364267174.issue9536@psf.upfronthosting.co.za>
Message-ID: <1418403877.76.0.698970865054.issue9536@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


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

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

From report at bugs.python.org  Fri Dec 12 18:30:20 2014
From: report at bugs.python.org (Wojtek Ruszczewski)
Date: Fri, 12 Dec 2014 17:30:20 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <1418405420.67.0.0646374777583.issue23040@psf.upfronthosting.co.za>


Wojtek Ruszczewski added the comment:

I was looking at the sentence:
"When query parameter is a str, the safe, encoding and error parameters are passed down to quote_plus() for encoding."

The query argument can't be a string itself (gives a TypeError with 3.5a0 and I think it's only intended to accept dicts or sequences of 2-tuples). The "parameter" then must refer to a component of the query -- a key or a value.

The safe argument is passed down and is effective no matter if a component is of str or bytes type (or a sequence with doseq), for example:

>>> urlencode({b'/ n': ''}, safe='/')
'/+n='
(note the "b"; without "safe" the slash would get encoded as %2F).

Maybe it would also be good to change "query parameter" to "query component" in that sentence.

----------

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

From report at bugs.python.org  Fri Dec 12 22:07:38 2014
From: report at bugs.python.org (R. David Murray)
Date: Fri, 12 Dec 2014 21:07:38 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <1418418458.06.0.632229076486.issue23040@psf.upfronthosting.co.za>


R. David Murray added the comment:

OK, now I understand.  How about this phrasing:

"The *safe*, *encoding*, and *error* parameters are passed down to :func:`quote_plus` (the *encoding* and *error* parameters are only passed when the query element is a :class:`str`).

----------

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

From report at bugs.python.org  Sat Dec 13 00:35:02 2014
From: report at bugs.python.org (Wojtek Ruszczewski)
Date: Fri, 12 Dec 2014 23:35:02 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <1418427302.41.0.671036714488.issue23040@psf.upfronthosting.co.za>


Wojtek Ruszczewski added the comment:

Thanks, that's right and better, as it doesn't replicate the safe explanation.

I've just noticed another small one, the docstring for quote() [2] says:
"encoding must not be specified if string is a str" -- that should be "... is a bytes".

[2] https://hg.python.org/cpython/file/default/Lib/urllib/parse.py#l690

----------

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

From report at bugs.python.org  Sat Dec 13 01:43:07 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 13 Dec 2014 00:43:07 +0000
Subject: [docs] [issue23011] Duplicate Paragraph in documentation for json
	module
In-Reply-To: <1418047735.37.0.83441849339.issue23011@psf.upfronthosting.co.za>
Message-ID: <1418431387.19.0.877982995403.issue23011@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

The section documents JSONDecoder and then JSONEncoder.  Looking at the current 3.4 online docs, I do not see any significant duplication within either entry.  Even if there were duplication between, we might leave it to keep the entries complete in themselves.  But not seeing any, this is moot.

----------
nosy: +terry.reedy
versions:  -Python 3.3

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

From report at bugs.python.org  Sat Dec 13 04:21:49 2014
From: report at bugs.python.org (Martin Panter)
Date: Sat, 13 Dec 2014 03:21:49 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1418440909.43.0.455473081371.issue21279@psf.upfronthosting.co.za>


Martin Panter added the comment:

Update patch with typo fixed, removed note about the ?codecs? module (which I never found useful either), and updated the doc string with similar wording.

Terry, do you think the wording in the patch is good enough, or do you think some of your proposed wording should be included?

----------
Added file: http://bugs.python.org/file37436/issue21279.patch

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

From report at bugs.python.org  Sat Dec 13 04:32:41 2014
From: report at bugs.python.org (Steven D'Aprano)
Date: Sat, 13 Dec 2014 03:32:41 +0000
Subject: [docs] [issue23017] string.printable.isprintable() returns False
In-Reply-To: <1418097121.16.0.891016494417.issue23017@psf.upfronthosting.co.za>
Message-ID: <1418441561.67.0.559533402593.issue23017@psf.upfronthosting.co.za>


Changes by Steven D'Aprano <steve+python at pearwood.info>:


----------
nosy: +steven.daprano

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

From report at bugs.python.org  Sat Dec 13 07:53:02 2014
From: report at bugs.python.org (Martin Panter)
Date: Sat, 13 Dec 2014 06:53:02 +0000
Subject: [docs] [issue22875] asyncio: call_soon() documentation unclear on
	timing
In-Reply-To: <1415995304.37.0.00737491261157.issue22875@psf.upfronthosting.co.za>
Message-ID: <1418453582.27.0.793612227254.issue22875@psf.upfronthosting.co.za>


Martin Panter added the comment:

I have been bitten by this when attempting to implement my own event loops. Parts of the ?asyncio? code itself expects that the callback is not invoked directly after call_soon() returns. Here is a simple patch.

----------
keywords: +patch
nosy: +vadmium
versions: +Python 3.4
Added file: http://bugs.python.org/file37437/call_soon.patch

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

From report at bugs.python.org  Sat Dec 13 11:01:17 2014
From: report at bugs.python.org (Xavier de Gaye)
Date: Sat, 13 Dec 2014 10:01:17 +0000
Subject: [docs] [issue23047] typo in pyporting.rst
Message-ID: <1418464877.74.0.653707717476.issue23047@psf.upfronthosting.co.za>


New submission from Xavier de Gaye:

In Doc/howto/pyporting.rst at line "from __future__ import print_statement":
  s/print_statement/print_function/

----------
assignee: docs at python
components: Documentation
messages: 232600
nosy: brett.cannon, docs at python, xdegaye
priority: normal
severity: normal
status: open
title: typo in pyporting.rst
type: behavior
versions: Python 3.5

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

From report at bugs.python.org  Sat Dec 13 12:51:30 2014
From: report at bugs.python.org (Chaitanya agrawal)
Date: Sat, 13 Dec 2014 11:51:30 +0000
Subject: [docs] [issue23047] typo in pyporting.rst
In-Reply-To: <1418464877.74.0.653707717476.issue23047@psf.upfronthosting.co.za>
Message-ID: <1418471490.92.0.922109335168.issue23047@psf.upfronthosting.co.za>


Chaitanya agrawal added the comment:

Typo corrected according to message232600.

----------
keywords: +patch
nosy: +krypten
Added file: http://bugs.python.org/file37438/issue23047.patch

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

From report at bugs.python.org  Sat Dec 13 12:51:36 2014
From: report at bugs.python.org (Wojtek Ruszczewski)
Date: Sat, 13 Dec 2014 11:51:36 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <1418471496.21.0.0489814930539.issue23040@psf.upfronthosting.co.za>


Wojtek Ruszczewski added the comment:

Updated the patch, additionally changing "be" to "contain" in the first sentence.

----------
Added file: http://bugs.python.org/file37439/urlencode-safe-v2.diff

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

From report at bugs.python.org  Sat Dec 13 14:48:37 2014
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 13 Dec 2014 13:48:37 +0000
Subject: [docs] [issue23047] typo in pyporting.rst
In-Reply-To: <1418464877.74.0.653707717476.issue23047@psf.upfronthosting.co.za>
Message-ID: <20141213134832.18143.78957@psf.io>


Roundup Robot added the comment:

New changeset 914e9092984e by Berker Peksag in branch '3.4':
Issue #23047: Fix typo in pyporting.rst.
https://hg.python.org/cpython/rev/914e9092984e

New changeset 81a56c9e1e1c by Berker Peksag in branch 'default':
Issue #23047: Fix typo in pyporting.rst.
https://hg.python.org/cpython/rev/81a56c9e1e1c

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

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

From report at bugs.python.org  Sat Dec 13 14:50:53 2014
From: report at bugs.python.org (Roundup Robot)
Date: Sat, 13 Dec 2014 13:50:53 +0000
Subject: [docs] [issue23047] typo in pyporting.rst
In-Reply-To: <1418464877.74.0.653707717476.issue23047@psf.upfronthosting.co.za>
Message-ID: <20141213135052.50097.81389@psf.io>


Roundup Robot added the comment:

New changeset f1f404f5422a by Berker Peksag in branch '2.7':
Issue #23047: Fix typo in pyporting.rst.
https://hg.python.org/cpython/rev/f1f404f5422a

----------

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

From report at bugs.python.org  Sat Dec 13 14:52:28 2014
From: report at bugs.python.org (Berker Peksag)
Date: Sat, 13 Dec 2014 13:52:28 +0000
Subject: [docs] [issue23047] typo in pyporting.rst
In-Reply-To: <1418464877.74.0.653707717476.issue23047@psf.upfronthosting.co.za>
Message-ID: <1418478748.6.0.268484947859.issue23047@psf.upfronthosting.co.za>


Berker Peksag added the comment:

Thanks for the report, Xavier and thanks for the patch, Chaitanya.

----------
nosy: +berker.peksag
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
versions: +Python 2.7, Python 3.4

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

From report at bugs.python.org  Sat Dec 13 16:30:06 2014
From: report at bugs.python.org (Akira Li)
Date: Sat, 13 Dec 2014 15:30:06 +0000
Subject: [docs] [issue23017] string.printable.isprintable() returns False
In-Reply-To: <1418097121.16.0.891016494417.issue23017@psf.upfronthosting.co.za>
Message-ID: <1418484605.96.0.78891909405.issue23017@psf.upfronthosting.co.za>


Akira Li added the comment:

C standard defines locale-specific *printing characters* that are [ -~]
in "C" locale for implementations that use 7-bit US ASCII character set
i.e., SP (space, 0x20) is a printing character in C (isprint() returns
nonzero).

There is isgraph() function that returns zero for the space but
otherwise is equivalent to isprint().

POSIX definition is aligned with the ISO C standard.

I don't know what RFC 5822 has to do with this issue but the rfc
contradicts itself e.g., in one place it has: "printable US-ASCII
characters except SP" that imlies that SP *is* printable but in other
places it considers isprint==isgraph. The authors probably meant
characters for which isgraph() is nonzero when they use "printable
US-ASCII" (that is incorrect according to C standard).

Tests from issue9770 show the relation between C character classes and
string constants [1]:

  set(string.printable) == set(C['graph']) + set(C['space'])

where C['space'] is '\t\n\v\f\r ' (the standard C whitespace).

It is a documented behavior [2]:

  This is a combination of digits, ascii_letters, punctuation,
  and whitespace

where *whitespace* is C['space'].

In Python 2, *printable* is locale-dependent and it coincides with the
corresponding Python 3 definition in "C" locale with ASCII charset.

Unlike other string constants, *printable* differs from C['print'] on
both Python 2 and 3 because it includes whitespace characters other than
space.

str.isprintable [3] obeys C['print'] (in ASCII range) and considers SP
to be printable.

---

It might be too late to change string.printable to correspond to C
isprint() (for ASCII characters).

I've uploaded a documentation patch that mentions that string.printable
and str.isprintable differ.

[1] http://bugs.python.org/review/9770/diff/12212/Lib/test/test_curses_ascii.py
[2] https://hg.python.org/cpython/file/3.4/Doc/library/string.rst#l62
[3] https://docs.python.org/3.4/library/stdtypes.html#str.isprintable

----------
nosy: +akira
Added file: http://bugs.python.org/file37441/docs-string.printable.diff

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

From report at bugs.python.org  Sat Dec 13 21:50:53 2014
From: report at bugs.python.org (Guido van Rossum)
Date: Sat, 13 Dec 2014 20:50:53 +0000
Subject: [docs] [issue22875] asyncio: call_soon() documentation unclear on
	timing
In-Reply-To: <1418453582.27.0.793612227254.issue22875@psf.upfronthosting.co.za>
Message-ID: <CAP7+vJJb2Pw6pE9o6Gz1e-P52=Mt+sibKybOSbSQxRQCWtyOmg@mail.gmail.com>


Guido van Rossum added the comment:

Docfix LGTM.

On Fri, Dec 12, 2014 at 10:53 PM, Martin Panter <report at bugs.python.org>
wrote:
>
>
> Martin Panter added the comment:
>
> I have been bitten by this when attempting to implement my own event
> loops. Parts of the ?asyncio? code itself expects that the callback is not
> invoked directly after call_soon() returns. Here is a simple patch.
>
> ----------
> keywords: +patch
> nosy: +vadmium
> versions: +Python 3.4
> Added file: http://bugs.python.org/file37437/call_soon.patch
>
> _______________________________________
> Python tracker <report at bugs.python.org>
> <http://bugs.python.org/issue22875>
> _______________________________________
>

----------

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

From report at bugs.python.org  Sun Dec 14 00:50:42 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 13 Dec 2014 23:50:42 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1418514642.36.0.479120687189.issue21279@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Many people may not know that IndexError and KeyError are subclasses of LookupError. I have not decided what to add yet, but I think we are close.

----------

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

From report at bugs.python.org  Sun Dec 14 00:52:46 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sat, 13 Dec 2014 23:52:46 +0000
Subject: [docs] [issue23011] Duplicate Paragraph in documentation for json
	module
In-Reply-To: <1418047735.37.0.83441849339.issue23011@psf.upfronthosting.co.za>
Message-ID: <1418514766.09.0.0736364013325.issue23011@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Will reconsider if an actual duplication is presented.

----------
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

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

From report at bugs.python.org  Sun Dec 14 01:27:27 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sun, 14 Dec 2014 00:27:27 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
Message-ID: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>


New submission from Terry J. Reedy:

from functools import reduce
def add(a,b): return a+b
reduce(add, {})
>>>
Traceback (most recent call last):
  File "C:\Programs\Python34\tem.py", line 3, in <module>
    reduce(add, {})
TypeError: reduce() of empty sequence with no initial value

However, the reduce-equivalent code in the doc sets a bad example and forgets to account for empty iterators.

def reduce(function, iterable, initializer=None):
    it = iter(iterable)
    if initializer is None:
        value = next(it)
    else: ...

So it lets the StopIteration escape (a bad practice that can silently break iterators).  The code should be

def reduce(function, iterable, initializer=None):
    it = iter(iterable)
    if initializer is None:
        try:
            value = next(it)
        except StopIteration:
            raise TypeError("reduce() of empty sequence with no initial value") from None
    else: ...

(patch coming)

----------
assignee: docs at python
components: Documentation, Interpreter Core
messages: 232626
nosy: docs at python, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Fix functools.reduce code equivalent.
type: behavior
versions: Python 3.4, Python 3.5

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

From report at bugs.python.org  Sun Dec 14 03:09:19 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Sun, 14 Dec 2014 02:09:19 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418522959.83.0.0817862467844.issue23049@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/issue23049>
_______________________________________

From report at bugs.python.org  Sun Dec 14 10:15:46 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 14 Dec 2014 09:15:46 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418548546.54.0.38267938244.issue23049@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

I think it would be good to add Python implementation in functools.py and test they equivalence in tests.

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

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

From report at bugs.python.org  Sun Dec 14 19:24:06 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Sun, 14 Dec 2014 18:24:06 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418581446.49.0.648514240081.issue23049@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

Background: the OP of #19202 proposed equivalent code for all the functool functions, including two versions for reduce. Georg combined the two versions into the one that Raymond pushed.  Both agreed that reduce was the only function that really needed this.  I called Georg's code  'excellent'.

I have changed my mind slightly because people use such code equivalents not only for understanding but also as models for writing code, and because some people have had problems when by doing the same as this model, which ignores the empty iterable case.

If you do not want to 'uglify' the doc code by making it exactly equivalent, how about qualifying the claim instead?  Change 'equivalent' to 'equivalent for non-empty iterables'.

----------
keywords: +patch
nosy: +georg.brandl

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

From report at bugs.python.org  Mon Dec 15 03:26:35 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Mon, 15 Dec 2014 02:26:35 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418610395.24.0.967138011118.issue23049@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

Elsewhere I have used "rough equivalent".

FWIW, the initializer defaulting to "None" is also an approximation.   It would be more technically correct to have "initializer = sentinel" where "sentinel = object()".   But of course this too would obfuscate the documentation which mainly aimed to clarify two sticky points:  1) the order of arguments to the function call (accm, x) vs (x, accm) and 2) that if an initializer isn't specified, the first value from the iterable is used.  These are the two issues that Guido found difficult to remember and caused reduce() to be banished from builtins.

----------

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

From JohnJPosner at verizon.net  Mon Dec 15 04:40:30 2014
From: JohnJPosner at verizon.net (JohnJPosner at verizon.net)
Date: Mon, 15 Dec 2014 03:40:30 -0000
Subject: [docs] str.translate documentation incomplete (issue 21279)
Message-ID: <20141215034030.6752.32822@psf.upfronthosting.co.za>

Using this mechanism for the first time. Please let me know if I'm using
it incorrectly.


http://bugs.python.org/review/21279/diff/13406/Doc/library/stdtypes.rst
File Doc/library/stdtypes.rst (right):

http://bugs.python.org/review/21279/diff/13406/Doc/library/stdtypes.rst#newcode1912
Doc/library/stdtypes.rst:1912: Return a copy of the string where all
characters have been mapped through the
I suggest a revised paragraph, combining this one with the comments made
by Terry Reedy. IMO, it's important to point out that a LookupError
produced by the translation table does not cause the translate() method
to fail. Rather, translate() catches the exception and sends the
character, unchanged, to the return string.

Here's my suggested paragraph:

Return a copy of the string *str* in which each character has been
mapped through the given translation *table*. The translation table must
be a subscriptable object, for instance a list or dictionary; when
subscripted (indexed) by a Unicode ordinal (an integer in
range(1048576)), the table object can yield a Unicode ordinal, a string,
or None -- or else can raise a LookupError. A LookupError (typically, an
instance of subclass IndexError or KeyError) is caught by translate; the
character is sent, unchanged, to the return string. A character mapped
to None is deleted from the return string.

And here's a possible alternative for the first sentence:

Map each character of the string *str* through the given translation
*table*, and return the resulting string.

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

From report at bugs.python.org  Mon Dec 15 14:38:48 2014
From: report at bugs.python.org (John Posner)
Date: Mon, 15 Dec 2014 13:38:48 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1418650728.14.0.202359912501.issue21279@psf.upfronthosting.co.za>


John Posner added the comment:

Kindly ignore message #2 on the Rietveld page (sorry for the channel noise). Here's my suggested revision:

Return a copy of the string *str* in which each character has been mapped through the given translation *table*. The table must be a subscriptable object, for instance a list or dictionary; when subscripted (indexed) by a Unicode ordinal (an integer in range(1048576)), the table object can:

* return a Unicode ordinal or a string, to map the character to one or more other characters.

* return None, to delete the character from the return string.

* raise a LookupError (possibly an instance of subclass IndexError or KeyError), to map the character to itself.

----------
nosy: +jjposner

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

From report at bugs.python.org  Mon Dec 15 15:49:03 2014
From: report at bugs.python.org (Joe Cabrera)
Date: Mon, 15 Dec 2014 14:49:03 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
Message-ID: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>


New submission from Joe Cabrera:

ConnectionError: ('Connection aborted.', BadStatusLine(""''''"))

This error can also occur on Linux and Windows, a more descriptive error messages would be useful for people trying to debug their code.

----------
assignee: docs at python
components: Documentation
messages: 232664
nosy: docs at python, joecabrera
priority: normal
severity: normal
status: open
title: ConnectionError: ('Connection aborted.', BadStatusLine(""''''"))
type: behavior
versions: Python 2.7

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

From report at bugs.python.org  Mon Dec 15 16:06:05 2014
From: report at bugs.python.org (R. David Murray)
Date: Mon, 15 Dec 2014 15:06:05 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
In-Reply-To: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>
Message-ID: <1418655965.73.0.689384380154.issue23054@psf.upfronthosting.co.za>


R. David Murray added the comment:

I think you made a mistake in your copy and paste or retyping of that line, since it is not valid python syntax.

What is not explicit about it?  It is telling you there was a bad status line, and what the bad status line contents was.  (Used to be you couldn't tell, when the badness of the status line was that it was empty, that that was what the error message was saying, but I'm pretty sure we fixed that so that it shows an empty status line as an empty string in the message).

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

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

From report at bugs.python.org  Mon Dec 15 16:08:54 2014
From: report at bugs.python.org (R. David Murray)
Date: Mon, 15 Dec 2014 15:08:54 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
In-Reply-To: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>
Message-ID: <1418656133.98.0.948710268009.issue23054@psf.upfronthosting.co.za>


R. David Murray added the comment:

Perhaps part of your problem is that you are not getting the string representation of the error message.  Is that because of your code, or is this representation something the stdlib is generating?

----------

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

From report at bugs.python.org  Mon Dec 15 17:52:12 2014
From: report at bugs.python.org (STINNER Victor)
Date: Mon, 15 Dec 2014 16:52:12 +0000
Subject: [docs] [issue22875] asyncio: call_soon() documentation unclear on
	timing
In-Reply-To: <1415995304.37.0.00737491261157.issue22875@psf.upfronthosting.co.za>
Message-ID: <1418662332.64.0.48787501686.issue22875@psf.upfronthosting.co.za>


STINNER Victor added the comment:

Thanks Martin for your change, I commited it.

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

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

From report at bugs.python.org  Mon Dec 15 17:52:44 2014
From: report at bugs.python.org (STINNER Victor)
Date: Mon, 15 Dec 2014 16:52:44 +0000
Subject: [docs] [issue22875] asyncio: call_soon() documentation unclear on
	timing
In-Reply-To: <1415995304.37.0.00737491261157.issue22875@psf.upfronthosting.co.za>
Message-ID: <1418662364.62.0.0164366660847.issue22875@psf.upfronthosting.co.za>


STINNER Victor added the comment:

Oops, I forgot to mention the issue number in my commit.

changeset:   93893:a59fed8c710b
branch:      3.4
parent:      93891:1da9e9eaeae8
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Mon Dec 15 17:50:55 2014 +0100
files:       Doc/library/asyncio-eventloop.rst
description:
asyncio doc: call_soon() does not call immediatly the callback. Patch written
by Martin Panter.

----------

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

From report at bugs.python.org  Mon Dec 15 17:56:13 2014
From: report at bugs.python.org (STINNER Victor)
Date: Mon, 15 Dec 2014 16:56:13 +0000
Subject: [docs] [issue22875] asyncio: call_soon() documentation unclear on
	timing
In-Reply-To: <1415995304.37.0.00737491261157.issue22875@psf.upfronthosting.co.za>
Message-ID: <1418662573.28.0.0419936790192.issue22875@psf.upfronthosting.co.za>


STINNER Victor added the comment:

FYI I added a new test to the aiotest project (test suite for asyncio), for this issue:
https://bitbucket.org/haypo/aiotest/commits/17dd11fc2f4bafad623f940b1a33a3b8b0d39ccd

----------

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

From report at bugs.python.org  Tue Dec 16 02:12:42 2014
From: report at bugs.python.org (Martin Panter)
Date: Tue, 16 Dec 2014 01:12:42 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1418692362.04.0.56521597689.issue21279@psf.upfronthosting.co.za>


Martin Panter added the comment:

I?m largely happy with any of these revisions. If I end up doing another patch I would omit the *str* (it is a class name, not a parameter). Also I would omit the range(2^20) claim. Unless people think it is important; why is it different to sys.maxunicode + 1 = 0x110000?

----------

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

From report at bugs.python.org  Tue Dec 16 05:24:24 2014
From: report at bugs.python.org (Ian Lee)
Date: Tue, 16 Dec 2014 04:24:24 +0000
Subject: [docs] [issue23061] Update pep8 to specify explicitly 'module
	level' imports	at top of file
Message-ID: <1418703864.09.0.281927050653.issue23061@psf.upfronthosting.co.za>


New submission from Ian Lee:

Minor update pep8 to specify explicitly that "Imports at top of file" refers specifically to module level imports, per input from Nick Coghlan @ https://github.com/jcrocholl/pep8/pull/304#issuecomment-66939162

----------
assignee: docs at python
components: Documentation
files: pep-0008.patch
keywords: patch
messages: 232708
nosy: IanLee1521, docs at python, ncoghlan
priority: normal
severity: normal
status: open
title: Update pep8 to specify explicitly 'module level' imports at top of file
type: enhancement
Added file: http://bugs.python.org/file37459/pep-0008.patch

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

From report at bugs.python.org  Tue Dec 16 07:28:00 2014
From: report at bugs.python.org (Martin Panter)
Date: Tue, 16 Dec 2014 06:28:00 +0000
Subject: [docs] [issue9694] argparse required arguments displayed under
	"optional	arguments"
In-Reply-To: <1282846759.11.0.900867962743.issue9694@psf.upfronthosting.co.za>
Message-ID: <1418711278.0.0.893397618697.issue9694@psf.upfronthosting.co.za>


Martin Panter added the comment:

Here is much larger patch in the spirit of Ryan?s, that fixes the documentation, adjusts the tests, and some of the internal comments and variable names in the source code as well. However if some changes are too controversial, I am happy to simplify it to (say) Ryan?s patch plus the minimum test fixes.

----------
versions: +Python 3.5
Added file: http://bugs.python.org/file37461/option-internal.patch

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

From report at bugs.python.org  Tue Dec 16 20:29:54 2014
From: report at bugs.python.org (Joe Cabrera)
Date: Tue, 16 Dec 2014 19:29:54 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
In-Reply-To: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>
Message-ID: <1418758194.0.0.102659125226.issue23054@psf.upfronthosting.co.za>


Joe Cabrera added the comment:

This is an error wrapping coming from requests.

https://github.com/kennethreitz/requests/issues/2364

The Requests team has concluded they can do nothing about this error, I believe the next step up is the python httplib library.

----------

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

From report at bugs.python.org  Tue Dec 16 21:11:17 2014
From: report at bugs.python.org (R. David Murray)
Date: Tue, 16 Dec 2014 20:11:17 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
In-Reply-To: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>
Message-ID: <1418760677.87.0.473254724609.issue23054@psf.upfronthosting.co.za>


R. David Murray added the comment:

I wonder the actual error reported in that issue has any relationship to issue 15082?

In any case, the error being presented to requests is *accurate*: httplib tried to read the status line and got nothing (the actual text in the linked issue is BadStatusLine("''")).  (Note that issue 7427 was where we fixed the repr, if you are curious).

I see that requests would like "a better error message".  Is there a concrete suggestion for what that better error message would look like?

----------

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

From report at bugs.python.org  Tue Dec 16 21:15:39 2014
From: report at bugs.python.org (Antoine Pitrou)
Date: Tue, 16 Dec 2014 20:15:39 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418760939.47.0.295170735902.issue23049@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

I agree with Raymond. Examples in the code are not meant to be a reference but, well, examples. That is, the educational value should come first and strict adherence to the language spec only second.

"Roughly equivalent" is already used in the functools doc, it can probably be reused :-)

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

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

From report at bugs.python.org  Tue Dec 16 21:27:24 2014
From: report at bugs.python.org (Martin Panter)
Date: Tue, 16 Dec 2014 20:27:24 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
In-Reply-To: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>
Message-ID: <1418761644.91.0.515271094091.issue23054@psf.upfronthosting.co.za>


Martin Panter added the comment:

Not exactly sure what do you want the Python library to do, but perhaps this is a duplicate of Issue 8450, about making the error less misleading when the connection is closed before _any_ status line is sent. See also Issue 7427.

----------
nosy: +vadmium

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

From report at bugs.python.org  Tue Dec 16 23:29:23 2014
From: report at bugs.python.org (R. David Murray)
Date: Tue, 16 Dec 2014 22:29:23 +0000
Subject: [docs] [issue23054] ConnectionError: ('Connection aborted.',
	BadStatusLine(""''''"))
In-Reply-To: <1418654943.54.0.176050651858.issue23054@psf.upfronthosting.co.za>
Message-ID: <1418768963.66.0.530087897115.issue23054@psf.upfronthosting.co.za>


R. David Murray added the comment:

Ouch.  I assumed the change was made to the repr, not the contents of line (I wasn't involved in that fix).  Not that that would actually affect this issue, I think, since Requests doesn't want to "introspect exception objects".

----------

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

From report at bugs.python.org  Tue Dec 16 23:57:16 2014
From: report at bugs.python.org (Martin Panter)
Date: Tue, 16 Dec 2014 22:57:16 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418770636.35.0.11657145904.issue21071@psf.upfronthosting.co.za>


Martin Panter added the comment:

It seems to me that the simplest fix is to document:

1. Struct.format attribute is a byte string
2. The input format strings for struct.pack(), Struct class, etc, are also allowed to be byte strings, for consistency (Issue 16349)

Here is a patch that does that, and adds some simple test cases.

----------
keywords: +patch
Added file: http://bugs.python.org/file37474/format-bytes.patch

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

From report at bugs.python.org  Wed Dec 17 00:29:01 2014
From: report at bugs.python.org (Martijn Pieters)
Date: Tue, 16 Dec 2014 23:29:01 +0000
Subject: [docs] [issue17876] Doc issue with threading.Event
In-Reply-To: <1367301985.85.0.51301072011.issue17876@psf.upfronthosting.co.za>
Message-ID: <1418772540.96.0.514453020385.issue17876@psf.upfronthosting.co.za>


Martijn Pieters added the comment:

I notice that the same issue still exists in the 3.5 documentation. Surely this can at least be fixed in the development copy?

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

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

From report at bugs.python.org  Wed Dec 17 00:48:12 2014
From: report at bugs.python.org (R. David Murray)
Date: Tue, 16 Dec 2014 23:48:12 +0000
Subject: [docs] [issue17876] Doc issue with threading.Event
In-Reply-To: <1367301985.85.0.51301072011.issue17876@psf.upfronthosting.co.za>
Message-ID: <1418773692.23.0.442691171542.issue17876@psf.upfronthosting.co.za>


R. David Murray added the comment:

If there really is an issue in the 3.4/3.5 docs, you should open an new issue explaining what the problem is.  In 3.4/3.5, Event is a class, not a function, and is documented accordingly.

----------

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

From report at bugs.python.org  Wed Dec 17 00:49:47 2014
From: report at bugs.python.org (Martijn Pieters)
Date: Tue, 16 Dec 2014 23:49:47 +0000
Subject: [docs] [issue17876] Doc issue with threading.Event
In-Reply-To: <1367301985.85.0.51301072011.issue17876@psf.upfronthosting.co.za>
Message-ID: <1418773787.78.0.484746926933.issue17876@psf.upfronthosting.co.za>


Martijn Pieters added the comment:

Ah! Mea Culpa, you are correct. The issue is then with Python 2.7 only for which no doubt exists a separate ticket.

----------

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

From report at bugs.python.org  Wed Dec 17 02:13:20 2014
From: report at bugs.python.org (Martin Panter)
Date: Wed, 17 Dec 2014 01:13:20 +0000
Subject: [docs] [issue16776] Document PyCFunction_New and PyCFunction_NewEx
	functions
In-Reply-To: <1356434154.16.0.0981038830976.issue16776@psf.upfronthosting.co.za>
Message-ID: <1418778800.17.0.108259002635.issue16776@psf.upfronthosting.co.za>


Martin Panter added the comment:

I?m far from an expert on the C API, but I was looking for a way to inspect a ?builtin_function_or_method? a.k.a. PyCFunction_Type a.k.a. types.BuiltinMethodType, and ended up looking at the ?Instance Method Objects? section. So maybe your functions should go near there, or perhaps the nearby ?Function Objects? section.

----------
nosy: +vadmium

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

From report at bugs.python.org  Wed Dec 17 03:17:33 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 17 Dec 2014 02:17:33 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <20141217021724.92271.92861@psf.io>


Roundup Robot added the comment:

New changeset 0b3d69f15950 by Raymond Hettinger in branch '3.4':
Issue #23049:  Pure python equivalent shouldn't imply more exactitude than is really there.
https://hg.python.org/cpython/rev/0b3d69f15950

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

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

From report at bugs.python.org  Wed Dec 17 03:17:55 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Wed, 17 Dec 2014 02:17:55 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418782675.26.0.622518325851.issue23049@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/issue23049>
_______________________________________

From report at bugs.python.org  Wed Dec 17 03:51:07 2014
From: report at bugs.python.org (Ross Burnett)
Date: Wed, 17 Dec 2014 02:51:07 +0000
Subject: [docs] [issue23070] Error in Tutorial comment
Message-ID: <1418784667.28.0.75679477956.issue23070@psf.upfronthosting.co.za>


New submission from Ross Burnett:

In section "3.1.2. Strings" of the Tutorial (version 3.4 plus others?), a comment on a slicing error has an error:

"word[42]  # the word only has 7 characters"

It should say "word[42]  # the word has 6 characters"

----------
assignee: docs at python
components: Documentation
messages: 232795
nosy: docs at python, rossburnett
priority: normal
severity: normal
status: open
title: Error in Tutorial comment
versions: Python 3.4

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

From report at bugs.python.org  Wed Dec 17 03:51:42 2014
From: report at bugs.python.org (Martin Panter)
Date: Wed, 17 Dec 2014 02:51:42 +0000
Subject: [docs] [issue19737] Documentation of globals() and locals() should
	be	improved
In-Reply-To: <1385225461.09.0.671908077084.issue19737@psf.upfronthosting.co.za>
Message-ID: <1418784702.15.0.263122013714.issue19737@psf.upfronthosting.co.za>


Martin Panter added the comment:

Here is a patch with my suggestion. It also now refers to _the_ dictionary rather than just _a_ dictionary, and drops the word ?current?, so that it does not sound like saving a snapshot.

----------
keywords: +patch
Added file: http://bugs.python.org/file37478/globals-copy.patch

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

From report at bugs.python.org  Wed Dec 17 03:53:41 2014
From: report at bugs.python.org (Martin Panter)
Date: Wed, 17 Dec 2014 02:53:41 +0000
Subject: [docs] [issue19737] Documentation of globals() and locals() should
	be	improved
In-Reply-To: <1385225461.09.0.671908077084.issue19737@psf.upfronthosting.co.za>
Message-ID: <1418784821.39.0.0178375679414.issue19737@psf.upfronthosting.co.za>


Changes by Martin Panter <vadmium+py at gmail.com>:


Added file: http://bugs.python.org/file37479/globals-copy.patch

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

From report at bugs.python.org  Wed Dec 17 03:53:53 2014
From: report at bugs.python.org (Martin Panter)
Date: Wed, 17 Dec 2014 02:53:53 +0000
Subject: [docs] [issue19737] Documentation of globals() and locals() should
	be	improved
In-Reply-To: <1385225461.09.0.671908077084.issue19737@psf.upfronthosting.co.za>
Message-ID: <1418784833.3.0.435103990913.issue19737@psf.upfronthosting.co.za>


Changes by Martin Panter <vadmium+py at gmail.com>:


Removed file: http://bugs.python.org/file37478/globals-copy.patch

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

From report at bugs.python.org  Wed Dec 17 05:18:32 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Wed, 17 Dec 2014 04:18:32 +0000
Subject: [docs] [issue16893] Generate Idle help from Doc/library/idle.rst
In-Reply-To: <1357663512.19.0.739336896498.issue16893@psf.upfronthosting.co.za>
Message-ID: <1418789912.1.0.390363972019.issue16893@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

The goal of this issue is that Idle -> Help -> IDLE Help display a good-looking, accurate help page based on Doc/library/idle.rst.  The current Lib/idlelib/help.txt is neither good-looking nor accurate and must somehow be replaced, even if by temporary means, before another release (2.7.9 was missed, 3.4.3 is coming in January).

Ned's gave some comments on the alternatives in msg185726.  I am extending those (and in some places implicitly referring back to them) based on further thinking and investigation.  A summary of what I currently think might be best:

if Windows:
  open .chm to Idle page
else:
  try:
    open offline docs to Idle page
  except failure:
    open generated .txt without `s.

The easiest alternative would be to display the online python.org page in a browser.  It looks nice, has a sidebar index, and access to the rest of the docs.  An obvious problem is that this requires a browser and online access, either of which might be lacking in a classroom or when one is away from home base.  More subtle is that Idle features can be changed or added at any time.  The online docs, generated daily from the repository, should reflect the repository version of Idle.  Released versions need a doc frozen at the time of release.

Still easy, perhaps, would be building Doc/build/html/library/idle.html and copying it to idlelib/help.html as part of the release process*, and changing the code to display that instead 

However as Zack hinted ("clean up the output a bit"), this file is not a standalone file.  It has many links to files in '..', such as "Index" and "Copyright"; these would have to be removed completely as the text is useless without the link.  For cross-reference link, such as 'Tkinter' or 'sys.path', the text should be left but the linkage removed.  In both cases, clicking the link gives a File not Found page. The broken links to javascript formatting files in '../.source' appears to be ignored and the formatting simply not done.  So the page index is at the bottom of the page instead of the sidebar.

* The beginners who most need the help doc are running installed Python, not respository builds, so the latter concerns me less.

But why make an off-line page when there already is one in off-line docs?  I presume that the linux and osx doc urls just need 'index.html' replaced with '/library/idle.html'.  The 'standard location' for linux is x.y.z specific.  The python2 rpm location does not seem to be.  The osx location I will not guess about.

For Windows, startfile('x.chm') does the same as double-clicking x.chm in Explorer, which is to open the file with the Help Control, with a nice sidebar for contents, index, search, and favorites. Adding "::/library/idle.html" does not work because it makes the path invalid.  But with an special prefix

>>> os.startfile("mk:@MSITStore:c:/programs/Python34/Doc/python342.chm::/library/idle.html")

opens the page in InternetExplorer.  However, there is no sidebar and the page has to be clicked on the taskbar to make it visible.  In 1 of 4 tries, the above failed.

An answer to this StackOverflow question

https://stackoverflow.com/questions/11076952/open-chm-file-at-specific-page-topic-using-command-line-arguments?rq=1

prompted me to try

>>> subprocess.Popen("hh ms-its:c:/programs/Python34/Doc/python342.chm::/library/idle.html")

This opens the chm doc with the help control (and sidebar) to the Idle page, just as I wanted.  Since Doc/pythonxyz.chm is part of the installation, I think this is the solution for Windows.  The one glitch is that testing that the exact code in the repository works needs to be done with a pre-final install.  That is already true of testing that "Help -> Python docs F1" opens the .chm to the index page.  These both should be part of a new installed idle test file.

After generating html.txt from idle.rst, the backticks could be filtered out.  It would be close to what we have now.  Is there any need to keep it as a backup for non-Windows systems?  If not, I would be inclined to delete it.

For repository builds, users could go to the online Idle page.  I might even look for ../../Misc and if present, open it directly.  That page would be at most a day out of date.

----------
assignee:  -> terry.reedy

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

From jeff at jefftk.com  Mon Dec 15 21:17:39 2014
From: jeff at jefftk.com (Jeff Kaufman)
Date: Mon, 15 Dec 2014 15:17:39 -0500
Subject: [docs] filecmp.cmp "shallow" documentation
Message-ID: <CAK36jCO+ACCsqqhn7GaD=WMDKx3ASsxaoX48=YvDgAx9Txwm4Q@mail.gmail.com>

If you have two files with identical size, mode, and mtime,
filecmp.cmp will return them as equal with its "shallow" option, which
is on by default.  This is documented in 2.x as:

    Unless shallow is given and is false, files with identical os.stat()
    signatures are taken to be equal.

and in 3.x as:

    If shallow is true, files with identical os.stat() signatures are taken
    to be equal. Otherwise, the contents of the files are compared.

This doesn't explain what is included in the signature.  On initial
reading, I had thought it would do something like "os.stat(a) ==
os.stat(b)", but it instead pulls out just the size, mode, and mtime
for comparison.  Could we document this?  Perhaps:

-    ... files with identical os.stat() signatures are ...
+   ... files with identical size, mode, and mtime given by os.stat() are ..."

(This bit me with https://github.com/jeffkaufman/icdiff/issues/37
where I had thought inode number would be included in the stat
signature.)

From minfatt_chai at yahoo.com  Tue Dec 16 03:44:13 2014
From: minfatt_chai at yahoo.com (MinFatt Chai)
Date: Mon, 15 Dec 2014 18:44:13 -0800
Subject: [docs] Possible Bug?
Message-ID: <1418697853.31340.YahooMailNeo@web141502.mail.bf1.yahoo.com>

7781.50 - 7777.77 not getting 3.73 But 3.7299999999995634
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141215/ad5d7f43/attachment.html>

From vadmium+py at gmail.com  Tue Dec 16 21:50:28 2014
From: vadmium+py at gmail.com (vadmium+py at gmail.com)
Date: Tue, 16 Dec 2014 20:50:28 -0000
Subject: [docs] argparse required arguments displayed under "optional
	arguments" (issue 9694)
Message-ID: <20141216205028.2191.88507@psf.upfronthosting.co.za>


https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst
File Doc/library/argparse.rst (right):

https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst#newcode1711
Doc/library/argparse.rst:1711: "positional arguments" and "options" when
displaying help
Maybe I should also add a ?Changed in version 3.5? notice for this

https://bugs.python.org/review/9694/

From report at bugs.python.org  Wed Dec 17 07:17:35 2014
From: report at bugs.python.org (Berker Peksag)
Date: Wed, 17 Dec 2014 06:17:35 +0000
Subject: [docs] [issue23049] Fix functools.reduce code equivalent.
In-Reply-To: <1418516847.13.0.26860108886.issue23049@psf.upfronthosting.co.za>
Message-ID: <1418797055.23.0.279910802818.issue23049@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


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

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

From report at bugs.python.org  Wed Dec 17 10:49:38 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Wed, 17 Dec 2014 09:49:38 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1418809778.37.0.947453148595.issue19548@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
stage:  -> needs patch
type:  -> enhancement
versions: +Python 2.7, Python 3.5 -Python 3.3

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

From report at bugs.python.org  Wed Dec 17 13:57:46 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 17 Dec 2014 12:57:46 +0000
Subject: [docs] [issue23070] Error in Tutorial comment
In-Reply-To: <1418784667.28.0.75679477956.issue23070@psf.upfronthosting.co.za>
Message-ID: <20141217125629.50111.22087@psf.io>


Roundup Robot added the comment:

New changeset 81c73f964066 by Berker Peksag in branch '3.4':
Issue #23070: Fix a comment in the tutorial.
https://hg.python.org/cpython/rev/81c73f964066

New changeset 81e2f58d9e4b by Berker Peksag in branch 'default':
Issue #23070: Fix a comment in the tutorial.
https://hg.python.org/cpython/rev/81e2f58d9e4b

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

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

From report at bugs.python.org  Wed Dec 17 13:58:57 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 17 Dec 2014 12:58:57 +0000
Subject: [docs] [issue23070] Error in Tutorial comment
In-Reply-To: <1418784667.28.0.75679477956.issue23070@psf.upfronthosting.co.za>
Message-ID: <20141217125847.18159.88098@psf.io>


Roundup Robot added the comment:

New changeset 8cd84e62c1fd by Berker Peksag in branch '2.7':
Issue #23070: Fix a comment in the tutorial.
https://hg.python.org/cpython/rev/8cd84e62c1fd

----------

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

From report at bugs.python.org  Wed Dec 17 14:00:05 2014
From: report at bugs.python.org (Berker Peksag)
Date: Wed, 17 Dec 2014 13:00:05 +0000
Subject: [docs] [issue23070] Error in Tutorial comment
In-Reply-To: <1418784667.28.0.75679477956.issue23070@psf.upfronthosting.co.za>
Message-ID: <1418821205.68.0.431770608401.issue23070@psf.upfronthosting.co.za>


Berker Peksag added the comment:

Fixed. Thanks for the report, Ross.

----------
nosy: +berker.peksag
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
type:  -> behavior
versions: +Python 2.7, Python 3.5

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

From berker.peksag at gmail.com  Wed Dec 17 06:24:42 2014
From: berker.peksag at gmail.com (berker.peksag at gmail.com)
Date: Wed, 17 Dec 2014 05:24:42 -0000
Subject: [docs] argparse required arguments displayed under "optional
 arguments" (issue 9694)
Message-ID: <20141217052442.19910.43697@psf.upfronthosting.co.za>


https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst
File Doc/library/argparse.rst (right):

https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst#newcode1711
Doc/library/argparse.rst:1711: "positional arguments" and "options" when
displaying help
On 2014/12/16 21:50:28, vadmium wrote:
> Maybe I should also add a ?Changed in version 3.5? notice for this

+1. That would be good.

https://bugs.python.org/review/9694/

From bctpapa at aol.com  Wed Dec 17 20:58:31 2014
From: bctpapa at aol.com (bctpapa at aol.com)
Date: Wed, 17 Dec 2014 14:58:31 -0500
Subject: [docs] print command
Message-ID: <8D1E84AF7D12356-1054-F16F@webmail-vm184.sysops.aol.com>

I am experimenting with Python step by step. The very first step in the Python for Dummies is >>>Print.  This gives me an error message. Any command of print gives an error.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141217/366b1f82/attachment.html>

From report at bugs.python.org  Wed Dec 17 22:28:40 2014
From: report at bugs.python.org (bbc)
Date: Wed, 17 Dec 2014 21:28:40 +0000
Subject: [docs] [issue23073] Broken turtle example in Cmd documentation
Message-ID: <1418851720.64.0.216827601034.issue23073@psf.upfronthosting.co.za>


New submission from bbc:

The documentation page for the cmd module contains an example with the turtle module:

https://docs.python.org/3.4/library/cmd.html#cmd-example

It seems like the turtle module has changed quite a bit since the code was written, and exposes a Pen class instead of all the various movement functions.  The example, while still useful, cannot be executed as is.

I like the example and would be happy to provide an idiomatic replacement if you think this is necessary.

----------
assignee: docs at python
components: Documentation
messages: 232829
nosy: bbc, docs at python
priority: normal
severity: normal
status: open
title: Broken turtle example in Cmd documentation
type: behavior
versions: Python 3.4

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

From report at bugs.python.org  Thu Dec 18 00:29:13 2014
From: report at bugs.python.org (Ethan Furman)
Date: Wed, 17 Dec 2014 23:29:13 +0000
Subject: [docs] [issue23073] Broken turtle example in Cmd documentation
In-Reply-To: <1418851720.64.0.216827601034.issue23073@psf.upfronthosting.co.za>
Message-ID: <1418858953.29.0.617300801646.issue23073@psf.upfronthosting.co.za>


Ethan Furman added the comment:

Please do!  Working examples are better than non-working ones.  :)

----------
nosy: +ethan.furman

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

From report at bugs.python.org  Thu Dec 18 00:30:48 2014
From: report at bugs.python.org (Ethan Furman)
Date: Wed, 17 Dec 2014 23:30:48 +0000
Subject: [docs] [issue23073] Broken turtle example in Cmd documentation
In-Reply-To: <1418851720.64.0.216827601034.issue23073@psf.upfronthosting.co.za>
Message-ID: <1418859048.92.0.426903457721.issue23073@psf.upfronthosting.co.za>


Ethan Furman added the comment:

While you're at it, could you also sign the contributors' license agreement?

https://www.python.org/psf/contrib/contrib-form/

----------

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

From report at bugs.python.org  Thu Dec 18 00:56:28 2014
From: report at bugs.python.org (STINNER Victor)
Date: Wed, 17 Dec 2014 23:56:28 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418860588.32.0.0269241215165.issue21071@psf.upfronthosting.co.za>


STINNER Victor added the comment:

> It would be backwards incompatible to change, though.

I'm in favor of breaking the compatibility with Python 3.4 and return the format as an Unicode string.

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

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

From report at bugs.python.org  Thu Dec 18 01:17:19 2014
From: report at bugs.python.org (Martin Panter)
Date: Thu, 18 Dec 2014 00:17:19 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418861839.57.0.832104732761.issue21071@psf.upfronthosting.co.za>


Martin Panter added the comment:

I originally assumed it would be a text string from the existing documentation, so changing the behaviour to match also seems reasonable

----------

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

From report at bugs.python.org  Thu Dec 18 01:42:25 2014
From: report at bugs.python.org (bbc)
Date: Thu, 18 Dec 2014 00:42:25 +0000
Subject: [docs] [issue23073] Broken turtle example in Cmd documentation
In-Reply-To: <1418851720.64.0.216827601034.issue23073@psf.upfronthosting.co.za>
Message-ID: <1418863344.96.0.726343622065.issue23073@psf.upfronthosting.co.za>


bbc added the comment:

It turns out the script is fine.  I could have investigated it more thoroughly at first if I had more carefully read the docs for turtle.

I thought those functions were not exposed because they were reportedly not found after I copy-pasted, executed the example script and entered commands.  The reason was my file was named turtle.py.

Sorry for the noise.

----------

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

From report at bugs.python.org  Thu Dec 18 01:44:11 2014
From: report at bugs.python.org (Ethan Furman)
Date: Thu, 18 Dec 2014 00:44:11 +0000
Subject: [docs] [issue23073] Broken turtle example in Cmd documentation
In-Reply-To: <1418851720.64.0.216827601034.issue23073@psf.upfronthosting.co.za>
Message-ID: <1418863451.78.0.401321730509.issue23073@psf.upfronthosting.co.za>


Ethan Furman added the comment:

No worries, thanks for following up.

----------
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

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

From report at bugs.python.org  Thu Dec 18 03:21:08 2014
From: report at bugs.python.org (Martin Panter)
Date: Thu, 18 Dec 2014 02:21:08 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1418869267.88.0.885938002462.issue19548@psf.upfronthosting.co.za>


Martin Panter added the comment:

Here is a patch addressing many of the points raised. Please have a look and give any feedback. Beware I am not very familiar with the Restructured Text markup and haven?t tried compiling it.

1. Mentioned bytes-to-bytes and text-to-text in general right at the top. Any APIs (e.g. see Issue 20132) that don't support them should be pointed out as exceptions to the rule.

8. The underlying mode is forced to binary, so 'r' is the same as 'rb'. I removed the 'b' from the signature for clarity.

## Jan?s points not yet addressed: ##

3. I expect the built-in open() function would already be much more obvious and advertised, so I didn't add any cross-reference from codecs.open().

5. Both points still need addressing:
  * Lack of requirement for implementing incremental codecs
  * Responsibility of implementing error handlers

9. First point left unaddressed:
  * register_error() error_handler replacement data type (unsure of details)

## Numbering Nick?s points: ##

12. Codec name normalization: Not addressed; what should be written?

[13. Registration not reversible: Added in patch]

[14. Added CodecInfo class, pulling out some existing details from register().]

15. ?encodings? module: not done

16. Import system: not done

## My (Martin?s) point: ##

[17. IncrementalEncoder.reset(): done]

## Zoinkity?s points, not addressed: ##

18. Multibyte codecs

19. register() usage example

## Some new points of my own that need fixing: ##

20. The doc string for register() says the search function is also allowed to return a tuple of functions, but the reference manual does not mention this. Which is more accurate? (I notice CodecInfo is a subclass of ?tuple?.)

21. EncodedFile() seems to return StreamRecoder instances. Perhaps move them closer together? Should probably warn that EncodedFile's data_encoding is handled by a stateless codec.

22. The Codec.encode() and decode() methods return a length consumed, but I suspect they have to consume everything they are supplied because the code I have seen ignores this return value.

----------
keywords: +patch
Added file: http://bugs.python.org/file37485/codecs-doc.patch

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

From report at bugs.python.org  Thu Dec 18 03:27:23 2014
From: report at bugs.python.org (Martin Panter)
Date: Thu, 18 Dec 2014 02:27:23 +0000
Subject: [docs] [issue19539] The 'raw_unicode_escape' codec buggy + not
	appropriate	for Python 3.x
In-Reply-To: <1384051905.56.0.969775270474.issue19539@psf.upfronthosting.co.za>
Message-ID: <1418869643.65.0.0205262185798.issue19539@psf.upfronthosting.co.za>


Martin Panter added the comment:

I included the proposed doc fix in my patch for Issue 19548

----------
nosy: +vadmium

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

From report at bugs.python.org  Thu Dec 18 03:56:40 2014
From: report at bugs.python.org (Berker Peksag)
Date: Thu, 18 Dec 2014 02:56:40 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1418871400.07.0.6466868594.issue19548@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


----------
nosy: +berker.peksag
stage: needs patch -> patch review

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

From report at bugs.python.org  Thu Dec 18 05:14:07 2014
From: report at bugs.python.org (Martin Panter)
Date: Thu, 18 Dec 2014 04:14:07 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1418876047.72.0.153587798126.issue21279@psf.upfronthosting.co.za>


Martin Panter added the comment:

Here is a new patch based on John?s suggestion

----------
Added file: http://bugs.python.org/file37487/issue21279.patch

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

From report at bugs.python.org  Thu Dec 18 06:25:00 2014
From: report at bugs.python.org (Martin Panter)
Date: Thu, 18 Dec 2014 05:25:00 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418880300.53.0.182606524162.issue21071@psf.upfronthosting.co.za>


Martin Panter added the comment:

Here is a patch that changes over to a str() type.

Is it safe to assume PyUnicode_AsUTF8() is null-terminated (like PyBytes_AS_STRING() is)? My documentation doesn?t say.

----------
Added file: http://bugs.python.org/file37488/format-str.patch

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

From vadmium+py at gmail.com  Thu Dec 18 06:32:15 2014
From: vadmium+py at gmail.com (vadmium+py at gmail.com)
Date: Thu, 18 Dec 2014 05:32:15 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141218053215.19910.7650@psf.upfronthosting.co.za>


https://bugs.python.org/review/19548/diff/13445/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

https://bugs.python.org/review/19548/diff/13445/Doc/library/codecs.rst#newcode74
Doc/library/codecs.rst:74: .. data:: name
Looking at other files I guess the syntax here is meant to be ..
attribute::, not .. data::

https://bugs.python.org/review/19548/

From report at bugs.python.org  Thu Dec 18 09:13:13 2014
From: report at bugs.python.org (STINNER Victor)
Date: Thu, 18 Dec 2014 08:13:13 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1418880300.53.0.182606524162.issue21071@psf.upfronthosting.co.za>
Message-ID: <CAMpsgwYGap_NJk8uboi58jiqzHd2kgyMqHEpL-nTfqGqrJ82sA@mail.gmail.com>


STINNER Victor added the comment:

> Is it safe to assume PyUnicode_AsUTF8() is null-terminated?

Yes, Python ensures that the string is null terminated.

> (like PyBytes_AS_STRING() is)

Yes, PyBytes_AS_STRING() also ends with a null byte.

By the way, Unicode strings internally ends with a null character.

----------

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

From report at bugs.python.org  Thu Dec 18 11:04:04 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Thu, 18 Dec 2014 10:04:04 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418897044.36.0.220393651692.issue21071@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

I think breaking the compatibility should be discussed on Python-Dev. Similar issue (and even worse) is issue8934.

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

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

From report at bugs.python.org  Thu Dec 18 13:02:11 2014
From: report at bugs.python.org (Chris Jerdonek)
Date: Thu, 18 Dec 2014 12:02:11 +0000
Subject: [docs] [issue23079] os.path.normcase documentation confusing
Message-ID: <1418904131.32.0.416083778815.issue23079@psf.upfronthosting.co.za>


New submission from Chris Jerdonek:

The documentation for os.path.normcase(path) is currently confusing or self-contradictory.

Currently, it reads--

"Normalize the case of a pathname. On Unix and Mac OS X, this returns the path unchanged; on case-insensitive filesystems, it converts the path to lowercase."

However, with a case-insensitive file system on Mac OS X (e.g. "File System Personality: Journaled HFS+"), normcase() does not convert paths to lowercase.

As it stands, it seems like the clause "on case-insensitive filesystems, it converts the path to lowercase" should be removed or further qualified.  I don't know what the qualification is though.

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 232871
nosy: chris.jerdonek, docs at python
priority: normal
severity: normal
status: open
title: os.path.normcase documentation confusing
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5

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

From report at bugs.python.org  Thu Dec 18 13:16:09 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Thu, 18 Dec 2014 12:16:09 +0000
Subject: [docs] [issue23079] os.path.normcase documentation confusing
In-Reply-To: <1418904131.32.0.416083778815.issue23079@psf.upfronthosting.co.za>
Message-ID: <1418904969.04.0.316295126062.issue23079@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

s/on case-insensitive filesystems/on Windows/ ?

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

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

From report at bugs.python.org  Thu Dec 18 13:18:34 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Thu, 18 Dec 2014 12:18:34 +0000
Subject: [docs] [issue23079] os.path.normcase documentation confusing
In-Reply-To: <1418904131.32.0.416083778815.issue23079@psf.upfronthosting.co.za>
Message-ID: <1418905114.03.0.915709501192.issue23079@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

... and OS/2 (in 2.7).

----------

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

From report at bugs.python.org  Thu Dec 18 14:15:20 2014
From: report at bugs.python.org (Lars Buitinck)
Date: Thu, 18 Dec 2014 13:15:20 +0000
Subject: [docs] [issue23081] Document PySequence_List(o) as equivalent to
	list(o)
Message-ID: <1418908520.28.0.480794985208.issue23081@psf.upfronthosting.co.za>


New submission from Lars Buitinck:

PySequence_List has accepted iterables since changeset 6c82277e77f3 of May 1, 2001 ("NEEDS DOC CHANGES" :), but its documentation still only speaks of sequences. I suggest that it is changed to promise to handle arbitrary iterables, just like PySequence_Tuple.

----------
assignee: docs at python
components: Documentation
files: PySequence_List-doc.patch
keywords: patch
messages: 232875
nosy: docs at python, larsmans
priority: normal
severity: normal
status: open
title: Document PySequence_List(o) as equivalent to list(o)
versions: Python 3.5
Added file: http://bugs.python.org/file37493/PySequence_List-doc.patch

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

From report at bugs.python.org  Thu Dec 18 15:17:33 2014
From: report at bugs.python.org (R. David Murray)
Date: Thu, 18 Dec 2014 14:17:33 +0000
Subject: [docs] [issue23079] os.path.normcase documentation confusing
In-Reply-To: <1418904131.32.0.416083778815.issue23079@psf.upfronthosting.co.za>
Message-ID: <1418912253.2.0.436670845171.issue23079@psf.upfronthosting.co.za>


R. David Murray added the comment:

Or would s/case-insensitive/not case-preserving/ be more accurate?  (Well, you'd probably rewrite the sentence to eliminate the 'not').

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

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

From report at bugs.python.org  Thu Dec 18 15:21:01 2014
From: report at bugs.python.org (R. David Murray)
Date: Thu, 18 Dec 2014 14:21:01 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418912461.23.0.157153983738.issue21071@psf.upfronthosting.co.za>


R. David Murray added the comment:

A backward compatibility break would certainly need to be discussed, IMO.

----------

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

From report at bugs.python.org  Thu Dec 18 15:46:41 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Thu, 18 Dec 2014 14:46:41 +0000
Subject: [docs] [issue23079] os.path.normcase documentation confusing
In-Reply-To: <1418912253.2.0.436670845171.issue23079@psf.upfronthosting.co.za>
Message-ID: <1583671.jtY2RXP0F0@raxxla>


Serhiy Storchaka added the comment:

> Or would s/case-insensitive/not case-preserving/ be more accurate?  (Well,
> you'd probably rewrite the sentence to eliminate the 'not').

This would not be more accurate because behavior depends from OS, not from file 
system. On Unix/Linux your can mount case-insensitive filesystem, but 
normcase() doesn't know anything about this.

----------

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

From report at bugs.python.org  Thu Dec 18 16:06:24 2014
From: report at bugs.python.org (Polux Moon)
Date: Thu, 18 Dec 2014 15:06:24 +0000
Subject: [docs] [issue23083] sys.exit with bool parameter
Message-ID: <1418915184.17.0.474799432406.issue23083@psf.upfronthosting.co.za>


New submission from Polux Moon:

when using a bool as parameter implementation (2.7) behave like:
sys.exit(True) <=> sys.exit(1)
sys.exit(False) <=> sys.exit(0)

so the bool indicate if the termination is abnormal

following the doc it should be equivalent to sys.exit(1) in all cases
if we assume the implementation is right, the doc should describe the behavior for boolean input

----------
assignee: docs at python
components: Documentation
messages: 232883
nosy: Polux.Moon, docs at python
priority: normal
severity: normal
status: open
title: sys.exit with bool parameter
type: enhancement
versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6

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

From report at bugs.python.org  Thu Dec 18 16:15:54 2014
From: report at bugs.python.org (R. David Murray)
Date: Thu, 18 Dec 2014 15:15:54 +0000
Subject: [docs] [issue23083] sys.exit with bool parameter
In-Reply-To: <1418915184.17.0.474799432406.issue23083@psf.upfronthosting.co.za>
Message-ID: <1418915753.99.0.457821782871.issue23083@psf.upfronthosting.co.za>


R. David Murray added the comment:

>>> issubclass(bool, int)
True
>>> True == 1
True
[41846 refs]
>>> False == 0
True

This is fundamental to Python, so it is not obvious that it is a good idea to mention bool explicitly in the sys.exit docs.  Perhaps we could change it to say "int (or an int subclass such as bool)".

----------
nosy: +r.david.murray
versions:  -Python 3.2, Python 3.3, Python 3.6

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

From report at bugs.python.org  Thu Dec 18 16:17:02 2014
From: report at bugs.python.org (Eric V. Smith)
Date: Thu, 18 Dec 2014 15:17:02 +0000
Subject: [docs] [issue23083] sys.exit with bool parameter
In-Reply-To: <1418915184.17.0.474799432406.issue23083@psf.upfronthosting.co.za>
Message-ID: <1418915822.02.0.579098705141.issue23083@psf.upfronthosting.co.za>


Eric V. Smith added the comment:

I'm not sure this should be documented. It follows from int and bool equivalence. Plus, I consider it an anti-pattern.

We don't want to document everywhere you can pass a bool where an int is called for. That's thousands of places.

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

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

From report at bugs.python.org  Thu Dec 18 16:20:45 2014
From: report at bugs.python.org (R. David Murray)
Date: Thu, 18 Dec 2014 15:20:45 +0000
Subject: [docs] [issue23083] sys.exit with bool parameter
In-Reply-To: <1418915184.17.0.474799432406.issue23083@psf.upfronthosting.co.za>
Message-ID: <1418916044.98.0.987816091523.issue23083@psf.upfronthosting.co.za>


R. David Murray added the comment:

Hmm.  Good point about the anti-pattern.  I agree that it is probably best to leave the docs as they are.

----------

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

From report at bugs.python.org  Thu Dec 18 16:58:46 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Thu, 18 Dec 2014 15:58:46 +0000
Subject: [docs] [issue23083] sys.exit with bool parameter
In-Reply-To: <1418915184.17.0.474799432406.issue23083@psf.upfronthosting.co.za>
Message-ID: <1418918326.73.0.868465524982.issue23083@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

I agree that the docs are best as-is.

----------
nosy: +rhettinger
resolution:  -> rejected
status: open -> closed

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

From report at bugs.python.org  Thu Dec 18 18:45:15 2014
From: report at bugs.python.org (Eric V. Smith)
Date: Thu, 18 Dec 2014 17:45:15 +0000
Subject: [docs] [issue23083] sys.exit with bool parameter
In-Reply-To: <1418915184.17.0.474799432406.issue23083@psf.upfronthosting.co.za>
Message-ID: <1418924715.78.0.103758675048.issue23083@psf.upfronthosting.co.za>


Changes by Eric V. Smith <eric at trueblade.com>:


----------
stage:  -> resolved

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

From report at bugs.python.org  Fri Dec 19 01:17:51 2014
From: report at bugs.python.org (Arfrever Frehtes Taifersar Arahesis)
Date: Fri, 19 Dec 2014 00:17:51 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1418948271.2.0.432819784387.issue21071@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/issue21071>
_______________________________________

From berker.peksag at gmail.com  Fri Dec 19 03:13:58 2014
From: berker.peksag at gmail.com (berker.peksag at gmail.com)
Date: Fri, 19 Dec 2014 02:13:58 -0000
Subject: [docs] Document PySequence_List(o) as equivalent to list(o) (issue
	23081)
Message-ID: <20141219021358.26198.806@psf.upfronthosting.co.za>


http://bugs.python.org/review/23081/diff/13453/Doc/c-api/sequence.rst
File Doc/c-api/sequence.rst (right):

http://bugs.python.org/review/23081/diff/13453/Doc/c-api/sequence.rst#newcode111
Doc/c-api/sequence.rst:111: or *NULL* on failure.  The returned list is
guaranteed to be new.  This is
*NULL* -> ``NULL``

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

From report at bugs.python.org  Fri Dec 19 03:15:34 2014
From: report at bugs.python.org (Berker Peksag)
Date: Fri, 19 Dec 2014 02:15:34 +0000
Subject: [docs] [issue23081] Document PySequence_List(o) as equivalent to
	list(o)
In-Reply-To: <1418908520.28.0.480794985208.issue23081@psf.upfronthosting.co.za>
Message-ID: <1418955334.71.0.561203721953.issue23081@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


----------
nosy: +berker.peksag, tim.peters

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

From report at bugs.python.org  Fri Dec 19 05:42:34 2014
From: report at bugs.python.org (Martin Panter)
Date: Fri, 19 Dec 2014 04:42:34 +0000
Subject: [docs] [issue23088] Document that PyUnicode_AsUTF8() returns
	a	null-terminated string
Message-ID: <1418964154.65.0.595903967697.issue23088@psf.upfronthosting.co.za>


New submission from Martin Panter:

As discussed in msg232863, and later confirmed in the code

----------
assignee: docs at python
components: Documentation
files: utf8-null.patch
keywords: patch
messages: 232925
nosy: docs at python, vadmium
priority: normal
severity: normal
status: open
title: Document that PyUnicode_AsUTF8() returns a null-terminated string
versions: Python 3.4
Added file: http://bugs.python.org/file37502/utf8-null.patch

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

From report at bugs.python.org  Fri Dec 19 06:14:30 2014
From: report at bugs.python.org (Martin Panter)
Date: Fri, 19 Dec 2014 05:14:30 +0000
Subject: [docs] [issue22341] Python 3 crc32 documentation clarifications
In-Reply-To: <1409918129.4.0.321897542374.issue22341@psf.upfronthosting.co.za>
Message-ID: <1418966070.05.0.526031070029.issue22341@psf.upfronthosting.co.za>


Martin Panter added the comment:

Here is a patch that fixes the binascii, zlib.crc32() and adler32() documentation as I suggested.

I?m still interested why there are two ways to do a CRC-32, each equally non-obvious as the other.

----------
keywords: +patch
Added file: http://bugs.python.org/file37504/crc-sign.patch

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

From report at bugs.python.org  Fri Dec 19 06:24:13 2014
From: report at bugs.python.org (Martin Panter)
Date: Fri, 19 Dec 2014 05:24:13 +0000
Subject: [docs] [issue9694] argparse required arguments displayed under
	"optional	arguments"
In-Reply-To: <1282846759.11.0.900867962743.issue9694@psf.upfronthosting.co.za>
Message-ID: <1418966650.58.0.259474860247.issue9694@psf.upfronthosting.co.za>


Martin Panter added the comment:

Updated my patch with a ?version changed? notice

----------
Added file: http://bugs.python.org/file37505/option-internal.patch

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

From report at bugs.python.org  Fri Dec 19 15:58:58 2014
From: report at bugs.python.org (John Posner)
Date: Fri, 19 Dec 2014 14:58:58 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419001138.18.0.93427051912.issue21279@psf.upfronthosting.co.za>


John Posner added the comment:

Regarding Martin's patch of 12-18:

stdtypes.rst -- looks good to me

unicodeobject.c -- I suggest changing this sentence:

If a character is not in the table, the subscript operation should raise LookupError, and the character is left untouched.

 ... to:

If the subscript operation raises a LookupError, the character is left untouched.

----------

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

From report at bugs.python.org  Fri Dec 19 23:06:11 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Fri, 19 Dec 2014 22:06:11 +0000
Subject: [docs] [issue23061] Update pep8 to specify explicitly 'module
	level' imports	at top of file
In-Reply-To: <1418703864.09.0.281927050653.issue23061@psf.upfronthosting.co.za>
Message-ID: <1419026771.7.0.585369050048.issue23061@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

I read Nick's post and I would like PEP8 to continue to discourage imports at class scope unless there is actually a use case.  I discovered yesterday that idlelib.ColorDelegator has several imports at the top of the module and more as the top of the class (of the same name).  I cannot think of any good reason for the split.

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

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

From report at bugs.python.org  Sat Dec 20 03:11:01 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Sat, 20 Dec 2014 02:11:01 +0000
Subject: [docs] [issue21071] struct.Struct.format is bytes, but should be str
In-Reply-To: <1395856133.5.0.672707015318.issue21071@psf.upfronthosting.co.za>
Message-ID: <1419041460.93.0.877523639206.issue21071@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

I would like to see this and issue 8934 discussed as a usability bug.  As far as I can tell, the current state of affairs an unintended by-product of a rushed effort to split the standard library to bytes apis and unicode apis.  I don't see any reason that we should have to live with this forever.

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

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

From report at bugs.python.org  Sat Dec 20 08:06:15 2014
From: report at bugs.python.org (Chandan kumar)
Date: Sat, 20 Dec 2014 07:06:15 +0000
Subject: [docs] [issue22671] Typo in class io.BufferedIOBase docs
In-Reply-To: <1413711352.27.0.0253692424247.issue22671@psf.upfronthosting.co.za>
Message-ID: <1419059175.9.0.888487853635.issue22671@psf.upfronthosting.co.za>


Changes by Chandan kumar <chkumar246 at gmail.com>:


----------
nosy: +Chandan.kumar

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

From report at bugs.python.org  Sat Dec 20 13:30:29 2014
From: report at bugs.python.org (Martin Panter)
Date: Sat, 20 Dec 2014 12:30:29 +0000
Subject: [docs] [issue22671] Typo in class io.BufferedIOBase docs
In-Reply-To: <1413711352.27.0.0253692424247.issue22671@psf.upfronthosting.co.za>
Message-ID: <1419078629.55.0.485596151979.issue22671@psf.upfronthosting.co.za>


Martin Panter added the comment:

The documentation was technically correct but too scanty. RawIOBase.read(-1) does defer to readall(), but with a proper size passed, it defers to readinto() instead. Here is a patch which hopefully clarifies this, and also explains which methods have a usable default implementation. Includes some tests for RawIOBase and BufferedIOBase which didn?t seem to be there already.

----------
keywords: +patch
nosy: +vadmium
Added file: http://bugs.python.org/file37515/read-defaults.patch

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

From report at bugs.python.org  Sat Dec 20 23:33:25 2014
From: report at bugs.python.org (STINNER Victor)
Date: Sat, 20 Dec 2014 22:33:25 +0000
Subject: [docs] [issue23088] Document that PyUnicode_AsUTF8() returns
	a	null-terminated string
In-Reply-To: <1418964154.65.0.595903967697.issue23088@psf.upfronthosting.co.za>
Message-ID: <1419114805.21.0.48746623613.issue23088@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/issue23088>
_______________________________________

From report at bugs.python.org  Sun Dec 21 02:19:20 2014
From: report at bugs.python.org (Martin Panter)
Date: Sun, 21 Dec 2014 01:19:20 +0000
Subject: [docs] [issue12600] Add example of using load_tests to parameterise
	Test	Cases
In-Reply-To: <1311226769.48.0.369455670372.issue12600@psf.upfronthosting.co.za>
Message-ID: <1419124758.08.0.199553248041.issue12600@psf.upfronthosting.co.za>


Changes by Martin Panter <vadmium+py at gmail.com>:


----------
nosy: +vadmium

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

From report at bugs.python.org  Sun Dec 21 02:50:28 2014
From: report at bugs.python.org (Martin Panter)
Date: Sun, 21 Dec 2014 01:50:28 +0000
Subject: [docs] [issue22673] document the special features (eg:
	fdclose=False) of the	standard streams
In-Reply-To: <1413745258.02.0.518044907787.issue22673@psf.upfronthosting.co.za>
Message-ID: <1419126628.92.0.734461025121.issue22673@psf.upfronthosting.co.za>


Changes by Martin Panter <vadmium+py at gmail.com>:


----------
nosy: +vadmium

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

From report at bugs.python.org  Sun Dec 21 09:50:48 2014
From: report at bugs.python.org (Martin Panter)
Date: Sun, 21 Dec 2014 08:50:48 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419151848.58.0.455835181135.issue21279@psf.upfronthosting.co.za>


Martin Panter added the comment:

Patch v4 with John?s doc string wording

----------
Added file: http://bugs.python.org/file37522/issue21279.v4.patch

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

From report at bugs.python.org  Sun Dec 21 16:58:49 2014
From: report at bugs.python.org (John Posner)
Date: Sun, 21 Dec 2014 15:58:49 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419177529.03.0.258196797525.issue21279@psf.upfronthosting.co.za>


John Posner added the comment:

Patch of 12-21 looks good, Martin.

----------

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

From report at bugs.python.org  Sun Dec 21 17:59:26 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Sun, 21 Dec 2014 16:59:26 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419181165.9.0.117431387835.issue21279@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

Proposed wording looks superfluously verbose to me.

Look also at description in Include/unicodeobject.h:

/* Translate a string by applying a character mapping table to it and
   return the resulting Unicode object.

   The mapping table must map Unicode ordinal integers to Unicode
   ordinal integers or None (causing deletion of the character).

   Mapping tables may be dictionaries or sequences. Unmapped character
   ordinals (ones which cause a LookupError) are left untouched and
   are copied as-is.

*/

It is repeated (more detailed) in Doc/c-api/unicode.rst. Isn't it pretty clear?

----------
components: +Unicode
nosy: +ezio.melotti, georg.brandl, haypo, serhiy.storchaka

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

From vadmium+py at gmail.com  Sun Dec 21 04:22:35 2014
From: vadmium+py at gmail.com (vadmium+py at gmail.com)
Date: Sun, 21 Dec 2014 03:22:35 -0000
Subject: [docs] Typo in class io.BufferedIOBase docs (issue 22671)
Message-ID: <20141221032235.19910.66485@psf.upfronthosting.co.za>


https://bugs.python.org/review/22671/diff/13472/Doc/library/io.rst
File Doc/library/io.rst (right):

https://bugs.python.org/review/22671/diff/13472/Doc/library/io.rst#newcode495
Doc/library/io.rst:495: A default implementation is provided.
Just noticed the summary of mixin methods near the top of the page. Need
to add readinto1() there, but maybe all of this ?default implementation
provided? is not needed after all.

https://bugs.python.org/review/22671/

From report at bugs.python.org  Sun Dec 21 23:05:30 2014
From: report at bugs.python.org (Martin Panter)
Date: Sun, 21 Dec 2014 22:05:30 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419199530.2.0.500289468832.issue21279@psf.upfronthosting.co.za>


Martin Panter added the comment:

Serhiy can you point out which bits are too verbose? Perhaps you prefer it without the bullet list like in the earlier 2014-12-13 version of the patch.

Looking at the C API, I see a couple problems there:
* Omits mentioning that an ordinal can map to a replacement string
* It looks like the documented None behaviour applies when errors="ignore", otherwise it invokes a codec error handler

----------

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

From report at bugs.python.org  Mon Dec 22 07:01:56 2014
From: report at bugs.python.org (Martin Panter)
Date: Mon, 22 Dec 2014 06:01:56 +0000
Subject: [docs] [issue19539] The 'raw_unicode_escape' codec buggy + not
	appropriate	for Python 3.x
In-Reply-To: <1384051905.56.0.969775270474.issue19539@psf.upfronthosting.co.za>
Message-ID: <1419228116.31.0.0723368338311.issue19539@psf.upfronthosting.co.za>


Martin Panter added the comment:

[Edit Error: 'utf8' codec can't decode byte 0xe2 in position 212: invalid continuation byte]


Re-reading the suggested description, it struck me that for encoding, this is redundant with the ?backslashreplace? error handler:

>>> test = "".join(map(chr, range(sys.maxunicode + 1)))
>>> test.encode("raw-unicode-escape") == test.encode("latin-1", "backslashreplace")
True

However, decoding also seems similar to ?unicode_escape?, except that only \uXXXX and \UXXXXXXXX seem to be supported.

Maybe there should be a warning that backslashes are not escaped:

>>> "\\u005C".encode("raw-unicode-escape").decode("raw-unicode-escape")
'\\'

----------

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

From report at bugs.python.org  Mon Dec 22 07:04:40 2014
From: report at bugs.python.org (Ian Lee)
Date: Mon, 22 Dec 2014 06:04:40 +0000
Subject: [docs] [issue23061] Update pep8 to specify explicitly 'module
	level' imports	at top of file
In-Reply-To: <1418703864.09.0.281927050653.issue23061@psf.upfronthosting.co.za>
Message-ID: <1419228280.63.0.0650862735677.issue23061@psf.upfronthosting.co.za>


Ian Lee added the comment:

So one concern that was brought up on GitHub was the fact that currently this is not actually followed universally in the Python standard library. In particular there are 636 errors in the standard library ``python pep8.py --select E402 --statistics /usr/lib/python3.4``.

The vast majority are due to issues with dunder definitions ``__{all,author,copyright,credits,version,etc...}__`` before the imports. A lesser cause is imports in the middle of files. ``Lib/tokenize.py`` has pretty much all of these issues. In particular ``__all__`` is specifically mentioned that it should be declared AFTER the imports by PEP-8. That said, I would argue this is a good time to clean up that code in the standard library.

Additionally, its possible that there might need to be some wording in the PEP about intermixing "try,except,else,finally" and possibly "if,elif,else" into the imports. E.g. 

```
try: 
    import unittest2
except:
    import unittest
```

```
if sys.platform == 'win32':
    import foo
```

----------

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

From report at bugs.python.org  Mon Dec 22 07:16:07 2014
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 22 Dec 2014 06:16:07 +0000
Subject: [docs] [issue23061] Update pep8 to specify explicitly 'module
	level' imports	at top of file
In-Reply-To: <1418703864.09.0.281927050653.issue23061@psf.upfronthosting.co.za>
Message-ID: <1419228967.2.0.159905072999.issue23061@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/issue23061>
_______________________________________

From report at bugs.python.org  Mon Dec 22 07:37:23 2014
From: report at bugs.python.org (Ian Lee)
Date: Mon, 22 Dec 2014 06:37:23 +0000
Subject: [docs] [issue23061] Update pep8 to specify explicitly 'module
	level' imports	at top of file
In-Reply-To: <1418703864.09.0.281927050653.issue23061@psf.upfronthosting.co.za>
Message-ID: <1419230243.39.0.165402099002.issue23061@psf.upfronthosting.co.za>


Ian Lee added the comment:

I should add that I would be happy to patch the standard libraries to be compliant w.r.t. the imports at top of the files.

----------

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

From report at bugs.python.org  Mon Dec 22 08:35:40 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Mon, 22 Dec 2014 07:35:40 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1419199530.2.0.500289468832.issue21279@psf.upfronthosting.co.za>
Message-ID: <2045607.dbza6R0L2x@raxxla>


Serhiy Storchaka added the comment:

> Serhiy can you point out which bits are too verbose? Perhaps you prefer it
> without the bullet list like in the earlier 2014-12-13 version of the
> patch.

I prefer it without the bullet list and without LookupError expansion (there 
is a link to LookupError definition where IndexError and KeyError should be 
mentioned). Instead of new term "subscriptable objects" use "mappings or 
sequences" with links to glossary.

> Looking at the C API, I see a couple problems there:

Yes, it is slightly outdated and needs updates.

----------

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

From report at bugs.python.org  Mon Dec 22 09:38:25 2014
From: report at bugs.python.org (Terry J. Reedy)
Date: Mon, 22 Dec 2014 08:38:25 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419237505.86.0.309990949029.issue21279@psf.upfronthosting.co.za>


Terry J. Reedy added the comment:

I agree with Serhiy: no bullet points, links to glossary (at least in doc), without repeating.

----------

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

From report at bugs.python.org  Mon Dec 22 12:51:15 2014
From: report at bugs.python.org (Martin Panter)
Date: Mon, 22 Dec 2014 11:51:15 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1419249072.56.0.121390982512.issue19548@psf.upfronthosting.co.za>


Martin Panter added the comment:

Adding patch v2 after learning how to compile the docs and fixing my errors. I also simplified the descriptions of the CodecInfo attributes by defering the constructor signatures to where they are fully defined under ?Codec base classes?, and merged the list of error handlers there as well.

A side effect of merging error handler lists is that ?surrogatepass? is now defined for codecs in general, not just Codec.encode() and decode().

Also I noticed that ?unicode_escape? actually does Latin-1 decoding.

----------
Added file: http://bugs.python.org/file37525/codecs-doc.v2.patch

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

From berker.peksag at gmail.com  Mon Dec 22 14:11:11 2014
From: berker.peksag at gmail.com (berker.peksag at gmail.com)
Date: Mon, 22 Dec 2014 13:11:11 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141222131111.28432.29049@psf.upfronthosting.co.za>


http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode229
Doc/library/codecs.rst:229: .. function:: open(filename, mode='r'[,
encoding[, errors[, buffering]]])
Could you also convert this to use Python 3 style parameter like the
other functions?

For example:

    open(filename, mode='r' encoding=None, errors='strict',
buffering=None)

(Not sure all default valures are correct)

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode361
Doc/library/codecs.rst:361: |                         | surrogate code
ranging from U+DC80 to U+DCFF. |
``U+DC80`` to ``U+DCFF``

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode363
Doc/library/codecs.rst:363: |                         | same byte when
the ``surrogateescape`` error  |
``'surrogateescape'``

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

From ncoghlan at gmail.com  Mon Dec 22 16:22:05 2014
From: ncoghlan at gmail.com (ncoghlan at gmail.com)
Date: Mon, 22 Dec 2014 15:22:05 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141222152205.28432.38078@psf.upfronthosting.co.za>

I definitely like the proposed changes overall, especially splitting
CodecInfo out into a separately documented class.

Lots more detailed feedback inline, including some genuien questions
where I don't know the answer off the top of my head myself, and it
isn't a quick check at the interactive prompt to confirm the current
behaviour.


http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode24
Doc/library/codecs.rst:24: bytes to bytes.
I like the idea of expanding on this paragraph. I suggest we make "text
encoding" a defined term in the glossary, and adjust this addition to
be:

Most standard codecs are :term:`text encodings <text encoding>`, which
encode text to bytes, but there are also codecs that encode text to
text, and bytes to bytes. Custom codecs beyond those provided in the
standard library may convert between arbitrary types."

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode54
Doc/library/codecs.rst:54: is not reversible, which doesn't play well
with module reloading.
I suggest pulling this caveat out into a "note". As far as phrasing
goes, something a little more formal may be good. Perhaps:

"Search function registration is not currently reversible, which may
cause problems in some cases, such as unit testing or module reloading"

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode198
Doc/library/codecs.rst:198: suitable replacement marker such as ``b'?'``
in or ``'\ufffd'``.
With the new defined term, this error handling function should gain a
sentence to indicate that it's only applicable to text encodings. (There
may actually be cases where it's usable for bytes->bytes or text->text,
but if that's actually the case, we can figure out how to fix the issue
later. For the time being, I think it's more important to clearly
document the text encoding case)

The substitution can then be clarified to say that b'?' is produced when
encoding, and '\ufffd' when decoding (we can also embed the actual
encoded code point in the documentation here, in addition to the \u
escape).

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode210
Doc/library/codecs.rst:210: unencodable character is replaced by an
appropriate XML character reference.
Also text encoding specific.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode216
Doc/library/codecs.rst:216: unencodable character is replaced by a
backslashed escape sequence.
Also text encoding specific.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode221
Doc/library/codecs.rst:221: unencodable character is replaced by a
``\N{...}`` escape sequence.
Also text encoding specific.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode238
Doc/library/codecs.rst:238: No automatic conversion of ``'\n'`` is done
on reading and writing.
We should also explicitly note here that *this* open uses the
StreamReader and StreamWriter classes provided by the CodecInfo module,
*not* the general purpose IO classes provided by the io module.

This means that 'encoding' here can be any arbitrary registered codec,
rather than necessarily being a text encoding as it is for the io module
(and hence the builtin open function)

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode241
Doc/library/codecs.rst:241: Only the codecs whose encoded form is bytes
are supported.
It's worth explicitly noting here that the types supported by the
file-like object will depend on the codec used.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode261
Doc/library/codecs.rst:261: a text stream.
I'm going to have to look at the implementation to confirm whether this
more specific version is accurate, as I suspect it isn't quite right in
the case where data_encoding == file_encoding.

For the case where they're different, we may want to use the word
"transcoding".

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode267
Doc/library/codecs.rst:267: error occurs.
Since this factory function produces a StreamRecoder instance, a cross
reference may be useful.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode329
Doc/library/codecs.rst:329: To simplify and standardize error handling,
I suggest giving this section on error handlers its own subheading and
label, so it can be referenced directly.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode332
Doc/library/codecs.rst:332: and implemented by all standard Python
codecs:
It may be worthwhile adding cross references back to the functions
implementing each error handler.

For example, finishing with: "(Implemented in :func:`strict_errors`)"

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode337
Doc/library/codecs.rst:337: | Value                   | Meaning         
                             |
I believe this table needs to be split in two, with replace through to
surrogateescape being restricted in applicability to text encodings.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode368
Doc/library/codecs.rst:368: In addition, the following error handlers
are specific to Unicode encoding
With the above table split in two, the phrasing in this introductory
paragraph may need tweaking.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode469
Doc/library/codecs.rst:469: by providing the *errors* keyword argument.
These parameters are predefined:
Given the new link target for the error handler tables, I'd replace this
bulleted list with a cross-reference.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode489
Doc/library/codecs.rst:489: :func:`register_error`.
This paragraph can move to the shared section on error handlers.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode540
Doc/library/codecs.rst:540: by providing the *errors* keyword argument.
These parameters are predefined:
As above - it's likely worth replacing the repeated list with a
cross-reference.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode554
Doc/library/codecs.rst:554: :func:`register_error`.
With this paragraph moved to the common section, it can be dropped here.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode617
Doc/library/codecs.rst:617: *stream* must be a file-like object open for
writing.
I suggest finishing this sentence as "... writing text or binary data,
as appropriate for the specific codec".

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode620
Doc/library/codecs.rst:620: providing the *errors* keyword argument.
These parameters are predefined:
As with the Incremental* APIs, I'm a fan of consolidating the error
handler documentation, and linking to it where appropriate.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode650
Doc/library/codecs.rst:650: the :meth:`write` method). Does not work on
byte encoders.
The new caveat needs to be clarified: what does "Does not work" mean?
What counts as a "byte encoder" in this context?

If the issue is "May not be present for codecs other than text
encodings", then that's what we should say.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode684
Doc/library/codecs.rst:684: *stream* must be a file-like object open for
reading.
See the StreamWriter comments for suggested phrasing here.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode708
Doc/library/codecs.rst:708: characters or bytes to return. The
:func:`read` method will
characters -> code points (due to complexities in the definition of what
actually constitutes a Unicode characters, str's are code point arrays
rather than character arrays)

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode713
Doc/library/codecs.rst:713: number of encoded bytes or characters to
read
characters -> code points again.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode760
Doc/library/codecs.rst:760: In addition to the above methods, the
:class:`StreamReader` must also inherit
Not a new issue in the patch, but "inherit" doesn't strike me as being
the right word here (I'm also not sure the statement is even true any
more).

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1242
Doc/library/codecs.rst:1242: |                    |         | decoding
``b''``          |
This should be clear on what b'' gets decoded to.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1250
Doc/library/codecs.rst:1250: |                    |         | Latin-1
source code.      |
This description should be caveated with the fact that Python 3 uses
UTF-8 by default, and relying on that is preferable to unicode_escape in
most cases where Python 2 source compatibility isn't needed and a utf-8
encoding cookie can't be used for some reason.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1256
Doc/library/codecs.rst:1256: |                    |         | ..
deprecated:: 3.3       |
May be worth cross referencing PEP 393 here to explain this deprecation.

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1265
Doc/library/codecs.rst:1265: to :class:`bytes` mappings.  They are not
supported by :meth:`bytes.decode`.
Perhaps append "(which is expected to produce :class:`str` output)" to
the new sentence?

http://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1320
Doc/library/codecs.rst:1320: mapping.  It is not supported by
:meth:`str.encode`.
Perhaps append "(which is expected to produce :class:`bytes` output)"?

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

From report at bugs.python.org  Mon Dec 22 16:26:21 2014
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 22 Dec 2014 15:26:21 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1419261981.09.0.0358603712356.issue19548@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

Thanks for those drafts, Martin - they look like a strong improvement to me. While I still had plenty of comments/questions on v2, I think that's more a reflection on how long it has been since we gave these docs a thorough overall review, moreso than a reflection on the proposed changes.

Victor - I added you to the nosy list for this one, as I'd specifically like your comments on the StreamReader/Writer docs updates. I'd like to make it clear that these are distinct from the "text encoding only" APIs in the io module, while still accurately describing the behaviour of the standard codecs.

----------
nosy: +haypo
versions:  -Python 2.7

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

From report at bugs.python.org  Mon Dec 22 18:14:58 2014
From: report at bugs.python.org (Ezio Melotti)
Date: Mon, 22 Dec 2014 17:14:58 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1419268498.49.0.203945393367.issue19548@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/issue19548>
_______________________________________

From report at bugs.python.org  Mon Dec 22 21:34:56 2014
From: report at bugs.python.org (Martin Panter)
Date: Mon, 22 Dec 2014 20:34:56 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419280496.64.0.224480509347.issue21279@psf.upfronthosting.co.za>


Martin Panter added the comment:

The problem with mappings and sequences is that they both require len() and iter() implementations, but str.translate() only requires __getitem__(). Perhaps a qualifier could work, like:

The table must implement the __getitem__() method of mappings and sequences.

----------

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

From report at bugs.python.org  Tue Dec 23 00:00:53 2014
From: report at bugs.python.org (Antoine Pitrou)
Date: Mon, 22 Dec 2014 23:00:53 +0000
Subject: [docs] [issue23088] Document that PyUnicode_AsUTF8() returns
	a	null-terminated string
In-Reply-To: <1418964154.65.0.595903967697.issue23088@psf.upfronthosting.co.za>
Message-ID: <1419289253.79.0.728700820447.issue23088@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

This looks good to me.

----------
nosy: +pitrou
stage:  -> commit review
type:  -> behavior
versions: +Python 3.5

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

From report at bugs.python.org  Tue Dec 23 00:31:13 2014
From: report at bugs.python.org (Martin Panter)
Date: Mon, 22 Dec 2014 23:31:13 +0000
Subject: [docs] [issue22671] Typo in class io.BufferedIOBase docs
In-Reply-To: <1413711352.27.0.0253692424247.issue22671@psf.upfronthosting.co.za>
Message-ID: <1419291072.97.0.119230498097.issue22671@psf.upfronthosting.co.za>


Martin Panter added the comment:

Adding patch v2 with readinto1() as a ?mixin method? and dropped many of my earlier changes for better consistency with the introduction of the classes (which I never really read before :P)

----------
Added file: http://bugs.python.org/file37528/read-defaults.v2.patch

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

From report at bugs.python.org  Tue Dec 23 00:58:11 2014
From: report at bugs.python.org (Davin Potts)
Date: Mon, 22 Dec 2014 23:58:11 +0000
Subject: [docs] [issue23100] multiprocessing doc organization impedes
	understanding
Message-ID: <1419292691.51.0.0335324108877.issue23100@psf.upfronthosting.co.za>


New submission from Davin Potts:

The organization and multiple sections of the multiprocessing module's documentation do not adhere to the Python Dev Guidelines for economy of expression, affirmative tone, and/or code examples.

Problem description:
The raw material and information in the multiprocessing module docs are good to excellent and very information rich -- the presentation of that information suffers primarily from its organization.
(1)  Too much information is presented in the same or neighboring subsections where the economy of expression guidelines would advocate for a different approach.  Specifically, section 17.2.2 "Reference" co-mingles discourses on usage topics with a description of the available objects and apis.  Section 17.2.1 "Introduction" does something similar and though some of this can be helpful in an intro section, it takes discourse a bit far at times, arguably losing its focus which is to clearly introduce the reader to the module and efficiently set them on a healthy path to understanding topics and establish sufficient comfort to begin working with the module.  Economy of expression would have us maintain focus in an Introduction or Reference section and re-organize such helpful discourses into supporting but distinct sections.
(2) Affirmative tone is not consistently used throughout the docs.  Multiple of the items under section 17.2.3 "Programming guidelines" leverage negative examples to motivate what should be done instead -- each of these can be rewritten in the way advocated in the Python Dev Guidelines for affirmative tone.
(3) Per the Python Dev Guidelines for code examples, examples should accelerate understanding versus alternative prose.  Code snippets showcasing internal behavior to the module, such as the "Beware of replacing sys.stdin" subsection inside 17.2.3.1 "All start methods", should arguably have their example code blocks replaced with prose.  Section 17.2.4 "Examples" provides examples showcasing many facets all in the same example code block yet little to no supporting or motivating explanation is offered for each (more could be offered inline as well as outside as prose).

Suggested changes:
* Re-organize the single multiprocessing module doc into multiple in the style of the logging module.  Specifically, tutorials should be created to house the "bunny trail" discourses from the Introduction/Reference sections and a cookbook should be created to house the material from the Examples section.
* By de-bunny-trailing the Introduction/Reference sections, a more focused set of sections in the style of the threading module should result.
* Limited modifications to code examples are advocated only so far as they restore the affirmative tone as needed.
* New examples are not advocated as part of this issue; they are out-of-scope.

This issue is intended to add to the path started/advocated by Issue 22952.  It does not supplant but rather expands upon that issue.

----------
assignee: docs at python
components: Documentation
messages: 233030
nosy: davin, docs at python, rhettinger
priority: normal
severity: normal
status: open
title: multiprocessing doc organization impedes understanding
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6

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

From report at bugs.python.org  Tue Dec 23 01:00:13 2014
From: report at bugs.python.org (Davin Potts)
Date: Tue, 23 Dec 2014 00:00:13 +0000
Subject: [docs] [issue23100] multiprocessing doc organization impedes
	understanding
In-Reply-To: <1419292691.51.0.0335324108877.issue23100@psf.upfronthosting.co.za>
Message-ID: <1419292813.06.0.613585139377.issue23100@psf.upfronthosting.co.za>


Davin Potts added the comment:

I am happy to provide proposed patches but first can someone please clarify for me whether I should have those patches depend upon the patches from Issue 22952?

----------

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

From report at bugs.python.org  Tue Dec 23 01:03:38 2014
From: report at bugs.python.org (Davin Potts)
Date: Tue, 23 Dec 2014 00:03:38 +0000
Subject: [docs] [issue22952] multiprocessing doc introduction not in
	affirmative tone
In-Reply-To: <1417037709.37.0.435561396576.issue22952@psf.upfronthosting.co.za>
Message-ID: <1419293018.0.0.450724956793.issue22952@psf.upfronthosting.co.za>


Davin Potts added the comment:

Procedural question (wanting to understand the label given to this issue):  when documentation does not adhere to the Python Developer's Guide, is a fix for this considered an "enhancement"?

----------
versions: +Python 3.6

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

From report at bugs.python.org  Tue Dec 23 07:44:22 2014
From: report at bugs.python.org (Ned Deily)
Date: Tue, 23 Dec 2014 06:44:22 +0000
Subject: [docs] [issue23100] multiprocessing doc organization impedes
	understanding
In-Reply-To: <1419292691.51.0.0335324108877.issue23100@psf.upfronthosting.co.za>
Message-ID: <1419317062.67.0.576736354359.issue23100@psf.upfronthosting.co.za>


Changes by Ned Deily <nad at acm.org>:


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

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

From report at bugs.python.org  Tue Dec 23 08:22:31 2014
From: report at bugs.python.org (Martin Panter)
Date: Tue, 23 Dec 2014 07:22:31 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1419319349.79.0.432489363036.issue19548@psf.upfronthosting.co.za>


Martin Panter added the comment:

New patch version addressing many of the comments; thanks for reviewing! Also adds and extends some unit tests to confirm some of the corner cases I am documenting.

----------
Added file: http://bugs.python.org/file37530/codecs-doc.v3.patch

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

From report at bugs.python.org  Tue Dec 23 16:39:44 2014
From: report at bugs.python.org (R. David Murray)
Date: Tue, 23 Dec 2014 15:39:44 +0000
Subject: [docs] [issue23105] os.O_SHLOCK and os.O_EXLOCK are not available
	on Linux
In-Reply-To: <1419345535.42.0.312768269587.issue23105@psf.upfronthosting.co.za>
Message-ID: <1419349184.22.0.850960619975.issue23105@psf.upfronthosting.co.za>


R. David Murray added the comment:

The documentation says "Some of them are not available on all platforms. For descriptions of their availability and use, consult the open(2) manual page on Unix or the MSDN on Windows.".  The important bit there being "consult the open(2) manual page on Unix" for availability.

That said, since the options are grouped and labeled with per-platform availability...but with a slightly different meaning of the word platform...I think the docs could be clarified.  Do you have a suggestion for rewording that sentence to make it clearer?

----------
assignee:  -> docs at python
components: +Documentation -Library (Lib)
nosy: +docs at python, r.david.murray
versions: +Python 2.7, Python 3.5

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

From report at bugs.python.org  Tue Dec 23 17:11:22 2014
From: report at bugs.python.org (Sworddragon)
Date: Tue, 23 Dec 2014 16:11:22 +0000
Subject: [docs] [issue23105] os.O_SHLOCK and os.O_EXLOCK are not available
	on Linux
In-Reply-To: <1419345535.42.0.312768269587.issue23105@psf.upfronthosting.co.za>
Message-ID: <1419351082.15.0.771690075404.issue23105@psf.upfronthosting.co.za>


Sworddragon added the comment:

I have missed the first part of the documentation and am not sure if something needs really to be changed. But if you think so maybe comments like "These constants are only available on Unix." could be extended by the word "commonly" like "These constants are commonly only available on Unix.".

----------

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

From report at bugs.python.org  Wed Dec 24 00:08:42 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 23 Dec 2014 23:08:42 +0000
Subject: [docs] [issue22952] multiprocessing doc introduction not in
	affirmative tone
In-Reply-To: <1417037709.37.0.435561396576.issue22952@psf.upfronthosting.co.za>
Message-ID: <1419376122.15.0.89469142439.issue22952@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

> Procedural question ... is a fix for this considered an "enhancement"?

Improvements to documentation are almost always backported.  The contrasts with code changes where enhancements (new features, optimizations, or refactorings) are made only on the latest development branch to reduce the risk of destabilizing code that has already shipped.

----------

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

From report at bugs.python.org  Wed Dec 24 00:16:53 2014
From: report at bugs.python.org (Raymond Hettinger)
Date: Tue, 23 Dec 2014 23:16:53 +0000
Subject: [docs] [issue23061] Update pep8 to specify explicitly 'module
	level' imports	at top of file
In-Reply-To: <1418703864.09.0.281927050653.issue23061@psf.upfronthosting.co.za>
Message-ID: <1419376613.71.0.869174523479.issue23061@psf.upfronthosting.co.za>


Raymond Hettinger added the comment:

> I would argue this is a good time to clean up that code in the standard library.

Please leave any clean-ups to the module maintainers.  PEP 8 is something you should do to your own code, rather than something you inflict on other people's code.

We generally leave "clean-ups" to the module maintainers rather than creating code churn which can make it more difficult to apply actual bug fixes across versions.

Also, GvR has long expressed a preference for "holistic refactoring" where we avoid making superficial changes across the library and reserve those changes for occasions where we're thinking more deeply about a specific piece of code.  The basis for this viewpoint has been confirmed a number of times when we've received Pep 8 patches that introduced bugs into code that was previously correct.

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

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

From report at bugs.python.org  Wed Dec 24 03:27:35 2014
From: report at bugs.python.org (John Posner)
Date: Wed, 24 Dec 2014 02:27:35 +0000
Subject: [docs] [issue21279] str.translate documentation incomplete
In-Reply-To: <1397696482.87.0.486412592823.issue21279@psf.upfronthosting.co.za>
Message-ID: <1419388054.76.0.872020577922.issue21279@psf.upfronthosting.co.za>


John Posner added the comment:

issue21279.v5.patch tries to apply the comments in msg233013, msg233014, and msg233025 to the Doc/library/stdtypes.rst writeup. Then it applies some of the same language to the docstring in Objects/unicodeobject.c.

----------
Added file: http://bugs.python.org/file37536/issue21279.v5.patch

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

From report at bugs.python.org  Wed Dec 24 12:42:35 2014
From: report at bugs.python.org (=?utf-8?q?Cl=C3=A9ment?=)
Date: Wed, 24 Dec 2014 11:42:35 +0000
Subject: [docs] [issue23109] French quotes in the documentation are
	often	ungrammatical
Message-ID: <1419421355.57.0.399831572163.issue23109@psf.upfronthosting.co.za>


New submission from Cl?ment:

>From https://docs.python.org/3/howto/unicode.html:

> For a while people just wrote programs that didn?t display accents.
> In the mid-1980s an Apple II BASIC program written by a French 
> speaker might have lines like these:
> 
> PRINT "FICHIER EST COMPLETE."
> PRINT "CARACTERE NON ACCEPTE."
> 
> Those messages should contain accents (complet?, caract?re, accept?), > and they just look wrong to someone who can read French.

One of the reasons the message looks wrong is that "FICHIER EST COMPLETE" in ungrammatical in French. Google has 16 hits for that query, half of which are from the Python documentation. The second one is better.

I imagine the first one comes from the English "FILE IS COMPLETE", but I'm not even sure what that meant, so it's hard to give a better translation :/ Instead, here are a few examples that could work:

MISE A JOUR TERMINEE (Update completed ? missing ? and ? in termin?e)
VEUILLEZ REDEMARRER (Please reboot ? missing ? in red?marrer)
PARAMETRES ENREGISTRES (Settings saved ? missing ? in param?tre and ? in enregistr?s)

Similarly, https://docs.python.org/3/library/email-examples.html#examples-using-the-provisional-api:

> msg['Subject'] = "Ayons asperges pour le d?jeuner"

I imagine this comes from the English "Let's have asparagus for lunch!", but the translation reads "Possess asparagus for lunch we". A proper idiomatic French version would be "?a te dirait de manger des asperges ? midi?" (Would you like to eat asparagus for lunch?)

Again further on the same page:

> Cela ressemble ? un excellent recipie[1] d?jeuner.

Could this mean "This looks like a delicious lunch recipie?" The typo in recipie would have prevented the machine translation from picking up recipie, which survived in the French version? This currently reads "This look like recipie lunch a excellent". A proper French version (adjusted to have accents) might be "J'ai trouv? une recette sympa: [1]" ("I found a nice recipe: [1]").

Not sure why using French is needed though; English already has a few accented words: a message with subject "R?sum? attached", and body "Here's my r?sum?" would probably work just as well, and might not divert the reader's attention as much.

Side note: in the example P?p? writes to Fabrette and Penelope. Aren't they the same character?

Cl?ment.

----------
assignee: docs at python
components: Documentation
messages: 233076
nosy: cpitcla, docs at python
priority: normal
severity: normal
status: open
title: French quotes in the documentation are often ungrammatical
versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6

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

From report at bugs.python.org  Wed Dec 24 15:25:03 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Wed, 24 Dec 2014 14:25:03 +0000
Subject: [docs] [issue23109] French quotes in the documentation are
	often	ungrammatical
In-Reply-To: <1419421355.57.0.399831572163.issue23109@psf.upfronthosting.co.za>
Message-ID: <1419431103.59.0.482704621661.issue23109@psf.upfronthosting.co.za>


Changes by Serhiy Storchaka <storchaka at gmail.com>:


----------
nosy: +haypo, pitrou

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

From report at bugs.python.org  Wed Dec 24 16:23:24 2014
From: report at bugs.python.org (R. David Murray)
Date: Wed, 24 Dec 2014 15:23:24 +0000
Subject: [docs] [issue23109] French quotes in the documentation are
	often	ungrammatical
In-Reply-To: <1419421355.57.0.399831572163.issue23109@psf.upfronthosting.co.za>
Message-ID: <1419434604.72.0.395169066051.issue23109@psf.upfronthosting.co.za>


R. David Murray added the comment:

Heh, I never claimed I understood French, but none of our French speakers decided to review my fake-french examples :)

(I can't speak to the examples from the unicode howto.)

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

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

From report at bugs.python.org  Wed Dec 24 17:22:53 2014
From: report at bugs.python.org (Robert Snoeberger)
Date: Wed, 24 Dec 2014 16:22:53 +0000
Subject: [docs] [issue23110] Document if argument to Py_SetPath requires
	static	storage.
Message-ID: <1419438173.5.0.679263724855.issue23110@psf.upfronthosting.co.za>


New submission from Robert Snoeberger:

The documentation for the Py_SetPath API does not indicate if the argument should point to a wide character array in static storage. However, the documentation for Py_GetPath says, "The returned string points into static storage; the caller should not modify its value." This leads me to believe that static storage is required for Py_SetPath.

The documentation for similar API functions, Py_SetPythonHome and Py_SetProgramName, indicates, "The argument should point to a zero-terminated wide character string in static storage whose contents will not change...".

----------
assignee: docs at python
components: Documentation
messages: 233081
nosy: docs at python, snoeberger
priority: normal
severity: normal
status: open
title: Document if argument to Py_SetPath requires static storage.
type: enhancement
versions: Python 3.5

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

From report at bugs.python.org  Wed Dec 24 17:51:20 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 24 Dec 2014 16:51:20 +0000
Subject: [docs] [issue23110] Document if argument to Py_SetPath requires
	static	storage.
In-Reply-To: <1419438173.5.0.679263724855.issue23110@psf.upfronthosting.co.za>
Message-ID: <20141224165115.102371.46152@psf.io>


Roundup Robot added the comment:

New changeset 08972a47f710 by Benjamin Peterson in branch '3.4':
doucment that Py_SetPath copies its argument (closes #23110)
https://hg.python.org/cpython/rev/08972a47f710

New changeset edf4ea3cfe68 by Benjamin Peterson in branch 'default':
merge 3.4 (#23110)
https://hg.python.org/cpython/rev/edf4ea3cfe68

----------
nosy: +python-dev
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

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

From report at bugs.python.org  Wed Dec 24 20:59:10 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 24 Dec 2014 19:59:10 +0000
Subject: [docs] [issue23109] French quotes in the documentation are
	often	ungrammatical
In-Reply-To: <1419421355.57.0.399831572163.issue23109@psf.upfronthosting.co.za>
Message-ID: <20141224195858.22196.14726@psf.io>


Roundup Robot added the comment:

New changeset 55462210ba2d by Benjamin Peterson in branch '2.7':
improve incorrect French (#23109)
https://hg.python.org/cpython/rev/55462210ba2d

New changeset 2c87dd2d821e by Benjamin Peterson in branch '3.4':
improve incorrect French (#23109)
https://hg.python.org/cpython/rev/2c87dd2d821e

New changeset c5603b77df68 by Benjamin Peterson in branch 'default':
merge 3.4 (#23109)
https://hg.python.org/cpython/rev/c5603b77df68

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

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

From report at bugs.python.org  Wed Dec 24 23:08:07 2014
From: report at bugs.python.org (Roundup Robot)
Date: Wed, 24 Dec 2014 22:08:07 +0000
Subject: [docs] [issue23109] French quotes in the documentation are
	often	ungrammatical
In-Reply-To: <1419421355.57.0.399831572163.issue23109@psf.upfronthosting.co.za>
Message-ID: <20141224220805.120051.9175@psf.io>


Roundup Robot added the comment:

New changeset 181dfe9288d4 by Benjamin Peterson in branch '3.4':
update correct French examples (#23109)
https://hg.python.org/cpython/rev/181dfe9288d4

----------

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

From report at bugs.python.org  Thu Dec 25 03:24:23 2014
From: report at bugs.python.org (Roundup Robot)
Date: Thu, 25 Dec 2014 02:24:23 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <20141225022419.22214.57880@psf.io>


Roundup Robot added the comment:

New changeset 126aff7c6a33 by R David Murray in branch '3.4':
#23040: Clarify treatment of encoding and errors when component is bytes.
https://hg.python.org/cpython/rev/126aff7c6a33

New changeset 367ba031a743 by R David Murray in branch 'default':
Merge: #23040: Clarify treatment of encoding and errors when component is bytes.
https://hg.python.org/cpython/rev/367ba031a743

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

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

From report at bugs.python.org  Thu Dec 25 03:25:08 2014
From: report at bugs.python.org (R. David Murray)
Date: Thu, 25 Dec 2014 02:25:08 +0000
Subject: [docs] [issue23040] Better documentation for the urlencode safe
	parameter
In-Reply-To: <1418398499.72.0.468214874616.issue23040@psf.upfronthosting.co.za>
Message-ID: <1419474308.82.0.329309174722.issue23040@psf.upfronthosting.co.za>


R. David Murray added the comment:

Thanks, Wojtek.

----------
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
versions: +Python 3.4

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

From report at bugs.python.org  Thu Dec 25 07:02:41 2014
From: report at bugs.python.org (Akira Li)
Date: Thu, 25 Dec 2014 06:02:41 +0000
Subject: [docs] [issue22673] document the special features (eg:
	fdclose=False) of the	standard streams
In-Reply-To: <1413745258.02.0.518044907787.issue22673@psf.upfronthosting.co.za>
Message-ID: <1419487361.68.0.683851761394.issue22673@psf.upfronthosting.co.za>


Akira Li added the comment:

Two minor details:

1. It is possible that `fileno(stdout) != 1` even in C [1]. 
   I don't know what happens if the code from the answer is
   run on Windows.

   In principle, it may break eryksun's workaround. I don't 
   know how likely it is in practice.

2. you can redirect at the file descriptor level in Python [2] 
   using os.dup2(). I don't know whether the code in the 
   answer works on Windows.

[1] http://stackoverflow.com/questions/25516375/is-it-possible-that-filenostdout-1-on-a-posix-system
[2] http://stackoverflow.com/questions/4675728/redirect-stdout-to-a-file-in-python/22434262#22434262

----------
nosy: +akira

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

From report at bugs.python.org  Fri Dec 26 01:31:41 2014
From: report at bugs.python.org (Jan Kaliszewski)
Date: Fri, 26 Dec 2014 00:31:41 +0000
Subject: [docs] [issue19539] The 'raw_unicode_escape' codec buggy + not
	appropriate	for Python 3.x
In-Reply-To: <1384051905.56.0.969775270474.issue19539@psf.upfronthosting.co.za>
Message-ID: <1419553901.98.0.3815981097.issue19539@psf.upfronthosting.co.za>


Changes by Jan Kaliszewski <zuo at chopin.edu.pl>:


----------
resolution:  -> duplicate
status: open -> closed

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

From report at bugs.python.org  Fri Dec 26 01:33:00 2014
From: report at bugs.python.org (Jan Kaliszewski)
Date: Fri, 26 Dec 2014 00:33:00 +0000
Subject: [docs] [issue19539] The 'raw_unicode_escape' codec buggy + not
	appropriate	for Python 3.x
In-Reply-To: <1384051905.56.0.969775270474.issue19539@psf.upfronthosting.co.za>
Message-ID: <1419553980.48.0.482873934702.issue19539@psf.upfronthosting.co.za>


Jan Kaliszewski added the comment:

My concerns are now being addressed in the issue19548.

----------

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

From report at bugs.python.org  Fri Dec 26 18:20:42 2014
From: report at bugs.python.org (Antoine Pitrou)
Date: Fri, 26 Dec 2014 17:20:42 +0000
Subject: [docs] [issue23109] French quotes in the documentation are
	often	ungrammatical
In-Reply-To: <1419421355.57.0.399831572163.issue23109@psf.upfronthosting.co.za>
Message-ID: <1419614442.32.0.507065968167.issue23109@psf.upfronthosting.co.za>


Antoine Pitrou added the comment:

> Heh, I never claimed I understood French, but none of our French speakers decided to review my fake-french examples :)

I just thought they looked funny :-)

----------

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

From vadmium+py at gmail.com  Tue Dec 23 08:25:19 2014
From: vadmium+py at gmail.com (vadmium+py at gmail.com)
Date: Tue, 23 Dec 2014 07:25:19 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141223072519.8653.20@psf.upfronthosting.co.za>

Addressed most of the comments in patch v3; there were a few of Nick?s I
wasn?t sure on


https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode24
Doc/library/codecs.rst:24: bytes to bytes.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> I like the idea of expanding on this paragraph. I suggest we make
"text
> encoding" a defined term in the glossary, and adjust this addition to
be:
> 
> Most standard codecs are :term:`text encodings <text encoding>`, which
encode
> text to bytes, but there are also codecs that encode text to text, and
bytes to
> bytes. Custom codecs beyond those provided in the standard library may
convert
> between arbitrary types."

Added, except for the last sentence. Can they really convert between
arbitrary types, or just sequences of arbitrary types? There are already
plenty of bugs and undocumented quirks with the existing non-text
encodings, so I wonder if allowing even stranger types is a good idea
right now.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode54
Doc/library/codecs.rst:54: is not reversible, which doesn't play well
with module reloading.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> I suggest pulling this caveat out into a "note". As far as phrasing
goes,
> something a little more formal may be good. Perhaps:
> 
> "Search function registration is not currently reversible, which may
cause
> problems in some cases, such as unit testing or module reloading"

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode198
Doc/library/codecs.rst:198: suitable replacement marker such as ``b'?'``
in or ``'\ufffd'``.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> With the new defined term, this error handling function should gain a
sentence
> to indicate that it's only applicable to text encodings. (There may
actually be
> cases where it's usable for bytes->bytes or text->text, but if that's
actually
> the case, we can figure out how to fix the issue later. For the time
being, I
> think it's more important to clearly document the text encoding case)

Added.

> The substitution can then be clarified to say that b'?' is produced
when
> encoding, and '\ufffd' when decoding (we can also embed the actual
encoded code
> point in the documentation here, in addition to the \u escape).

Actually my change to b'?' was misleading. See revised text.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode210
Doc/library/codecs.rst:210: unencodable character is replaced by an
appropriate XML character reference.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Also text encoding specific.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode216
Doc/library/codecs.rst:216: unencodable character is replaced by a
backslashed escape sequence.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Also text encoding specific.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode221
Doc/library/codecs.rst:221: unencodable character is replaced by a
``\N{...}`` escape sequence.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Also text encoding specific.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode229
Doc/library/codecs.rst:229: .. function:: open(filename, mode='r'[,
encoding[, errors[, buffering]]])
On 2014/12/22 14:11:11, berkerpeksag wrote:
> Could you also convert this to use Python 3 style parameter like the
other
> functions?
> 
> For example:
> 
>     open(filename, mode='r' encoding=None, errors='strict',
buffering=None)
> 
> (Not sure all default valures are correct)

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode238
Doc/library/codecs.rst:238: No automatic conversion of ``'\n'`` is done
on reading and writing.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> We should also explicitly note here that *this* open uses the
StreamReader and
> StreamWriter classes provided by the CodecInfo module, *not* the
general purpose
> IO classes provided by the io module.

Added, including a unit test asserting it is always StreamReaderWriter.

> This means that 'encoding' here can be any arbitrary registered codec,
rather
> than necessarily being a text encoding as it is for the io module (and
hence the
> builtin open function)

Clarified below, though still with the requirement that it has to encode
to bytes.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode241
Doc/library/codecs.rst:241: Only the codecs whose encoded form is bytes
are supported.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> It's worth explicitly noting here that the types supported by the
file-like
> object will depend on the codec used.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode261
Doc/library/codecs.rst:261: a text stream.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> I'm going to have to look at the implementation to confirm whether
this more
> specific version is accurate, as I suspect it isn't quite right in the
case
> where data_encoding == file_encoding.

EncodedFile() implementation just blindly calls StreamRecoder, and
StreamRecoder doesn?t appear to do any optimization or anything either.
I think you?d definitely need to do a full decode and recode if the user
specified a non-strict error handler.

> For the case where they're different, we may want to use the word
"transcoding".

Okay, done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode267
Doc/library/codecs.rst:267: error occurs.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Since this factory function produces a StreamRecoder instance, a cross
reference
> may be useful.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode329
Doc/library/codecs.rst:329: To simplify and standardize error handling,
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> I suggest giving this section on error handlers its own subheading and
label, so
> it can be referenced directly.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode332
Doc/library/codecs.rst:332: and implemented by all standard Python
codecs:
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> It may be worthwhile adding cross references back to the functions
implementing
> each error handler.
> 
> For example, finishing with: "(Implemented in :func:`strict_errors`)"

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode337
Doc/library/codecs.rst:337: | Value                   | Meaning         
                             |
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> I believe this table needs to be split in two, with replace through to
> surrogateescape being restricted in applicability to text encodings.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode361
Doc/library/codecs.rst:361: |                         | surrogate code
ranging from U+DC80 to U+DCFF. |
On 2014/12/22 14:11:11, berkerpeksag wrote:
> ``U+DC80`` to ``U+DCFF``

Done, including other instances in the file.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode363
Doc/library/codecs.rst:363: |                         | same byte when
the ``surrogateescape`` error  |
On 2014/12/22 14:11:11, berkerpeksag wrote:
> ``'surrogateescape'``

Done, including other references in the page.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode469
Doc/library/codecs.rst:469: by providing the *errors* keyword argument.
These parameters are predefined:
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Given the new link target for the error handler tables, I'd replace
this
> bulleted list with a cross-reference.

Good idea, done

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode489
Doc/library/codecs.rst:489: :func:`register_error`.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> This paragraph can move to the shared section on error handlers.

Already in the section, so removed.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode540
Doc/library/codecs.rst:540: by providing the *errors* keyword argument.
These parameters are predefined:
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> As above - it's likely worth replacing the repeated list with a
cross-reference.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode554
Doc/library/codecs.rst:554: :func:`register_error`.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> With this paragraph moved to the common section, it can be dropped
here.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode617
Doc/library/codecs.rst:617: *stream* must be a file-like object open for
writing.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> I suggest finishing this sentence as "... writing text or binary data,
as
> appropriate for the specific codec".

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode620
Doc/library/codecs.rst:620: providing the *errors* keyword argument.
These parameters are predefined:
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> As with the Incremental* APIs, I'm a fan of consolidating the error
handler
> documentation, and linking to it where appropriate.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode650
Doc/library/codecs.rst:650: the :meth:`write` method). Does not work on
byte encoders.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> The new caveat needs to be clarified: what does "Does not work" mean?
What
> counts as a "byte encoder" in this context?
> 
> If the issue is "May not be present for codecs other than text
encodings", then
> that's what we should say.

I think the trouble is that it is present (via inheritance I assume) for
the byte-to-byte codecs, but the code assumes the input is text strings.
Will change to something like ?The standard bytes-to-bytes codecs do not
support this method?.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode684
Doc/library/codecs.rst:684: *stream* must be a file-like object open for
reading.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> See the StreamWriter comments for suggested phrasing here.

Applied

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode708
Doc/library/codecs.rst:708: characters or bytes to return. The
:func:`read` method will
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> characters -> code points (due to complexities in the definition of
what
> actually constitutes a Unicode characters, str's are code point arrays
rather
> than character arrays)

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode713
Doc/library/codecs.rst:713: number of encoded bytes or characters to
read
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> characters -> code points again.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1242
Doc/library/codecs.rst:1242: |                    |         | decoding
``b''``          |
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> This should be clear on what b'' gets decoded to.

I might drop that bit for now. I found that b"".decode("undefined") ->
"", but now I find codecs.decode(b"", "undefined") raises an exception.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1250
Doc/library/codecs.rst:1250: |                    |         | Latin-1
source code.      |
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> This description should be caveated with the fact that Python 3 uses
UTF-8 by
> default, and relying on that is preferable to unicode_escape in most
cases where
> Python 2 source compatibility isn't needed and a utf-8 encoding cookie
can't be
> used for some reason.

Pointed out that UTF-8 is the default, but the second half went over my
head. What is preferable to unicode_escape when you have UTF-8 source
code?

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1256
Doc/library/codecs.rst:1256: |                    |         | ..
deprecated:: 3.3       |
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> May be worth cross referencing PEP 393 here to explain this
deprecation.

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1265
Doc/library/codecs.rst:1265: to :class:`bytes` mappings.  They are not
supported by :meth:`bytes.decode`.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Perhaps append "(which is expected to produce :class:`str` output)" to
the new
> sentence?

Done.

https://bugs.python.org/review/19548/diff/13481/Doc/library/codecs.rst#newcode1320
Doc/library/codecs.rst:1320: mapping.  It is not supported by
:meth:`str.encode`.
On 2014/12/22 16:22:05, Nick Coghlan wrote:
> Perhaps append "(which is expected to produce :class:`bytes` output)"?

Done.

https://bugs.python.org/review/19548/

From walter at livinglogic.de  Tue Dec 23 12:08:03 2014
From: walter at livinglogic.de (walter at livinglogic.de)
Date: Tue, 23 Dec 2014 11:08:03 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141223110803.820.24871@psf.upfronthosting.co.za>


http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode204
Doc/library/codecs.rst:204: (to be encoded by the codec), and
``'\ufffd'`` (``'?'``) for
I think the literal replacement character should be removed in this
spot, as it's unclean how this character will appear in the target
document.

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

From vdheuvel.bas at gmail.com  Tue Dec 23 12:59:08 2014
From: vdheuvel.bas at gmail.com (Bas van den Heuvel)
Date: Tue, 23 Dec 2014 12:59:08 +0100
Subject: [docs] Small bug in documentation menu
Message-ID: <5499590C.3080209@gmail.com>

Hi,

I discovered a small bug in the documentation. When you visit the main
documentation page of Python 3.4, the menu says that Python 3.3 is
stable and that 3.5 is in development.
WHen you then click on 3.5, it says Python 3.4 is stable.
WHen you now return to 3.4 and then click on 3.3, it says that Python
3.4 is in development. It probably got left behind in updating
documentation, but this was kind of confusing for me.

Thank you.

Bas

From zuo at chopin.edu.pl  Fri Dec 26 00:35:53 2014
From: zuo at chopin.edu.pl (zuo at chopin.edu.pl)
Date: Thu, 25 Dec 2014 23:35:53 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141225233553.820.94931@psf.upfronthosting.co.za>

Reviewers: vadmium, berkerpeksag, Nick Coghlan, doerwalter,


http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode1243
Doc/library/codecs.rst:1243: |                    |         | be decoded
differently.   |
I don't understand what does "may be decoded differently" mean here.



Please review this at http://bugs.python.org/review/19548/

Affected files:
  Doc/glossary.rst
  Doc/library/codecs.rst
  Doc/library/functions.rst
  Lib/codecs.py
  Lib/test/test_codecs.py
  Modules/_codecsmodule.c



From zuo at chopin.edu.pl  Fri Dec 26 01:21:34 2014
From: zuo at chopin.edu.pl (zuo at chopin.edu.pl)
Date: Fri, 26 Dec 2014 00:21:34 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141226002134.820.232@psf.upfronthosting.co.za>

A few remarks from a perspective of a person who still does not
understand all nooks and crannies of the Python codecs system and the
*codecs* module.


http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode24
Doc/library/codecs.rst:24: but there are also codecs that encode text to
text, and bytes to bytes.
Shouldn't be a note about arbitrary-types codecs added *here*?

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode164
Doc/library/codecs.rst:164: .. function:: register_error(name,
error_handler)
For this function and the functions described below, the above sentence
"To simplify access to the various codecs, the module provides these
additional functions which use :func:`lookup` for the codec lookup:"
(line 112) is not appropriate.  Some other sentence should be placed
here (introducing error-handling-related functions.

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode182
Doc/library/codecs.rst:182: Decoding and translating works similarly,
except :exc:`UnicodeDecodeError` or
Possible beginner's questions: What is "translating"? When it is
performed? How can it be differentiated from subsequent encoding +
decoding?

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode250
Doc/library/codecs.rst:250: :func:`open` function; the ``'b'`` is
automatically added.
I would add something like: "Please note that when you need to use just
an ordinary :term:`text encoding` the built-in :func:`open` function is
the recommended (and, typically, more efficient) way to operate on text
files".

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode325
Doc/library/codecs.rst:325: .. _surrogateescape:
Should be moved to the place above the ".. _error-handlers:" line (341).

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode335
Doc/library/codecs.rst:335: Each codec has to define four interfaces to
make it usable as codec in Python:
Possible beginner's questions: is a codec an instance of :class:`Codec`?
Or of :class:`CodecInfo`? What does it mean that it define those *four*
intefraces? How is it related to the
stateless/incremental/decoder/encoder and stream writer/reader classes
described below? Why here only *four* interfaces and not *six*
interfaces are mentioned? (i.e., what about *incremental encoder* and
*incremental decoder?*)

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode687
Doc/library/codecs.rst:687: providing the *errors* keyword argument.
These parameters are defined:
The "parameters" word does not seem to be the correct term here...

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode689
Doc/library/codecs.rst:689: * ``'strict'`` Raise :exc:`ValueError` (or a
subclass); this is the default.
Only these three and not, e.g. 'surrogateescape'?
Shouldn't be a reference to ".. _error-handlers:" be used here instead
of this enumeration? (with a caution that the "only for encoding"
handlers are disallowed)

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

From report at bugs.python.org  Sat Dec 27 22:04:02 2014
From: report at bugs.python.org (Berker Peksag)
Date: Sat, 27 Dec 2014 21:04:02 +0000
Subject: [docs] [issue19539] The 'raw_unicode_escape' codec buggy + not
	appropriate	for Python 3.x
In-Reply-To: <1384051905.56.0.969775270474.issue19539@psf.upfronthosting.co.za>
Message-ID: <1419714242.79.0.428689061804.issue19539@psf.upfronthosting.co.za>


Changes by Berker Peksag <berker.peksag at gmail.com>:


----------
stage: needs patch -> resolved
superseder:  -> 'codecs' module docs improvements

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

From report at bugs.python.org  Sun Dec 28 09:48:33 2014
From: report at bugs.python.org (STINNER Victor)
Date: Sun, 28 Dec 2014 08:48:33 +0000
Subject: [docs] [issue19539] The 'raw_unicode_escape' codec buggy + not
	appropriate	for Python 3.x
In-Reply-To: <1419714242.79.0.428689061804.issue19539@psf.upfronthosting.co.za>
Message-ID: <CAMpsgwYhM4uPktsxZk3-Evq+ma5dZB3a+D2=hFMn5MR-uGNLSg@mail.gmail.com>


STINNER Victor added the comment:

This issue is just a documentation issue. The do must be more explicit,
explain that the codecs is only used internally by the pickle module, and
that its output cannot be used anymore by eval().

----------

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

From report at bugs.python.org  Sun Dec 28 09:50:57 2014
From: report at bugs.python.org (=?utf-8?q?Damien_Mari=C3=A9?=)
Date: Sun, 28 Dec 2014 08:50:57 +0000
Subject: [docs] [issue23125] Link to the nose project obsolete
Message-ID: <1419756657.65.0.513358597735.issue23125@psf.upfronthosting.co.za>


New submission from Damien Mari?:

The Nose project moved from Google Code to Github, the link in the unittest documentation didn't change.

How to reproduce:
- Go to https://docs.python.org/3.5/library/unittest.html 
- Click on nose (in the "See also" section)
- See the Google Code project being moved to github

How to fix:
Replace the link with the readthedocs page ( https://nose.readthedocs.org/en/latest/ ) or the github page

----------
assignee: docs at python
components: Documentation
messages: 233148
nosy: docs at python, mariedam
priority: normal
severity: normal
status: open
title: Link to the nose project obsolete
versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6

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

From report at bugs.python.org  Sun Dec 28 17:47:23 2014
From: report at bugs.python.org (Roundup Robot)
Date: Sun, 28 Dec 2014 16:47:23 +0000
Subject: [docs] [issue23125] Link to the nose project obsolete
In-Reply-To: <1419756657.65.0.513358597735.issue23125@psf.upfronthosting.co.za>
Message-ID: <20141228164720.22202.40704@psf.io>


Roundup Robot added the comment:

New changeset 0a2bb697d1c3 by Berker Peksag in branch '3.4':
Issue #23125: Update nose project page link.
https://hg.python.org/cpython/rev/0a2bb697d1c3

New changeset 11fd71a37665 by Berker Peksag in branch 'default':
Issue #23125: Update nose project page link.
https://hg.python.org/cpython/rev/11fd71a37665

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

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

From report at bugs.python.org  Sun Dec 28 17:49:51 2014
From: report at bugs.python.org (Roundup Robot)
Date: Sun, 28 Dec 2014 16:49:51 +0000
Subject: [docs] [issue23125] Link to the nose project obsolete
In-Reply-To: <1419756657.65.0.513358597735.issue23125@psf.upfronthosting.co.za>
Message-ID: <20141228164945.120047.32672@psf.io>


Roundup Robot added the comment:

New changeset 88de50c1696b by Berker Peksag in branch '2.7':
Issue #23125: Update nose project page link.
https://hg.python.org/cpython/rev/88de50c1696b

----------

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

From report at bugs.python.org  Sun Dec 28 17:51:02 2014
From: report at bugs.python.org (Berker Peksag)
Date: Sun, 28 Dec 2014 16:51:02 +0000
Subject: [docs] [issue23125] Link to the nose project obsolete
In-Reply-To: <1419756657.65.0.513358597735.issue23125@psf.upfronthosting.co.za>
Message-ID: <1419785462.26.0.128745401544.issue23125@psf.upfronthosting.co.za>


Berker Peksag added the comment:

Fixed. Thanks for the report, Damien.

----------
nosy: +berker.peksag
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
versions: +Python 2.7 -Python 3.2, Python 3.3, Python 3.6

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

From ls.sergey at gmail.com  Sat Dec 27 19:51:35 2014
From: ls.sergey at gmail.com (Sergey Skovorodkin)
Date: Sat, 27 Dec 2014 22:51:35 +0400
Subject: [docs] Inaccuracy in the description of factorial function
Message-ID: <CAMNHFoWe6Ti8526eix5vWSycns96OjO6Eyf+_R2Yi3JYQa7aSA@mail.gmail.com>

Documentation of math.factorial function says [1]:
> Raises ValueError if x is not integral or is negative.

It should be changed to:
> Raises ValueError if x is negative or TypeError if it is not integral.

It's applicable for Python versions 2.7 and 3.4. I didn't check it for
other versions.

Doc/library/math.rst file.

Thanks

[1] https://docs.python.org/3/library/math.html#math.factorial
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141227/3f6d8f99/attachment.html>

From zachary.ware+pydocs at gmail.com  Mon Dec 29 08:23:08 2014
From: zachary.ware+pydocs at gmail.com (Zachary Ware)
Date: Mon, 29 Dec 2014 01:23:08 -0600
Subject: [docs] Inaccuracy in the description of factorial function
In-Reply-To: <CAMNHFoWe6Ti8526eix5vWSycns96OjO6Eyf+_R2Yi3JYQa7aSA@mail.gmail.com>
References: <CAMNHFoWe6Ti8526eix5vWSycns96OjO6Eyf+_R2Yi3JYQa7aSA@mail.gmail.com>
Message-ID: <CAKJDb-P08f_9ZE=ikDMZv5ArJ6NaUJY502GmVhv_=7dstT4x-Q@mail.gmail.com>

Hi Sergey,

On Sat, Dec 27, 2014 at 12:51 PM, Sergey Skovorodkin
<ls.sergey at gmail.com> wrote:
> Documentation of math.factorial function says [1]:
>> Raises ValueError if x is not integral or is negative.
>
> It should be changed to:
>> Raises ValueError if x is negative or TypeError if it is not integral.
>
> It's applicable for Python versions 2.7 and 3.4. I didn't check it for other
> versions.

Thanks for the report, but I don't think any change should be made.  See below:

   >>> math.factorial(-3)  # negative x
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: factorial() not defined for negative values
   >>> math.factorial(3.14)  # non-integral x
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: factorial() only accepts integral values
   >>> math.factorial('nope')  # non-number x
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: an integer is required (got type str)

The TypeError raised in the non-number x case is just like the
TypeError that any function might raise if it receives an argument of
the wrong type.  We generally don't document places that could raise
TypeError because nearly any function could, and a TypeError generally
indicates a programming error rather than something that can (or
should) be recovered from.

Regards,
-- 
Zach

From report at bugs.python.org  Mon Dec 29 10:10:38 2014
From: report at bugs.python.org (Nick Coghlan)
Date: Mon, 29 Dec 2014 09:10:38 +0000
Subject: [docs] [issue19548] 'codecs' module docs improvements
In-Reply-To: <1384133353.82.0.173341188397.issue19548@psf.upfronthosting.co.za>
Message-ID: <1419844235.65.0.616803684977.issue19548@psf.upfronthosting.co.za>


Nick Coghlan added the comment:

I started making a few edits based on Zuo and Walter's comments while getting this patch ready for merging, and decided the end result could benefit from an additional round of feedback before committing it.

This particular patch is also aimed at the Python 3.4 maintenance branch rather than at trunk - the introduction of the new namereplace error handler in 3.5 means that the previous patch didn't apply cleanly to the maintenance branch.

While Zoinkity's feedback is also valid (i.e. multibyte codecs aren't documented properly, custom codec registration is both harder than it really should be and not well documented), I think those are better filed and handled as separate issues, rather than trying to handle them here as part of the general "bring the current content of the codec module documentation up to date with the current state of Python 3".

----------
assignee: docs at python -> ncoghlan
stage: patch review -> commit review
Added file: http://bugs.python.org/file37553/issue19548-codecs-doc.py34.patch

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

From report at bugs.python.org  Tue Dec 30 15:24:32 2014
From: report at bugs.python.org (Mark Lawrence)
Date: Tue, 30 Dec 2014 14:24:32 +0000
Subject: [docs] [issue19980] Improve help('non-topic') response
In-Reply-To: <1386984892.27.0.919528696836.issue19980@psf.upfronthosting.co.za>
Message-ID: <1419949472.42.0.0665702086341.issue19980@psf.upfronthosting.co.za>


Mark Lawrence added the comment:

I screwed up, sorry folks.  If the latest patch isn't correct I give up as it's three strikes and I'm out :(

----------
Added file: http://bugs.python.org/file37565/issue19880v3.diff

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

From zuo at chopin.edu.pl  Tue Dec 30 14:38:56 2014
From: zuo at chopin.edu.pl (zuo at chopin.edu.pl)
Date: Tue, 30 Dec 2014 13:38:56 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141230133856.29748.54178@psf.upfronthosting.co.za>

A few more comments.


http://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode420
Doc/library/codecs.rst:420: Codec Objects
Still the relation between the `codec` term and the Codec class/objects
is not clear IMHO.

http://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode829
Doc/library/codecs.rst:829: :term:`text encoding` and recreating the
A see some term confusion here: the `text encoding` term is defined (in
the glossary) just as a *kind of* *codec*, buy *here* the words
`encoding` and `decoding` refer to activities (each being a reversal of
the other) performed *by* a *codec*.

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

From sujosibn at icloud.com  Tue Dec 30 16:26:12 2014
From: sujosibn at icloud.com (Peter McCahy)
Date: Tue, 30 Dec 2014 15:26:12 +0000
Subject: [docs] Problem with Python Idle
Message-ID: <1E29BC37-4C35-435B-B900-659DA5A8888B@icloud.com>

Good afternoon,

I hope you can assist.  I have decided to learn some programming and have downloaded Python as it appears to offer the advantage of being logical without being over complicated.

I have installed Python 3.4 on my Mac which is running OS X 10.10.1 Yosemite.  

When I open the program Idle I get the message

>>> WARNING: The version of Tcl/Tk (8.5.9) in use may be unstable.
Visit http://www.python.org/download/mac/tcltk/ for current information.

I tried typing in some lines of code copied from a Python tutorial I found on the Python website
After Hours Programming Python 3 Tutorial <http://www.afterhoursprogramming.com/tutorial/Python/Overview/> (Python 3)
Although the code ran OK on the tutorial website it produced errors when I typed it in Idle.

I visited the site quoted in the error message and as a result of information given there I downloaded and installed Wish 8.6 which has version Tcl 8.6 & Tk 8.6 (8.6.3)

However I still got the same error message.  I, therefore, uninstalled Python and downloaded it again from the Python website and reinstalled it in the hope that it would recognise the new version of Tcl/Tk.
But, the same error message still appears.  The program Idle does not seem to recognise that I have Tcl8.6 &Tk 8.6.3 installed instead of Tcl/Tk 8.5.9

There must be a simple error I am making, but I do not know what it is.  

This is the first time that I have tried anything like programming and I would appreciate assistance if possible.

Kind Regards

Peter McCahy
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20141230/333a911e/attachment.html>

From zachary.ware+pydocs at gmail.com  Tue Dec 30 17:57:38 2014
From: zachary.ware+pydocs at gmail.com (Zachary Ware)
Date: Tue, 30 Dec 2014 10:57:38 -0600
Subject: [docs] Problem with Python Idle
In-Reply-To: <1E29BC37-4C35-435B-B900-659DA5A8888B@icloud.com>
References: <1E29BC37-4C35-435B-B900-659DA5A8888B@icloud.com>
Message-ID: <CAKJDb-M5tk++XaJ3kKDT6epnSSgxuR_USBYbCLAVf0VuNoGqEw@mail.gmail.com>

Hi Peter,

On Tue, Dec 30, 2014 at 9:26 AM, Peter McCahy <sujosibn at icloud.com> wrote:
> Good afternoon,
>
> I hope you can assist.  I have decided to learn some programming and have
> downloaded Python as it appears to offer the advantage of being logical
> without being over complicated.
>
> I have installed Python 3.4 on my Mac which is running OS X 10.10.1
> Yosemite.
>
> When I open the program Idle I get the message
>
>>>> WARNING: The version of Tcl/Tk (8.5.9) in use may be unstable.
> Visit http://www.python.org/download/mac/tcltk/ for current information.
>
> I tried typing in some lines of code copied from a Python tutorial I found
> on the Python website
>
> After Hours Programming Python 3 Tutorial (Python 3)
>
> Although the code ran OK on the tutorial website it produced errors when I
> typed it in Idle.
>
> I visited the site quoted in the error message and as a result of
> information given there I downloaded and installed Wish 8.6 which has
> version Tcl 8.6 & Tk 8.6 (8.6.3)
>
> However I still got the same error message.  I, therefore, uninstalled
> Python and downloaded it again from the Python website and reinstalled it in
> the hope that it would recognise the new version of Tcl/Tk.
> But, the same error message still appears.  The program Idle does not seem
> to recognise that I have Tcl8.6 &Tk 8.6.3 installed instead of Tcl/Tk 8.5.9
>
> There must be a simple error I am making, but I do not know what it is.

First off, this is not the correct list for usage questions like this;
this list is meant for discussion about the Python documentation.
You'll have better luck asking questions like this on the main list,
python-list at python.org.

That said, I suspect the problem may be that the version of tkinter
(which is the graphical framework behind IDLE) is as far as I know
compiled against Tcl/Tk 8.5, and thus can't use Tcl/Tk 8.6.  I'd
suggest trying the latest Tcl/Tk 8.5 (look for 8.5.17.0 on
http://www.activestate.com/activetcl/downloads).  If that doesn't
help, please re-ask your question on python-list.

Hope this helps,
--
Zach

From report at bugs.python.org  Wed Dec 31 10:47:51 2014
From: report at bugs.python.org (Friedrich Spee von Langenfeld)
Date: Wed, 31 Dec 2014 09:47:51 +0000
Subject: [docs] [issue23139] syntax diagram after EBNF description?
Message-ID: <1420019271.73.0.760663743856.issue23139@psf.upfronthosting.co.za>


New submission from Friedrich Spee von Langenfeld:

In our full grammar specification (10th chapter of the language reference, https://docs.python.org/3/reference/grammar.html), the grammar of Python is comprehensively notated. What would you think of adding a picture with an equivalent syntax diagram (e. g. produced with the help of http://www.bottlecaps.de/rr/ui) to open a new way of understanding for readers?

----------
assignee: docs at python
components: Documentation
messages: 233236
nosy: Friedrich.Spee.von.Langenfeld, docs at python
priority: normal
severity: normal
status: open
title: syntax diagram after EBNF description?

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

From report at bugs.python.org  Wed Dec 31 17:15:07 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:15:07 +0000
Subject: [docs] [issue18779] Misleading documentations and comments in
	regular	expression HOWTO
In-Reply-To: <1376898316.85.0.0813282739116.issue18779@psf.upfronthosting.co.za>
Message-ID: <1420042507.15.0.215481778696.issue18779@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:21:30 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:21:30 +0000
Subject: [docs] [issue14944] Setup & Usage documentation for pydoc,
	idle & 2to3
In-Reply-To: <1338256058.02.0.10025521772.issue14944@psf.upfronthosting.co.za>
Message-ID: <1420042890.0.0.322317609651.issue14944@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:21:55 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:21:55 +0000
Subject: [docs] [issue14945] Setup & Usage documentation for selected stdlib
	modules
In-Reply-To: <1338256259.22.0.129056676976.issue14945@psf.upfronthosting.co.za>
Message-ID: <1420042915.35.0.338508795033.issue14945@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:22:16 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:22:16 +0000
Subject: [docs] [issue11352] Update cgi module doc
In-Reply-To: <1298895261.86.0.965235067518.issue11352@psf.upfronthosting.co.za>
Message-ID: <1420042936.22.0.621596298649.issue11352@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:22:31 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:22:31 +0000
Subject: [docs] [issue17006] Add advice on best practices for hashing secrets
In-Reply-To: <1358758082.76.0.415880124971.issue17006@psf.upfronthosting.co.za>
Message-ID: <1420042951.97.0.818157096774.issue17006@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:23:00 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:23:00 +0000
Subject: [docs] [issue5901] missing meta-info in documentation pdf
In-Reply-To: <1241246578.79.0.771794251259.issue5901@psf.upfronthosting.co.za>
Message-ID: <1420042980.81.0.556767261348.issue5901@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:23:08 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:23:08 +0000
Subject: [docs] [issue18280] Documentation is too personalized
In-Reply-To: <1371889714.5.0.753258621658.issue18280@psf.upfronthosting.co.za>
Message-ID: <1420042988.62.0.738166381448.issue18280@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:23:14 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:23:14 +0000
Subject: [docs] [issue20487] Odd words in unittest.mock document.
In-Reply-To: <1391355507.86.0.158179018907.issue20487@psf.upfronthosting.co.za>
Message-ID: <1420042994.05.0.676241018495.issue20487@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:25:20 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:25:20 +0000
Subject: [docs] [issue18518] return-ing within code timed with timeit.timeit
	causes	wrong return value of timeit.timeit
In-Reply-To: <1374400020.0.0.45788018989.issue18518@psf.upfronthosting.co.za>
Message-ID: <1420043120.54.0.500487871772.issue18518@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 17:34:48 2014
From: report at bugs.python.org (A.M. Kuchling)
Date: Wed, 31 Dec 2014 16:34:48 +0000
Subject: [docs] [issue16776] Document PyCFunction_New and PyCFunction_NewEx
	functions
In-Reply-To: <1356434154.16.0.0981038830976.issue16776@psf.upfronthosting.co.za>
Message-ID: <1420043688.25.0.777553643338.issue16776@psf.upfronthosting.co.za>


Changes by A.M. Kuchling <amk at amk.ca>:


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

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

From report at bugs.python.org  Wed Dec 31 19:16:58 2014
From: report at bugs.python.org (Serhiy Storchaka)
Date: Wed, 31 Dec 2014 18:16:58 +0000
Subject: [docs] [issue18518] return-ing within code timed with timeit.timeit
	causes	wrong return value of timeit.timeit
In-Reply-To: <1374400020.0.0.45788018989.issue18518@psf.upfronthosting.co.za>
Message-ID: <1420049817.97.0.767900423885.issue18518@psf.upfronthosting.co.za>


Serhiy Storchaka added the comment:

May be add a guard against statements which can confuse timeit? These are not only "return", but "yield", and "break" and "continue" outside of a loop. Proposed patch checks that testing code can be compiled outside of a function.

----------
assignee: docs at python -> 
components: +Library (Lib) -Documentation
nosy: +serhiy.storchaka
stage:  -> patch review
versions: +Python 3.5 -Python 3.3
Added file: http://bugs.python.org/file37577/timeit_reject_invalid_statements.patch

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

From vadmium+py at gmail.com  Wed Dec 31 10:53:25 2014
From: vadmium+py at gmail.com (vadmium+py at gmail.com)
Date: Wed, 31 Dec 2014 09:53:25 -0000
Subject: [docs] 'codecs' module docs improvements (issue 19548)
Message-ID: <20141231095325.29668.12096@psf.upfronthosting.co.za>


https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode325
Doc/library/codecs.rst:325: .. _surrogateescape:
On 2014/12/26 01:21:35, zuo wrote:
> Should be moved to the place above the ".. _error-handlers:" line
(341).

Still needs updating in the ?default? branch. Not relevant for the 3.4
branch.

https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode335
Doc/library/codecs.rst:335: Each codec has to define four interfaces to
make it usable as codec in Python:
On 2014/12/26 01:21:35, zuo wrote:
> Possible beginner's questions: is a codec an instance of
:class:`Codec`? Or of
> :class:`CodecInfo`?
My understanding is a codec is a CodecInfo instance pointing to concrete
classes implementing the (stateless) Codec, and/or stateful
StreamReader/Writer, IncrementalDe/Encoder interfaces. Not sure on how
many of these are mandatory though.

> What does it mean that it define those *four* intefraces?
> How is it related to the stateless/incremental/decoder/encoder and
stream
> writer/reader classes described below? Why here only *four* interfaces
and not
> *six* interfaces are mentioned? (i.e., what about *incremental
encoder* and
> *incremental decoder?*)

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode24
Doc/library/codecs.rst:24: bytes. Custom codecs may encode and decode
between arbitrary types, but some
Does this include non-sequence types? If so, the ?length consumed?
return value and the StreamReader class make no sense to me, and
finalizing incremental codecs becomes more difficult.

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode211
Doc/library/codecs.rst:211: a text stream.
Perhaps the last sentence is not needed, now that all these functions
are introduced as being for binary files.

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode382
Doc/library/codecs.rst:382: The standard error handlers are implemented
in the following functions:
This is just ?_Some_ standard error handlers?, since the surrogate
handlers are omitted.

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode420
Doc/library/codecs.rst:420: Codec Objects
On 2014/12/30 14:38:56, zuo wrote:
> Still the relation between the `codec` term and the Codec
class/objects is not
> clear IMHO.

Maybe changing the heading to ?Stateless Codec Objects? would help?

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode625
Doc/library/codecs.rst:625: *stream* must be a file-like object open for
writing binary data.
Did you mean to revert to ?binary data? here? Patch v3 changed the
wording here.

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newcode829
Doc/library/codecs.rst:829: :term:`text encoding` and recreating the
On 2014/12/30 14:38:56, zuo wrote:
> A see some term confusion here: the `text encoding` term is defined
(in the
> glossary) just as a *kind of* *codec*, buy *here* the words `encoding`
and
> `decoding` refer to activities (each being a reversal of the other)
performed
> *by* a *codec*.

This was my sloppy wording, when I tried to introduce a link to the
glossary. Maybe it should be added a couple sentences later:

Transforming a string into a sequence of bytes is known as *encoding*,
and recreating the string from the sequence of bytes is known as
*decoding*.  There are different methods for how this transformation can
be done.  (These methods are also called :term:`text encodings <text
encoding>`.)

https://bugs.python.org/review/19548/