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"));