Metadata-Version: 2.4
Name: credit-check
Version: 1.1.6
Summary: Keep track of which Wikipedia articles use your photos.
Author-email: Jay Dixit <jay@wikiportraits.org>
License: MIT
Keywords: wikimedia,commons,wikipedia,photography,categories,attribution,glam
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Description-Content-Type: text/plain
License-File: LICENSE
Requires-Dist: prompt_toolkit<4,>=3
Requires-Dist: questionary<3,>=2
Dynamic: license-file

#+TITLE: Credit Check

/Find and track which of your photos are being featured on Wikipedia/

[[https://img.shields.io/badge/License-MIT-2e7d4f.svg]]
[[https://img.shields.io/badge/Python-3.8%2B-3776ab.svg]]
[[https://img.shields.io/badge/from-WikiPortraits-0e6b45.svg]]

Credit Check is a free guided tool from WikiPortraits for Wikimedia Commons
photographers. It searches Wikipedia to find the articles that feature your
photos, then adds those photos (or a subset you pick) to a category page on
Wikimedia Commons — using a category name like =Photographs by Jay Dixit= — so
you can easily keep track of which Wikipedia articles use your photos.

#+ATTR_HTML: :alt Credit Check screenshot showing selected Wikimedia Commons photos, Wikipedia usage, and a photographer category :width 100%
[[file:assets/credit-check-hero.jpeg]]

* Quick start

#+begin_src sh
pipx install credit-check     # or: pip install credit-check
credit-check                  # start the guided app, then follow the prompts
#+end_src

Credit Check walks you through the rest: save your Commons details once, find
your photos, pick the ones to add, and add them to your photographer category.

* Why this exists

If you're a Wikimedia Commons photographer, chances are some of your photos are
already being used on Wikipedia — maybe dozens or hundreds of them, across
articles in languages you don't even read. But there's no easy way to see, at a
glance, all the Wikipedia pages that use your photos.

The standard fix is to gather your photos into a Commons category — something
like =Photographs by Jay Dixit= — so they all live at one URL you can track, and
one page where other editors can find more of your work. But if you're like many
Wikipedia photographers, with hundreds of photos scattered across articles in
dozens of languages, adding each one by hand is slow, tedious work.

Credit Check automates it. It finds the photos you took that Wikipedia uses,
and adds the ones you pick to your photographer category — so
you can finally see, in one place, where your photos are used on Wikipedia.

I made this for my fellow WikiPortraits photographers. We're all volunteers, and
our photos end up all over Wikipedia — I just wanted an easy way for us to
collect our photo credits and see where our work is used. That's why I built
Credit Check.

* What it does

1. *Finds likely candidates.* Your uploads, plus any file whose
   author/photographer field credits you. Uploading alone does not make a file
   count as your photo.
2. *Checks Wikipedia.* Keeps only files used on live Wikipedia articles, across
   every language edition.
3. *Spots the gaps.* Flags the ones missing =Category:Photographs by <you>=.
4. *Traces crops.* If a crop dropped your credit but still cites your original
   file as its source, Credit Check follows the trail back and includes it too.
5. *You select* which photos to add to your photographer category.

* Requirements

- Python 3.8 or newer.
- The guided app dependencies, installed automatically with Credit Check.
- A Wikimedia Commons account (to make edits).

* Install

Install from PyPI with pipx:

: pipx install credit-check

=credit-check= runs from anywhere. (=pip install credit-check= works too.)

Advanced installation options are covered in the Reference section below.

* Start

Start the guided app:

: credit-check

If this is your first run, it asks for the details it needs: your Commons
username, your credited name, and your photographer category. After that, it
shows where you're up to and offers the obvious next step first: find your
photos, choose photos to add, or add the photos you picked. A separate optional
action is always available for photos of you taken by other people; it looks up
matching Wikidata items by your name when you choose it.

In guided mode, Credit Check keeps track of the found photos automatically.
After it searches, it opens the browser photo picker automatically. The Settings
action saves your Commons username, credited name, and photographer category for
this folder, so you do not have to re-enter them. To use the same folder for
someone else, choose =Start over with a different photographer=; it clears saved
details and the photos found so far, then asks for the new photographer and
searches again.

* Making edits: the bot password

Editing needs a login. Don't use your main password. Create a bot password, a
scoped, revocable app password for your own Commons account:

1. Go to https://commons.wikimedia.org/wiki/Special:BotPasswords
2. Log in there with your normal Wikimedia Commons username and password.
3. Commons will prompt you to create a bot password. Name it something like
   =categorize=.
4. Grant *Edit existing pages*.
5. You'll get a username like =Jaydixit@categorize= and a generated password.
6. Come back to Credit Check and enter that generated username and password.

That generated username is not a separate Commons account. It is your account
plus a suffix that names this credential. A login like =Jaydixit@categorize=
still edits as =Jaydixit=, and Credit Check does not upload files or change who
uploaded them; it only edits existing file pages to add categories.

The point is to avoid giving any tool your main Commons password. If this
credential ever leaks, you can revoke or reset just this bot password.

* Finding photos that depict you

Credit Check's main flow is for photos you took. It also has an additional
feature for photos of you taken by other people: choose =Find photos of you by
other people= in the guided app, and Credit Check looks up matching Wikidata
items so you can pick yourself or skip cleanly if none of them are you. Files
that Commons structured data says depict you land in their own section. If you
pick them, Credit Check adds them to your category for photos of you.

* Good Commons manners

Credit Check is built to be careful on Commons:

- Nothing is edited unless you pick it and confirm. Preview is the default.
- It appends only. It never rewrites a page, reorders categories, or touches
  license, author, or description fields.
- It re-checks every file right before editing, so it won't add a duplicate.
- It pauses between edits and backs off while fetching or logging in if
  Commons asks it to slow down.
- It doesn't automatically resubmit an edit after a lost network response; it
  reports that file as failed so you can re-run safely after checking the page.
- Every edit carries a transparent summary naming the category it added.

If you're about to categorize hundreds of files, that's a semi-automated batch.
Skim the Commons norms for that kind of work, and if you're doing it regularly,
consider whether a bot flag or a quick note to the community is warranted. For a
one-time cleanup of your own photos, a normal login is generally fine.

* When something goes wrong

- *Credit Check says details are missing*: choose =Settings= and enter your Commons
  username, credited name, and photographer category.
- *"rate-limited, waiting Ns..."*: normal. Commons throttled you; the tool
  waits and retries discovery, fetch, and login requests on its own.
- *"! failed (network)"*: the edit response was lost or failed. The tool did
  not resubmit the edit automatically, to avoid double-appending a category.
  Check the file page, then try adding the selected photos again.
- *"Login failed"*: check the generated bot-password username and password, and
  that you granted it "Edit existing pages."
- *A search feels slow*: it's fetching usage and wikitext for hundreds of
  files. Let it run; it prints progress as it goes.

* What it won't do

It won't upload files, edit Wikipedia articles, rewrite your metadata, or add
event or location categories. Its job is narrow on purpose: find photos
you've taken that appear on Wikipedia and add them to your Wikimedia
Commons photographer category.

* The payoff

When you're done, your work is collected at one URL you can point anyone to:

: https://commons.wikimedia.org/wiki/Category:Photographs_by_Jay_Dixit

If your photo is on Wikipedia and Commons already credits you, Credit Check
makes sure it shows up in your photographer category.

* About WikiPortraits

WikiPortraits is a global network of volunteer photographers on a mission to
deliver high-quality, freely licensed portraits to
[[https://en.wikipedia.org/wiki/Main_Page][Wikipedia]],
[[https://commons.wikimedia.org/wiki/Main_Page][Wikimedia Commons]], and the
world.

Wikipedia and its sister Wikimedia projects require freely licensed images, but
most published photos of notable people are press shots under full copyright, so
countless biographies are stuck with low-quality photos or none at all.
WikiPortraits changes that: our volunteer photographers go where notable people
gather — film festivals, conferences, and award ceremonies — often as
credentialed press. At many events we also run a photo booth, where anyone with
a Wikipedia page, speaker or not, can drop by for a portrait. Every shot is
freely licensed, uploaded to Wikimedia Commons, and free for the world to use.

Since our first shoot at Sundance in 2024, our portraits have reached Wikipedia
articles in over 150 languages, viewed more than 150 million times a month.
Among the events our photographers have captured: Sundance Film Festival, SXSW,
Cannes Film Festival, Edinburgh Festival Fringe, Venice Film Festival, Toronto
International Film Festival, the Nobel Prizes, CES, and the Pulitzer Prizes.

* Author

Credit Check was built by Jay Dixit ([[mailto:jay@wikiportraits.org][jay@wikiportraits.org]]).

* Reference

The guided =credit-check= app covers everything above. The sections below are
for scripting and power users who want to run each step by hand.

** Install alternatives

Prefer to run from source? Clone the repo and install it instead:

: git clone https://github.com/incandescentman/credit-check.git
: cd credit-check
: pipx install .

Add =--editable= if you plan to modify the code.

Prefer not to install? Run the script directly, using =python3 credit_check.py=
in place of =credit-check= for the direct commands below. Direct script mode
works for direct commands and browser review; guided menus and terminal review
need the packaged dependencies that the installed =credit-check= command has.

** Check the tool

Run local parser and review-format checks:

: credit-check self-test

Run a read-only Commons smoke test:

: credit-check smoke

Neither command edits Commons.

** Command-line workflow

For advanced users, Credit Check also supports direct commands for each step of
the workflow. This is useful for scripting, debugging, custom review files, or
running one stage at a time. If you just want the normal experience, run
=credit-check= and use the guided app instead.

*** Optional shortcuts for direct-command users

The guided app already collects the ordinary details it needs and saves them for
this folder. You do not need environment variables for the normal flow.

If you're scripting direct commands, you can provide the same identity values as
flags (=--username=, =--author=, and so on) or as environment variables:

: export WIKI_USERNAME='Jaydixit'        # your Commons account
: export WIKI_AUTHOR='Jay Dixit'         # your name as it appears in author fields

Optional extras:

: export WIKI_BY_CATEGORY='Photographs by Jay Dixit'   # defaults to "Photographs by <author>"
: export WIKI_OF_CATEGORY='Jay Dixit'                  # category for photos of you
: export WIKI_QID='Q12345'                             # your Wikidata id, enables depicts detection

Direct-command users can also put advanced defaults in
[[file:.credit-check.json][.credit-check.json]]. This is optional; the guided app
manages ordinary settings for you.

#+begin_src json
{
  "review_format": "org",
  "review_page_size": 20,
  "min_uses": 1,
  "english_only": false,
  "match_user_page_source": true,
  "trace_derivatives": true,
  "source_depth": 2
}
#+end_src

What those advanced preferences mean:

- =min_uses= is a priority filter. The default =1= means "include any photo
  live on at least one Wikipedia article." Raise it only if you want to review
  the most-used photos first.
- =match_user_page_source= also searches for file text that names
  =User:<username>=. Credit Check already checks uploads and author/photographer
  fields; this catches edge cases where a file credits your Commons user page
  instead of your real name. It is on by default because the authorship check
  still has to confirm the author/photographer field before anything goes into
  your photographer category.
- =source_depth= controls crop tracing. A hop is one step from a crop back to
  the file it came from. The default =2= covers an original and a crop-of-a-crop
  without following long source chains.

*** 1. Scan

: credit-check scan

This searches Commons, checks Wikipedia usage, classifies each file, and writes
=review.md=. It prints a summary when it finishes, for example:

: by  (photos you took, missing [[Category:Photographs by Jay Dixit]]): 207 photos, used 1480 times
: ambiguous (authorship or category unclear): 0 photos

The scan only puts photos in the review when they are missing the category it
would add. If one of your photos is already in your photographer category, it is
left out of =review.md=. When you run the direct =commit --go= step, Credit
Check checks again and skips any page where the category is already present.

By default, any photo live on at least one Wikipedia article is eligible. Crop
tracing is on by default too, following up to two source links so a
crop-of-a-crop can still be connected to your original.

*** 2. Review and pick photos

Open the local browser picker:

: credit-check review review.md

It opens a contact sheet at =127.0.0.1= with Commons thumbnails, category
sections, search, review modes (=All=, =Selected=, and =Not selected yet=),
select-shown/select-all buttons, and links that open each file on Commons.
Selected photos get a visible badge and left stripe so you can scan the page
quickly. The =Commons edits= panel updates automatically with the exact category
edits for the photos you picked. The page saves your choices automatically. Use
=Done= when you are finished.

Browser shortcuts:

- =/= focuses search.
- =Space= toggles the focused photo.
- =o= opens the focused photo on Commons.

To open the browser directly in selected-only mode:

: credit-check review --selected review.md

If Credit Check cannot open a browser from the current terminal, it falls back
to the keyboard-only reviewer. If the review file contains ambiguous photos,
the browser shows a count for them, but does not let you select them until you
move them under a real category heading in =review.md=.

Prefer the keyboard-only terminal reviewer?

: credit-check review --terminal review.md

The terminal reviewer shows one page of photos at a time, with hotkeys visible
at the top of the screen:

- =Space= toggles the highlighted photo.
- Arrow keys move through the list.
- =n= and =p= move to the next or previous page.
- =m= selects the current page; =c= clears the current page.
- =a= selects all photos; =u= clears all photos.
- =o= opens the highlighted photo on Commons.
- =g= opens the current page as a read-only browser gallery.
- =v= opens the full review as a read-only browser gallery.
- =s= saves your choices; =q= quits without saving.

Both review modes edit the same plain Markdown file, so you can still inspect
or edit it directly.

=review.md= is split into sections, one per category, plus an Ambiguous section
for anything unclear:

: # Add to [Category:Photographs by Jay Dixit] - photos you took (207)
: ## [148] Jessie Buckley ... (Cropped & Centered).jpg
:
: - [ ] File:Jessie Buckley ... (Cropped & Centered).jpg
:   [open on Commons](https://commons.wikimedia.org/...) - uploader Indopug - credited
:   cats: Jessie Buckley, WikiPortraits at 2025 TIFF
:   live: en, af, ar, az, bg, bn, ca, da, +29

The number in brackets is how many Wikipedia articles use that photo, sorted
most-used first. The browser and terminal reviewers toggle those =[X]= marks
for you. If you edit the file by hand, tick =[X]= on the files you want to
categorize and leave =[ ]= to skip.

Two things worth knowing:

- Each =# Add to [Category:...]= heading sets the category for the photos under
  it. Move a photo to a different section and it goes to that category instead.
- Files under =# Ambiguous= are skipped until you move them under a real heading
  and tick them.

*** 3. Plan

This never logs in — it just prints the edits it would make:

: credit-check plan review.md

The browser review shows the same edits live as you pick photos.

*** 4. Commit

When the plan looks right, make the edits:

: credit-check commit review.md --go

Credit Check logs in, re-checks each file (skipping any already categorized),
and appends the category with a clear edit summary, pausing a few seconds
between edits. When it finishes, it shows how many photos were added, already
present, or failed, links to the category page, and tells you whether any
photos you did not select remain.

** All options

On =scan=:

| Option              | What it does                                              |
|---------------------+----------------------------------------------------------|
| =--english-only=    | Only count English Wikipedia usage                       |
| =--min-uses N=      | Only flag photos on at least N articles                  |
| =--of-category '<name>'= | Also collect photos of you in this category        |
| =--qid Q12345=      | Use Wikidata "depicts" to find photos of you             |
| =--insource-user=   | Also match files whose source names your user page |
| =--no-insource-user= | Skip that user-page source search                 |
| =--no-derivatives=  | Skip crop/source-chain tracing                           |
| =--depth N=         | How many source hops to follow (default 2)               |
| =--review-format FMT= | One-run override for =markdown= or =org=               |
| =--out FILE=        | Write the review somewhere other than =review.md=        |

On =commit=:

| Option           | What it does                                     |
|------------------+--------------------------------------------------|
| =--go=           | Actually edit (default is preview only)          |
| =--throttle S=   | Seconds to pause between edits (default 5)       |
| =--summary '...'= | Custom edit summary                             |

Other commands:

| Command            | What it does                                      |
|--------------------+---------------------------------------------------|
| =self-test=        | Runs local parser and review-format checks        |
| =smoke=            | Runs a read-only Commons smoke test               |
| =interactive=      | Starts the guided command-line app                |
| =review REVIEW=    | Opens the local browser picker for your photos    |
| =review --selected REVIEW= | Opens the browser filtered to photos you selected |
| =web REVIEW=       | Same browser picker, kept as an explicit alias    |
| =plan REVIEW=      | Prints planned edits for the photos you checked   |
