Email example using imaginary library installation error.

[jackotonye]

BPO	38349
Nosy	@warsaw, @terryjreedy, @bitdancer, @maxking

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-10-02.16:10:03.652>
labels = ['3.8', 'docs', '3.7', '3.9', 'performance']
title = 'Email example using imaginary library installation error.'
updated_at = <Date 2019-10-05.16:15:18.636>
user = 'https://bugs.python.org/jackotonye'

bugs.python.org fields:

activity = <Date 2019-10-05.16:15:18.636>
actor = 'maxking'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-10-02.16:10:03.652>
creator = 'jackotonye'
dependencies = []
files = []
hgrepos = []
issue_num = 38349
keywords = []
message_count = 9.0
messages = ['353743', '353745', '353755', '353997', '353998', '354015', '354016', '354017', '354018']
nosy_count = 7.0
nosy_names = ['barry', 'terry.reedy', 'r.david.murray', 'SilentGhost', 'docs@python', 'maxking', 'jackotonye']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'resource usage'
url = 'https://bugs.python.org/issue38349'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[jackotonye]

https://docs.python.org/3.7/library/email.examples.html

[SilentGhost]

imaginary in the example is not meant to refer to https://pypi.org/project/Imaginary/ it's meant to refer to a module that you could write that would do all the dirty work. Perhaps, it's not the best name to use provided there is an actual module on pypi, alternatively half-baked outdated modules could be remove.

[jackotonye]

Might be best to make it a little more obvious since most examples are
considered executable code. That would require little modification.

On Wed, Oct 2, 2019 at 12:20 PM SilentGhost <report@bugs.python.org> wrote:

SilentGhost <ghost.adh@runbox.com> added the comment:

imaginary in the example is not meant to refer to
https://pypi.org/project/Imaginary/ it's meant to refer to a module that
you could write that would do all the dirty work. Perhaps, it's not the
best name to use provided there is an actual module on pypi, alternatively
half-baked outdated modules could be remove.

----------
nosy: +SilentGhost

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue38349\>

---

[terryjreedy]

The rest of the overly long title was "The install shows that it only supports python 2.x but is listed under python 3.6+ docs."

The lines in question are from the 2nd to last example.

  # An imaginary module that would make this work and be safe.
  from imaginary import magic_html_parser

The comment plus the names 'imaginary' and 'magic_html_parser' should make it pretty clear that 'imaginary' is meant to be an imaginary, hypothetical module with an imaginary, hypothetical method, not an actual module named 'imaginary' with an actual 'magic_html_parser' method.

jackotonye, do you have a concrete suggestion? I am tempted to close this, but will wait for suggestion and let the email people see this.

Also, when responding by email, please remove the quoted previous post and it is redundant on the web page.

[SilentGhost]

One fairly naive solution would be to define a magic_html_parser directly in the example and move explanatory comment there. In order not to break the code it could return an empty string.

[maxking]

The function of this imaginary method is described below:

# The magic_html_parser has to rewrite the href="cid:...." attributes to
# point to the filenames in partfiles.  It also has to do a safety-sanitize
# of the html.  It could be written using html.parser.

This implementation is going to be non-trivial (more than just a wrapper around html.parser) I think, and I would like to not make the example related to email even longer due to that implementation.

And I agree with Terry, the comment should make it pretty clear, there aren't any dependencies in the examples outside of standard library.

Any other synonym that we'd choose could end up being a package in pypi someday :)

[maxking]

The comment should make it clear that it is an made up imaginary module. The no dependencies outside of standard library is not written, I guess?