classification
Title: TypeError in smtpd module with string arguments
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, giampaolo.rodola, lorenzo.ancora, python-dev, r.david.murray, rvallury, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2016-01-26 20:34 by lorenzo.ancora, last changed 2016-09-07 18:11 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
smtpd_doc_updated.patch rvallury, 2016-08-08 09:42 smtpd Server documentation updated review
smtpd_doc_updated_2.patch rvallury, 2016-08-08 10:42 smtpd patch 2 with review comments applied review
smtpd_doc_updated_3.patch rvallury, 2016-08-09 09:44 smtpd patch 3 with review comments applied review
Messages (15)
msg258971 - (view) Author: Lorenzo Ancora (lorenzo.ancora) Date: 2016-01-26 20:34
smtpd.PureProxy(localaddr="host1", remoteaddr="host2")

...produces the error:

[...] smtpd.py", line 657, in __init__
    gai_results = socket.getaddrinfo(*localaddr, type=socket.SOCK_STREAM)
TypeError: getaddrinfo() got multiple values for argument 'type'

The module only works with:

smtpd.PureProxy(localaddr=("host1", 25), remoteaddr=("host2", 25))

The documentation does not specify the format of the INPUT parameters, only the CLI syntax with hostnames as "host:port" strings.
The underlying library should convert them to tuples or at least the documentation should be completed.
msg259229 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-01-30 01:48
I am guessing that 25 is the default port.  Autoconversion of 'host' to ('host', 25) would be a new feature ('enhancement') that would have to wait for the next Python version (3.6 or later).  Is there any precedent for this in any other module?

Does 2.7 act the same as 3.5?  A doc improvement could go there also.
msg259261 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-01-30 17:19
There is a strong change that smtpd is going to be deprecated in Python 3.6. See issue 25008 for details.

+1 for improving documentation.
msg259455 - (view) Author: Lorenzo Ancora (lorenzo.ancora) Date: 2016-02-03 03:52
(msg259229) Terry J. Reedy i Suggest that a standard and globally accepted scheme to manage IPv4 addresses is:

  "Host:PortNumber" --> (host, PortNumber)
  "Host"            --> (host, DefaultPortNumber)
  "IP:PortNumber" --> (host, PortNumber)
  "IP"            --> (host, DefaultPortNumber)

...where DefaultPortNumber is protocol and system dependent (IANA standard, see the SMTP line in: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml).

A simple research reveals that all versions of the module are (sadly) poorly documented, but the module is an interface to a very important protocol that indeed must be offered by the standard library.
The only little suggestion in the documentation of the module is: https://docs.python.org/3.6/library/socket.html#socket.socket.accept
...from a one-word link in: https://docs.python.org/3.6/library/smtpd.html#smtpd.SMTPChannel.addr
Which has only an indirect relation with the object itself.

Many users may not recognize the cause of the error if the documentation doesn't explicitate the information to correctly initialize the core objects of the module.
I also Suggest that at least the object should return an helpful error in newer versions of Python.

Thank you for your efforts guys. :-)
msg259475 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-02-03 12:02
Doc fixes unrelated to security fixes are not applied to security-fix-only versions.
msg259727 - (view) Author: Lorenzo Ancora (lorenzo.ancora) Date: 2016-02-06 12:51
(msg259475) Terry J. Reedy thank you for the correction, I've confused the versions affected with the versions actually supported.
Since this doesn't only affect the documentation, is it correct to assign the issue to docs@python?
The expert index indicates giampaolo.rodola as the module maintainer, so he should be moved from the nosy list to the field "Assigned To" and docs@python should be in the nosy list.

Also, there is a documentation on how to send a patch for a specific module in Python 3.5?
I'd like to help by creating a new source code patch. :-)
msg259747 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-02-06 18:41
Code patches should not be assigned to 'docs'.  But Berker, for the reason stated, thinks this should be doc only.  Giampaolo is not currently active, so should not be assigned the issue by anyone else.

After making a patch -- see the devguide -- use the File: Browse button to upload a file.  You can suggest a specific doc change in a message, without a .patch or .diff file.
msg259748 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-02-06 18:45
Note that the proposed code change would be a 3.6 only enhancement.  Adding the other versions was part of changing to a doc-only issue.  Note also that if the module is not deprecated, then a 3.6 code change could be considered.  But only a doc change for now.
msg259753 - (view) Author: Lorenzo Ancora (lorenzo.ancora) Date: 2016-02-07 00:03
(msg259748) ok, then I propose to correct https://docs.python.org/dev/library/smtpd.html?highlight=q#smtpd.SMTPServer from:

.. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,\
                      map=None, enable_SMTPUTF8=False, decode_data=True)

   Create a new :class:`SMTPServer` object, which binds to local address
   *localaddr*.  It will treat *remoteaddr* as an upstream SMTP relayer.  It
   inherits from :class:`asyncore.dispatcher`, and so will insert itself into
   :mod:`asyncore`'s event loop on instantiation.


