Changeset 1940:b0cb3871ed21

May 31, 2020, 7:08:08 PM (14 months ago)
Stefan Schwarzer <sschwarzer@…>
Adapt documentation to changed time shift semantics

ticket: 134
1 edited


  • doc/ftputil.txt

    r1890 r1940  
    612 If the client where ``ftputil`` runs and the server have different
    613 understandings of their local times, this has to be taken into account
    614 for ``upload_if_newer`` and ``download_if_newer`` to work correctly.
    616 Note that even if the client and the server are in the same time zone
    617 (or even on the same computer), the time shift value (see below) may
    618 be different from zero. For example, my computer is set to use local
    619 time whereas the server running on the very same host uses UTC time.
     612For ``upload_if_newer`` and ``download_if_newer`` to work correctly,
     613the time zone of the server must be taken into account. By default,
     614ftputil assumes that the timestamps in server listings are in UTC_.
     616.. _UTC:
    621618.. _`set_time_shift`:
    625622  sets the so-called time shift value, measured in seconds. The time
    626   shift is the difference between the local time of the server and the
    627   local time of the client at a given moment, i. e. by definition
     623  shift here is defined as the difference between the time used in
     624  server listings and UTC.
    629626  ::
    631     time_shift = server_time - client_time
    633   Setting this value is important for `upload_if_newer`_ and
    634   `download_if_newer`_ to work correctly even if the time zone of the
    635   FTP server differs from that of the client. Note that the time shift
    636   value *can be negative*.
     628    time_shift = server_time - utc_time
     630  For example, a server in Berlin/Germany set to the local time
     631  (currently UTC+03:00), would require a time shift value of 3 *
     632  3600.0 = 10800.0 seconds to be handled correctly by ftputil's
     633  ``upload_if_newer`` and ``download_if_newer``, as well as the
     634  ``stat`` and ``lstat`` calls.
     636  Note that servers don't necessarily send their file system listings
     637  in their local time zone. Some use UTC, which actually makes sense
     638  because UTC doesn't lead to an ambiguity when there's a switch back
     639  from the daylight saving time to the "normal" time of the server
     640  location.
    638642  If the time shift value is invalid, for example its absolute value
    639643  is larger than 24 hours, a ``TimeShiftError`` is raised.
     645  .. note::
     647     Versions of ftputil before 4.0.0 used a different definition of
     648     "time shift", server_time - local_client_time.
     650     This had the advantage that the default of 0.0 would be correct
     651     *if* the server was set to the same time zone as the client
     652     where ftputil runs. On the other hand, this approach meant that
     653     the time shift depended on *two* time zones, not only the one
     654     used on the server side. This could be confusing if server
     655     and client *didn't* use the same time zone.
    641657  See also `synchronize_times`_ for a way to set the time shift with a
    642   simple method call.
     658  simple method call. If you can't use ``synchronize_times`` *and* the
     659  server uses the same time zone as the client, you can set the time
     660  shift value with
     662  ::
     664    set_time_shift(
     665      round( ( - datetime.datetime.utcnow()).seconds, -2 )
     666    )
    644668- ``time_shift()``
    15791603You may find that ``ftputil`` uploads or downloads files
    1580 unnecessarily, or not when it should. This can happen when the FTP
    1581 server is in a different time zone than the client on which
    1582 ``ftputil`` runs. Please see the section on `time zone correction`_.
    1583 It may even be sufficient to call `synchronize_times`_.
     1604unnecessarily, or not when it should. Please see the section on `time
     1605zone correction`_. It may even be sufficient to call
    15851608When I use ``ftputil``, all I get is a ``ParserError`` exception
Note: See TracChangeset for help on using the changeset viewer.