Fold Path/prefix setup into walk_and_upload and resolve pylint findings

* Move the ``Path`` / ``is_dir`` check / prefix rstrip into
  ``walk_and_upload``; it now returns an ``UploadDirResult`` with the
  resolved source and normalised prefix so each backend can still log
  its own line. Eliminates the last duplicate-code finding across the
  four cloud/SFTP ``*_upload_dir`` functions.
* Split ``build_default_registry`` into ``_local_commands`` /
  ``_http_commands`` / ``_drive_commands`` / ``_register_cloud_backends``
  helpers so the top-level function drops back under the too-many-locals
  threshold.
* ``SFTPClient.later_init`` now takes an ``SFTPConnectOptions`` dataclass
  (with a kwargs-compat fallback) so it no longer trips too-many-args.
* Rename the tqdm bar variable in ``http_download`` off the disallowed
  ``bar`` name; add a ``.pylintrc`` that teaches pylint about PySide6 as
  an extension package and about googleapiclient's dynamic ``Resource``
  members; silence ``arguments-differ`` / ``useless-import-alias`` at
  their intentional use sites.

Author: JE-Chen

.pylintrc

@@ -0,0 +1,39 @@
+[MAIN]
+# PySide6 is a C-extension binding — pylint's static inference cannot see the
+# generated classes, so treat it as a trusted extension package.
+extension-pkg-allow-list=PySide6,PySide6.QtCore,PySide6.QtGui,PySide6.QtWidgets
+
+[MESSAGES CONTROL]
+# Disabled rules, with rationale:
+#   C0114/C0115/C0116 — docstring requirements are enforced by review, not lint.
+#   C0415              — ``import-outside-toplevel`` is used deliberately for
+#                        lazy imports of heavy / optional modules (see CLAUDE.md).
+#   R0903              — too-few-public-methods; dataclasses and frozen option
+#                        objects are allowed to have no methods.
+#   W0511              — TODO/FIXME markers; tracked via issues, not lint.
+disable=
+    C0114,
+    C0115,
+    C0116,
+    C0415,
+    R0903,
+    W0511
+
+[TYPECHECK]
+# googleapiclient's ``Resource`` object exposes ``files()``, ``permissions()``,
+# etc. dynamically — pylint can't see them, so whitelist the names rather than
+# littering the Drive ops modules with ``# pylint: disable=no-member``.
+generated-members=files,permissions
+
+[DESIGN]
+# Align with CLAUDE.md's code-quality checklist.
+max-args=7
+max-locals=15
+max-returns=8
+max-branches=15
+max-statements=50
+max-attributes=17
+max-public-methods=25
+
+[FORMAT]
+max-line-length=100

automation_file/__init__.py

@@ -90,7 +90,9 @@
 from automation_file.utils.file_discovery import get_dir_files_as_list
 
 if TYPE_CHECKING:
-    from automation_file.ui.launcher import launch_ui as launch_ui
+    from automation_file.ui.launcher import (
+        launch_ui as launch_ui,  # pylint: disable=useless-import-alias
+    )
 
 # Shared callback executor + package loader wired to the shared registry.
 callback_executor: CallbackExecutor = CallbackExecutor(executor.registry)

automation_file/core/action_registry.py

@@ -65,12 +65,35 @@ def event_dict(self) -> dict[str, Command]:
         return self._commands
 
 
-def build_default_registry() -> ActionRegistry:
-    """Return a registry pre-populated with every built-in ``FA_*`` action."""
+def _local_commands() -> dict[str, Command]:
     from automation_file.local import dir_ops, file_ops, zip_ops
-    from automation_file.remote import http_download
-    from automation_file.remote.azure_blob import register_azure_blob_ops
-    from automation_file.remote.dropbox_api import register_dropbox_ops
+
+    return {
+        # Files
+        "FA_create_file": file_ops.create_file,
+        "FA_copy_file": file_ops.copy_file,
+        "FA_rename_file": file_ops.rename_file,
+        "FA_remove_file": file_ops.remove_file,
+        "FA_copy_all_file_to_dir": file_ops.copy_all_file_to_dir,
+        "FA_copy_specify_extension_file": file_ops.copy_specify_extension_file,
+        # Directories
+        "FA_copy_dir": dir_ops.copy_dir,
+        "FA_create_dir": dir_ops.create_dir,
+        "FA_remove_dir_tree": dir_ops.remove_dir_tree,
+        "FA_rename_dir": dir_ops.rename_dir,
+        # Zip
+        "FA_zip_dir": zip_ops.zip_dir,
+        "FA_zip_file": zip_ops.zip_file,
+        "FA_zip_info": zip_ops.zip_info,
+        "FA_zip_file_info": zip_ops.zip_file_info,
+        "FA_set_zip_password": zip_ops.set_zip_password,
+        "FA_unzip_file": zip_ops.unzip_file,
+        "FA_read_zip_file": zip_ops.read_zip_file,
+        "FA_unzip_all": zip_ops.unzip_all,
+    }
+
+
+def _drive_commands() -> dict[str, Command]:
     from automation_file.remote.google_drive import (
         client,
         delete_ops,
@@ -80,58 +103,51 @@ def build_default_registry() -> ActionRegistry:
         share_ops,
         upload_ops,
     )
