You are browsing a read-only backup copy of Wikitech. The primary site can be found at wikitech.wikimedia.org

Help:Toolforge/My first Pywikibot tool: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>BryanDavis
(tool-labs -> toolforge)
 
imported>Ahecht
(Use shared pywikibot files)
 
(8 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{draft}}
{{Pywikibot outdated}}
[[mw:Manual:Pywikibot|Pywikibot]] is a [[w:Python_(programming_language)|Python]] library which automates work on MediaWiki sites. Use this guide to create your own tool based on Pywikibot and host it on [[Help:Toolforge|Toolforge]].
{{note| This page is related to https://wikitech.wikimedia.org/wiki/Help:Toolforge/Pywikibot. These pages will be combined for simpler documentation}}.
 
{{Toolforge nav}}
 
[[mw:Manual:Pywikibot|Pywikibot]] is a [[w:Python_(programming_language)|Python]] library which automates work on MediaWiki sites. Use this guide to create your own tool based on Pywikibot and host it on the [[Help:Toolforge|Toolforge]] hosting enviornment.


__TOC__
__TOC__


'''Toolforge account required:'''
== Request access to Toolforge ==
Before creating your tool, you need to [[Help:Tool_Labs/Getting_started#Creating_your_account|create an account to access Toolforge]]. Set up your user name and shell name and submit a [https://toolsadmin.wikimedia.org/tools/membership/apply Toolforge project membership request].
 
Before creating your tool, you need to create a Wikimedia developer account and request access Toolforge:


==Create your Pywikibot Tool account==
# [https://toolsadmin.wikimedia.org/register/ 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'':
In addition to your own Toolforge account, you also need to create a [[Help:Tool_Labs#Joining_and_creating_a_Tool_account|Tool acoount]] for your Pywikibot tool.
#* '''LDAP username''': used to log into this wiki, [[:mw:Gerrit|Gerrit]], and the [https://toolsadmin.wikimedia.org/ Toolforge admin console].
#* '''UNIX shell username''': used when you interact with servers using [[Help:Access|ssh]] and when using [[:mw:Gerrit/Getting_started|git with Gerrit]].
# [https://toolsadmin.wikimedia.org/tools/membership/apply Fill out an access request to join the Toolforge project]. You will receive a reply on your [[Special:MyTalk | Wikitech talk page]].
 
=== Accessing Toolforge for the first time ===
 
Once your request to access Toolforge is approved, you can set up [[Help:Access|ssh]] access to Toolforge severs:
 
==== Generate a new SSH key for your account ====
<ol>
<li>From a Linux terminal, you can generate a new ssh key using the <code>ssh-keygen</code> command:
<pre>ssh-keygen -t rsa -C "your_email@youremail.com"</pre>
Select a passphrase for your ssh key and press '''Enter'''. The command will create two files in your <code>~/.ssh</code> directory:
<pre>
~/.ssh/id_rsa : identification (private) key
~/.ssh/id_rsa.pub : public key
</pre>
</li>
<li>Add your public key to your Wikimedia developer account in the [https://toolsadmin.wikimedia.org/profile/settings/ssh-keys SSH Keys page of the Toolforge admin console]. Copy the contents of <code>~/.ssh/id_rsa.pub</code> into the '''New SSH Key''' field and click '''Add SSH key'''.
</li>
</ol>


# Navigate to the [[toollabs:|Tools home page]].
==== Log into Toolforge with ssh ====
# Click '''Create a New Tool''' under '''Develop your own tool'''.
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 <code>ssh</code> to log in with your '''UNIX shell username''':
# Enter a Service group name. The Service group name will become the name of your tool account.<br/> Do not prefix your service group name with <code>tools.</code>. This prefix will cause an improperly created account. The management interface automatically adds this prefix where appropriate.


'''Note:''' If you only recently received access to the tools project, you may get an error about appropriate credentials. Log out of Wikitech and back in to fix the issue.
<pre>
ssh -i ~/.ssh/id_rsa <unix shell username>@login.toolforge.org
</pre>


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
== Create your Pywikibot Tool account ==
In addition to your own Toolforge account, you also need to create a [[Help:Toolforge#Tool_Accounts|Tool acoount]] for your Pywikibot tool.


==Access your Pywikibot tool==
# Navigate to the [https://toolsadmin.wikimedia.org/tools/create Create Tool Account] page in the Toolforge admin console.
After you create  your Pywikibot's tool account, you can log into your tool project with SSH.
# Enter a '''Unique Tool Name''' for your tool account.<br/> Do not prefix your tool name with <code>tools.</code> as this prefix will cause errors.


<source lang="bash">
'''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.
$ ssh <shell name>@login.tools.wmflabs.org
</source>


Switch to your tool account:
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


<source lang="bash">
== Access your Pywikibot tool ==
maintainer@tools-bastion:~$ become <toolname>
After you create your Pywikibot's tool account, you can log into your tool project with SSH.
 
<syntaxhighlight lang="bash">
$ ssh <unix shell username>@login.toolforge.org
</syntaxhighlight>
 
From the command line, switch to your tool account:
 
<syntaxhighlight lang="bash">
become <toolname>
</syntaxhighlight>
 
You should see the command prompt change to:
<syntaxhighlight lang="bash">
tools.<toolname>@tools-bastion:~$
tools.<toolname>@tools-bastion:~$
</source>
</syntaxhighlight>


Now, you can install Pywikibot.
Now, you can install Pywikibot.


==Install Pywikibot==
== Install Pywikibot ==
Using your tool account, do the following:
{{#section-h:Help:Toolforge/Pywikibot|Using the shared Pywikibot files (recommended setup)}}


<ol>
== Choose a license ==
<li>Use git to download Pywikibot:
<source lang="bash">
git clone --recursive https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot-core
cd pywikibot-core
</source>
</li>
<li>
Set up your bot for selected wikis by running:
<source lang="bash">
python generate_user_files.py
</source>
</li>
</ol>
 
==Choose a license==
Pywikibot comes with an MIT <tt>LICENSE</tt> file. Make sure to choose a license for your tool early on. Also see, [[Help:Tool_Labs/Developing#Licensing_your_source_code]]
Pywikibot comes with an MIT <tt>LICENSE</tt> file. Make sure to choose a license for your tool early on. Also see, [[Help:Tool_Labs/Developing#Licensing_your_source_code]]


==Publish your source code==
== Documentation ==
 
==Documentation==
 
===Add documentation page for your tool===


===Set up a webpage for your tool===
=== 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 [https://tools.wmflabs.org/?list Tool list] will link to it.  
You can add webpage for your tool under https://TOOLNAME.toolforge.org. For example, https://my-first-pywikibot-tool.toolforge.org. Once you set up a webpage for your tool, the [https://admin.toolforge.org/?list Tool list] will link to it.


To set up webpage for you tool:
To set up webpage for you tool:
Line 73: Line 92:
$ webservice start
$ webservice start
</pre>
</pre>
{{:Help:Cloud Services communication}}
[[Category:Toolforge|Pywikibot]]

Latest revision as of 08:24, 5 July 2021

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

.

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:
  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.toolforge.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.toolforge.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

{{#section-h:Help:Toolforge/Pywikibot|Using the shared Pywikibot files (recommended setup)}}

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 https://TOOLNAME.toolforge.org. For example, https://my-first-pywikibot-tool.toolforge.org. 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

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
Receive mail announcements about critical changes
Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
Track work tasks and report bugs
Use the Phabricator workboard #Cloud-Services for bug reports and feature requests about the Cloud VPS infrastructure itself
Learn about major near-term plans
Read the News wiki page
Read news and stories about Wikimedia Cloud Services
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)