Changeset 790:2148fae72310


Ignore:
Timestamp:
May 3, 2009, 10:00:39 PM (10 years ago)
Author:
Stefan Schwarzer <sschwarzer@…>
Branch:
default
Convert:
svn:778c30c8-61e0-0310-89d4-fe2f97a467b2/trunk@858
Message:
Some small improvements.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • ftputil.txt

    r781 r790  
    1 ``ftputil`` - a high-level FTP client library
    2 =============================================
     1``ftputil`` -- a high-level FTP client library
     2==============================================
    33
    44:Version:   2.4
     
    8282  have many common methods like ``read``, ``readline``, ``readlines``,
    8383  ``write``, ``writelines``, ``close`` and can do automatic line
    84   ending conversions on the fly, i. e. text/binary mode)
     84  ending conversions on the fly, i. e. text/binary mode).
    8585
    8686
     
    211211    550 not_there: No such file or directory.
    212212
    213   As you can see, both code snippets are similar. (However, the error
    214   codes aren't the same.)
     213  As you can see, both code snippets are similar. However, the error
     214  codes aren't the same.
    215215
    216216- ``InternalError``
     
    225225
    226226  - The directory in which "you" are placed upon login is not
    227     accessible, i. e. a ``chdir`` call fails.
     227    accessible, i. e. a ``chdir`` call with the directory as
     228    argument would fail.
    228229
    229230  - You try to access a path which contains whitespace.
     
    262263``````
    263264
    264 ``FTPHost`` instances may be generated with the following call::
     265``FTPHost`` instances can be generated with the following call::
    265266
    266267    host = ftputil.FTPHost(host, user, password, account,
     
    289290As an example, assume you want to connect to another than the default
    290291port but ``ftplib.FTP`` only offers this by means of its ``connect``
    291 method, but not via its constructor. The solution is to provide a
    292 wrapper class::
     292method, but not via its constructor. The solution is to use a wrapper
     293class::
    293294
    294295    import ftplib
     
    299300    class MySession(ftplib.FTP):
    300301        def __init__(self, host, userid, password, port):
    301             """Act like ftplib.FTP's constructor but connect to other port."""
     302            """Act like ftplib.FTP's constructor but connect to another port."""
    302303            ftplib.FTP.__init__(self)
    303304            self.connect(host, port)
     
    347348
    348349  are strings which denote the current and the parent directory on the
    349   remote server. sep identifies the path separator. Though `RFC 959`_
     350  remote server. ``sep`` identifies the path separator. Though `RFC 959`_
    350351  (File Transfer Protocol) notes that these values may depend on the
    351352  FTP server implementation, the Unix counterparts seem to work well
     
    371372
    372373  copies a local source file (given by a filename, i. e. a string)
    373   to the remote host under the name target. Both source and target
    374   may be absolute paths or relative to their corresponding current
    375   directory (on the local or the remote host, respectively). The
    376   mode may be "" or "a" for ASCII uploads or "b" for binary uploads.
    377   ASCII mode is the default (again, similar to regular local file
    378   objects).
     374  to the remote host under the name target. Both ``source`` and
     375  ``target`` may be absolute paths or relative to their corresponding
     376  current directory (on the local or the remote host, respectively).
     377  The mode may be "" or "a" for ASCII uploads or "b" for binary
     378  uploads. ASCII mode is the default (again, similar to regular local
     379  file objects).
    379380
    380381- ``download(source, target, mode='')``
    381382
    382383  performs a download from the remote source to a target file. Both
    383   source and target are strings. Additionally, the description of
    384   the upload method applies here, too.
     384  ``source`` and ``target`` are strings. The description of the
     385  upload method applies here, too.
    385386
    386387.. _`upload_if_newer`:
     
    388389- ``upload_if_newer(source, target, mode='')``
    389390
    390   is similar to the upload method. The only difference is that the
    391   upload is only invoked if the time of the last modification for
    392   the source file is more recent than that of the target file, or
    393   the target doesn't exist at all. If an upload actually happened,
    394   the return value is a true value, else a false value.
     391  is similar to the ``upload`` method. The only difference is that the
     392  upload is only invoked if the time of the last modification for the
     393  source file is more recent than that of the target file or the
     394  target doesn't exist at all. If an upload actually happened, the
     395  return value is a true value, else a false value.
    395396
    396397  Note that this method only checks the existence and/or the
     
    448449
    449450  Setting this value is important if `upload_if_newer`_ and
    450   `download_if_newer`_ should work correctly even if the time zone of
     451  `download_if_newer`_ have to work correctly even if the time zone of
    451452  the FTP server differs from that of the client (where ``ftputil``
    452   runs). Note that the time shift value *can* be negative.
     453  runs). Note that the time shift value *can be negative*.
    453454
    454455  If the time shift value is invalid, e. g. no multiple of a full hour
     
    461462- ``time_shift()``
    462463
    463   return the currently-set time shift value. See ``set_time_shift``
     464  returns the currently-set time shift value. See ``set_time_shift``
    464465  (above) for its definition.
    465466
     
    491492  "intermediate" directories which don't already exist. The ``mode``
    492493  parameter is ignored; this is for compatibility with ``os.mkdir`` if
    493   an ``FTPHost`` object is passed into a function instead of the os
    494   module (see the subsection on Python exceptions above for an
    495   explanation).
     494  an ``FTPHost`` object is passed into a function instead of the
     495  ``os`` module. See the explanation in the subsection `Exception hierarchy`_.
    496496
    497497- ``makedirs(path, [mode])``
    498498
    499   works similar to ``mkdir`` (see above, but also makes intermediate
    500   directories, like ``os.makedirs``). The ``mode`` parameter is
    501   only there for compatibility with ``os.makedirs`` and is
    502   ignored.
     499  works similar to ``mkdir`` (see above), but also makes intermediate
     500  directories like ``os.makedirs``. The ``mode`` parameter is only
     501  there for compatibility with ``os.makedirs`` and is ignored.
    503502
    504503- ``rmdir(path)``
     
    519518  ``PermanentError``.
    520519
    521   To distinguish between error situations and/or pass in a callable
    522   for ``onerror``. This callable must accept three arguments:
    523   ``func``, ``path`` and ``exc_info``). ``func`` is a bound method
    524   object, *for example* ``your_host_object.listdir``. ``path`` is
    525   the path that was the recent argument of the respective method
    526   (``listdir``, ``remove``, ``rmdir``). ``exc_info`` is the exception
    527   info as it is got from ``sys.exc_info``.
     520  To distinguish between error causes, pass in a callable for
     521  ``onerror``. This callable must accept three arguments: ``func``,
     522  ``path`` and ``exc_info``. ``func`` is a bound method object,
     523  *for example* ``your_host_object.listdir``. ``path`` is the path
     524  that was the recent argument of the respective method (``listdir``,
     525  ``remove``, ``rmdir``). ``exc_info`` is the exception info as it is
     526  gotten from ``sys.exc_info``.
    528527
    529528  The code of ``rmtree`` is taken from Python's ``shutil`` module
     
    535534- ``remove(path)``
    536535
    537   removes a file or link on the remote host (similar to ``os.remove``).
     536  removes a file or link on the remote host, similar to ``os.remove``.
    538537
    539538- ``unlink(path)``
     
    547546
    548547  returns a list containing the names of the files and directories
    549   in the given path; similar to ``os.listdir``. The special names
     548  in the given path, similar to ``os.listdir``. The special names
    550549  ``.`` and ``..`` are not in the list.
    551550
     
    553552listing format used by the FTP server. When connecting to a host,
    554553``FTPHost``'s constructor tries to guess the right format, which
    555 mostly succeeds. However, if you get strange results or
    556 ``ParserError`` exceptions by a mere ``lstat`` call, please `file a
    557 bug report`_.
     554succeeds in most cases. However, if you get strange results or
     555``ParserError`` exceptions by a mere ``lstat`` call, please
     556`file a bug report`_.
    558557
    559558If ``lstat`` or ``stat`` yield wrong modification dates or times, look
     
    564563- ``lstat(path)``
    565564
    566   returns an object similar that from ``os.lstat`` (a "tuple" with
     565  returns an object similar to that from ``os.lstat`` (a "tuple" with
    567566  additional attributes; see the documentation of the ``os`` module for
    568567  details). However, due to the nature of the application, there are
     
    575574  - User and group ids can only be determined as strings, not as
    576575    numbers, and that only if the server supplies them. This is
    577     usually the case with Unix servers but may not be for other FTP
     576    usually the case with Unix servers but maybe not for other FTP
    578577    server programs.
    579578
     
    587586    information in the ``DIR`` output.
    588587
    589   - Items that can't be determined at all are set to ``None``.
     588  - Stat attributes that can't be determined at all are set to
     589        ``None``. For example, a line of a directory listing may not
     590        contain the date/time of a directory's last modification.
    590591
    591592  - There's a special problem with stat'ing the root directory.
    592593    (Stat'ing things *in* the root directory is fine though.) In
    593594    this case, a ``RootDirError`` is raised. This has to do with the
    594     algorithm used by ``(l)stat`` and I know of no approach which
     595    algorithm used by ``(l)stat``, and I know of no approach which
    595596    mends this problem.
    596597
     
    608609
    609610- ``stat(path)``
     611
    610612  returns ``stat`` information also for files which are pointed to by a
    611613  link. This method follows multiple links until a regular file or
    612   directory is found. If an infinite link chain is encountered, a
     614  directory is found. If an infinite link chain is encountered or the
     615  target of the last link in the chain doesn't exist, a
    613616  ``PermanentError`` is raised.
    614617
     
    647650*each* call to ``lstat``, ``stat``, ``exists``, ``getmtime`` etc.
    648651would require to fetch a directory listing from the server, which can
    649 make the program very slow. This effect is more pronounced for
     652make the program *very* slow. This effect is more pronounced for
    650653operations which mostly scan the file system rather than transferring
    651654file data.
     
    657660also increases. This will be discussed below.
    658661
    659 Caching can - if necessary at all - be controlled via the
     662Caching can -- if necessary at all -- be controlled via the
    660663``stat_cache`` object in an ``FTPHost``'s namespace. For example,
    661664after calling
     
    669672
    670673While ``ftputil`` usually manages the cache quite well, there are two
    671 possible reasons for modifying cache parameters. The first is when the
    672 number of possible entries is too low. You may notice that when you
    673 are processing very large directories (e. g. above 1000 directories or
    674 files) and the program becomes much slower than before. It's common
    675 for code to read a directory with ``listdir`` and then process the
    676 found directories and files. For this application, it's a good rule of
    677 thumb to set the cache size to somewhat more than the number of
    678 directory entries fetched with ``listdir``. This is done by the
    679 ``resize`` method::
     674possible reasons that may suggest to modify cache parameters.
     675The first is when the number of possible entries is too low. You may
     676notice that when you are processing very large directories (e. g.
     677containing more than 1000 directories or files) and the program
     678becomes much slower than before. It's common for code to read a
     679directory with ``listdir`` and then process the found directories and
     680files. For this application, it's a good rule of thumb to set the
     681cache size to somewhat more than the number of directory entries
     682fetched with ``listdir``. This is done by the ``resize`` method::
    680683
    681684    host.stat_cache.resize(2000)
     
    763766This sets the maximum age of entries in the cache to an hour. This
    764767means any entry older won't be retrieved from the cache but its data
    765 instead fetched again from the remote host (and then again stored for
    766 up to an hour). To reset `max_age` to the default of unlimited age,
     768instead fetched again from the remote host and then again stored for
     769up to an hour. To reset `max_age` to the default of unlimited age,
    767770i. e. cache entries never expire, use ``None`` as value.
    768771
    769 If you are certain that the cache is in the way, you can disable and
    770 later re-enable it completely with ``disable`` and ``enable``::
     772If you are certain that the cache will be in the way, you can disable
     773and later re-enable it completely with ``disable`` and ``enable``::
    771774
    772775    host = ftputil.FTPHost(server, user, password)
     
    797800- ``walk(top, topdown=True, onerror=None)``
    798801
    799   iterates over a directory tree, similar to `os.walk`_ in Python 2.3
    800   and above. Actually, ``FTPHost.walk`` uses the code from Python with
    801   just the necessary modifications, so see the linked documentation.
     802  iterates over a directory tree, similar to `os.walk`_. Actually,
     803  ``FTPHost.walk`` uses the code from Python with just the necessary
     804  modifications, so see the linked documentation.
    802805
    803806.. _`os.walk`: http://www.python.org/doc/2.5/lib/os-file-dir.html#l2h-2707
     
    808811
    809812  Similar to ``os.path.walk``, the ``walk`` method in
    810   `FTPHost.path`_ can be used.
     813  `FTPHost.path`_ can be used, though ``FTPHost.walk`` is probably
     814  easier to use.
    811815
    812816Other methods
     
    836840    host.chmod("some_directory", 0755)
    837841
    838   Note the leading zero.
     842  *Note the leading zero.*
    839843 
    840844  Not all FTP servers support the ``chmod`` command. In case of
     
    954958
    955959and the attribute ``closed`` have the same semantics as for file
    956 objects of a local disk file system. The iterator protocol is also
    957 supported, i. e. you can use a loop to read a file line by line::
     960objects of a local disk file system. The iterator protocol is
     961supported as well, i. e. you can use a loop to read a file line by
     962line::
    958963
    959964    host = ftputil.FTPHost(...)
     
    12531258- Until now, I haven't paid attention to thread safety. In principle,
    12541259  at least, different ``FTPFile`` objects should be usable in different
    1255   threads.
     1260  threads. If in doubt if your approach will work, ask on the mailing
     1261  list.
    12561262
    12571263- ``FTPFile`` objects in text mode *may not* support charsets with more
     
    13061312
    13071313The ``lrucache`` module is written by Evan Prodromou
    1308 <evan@bad.dynu.ca>.
     1314<evan@prodromou.name>.
    13091315
    13101316Feedback is appreciated. :-)
Note: See TracChangeset for help on using the changeset viewer.