Changes between Version 25 and Version 26 of Documentation


Ignore:
Timestamp:
Oct 24, 2010, 2:01:00 PM (11 years ago)
Author:
schwa
Comment:

Updated documentation for release 2.5.

Legend:

Unmodified
Added
Removed
Modified
  • Documentation

    v25 v26  
    55==============================================
    66
    7 :Version:   2.5b
    8 :Date:      2010-09-19
     7:Version:   2.5
     8:Date:      2010-10-24
    99:Summary:   high-level FTP client library for Python
    1010:Keywords:  FTP, ``ftplib`` substitute, virtual filesystem, pure Python
     
    3333    import ftputil
    3434
    35     # download some files from the login directory
     35    # Download some files from the login directory.
    3636    host = ftputil.FTPHost('ftp.domain.com', 'user', 'password')
    3737    names = host.listdir(host.curdir)
     
    4040            host.download(name, name, 'b')  # remote, local, binary mode
    4141
    42     # make a new directory and copy a remote file into it
     42    # Make a new directory and copy a remote file into it.
    4343    host.mkdir('newdir')
    4444    source = host.file('index.html', 'r')         # file-like object
     
    307307            self.login(userid, password)
    308308
    309     # try not to use MySession() as factory, - use the class itself
     309    # Try not to use MySession() as factory, - use the class itself.
    310310    host = ftputil.FTPHost(host, userid, password,
    311311                           port=EXAMPLE_PORT, session_factory=MySession)
    312     # use `host` as usual
     312    # Use `host` as usual.
    313313
    314314On login, the format of the directory listings (needed for stat'ing
     
    3243242.5, you can use Python's `with statement`_::
    325325
    326     # not needed for Python 2.6 and later
     326    # Not needed for Python 2.6 and later
    327327    from __future__ import with_statement
    328328
     
    432432  ::
    433433
    434     # transfer in ASCII mode
     434    # Transfer in ASCII mode.
    435435    host.upload_if_newer('source_file', 'target_file', 'a')
    436     # won't transfer the file again, which is bad!
     436    # Won't transfer the file again, which is bad!
    437437    host.upload_if_newer('source_file', 'target_file', 'b')
    438438
     
    757757        # `host1` will still see the obsolete cache entry!
    758758        print host1.stat("some_file")
    759         # will raise an exception since an `FTPHost` object
    760         #  knows of its own changes
     759        # Will raise an exception since an `FTPHost` object
     760        #  knows of its own changes.
    761761        print host2.stat("some_file")
    762762    finally:
     
    779779        stat_result2 = host2.stat("some_file")
    780780        host2.remove("some_file")
    781         # invalidate using an absolute path
     781        # Invalidate using an absolute path.
    782782        absolute_path = host1.path.abspath(
    783783                        host1.path.join(host1.curdir, "some_file"))
    784784        host1.stat_cache.invalidate(absolute_path)
    785         # will now raise an exception as it should
     785        # Will now raise an exception as it should
    786786        print host1.stat("some_file")
    787         # would raise an exception since an `FTPHost` object
     787        # Would raise an exception since an `FTPHost` object
    788788        #  knows of its own changes, even without `invalidate`
    789789        print host2.stat("some_file")
     
    896896        host.chmod("some_file", 0644)
    897897    except ftp_error.CommandNotImplementedError:
    898         # chmod not supported
     898        # `chmod` not supported
    899899        ...
    900900    except ftp_error.PermanentError:
    901         # possibly a non-existent file
     901        # Possibly a non-existent file
    902902        ...
    903903
     
    932932.. _`keep_alive`:
    933933
    934 - ``keep_alive``
     934- ``keep_alive()``
    935935
    936936  attempts to keep the connection to the remote server active in order
     
    996996constructor::
    997997
    998     # not needed for Python 2.6 and later
     998    # Not needed for Python 2.6 and later
    999999    from __future__ import with_statement
    10001000
    10011001    import ftputil
    10021002
    1003     # get an ``FTPHost`` object from somewhere
     1003    # Get an ``FTPHost`` object from somewhere.
    10041004    ...
    10051005
     
    10381038    input_file = host.file("some_file")
    10391039    for line in input_file:
    1040         # do something with the line, e. g.
     1040        # Do something with the line, e. g.
    10411041        print line.strip().replace("ftplib", "ftputil")
    10421042    input_file.close()
     
    10811081            `ftp_stat.UnixParser` for an example.
    10821082            """
    1083             # split the `line` argument and examine it further; if
    1084             #  something goes wrong, raise an `ftp_error.ParserError`
     1083            # Split the `line` argument and examine it further; if
     1084            #  something goes wrong, raise an `ftp_error.ParserError`.
    10851085            ...
    1086             # make a `StatResult` object from the parts above
     1086            # Make a `StatResult` object from the parts above.
    10871087            stat_result = ftp_stat.StatResult(...)
    1088             # `_st_name`, `_st_target` and `_st_mtime_precision` are optional
     1088            # `_st_name`, `_st_target` and `_st_mtime_precision` are optional.
    10891089            stat_result._st_name = ...
    10901090            stat_result._st_target = ...
     
    10921092            return stat_result
    10931093
    1094         # define `ignores_line` only if the default in the base class
     1094        # Define `ignores_line` only if the default in the base class
    10951095        #  doesn't do enough!
    10961096        def ignores_line(self, line):
     
    12001200~~~~~~~~~~~~~~~~~~~~~~~~
    12011201
    1202 Before reporting a bug, make sure that you already tried the `latest
    1203 version`_ of ``ftputil``. There the bug might have already been fixed.
     1202Before reporting a bug, make sure that you already read this manual
     1203and tried the `latest version`_ of ``ftputil``. There the bug might
     1204have already been fixed.
    12041205
    12051206.. _`latest version`: http://ftputil.sschwarzer.net/download
     
    12341235            """
    12351236            ftpslib.FTP_TLS.__init__(self)
    1236             # do anything necessary to set up the SSL connection
     1237            # Do anything necessary to set up the SSL connection.
    12371238            ...
    12381239            self.connect(host, port)
     
    12401241            ...
    12411242
    1242     # note the `session_factory` parameter
     1243    # Note the `session_factory` parameter.
    12431244    host = ftputil.FTPHost(host, userid, password,
    12441245                           session_factory=SSLFTPSession)
    1245     # use `host` as usual
    1246 
    1247 If you work with Python 2.7, you can use a similar recipe with the new
    1248 class ``FTP_TLS`` in the ``ftplib`` module. Note that you need to call
    1249 ``prot_p`` on the ``FTP_TLS`` instance to actually use a secure
    1250 transfer. This makes it still necessary to define a session class
    1251 similar to the one above.
     1246    # Use `host` as usual.
     1247
     1248If you work with Python 2.7 or the upcoming 3.2 release, you can use a
     1249similar recipe with the new class ``FTP_TLS`` in the ``ftplib``
     1250module. Note that you need to call ``prot_p`` on the ``FTP_TLS``
     1251instance to actually use a secure transfer. This makes it still
     1252necessary to define a session class similar to the one above.
    12521253
    12531254.. _M2Crypto: http://wiki.osafoundation.org/bin/view/Projects/MeTooCrypto#Downloads
     
    12801281            self.connect(host, port)
    12811282            self.login(userid, password)
    1282             # see http://docs.python.org/lib/ftp-objects.html
     1283            # See http://docs.python.org/lib/ftp-objects.html
    12831284            self.set_pasv(False)
    12841285
    12851286Use this class as the ``session_factory`` argument in ``FTPHost``'s
    12861287constructor.
     1288
     1289When iterating over directories, ``ftputil`` becomes unbearably slow
     1290~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1291
     1292You probably iterate over a directory with more than 1000 items
     1293(directories and files) in it and use methods like `lstat` or `isdir`
     1294for that.
     1295
     1296Even though ``ftputil`` uses a cache to store stat information used by
     1297these methods, the cache's default size is 1000 entries. If your
     1298directory contains more items, the first entries will have been
     1299flushed from the cache by the time the iteration over the items
     1300starts.
     1301
     1302To avoid this problem, increase the cache size to the size of the
     1303largest directory you expect::
     1304
     1305    ftp_host = ftputil.FTPHost(host, userid, password)
     1306    # Increase cache size to hold at most 10000 entries.
     1307    ftp_host.stat_cache.resize(10000)
     1308
     1309For details on caching read `Local caching of file system
     1310information`_.
     1311
     1312Support for an auto-resize feature is planned for *future* versions
     1313of ``ftputil``. This won't be fool-proof either, but will most likely
     1314work for the case described above.
    12871315
    12881316Conditional upload/download to/from a server in a different time zone
     
    14111439
    14121440Feedback is appreciated. :-)
     1441
    14131442}}}