Reviewing the What's New docs, this seemed like the easiest way to give Raymond a list of things I noticed:

- first sentence in the "ast" module section needs rewording (currently includes fragments from a couple of different phrasings)

- in the "dis" module section, dis.dis has also acquired the ability to disassemble source string directly, avoiding the need to compile them manually first (see issue 6507).

- in the "dbm" module section, there is another case of a sentence containing fragments from two different phrasings

- the new "handler of last resort" functionality in the logging module deserves a mention (see issue 10626 and the explanation at http://docs.python.org/dev/howto/logging.html#what-happens-if-no-configuration-is-provided)

- Vinay's rewrite of the logging module docs to be significantly more approachable (by splitting them into the raw logging API docs and the "read-as-much-as-you-need-to" logging HOWTO) is also a notable and welcome change.

A couple more in the Build and CAPI section:

- "The is a new function" should be "There is a new function"

- "The PyUnicode_CompareWithASCIIString() now" either needs to drop the "The" or add "function" before the "now". 

It's fascinating to read all that and realise how much actually has been done since 3.1 came out.

Another significant logging change: the addition of the "style" parameter for Formatter objects (allowing the use of str.format and string.Template style substitution instead of percent formatting)

The last two logging changes potentially worth mentioning that I noticed:

- simple callables can now be supplied as logging filters (see the version 3.2 note in http://docs.python.org/dev/library/logging#filter-objects)

- the logging API docs now include a section dedicated to the available attributes on LogRecord instances (http://docs.python.org/dev/library/logging#filter-objects). This makes it much easier to write Filter and Formatter objects that reference these attributes.

I was wrong, I found one more potentially notable logging change:
http://docs.python.org/dev/library/logging#logging.setLogRecordFactory

Adding Vinay, given the number of logging changes in 3.2 that don't appear to be in the What's New yet (the only logging change noted there at the moment is the inclusion of PEP 391)

Nick, thanks for the read-through and comments.

Later this week, will get add a section of logging.

Other people are also welcome to use this tracker item for other comments.

Correct docs links for LogRecord attributes section: http://docs.python.org/dev/library/logging#logrecord-attributes

Eli, put your suggestions here.

Do not edit the document directly.
Right now, it's conflicting with
my pending edits.  Also, see
the instruction at the top of
the document.

Raymond, as I said in the email sorry I wasn't aware of the issue, and Georg permitted me to commit directly to the file once the freeze is over. Maybe there was a misunderstanding.

Also, can you refer me to the part of the file you mean? I see it says "Anyone can add text to the document" but then warns that you may change it later. I have no problem with that, and I split my commit to several to make it easier to fix/reject.

I was just told about typo and grammar fixes though :)

r88274 - python/branches/py3k/Doc/whatsnew/3.2.rst
"Revert r88272 -- the examples are more readable with spacing."


Raymond - then perhaps we should consider revising PEP 8 as well. When I first read it, the "no spaces around =" rule for kwargs was strange at first, but then it grew on me. Regardless of personal style preferences, what we can't do (IMvHO) is have our official docs not follow PEP 8, and be inconsistent among themselves for that matter (very similar examples in argparse.rst and whatsnew/3.2.rst formatted differently)

Do yourself a favor and don't become a PEP 8 nut ;-)

The primary purpose of the example in whatsnew is to teach, demonstrate, and explain.  Any PEP 8 considerations take a back seat to that purpose (even PEP 8 itself admonishes the reader with the famous foolish consistency quotation).

The purpose behind the usual space conventions for keyword arguments is to allow them to be visually grouped when more than one is used on a line.  In the case of the argparse example, the important parameters are being listed one per line along with an explanatory comment.  In my judgement, the example is more readable with the spacing as it allows the eye to easily pick-out the argument list.  

Am sorry, but it is not really open for debate.  Whatsnew is a single-author document reflecting an enormous amount of my time culling changes, crafting expository text, and creating strong examples.  As such, it is going to very much reflect my style and judgement.

I agree with Raymond: whoever puts in 95% of work for a single document should have artistic license over the style.

I also don't complain if people use a different indentation style in module docs they write (but I reserve the right to use mine if I edit these docs).

It is very nice having standards, but well, I hope you know about the hobgoblin :)

And particularly about keyword arg spacing, I found that it very much depends on the manner of arguments you're dealing with.  For dict()-style functions with lots of kwargs, it can really be much easier on the eyes to use space around the '=', or even use this style:

foo = dict(
    some_key        = some_value,
    some_longer_key = some_other_value,
)

even if PEP 8 doesn't approve of that either.

"Python’s import mechanism can now load modules installed in directories with non-ASCII characters in the path name: import møøse.bites"

møøse is not a module *path*, but a module *name*... This example doesn't work on Windows: see #3080. Module paths is the sys.path list. An use case is Python installed in the user directory with diacritics in the user name (eg. Python installed in C:\Users\Amélie\...).

"The biggest news for Python 3.2 is that the email package and nntplib modules now work correctly with the bytes/text model in Python 3."

You can also include mailbox in this list.

Should we add imports in all examples? Eg. add import math in:

>>> repr(math.pi)
'3.141592653589793'
>>> str(math.pi)
'3.141592653589793'

At least, accumulate should be replaced by itertools.accumulate in the following example:

>>> list(accumulate(8, 2, 50))
[8, 10, 60]

Because it looks like accumulate() is a builtin function.

Some other examples without the module name: "tally = Counter(dogs=5, cat=3)", "d = OrderedDict...", "d = deque('simsalabim')", "all_polls_closed = Barrier(len(sites))", ...

I prefer to have the module name in examples because it is easy to test them: just copy/paste in an interpreter. It's even more easier if there is the import statement :-)

The import in the following example is wrong :

>>> import datetime
>>> datetime.now(timezone.utc)
...

It should be replaced by: from datetime import datetime, timezone.

Nick, thanks for highlighting the logging changes. In addition to what you mentioned, there's still more, at least some of which deserves to get into "what's new" :-)

1. QueueHandler and QueueListener classes were added to help with logging in multiprocessing applications.
2. Logger got a getChild(suffix) method which returns a child logger with the given suffix.
3. An optional stack_info parameter to logging calls provides complete stack information (not just the parts unwound during exception handling).
4. Logger got a hasHandlers() method which returns True if any handlers are available for the logger (including those in ancestor loggers).
5. The LoggerAdapter implementation was changed to improve its usability, during which its public API gained the isEnabledFor(),   getEffectiveLevel(), hasHandlers() and setLevel() methods.
6. HTTPHandler gained secure and credentials keyword arguments for use with SSL and sites needing authentication.
7. StreamHandler now has a terminator attribute (defaults to '\n' for backward compatibility) but can now be set on a per-handler basis.
8. SysLogHandler gained a socktype keyword argument which defaults to SOCK_DGRAM but can accept SOCK_STREAM for use with newer syslog daemons which can listen using TCP.
9. basicConfig() also takes an optional style argument (default '%', also accepts '{' or '$').
10. SMTPHandler takes optional "secure" kwarg for use with TLS.
11. SysLogHandler now treats Unicode as per RFC 5424.

Er ... that's it for now.

ABCMeta should be replaced by abc.ABCMeta, or other "abc." prefixes should be removed.

class Temperature(metaclass=ABCMeta):
    @abc.abstractclassmethod
    def from_fahrenheit(self, t):
        ...
    @abc.abstractclassmethod
    def from_celsius(self, t):
        ...

I don't know/understand the "->" syntax:

>>> print(byte_stream.getvalue())
b'G3805  showroom   Main chassis    ' ->
b'X7899  warehouse  Reserve cog     ' ->
b'L6988  receiving  Primary sprocket'

If you would like to split record by record, use something like:

>>> x=byte_stream.getvalue()
>>> [x[index:index+REC_LEN] for index in range(0,len(x),REC_LEN)]
[b'G3805  showroom   Main chassis    ', b'X7899  warehouse  Reserve cog     ', b'L6988  receiving  Primary sprocket']

--

$ ./python 
Python 3.2rc2+ (py3k:88277, Jan 31 2011, 14:24:09) 
>>> from ast import literalrequest
ImportError: cannot import name literalrequest

--

>>> import shutil, pprint
...
>>> f = make_archive(...)

It's shutil.make_archive(), not make_archive() here.

>>> shutil.register_archive_format(                  # register a new archive format
        name = 'xz',
        function = 'xz.compress',
        extra_args = [('level', 8)],
        description = 'xz compression'
)

The function have to be callable: a str is not callable.

Thanks Victor.

Please consider mentioning that several modules can now be called with -m: pickle, pickletools and tkinter.

In the abc.abstractclassmethod example(http://docs.python.org/dev/py3k/whatsnew/3.2.html#abc), the methods probably should use cls as the name of the first parameter, not self, because they are classmethods.

In the shutil example (http://docs.python.org/dev/py3k/whatsnew/3.2.html#shutil) the function argument of shutil.register_archive_format is a string, but according to http://docs.python.org/dev/py3k/library/shutil.html#shutil.register_archive_format it should be a callable.

In the paragraph on OS X builds, suggest changing "OS X" to "Mac OS X". 

Also, instead of the direct recommendation to install ActiveState Tcl, a recommendation that could very well change over the lifetime of the 3.2 release and the released copies of the What's New document, please substitute a reference to the web page, http://www.python.org/download/mac/tcltk/ which will contain the most up-to-date information.

Ned, thanks for the "Mac" correction. I prefer to leave the Tcl/Tk recommendation in place for several reasons:

* for right now, it is needed to get tkinter to work and if we're too indirect about the fix, no one will find it and their install won't work.

* if other options become available in the future or it stops being needed, I will update the whatsnew recommendation in a point release.

* the recommendation won't stop being correct.  it may become unnecessary, but it will still work.

The only bad outcome here would be if we fail to speak-up and tell users what they have to do to get their install to work.  There are no points for hiding the message behind another link and letting people get erratic crashes when they do an install and try to run IDLE.

Victor, I added more imports and fixed the ones that were mismatched with the sample code.  I've left a few out in a couple places where I thought the imports got in the way of the narrative.

I understand your point and it is not a huge issue but let me make an attempt to expand on the rationale.

> * for right now, it is needed to get tkinter to work and if we're too indirect about the fix, no one will find it and their install won't work.

It may be indirect but the situation is complicated and dynamic.  There are references to the canonical webpage in the Installer welcome message (in bold), the Installer ReadMe, and in IDLE if the known-to-be-problematic Apple version is being used.  As it stands, the What's New document is the only place that doesn't refer to the webpage.

> * if other options become available in the future or it stops being needed, I will update the whatsnew recommendation in a point release.

That's fine but it doesn't necessarily help the users who will not be installing cutting edge versions of Python 3.2.x maintenance releases.

> * the recommendation won't stop being correct.  it may become unnecessary, but it will still work.

That's not necessarily true.  We have no control over what ActiveState does.  From their website:

>Looking for access to older versions of ActiveTcl?
>  Community Edition offers access to the newest versions of ActiveTcl.
>  Access to older versions is available only in Business Edition.

We could find that the current working version has been replaced by one that doesn't work.  Between the ActiveState 8.5.8.2 (released earlier in 2010) and 8.5.9, there was a huge change, going from supplying the Carbon-based Tk version (which was supported on Mac OS 10.4+ and on PPC and Intel 32-bit-only archs) to the Cocoa-based one (10.5+ and Intel-only and 32-/64-bit).  The Carbon one is no longer available to the community.  If you were using Tk 8.5 on a PPC machine or on 10.4, my understanding it that you are now out of luck unless you make arrangements with ActiveState to be covered under presumably a non-zero-cost license.  Something like that could happen again.

There is also the issue of the ActiveState community license; some users of the python.org distribution may not be able to use the ActiveState version because of its terms.  There are more details that need to be filled in on the download page prior to release to expand on that.

The whole point of creating the canonical webpage is to have one place to go for the current information in an inherently dynamic environment.  I think there is a strong case to change the wording in the What's New as suggested but, if you think it better to not do so, I will be OK with your decision.

Another remark. In the "poplib" section, there is a paragraph about asyncore: I don't see how both are related.

In the What's new in 3.2: there is no mention of the PEP 3003 (Python Language Moratorium). May we add a section "What is not new in 3.2"? :-) This PEP is something specific to Python 3.2.

Victor, I don't think that would be useful in the Whatsnew document.  That PEP was really about letting other implementations get caught-up.  It has nearly zero relevance to users of CPython.

Here are couple of Review Comments on What's new document.

1. The logging dictConfig example fails if you try directly out-of-text.

The conf file is opened as a 'rb' and json module throws an error as "TypeError: can't use a string pattern on a bytes-like object".  Suggestion - Just reading it as string is fine.
Also, this example throws another error from json, when you read it as string.

ValueError: Expecting property name: line 4 column 17 (char 204)

I was able to fix it by simplifying the conf.json, but I think the current one itself should be fixed and made to work.

Related suggestion - I see another section on logging further down. It would be better to combine the sections.

2.Issue number for functools.lru_cache is not mentioned. If no tracker id/ discussion is available, checkin link can be mentioned.

3. There is section for Popen which says, subprocess.Popen() functions now support with statements for auto-closing of the file descriptors. Not really. Only os.popen() function supports it.

4. In the concurrent.futures example, it is given as:

import threading, shutil
with threading.ThreadPoolExecutor(max_workers=4) as e:

It should be:
import concurrent.futures, shutil
with concurrent.futures.ThreadPoolExector(max_workers=4) as e:


Please correct these before the release on 19th.

> 2.Issue number for functools.lru_cache is not mentioned. If no tracker
> id/ discussion is available, checkin link can be mentioned.
There was no tracker issue for that; the checkin is r83327, but I don’t think it would be useful to mention it in whatsnew.

> 3. There is section for Popen which says, subprocess.Popen() functions
> now support with statements for auto-closing of the file descriptors.
> Not really. Only os.popen() function supports it.
You must have missed line 752 and following of Lib/functools.py.  Brian did add context management support to Popen in response to my request in #10554.

I meant Lib/subprocess.py, of course :)

On Fri, Feb 18, 2011 at 2:18 AM, Éric Araujo <report@bugs.python.org> wrote:

> You must have missed line 752 and following of Lib/functools.py.  Brian did add context management support to Popen in response to my request in #10554.

Yes, I did miss it because the What's new document referenced only
issue 7461 and I saw that checkin had changes for os.popen only.
Thanks for pointing this out. I think #10554 should be referenced
where the claim for subprocess.Popen Context Manager support is
mentioned.
Other comments have been care of.

Attached patch adds a missing attribution, a missing bug number, fixes one typo (“content manager”) and five grammar issues.

I haven’t had time to make a full read-through during the last weeks, but here are a few comments about the overall structure of the file:
- The introduction is a bit scarce (compare that of 2.6);
- “Other Language Changes” sounds strange, given that the previous sections (PEPs) are language as well as library changes → name it something like “Small Language Changes”;
- “New, Improved, and Deprecated Modules” are not sorted nor grouped;
- Ditto for the bits of advice in the Porting section;
- The small sections about Unicode and codecs could be merged;
- What Antoine said about “Code repository”.

Éric, go ahead an apply this patch except for the insertion of "the" in the codecs section.

I'm not making regrouping, reordering, merging or other stylistic changes at this point.

Applied in r88441.

I checked again that the issue numbers were right, and discovered that
the functions in site related to PEP 370 were actually new in 2.6, not
3.2, so you may want to remove that section.

> I checked again that the issue numbers were right, and discovered that
> the functions in site related to PEP 370 were actually new in 2.6, not
> 3.2, so you may want to remove that section.

Sorry: The functions are indeed new in 2.7/3.2, it’s the command-line
functionality (python -m site --user-base) that was already here in
previous versions.

It appears that Misc/NEWS in 3.2 lists the new functions under the 3.1 section, among other strange differences.

On Sun, Feb 20, 2011 at 4:22 AM, Éric Araujo <report@bugs.python.org> wrote:
> It appears that Misc/NEWS in 3.2 lists the new functions under the 3.1 section, among other strange differences.

"new in 3.2" changes are relative to 3.1, while 2.7 is relative to
2.6. They're treated as separate streams of development. Since 3.1
came out well after 2.6, there are some things that were new in 2.7
that 3.1 already included.

Thanks for the message, but I already knew that.  What I meant is that in the 3.2 version of Misc/NEWS, the addition of the functions is listed under the 3.1 section instead of 3.2.

The section about os.environb talks about unencoded bytes and unencoded environment variables instead of undecoded.

It seems no new issues have arisen.
If something new comes-up, feel free to re-open.

“unencoded” is still here.

New changeset a805d4415e34 by Raymond Hettinger in branch '3.2':
Issue  #11071: Fix whatsnew description of O/S access to raw bytes.
http://hg.python.org/cpython/rev/a805d4415e34

New changeset df1a1774a544 by Raymond Hettinger in branch 'default':
Issue  #11071: Fix whatsnew description of O/S access to raw bytes.
http://hg.python.org/cpython/rev/df1a1774a544