[IMPR} Add a post_processing attribute to UploadRobot

If this attribute is set to a callable, the run method calls it
after upload. The parameter passed to the callable is the origin file_url
passed to the upload method and the filename returned from that method.

- use this feature with imagetransfer  and use bot.run() mehtod instead
  of bot.upload_file()

Bug: T360837
Change-Id: I4a9c6182a87a601ce770ebb5e84c8898d2a4563d
---
M pywikibot/specialbots/_upload.py
M scripts/imagetransfer.py
M tests/uploadbot_tests.py
3 files changed, 75 insertions(+), 29 deletions(-)

diff --git a/pywikibot/specialbots/_upload.py b/pywikibot/specialbots/_upload.py
index ce8bd29..e34f601 100644
--- a/pywikibot/specialbots/_upload.py
+++ b/pywikibot/specialbots/_upload.py
@@ -3,7 +3,7 @@
 Do not import classes directly from here but from specialbots.
 """
 #
-# (C) Pywikibot team, 2003-2023
+# (C) Pywikibot team, 2003-2024
 #
 # Distributed under the terms of the MIT license.
 #
@@ -21,6 +21,7 @@
 import pywikibot
 import pywikibot.comms.http as http
 from pywikibot import config
+from pywikibot.backports import Callable
 from pywikibot.bot import BaseBot, QuitKeyboardInterrupt
 from pywikibot.exceptions import APIError, FatalServerError, NoPageError
 
@@ -29,6 +30,27 @@
 
     """Upload bot."""
 
+    post_processor: Callable[[str, str | None], None] | None = None
+    """If this attribute is set to a callable, the :meth:`run` method calls it
+    after upload. The parameter passed to the callable is the origin *file_url*
+    passed to the :meth:`upload` method and the filename returned from that
+    method. It can be used like this:
+
+    .. code:: python
+
+       def summarize(old: str, new: str | None) -> None:
+           if new is None:
+               print(f'{old} was ignored')
+           else:
+               print(f'{old} was uploaded as {new}')
+
+       bot = UploadRobot('Myfile.bmp')
+       bot.post_processor = summarize
+       bot.run()
+
+    .. versionadded:: 9.1
+    """
+
     def __init__(self, url: list[str] | str, *,
                  url_encoding=None,
                  description: str = '',
@@ -464,6 +486,8 @@
                 self.counter['read'] += 1
                 if filename:
                     self.counter['upload'] += 1
+                if callable(self.post_processor):
+                    self.post_processor(file_url, filename)
         except QuitKeyboardInterrupt:
             pywikibot.info(f'\nUser quit {type(self).__name__} bot run...')
         except KeyboardInterrupt:
diff --git a/scripts/imagetransfer.py b/scripts/imagetransfer.py
index eb4bf8c..7cf4836 100755
--- a/scripts/imagetransfer.py
+++ b/scripts/imagetransfer.py
@@ -37,7 +37,7 @@
 &params;
 """
 #
-# (C) Pywikibot team, 2004-2022
+# (C) Pywikibot team, 2004-2024
 #
 # Distributed under the terms of the MIT license.
 #
@@ -201,6 +201,34 @@
 
         :return: the filename which was used to upload the image
         """
+        def delete_source(old_filename, target_filename):
+            """Delete source image or tag nowCommons template to it.
+
+            This function is called when upload to Commons was
+            successful.
+            """
+            if not target_filename \
+               or self.opt.target.sitename != 'commons:commons':
+                return
+
+            reason = i18n.twtranslate(sourceSite,
+                                      'imagetransfer-nowcommons_notice')
+            # try to delete the original image if we have a sysop account
+            if sourceSite.has_right('delete') \
+               and sourceImagePage.delete(reason):
+                return
+
+            if sourceSite.lang in nowCommonsTemplate \
+               and sourceSite.family.name in config.usernames \
+               and sourceSite.lang in config.usernames[sourceSite.family.name]:
+                # add the nowCommons template.
+                pywikibot.info('Adding nowCommons template to '
+                               + sourceImagePage.title())
+                sourceImagePage.put(sourceImagePage.get() + '\n\n'
+                                    + nowCommonsTemplate[sourceSite.code]
+                                    % target_filename,
+                                    summary=reason)
+
         sourceSite = sourceImagePage.site
         pywikibot.info(
             '\n>>> Transfer {source} from {source.site} to {target}\n'
@@ -246,32 +274,8 @@
                               force_if_shared=self.opt.force_if_shared,
                               asynchronous=self.opt.asynchronous,
                               chunk_size=self.opt.chunk_size)
-
-            # try to upload
-            if bot.skip_run():
-                return
-            target_filename = bot.upload_file(url)
-
-            if target_filename \
-               and self.opt.target.sitename == 'commons:commons':
-                # upload to Commons was successful
-                reason = i18n.twtranslate(sourceSite,
-                                          'imagetransfer-nowcommons_notice')
-                # try to delete the original image if we have a sysop account
-                if sourceSite.has_right('delete') \
-                   and sourceImagePage.delete(reason):
-                    return
-                if sourceSite.lang in nowCommonsTemplate \
-                   and sourceSite.family.name in config.usernames \
-                   and sourceSite.lang in \
-                   config.usernames[sourceSite.family.name]:
-                    # add the nowCommons template.
-                    pywikibot.info('Adding nowCommons template to '
-                                   + sourceImagePage.title())
-                    sourceImagePage.put(sourceImagePage.get() + '\n\n'
-                                        + nowCommonsTemplate[sourceSite.lang]
-                                        % target_filename,
-                                        summary=reason)
+            bot.post_processor = delete_source
+            bot.run()
 
     def show_image_list(self, imagelist) -> None:
         """Print image list."""
diff --git a/tests/uploadbot_tests.py b/tests/uploadbot_tests.py
index 4bc255f..7bffec2 100755
--- a/tests/uploadbot_tests.py
+++ b/tests/uploadbot_tests.py
@@ -5,7 +5,7 @@
 These tests write to the wiki.
 """
 #
-# (C) Pywikibot team, 2014-2022
+# (C) Pywikibot team, 2014-2024
 #
 # Distributed under the terms of the MIT license.
 #
@@ -83,6 +83,7 @@
         self.assertTrue(bot._handle_warning('any warning'))  # ignore_warning
         self.assertTrue(bot.ignore_on_warn('any warning'))  # ignore_warning
         self.assertFalse(bot.abort_on_warn('any warning'))  # aborts
+        self.assertIsNone(bot.post_processor)
 
 
 if __name__ == '__main__':

