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.

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.

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.

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

Doc fixes unrelated to security fixes are not applied to security-fix-only versions.

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

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.

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.

(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.

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*

Submitting patch 2 for smtpd doc changes

added space before word portnumber. column space adjusted

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

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.

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