Changeset 1828:6cd5eb8a9922


Ignore:
Timestamp:
Jul 8, 2019, 10:57:38 PM (7 weeks ago)
Author:
Stefan Schwarzer <sschwarzer@…>
Branch:
default
amend_source:
f8eaad41b7d7a29328c4efbc662488ba23b30db5
histedit_source:
50833e3f78e78489cdd5ab55070866073b2e5fa6
Message:
Comment the two variants of stat methods

I assume the comment will help readers understand the two method
variants (with and without `_real_` prefix) better and keep them
from introducing bugs because of presumed "simplifications".
File:
1 edited

Legend:

Unmodified
Added
Removed
  • ftputil/stat.py

    r1745 r1828  
    1 # Copyright (C) 2002-2018, Stefan Schwarzer <sschwarzer@sschwarzer.net>
     1# Copyright (C) 2002-2019, Stefan Schwarzer <sschwarzer@sschwarzer.net>
    22# and ftputil contributors (see `doc/contributors.txt`)
    33# See the file LICENSE for licensing terms.
     
    552552            if self._parser.ignores_line(line):
    553553                continue
    554             # For `listdir`, we are interested in just the names,
    555             # but we use the `time_shift` parameter to have the
     554            # Although for a `listdir` call we're only interested in
     555            # the names, use the `time_shift` parameter to store the
    556556            # correct timestamp values in the cache.
    557557            stat_result = self._parser.parse_line(line,
    558558                                                  self._host.time_shift())
     559            # Skip entries "." and "..".
    559560            if stat_result._st_name in [self._host.curdir, self._host.pardir]:
    560561                continue
     
    562563            self._lstat_cache[loop_path] = stat_result
    563564            yield stat_result
     565
     566    # The methods `listdir`, `lstat` and `stat` come in two variants.
     567    # The methods `_real_listdir`, `_real_lstat` and `_real_stat` use
     568    # the currently set parser to get the directories/files of the
     569    # requested directory, the lstat result or the stat result,
     570    # respectively.
     571    #
     572    # Additionally, we have the methods `_listdir`, `_lstat` and
     573    # `_stat`, which wrap the above `_real_*` methods. _For example_,
     574    # `_listdir` calls `_real_listdir`. If `_real_listdir` can't parse
     575    # the directory lines and a parser hasn't been fixed yet,
     576    # `_listdir` switches to the MS parser and calls `_real_listdir`
     577    # again.
     578    #
     579    # There are two important conditions to watch out for:
     580    #
     581    # - If the user explicitly set a different parser with
     582    #   `FTPHost.set_parser`, parser switching is disabled after that
     583    #   and `_listdir` etc. only call "their" method once with the
     584    #   fixed parser.
     585    #
     586    # - A `_real_*` call will fail if there's no directory line at all
     587    #   in the given directory. In that case, we can't tell whether
     588    #   the default parser was appropriate or not. Hence parser
     589    #   switching will still be allowed until we encounter a directory
     590    #   that has directories/files/links in it.
    564591
    565592    def _real_listdir(self, path):
Note: See TracChangeset for help on using the changeset viewer.