+
+    return {
+        "FA_drive_later_init": client.driver_instance.later_init,
+        "FA_drive_search_all_file": search_ops.drive_search_all_file,
+        "FA_drive_search_field": search_ops.drive_search_field,
+        "FA_drive_search_file_mimetype": search_ops.drive_search_file_mimetype,
+        "FA_drive_upload_dir_to_folder": upload_ops.drive_upload_dir_to_folder,
+        "FA_drive_upload_to_folder": upload_ops.drive_upload_to_folder,
+        "FA_drive_upload_dir_to_drive": upload_ops.drive_upload_dir_to_drive,
+        "FA_drive_upload_to_drive": upload_ops.drive_upload_to_drive,
+        "FA_drive_add_folder": folder_ops.drive_add_folder,
+        "FA_drive_share_file_to_anyone": share_ops.drive_share_file_to_anyone,
+        "FA_drive_share_file_to_domain": share_ops.drive_share_file_to_domain,
+        "FA_drive_share_file_to_user": share_ops.drive_share_file_to_user,
+        "FA_drive_delete_file": delete_ops.drive_delete_file,
+        "FA_drive_download_file": download_ops.drive_download_file,
+        "FA_drive_download_file_from_folder": download_ops.drive_download_file_from_folder,
+    }
+
+
+def _http_commands() -> dict[str, Command]:
+    from automation_file.remote import http_download
+
+    return {"FA_download_file": http_download.download_file}
+
+
+def _register_cloud_backends(registry: ActionRegistry) -> None:
+    from automation_file.remote.azure_blob import register_azure_blob_ops
+    from automation_file.remote.dropbox_api import register_dropbox_ops
     from automation_file.remote.s3 import register_s3_ops
     from automation_file.remote.sftp import register_sftp_ops
 
-    registry = ActionRegistry()
-    registry.register_many(
-        {
-            # Files
-            "FA_create_file": file_ops.create_file,
-            "FA_copy_file": file_ops.copy_file,
-            "FA_rename_file": file_ops.rename_file,
-            "FA_remove_file": file_ops.remove_file,
-            "FA_copy_all_file_to_dir": file_ops.copy_all_file_to_dir,
-            "FA_copy_specify_extension_file": file_ops.copy_specify_extension_file,
-            # Directories
-            "FA_copy_dir": dir_ops.copy_dir,
-            "FA_create_dir": dir_ops.create_dir,
-            "FA_remove_dir_tree": dir_ops.remove_dir_tree,
-            "FA_rename_dir": dir_ops.rename_dir,
-            # Zip
-            "FA_zip_dir": zip_ops.zip_dir,
-            "FA_zip_file": zip_ops.zip_file,
-            "FA_zip_info": zip_ops.zip_info,
-            "FA_zip_file_info": zip_ops.zip_file_info,
-            "FA_set_zip_password": zip_ops.set_zip_password,
-            "FA_unzip_file": zip_ops.unzip_file,
-            "FA_read_zip_file": zip_ops.read_zip_file,
-            "FA_unzip_all": zip_ops.unzip_all,
-            # HTTP
-            "FA_download_file": http_download.download_file,
-            # Google Drive
-            "FA_drive_later_init": client.driver_instance.later_init,
-            "FA_drive_search_all_file": search_ops.drive_search_all_file,
-            "FA_drive_search_field": search_ops.drive_search_field,
-            "FA_drive_search_file_mimetype": search_ops.drive_search_file_mimetype,
-            "FA_drive_upload_dir_to_folder": upload_ops.drive_upload_dir_to_folder,
-            "FA_drive_upload_to_folder": upload_ops.drive_upload_to_folder,
-            "FA_drive_upload_dir_to_drive": upload_ops.drive_upload_dir_to_drive,
-            "FA_drive_upload_to_drive": upload_ops.drive_upload_to_drive,
-            "FA_drive_add_folder": folder_ops.drive_add_folder,
-            "FA_drive_share_file_to_anyone": share_ops.drive_share_file_to_anyone,
-            "FA_drive_share_file_to_domain": share_ops.drive_share_file_to_domain,
-            "FA_drive_share_file_to_user": share_ops.drive_share_file_to_user,
-            "FA_drive_delete_file": delete_ops.drive_delete_file,
-            "FA_drive_download_file": download_ops.drive_download_file,
-            "FA_drive_download_file_from_folder": download_ops.drive_download_file_from_folder,
-        }
-    )
-    # Cloud / SFTP backends are first-class; register them on every default registry.
     register_s3_ops(registry)
     register_azure_blob_ops(registry)
     register_dropbox_ops(registry)
     register_sftp_ops(registry)
