Changeset 796:6929c27acdc9


Ignore:
Timestamp:
May 9, 2009, 1:28:32 PM (10 years ago)
Author:
Stefan Schwarzer <sschwarzer@…>
Branch:
default
Convert:
svn:778c30c8-61e0-0310-89d4-fe2f97a467b2/trunk@864
Message:
Tried to make the documentation more readable. In particular, removed
parentheses and made difficult sentences easier to parse.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • ftputil.txt

    r795 r796  
    9393supported in ``ftputil`` version 2.5.
    9494
    95 The exceptions are organized as follows::
     95The exception classes are organized as follows::
    9696
    9797    FTPError
     
    157157    func(path, file, os=host)
    158158
    159   to use the same code for a local and remote file system. Another
    160   similarity between ``OSError`` and ``FTPOSError`` is that the latter
    161   holds the FTP server return code in the ``errno`` attribute of the
    162   exception object and the error text in ``strerror``.
     159  to use the same code for both a local and remote file system.
     160  Another similarity between ``OSError`` and ``FTPOSError`` is that
     161  the latter holds the FTP server return code in the ``errno``
     162  attribute of the exception object and the error text in
     163  ``strerror``.
    163164
    164165- ``PermanentError``
     
    280281
    281282In fact, all positional and keyword arguments other than
    282 ``session_factory`` are passed to the factory to generate a new background
    283 session (which happens for every remote file that is opened; see
    284 below).
     283``session_factory`` are passed to the factory to generate a new
     284background session. This happens for every remote file that is opened;
     285see below.
    285286
    286287This functionality of the constructor also allows to wrap
     
    289290
    290291As an example, assume you want to connect to another than the default
    291 port but ``ftplib.FTP`` only offers this by means of its ``connect``
    292 method, but not via its constructor. The solution is to use a wrapper
     292port, but ``ftplib.FTP`` only offers this by means of its ``connect``
     293method, not via its constructor. The solution is to use a wrapper
    293294class::
    294295
     
    348349
    349350  are strings which denote the current and the parent directory on the
    350   remote server. ``sep`` identifies the path separator. Though `RFC 959`_
     351  remote server. ``sep`` holds the path separator. Though `RFC 959`_
    351352  (File Transfer Protocol) notes that these values may depend on the
    352   FTP server implementation, the Unix counterparts seem to work well
    353   in practice, even for non-Unix servers.
     353  FTP server implementation, the Unix variants seem to work well in
     354  practice, even for non-Unix servers.
    354355
    355356Remote file system navigation
     
    376377  current directory (on the local or the remote host, respectively).
    377378  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).
     379  uploads. ASCII mode is the default, similar to regular local
     380  file objects.
    380381
    381382- ``download(source, target, mode='')``
    382383
    383384  performs a download from the remote source to a target file. Both
    384   ``source`` and ``target`` are strings. The description of the
    385   upload method applies here, too.
     385  ``source`` and ``target`` are strings. Most of the description of
     386  the upload method applies here, too.
    386387
    387388.. _`upload_if_newer`:
     
    409410  newer modification time than the local file, and thus the transfer
    410411  won't be repeated if ``upload_if_newer`` is used a second time.
    411   There are (at least) two possibilities after a failed upload:
     412  There are at least two possibilities after a failed upload:
    412413
    413414  - use ``upload`` instead of ``upload_if_newer``, or
     
    416417    use ``upload`` or ``upload_if_newer`` to transfer it again.
    417418
    418   If it seems that a file is uploaded unnecessarily, read the
    419   subsection on `time shift`_ settings.
     419  If it seems that a file is uploaded unnecessarily or not when it
     420  should, read the subsection on `time shift`_ settings.
    420421
    421422.. _`download_if_newer`:
     
    428429  return value is a true value, else a false value.
    429430
    430   If it seems that a file is downloaded unnecessarily, read the
    431   subsection on `time zone correction`_.
     431  If it seems that a file is downloaded unnecessarily or not when it
     432  should, read the subsection on `time zone correction`_.
    432433
    433434.. _`time shift`:
     
    437438````````````````````
    438439
    439 If the client (where ``ftputil`` runs) and the server have a different
    440 understanding of local time, this has to be taken into account for
    441 ``upload_if_newer`` and ``download_if_newer`` to work correctly.
     440If the client where ``ftputil`` runs and the server have a different
     441understanding of their local times, this has to be taken into account
     442for ``upload_if_newer`` and ``download_if_newer`` to work correctly.
    442443
    443444Note that even if the client and the server are in the same time zone
    444445(or even on the same computer), the time shift value (see below) may
    445446be different from zero. For example, my computer is set to use local
    446 time whereas the server insists on using UTC time.
     447time whereas the server running on the very same host insists on using
     448UTC time.
    447449
    448450.. _`set_time_shift`:
     
    450452- ``set_time_shift(time_shift)``
    451453
    452   sets the so-called time shift value (measured in seconds). The time
     454  sets the so-called time shift value, measured in seconds. The time
    453455  shift is the difference between the local time of the server and the
    454456  local time of the client at a given moment, i. e. by definition
     
    458460    time_shift = server_time - client_time
    459461
    460   Setting this value is important if `upload_if_newer`_ and
    461   `download_if_newer`_ have to work correctly even if the time zone of
    462   the FTP server differs from that of the client (where ``ftputil``
    463   runs). Note that the time shift value *can be negative*.
     462  Setting this value is important for `upload_if_newer`_ and
     463  `download_if_newer`_ to work correctly even if the time zone of the
     464  FTP server differs from that of the client. Note that the time shift
     465  value *can be negative*.
    464466
    465467  If the time shift value is invalid, e. g. no multiple of a full hour
    466   or its absolute (unsigned) value larger than 24 hours, a
    467   ``TimeShiftError`` is raised.
     468  or its absolute value larger than 24 hours, a ``TimeShiftError`` is
     469  raised.
    468470
    469471  See also `synchronize_times`_ for a way to set the time shift with a
     
    473475
    474476  returns the currently-set time shift value. See ``set_time_shift``
    475   (above) for its definition.
     477  above for its definition.
    476478
    477479.. _`synchronize_times`:
     
    481483  synchronizes the local times of the server and the client, so that
    482484  `upload_if_newer`_ and `download_if_newer`_ work as expected, even
    483   if the client and the server are in different time zones. For this
     485  if the client and the server use different time zones. For this
    484486  to work, *all* of the following conditions must be true:
    485487
     
    490492
    491493  If you can't fulfill these conditions, you can nevertheless set the
    492   time shift value manually with `set_time_shift`_. Trying to call
    493   ``synchronize_times`` if the above conditions aren't true results in
     494  time shift value explicitly with `set_time_shift`_. Trying to call
     495  ``synchronize_times`` if the above conditions aren't met results in
    494496  a ``TimeShiftError`` exception.
    495497
     
    503505  parameter is ignored; this is for compatibility with ``os.mkdir`` if
    504506  an ``FTPHost`` object is passed into a function instead of the
    505   ``os`` module. See the explanation in the subsection `Exception hierarchy`_.
     507  ``os`` module. See the explanation in the subsection `Exception
     508  hierarchy`_.
    506509
    507510- ``makedirs(path, [mode])``
     
    528531  ``PermanentError``.
    529532
    530   To distinguish between error causes, pass in a callable for
    531   ``onerror``. This callable must accept three arguments: ``func``,
    532   ``path`` and ``exc_info``. ``func`` is a bound method object,
    533   *for example* ``your_host_object.listdir``. ``path`` is the path
    534   that was the recent argument of the respective method (``listdir``,
    535   ``remove``, ``rmdir``). ``exc_info`` is the exception info as it is
    536   gotten from ``sys.exc_info``.
     533  To distinguish between different kinds of errors, pass in a callable
     534  for ``onerror``. This callable must accept three arguments:
     535  ``func``, ``path`` and ``exc_info``. ``func`` is a bound method
     536  object, *for example* ``your_host_object.listdir``. ``path`` is the
     537  path that was the recent argument of the respective method
     538  (``listdir``, ``remove``, ``rmdir``). ``exc_info`` is the exception
     539  info as it is gotten from ``sys.exc_info``.
    537540
    538541  The code of ``rmtree`` is taken from Python's ``shutil`` module
     
    559562  ``.`` and ``..`` are not in the list.
    560563
    561 The methods ``lstat`` and ``stat`` (and others) rely on the directory
    562 listing format used by the FTP server. When connecting to a host,
    563 ``FTPHost``'s constructor tries to guess the right format, which
     564The methods ``lstat`` and ``stat`` (and some others) rely on the
     565directory listing format used by the FTP server. When connecting to a
     566host, ``FTPHost``'s constructor tries to guess the right format, which
    564567succeeds in most cases. However, if you get strange results or
    565 ``ParserError`` exceptions by a mere ``lstat`` call, please
    566 `file a bug report`_.
     568``ParserError`` exceptions by a mere ``lstat`` call, please `file a
     569bug report`_.
    567570
    568571If ``lstat`` or ``stat`` yield wrong modification dates or times, look
     
    574577- ``lstat(path)``
    575578
    576   returns an object similar to that from ``os.lstat`` (a "tuple" with
    577   additional attributes; see the documentation of the ``os`` module for
    578   details). However, due to the nature of the application, there are
    579   some important aspects to keep in mind:
    580 
    581   - The result is derived by parsing the output of a ``DIR`` command on
    582     the server. Therefore, the result from ``FTPHost.lstat`` can not
    583     contain more information than the received text. In particular:
     579  returns an object similar to that from ``os.lstat``. This is a
     580  "tuple" with additional attributes; see the documentation of the
     581  ``os`` module for details.
     582
     583  The result is derived by parsing the output of a ``DIR`` command on
     584  the server. Therefore, the result from ``FTPHost.lstat`` can not
     585  contain more information than the received text. In particular:
    584586
    585587  - User and group ids can only be determined as strings, not as
     
    606608    algorithm used by ``(l)stat``, and I know of no approach which
    607609    mends this problem.
    608 
    609 ..
    610610
    611611  Currently, ``ftputil`` recognizes the common Unix-style and
     
    655655
    656656Like Python's counterparts under `os.path`_, ``ftputil``'s ``is...``
    657 methods return ``False`` if they can't find the given path.
     657methods return ``False`` if they can't find the path given by their
     658argument.
    658659
    659660Local caching of file system information
     
    668669file data.
    669670
    670 For this reason, ``ftputil`` by default saves (caches) the results
    671 from directory listings locally and reuses those results. This reduces
     671For this reason, ``ftputil`` by default saves the results from
     672directory listings locally and reuses those results. This reduces
    672673network accesses and so speeds up the software a lot. However, since
    673674data is more rarely fetched from the server, the risk of obsolete data
    674675also increases. This will be discussed below.
    675676
    676 Caching can -- if necessary at all -- be controlled via the
     677Caching can be controlled -- if necessary at all -- via the
    677678``stat_cache`` object in an ``FTPHost``'s namespace. For example,
    678679after calling
     
    686687
    687688While ``ftputil`` usually manages the cache quite well, there are two
    688 possible reasons that may suggest to modify cache parameters.
     689possible reasons that may suggest modifying cache parameters.
    689690The first is when the number of possible entries is too low. You may
    690 notice that when you are processing very large directories (e. g.
    691 containing more than 1000 directories or files) and the program
     691notice that when you are processing very large directories, e. g.
     692containing more than 1000 directories or files, and the program
    692693becomes much slower than before. It's common for code to read a
    693694directory with ``listdir`` and then process the found directories and
     
    700701where the argument is the maximum number of ``lstat`` results to store
    701702(the default is 1000). Note that each path on the server, e. g.
    702 "/home/schwa/some_dir", corresponds to a single cache entry. (Methods
     703"/home/schwa/some_dir", corresponds to a single cache entry. Methods
    703704like ``exists`` or ``getmtime`` all derive their results from a
    704 previously fetched ``lstat`` result.)
     705previously fetched ``lstat`` result.
    705706
    706707The value 2000 above means that the cache will hold at most 2000
    707 entries. If more are about to be stored, the entries which have not
     708entries. If more are about to be stored, the entries which haven't
    708709been used for the longest time will be deleted to make place for newer
    709710entries.
     
    719720changes are handled transparently; the path will be deleted from the
    720721cache. A different matter are changes unknown to the ``FTPHost``
    721 object which reads its cache. Obviously, for example, these are
     722object which inspects its cache. Obviously, for example, these are
    722723changes by programs running on the remote host. On the other hand,
    723724cache inconsistencies can also occur if two ``FTPHost`` objects change
     
    743744to be very error-prone. For example, it won't help with different
    744745processes using ``ftputil``. So, if you have to deal with concurrent
    745 write accesses to a server, you have to handle them explicitly.
    746 
    747 The most useful tool for this probably is the ``invalidate`` method.
    748 In the example above, it could be used as::
     746write/read accesses to a server, you have to handle them explicitly.
     747
     748The most useful tool for this is the ``invalidate`` method. In the
     749example above, it could be used like this::
    749750
    750751    host1 = ftputil.FTPHost(server, user1, password1)
     
    770771directory, a file or a link.
    771772
    772 By default, the cache entries are stored indefinitely, i. e. if you
    773 start your Python process using ``ftputil`` and let it run for three
    774 days a stat call may still access cache data that old. To avoid this,
    775 you can set the ``max_age`` attribute::
     773By default, the cache entries (if not replaced by newer ones) are
     774stored for an infinite time. That is, if you start your Python process
     775using ``ftputil`` and let it run for three days a stat call may still
     776access cache data that old. To avoid this, you can set the ``max_age``
     777attribute::
    776778
    777779    host = ftputil.FTPHost(server, user, password)
     
    933935
    934936If you are sure that all the users of your code use at least Python
    935 2.5, you can use Python's `with statement`_ also with the ``FTPFile``
     9372.5, you can use Python's `with statement`_ with the ``FTPFile``
    936938constructor::
    937939
     
    952954If something goes wrong during the construction of the file or in the
    953955body of the ``with`` statement, the file will be closed as well.
    954 Exceptions will be propagated (as with ``try ... finally``).
     956Exceptions will be propagated as with ``try ... finally``.
    955957
    956958.. _`with statement`: http://www.python.org/dev/peps/pep-0343/
     
    10011003(Unix and MS style) and adjusts itself automatically. However, if your
    10021004server uses a format which is different from the two provided by
    1003 ``ftputil``, you can plug in an own custom parser and have it used by
     1005``ftputil``, you can plug in a custom parser and have it used by
    10041006a single method call.
    10051007
     
    11001102
    11011103Additionally, there's an attribute ``_month_numbers`` which maps
    1102 three-letter month abbreviations to integers.
     1104lowercase three-letter month abbreviations to integers.
    11031105
    11041106For more details, see the two "standard" parsers ``UnixParser`` and
     
    11331135subscribe or read the archives.
    11341136
     1137Though you can *technically* post without subscribing first I can't
     1138recommend that: The mails from non-subscribers have to be approved by
     1139me and because the arriving mails contain *lots* of spam, I rarely go
     1140through this bunch of mails.
     1141
    11351142I found a bug! What now?
    11361143~~~~~~~~~~~~~~~~~~~~~~~~
     
    11431150Please see http://ftputil.sschwarzer.net/issuetrackernotes for
    11441151guidelines on entering a bug in ``ftputil``'s ticket system. If you
    1145 are unsure if the behaviour you found is a bug or not, you can write
     1152are unsure if the behaviour you found is a bug or not, you should write
    11461153to the `ftputil mailing list`_. In *either* case you *must not*
    11471154include confidential information (user id, password, file names, etc.)
     
    12861293  list.
    12871294
    1288 - ``FTPFile`` objects in text mode *may not* support charsets with more
    1289   than one byte per character. Please email me your experiences
    1290   (address above), if you work with multibyte text streams in FTP
    1291   sessions.
     1295- ``FTPFile`` objects in text mode *may not* support charsets with
     1296  more than one byte per character. Please e-mail your experiences to
     1297  the mailing list (see above), if you work with multibyte text
     1298  streams in FTP sessions.
    12921299
    12931300- Currently, it is not possible to continue an interrupted upload or
     
    13031310
    13041311If not overwritten via installation options, the ``ftputil`` files
    1305 reside in the ``ftputil`` package. The documentation (in
    1306 `reStructuredText`_ and in HTML format) is in the same directory.
     1312reside in the ``ftputil`` package. The documentation in
     1313`reStructuredText`_ and in HTML format is in the same directory.
    13071314
    13081315.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
    13091316
    13101317The files ``_test_*.py`` and ``_mock_ftplib.py`` are for unit-testing.
    1311 If you only *use* ``ftputil`` (i. e. *don't* modify it), you can
     1318If you only *use* ``ftputil``, i. e. *don't* modify it, you can
    13121319delete these files.
    13131320
Note: See TracChangeset for help on using the changeset viewer.