classification
Title: examples in email.policy doc are fu'd
Type: behavior Stage: resolved
Components: Documentation, email Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, docs@python, python-dev, r.david.murray, rurpy2
Priority: normal Keywords:

Created on 2013-07-29 06:27 by rurpy2, last changed 2013-07-30 18:43 by python-dev. This issue is now closed.

Messages (5)
msg193852 - (view) Author: rurpy (rurpy2) Date: 2013-07-29 06:27
In the first example in the documentation for library module email.policy (http://docs.python.org/3/library/email.policy.html#module-email.policy):

  >>> from email import msg_from_binary_file
  >>> from email.generator import BytesGenerator
  >>> from subprocess import Popen, PIPE
  >>> with open('mymsg.txt', 'b') as f:
  ...     msg = msg_from_binary_file(f)

line 1: The module is "message_from_binary_file", not "msg_from_binary_file"
line 4: The mode must be "rb", not "b".
line 5: Same module (mis-)name problem as line 1.

Then in following example...

  >>> import os
  >>> with open('converted.txt', 'wb') as f:
  ...   f.write(msg.as_string (policy=msg.policy.clone (linesep=os.linesep))

line 3: Ubnbalanced parens, .as_string() has no "policy" keyword arg.

Please note I am trying to figure out how to use the email module for the first time and the above errors are glaring.  There may be (probably are) other errors in the examples and in the text that I am unaware of -- I've made  no attempt to find any others.  I suggest that someone familiar with email module review this page more carefully.
msg193882 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-07-29 17:12
Thank you for the report.  We currently don't have automated testing of the doctest strings, and I must have neglected to hand test those examples before release.  I will fix (and test!) them ASAP.
msg193892 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-07-29 20:02
New changeset ffc7ea3c04a5 by R David Murray in branch '3.3':
#18584: make doctest examples in email documentation pass.
http://hg.python.org/cpython/rev/ffc7ea3c04a5

New changeset 206685a4b19c by R David Murray in branch 'default':
Merge #18584: make doctest examples in email documentation pass.
http://hg.python.org/cpython/rev/206685a4b19c
msg193893 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-07-29 20:06
OK, this fixed.  The 'as_string' example will still fail, as I never added the policy argument to that method.  I'll deal with that in a separate issue.

Unfortunately it is quite possible there are other errors in the new docs, since they are new...I will review them in the coming month as I'll be working on adding some additional new features to the provisional policies.
msg193947 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-07-30 18:43
New changeset 7b86be4e822c by R David Murray in branch '3.3':
#18584: s/testcleanup/testsetup/ until we switch to Sphinx 1.1.
http://hg.python.org/cpython/rev/7b86be4e822c

New changeset 1901a04a3b4a by R David Murray in branch 'default':
Merge #18584: s/testcleanup/testsetup/ until we switch to Sphinx 1.1.
http://hg.python.org/cpython/rev/1901a04a3b4a
History
Date User Action Args
2013-07-30 18:43:26python-devsetmessages: + msg193947
2013-07-29 20:06:01r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg193893

stage: needs patch -> resolved
2013-07-29 20:02:12python-devsetnosy: + python-dev
messages: + msg193892
2013-07-29 17:12:35r.david.murraysettype: behavior
components: + email
versions: + Python 3.4
nosy: + barry, r.david.murray

messages: + msg193882
stage: needs patch
2013-07-29 06:27:08rurpy2create