Changeset 1711:766c15f83205

Timestamp:

Dec 25, 2018, 10:55:24 PM (3 months ago)

Author:

Stefan Schwarzer <sschwarzer@…>

Branch:

default

histedit_source:

160218f7e8d5388866cabb8ce12f3d2f32ec82ca,bd2e407ea486f11e94d86b0419db5e02843089e1

Message:

Set `use_list_a_option` to `False` by default

See ticket #110 for the reasoning.

Files:

• doc/ftputil.txt (modified) (1 diff)
• ftputil/host.py (modified) (1 diff)
• test/test_real_ftp.py (modified) (1 diff)

doc/ftputil.txt

@@ -458 +458 @@
 Whether ftputil sees "hidden" files and directories (usually files or
 directories whose names start with a dot) depends on the FTP server
-configuration. By default, ftputil uses the ``-a`` option in the FTP
-``LIST`` command to find hidden files. However, the server may ignore
-this.
-
-If using the ``-a`` option leads to problems, for example if an
-FTP server causes an exception, you may switch off the use of the
-option::
+configuration. By default, ftputil does *not* use the ``-a`` option in
+the FTP ``LIST`` command to find hidden files.
+
+To tell the server to list hidden directories and files, set
+``FTPHost.use_list_a_option`` to ``True``::
 
     ftp_host = ftputil.FTPHost(server, user, password, account,
                                session_factory=ftplib.FTP)
-    ftp_host.use_list_a_option = False
+    ftp_host.use_list_a_option = True
+
+Caveats:
+
+- If the server doesn't understand the ``-a`` option at all, the
+  server may interpret ``-a`` as the name of a file or directory,
+  which can result in odd behavior. Therefore, use ``-a`` only if
+  you're sure the server you're talking to supports it. Another
+  approach is to have test code for ``-a`` support and fall back to
+  not using the option.
+
+- Even if the server knows about the ``-a`` option, the server may
+  be configured to ignore it.
 
 ``FTPHost`` attributes and methods

ftputil/host.py

@@ -94 +94 @@
         # `download_if_newer`).
         self.set_time_shift(0.0)
-        # Use `LIST -a` option by default. If this causes problems,
-        # the user can set the attribute to `False`.
-        warnings.warn(
-          "`use_list_a_option` will default to `False` in ftputil 4.x.x",
-          DeprecationWarning, stacklevel=2)
-        self.use_list_a_option = True
+        # Don't use `LIST -a` option by default. If the server doesn't
+        # understand the `-a` option and interprets it as a path, the
+        # results can be surprising. See ticket #110.
+        self.use_list_a_option = False
 
     def keep_alive(self):

test/test_real_ftp.py

@@ -944 +944 @@
         # option is used.
         host = self.host
-        assert host.use_list_a_option
+        assert not host.use_list_a_option
+        directory_entries = host.listdir(host.curdir)
+        assert ".hidden" not in directory_entries
+        # Switch on showing of hidden paths.
+        host.use_list_a_option = True
         directory_entries = host.listdir(host.curdir)
         assert ".hidden" in directory_entries
-        host.use_list_a_option = False
-        directory_entries = host.listdir(host.curdir)
-        assert ".hidden" not in directory_entries
 
     def _make_objects_to_be_garbage_collected(self):