classification
Title: Email example using imaginary library installation error.
Type: resource usage Stage:
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: SilentGhost, barry, docs@python, jackotonye, maxking, r.david.murray, terry.reedy
Priority: normal Keywords:

Created on 2019-10-02 16:10 by jackotonye, last changed 2019-10-05 16:15 by maxking.

Messages (9)
msg353743 - (view) Author: jackotonye (jackotonye) Date: 2019-10-02 16:10
https://docs.python.org/3.7/library/email.examples.html
msg353745 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2019-10-02 16:20
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.
msg353755 - (view) Author: jackotonye (jackotonye) Date: 2019-10-02 17:01
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>
> _______________________________________
>
msg353997 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-10-05 07:20
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.
msg353998 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2019-10-05 08:09
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.
msg354015 - (view) Author: Abhilash Raj (maxking) * (Python committer) Date: 2019-10-05 15:46
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 :)
msg354016 - (view) Author: Abhilash Raj (maxking) * (Python committer) Date: 2019-10-05 15:48
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?
msg354017 - (view) Author: jackotonye (jackotonye) Date: 2019-10-05 16:07
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.
msg354018 - (view) Author: Abhilash Raj (maxking) * (Python committer) Date: 2019-10-05 16:15
We could move that comment to the top near the import, I am totally fine with that.
History
Date User Action Args
2019-10-05 16:15:18maxkingsetmessages: + msg354018
2019-10-05 16:07:49jackotonyesetmessages: + msg354017
2019-10-05 15:48:06maxkingsetmessages: + msg354016
2019-10-05 15:46:08maxkingsetmessages: + msg354015
2019-10-05 08:09:38SilentGhostsetmessages: + msg353998
2019-10-05 07:20:01terry.reedysetnosy: + terry.reedy, r.david.murray, maxking, barry
title: Email example using imaginary library installation error. The install shows that it only supports python 2.x but is listed under python 3.6+ docs. -> Email example using imaginary library installation error.
messages: + msg353997

versions: - Python 3.6
2019-10-02 17:01:04jackotonyesetmessages: + msg353755
2019-10-02 16:20:48SilentGhostsetnosy: + SilentGhost
messages: + msg353745
2019-10-02 16:10:48jackotonyesettitle: Email example using imaginary library installation error. The install shows that it only supports python 2.x but is listed for python 3.6+ -> Email example using imaginary library installation error. The install shows that it only supports python 2.x but is listed under python 3.6+ docs.
2019-10-02 16:10:03jackotonyecreate