Changes between Version 17 and Version 18 of Documentation


Ignore:
Timestamp:
Feb 15, 2009, 2:06:13 PM (12 years ago)
Author:
schwa
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation

    v17 v18  
    55=============================================
    66
    7 :Version:   2.3
    8 :Date:      2008-09-06
     7:Version:   2.4
     8:Date:      2009-02-15
    99:Summary:   high-level FTP client library for Python
    1010:Keywords:  FTP, ``ftplib`` substitute, virtual filesystem, pure Python
     
    9393The exceptions are in the namespace of the ``ftp_error`` module, e. g.
    9494``ftp_error.TemporaryError``. Getting the exception classes from the
    95 "package module" ``ftputil`` is deprecated.
     95"package module" ``ftputil`` is deprecated and will no longer be
     96supported in ``ftputil`` version 2.5.
    9697
    9798The exceptions are organized as follows::
     
    100101        FTPOSError(FTPError, OSError)
    101102            PermanentError(FTPOSError)
     103                CommandNotImplementedError(PermanentError)
    102104            TemporaryError(FTPOSError)
    103105        FTPIOError(FTPError)
     
    165167- ``PermanentError``
    166168
    167   is raised for 5xx return codes from the FTP server
    168   (again, that's similar but *not* identical to ``ftplib.error_perm``).
     169  is raised for 5xx return codes from the FTP server. This
     170  corresponds to ``ftplib.error_perm`` (though ``PermanentError`` and
     171  ``ftplib.error_perm`` are *not* identical).
     172
     173- ``CommandNotImplementedError``
     174
     175  indicates that an underlying command the code tries to use is not
     176  implemented. For an example, see the description of the
     177  `FTPHost.chmod`_ method.
    169178
    170179- ``TemporaryError``
     
    345354  FTP server implementation, the Unix counterparts seem to work well
    346355  in practice, even for non-Unix servers.
    347 
    348 .. _`RFC 959`: `RFC 959 - File Transfer Protocol (FTP)`_
    349356
    350357Remote file system navigation
     
    819826  renames the source file (or directory) on the FTP server.
    820827
     828.. _`FTPHost.chmod`:
     829
     830- ``chmod(path, mode)``
     831
     832  sets the access mode (permission flags) for the given path. The mode
     833  is an integer as returned for the mode by the ``stat`` and ``lstat``
     834  methods. Be careful: Usually, mode values are written as octal
     835  numbers, for example 0755 to make a directory readable and writable
     836  for the owner, but not writable for the group and others. If you
     837  want to use such octal values, rely on Python's support for them::
     838
     839    host.chmod("some_directory", 0755)
     840
     841  Note the leading zero.
     842 
     843  Not all FTP servers support the ``chmod`` command. In case of
     844  an exception, how do you know if the path doesn't exist or if
     845  the command itself is invalid? If the FTP server complies with
     846  `RFC 959`_, it should return a status code 502 if the ``SITE CHMOD``
     847  command isn't allowed. ``ftputil`` maps this special error
     848  response to a ``CommandNotImplementedError`` which is derived from
     849  ``PermanentError``.
     850 
     851  So you need to code like this::
     852
     853    host = ftputil.FTPHost(server, user, password)
     854    try:
     855        host.chmod("some_file", 0644)
     856    except ftp_error.CommandNotImplementedError:
     857        # chmod not supported
     858        ...
     859    except ftp_error.PermanentError:
     860        # possibly a non-existent file
     861        ...
     862
     863  Because the ``CommandNotImplementedError`` is more specific, you
     864  have to test for it first.
     865
     866.. _`RFC 959`: `RFC 959 - File Transfer Protocol (FTP)`_
     867
    821868- ``copyfileobj(source, target, length=64*1024)``
    822869
     
    834881  sets a custom parser for FTP directories. Note that you have to pass
    835882  in a parser *instance*, not the class.
    836  
     883
    837884  An `extra section`_ shows how to write own parsers if the default
    838885  parsers in ``ftputil`` don't work for you. Possibly you are lucky
     
    919966        print line.strip().replace("ftplib", "ftputil")
    920967    input_file.close()
     968
     969This feature obsoletes the ``xreadlines`` method which is deprecated
     970and will be removed in ``ftputil`` version 2.5.
    921971
    922972For more on file objects, see the section `File objects`_ in the