specialbots — Special Reusable Bots#

Module containing special bots reusable by scripts.

class specialbots.BaseUnlinkBot(**kwargs)[source]#

Bases: ExistingPageBot, AutomaticTWSummaryBot

A basic bot unlinking a given link from the current page.

Redirect all parameters and add namespace as an available option.

Unlink all links linking to the target page.

Return type:


use_redirects: bool | None = False#

Attribute to determine whether to use redirect pages. Set it to True to use redirects only, set it to False to skip redirects. If None both are processed. For example to create a RedirectBot you may define:

class MyRedirectBot(ExistingPageBot):

    '''Bot who only works on existing redirects.'''

    use_redirects = True

Added in version 7.2.

Bases: InteractiveReplace

An implementation which just allows unlinking.

Create default settings.


Handle choice and store in bot’s options.

class specialbots.UploadRobot(url, *, url_encoding=None, description='', use_filename=None, keep_filename=False, verify_description=True, ignore_warning=False, target_site=None, aborts=None, chunk_size=0, asynchronous=False, summary=None, filename_prefix=None, force_if_shared=False, **kwargs)[source]#

Bases: BaseBot

Upload bot.

Changed in version 6.2: asynchronous upload is used if asynchronous parameter is set

Changed in version 6.4: force_if_shared parameter was added

  • url (list[str] | str) – path to url or local file, or list of urls or paths to local files.

  • description (str) – Description of file for its page. If multiple files are uploading the same description is used for every file.

  • use_filename – Specify title of the file’s page. If multiple files are uploading it asks to change the name for second, third, etc. files, otherwise the last file will overwrite the other.

  • keep_filename (bool) – Set to True to keep original names of urls and files, otherwise it will ask to enter a name for each file.

  • summary (str | None) – Summary of the upload

  • verify_description (bool) – Set to True to proofread the description.

  • ignore_warning (bool | list) – Set this to True to upload even if another file would be overwritten or another mistake would be risked. Set it to an array of warning codes to selectively ignore specific warnings.

  • target_site (object) – Set the site to upload to. If target site is not given it’s taken from user config file (user-config.py).

  • aborts (bool | list | None) – List of the warning types to abort upload on. Set to True to abort on any warning.

  • chunk_size (int) – Upload the file in chunks (more overhead, but restartable) specified in bytes. If no value is specified the file will be uploaded as whole.

  • asynchronous (bool) – Make potentially large file operations asynchronous on the server side when possible.

  • filename_prefix (str | None) – Specify prefix for the title of every file’s page.

  • force_if_shared (bool) – Upload the file even if it’s currently shared to the target site (e.g. when moving from Commons to another wiki)

Keyword Arguments:

always (bool) – Disables any input, requires that either ignore_warning or aborts are set to True and that the description is also set. It overwrites verify_description to False and keep_filename to True.


Determine if the warning message should cause an abort.


Determine if the warning message should be ignored.


warn_code (str) – The warning message

post_processor: Callable[[str, str | None], None] | None = None#

If this attribute is set to a callable, the run() method calls it after upload. The parameters passed to the callable is the origin file_url passed to the upload() method and the filename returned from that method. It can be used like this:

def summarize(old: str, new: str | None) -> None:
    if new is None:
        print(f'{old} was ignored')
        print(f'{old} was uploaded as {new}')

bot = UploadRobot('Myfile.bmp')
bot.post_processor = summarize

Added in version 9.1.


Return base filename portion of file_url.


file_url (str) – either a URL or a local file path

Return type:

str | None


Return name of temp file in which remote file is saved.


file_url (str)


Run bot.

Changed in version 9.1: count uploads.


Check whether processing is to be skipped.

Return type:



Upload the image at file_url to the target wiki.

See also


Return the filename that was used to upload the image. If the upload fails, ask the user whether to try again or not. If the user chooses not to retry, return None.

Changed in version 7.0: If ‘copyuploadbaddomain’ API error occurred in first step, download the file and upload it afterwards


file_url (str) – either a URL or a local file path

Return type:

str | None