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.