pwb-wrapper-for-simpler-uploading-to-commons 0.3.1
CLI wrapper around Pywikibot for simpler Wikimedia Commons uploads
Requires Python: >=3.9
Keywords: wikimedia, commons, pywikibot, upload, cli

It is a wrapper around [pywikibot](https://github.com/wikimedia/pywikibot) to make uploading to Wikimedia Commons from CLI simpler.

## Install

From [PyPI](https://pypi.org/project/pwb-wrapper-for-simpler-uploading-to-commons/):

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

With shell autocompletion support:

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

## Usage

Installed CLI command:

```bash
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`:

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

Default `source` is `{{own}}`.

Default `license` is `cc-by-4.0`.

`--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:

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

Or pass the file as positional argument:

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

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

```bash
pwb-upload my.jpg
```

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

To include subfolders:

```bash
pwb-upload --recursive
```

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

```bash
./upload.py --file my.jpg
```

Author: for the current user use `me`.

## Autocompletion

Enable completion for the installed command:

```bash
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):

```bash
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:

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

Build distribution files:

```bash
python3 -m build
```

Upload to TestPyPI:

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

Upload to PyPI:

```bash
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](https://gitlab.com/vitaly-zdanevich/upload_to_commons_with_categories_from_iptc)

My [web extension for uploading to Commons](https://gitlab.com/vitaly-zdanevich-extensions/uploading-to-wikimedia-commons)

[All upload tools](https://commons.wikimedia.org/wiki/Commons:Upload_tools)

[CLI upload tools](https://commons.wikimedia.org/wiki/Commons:Command-line_upload)