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/ftplib.rst

    r2 r391  
    99   pair: FTP; protocol
    1010   single: FTP; ftplib (standard module)
     11
     12**Source code:** :source:`Lib/ftplib.py`
     13
     14--------------
    1115
    1216This module defines the class :class:`FTP` and a few related items. The
    … …  
    2024
    2125   >>> from ftplib import FTP
    22    >>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
    23    >>> ftp.login()               # user anonymous, passwd anonymous@
    24    >>> ftp.retrlines('LIST')     # list directory contents
    25    total 24418
    26    drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
    27    dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
    28    -rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
    29     .
    30     .
    31     .
     26   >>> ftp = FTP('ftp.debian.org')     # connect to host, default port
     27   >>> ftp.login()                     # user anonymous, passwd anonymous@
     28   '230 Login successful.'
     29   >>> ftp.cwd('debian')               # change into "debian" directory
     30   >>> ftp.retrlines('LIST')           # list directory contents
     31   -rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
     32   ...
     33   drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
     34   drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
     35   drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
     36   '226 Directory send OK.'
    3237   >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
    3338   '226 Transfer complete.'
    3439   >>> ftp.quit()
    3540
     41
    3642The module defines the following items:
    37 
    3843
    3944.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
    … …  
    5156
    5257
    53    .. attribute:: all_errors
    54 
    55       The set of all exceptions (as a tuple) that methods of :class:`FTP`
    56       instances may raise as a result of problems with the FTP connection (as
    57       opposed to programming errors made by the caller).  This set includes the
    58       four exceptions listed below as well as :exc:`socket.error` and
    59       :exc:`IOError`.
    60 
    61 
    62    .. exception:: error_reply
    63 
    64       Exception raised when an unexpected reply is received from the server.
    65 
    66 
    67    .. exception:: error_temp
    68 
    69       Exception raised when an error code in the range 400--499 is received.
    70 
    71 
    72    .. exception:: error_perm
    73 
    74       Exception raised when an error code in the range 500--599 is received.
    75 
    76 
    77    .. exception:: error_proto
    78 
    79       Exception raised when a reply is received from the server that does not
    80       begin with a digit in the range 1--5.
     58.. class:: FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, timeout]]]]]]])
     59
     60   A :class:`FTP` subclass which adds TLS support to FTP as described in
     61   :rfc:`4217`.
     62   Connect as usual to port 21 implicitly securing the FTP control connection
     63   before authenticating. Securing the data connection requires the user to
     64   explicitly ask for it by calling the :meth:`prot_p` method.
     65   *keyfile* and *certfile* are optional -- they can contain a PEM formatted
     66   private key and certificate chain file name for the SSL connection.
     67
     68   .. versionadded:: 2.7
     69
     70   Here's a sample session using the :class:`FTP_TLS` class:
     71
     72   >>> from ftplib import FTP_TLS
     73   >>> ftps = FTP_TLS('ftp.python.org')
     74   >>> ftps.login()           # login anonymously before securing control channel
     75   >>> ftps.prot_p()          # switch to secure data connection
     76   >>> ftps.retrlines('LIST') # list directory content securely
     77   total 9
     78   drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 .
     79   drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 ..
     80   drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 bin
     81   drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 etc
     82   d-wxrwxr-x   2 ftp      wheel        1024 Sep  5 13:43 incoming
     83   drwxr-xr-x   2 root     wheel        1024 Nov 17  1993 lib
     84   drwxr-xr-x   6 1094     wheel        1024 Sep 13 19:07 pub
     85   drwxr-xr-x   3 root     wheel        1024 Jan  3  1994 usr
     86   -rw-r--r--   1 root     root          312 Aug  1  1994 welcome.msg
     87   '226 Transfer complete.'
     88   >>> ftps.quit()
     89   >>>
     90
     91
     92.. exception:: error_reply
     93
     94   Exception raised when an unexpected reply is received from the server.
     95
     96
     97.. exception:: error_temp
     98
     99   Exception raised when an error code signifying a temporary error (response
     100   codes in the range 400--499) is received.
     101
     102
     103.. exception:: error_perm
     104
     105   Exception raised when an error code signifying a permanent error (response
     106   codes in the range 500--599) is received.
     107
     108
     109.. exception:: error_proto
     110
     111   Exception raised when a reply is received from the server that does not fit
     112   the response specifications of the File Transfer Protocol, i.e. begin with a
     113   digit in the range 1--5.
     114
     115
     116.. data:: all_errors
     117
     118   The set of all exceptions (as a tuple) that methods of :class:`FTP`
     119   instances may raise as a result of problems with the FTP connection (as
     120   opposed to programming errors made by the caller).  This set includes the
     121   four exceptions listed above as well as :exc:`socket.error` and
     122   :exc:`IOError`.
    81123
    82124
    … …  
    84126
    85127   Module :mod:`netrc`
    86       Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is typically
    87       used by FTP clients to load user authentication information before prompting the
    88       user.
     128      Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is
     129      typically used by FTP clients to load user authentication information
     130      before prompting the user.
    89131
    90132   .. index:: single: ftpmirror.py
    … …  
    165207.. method:: FTP.voidcmd(command)
    166208
    167    Send a simple command string to the server and handle the response. Return
    168    nothing if a response code in the range 200--299 is received. Raise an exception
    169    otherwise.
     209   Send a simple command string to the server and handle the response.  Return
     210   nothing if a response code corresponding to success (codes in the range
     211   200--299) is received.  Raise :exc:`error_reply` otherwise.
    170212
    171213
    … …  
    187229   should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
    188230   command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
    189    ``'LIST'``).  The *callback* function is called for each line, with the
    190    trailing CRLF stripped.  The default *callback* prints the line to
    191    ``sys.stdout``.
     231   ``'LIST'``).  ``LIST`` retrieves a list of files and information about those files.
     232   ``NLST`` retrieves a list of file names.  On some servers, ``MLSD`` retrieves
     233   a machine readable list of files and information about those files.  The *callback*
     234   function is called for each line with a string argument containing the line with
     235   the trailing CRLF stripped.  The default *callback* prints the line to ``sys.stdout``.
    192236
    193237
    … …  
    199243
    200244
    201 .. method:: FTP.storbinary(command, file[, blocksize, callback])
     245.. method:: FTP.storbinary(command, file[, blocksize, callback, rest])
    202246
    203247   Store a file in binary transfer mode.  *command* should be an appropriate
    … …  
    206250   provide the data to be stored.  The *blocksize* argument defaults to 8192.
    207251   *callback* is an optional single parameter callable that is called
    208    on each block of data after it is sent.
     252   on each block of data after it is sent. *rest* means the same thing as in
     253   the :meth:`transfercmd` method.
    209254
    210255   .. versionchanged:: 2.1
    … …  
    214259      *callback* parameter added.
    215260
     261   .. versionchanged:: 2.7
     262      *rest* parameter added.
    216263
    217264.. method:: FTP.storlines(command, file[, callback])
    … …  
    219266   Store a file in ASCII transfer mode.  *command* should be an appropriate
    220267   ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
    221    open file object *file* using its :meth:`readline` method to provide the data to
    222    be stored.  *callback* is an optional single parameter callable
     268   open file object *file* using its :meth:`~file.readline` method to provide
     269   the data to be stored.  *callback* is an optional single parameter callable
    223270   that is called on each line after it is sent.
    224271
    … …  
    257304.. method:: FTP.nlst(argument[, ...])
    258305
    259    Return a list of files as returned by the ``NLST`` command.  The optional
    260    *argument* is a directory to list (default is the current server directory).
    261    Multiple arguments can be used to pass non-standard options to the ``NLST``
    262    command.
     306   Return a list of file names as returned by the ``NLST`` command.  The
     307   optional *argument* is a directory to list (default is the current server
     308   directory).  Multiple arguments can be used to pass non-standard options to
     309   the ``NLST`` command.
    263310
    264311
    … …  
    325372
    326373   Close the connection unilaterally.  This should not be applied to an already
    327    closed connection such as after a successful call to :meth:`quit`.  After this
    328    call the :class:`FTP` instance should not be used any more (after a call to
    329    :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
    330    another :meth:`login` method).
    331 
     374   closed connection such as after a successful call to :meth:`~FTP.quit`.
     375   After this call the :class:`FTP` instance should not be used any more (after
     376   a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
     377   connection by issuing another :meth:`login` method).
     378
     379
     380FTP_TLS Objects
     381---------------
     382
     383:class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional objects:
     384
     385.. attribute:: FTP_TLS.ssl_version
     386
     387   The SSL version to use (defaults to *TLSv1*).
     388
     389.. method:: FTP_TLS.auth()
     390
     391   Set up secure control connection by using TLS or SSL, depending on what
     392   specified in :meth:`ssl_version` attribute.
     393
     394.. method:: FTP_TLS.prot_p()
     395
     396   Set up secure data connection.
     397
     398.. method:: FTP_TLS.prot_c()
     399
     400   Set up clear text data connection.
Note: See TracChangeset for help on using the changeset viewer.