User:Legoktm/toolforge library

toolforge is a simple Python 3 library to help with some common tasks that Toolforge users might encounter. A Rust version is in development now. Source code is published on GitHub (Python) and GitLab (Rust). Patches welcome.

Installation

Python:

pip install toolforge.

Rust:

[dependencies]
toolforge = "5.0"

Python usage

Connect to databases

An example how to connect to a replicating database without needing to remember all the various options.

import toolforge
conn = toolforge.connect('enwiki')  # You can also use "enwiki_p"
# conn is a pymysql.connection object.
with conn.cursor() as cur:
    cur.execute(query)  # Or something....

If you want to connect to a user database, use toolforge.toolsdb() instead.

Please keep the connection handling policy in mind – web tools should do this per request, not during application initialization.

Set proper user-agent

Set the default requests user-agent to one that complies with the Wikimedia User-Agent policy:

import requests
import toolforge

toolforge.set_user_agent('mycooltool')
# Sets user-agent to:
# mycooltool (https://tools.wmflabs.org/mycooltool; tools.mycooltool@tools.wmflabs.org) python-requests/2.13.0
requests.get('...')

For cases where the default requests user-agent isn’t used, the function also returns the string to use instead:

import mwapi
import toolforge

user_agent = toolforge.set_user_agent('mycooltool')
session = mwapi.Session('https://meta.wikimedia.org',
                        user_agent=user_agent)
session.get(action='...')

Rust usage

Connect to databases

You will need to enable the mysql feature in the toolforge crate for this functionality.

An example how to connect to a replicating database using the mysql crate.

use mysql::*;
use mysql::prelude::*;

let db_url = toolforge::connection_info!("enwiki")?;
let pool = Pool::new(db_url.to_string())?;
let mut conn = pool.get_conn()?;

Please keep the connection handling policy in mind – web tools should do this per request, not during application initialization.

Set proper user-agent

Get a user-agent that complies with the Wikimedia User-Agent policy:

// Generic:
const USER_AGENT: &str = toolforge::user_agent!("mycooltool");

// mediawiki crate:
let mut api = Api::new(...);
api.set_user_agent(toolforge::user_agent!("mycooltool"));