Changes between Version 19 and Version 20 of Documentation


Ignore:
Timestamp:
May 10, 2009, 4:20:43 PM (12 years ago)
Author:
schwa
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation

    v19 v20  
    22#!rst
    33
    4 ``ftputil`` - a high-level FTP client library
    5 =============================================
    6 
    7 :Version:   2.4
    8 :Date:      2009-02-15
     4``ftputil`` -- a high-level FTP client library
     5==============================================
     6
     7:Version:   2.4.1
     8:Date:      2009-05-10
    99:Summary:   high-level FTP client library for Python
    1010:Keywords:  FTP, ``ftplib`` substitute, virtual filesystem, pure Python
     
    8585  have many common methods like ``read``, ``readline``, ``readlines``,
    8686  ``write``, ``writelines``, ``close`` and can do automatic line
    87   ending conversions on the fly, i. e. text/binary mode)
     87  ending conversions on the fly, i. e. text/binary mode).
    8888
    8989
     
    9696supported in ``ftputil`` version 2.5.
    9797
    98 The exceptions are organized as follows::
     98The exception classes are organized as follows::
    9999
    100100    FTPError
     
    160160    func(path, file, os=host)
    161161
    162   to use the same code for a local and remote file system. Another
    163   similarity between ``OSError`` and ``FTPOSError`` is that the latter
    164   holds the FTP server return code in the ``errno`` attribute of the
    165   exception object and the error text in ``strerror``.
     162  to use the same code for both a local and remote file system.
     163  Another similarity between ``OSError`` and ``FTPOSError`` is that
     164  the latter holds the FTP server return code in the ``errno``
     165  attribute of the exception object and the error text in
     166  ``strerror``.
    166167
    167168- ``PermanentError``
     
    214215    550 not_there: No such file or directory.
    215216
    216   As you can see, both code snippets are similar. (However, the error
    217   codes aren't the same.)
     217  As you can see, both code snippets are similar. However, the error
     218  codes aren't the same.
    218219
    219220- ``InternalError``
     
    228229
    229230  - The directory in which "you" are placed upon login is not
    230     accessible, i. e. a ``chdir`` call fails.
     231    accessible, i. e. a ``chdir`` call with the directory as
     232    argument would fail.
    231233
    232234  - You try to access a path which contains whitespace.
     
    265267``````
    266268
    267 ``FTPHost`` instances may be generated with the following call::
     269``FTPHost`` instances can be generated with the following call::
    268270
    269271    host = ftputil.FTPHost(host, user, password, account,
     
    282284
    283285In fact, all positional and keyword arguments other than
    284 ``session_factory`` are passed to the factory to generate a new background
    285 session (which happens for every remote file that is opened; see
    286 below).
     286``session_factory`` are passed to the factory to generate a new
     287background session. This happens for every remote file that is opened;
     288see below.
    287289
    288290This functionality of the constructor also allows to wrap
     
    291293
    292294As an example, assume you want to connect to another than the default
    293 port but ``ftplib.FTP`` only offers this by means of its ``connect``
    294 method, but not via its constructor. The solution is to provide a
    295 wrapper class::
     295port, but ``ftplib.FTP`` only offers this by means of its ``connect``
     296method, not via its constructor. The solution is to use a wrapper
     297class::
    296298
    297299    import ftplib
     
    302304    class MySession(ftplib.FTP):
    303305        def __init__(self, host, userid, password, port):
    304             """Act like ftplib.FTP's constructor but connect to other port."""
     306            """Act like ftplib.FTP's constructor but connect to another port."""
    305307            ftplib.FTP.__init__(self)
    306308            self.connect(host, port)
     
    350352
    351353  are strings which denote the current and the parent directory on the
    352   remote server. sep identifies the path separator. Though `RFC 959`_
     354  remote server. ``sep`` holds the path separator. Though `RFC 959`_
    353355  (File Transfer Protocol) notes that these values may depend on the
    354   FTP server implementation, the Unix counterparts seem to work well
    355   in practice, even for non-Unix servers.
     356  FTP server implementation, the Unix variants seem to work well in
     357  practice, even for non-Unix servers.
    356358
    357359Remote file system navigation
     
    374376
    375377  copies a local source file (given by a filename, i. e. a string)
    376   to the remote host under the name target. Both source and target
    377   may be absolute paths or relative to their corresponding current
    378   directory (on the local or the remote host, respectively). The
    379   mode may be "" or "a" for ASCII uploads or "b" for binary uploads.
    380   ASCII mode is the default (again, similar to regular local file
    381   objects).
     378  to the remote host under the name target. Both ``source`` and
     379  ``target`` may be absolute paths or relative to their corresponding
     380  current directory (on the local or the remote host, respectively).
     381  The mode may be "" or "a" for ASCII uploads or "b" for binary
     382  uploads. ASCII mode is the default, similar to regular local
     383  file objects.
    382384
    383385- ``download(source, target, mode='')``
    384386
    385387  performs a download from the remote source to a target file. Both
    386   source and target are strings. Additionally, the description of
     388  ``source`` and ``target`` are strings. Most of the description of
    387389  the upload method applies here, too.
    388390
     
    391393- ``upload_if_newer(source, target, mode='')``
    392394
    393   is similar to the upload method. The only difference is that the
    394   upload is only invoked if the time of the last modification for
    395   the source file is more recent than that of the target file, or
    396   the target doesn't exist at all. If an upload actually happened,
    397   the return value is a true value, else a false value.
     395  is similar to the ``upload`` method. The only difference is that the
     396  upload is only invoked if the time of the last modification for the
     397  source file is more recent than that of the target file or the
     398  target doesn't exist at all. If an upload actually happened, the
     399  return value is a true value, else a false value.
    398400
    399401  Note that this method only checks the existence and/or the
     
    411413  newer modification time than the local file, and thus the transfer
    412414  won't be repeated if ``upload_if_newer`` is used a second time.
    413   There are (at least) two possibilities after a failed upload:
     415  There are at least two possibilities after a failed upload:
    414416
    415417  - use ``upload`` instead of ``upload_if_newer``, or
     
    418420    use ``upload`` or ``upload_if_newer`` to transfer it again.
    419421
    420   If it seems that a file is uploaded unnecessarily, read the
    421   subsection on `time shift`_ settings.
     422  If it seems that a file is uploaded unnecessarily or not when it
     423  should, read the subsection on `time shift`_ settings.
    422424
    423425.. _`download_if_newer`:
     
    430432  return value is a true value, else a false value.
    431433
    432   If it seems that a file is downloaded unnecessarily, read the
    433   subsection on `time shift`_ settings.
     434  If it seems that a file is downloaded unnecessarily or not when it
     435  should, read the subsection on `time zone correction`_.
    434436
    435437.. _`time shift`:
     438.. _`time zone correction`:
    436439
    437440Time zone correction
    438441````````````````````
    439442
     443If the client where ``ftputil`` runs and the server have a different
     444understanding of their local times, this has to be taken into account
     445for ``upload_if_newer`` and ``download_if_newer`` to work correctly.
     446
     447Note that even if the client and the server are in the same time zone
     448(or even on the same computer), the time shift value (see below) may
     449be different from zero. For example, my computer is set to use local
     450time whereas the server running on the very same host insists on using
     451UTC time.
     452
    440453.. _`set_time_shift`:
    441454
    442455- ``set_time_shift(time_shift)``
    443456
    444   sets the so-called time shift value (measured in seconds). The time
     457  sets the so-called time shift value, measured in seconds. The time
    445458  shift is the difference between the local time of the server and the
    446459  local time of the client at a given moment, i. e. by definition
     
    450463    time_shift = server_time - client_time
    451464
    452   Setting this value is important if `upload_if_newer`_ and
    453   `download_if_newer`_ should work correctly even if the time zone of
    454   the FTP server differs from that of the client (where ``ftputil``
    455   runs). Note that the time shift value *can* be negative.
     465  Setting this value is important for `upload_if_newer`_ and
     466  `download_if_newer`_ to work correctly even if the time zone of the
     467  FTP server differs from that of the client. Note that the time shift
     468  value *can be negative*.
    456469
    457470  If the time shift value is invalid, e. g. no multiple of a full hour
    458   or its absolute (unsigned) value larger than 24 hours, a
    459   ``TimeShiftError`` is raised.
     471  or its absolute value larger than 24 hours, a ``TimeShiftError`` is
     472  raised.
    460473
    461474  See also `synchronize_times`_ for a way to set the time shift with a
     
    464477- ``time_shift()``
    465478
    466   return the currently-set time shift value. See ``set_time_shift``
    467   (above) for its definition.
     479  returns the currently-set time shift value. See ``set_time_shift``
     480  above for its definition.
    468481
    469482.. _`synchronize_times`:
     
    473486  synchronizes the local times of the server and the client, so that
    474487  `upload_if_newer`_ and `download_if_newer`_ work as expected, even
    475   if the client and the server are in different time zones. For this
     488  if the client and the server use different time zones. For this
    476489  to work, *all* of the following conditions must be true:
    477490
     
    482495
    483496  If you can't fulfill these conditions, you can nevertheless set the
    484   time shift value manually with `set_time_shift`_. Trying to call
    485   ``synchronize_times`` if the above conditions aren't true results in
     497  time shift value explicitly with `set_time_shift`_. Trying to call
     498  ``synchronize_times`` if the above conditions aren't met results in
    486499  a ``TimeShiftError`` exception.
    487500
     
    494507  "intermediate" directories which don't already exist. The ``mode``
    495508  parameter is ignored; this is for compatibility with ``os.mkdir`` if
    496   an ``FTPHost`` object is passed into a function instead of the os
    497   module (see the subsection on Python exceptions above for an
    498   explanation).
     509  an ``FTPHost`` object is passed into a function instead of the
     510  ``os`` module. See the explanation in the subsection `Exception
     511  hierarchy`_.
    499512
    500513- ``makedirs(path, [mode])``
    501514
    502   works similar to ``mkdir`` (see above, but also makes intermediate
    503   directories, like ``os.makedirs``). The ``mode`` parameter is
    504   only there for compatibility with ``os.makedirs`` and is
    505   ignored.
     515  works similar to ``mkdir`` (see above), but also makes intermediate
     516  directories like ``os.makedirs``. The ``mode`` parameter is only
     517  there for compatibility with ``os.makedirs`` and is ignored.
    506518
    507519- ``rmdir(path)``
     
    522534  ``PermanentError``.
    523535
    524   To distinguish between error situations and/or pass in a callable
     536  To distinguish between different kinds of errors, pass in a callable
    525537  for ``onerror``. This callable must accept three arguments:
    526   ``func``, ``path`` and ``exc_info``). ``func`` is a bound method
    527   object, *for example* ``your_host_object.listdir``. ``path`` is
    528   the path that was the recent argument of the respective method
     538  ``func``, ``path`` and ``exc_info``. ``func`` is a bound method
     539  object, *for example* ``your_host_object.listdir``. ``path`` is the
     540  path that was the recent argument of the respective method
    529541  (``listdir``, ``remove``, ``rmdir``). ``exc_info`` is the exception
    530   info as it is got from ``sys.exc_info``.
     542  info as it is gotten from ``sys.exc_info``.
    531543
    532544  The code of ``rmtree`` is taken from Python's ``shutil`` module
     
    538550- ``remove(path)``
    539551
    540   removes a file or link on the remote host (similar to ``os.remove``).
     552  removes a file or link on the remote host, similar to ``os.remove``.
    541553
    542554- ``unlink(path)``
     
    550562
    551563  returns a list containing the names of the files and directories
    552   in the given path; similar to ``os.listdir``. The special names
     564  in the given path, similar to ``os.listdir``. The special names
    553565  ``.`` and ``..`` are not in the list.
    554566
    555 The methods ``lstat`` and ``stat`` (and others) rely on the directory
    556 listing format used by the FTP server. When connecting to a host,
    557 ``FTPHost``'s constructor tries to guess the right format, which
    558 mostly succeeds. However, if you get strange results or
     567The methods ``lstat`` and ``stat`` (and some others) rely on the
     568directory listing format used by the FTP server. When connecting to a
     569host, ``FTPHost``'s constructor tries to guess the right format, which
     570succeeds in most cases. However, if you get strange results or
    559571``ParserError`` exceptions by a mere ``lstat`` call, please `file a
    560572bug report`_.
    561573
    562574If ``lstat`` or ``stat`` yield wrong modification dates or times, look
    563 at the methods that deal with time zone differences (`time shift`_).
     575at the methods that deal with time zone differences (`time zone
     576correction`_).
    564577
    565578.. _`FTPHost.lstat`:
     
    567580- ``lstat(path)``
    568581
    569   returns an object similar that from ``os.lstat`` (a "tuple" with
    570   additional attributes; see the documentation of the ``os`` module for
    571   details). However, due to the nature of the application, there are
    572   some important aspects to keep in mind:
    573 
    574   - The result is derived by parsing the output of a ``DIR`` command on
    575     the server. Therefore, the result from ``FTPHost.lstat`` can not
    576     contain more information than the received text. In particular:
     582  returns an object similar to that from ``os.lstat``. This is a
     583  "tuple" with additional attributes; see the documentation of the
     584  ``os`` module for details.
     585
     586  The result is derived by parsing the output of a ``DIR`` command on
     587  the server. Therefore, the result from ``FTPHost.lstat`` can not
     588  contain more information than the received text. In particular:
    577589
    578590  - User and group ids can only be determined as strings, not as
    579591    numbers, and that only if the server supplies them. This is
    580     usually the case with Unix servers but may not be for other FTP
     592    usually the case with Unix servers but maybe not for other FTP
    581593    server programs.
    582594
     
    590602    information in the ``DIR`` output.
    591603
    592   - Items that can't be determined at all are set to ``None``.
     604  - Stat attributes that can't be determined at all are set to
     605        ``None``. For example, a line of a directory listing may not
     606        contain the date/time of a directory's last modification.
    593607
    594608  - There's a special problem with stat'ing the root directory.
    595609    (Stat'ing things *in* the root directory is fine though.) In
    596610    this case, a ``RootDirError`` is raised. This has to do with the
    597     algorithm used by ``(l)stat`` and I know of no approach which
     611    algorithm used by ``(l)stat``, and I know of no approach which
    598612    mends this problem.
    599 
    600 ..
    601613
    602614  Currently, ``ftputil`` recognizes the common Unix-style and
     
    611623
    612624- ``stat(path)``
     625
    613626  returns ``stat`` information also for files which are pointed to by a
    614627  link. This method follows multiple links until a regular file or
    615   directory is found. If an infinite link chain is encountered, a
     628  directory is found. If an infinite link chain is encountered or the
     629  target of the last link in the chain doesn't exist, a
    616630  ``PermanentError`` is raised.
    617631
     
    643657    walk(path, func, arg)
    644658
     659Like Python's counterparts under `os.path`_, ``ftputil``'s ``is...``
     660methods return ``False`` if they can't find the path given by their
     661argument.
     662
    645663Local caching of file system information
    646664````````````````````````````````````````
     
    650668*each* call to ``lstat``, ``stat``, ``exists``, ``getmtime`` etc.
    651669would require to fetch a directory listing from the server, which can
    652 make the program very slow. This effect is more pronounced for
     670make the program *very* slow. This effect is more pronounced for
    653671operations which mostly scan the file system rather than transferring
    654672file data.
    655673
    656 For this reason, ``ftputil`` by default saves (caches) the results
    657 from directory listings locally and reuses those results. This reduces
     674For this reason, ``ftputil`` by default saves the results from
     675directory listings locally and reuses those results. This reduces
    658676network accesses and so speeds up the software a lot. However, since
    659677data is more rarely fetched from the server, the risk of obsolete data
    660678also increases. This will be discussed below.
    661679
    662 Caching can - if necessary at all - be controlled via the
     680Caching can be controlled -- if necessary at all -- via the
    663681``stat_cache`` object in an ``FTPHost``'s namespace. For example,
    664682after calling
     
    672690
    673691While ``ftputil`` usually manages the cache quite well, there are two
    674 possible reasons for modifying cache parameters. The first is when the
    675 number of possible entries is too low. You may notice that when you
    676 are processing very large directories (e. g. above 1000 directories or
    677 files) and the program becomes much slower than before. It's common
    678 for code to read a directory with ``listdir`` and then process the
    679 found directories and files. For this application, it's a good rule of
    680 thumb to set the cache size to somewhat more than the number of
    681 directory entries fetched with ``listdir``. This is done by the
    682 ``resize`` method::
     692possible reasons that may suggest modifying cache parameters.
     693The first is when the number of possible entries is too low. You may
     694notice that when you are processing very large directories, e. g.
     695containing more than 1000 directories or files, and the program
     696becomes much slower than before. It's common for code to read a
     697directory with ``listdir`` and then process the found directories and
     698files. For this application, it's a good rule of thumb to set the
     699cache size to somewhat more than the number of directory entries
     700fetched with ``listdir``. This is done by the ``resize`` method::
    683701
    684702    host.stat_cache.resize(2000)
     
    686704where the argument is the maximum number of ``lstat`` results to store
    687705(the default is 1000). Note that each path on the server, e. g.
    688 "/home/schwa/some_dir", corresponds to a single cache entry. (Methods
     706"/home/schwa/some_dir", corresponds to a single cache entry. Methods
    689707like ``exists`` or ``getmtime`` all derive their results from a
    690 previously fetched ``lstat`` result.)
     708previously fetched ``lstat`` result.
    691709
    692710The value 2000 above means that the cache will hold at most 2000
    693 entries. If more are about to be stored, the entries which have not
     711entries. If more are about to be stored, the entries which haven't
    694712been used for the longest time will be deleted to make place for newer
    695713entries.
     
    705723changes are handled transparently; the path will be deleted from the
    706724cache. A different matter are changes unknown to the ``FTPHost``
    707 object which reads its cache. Obviously, for example, these are
     725object which inspects its cache. Obviously, for example, these are
    708726changes by programs running on the remote host. On the other hand,
    709727cache inconsistencies can also occur if two ``FTPHost`` objects change
     
    729747to be very error-prone. For example, it won't help with different
    730748processes using ``ftputil``. So, if you have to deal with concurrent
    731 write accesses to a server, you have to handle them explicitly.
    732 
    733 The most useful tool for this probably is the ``invalidate`` method.
    734 In the example above, it could be used as::
     749write/read accesses to a server, you have to handle them explicitly.
     750
     751The most useful tool for this is the ``invalidate`` method. In the
     752example above, it could be used like this::
    735753
    736754    host1 = ftputil.FTPHost(server, user1, password1)
     
    756774directory, a file or a link.
    757775
    758 By default, the cache entries are stored indefinitely, i. e. if you
    759 start your Python process using ``ftputil`` and let it run for three
    760 days a stat call may still access cache data that old. To avoid this,
    761 you can set the ``max_age`` attribute::
     776By default, the cache entries (if not replaced by newer ones) are
     777stored for an infinite time. That is, if you start your Python process
     778using ``ftputil`` and let it run for three days a stat call may still
     779access cache data that old. To avoid this, you can set the ``max_age``
     780attribute::
    762781
    763782    host = ftputil.FTPHost(server, user, password)
     
    766785This sets the maximum age of entries in the cache to an hour. This
    767786means any entry older won't be retrieved from the cache but its data
    768 instead fetched again from the remote host (and then again stored for
    769 up to an hour). To reset `max_age` to the default of unlimited age,
     787instead fetched again from the remote host and then again stored for
     788up to an hour. To reset `max_age` to the default of unlimited age,
    770789i. e. cache entries never expire, use ``None`` as value.
    771790
    772 If you are certain that the cache is in the way, you can disable and
    773 later re-enable it completely with ``disable`` and ``enable``::
     791If you are certain that the cache will be in the way, you can disable
     792and later re-enable it completely with ``disable`` and ``enable``::
    774793
    775794    host = ftputil.FTPHost(server, user, password)
     
    800819- ``walk(top, topdown=True, onerror=None)``
    801820
    802   iterates over a directory tree, similar to `os.walk`_ in Python 2.3
    803   and above. Actually, ``FTPHost.walk`` uses the code from Python with
    804   just the necessary modifications, so see the linked documentation.
     821  iterates over a directory tree, similar to `os.walk`_. Actually,
     822  ``FTPHost.walk`` uses the code from Python with just the necessary
     823  modifications, so see the linked documentation.
    805824
    806825.. _`os.walk`: http://www.python.org/doc/2.5/lib/os-file-dir.html#l2h-2707
     
    811830
    812831  Similar to ``os.path.walk``, the ``walk`` method in
    813   `FTPHost.path`_ can be used.
     832  `FTPHost.path`_ can be used, though ``FTPHost.walk`` is probably
     833  easier to use.
    814834
    815835Other methods
     
    839859    host.chmod("some_directory", 0755)
    840860
    841   Note the leading zero.
    842  
     861  *Note the leading zero.*
     862
    843863  Not all FTP servers support the ``chmod`` command. In case of
    844864  an exception, how do you know if the path doesn't exist or if
     
    848868  response to a ``CommandNotImplementedError`` which is derived from
    849869  ``PermanentError``.
    850  
     870
    851871  So you need to code like this::
    852872
     
    918938
    919939If you are sure that all the users of your code use at least Python
    920 2.5, you can use Python's `with statement`_ also with the ``FTPFile``
     9402.5, you can use Python's `with statement`_ with the ``FTPFile``
    921941constructor::
    922942
     
    937957If something goes wrong during the construction of the file or in the
    938958body of the ``with`` statement, the file will be closed as well.
    939 Exceptions will be propagated (as with ``try ... finally``).
     959Exceptions will be propagated as with ``try ... finally``.
    940960
    941961.. _`with statement`: http://www.python.org/dev/peps/pep-0343/
     
    957977
    958978and the attribute ``closed`` have the same semantics as for file
    959 objects of a local disk file system. The iterator protocol is also
    960 supported, i. e. you can use a loop to read a file line by line::
     979objects of a local disk file system. The iterator protocol is
     980supported as well, i. e. you can use a loop to read a file line by
     981line::
    961982
    962983    host = ftputil.FTPHost(...)
     
    9851006(Unix and MS style) and adjusts itself automatically. However, if your
    9861007server uses a format which is different from the two provided by
    987 ``ftputil``, you can plug in an own custom parser and have it used by
     1008``ftputil``, you can plug in a custom parser and have it used by
    9881009a single method call.
    9891010
     
    10841105
    10851106Additionally, there's an attribute ``_month_numbers`` which maps
    1086 three-letter month abbreviations to integers.
     1107lowercase three-letter month abbreviations to integers.
    10871108
    10881109For more details, see the two "standard" parsers ``UnixParser`` and
     
    11171138subscribe or read the archives.
    11181139
     1140Though you can *technically* post without subscribing first I can't
     1141recommend that: The mails from non-subscribers have to be approved by
     1142me and because the arriving mails contain *lots* of spam, I rarely go
     1143through this bunch of mails.
     1144
    11191145I found a bug! What now?
    11201146~~~~~~~~~~~~~~~~~~~~~~~~
     
    11271153Please see http://ftputil.sschwarzer.net/issuetrackernotes for
    11281154guidelines on entering a bug in ``ftputil``'s ticket system. If you
    1129 are unsure if the behaviour you found is a bug or not, you can write
     1155are unsure if the behaviour you found is a bug or not, you should write
    11301156to the `ftputil mailing list`_. In *either* case you *must not*
    11311157include confidential information (user id, password, file names, etc.)
     
    12051231unnecessarily, or not when it should. This can happen when the FTP
    12061232server is in a different time zone than the client on which
    1207 ``ftputil`` runs. Please see the section on setting the
    1208 `time shift`_. It may even be sufficient to call `synchronize_times`_.
     1233``ftputil`` runs. Please see the section on `time zone correction`_.
     1234It may even be sufficient to call `synchronize_times`_.
    12091235
    12101236Wrong dates or times when stat'ing on a server
     
    12321258.. _`plug in an own parser`: `Writing directory parsers`_
    12331259
     1260``isdir``, ``isfile`` or ``islink`` incorrectly return ``False``
     1261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1262
     1263Like Python's counterparts under `os.path`_, ``ftputil``'s methods
     1264return ``False`` if they can't find the given path.
     1265
     1266Probably you used ``listdir`` on a directory and called ``is...()`` on
     1267the returned names. But if the argument for ``listdir`` wasn't the
     1268current directory, the paths won't be found and so all ``is...()``
     1269variants will return ``False``.
     1270
    12341271I don't find an answer to my problem in this document
    12351272~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    12561293- Until now, I haven't paid attention to thread safety. In principle,
    12571294  at least, different ``FTPFile`` objects should be usable in different
    1258   threads.
    1259 
    1260 - ``FTPFile`` objects in text mode *may not* support charsets with more
    1261   than one byte per character. Please email me your experiences
    1262   (address above), if you work with multibyte text streams in FTP
    1263   sessions.
     1295  threads. If in doubt if your approach will work, ask on the mailing
     1296  list.
     1297
     1298- ``FTPFile`` objects in text mode *may not* support charsets with
     1299  more than one byte per character. Please e-mail your experiences to
     1300  the mailing list (see above), if you work with multibyte text
     1301  streams in FTP sessions.
    12641302
    12651303- Currently, it is not possible to continue an interrupted upload or
     
    12751313
    12761314If not overwritten via installation options, the ``ftputil`` files
    1277 reside in the ``ftputil`` package. The documentation (in
    1278 `reStructuredText`_ and in HTML format) is in the same directory.
     1315reside in the ``ftputil`` package. The documentation in
     1316`reStructuredText`_ and in HTML format is in the same directory.
    12791317
    12801318.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
    12811319
    12821320The files ``_test_*.py`` and ``_mock_ftplib.py`` are for unit-testing.
    1283 If you only *use* ``ftputil`` (i. e. *don't* modify it), you can
     1321If you only *use* ``ftputil``, i. e. *don't* modify it, you can
    12841322delete these files.
    12851323
     
    13091347
    13101348The ``lrucache`` module is written by Evan Prodromou
    1311 <evan@bad.dynu.ca>.
     1349<evan@prodromou.name>.
    13121350
    13131351Feedback is appreciated. :-)
    1314 
    13151352}}}