+
+
+def build_default_registry() -> ActionRegistry:
+    """Return a registry pre-populated with every built-in ``FA_*`` action."""
+    registry = ActionRegistry()
+    registry.register_many(_local_commands())
+    registry.register_many(_http_commands())
+    registry.register_many(_drive_commands())
+    _register_cloud_backends(registry)
     file_automation_logger.info(
         "action_registry: built default registry with %d commands", len(registry)
     )

automation_file/remote/_upload_tree.py

@@ -1,39 +1,63 @@
 """Shared directory-walker for cloud/SFTP ``*_upload_dir`` operations.
 
-Every backend implements the same pattern: iterate ``Path.rglob('*')``,
-skip non-files, compute a POSIX-relative remote identifier, call
+Every backend implements the same pattern: validate that ``dir_path``
+exists, normalise the remote prefix, iterate ``Path.rglob('*')``, skip
+non-files, compute a POSIX-relative remote identifier, call
 ``upload_file`` for each, and collect the successful remote keys. This
 module factors that walk out so each backend only supplies the two
-parts that actually differ — how to assemble the remote identifier
-and which per-file upload function to call.
+parts that actually differ — how to assemble the remote identifier and
+which per-file upload function to call.
 """
 
 from __future__ import annotations
 
 from collections.abc import Callable
 from pathlib import Path
