credit-check 1.1.0__tar.gz

credit_check-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Dixit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

credit_check-1.1.0/PKG-INFO

@@ -0,0 +1,433 @@
+Metadata-Version: 2.4
+Name: credit-check
+Version: 1.1.0
+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 Commons files you photographed that are used 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 command-line 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
+git clone https://github.com/incandescentman/credit-check.git
+cd credit-check
+pipx install .                # adds the `credit-check` command
+credit-check                  # start the guided app, then follow the prompts
+#+end_src
+
+That's it. Credit Check walks you through the rest: set up your Commons account
+once, find your photos, pick the ones to add, and add them to your category.
+
+* 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.
+- =questionary= and =prompt_toolkit=, installed automatically from
+  =pyproject.toml=, for guided menus and the optional terminal review.
+- A Wikimedia Commons account (to make edits).
+
+Check your Python:
+
+: python3 --version
+
+* Install
+
+Clone the repository and install it with pipx:
+
+: git clone https://github.com/incandescentman/credit-check.git
+: cd credit-check
+: pipx install .
+
+Now =credit-check= runs from anywhere. If you plan to modify the code, use
+=pipx install --editable .= instead, so the command tracks your checkout.
+
+Prefer not to install? Just run the script directly, using =python3 credit_check.py=
+in place of =credit-check= throughout this guide. Direct script mode still
+works without those interactive dependencies for direct commands and browser
+review, but guided menus and terminal review need them; the installed
+=credit-check= command has them.
+
+* Start
+
+Start the guided command-line app:
+
+: credit-check
+
+If this is your first run, it starts with setup: 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 a scan, it opens the browser photo picker instead of asking you which file
+to use. The
+Settings action saves your Commons username, credited name, and photographer
+category in [[file:.credit-check.json][.credit-check.json]] for this folder, so you do not have to
+re-enter them.
+
+* Making edits: the bot password
+
+Editing needs a login. Don't use your main password. Create a bot password, a
+scoped, revocable credential:
+
+1. Go to https://commons.wikimedia.org/wiki/Special:BotPasswords
+2. Create one (name it something like =categorize=). Grant *Edit existing pages*.
+3. You'll get a username like =Jaydixit@categorize= and a generated password.
+
+Give them to Credit Check by environment variable:
+
+: export COMMONS_BOTUSER='Jaydixit@categorize'
+: export COMMONS_BOTPASS='the-generated-password'
+
+If you skip this, =commit --go= will prompt you for them.
+
+* Finding photos that depict you
+
+Credit Check only files photos you took — a portrait someone else shot won't be
+filed under "Photographs by you." For photos of you taken by other people, choose
+=Find photos of you by other people= in the guided app; Credit Check looks up
+matching Wikidata items so you can pick yourself, or skip cleanly if none of them
+are you. If you use direct
+commands and have a Wikidata item, point the tool at it:
+
+: credit-check scan --of-category 'Jay Dixit' --qid Q12345
+
+Files that Commons structured data says depict you (and that you didn't shoot)
+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
+
+- *"Missing --username (or WIKI_USERNAME)"*: set your identity (see Environment
+  variables and config).
+- *"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 or re-run the plan before trying again.
+- *"Login failed"*: check your bot password, and that you granted it "Edit
+  existing pages."
+- *A scan 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: get your
+Wikipedia-used photos into your 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 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.
+
+** 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.
+
+** Environment variables and config
+
+Set your identity once. Put this in your shell profile if you like:
+
+: export WIKI_USERNAME='Jaydixit'        # your Commons account
+: export WIKI_AUTHOR='Jay Dixit'         # your name as it appears in author fields
+
+That's enough to start. 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
+
+You can also pass any of these as flags (=--username=, =--author=, and so on),
+which override the environment.
+
+Markdown is the default review format. To use org-mode in this folder, create
+[[file:.credit-check.json][.credit-check.json]]:
+
+: {"review_format": "org"}
+
+You can also use that file for advanced defaults. Most people should never need
+these:
+
+#+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 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.
+
+** Command-line workflow
+
+*** 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=. Before editing, =commit --go= checks again and skips
+any page where the category is already present.
+
+The guided scan does not ask you to filter by popularity. It uses the normal
+default: any photo live on at least one Wikipedia article is eligible. It also
+keeps crop tracing on by default, following up to two source links so a
+crop-of-a-crop can still be connected to your original. In the guided app, scan
+then opens the browser review automatically.
+
+*** 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   |