Manual:Pywikibot/Workshop Materials/How to run basic scripts

This page is designed as a resource for workshop organizers who want to run a workshop about basic Pywikibot scripts. By following the instructions on this page, you will learn everything you need to know to teach others about this subject. This page features a complete script based on a past workshop, and provides many useful tips for people with little experience running such events.

Note that you do not need to follow this guide to the letter. Feel free to adapt it to your needs, and contribute back to it based on your experience.

If you want to learn more about this subject before committing to running a workshop, or need more concise materials, see User:KBach-WMF/Sandbox/SWT Workshop Materials/How to run a basic script via Pywikibot (self-study).

TODO: Link to any general tips and tricks for workshop organizers if they exist somewhere.

How to use this guide?
Read the guide in its entirety to determine if the content of this workshop matches your expectations. Change whatever you feel does not match your style or is not interesting for your audience.

Next, read the relevant linked materials to make sure you know everything you need to run this workshop.

Finally, prepare for the workshop by going through the section.

Requirements
To successfully run this workshop you should know how to run scripts included with Pywikibot. This means basic familiarity with Python, Pywikibot, your terminal or command line of choice, and PAWS.

Organizer
To prepare for this workshop, follow the steps below.


 * 1) Prepare a local Pywikibot environment for the  part of the workshop.
 * 2) * Make sure that Pywikibot and its scripts are available on your local environment. The best way to do this is to download the code from the Pywikibot repository as described on Manual:Pywikibot/Installation. You will then be able to run pywikibot from the core directory by calling . The rest of this page assumes you have used this method of installing Pywikibot.
 * 3) * Run, select the wiki you want to use for your demonstrations. In this workshop we recommend working with https://test.wikimedia.org, which you can select by picking ```wikipedia```, followed by the ```test``` site code. Provide your user credentials if you prefer.
 * 4) * Pick a categories and pages on the test Wikipedia that you will use to present how to manage categories and pages. Read through the instructions on this page first and then select the best categories and pages for your presentation. Create new ones if necessary.
 * 5) Prepare the PAWS environment for the  part of the workshop.
 * 6) * Create or upload a page file that you will use when presenting how to create a new page from file.
 * 7) Make the following decisions on how you want to run the workshop.
 * 8) * Do you want the participants to follow along and perform the described activities immediately as you talk about them, or wait until a designated time to perform the activities?
 * 9) * Do you want the participants to interrupt you to ask questions, or wait for the designated time instead?
 * 10) * Do you want to record the workshop? If so, ask the participants if they consent to being recorded.
 * 11) Share your decisions during the introduction to the workshop.
 * 12) Consider if there are any prerequisites or preparations required from the participants and share them before the workshop.

Participants
Be sure to inform workshop participants about the following points they need to consider to prepare for this workshop.


 * To run Pywikibot scripts locally, participants must have Pywikibot installed. For information on how to do this, see Manual:Pywikibot, other small wiki toolkits workshops (see small wiki toolkits workshops), and other self-study guides (TODO).
 * To run Pywikibot scripts on PAWS, participants need a Wikipedia/SUL account. They can create it on any Wikipedia page.

Workshop script
Start sharing your screen, ensure the recording is enabled if you planned to record.

Introduce yourself and the topic of the workshop. Explain the organizational choices and rules you've decided upon (for example, whether the participants should ask questions immediately or later, try to follow along or not - see for details).

Present the agenda of the workshop, outlining what scripts you will run and how. Talk about the purpose of the workshop.

Working with categories
Explain that in this section you will focus on Pywikibot scripts that operate on page categories. Go through the scripts you will present.

Adding categories to pages


Explain that you can use the  script to add a category to a list of pages.

Show a page you intend to provide to the script.

Run the  script and explain what is happening.

Pywikibot asks you to provide a page with the list and then specify a category. It then adds the category to all pages linked from the page you provided, but only after you confirm you want to do this.

Show the page again, pointing out that the category has been added.

Mention that Pywikibot does not add the category directly to the page you specify, only to linked pages. Also, note that you can pass the  option if you want linked pages that do not exist to be created as well. They are skipped by default.

Sources:


 * Manual:Pywikibot/category.py
 * Category script documentation on doc.wikimedia.org

Removing categories from pages


Explain that you can use the  script to remove the category from all pages with that category. Mention that this script does not allow you to specify pages to remove the category from. Its primary use is for when you want to delete a category entirely.

There is an option to use a page generator to limit the reach of this script. For example, you can choose to only remove a category from pages that only exist in another, specified category. You can read more about this in the documentation.

Demonstrate the use of this script by running  and then picking a category from the test Wikipedia to remove. The best way to do this is to remove the category you have added in the previous step. Show the page again to demonstrate it.

Sources:
 * Manual:Pywikibot/category.py
 * |Category script documentation on doc.wikimedia.org

Creating a list of pages in a given category


Explain that you can use the  script to generate a list of pages with a specific category.

Demonstrate the use of this script by running  and then providing category name and the name of a list page to create. Show the newly created page on the wiki.

Note that you can use the  option to overwrite a page if it already exists.

Sources:
 * Manual:Pywikibot/category.py
 * |Category script documentation on doc.wikimedia.org

Running Pywikibot scripts using PAWS
TODO - slides 17-23?

PAWS ...

Creating pages from a file




Archiving page discussion




Closing
Thank the participants and other organizers. Leave some time for final questions the participants might have. List links to additional materials on your last slide (if you are using them), and let the participants know where they can find the slides and any helpful resources.

Frequently asked questions
(questions asked by participants during previous workshops)

Resource reference
(list all links for quick access)