+from typing import NamedTuple
+
+from automation_file.exceptions import DirNotExistsException
+
+
+class UploadDirResult(NamedTuple):
+    """Return value of :func:`walk_and_upload`.
+
+    Carries the resolved ``source`` ``Path``, the normalised prefix
+    (trailing ``/`` stripped), and the list of remote identifiers that
+    uploaded successfully — so each backend can feed its own log line
+    without re-doing the Path / prefix work.
+    """
+
+    source: Path
+    prefix: str
+    uploaded: list[str]
 
 
 def walk_and_upload(
-    source: Path,
-    make_remote: Callable[[str], str],
+    dir_path: str,
+    prefix: str,
+    make_remote: Callable[[str, str], str],
     upload_one: Callable[[Path, str], bool],
-) -> list[str]:
-    """Return the list of remote identifiers successfully uploaded from ``source``.
-
-    ``make_remote`` is called with the POSIX relative path of each file
-    (no leading slash) and must return the backend-specific remote key.
-    ``upload_one`` receives ``(local_path, remote_key)`` and returns True
-    on success. Per-file failures are not raised — they are simply
-    omitted from the returned list, matching the existing backend
+) -> UploadDirResult:
+    """Walk ``dir_path`` and upload every file via ``upload_one``.
+
+    Raises :class:`DirNotExistsException` if ``dir_path`` is not a
+    directory. ``prefix`` is ``rstrip("/")``-ed before being passed to
+    ``make_remote(normalised_prefix, rel_posix)``, and ``upload_one``
+    receives ``(local_path, remote_key)`` returning True on success.
+    Per-file failures are not raised — they are simply omitted from
+    :attr:`UploadDirResult.uploaded`, matching the existing backend
     contract.
     """
+    source = Path(dir_path)
+    if not source.is_dir():
+        raise DirNotExistsException(str(source))
+    normalised = prefix.rstrip("/")
     uploaded: list[str] = []
     for entry in source.rglob("*"):
         if not entry.is_file():
             continue
         rel = entry.relative_to(source).as_posix()
-        remote = make_remote(rel)
+        remote = make_remote(normalised, rel)
         if upload_one(entry, remote):
             uploaded.append(remote)
-    return uploaded
+    return UploadDirResult(source=source, prefix=normalised, uploaded=uploaded)

automation_file/remote/azure_blob/upload_ops.py

@@ -4,7 +4,7 @@
 
 from pathlib import Path
 
-from automation_file.exceptions import DirNotExistsException, FileNotExistsException
+from automation_file.exceptions import FileNotExistsException
 from automation_file.logging_config import file_automation_logger
 from automation_file.remote._upload_tree import walk_and_upload
 from automation_file.remote.azure_blob.client import azure_blob_instance
@@ -43,20 +43,17 @@ def azure_blob_upload_dir(
     name_prefix: str = "",
 ) -> list[str]:
     """Upload every file under ``dir_path`` to ``container`` under ``name_prefix``."""
-    source = Path(dir_path)
-    if not source.is_dir():
-        raise DirNotExistsException(str(source))
-    prefix = name_prefix.rstrip("/")
-    uploaded = walk_and_upload(
-        source,
-        lambda rel: f"{prefix}/{rel}" if prefix else rel,
+    result = walk_and_upload(
+        dir_path,
+        name_prefix,
+        lambda prefix, rel: f"{prefix}/{rel}" if prefix else rel,
         lambda local, blob_name: azure_blob_upload_file(str(local), container, blob_name),
     )
     file_automation_logger.info(
         "azure_blob_upload_dir: %s -> %s/%s (%d files)",
-        source,
+        result.source,
         container,
-        prefix,
-        len(uploaded),
+        result.prefix,
+        len(result.uploaded),
     )
-    return uploaded
+    return result.uploaded

automation_file/remote/dropbox_api/upload_ops.py

@@ -4,7 +4,7 @@
 
 from pathlib import Path
 
-from automation_file.exceptions import DirNotExistsException, FileNotExistsException
+from automation_file.exceptions import FileNotExistsException
 from automation_file.logging_config import file_automation_logger
 from automation_file.remote._upload_tree import walk_and_upload
 from automation_file.remote.dropbox_api.client import dropbox_instance
@@ -46,19 +46,16 @@ def dropbox_upload_file(file_path: str, remote_path: str) -> bool:
 
 def dropbox_upload_dir(dir_path: str, remote_prefix: str = "/") -> list[str]:
     """Upload every file under ``dir_path`` to Dropbox under ``remote_prefix``."""
-    source = Path(dir_path)
-    if not source.is_dir():
-        raise DirNotExistsException(str(source))
-    prefix = remote_prefix.rstrip("/")
-    uploaded = walk_and_upload(
-        source,
-        lambda rel: f"{prefix}/{rel}" if prefix else f"/{rel}",
+    result = walk_and_upload(
+        dir_path,
+        remote_prefix,
+        lambda prefix, rel: f"{prefix}/{rel}" if prefix else f"/{rel}",
         lambda local, remote: dropbox_upload_file(str(local), remote),
     )
     file_automation_logger.info(
         "dropbox_upload_dir: %s -> %s (%d files)",
-        source,
-        prefix,
-        len(uploaded),
+        result.source,
+        result.prefix,
+        len(result.uploaded),
     )
-    return uploaded
+    return result.uploaded

automation_file/remote/http_download.py

@@ -78,7 +78,7 @@ def download_file(
 
     written = 0
     try:
-        with open(file_name, "wb") as output, _progress(total_size, file_name) as bar:
+        with open(file_name, "wb") as output, _progress(total_size, file_name) as progress:
             for chunk in response.iter_content(chunk_size=chunk_size):
                 if not chunk:
                     continue
@@ -90,7 +90,7 @@ def download_file(
                     )
                     return False
                 output.write(chunk)
-                bar.update(len(chunk))
+                progress.update(len(chunk))
     except OSError as error:
         file_automation_logger.error("download_file write error: %r", error)
         return False

automation_file/remote/s3/upload_ops.py

@@ -4,7 +4,7 @@
 
 from pathlib import Path
 
-from automation_file.exceptions import DirNotExistsException, FileNotExistsException
+from automation_file.exceptions import FileNotExistsException
 from automation_file.logging_config import file_automation_logger
 from automation_file.remote._upload_tree import walk_and_upload
 from automation_file.remote.s3.client import s3_instance
@@ -27,20 +27,17 @@ def s3_upload_file(file_path: str, bucket: str, key: str) -> bool:
 
 def s3_upload_dir(dir_path: str, bucket: str, key_prefix: str = "") -> list[str]:
     """Upload every file under ``dir_path`` to ``bucket`` under ``key_prefix``."""
-    source = Path(dir_path)
-    if not source.is_dir():
-        raise DirNotExistsException(str(source))
-    prefix = key_prefix.rstrip("/")
-    uploaded = walk_and_upload(
-        source,
-        lambda rel: f"{prefix}/{rel}" if prefix else rel,
+    result = walk_and_upload(
+        dir_path,
+        key_prefix,
+        lambda prefix, rel: f"{prefix}/{rel}" if prefix else rel,
         lambda local, key: s3_upload_file(str(local), bucket, key),
     )
     file_automation_logger.info(
         "s3_upload_dir: %s -> s3://%s/%s (%d files)",
-        source,
+        result.source,
         bucket,
-        prefix,
-        len(uploaded),
+        result.prefix,
+        len(result.uploaded),
     )
-    return uploaded
+    return result.uploaded