To:


.. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,\
                      map=None, enable_SMTPUTF8=False, decode_data=True)

   Creates a new :class:`SMTPServer` object, which binds to local address
   *localaddr* and uses *remoteaddr* as an upstream SMTP relayer.
   Both parameters should be a tuple in the form ``("host", portnumber)``, where *host* is a valid IP/FQDN.
   The object will insert itself into :mod:`asyncore`'s event loop on instantiation (inherits from :class:`asyncore.dispatcher`) and can be started with a call to :class:`asyncore.loop`.

---

These clarifications should be also inserted in the source code as heredocs (without the Sphynx syntax).
I really think that those changes will make the use of smtpd easier.
msg272154 - (view) Author: Ram Vallury (rvallury) * Date: 2016-08-08 09:42
Updated the documentation of smtpd.
https://docs.python.org/3/library/smtpd.html#smtpserver-objects




* this is my first patch, please revert back to me or make learn if I do any mistake*
msg272159 - (view) Author: Ram Vallury (rvallury) * Date: 2016-08-08 10:42
Submitting patch 2 for smtpd doc changes
msg272227 - (view) Author: Ram Vallury (rvallury) * Date: 2016-08-09 09:44
added space before word portnumber. column space adjusted
msg274852 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-09-07 18:02
New changeset 1ed37f6e91bb by R David Murray in branch '3.5':
#26209: Clarify type of *localaddr*/*remoteadr* in smtpd docs.
https://hg.python.org/cpython/rev/1ed37f6e91bb

New changeset fe2ca2216334 by R David Murray in branch 'default':
Merge: #26209: Clarify type of *localaddr*/*remoteadr* in smtpd docs.
https://hg.python.org/cpython/rev/fe2ca2216334
msg274853 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-09-07 18:08
Thanks for the patch, Ram.  I started from your patch but further clarified exactly what the tuple is by linking to the actual documentation in the socket docs of what a (host, port) tuple looks like.  I'll apply my patch to 2.7 as well as soon as I confirm the docs build correctly.
msg274854 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-09-07 18:10
New changeset 7aaf8cff23e5 by R David Murray in branch '2.7':
#26209: Clarify type of *localaddr*/*remoteadr* in smtpd docs.
https://hg.python.org/cpython/rev/7aaf8cff23e5
History
Date User Action Args
2016-09-07 18:11:15r.david.murraysetstatus: open -> closed
dependencies: - Deprecate smtpd (based on deprecated asyncore/asynchat)
resolution: fixed
stage: patch review -> resolved
2016-09-07 18:10:38python-devsetmessages: + msg274854
2016-09-07 18:08:17r.david.murraysetnosy: + r.david.murray
messages: + msg274853
2016-09-07 18:02:23python-devsetnosy: + python-dev
messages: + msg274852
2016-08-09 09:45:00rvallurysetfiles: + smtpd_doc_updated_3.patch

messages: + msg272227
2016-08-08 10:45:40berker.peksagsetstage: needs patch -> patch review
2016-08-08 10:42:27rvallurysetfiles: + smtpd_doc_updated_2.patch

messages: + msg272159
2016-08-08 09:42:41rvallurysetfiles: + smtpd_doc_updated.patch

nosy: + rvallury
messages: + msg272154

keywords: + patch
2016-02-13 18:01:55anish.shahsetnosy: - anish.shah
2016-02-12 19:01:49anish.shahsetnosy: + anish.shah
2016-02-07 00:03:44lorenzo.ancorasetmessages: + msg259753
2016-02-06 18:45:22terry.reedysetdependencies: + Deprecate smtpd (based on deprecated asyncore/asynchat)
messages: + msg259748
2016-02-06 18:41:49terry.reedysetmessages: + msg259747
2016-02-06 12:51:30lorenzo.ancorasetmessages: + msg259727
2016-02-03 12:02:43terry.reedysetmessages: + msg259475
versions: - Python 3.2, Python 3.3, Python 3.4
2016-02-03 03:52:28lorenzo.ancorasetmessages: + msg259455
components: + Library (Lib)
versions: + Python 3.2, Python 3.3, Python 3.4
2016-01-30 17:19:35berker.peksagsetassignee: docs@python
type: behavior -> enhancement
components: + Documentation, - Library (Lib)
versions: + Python 2.7, Python 3.6
keywords: + easy
nosy: + docs@python, berker.peksag

messages: + msg259261
stage: needs patch
2016-01-30 01:48:22terry.reedysetnosy: + terry.reedy
messages: + msg259229
2016-01-26 20:42:18SilentGhostsetnosy: + giampaolo.rodola
2016-01-26 20:34:38lorenzo.ancoracreate