Cleanup and improve error message

Author: mar10

docs/sample_pyftpsync.yaml

@@ -17,9 +17,9 @@ common_config:
     # local: sync_root
     #: Remote target protocol and address
     remote: sftp://example.com/my_project
-    #: Make --dry-run default (can be overridden by --execute or --no-dry-run):
+    #: Make --dry-run default (pass  `--execute` or `--no-dry-run` to override):
     dry_run: true
-    #: Make --root default (can be overridden by --here):
+    #: Make --root default (pass `--here` to override):
     root: true
     #: Return exit code 10 on skipped files:
     report_problems: true
@@ -30,15 +30,16 @@ tasks:
     show: 
         command: tree
         dry_run: false
-        files: true
         sort: true
+        files: false  # Pass `--files` to override
 
     sync_all:
         command: sync
 
     deploy:
         command: upload
-        delete_unmatched: true
+        delete: false
+        delete_unmatched: false
         exclude: build,node_modules,.*,_*
 
     deploy_force:

docs/sphinx/ug_cli.rst

@@ -87,8 +87,10 @@ FTP URLs may contain credentials (*not* recommended)::
 
     $ pyftpsync upload ~/temp ftp://joe:[email protected]/target/folder
 
-Note that `pyftpsync` also supports prompting for passwords and storing
-passwords in the system keyring and ``.netrc`` files.
+.. note::
+
+    Replace ``ftp://`` with ``ftps://`` to enable TLS encryption. |br|
+    Replace ``ftp://`` with ``sftp://`` to use the SFTP protocol.
 
 .. note::
 
@@ -97,10 +99,8 @@ passwords in the system keyring and ``.netrc`` files.
   If the remote target does *not* exist, but its parent folder does, the 
   ``--create-folder`` option may be passed.
 
-.. note::
-
-    Replace ``ftp://`` with ``ftps://`` to enable TLS encryption. |br|
-    Replace ``ftp://`` with ``sftp://`` to use the SFTP protocol.
+Note that `pyftpsync` also supports prompting for passwords and storing
+passwords in the system keyring and ``.netrc`` files (see below).
 
 
 Authentication
@@ -157,8 +157,8 @@ The ``--match`` option filters processed files using on or more patterns
 (using the `fnmatch syntax <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`_). |br|
 **Note:**  These patterns are only applied to files, not directories.
 
-The ``--exclude`` option is applied after `--match` and removes entries from
-processing. Unlike `--match`, these patterns are also applied to directories.
+The ``--exclude`` option is applied after ``--match`` and removes entries from
+processing. Unlike ``--match``, these patterns are also applied to directories.
 
 Example::
 
@@ -224,25 +224,25 @@ Example: Upload Files
 Upload all new and modified files from user's temp folder to an FTP server.
 No files are changed on the local directory::
 
-  $ pyftpsync upload ~/temp ftp://example.com/target/folder
+  $ pyftpsync upload ~/temp sftp://example.com/target/folder
 
 Add the ``--delete`` option to remove all files from the remote target that
 don't exist locally::
 
-  $ pyftpsync upload ~/temp ftp://example.com/target/folder --delete
+  $ pyftpsync upload ~/temp sftp://example.com/target/folder --delete
 
 Add the ``--dry-run`` option to switch to DRY-RUN mode, i.e. run in test mode
 without modifying files::
 
-  $ pyftpsync upload ~/temp ftp://example.com/target/folder --delete --dry-run
+  $ pyftpsync upload ~/temp sftp://example.com/target/folder --delete --dry-run
 
 Add one or more  ``-v`` options to increase output verbosity::
 
-  $ pyftpsync upload ~/temp ftp://example.com/target/folder --delete -vv
+  $ pyftpsync upload ~/temp sftp://example.com/target/folder --delete -vv
 
 Mirror current directory to remote folder::
 
-  $ pyftpsync upload . ftp://example.com/target/folder --force --delete --resolve=local
+  $ pyftpsync upload . sftp://example.com/target/folder --force --delete --resolve=local
 
 
 Download Files Syntax

ftpsync/cli_common.py

@@ -68,7 +68,7 @@
     action="store_true",
     default=False,
     help="replace meta data files from different pyftpsync versions "
-    "with current format. Existing data will be discarded.",
+    "with current format. Existing data will be discarded",
 )
 
 common_parser.add_argument(

ftpsync/run_command.py

@@ -169,13 +169,14 @@ def handle_run_command(parser, cli_args):
         if task_name not in config["tasks"]:
             parser.error(
                 f"Invalid entry `default_task: {task_name}`: "
-                f"must also define `tasks.{task_name}` in {config_path}"
+                f"`tasks.{task_name}` is not defined in {config_path}"
             )
 
     else:
         parser.error(
             "No `TASK` argument was passed and no default configured: "
-            f"please define `default_task: TASK` in {config_path}"
+            f"choose from [{', '.join(config['tasks'])}] "
+            f"or define `default_task: TASK` in {config_path}"
         )
 
     if task_name not in config["tasks"]:
@@ -221,7 +222,7 @@ def handle_run_command(parser, cli_args):
             write("`--no-dry-run` (or `--execute`) was passed: resetting dry_run mode")
         else:
             write(
-                "dry_run mode is configured: pass --no-dry-run (or --execute) "
+                "Dry-run mode is configured: pass --no-dry-run (or --execute) "
                 "to enable write operations"
             )
 

tests/debug_adhoc.py

@@ -5,21 +5,27 @@
 import os
 import sys
 
+from build.lib.ftpsync.util import get_debug_option
+
 sys.path.append(os.path.dirname(__file__) + "/..")
 
 
 # ===============================================================================
 # Main
 # ===============================================================================
 
+PYFTPSYNC_REMOTE_URL = get_debug_option(
+    "PYFTPSYNC_DEBUG_FTP_URL", "debug", "ftp_url", "ftp://example.com/test_pyftpsync"
+)
+
 
 def do_sync():
     from ftpsync.synchronizers import BiDirSynchronizer
     from ftpsync.targets import make_target
 
     local_target = make_target("~/test_pyftpsync_dl")
     # local_target = make_target("c:/tmp/test_pyftpsync")
-    remote_target = make_target("ftp://wwwendt.de/test_pyftpsync", {"ftp_debug": False})
+    remote_target = make_target(PYFTPSYNC_REMOTE_URL, {"ftp_debug": False})
     opts = {"verbose": 6, "dry_run": False, "resolve": "local"}
     s = BiDirSynchronizer(local_target, remote_target, opts)
     s.run()
@@ -31,7 +37,7 @@ def do_scan():
     class args:  # noqa: N801
         """"""
 
-    args.target = "ftp://wwwendt.de/test_pyftpsync"
+    args.target = PYFTPSYNC_REMOTE_URL
     args.list = True
     args.verbose = 4
     args.recursive = False