Changeset 1525:349506cfb444


Ignore:
Timestamp:
Jun 8, 2014, 7:08:52 PM (5 years ago)
Author:
Stefan Schwarzer <sschwarzer@…>
Branch:
default
amend_source:
8fe39b82fe246b242174861d360304f41964b0ef
Message:
Consistently use `server` and `ftp_host` in example code.

`server` now always means the host name and `ftp_host` an `FTPHost`
instance. Previously, some examples even accidentally used `host` for
both the server name and the created `FTPHost` object.

Also converted some old code snippets to create `FTPHost` objects in
a `with` statement.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/ftputil.txt

    r1524 r1525  
    2424.. _`shutil`: https://docs.python.org/library/shutil.html
    2525
    26 Examples::
     26Example::
    2727
    2828    import ftputil
    2929
    3030    # Download some files from the login directory.
    31     with ftputil.FTPHost("ftp.domain.com", "user", "password") as host:
    32         names = host.listdir(host.curdir)
     31    with ftputil.FTPHost("ftp.domain.com", "user", "password") as ftp_host:
     32        names = ftp_host.listdir(ftp_host.curdir)
    3333        for name in names:
    34             if host.path.isfile(name):
    35                 host.download(name, name)  # remote, local
     34            if ftp_host.path.isfile(name):
     35                ftp_host.download(name, name)  # remote, local
    3636        # Make a new directory and copy a remote file into it.
    37         host.mkdir("newdir")
    38         with host.open("index.html", "rb") as source:
    39             with host.open("newdir/index.html", "wb") as target:
    40                 host.copyfileobj(source, target)  # similar to shutil.copyfileobj
     37        ftp_host.mkdir("newdir")
     38        with ftp_host.open("index.html", "rb") as source:
     39            with ftp_host.open("newdir/index.html", "wb") as target:
     40                ftp_host.copyfileobj(source, target)  # similar to shutil.copyfileobj
    4141
    4242Also, there are `FTPHost.lstat`_ and `FTPHost.stat`_ to request size and
     
    7373* Read files from and write files to remote hosts via
    7474  file-like objects (``FTPHost.open``; the generated file-like objects
    75   have many common methods like ``read``, ``readline``, ``readlines``,
    76   ``write``, ``writelines``, ``close`` and can do automatic line
    77   ending conversions on the fly, i. e. text/binary mode).
     75  have the familiar methods like ``read``, ``readline``, ``readlines``,
     76  ``write``, ``writelines`` and ``close``. You can also iterate over
     77  these files line by line in a ``for`` loop.
    7878
    7979
     
    193193  ::
    194194
    195     >>> host = ftputil.FTPHost("host", "user", "password")
     195    >>> ftp_host = ftputil.FTPHost("host", "user", "password")
    196196    >>> try:
    197     ...     f = host.open("not_there")
     197    ...     f = ftp_host.open("not_there")
    198198    ... except IOError as obj:
    199199    ...     print obj.errno
     
    271271``FTPHost`` instances can be generated with the following call::
    272272
    273     host = ftputil.FTPHost(host, user, password, account,
    274                            session_factory=ftplib.FTP)
     273    ftp_host = ftputil.FTPHost(server, user, password, account,
     274                               session_factory=ftplib.FTP)
    275275
    276276The first four parameters are strings with the same meaning as for the
     
    281281    import ftputil
    282282
    283     with ftputil.FTPHost(host, user, password) as ftp_host:
     283    with ftputil.FTPHost(server, user, password) as ftp_host:
    284284        print ftp_host.listdir(ftp_host.curdir)
    285285
     
    390390                           debug_level=2)
    391391
    392     with ftputil.FTPHost(host, user, password,
     392    with ftputil.FTPHost(server, user, password,
    393393                         session_factory=my_session_factory) as ftp_host:
    394394        ...
     
    421421option::
    422422
    423     host = ftputil.FTPHost(host, user, password, account,
    424                            session_factory=ftplib.FTP)
    425     host.use_list_a_option = False
     423    ftp_host = ftputil.FTPHost(server, user, password, account,
     424                               session_factory=ftplib.FTP)
     425    ftp_host.use_list_a_option = False
    426426
    427427``FTPHost`` attributes and methods
     
    504504  ::
    505505
    506     host.upload_if_newer("source_file", "target_file")
     506    ftp_host.upload_if_newer("source_file", "target_file")
    507507    time.sleep(10)
    508     host.upload_if_newer("source_file", "target_file")
     508    ftp_host.upload_if_newer("source_file", "target_file")
    509509
    510510  might upload the file again if the timestamp of the target file is
     
    796796::
    797797
    798     host = ftputil.FTPHost(host, user, password)
    799 
    800 the cache can be accessed as ``host.stat_cache``.
     798    ftp_host = ftputil.FTPHost(host, user, password)
     799
     800the cache can be accessed as ``ftp_host.stat_cache``.
    801801
    802802While ``ftputil`` usually manages the cache quite well, there are two
     
    817817done by the ``resize`` method::
    818818
    819     host.stat_cache.resize(20000)
     819    ftp_host.stat_cache.resize(20000)
    820820
    821821where the argument is the maximum number of ``lstat`` results to store
     
    849849
    850850    with (
    851       ftputil.FTPHost(server, user1, password1) as host1,
    852       ftputil.FTPHost(server, user1, password1) as host2
     851      ftputil.FTPHost(server, user1, password1) as ftp_host1,
     852      ftputil.FTPHost(server, user1, password1) as ftp_host2
    853853    ):
    854         stat_result1 = host1.stat("some_file")
    855         stat_result2 = host2.stat("some_file")
    856         host2.remove("some_file")
    857         # `host1` will still see the obsolete cache entry!
    858         print host1.stat("some_file")
     854        stat_result1 = ftp_host1.stat("some_file")
     855        stat_result2 = ftp_host2.stat("some_file")
     856        ftp_host2.remove("some_file")
     857        # `ftp_host1` will still see the obsolete cache entry!
     858        print ftp_host1.stat("some_file")
    859859        # Will raise an exception since an `FTPHost` object
    860860        # knows of its own changes.
    861         print host2.stat("some_file")
     861        print ftp_host2.stat("some_file")
    862862
    863863At first sight, it may appear to be a good idea to have a shared cache
     
    871871
    872872    with (
    873       ftputil.FTPHost(server, user1, password1) as host1,
    874       ftputil.FTPHost(server, user1, password1) as host2
     873      ftputil.FTPHost(server, user1, password1) as ftp_host1,
     874      ftputil.FTPHost(server, user1, password1) as ftp_host2
    875875    ):
    876         stat_result1 = host1.stat("some_file")
    877         stat_result2 = host2.stat("some_file")
    878         host2.remove("some_file")
     876        stat_result1 = ftp_host1.stat("some_file")
     877        stat_result2 = ftp_host2.stat("some_file")
     878        ftp_host2.remove("some_file")
    879879        # Invalidate using an absolute path.
    880         absolute_path = host1.path.abspath(
    881                           host1.path.join(host1.getcwd(), "some_file"))
    882         host1.stat_cache.invalidate(absolute_path)
     880        absolute_path = ftp_host1.path.abspath(
     881                          ftp_host1.path.join(ftp_host1.getcwd(), "some_file"))
     882        ftp_host1.stat_cache.invalidate(absolute_path)
    883883        # Will now raise an exception as it should.
    884         print host1.stat("some_file")
     884        print ftp_host1.stat("some_file")
    885885        # Would raise an exception since an `FTPHost` object
    886886        # knows of its own changes, even without `invalidate`.
    887         print host2.stat("some_file")
     887        print ftp_host2.stat("some_file")
    888888
    889889The method ``invalidate`` can be used on any *absolute* path, be it a
     
    896896attribute::
    897897
    898     host = ftputil.FTPHost(server, user, password)
    899     host.stat_cache.max_age = 60 * 60  # = 3600 seconds
     898    with ftputil.FTPHost(server, user, password) as ftp_host:
     899        ftp_host.stat_cache.max_age = 60 * 60  # = 3600 seconds
    900900
    901901This sets the maximum age of entries in the cache to an hour. This
     
    908908and later re-enable it completely with ``disable`` and ``enable``::
    909909
    910     host = ftputil.FTPHost(server, user, password)
    911     host.stat_cache.disable()
    912     ...
    913     host.stat_cache.enable()
     910    with ftputil.FTPHost(server, user, password) as ftp_host:
     911        ftp_host.stat_cache.disable()
     912        ...
     913        ftp_host.stat_cache.enable()
    914914
    915915During that time, the cache won't be used; all data will be fetched
    916 from the network. After enabling the cache, its entries will be the
    917 same as when the cache was disabled, that is, entries won't get
     916from the network. After enabling the cache again, its entries will be
     917the same as when the cache was disabled, that is, entries won't get
    918918updated with newer data during this period. Note that even when the
    919919cache is disabled, the file system data in the code can become
    920920inconsistent::
    921921
    922     host = ftputil.FTPHost(server, user, password)
    923     host.stat_cache.disable()
    924     if host.path.exists("some_file"):
    925         mtime = host.path.getmtime("some_file")
     922    with ftputil.FTPHost(server, user, password) as ftp_host:
     923        ftp_host.stat_cache.disable()
     924        if ftp_host.path.exists("some_file"):
     925            mtime = ftp_host.path.getmtime("some_file")
    926926
    927927In that case, the file ``some_file`` may have been removed by another
     
    974974  want to use such octal values, rely on Python's support for them::
    975975
    976     host.chmod("some_directory", 0o755)
     976    ftp_host.chmod("some_directory", 0o755)
    977977
    978978  Not all FTP servers support the ``chmod`` command. In case of
     
    986986  So you need to code like this::
    987987
    988     host = ftputil.FTPHost(server, user, password)
    989     try:
    990         host.chmod("some_file", 0o644)
    991     except ftputil.error.CommandNotImplementedError:
    992         # `chmod` not supported
    993         ...
    994     except ftputil.error.PermanentError:
    995         # Possibly a non-existent file
    996         ...
     988    with ftputil.FTPHost(server, user, password) as ftp_host:
     989        try:
     990            ftp_host.chmod("some_file", 0o644)
     991        except ftputil.error.CommandNotImplementedError:
     992            # `chmod` not supported
     993            ...
     994        except ftputil.error.PermanentError:
     995            # Possibly a non-existent file
     996            ...
    997997
    998998  Because the ``CommandNotImplementedError`` is more specific, you
     
    10541054  like this::
    10551055
    1056       with ftputil.FTPHost(server, userid, password) as host:
    1057           fobj = host.open("some_remote_file", "rb")
    1058           data = fobj.read(100)
    1059           # _Futile_ attempt to avoid file connection timeout.
    1060           for i in xrange(15):
    1061               time.sleep(60)
    1062               host.keep_alive()
    1063           # Will raise an `ftputil.error.TemporaryError`.
    1064           data += fobj.read()
     1056      with ftputil.FTPHost(server, userid, password) as ftp_host:
     1057          with ftp_host.open("some_remote_file", "rb") as fobj:
     1058              data = fobj.read(100)
     1059              # _Futile_ attempt to avoid file connection timeout.
     1060              for i in xrange(15):
     1061                  time.sleep(60)
     1062                  ftp_host.keep_alive()
     1063              # Will raise an `ftputil.error.TemporaryError`.
     1064              data += fobj.read()
    10651065
    10661066
     
    11561156line::
    11571157
    1158     with ftputil.FTPHost(...) as host:
    1159         with host.open("some_file") as input_file:
     1158    with ftputil.FTPHost(...) as ftp_host:
     1159        with ftp_host.open("some_file") as input_file:
    11601160            for line in input_file:
    11611161                # Do something with the line, e. g.
     
    13711371    # Note the `session_factory` parameter. Pass the class, not
    13721372    # an instance.
    1373     with ftputil.FTPHost(host, user, password,
     1373    with ftputil.FTPHost(server, user, password,
    13741374                         session_factory=FTPTLSSession) as ftp_host:
    13751375        # Use `ftp_host` as usual.
     1376        ...
    13761377
    13771378.. _`ftputil.session.session_factory`: `Session factories`_
     
    14211422    # Note the `session_factory` parameter. Pass the class, not
    14221423    # an instance.
    1423     with ftputil.FTPHost(host, user, password,
     1424    with ftputil.FTPHost(server, user, password,
    14241425                         session_factory=M2CryptoSession) as ftp_host:
    14251426        # Use `ftp_host` as usual.
     1427        ...
    14261428
    14271429  That said, ``session_factory`` has this workaround built in, so
Note: See TracChangeset for help on using the changeset viewer.