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

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.

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\>

---

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.

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.

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 :)

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?

I’m fine with closing the issue.

Seems trivial now after reading the comments but noting that most developers take examples as running code and spend less time going over the comments and a dependency that had similar names makes it even harder to make the point.

If the comment was at the usage rather than at import it would be more obvious that it needs to be a custom implementation.

We could move that comment to the top near the import, I am totally fine with that.

We could also rename imaginary to imaginary_module and then it won't look like a real module name.

The file under consideration was written by R. David Murray in 2014, with little revision since. The suggestions include: do nothing; rewrite the import comment; change the fake name (in particular, to imaginary_module); move the function description up to the import; and turn the function description into a docstring for a def that replaces the import (SilentGhost). There was no consensus on which to do.

Stanley(slateny)'s PR changes the import name and moves the fake function description up. After reading it and thinking more, I prefer SilentGhost's idea, except that I would want to raise rather than return an empty string. One reason is that understanding the function description requires knowing its signature. I presume that this is why David put the comment where he did, just above the call that shows the intended signature.

So, replace the import and its comment and turn the current multiline function comment into a docstring as follows.

def magic_html_parser(html_text, partfiles):
    """Return safety sanitized html linked to partfiles.

   Rewrite the href="cid:...." attributes to point to the filenames in partfiles.
   Though not trivial, this should be possible using html.parser.
    """
    raise NotImplementedError("Add the magic needed")

I am giving slateny at least a week to write a new PR if he wishes.