Utility scripts#

Folder which holds framework scripts.

When uploading pywikibot to pypi the pwb.py (wrapper script) and pywikibot i18n package are copied here.

New in version 7.0.

pwb wrapper script#

Wrapper script to invoke pywikibot-based scripts.

This wrapper script invokes script by its name in this search order:

  1. Scripts listed in user_script_paths list inside your user-config.py settings file in the given order. Refer External Script Path Settings.

  2. User scripts residing in scripts/userscripts (directory mode only).

  3. Scripts residing in scripts folder (directory mode only).

  4. Maintenance scripts residing in scripts/maintenance (directory mode only).

  5. Framework scripts residing in pywikibot/scripts.

This wrapper script is able to invoke scripts even if the script name is misspelled. In directory mode it also checks package dependencies.

Run scripts with pywikibot in directory mode using:

python pwb.py <pwb options> <name_of_script> <options>

or run scripts with pywikibot installed as a site package using:

pwb <pwb options> <name_of_script> <options>

This wrapper script uses the package directory to store all user files, will fix up search paths so the package does not need to be installed, etc.

Currently, <pwb options> are Global Options. This can be used for tests to set the default site (see T216825):

python pwb.py -lang:de bot_tests -v

Changed in version 7.0: pwb wrapper was added to the Python site package lib

generate_family_file script#

This script generates a family file from a given URL.

This script must be invoked with the pwb wrapper script/code entry point.


pwb generate_family_file.py [<url>] [<name>] [<dointerwiki>] [<verify>]

Parameters are optional. They must be given consecutively but may be omitted if there is no successor parameter. The parameters are:

<url>:         an url from where the family settings are loaded
<name>:        the family name without "_family.py" tail.
<dointerwiki>: predefined answer (y|n) to add multiple site codes
<verify>:      disable certificate validaton `(y|n)


pwb generate_family_file.py https://www.mywiki.bogus/wiki/Main_Page mywiki

This will create the file mywiki_family.py in families folder of your base directory.

Changed in version 7.0: moved to pywikibot.scripts folder; create family files in families folder of your base directory instead of pywikibot/families.

generate_user_files script#

Script to create user-config.py.

Changed in version 7.0: moved to pywikibot.scripts folder

login script#

Script to log the bot in to a wiki account.

Suggestion is to make a special account to use for bot use only. Make sure this bot account is well known on your home wiki before using.

The following parameters are supported:

-family:FF   Log in to the LL language of the FF family.
-lang:LL     Example: -family:wiktionary -lang:fr will log you in at

-site:FF:LL  Log in to the LL language of the FF family

-all         Try to log in on all sites where a username is defined in

-logout      Log out of the current site. Combine with -all to log out of
             all sites, or with -family and -lang to log out of a specific

-oauth       Generate OAuth authentication information.

             .. note:: Need to copy OAuth tokens to your user-config.py
                manually. -logout is not compatible with -oauth.

-autocreate  Auto-create an account using unified login when necessary.

             .. note:: the global account must exist already before
                using this.

If not given as parameter, the script will ask for your username and password (password entry will be hidden), log in to your home wiki using this combination, and store the resulting cookies (containing your password hash, so keep it secured!) in a file in the data subdirectory.

All scripts in this library will be looking for this cookie file and will use the login information if it is present.

To log out, throw away the *.lwp file that is created in the data subdirectory.

Changed in version 7.4: moved to pywikibot.scripts folder

preload_sites script#

Script that preloads site and user info for all sites of given family.

The following parameters are supported:

-worker:<num> The number of parallel tasks to be run. Default is the

number of processors on the machine


python pwb.py preload_sites [{<family>}] [-worker:{<num>}]

To force preloading, change the global expiry value to 0:

python pwb.py -API_config_expiry:0 preload_sites [{<family>}]

Changed in version 7.4: script was moved to the framework scripts folder.

shell script#

Spawns an interactive Python shell and imports the pywikibot library.

The following local option is supported:

-noimport Do not import the pywikibot library. All other arguments are
          ignored in this case.


python pwb.py shell [args]

Changed in version 7.0: moved to pywikibot.scripts

version script#

Script to determine the Pywikibot version (tag, revision and date).

Changed in version 7.0: version script was moved to the framework scripts folder