Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/library/smtplib.rst

    r2 r391  
    1 
    21:mod:`smtplib` --- SMTP protocol client
    32=======================================
    … …  
    1110   pair: SMTP; protocol
    1211   single: Simple Mail Transfer Protocol
     12
     13**Source code:** :source:`Lib/smtplib.py`
     14
     15--------------
    1316
    1417The :mod:`smtplib` module defines an SMTP client session object that can be used
    … …  
    2225   A :class:`SMTP` instance encapsulates an SMTP connection.  It has methods
    2326   that support a full repertoire of SMTP and ESMTP operations. If the optional
    24    host and port parameters are given, the SMTP :meth:`connect` method is called
    25    with those parameters during initialization.  An :exc:`SMTPConnectError` is
    26    raised if the specified host doesn't respond correctly. The optional
     27   host and port parameters are given, the SMTP :meth:`connect` method is
     28   called with those parameters during initialization.  If specified,
     29   *local_hostname* is used as the FQDN of the local host in the HELO/EHLO
     30   command.  Otherwise, the local hostname is found using
     31   :func:`socket.getfqdn`.  If the :meth:`connect` call returns anything other
     32   than a success code, an :exc:`SMTPConnectError` is raised. The optional
    2733   *timeout* parameter specifies a timeout in seconds for blocking operations
    2834   like the connection attempt (if not specified, the global default timeout
    … …  
    3036
    3137   For normal use, you should only require the initialization/connect,
    32    :meth:`sendmail`, and :meth:`quit` methods.  An example is included below.
     38   :meth:`sendmail`, and :meth:`~smtplib.quit` methods.
     39   An example is included below.
    3340
    3441   .. versionchanged:: 2.6
    … …  
    4249   required from the beginning of the connection and using :meth:`starttls` is
    4350   not appropriate. If *host* is not specified, the local host is used. If
    44    *port* is omitted, the standard SMTP-over-SSL port (465) is used. *keyfile*
    45    and *certfile* are also optional, and can contain a PEM formatted private key
    46    and certificate chain file for the SSL connection. The optional *timeout*
    47    parameter specifies a timeout in seconds for blocking operations like the
    48    connection attempt (if not specified, the global default timeout setting
    49    will be used).
    50 
    51    .. versionchanged:: 2.6
    52       *timeout* was added.
     51   *port* is omitted, the standard SMTP-over-SSL port (465) is used.
     52   *local_hostname* has the same meaning as it does for the :class:`SMTP`
     53   class.  *keyfile* and *certfile* are also optional, and can contain a PEM
     54   formatted private key and certificate chain file for the SSL connection. The
     55   optional *timeout* parameter specifies a timeout in seconds for blocking
     56   operations like the connection attempt (if not specified, the global default
     57   timeout setting will be used).
     58
     59   .. versionadded:: 2.6
    5360
    5461
    … …  
    5663
    5764   The LMTP protocol, which is very similar to ESMTP, is heavily based on the
    58    standard SMTP client. It's common to use Unix sockets for LMTP, so our :meth:`connect`
    59    method must support that as well as a regular host:port server. To specify a
    60    Unix socket, you must use an absolute path for *host*, starting with a '/'.
    61 
    62    Authentication is supported, using the regular SMTP mechanism. When using a Unix
    63    socket, LMTP generally don't support or require any authentication, but your
    64    mileage might vary.
     65   standard SMTP client. It's common to use Unix sockets for LMTP, so our
     66   :meth:`connect` method must support that as well as a regular host:port
     67   server.  *local_hostname* has the same meaning as it does for the
     68   :class:`SMTP` class.  To specify a Unix socket, you must use an absolute
     69   path for *host*, starting with a '/'.
     70
     71   Authentication is supported, using the regular SMTP mechanism. When using a
     72   Unix socket, LMTP generally don't support or require any authentication, but
     73   your mileage might vary.
    6574
    6675   .. versionadded:: 2.6
    … …  
    7180.. exception:: SMTPException
    7281
    73    Base exception class for all exceptions raised by this module.
     82   The base exception class for all the other exceptions provided by this
     83   module.
    7484
    7585
    … …  
    150160
    151161
     162.. method:: SMTP.docmd(cmd, [, argstring])
     163
     164   Send a command *cmd* to the server.  The optional argument *argstring* is simply
     165   concatenated to the command, separated by a space.
     166
     167   This returns a 2-tuple composed of a numeric response code and the actual
     168   response line (multiline responses are joined into one long line.)
     169
     170   In normal operation it should not be necessary to call this method explicitly.
     171   It is used to implement other methods and may be useful for testing private
     172   extensions.
     173
     174   If the connection to the server is lost while waiting for the reply,
     175   :exc:`SMTPServerDisconnected` will be raised.
     176
     177
    152178.. method:: SMTP.connect([host[, port]])
    153179
    … …  
    156182   followed by a number, that suffix will be stripped off and the number
    157183   interpreted as the port number to use. This method is automatically invoked by
    158    the constructor if a host is specified during instantiation.
    159 
    160 
    161 .. method:: SMTP.docmd(cmd, [, argstring])
    162 
    163    Send a command *cmd* to the server.  The optional argument *argstring* is simply
    164    concatenated to the command, separated by a space.
    165 
    166    This returns a 2-tuple composed of a numeric response code and the actual
    167    response line (multiline responses are joined into one long line.)
    168 
    169    In normal operation it should not be necessary to call this method explicitly.
    170    It is used to implement other methods and may be useful for testing private
    171    extensions.
    172 
    173    If the connection to the server is lost while waiting for the reply,
    174    :exc:`SMTPServerDisconnected` will be raised.
     184   the constructor if a host is specified during instantiation.  Returns a
     185   2-tuple of the response code and message sent by the server in its
     186   connection response.
    175187
    176188
    … …  
    299311
    300312   This method will return normally if the mail is accepted for at least one
    301    recipient. Otherwise it will throw an exception.  That is, if this method does
    302    not throw an exception, then someone should get your mail. If this method does
    303    not throw an exception, it returns a dictionary, with one entry for each
     313   recipient. Otherwise it will raise an exception.  That is, if this method does
     314   not raise an exception, then someone should get your mail. If this method does
     315   not raise an exception, it returns a dictionary, with one entry for each
    304316   recipient that was refused.  Each entry contains a tuple of the SMTP error code
    305317   and the accompanying error message sent by the server.
Note: See TracChangeset for help on using the changeset viewer.