pwb-wrapper-for-simpler-uploading-to-commons 1.4.0

CLI wrapper around Pywikibot for simpler Wikimedia Commons uploads

It is a wrapper around pywikibot to make uploading to Wikimedia Commons from CLI simpler.

Install

From PyPI:

pip install pwb-wrapper-for-simpler-uploading-to-commons

With shell autocompletion support:

pip install 'pwb-wrapper-for-simpler-uploading-to-commons[autocomplete]'

Usage

Installed CLI command:

pwb-upload --file my.jpg --source https://example.com --license 'PD-old' --category 'Sunsets in Batumi' --date '2025-12-27' --desc 'A beautiful sunset from the beach' --target myrenamed.jpg

For multiple categories, repeat --category:

pwb-upload --file my.jpg --category 'Sunsets in Batumi' --category 'Evening in Georgia' --date '2025-12-27'

Use folder name in category:

pwb-upload --category "Kaspiy ${PWD##*/}" --license 'PD-scan|PD-old-assumed-expired' --source https://dspace.nplg.gov.ge/handle/1234/387883 --dateParse

Default source is {{own}}.

Default license is cc-by-4.0.

--author for example [[User:Globustut|Globustut]]

--date in format YYYY-MM-DD.

--dateParse extracts year from a filename (1xxx or 2xxx).

--date and --dateParse are mutually exclusive.

--target (file name on Commons) is optional.

--prefix (prefix for file name on Commons) is optional.

--i lets you start from a specific index.

--recursive includes files from subfolders when no file is specified.

You can upload with minimal arguments:

pwb-upload --file my.jpg --category 'Sunsets in Batumi' --date '2025-12-27'

Or pass the file as positional argument:

pwb-upload my.jpg --category 'Sunsets in Batumi' --date '2025-12-27'

Or upload without category, date, and dateParse (set them later on Commons):

pwb-upload my.jpg

If no file is specified, it uploads eligible files from the current folder (no subfolders by default):

pwb-upload --category 'My category' --author '[[User:Globustut|Globustut]]' --license 'self|CC-BY-4.0|author=Globustut' --date 2005

To include subfolders:

pwb-upload --recursive

For local development (without installation), you can still run:

./upload.py --file my.jpg

Author: for the current user use me.

Autocompletion

Enable completion for the installed command:

eval "$(register-python-argcomplete pwb-upload)"

Release to PyPI

Release scripts in this repository:

• release_minor.sh bumps x.y.z -> x.(y+1).0
• release_patch.sh bumps x.y.z -> x.y.(z+1)
• release-added.sh uses already staged files and already bumped version in pyproject.toml (no git add .)

Call them from git (one-time setup):

git config alias.release-minor '!f() { repo=$(git rev-parse --show-toplevel) && bash "$repo/release_minor.sh" "$@"; }; f'
git config alias.release-patch '!f() { repo=$(git rev-parse --show-toplevel) && bash "$repo/release_patch.sh" "$@"; }; f'
git config alias.release-added '!f() { repo=$(git rev-parse --show-toplevel) && bash "$repo/release-added.sh" "$@"; }; f'

Then run:

git release-minor 'Release message'
git release-patch 'Release message'
git release-added 'Release message'

Build distribution files:

python3 -m build

Upload to TestPyPI:

python3 -m twine upload --repository testpypi dist/*

Upload to PyPI:

python3 -m twine upload dist/*

Wikidata item about this tool https://www.wikidata.org/wiki/Q137601716

Commons category https://commons.wikimedia.org/wiki/Category:Uploaded_with_pwb_wrapper_script_by_Vitaly_Zdanevich

SonarCloud https://sonarcloud.io/project/overview?id=vitaly-zdanevich_pwb_wrapper_for_simpler_uploading_to_commons

See also

My another Python script for uploading to Commons from gThumb

My web extension for uploading to Commons

All upload tools

CLI upload tools