Help:Toolforge/My first Pywikibot tool

Caution: This page may contain inaccuracies. It is currently being edited and redesigned for better readability. For further information, please see T134495.

Toolforge
Toolforge technical documentation Toolforge administrator documentation Help and communication List of tools Terms and conditions Glossary Technical documentation resources
Getting started Cloud VPS and Toolforge at a glance About Toolforge Toolforge quickstart guide How-tos, tutorials and walkthroughs Create a Wikimedia developer account Access Toolforge instances with PuTTY and WinSCP Troubleshooting Toolforge
Developing tools Tool accounts Developing successful tools Develop Mono/.NET tools and bots Develop tools in Java Develop tools in Python Develop tools using Pywikibot framework Web servers for tools (Kubernetes) Grid engine
Additional documentation Version control in Toolforge Elasticsearch for Toolforge Redis for Toolforge Dumps and Toolforge Database

Pywikibot is a Python library which automates work on MediaWiki sites. Use this guide to create your own tool based on Pywikibot and host it on the Toolforge hosting enviornment.

Request access to Toolforge

Before creating your tool, you need to create a Wikimedia developer account and request access Toolforge:

1. Create a Wikimedia developer account from the Toolforge admin console. This account is used for most developer activities including editing this wiki, accessing code repositories, and accessing the bug tracking system. Take note of your LDAP username and your UNIX shell username:
   • LDAP username: used to log into this wiki, Gerrit, and the Toolforge admin console.
   • UNIX shell username: used when you interact with servers using ssh and when using git with Gerrit.
2. Fill out an access request to join the Toolforge project. You will receive a reply on your Wikitech talk page.

Accessing Toolforge for the first time

Once your request to access Toolforge is approved, you can set up ssh access to Toolforge severs:

Generate a new SSH key for your account

1. From a Linux terminal, you can generate a new ssh key using the ssh-keygen command:

   ssh-keygen -t rsa -C "your_email@youremail.com"

   Select a passphrase for your ssh key and press Enter. The command will create two files in your ~/.ssh directory:

   ~/.ssh/id_rsa : identification (private) key
   ~/.ssh/id_rsa.pub : public key
   

2. Add your public key to your Wikimedia developer account in the SSH Keys page of the Toolforge admin console. Copy the contents of ~/.ssh/id_rsa.pub into the New SSH Key field and click Add SSH key.

Log into Toolforge with ssh

After you add your public key to your Wikimedia developer account, you can use your private key to log into the Toolforge servers. From a Linux command line, use ssh to log in with your UNIX shell username:

ssh -i ~/.ssh/id_rsa <unix shell username>@login.tools.wmflabs.org

Create your Pywikibot Tool account

In addition to your own Toolforge account, you also need to create a Tool acoount for your Pywikibot tool.

1. Navigate to the Create Tool Account page in the Toolforge admin console.
2. Enter a Unique Tool Name for your tool account.
   Do not prefix your tool name with tools. as this prefix will cause errors.

Note: If you only recently received access to the tools project, you may get an error about appropriate credentials. Log out and back in to fix the issue.

Within a minute or two, Toolforge creates the Tool account and grants you access. If you were logged in through ssh when you created the Tool account, you must log off and log in again

Access your Pywikibot tool

After you create your Pywikibot's tool account, you can log into your tool project with SSH.

$ ssh <unix shell username>@login.tools.wmflabs.org

From the command line, switch to your tool account:

become <toolname>

You should see the command prompt change to:

tools.<toolname>@tools-bastion:~$

Now, you can install Pywikibot.

Install Pywikibot

Using your tool account, do the following:

1. Use git to download Pywikibot:

   git clone --recursive --branch stable https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot-core
   cd pywikibot-core
   

2. Set up your bot for selected wikis by running:

   python generate_user_files.py
   

Choose a license

Pywikibot comes with an MIT LICENSE file. Make sure to choose a license for your tool early on. Also see, Help:Tool_Labs/Developing#Licensing_your_source_code

Documentation

Set up a webpage for your tool

You can add webpage for your tool under http://tools.wmflabs.org/TOOLNAME. For example, http://tools.wmflabs.org/my-first-pywikibot-tool. Once you set up a webpage for your tool, the Tool list will link to it.

To set up webpage for you tool:

1. Log in with your Tool account.
2. Create a ~/public_html directory.
3. Create ~/public_html/index.html.
4. Start the web service:

$ webservice start

Communication and support

We communicate and provide support through several primary channels. Please reach out with questions and to join the conversation.

Communicate with us

	Connect	Best for
Phabricator Workboard	#Cloud-Services	Task tracking and bug reporting
IRC Channel	#wikimedia-cloud connect	General discussion and support
Mailing List	cloud@	Information about ongoing initiatives, general discussion and support
Announcement emails	cloud-announce@	Information about critical changes (all messages mirrored to cloud@)
News wiki page	News	Information about major near-term plans
Cloud Services Blog	Clouds & Unicorns	Learning more details about some of our work
Wikimedia Technology Blog	techblog.wikimedia.org	News and stories from the Wikimedia technical movement