Changeset 1940:b0cb3871ed21


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

ticket: 134
File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/ftputil.txt

    r1890 r1940  
    610610````````````````````
    611611
    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.
    615 
    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_.
     615
     616.. _UTC: https://en.wikipedia.org/wiki/Utc
    620617
    621618.. _`set_time_shift`:
     
    624621
    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.
    628625
    629626  ::
    630627
    631     time_shift = server_time - client_time
    632 
    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
     629
     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.
     635
     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.
    637641
    638642  If the time shift value is invalid, for example its absolute value
    639643  is larger than 24 hours, a ``TimeShiftError`` is raised.
    640644
     645  .. note::
     646
     647     Versions of ftputil before 4.0.0 used a different definition of
     648     "time shift", server_time - local_client_time.
     649
     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.
     656
    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
     661
     662  ::
     663
     664    set_time_shift(
     665      round( (datetime.datetime.now() - datetime.datetime.utcnow()).seconds, -2 )
     666    )
    643667
    644668- ``time_shift()``
     
    15781602
    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
     1606`synchronize_times`_.
    15841607
    15851608When I use ``ftputil``, all I get is a ``ParserError`` exception
Note: See TracChangeset for help on using the changeset viewer.