User:Pathoschild/Scripts/StewardBot

From Meta, a Wikimedia project coordination wiki
< User:Pathoschild‎ | Scripts(Redirected from User:StewardBot)
Jump to: navigation, search
This bot is named "stewbot" on IRC, and is entirely distinct from the bot named "StewardBot" on IRC.
Scripts User:Pathoschild (Scripts > StewardBot)


StewardBot is a Python script which idles in several channels on the freenode IRC network as "stewbot" when Pathoschild is around, including #stewardbotconnect and #wikimedia-stewardsconnect. It accepts commands and performs utility operations related to steward tasks.

Contents

Secret agenda[edit]

Popular wikis are often abused to publish attacks on users or persons. This bot aims to defeat such attempts, particularly with regards to the registration of usernames containing attacks or private information. This method was particularly nefarious, because it was virtually impossible to remove this information after the account was created.

Fortunately, recent developments in the MediaWiki software make it possible to counter this, and even erase past attacks. This bot was primarily created to facilitate this. Specifically...

  1. The bot automates the process of blocking a malicious user globally and locally, and if necessary removing it from logs and edit histories. A new account processed this way effectively disappears. Since the process is almost entirely automated, it takes longer for malicious users to create such accounts than it takes to suppress them.
  2. By automatically scanning locked global accounts' local edits, operators are notified about hidden vandalism and page creations, avoiding the possibility that an attack page will be created on a small wiki and be indexed by search engines.

User access & security[edit]

Commands are divided into three access groups: unrestricted commands may be issued by anyone; whitelist commands may be issued by users in the bot's whitelist; and operator commands which will be accepted only from the operator. Whitelisted users may also issue op commands, but will require operator approval using !commit.

The bot only processes sensitive commands from authorized users. Its authorization is based on explicitly whitelisted Wikimedia cloaks, and its security is paranoid and handled at a code path bottleneck at the parser level. In addition, it is only running when Pathoschild is near its terminal to intervene if needed, and all its commands are reversible.

Only Pathoschild has operator access.

Current commands[edit]

Unrestricted commands[edit]

Documentation
!help
!help command
Displays concise documentation about the bot, or the specified command.
!help keyword Displays details about the bot:
  • !help access: information about command access, and a list of whitelisted users and operators.
  • !help commands: a list of commands, sorted by access level.
  • !help status: information about the bot's IRC and web connections and configuration.
Utility
!activity domain
!activity dbprefix
display dates of last edit, and last local sysop & bureaucrat actions by local users on the specified wiki.
!links ip
!links username
Provide relevant links for IPs or global accounts.
!lookup language_code Looks up an ISO-639 1–3 language code in iso639db.
!scanedits name Scan for edits by a global account; privately send links to contributions for wikis with edits, or link to a sandbox list if there too many edited wikis.
!showrights name@wiki List the specified user's local and global right-groups.
!steward Ping available stewards, for emergency situations where a steward is needed immediately.
Disabled by default; enable with "!config > stewardping > 1".
!translate text Uses Google translation tool to detect the language the text is written in and outputs the English translation if available.
  • !translate source language > text : Translates text from source language to English.
  • !translate source language > target language > text : Translates text from source language to target language.
Frivolous
!bash
!bash literal search terms
!bash id
Display a randomly-selected quote from bash or bugzilla quips, the first quote containing the search string, or the quote selected by queue ID.
!debug Print a random quote from Pathoschild's three-year-old niece (except when debugging).

Whitelisted guest commands[edit]

!config option > value Changes runtime configuration:
  • [operators only] disablerestricted > 0|1: disable processing of all restricted commands at the parser level, for even more paranoid security during operator absence.
  • redundantconfirm > 0|1: toggle confirmation messages for wiki actions (normally redundant with another IRC bot).
  • stewardping > 0|1: toggle response to "!steward" command (normally redundant with another IRC bot).
!exit
!exit reason
Disconnect from IRC and end process.
!reset
!reset reason
Delete web cookies and log back in, disconnect from IRC and reconnect.

Operator commands[edit]

Wiki-targeted commands
!block user@wiki
!block user@wiki > expiry
!block user@wiki > expiry > reason
Block the user on the specified wiki (with email disabled). Wiki can be 'global' or a db_prefix, and expiry can be 'never'.
!blockhide user@wiki
!blockhide user@wiki > reason
Block the user on the specified wiki (with email disabled), and oversight the account name in edit histories and log entries. Wiki can be 'global' or a db_prefix.
!unblock user@wiki
!unblock user@wiki > reason
Unblock the user on the specified wiki. Wiki can be 'global' or a db_prefix.
!checkuser target@wiki [operators only] Assign checkuser access to the requesting user, and link to the checkuser form prefilled with the specified user.
!setrights user@wiki > +right1,right2
!rights user > right1,-right2 > reason
Adds or removes the specified user's right-groups, where wiki is a db_prefix. Groups are listed with commas, with '+' or '-' before a name switching between addition and removal of subsequent groups (default is addition).
CentralAuth commands
!lock name
!lock; name > reason
Lock a global account.
!hide name
!hide name > reason
Hide a global account.
!lockandhide name
!lockandhide name > reason
Lock and hide a global account.
!unlock name
!unlock name > reason
Unlock a global account.
!unhide name
!unhide name > reason
Unhide a global account.
Other global commands
!gblock address > expiry > reason Globally block an IP address or CIDR range, anonymous-users only.
!gunblock address > reason Globally unblock an IP address or CIDR range.
!stab user Lock & hide the global account, scan its edits on every wiki, and block all local accounts.
!stabhide user Lock & hide the global account, scan its edits on every wiki, block all local accounts, and oversight name in local logs and edit histories.
!wikiset wikiset_id > +wiki1,-wiki2
!wikiset id > wiki1,wiki2 > reason
Add or remove the wikis to the wiki set. Wikiset_id is the numeric wikiset ID (type "!help > wikiset" for a list). Wikis are database prefixes listed with commas, with '+' or '-' before a name switching between addition and removal of subsequent groups (default is addition).
Command commands
!commit id
!commit all
[operators only] Executes the specified user restricted command (or all uncommitted user commands).
!cancel id
!cancel all
[operators only] Removes the specified user restricted command without executing it (or all uncommitted user commands).
!requeue [operators only] List IDs in uncommitted queue (awaiting !commit or !cancel).
!requeue view > commit_id
!requeue edit > commit_id > arg_id > value
[operators only] View or modify the queue of commands awaiting !commit or !cancel. commit_id is the command's numeric ID in the queue; arg_id is the numeric count from one of the argument you want to modify; value is the value to set for that argument.
!withlist url > command
!withlist url > command > arg1 > ...
Parse a plaintext list of values at the given URL, and queue "!command > value > arguments" for each value (!commit needed). Valid with commands: block, blockhide, lock, hide, lockandhide, unlock, unhide, gblock, gunblock, setrights, stab, stabhide, unblock, wikiset, setrights.

Code documentation[edit]

Don't mind this section, just notes. This section is somewhat out of date, and will be replaced once proper code documentation is in place.

Class hierarchy[edit]

                                              ┌─────────────────┐
 ↑ abstract                                   │   __config__    │
 ↓ modules                                    └────────┬────────┘
                                              ┌────────┴────────┐
                                              │    __init__     │
                                              └────────┬────────┘
                                              ┌────────┴────────┐
                                              │    Stewardbot   │
                                              └────────┬────────┘
          ┌─────────────────────┬──────────────────────┼─────────────────────┬─────────────────────┬────────────┐
 ┌────────┴─────────┐  ┌────────┴─────────┐  ┌─────────┴────────┐  ┌─────────┴────────┐  ┌─────────┴────────┐   │
 │ Wikimedia.Browser│  │  CommandParser   │  │        IRC       │  │   Documentation  │  │       Bash       │   │
 └────────┬─────────┘  └────────┬─────────┘  └─────────┬────────┘  └─────────┬────────┘  └─────────┬────────┘   │
 ┌────────┴─────────┐           │                      │                     │                     │            │
 │      Browser     │           │                      │                     │                     │            │
 └────────┬─────────┘           │                      │                     │                     │            │
          └─────────────────────┴──────────────────────┼─────────────────────┴─────────────────────┴────────────┘
                                             ┌─────────┴────────┐
                                             │    BaseClass     │
                                             └──────────────────┘

BaseClass[edit]

BaseClass is inherited by all classes in the stewbot framework, and provides a common interface and internal methods. It includes an Error object (subclassing Exception) that is raised when a framework error occurs.

Constructor[edit]

__init__
( verbose=True )

Instantiates the BaseClass, and sets debug message verbosity.

  • verbose (bool): Sets whether to print debug messages to the terminal.

Profiling & error-handling[edit]

traceMessage
( msg )

If verbose, print message to console.

  • msg (str): Text to print.
formatException
 or handleException()
Prints a formatted error and traceback to the console for the last exception raised, and return a short summary suitable for public display (eg, on IRC).
formatFullException
()
Returns a string containing a formatted error and traceback for the last exception raised.
formatArg
( value )

Converts an arbitrary object to a printable representation for debug output.

  • value (*): An arbitrary object to format.

String manipulation[edit]

parse
( obj, encodings=['utf-8', 'ISO-8859-1', 'CP1252', 'latin1'], suppress_text=True, suppress_trace=True )

Given an arbitrary text object, returns its equivalent UTF-8 Unicode string using one of the specified encodings. If these all fail, attempts to detect a valid encoding. If even this fails, returns the object unmodified.

  • obj (text*): The text object to parse.
  • encodings (arr of str): An array of encodings to attempt decoding with, before trying the encoding detection heuristic.
  • suppress_text (bool): Replace obj with <<hidden>> in debug messages.
  • suppress_trace (bool): Do not raise debug messages at all.
unparse
( obj, suppress_text=True, suppress_trace=True )

Given a UTF-8 Unicode string (as returned by parse), return an equivalent encoded bytestring.

  • obj (text*): The text object to unparse.
  • suppress_text (bool): Replace obj with <<hidden>> in debug messages.
  • suppress_trace (bool): Do not raise debug messages at all.
urlEncode
( obj, suppress_trace=True )

Returns a Unicode-aware URL-encoded query string representation of the obj hash.

  • obj (hash): An arbitrary hash to represent.
  • suppress_trace (bool): Do not raise debug messages at all.
capitalizeFirstLetter
( text )

Returns the text with the first character capitalized.

  • text (str): The text to manipulate.
isAddress
( text )

Returns a boolean indicating whether the given text is a well-formed IP address or CIDR range.

  • text (str): Text to test.
isInt
( text )

Returns a boolean indicating whether the given text is numeric.

  • text (str): Text to test.

Object manipulation[edit]

hasIndex
( obj, i )

Returns boolean indicating whether the object obj has index i.

  • obj (*): The object to test.
  • i (*): The index of obj to check for existence.

Browser[edit]

Browser abstracts querying, scraping, and parsing web pages and APIs, and provides high-level functions for performing actions and fetching data.

Constructor[edit]

__init__
( username, password, user_agent='stewbot framework', obey_robot_rules=False, max_api_items=200 )

Instantiates the Browser class with configuration.

  • username (str): The wiki username the bot will use to log in.
  • password (str): The wiki password the bot will use to log in.
  • user_agent (str): The user agent sent to servers the bot queries.
  • obey_robot_rules (bool): Should the bot comply with bot exclusion directives?
  • max_api_items (int): Number of items to ask the API for per page.

Session & URL management[edit]

loggedIn
( force_check=False )

Return a boolean indicating whether the bot is logged in to the current wiki.

  • force_check (bool): Bypass cached data, and verify whether bot is logged in by querying the API.
storeSession
( base_url, username )

Create a new session for the given wiki.

  • base_url (str): The base URL of the wiki to create a session for, in the form 'meta.wikimedia.org'.
  • username (str): The username logged in as (only used when reporting cached login status).
storeSessionToken
( type, token )

Store a token in the session for the current wiki.

  • type (str): The token type, as requested from the API ('edit', 'block', etc).
  • token (str): The token string.
readSessionToken
( type )

Returns the token of the given type from the current session, or None.

  • type (str): The token type, as requested from the API ('edit', 'block', etc).
destroySession
( base_url )

Delete all session data, and forget the bot is logged in.

  • base_url (str): The base URL of the wiki whose session is to be destroyed, in the form 'meta.wikimedia.org'.
setBaseUrl
( base_url, index_path='/w/index.php', api_path='/w/api.php', article_path='/wiki/', set_default=False )

Change the bot's location to another wiki, and make it the default wiki for future wiki-specific actions.

  • base_url (str): The base URL of the wiki to move the bot to, in the form 'meta.wikimedia.org'.
  • index_path (str): The path relative to the domain where index.php resides.
  • api_path (str): The path relative to the domain where api.php resides.
  • article_path (str): The pretty path relative to the domain where articles reside; on wikis with pretty URL rewriting disabled, this is something like '/w/index.php?title='.
  • set_default (bool): Make this the default wiki reset to with resetBaseUrl?
resetBaseUrl
()
Change the bot's location to the default wiki (as defined by setBaseUrl with set_default=True).
reset
()
Return to the default wiki (as defined by setBaseUrl with set_default=True), and delete all session data.

Page fetching[edit]

load
( url, parameters=None, GET=False, visit=False, parse_as=None, unicodify=True, censor_url=False, catch_errors=True )

Fetch the specified page, set Browser.text to the response text, and (optionally) parse as XML, HTML DOM, or JSON.

  • url (str): The URL to fetch.
  • parameters (hash): A key=>value hash of parameters to send with the request, either as POST data or as a URL query string.
  • GET (bool): Send the request using GET instead of POST (see HTTP request methods).
  • visit (bool): Analyze the page for manipulation using the internal mechanize client, usually for submitting forms; causes significant delay on large pages.
  • parse_as (str): Parse the result as the specified format ('xml', 'html', or 'json'), and store the result in Browser.text_parsed. If None, sets Browser.text_parsed to None.
  • unicodify (bool): Convert the response text to a Unicode string before storing it.
  • censor_url (bool): Replace URL with <<hidden>> in debug messages.
  • catch_errors (bool): Check the response text for errors, and raise self.Error with the error message.
queryApi
( parameters, GET=False, censor_url=False )

Query the current wiki's API, set Browser.text to the response text, and parse as XML, HTML DOM, or JSON. (This is a wrapper for load.)

  • parameters (hash): A key=>value hash of parameters to send with the request, either as POST data or as a URL query string.
  • GET (bool): Send the request using GET instead of POST (see HTTP request methods).
  • censor_url (bool): Replace URL with <<hidden>> in debug messages.
submit
()
Submit the current form (which must have been visited using load with visit=True), and set Browser.text and Browser.parsed with the response.
stripHtml
( text, strip_newlines=True, suppress_text=False )

Strip HTML formatting from a string, returning only the textual content.

  • text (str): String to extract textual content from.
  • strip_newlines (bool): Remove all newlines, returning the textual content on one line.
  • suppress_text (bool): Replace text with <<hidden>> in debug messages.
readXmlElement
( element )

Extracts the textual content from the immediate children of an XML element.

  • element (XML node): Element to extract text from.

Error-handling[edit]

handleApiErrors
()
Scan the XML data in Browser.parsed (set by load or queryApi) for <error> tags or known errors; raises a self.Error with the error message if one is found.
handleHtmlErrors
()
Scan the HTML DOM in Browser.parsed (set by load or queryApi) for elements with a fail or error class; raises a self.Error with the error message if one is found.

MediaWiki API queries[edit]

login
( force_login=False )

Log in to the current wiki with the username and password specified in the constructor.

  • force_login (bool): Login to the API and start a new session, even if already logged in.
logout
()
Log out from the current wiki and delete its session data.
fetchToken
( type, title='User:Pathoschild', user=None )

Fetch an API token for the current wiki, required for certain API queries like edits and deletions.

  • type (str): The type of token to fetch, such as 'edit' or 'delete' (see API documentation).
  • title (str): An arbitrary title, which need not exist; the API requires at least one title to display data.
  • user (str): Used only for userrights queries; the target user name to fetch a token for.
getBlockStatus
( user )

Returns a hash with data about the current block against the user on the current wiki (or False if not blocked). The hash contains the following keys: id, by, timestamp, expiry, reason, nocreate, autoblock, noemail, alowusertalk, hidden.

  • user (str): The user name whose block status to query.
block
( user, expiry, reason, anononly=True, nocreate=True, hidename=False, allowusertalk=True, autoblock=True, reblockIfChanged=False, reblock=False )

Blocks a user, IP address, or CIDR range from editing on the current wiki.

  • user (str): The user name, IP address, or range to block.
  • expiry (str): The GNU-standard time specifying the expiry of the block (by length or date), or 'never'.
  • reason (str): The reason for the block shown in the logs, and to the blocked user.
  • anononly (bool): When blocking an IP address, the block will not affect logged-in users.
  • nocreate (bool): Prohibit account creation by the IP address (or IP addresses used by the logged-in account).
  • hidename (bool): Make the name disappear from edit histories, logs, and user lists; subject to the oversight policy, and requires oversight access.
  • allowusertalk (bool): Allow the user to edit their talk page when blocked.
  • autoblock (bool): Block any IP address used by the registered account, or any registered account editing from the IP address.
  • reblockIfChanged (bool): If the user is already blocked, override the current block only if the hidden status or expiry changed.
  • reblock (bool): If the user is already blocked, override the current block.
unblock
( user, reason )

Remove a block on a user account, IP address, or CIDR range on the current wiki.

  • user (str): The user name, IP address, or range to unblock.
  • reason (str): The reason for the unblock shown in the logs.
edit
( title, summary, text='', section=None, bot=False, minor=False, recreate=True, createonly=False )

Edit a page on the current wiki.

  • title (str): The title of the wiki page to edit.
  • summary (str): The edit summary, which will appear in the edit history.
  • text (str): The text to replace the current text with.
  • section (int): The numeric ID of the section you want to edit, if not the whole page.
  • bot (bool): Hide edit by default on recentchanges and watchlists; requires bot flag.
  • minor (bool): Mark the edit as a minor change.
  • recreate (bool): If the article is deleted, recreate it.
  • createonly (bool): If the article currently exists, do not edit it.
countUserEdits
( username )

Returns a hash with the number of total, new, and top edits by the specified user or IP address on the current wiki. The keys are: edits, new, and top.

  • username (str): The user name or IP address whose edits to count.
getRights
( username )

Return a list of local groups the user is in on the current wiki.

  • username (str): The user name whose groups to list.
setRights
( username, groups, reason, allowUnchanged=False )

Add or remove a user's local groups on the current wiki.

  • username (str): The user name whose groups to modify.
  • groups (hash): A group name=<boolean hash indicating groups to add (True) or remove (False). Groups that are not set in the hash will not be modified.
  • reason (str): The reason for the groups change, visible in the logs.
  • allowUnchanged (bool): Silently submit the form even if no groups were changed, rather than raise Browser.Error.

MediaWiki queries (screen-scraping)[edit]

centralAuth
( user, reason='', lock=None, hide=None, delete=None, blockMeta=False, ignoreUnchanged=False )

Perform a global CentralAuth action, such as locking, hiding, or undoing a lock or hide. This requires the steward flag.

  • user (str): The username to perform the action on.
  • reason (str): The reason for the action, visible in the logs.
  • lock (bool or None): Lock or unlock the account depending on the boolean value, or do not change lock status if None.
  • hide (bool or None): Hide or unhide the account depending on the boolean value, or do not change hide status if None.
  • delete (None): This feature is deliberately not implemented, because it is irreversible; setting this to anything but None raises a Browser.Error.
  • blockMeta (None): This feature is not implemented.
  • ignoreUnchanged (bool): Silently submit the form even if no groups were changed, rather than raise Browser.Error.
getGlobalRights
( user )

Return a list of global groups the user is in.

  • user (str): The username whose global groups to list.
globalBlock
( address, reason, expiry, lock=True, anononly=True )

Globally block an IP address or CIDR range. (Not valid for usernames, due to MediaWiki limitations.) This requires the steward flag.

address=str reason=str expiry=None lock=True anononly=Do not block logged-in users, only anonymous users.
getGlobalAccounts
( user, show_zero_edits=False )

Return a list of wiki prefixes where the global account has a unified local account. This requires the steward flag.

  • user (str): The username whose unified local accounts to list.
  • show_zero_edits (bool): include wikis where the user has not edited.
wikiset
( id, reason=None, add_wikis=None, del_wikis=None )

Add or remove wikis in the specified global wikiset. This requires the steward flag.

  • id (int): The numeric wikiset ID to modify.
  • reason (str): The reason for the change, visible in the logs.
  • add_wikis (list of str): A list of wiki prefixes to add to the wikiset.
  • del_wikis (list of str): A list of wiki prefixes to remove from the wikiset.

Non-MediaWiki queries (screen-scraping)[edit]

lookupCode
( code )

Searches for the ISO 639 1–3 code in the ISO 639 database, and returns a list of hashes with the following keys: list (1–3), code, name, scope, type, notes.

  • code (str): The ISO 639 1–3 to search for.
translate
( text, source='', target='en' )

Translate text from one language into another, using the Google Translation API.

  • text (str): The original text to translate.
  • source (str): The ISO 639 1–3 code of the source language. If left blank, attempts to auto-detect language.
  • target (str): The ISO 639 1–3 code of the target language.

Wikimedia.Browser[edit]

Wikimedia.Browser extends Browser with methods specific to Wikimedia wikis.

__init__
( username, password, user_agent='stewbot framework', default_base_url='http://meta.wikimedia.org', default_index_path='/w/index.php',

default_api_path='/w/api.php', obey_robot_rules=False, max_api_items=200, wiki_cache='Wikimedia.cache', max_cache_age=14 * 24 * 60 * 60 )

Instantiates the Wikimedia.Browser class with configuration.

  • username (str): The wiki username the bot will use to log in.
  • password (str): The wiki password the bot will use to log in.
  • user_agent (str): The user agent sent to servers the bot queries.
  • default_base_url (str): The default URL which the bot operates on; wiki-specific actions will be performed on this wiki if no interwiki prefix is specified.
  • default_index_path (str): The default path relative to the domain where index.php resides.
  • default_api_path (str): The default path relative to the domain where api.php resides.
  • obey_robot_rules (bool): Should the bot comply with bot exclusion directives?
  • max_api_items (int): Number of items to ask the API for per page.
  • wiki_cache (str): The filename in the current working directory to cache wiki data to.
  • max_cache_age (int): After this many seconds, update the cache by querying the API.
loadWikis
( from_cache=True )

Loads information about the current wiki farm (called by the constructor). Tries to unpickle data from the cache filename in the working directory if it is within the maximum cache age, otherwise queries the API sitematrix for the default wiki.

  • from_cache (bool): Load the information from the cache if possible (and within maximum cache age).
getWiki
( code=None, family=None, domain=None, prefix=None, want=None )

Attempts to find a wiki it knows that matches one of the specified criteria (checking prefix, then domain, then code + family). Returns a tuple (code, family, domain, special<bool>, locked<bool>, private<bool>).

  • code (str): The wiki code portion of the database prefix, normally matching the subdomain (meta for meta.wikimedia.org). Must be specified with family.
  • family (str): The family code portion of the database prefix (wiki for meta.wikimedia.org). Must be specified with code.
  • domain (str): The wiki's base URL, in the form 'meta.wikimedia.org'.
  • prefix (str): The wiki's database prefix; equivalent to code + family.
  • want (int or None): Return the wantth index of the tuple, instead of the entire tuple; normally a Wikimedia.Browser constant (CODE , FAMILY, DOMAIN, SPECIAL, LOCKED, PRIVATE).
getUrl
( code=None, family=None, domain=None, prefix=None, path='/wiki/' )

Returns a full URL for the wiki matching the given criteria, by default with the article path appended.

  • code (str): See getWiki.
  • family (str): See getWiki.
  • domain (str): See getWiki.
  • prefix (str): See getWiki.
  • path (str): The path to append to the URL.
reset
()
Clears the wiki cache and refetches data, and calls Browser.reset.
writeCache
()
Pickle the data about known wikis to the cache file.
readCache
()
Unpickle the data about known wikis from the cache file.

CommandParser[edit]

CommandParser abstracts parsing data into commands and arguments, handling configurable security, and calling command handlers.

Access levels[edit]

Commands are assigned arbitrary integer access levels, which determine who is allowed to issue them. Users can use commands whose access is less than or equal to their own access level; everyone has access level 0 by default, unless they are assigned an access level by hostmask.

Access levels are configured through the constructor. The example below adds recognition for five commands, with two arbitrary security levels in addition to the default 0. Anyone can issue help or reset commands; users with the IRC hostmask *@wikimedia/Az1568 and *@wikipedia/Bsadowski1 can use the help, reset, exit, and block commands; and *@wikimedia/Pathoschild can use all of them.

self.parser = CommandParser(
   commands = {
      0:['help', 'reset'],
      1:['exit', 'block'],
      2:['checkuser']
   },
   users = {
      1:['wikimedia/Az1568', 'wikipedia/Bsadowski1'],
      2:['wikimedia/Pathoschild']
   }
)

Committing[edit]

The CommandParser supports committing, where a user with insufficient access can issue a command to be queued until a user with commit access confirms it. The commit access level, and a list of commands that cannot be committed, can be configured through the constructor.

The following example illustrates its usage on IRC:

 user> !block some user > forever > because he sucks
  bot> user: commit id 4.
 admin> !commit 4
  bot> "some user" blocked.

Command handling[edit]

After it is configured with the constructor, CommandParser sits idly until given data through handle. This parses the data, determines whether it is a command, and determines access levels. It always returns a command data object, and also calls command handlers directly by passing the constructor a class implementing the following methods. These methods will be passed a command data object as the first positional argument.

  • handle_<command> for each recognized command (for example, handle_commit for a commit command);
  • handle_None, called if CommandParser gets a valid command but can't find its handler method;
  • handle_Error, called if CommandParser gets a valid command but an occurred while processing it (for example, the user has an insufficient access level);
  • handle_Queued, called if CommandParser gets a valid command from a user with insufficient access to issue it, but sufficient access to request a commit.

Command data object[edit]

Command data is returned in the following format:

{
   'text':'!block some user > forever > because he sucks',
   'command':'block',
   'args':['some user', 'forever', 'because he sucks'],
   'commit_id':3,
   'user_level':1,
   'command_level:2,
   'flag':MUST_COMMIT,
   'flag_type':MUST_COMMIT,
   'flag_text':None
}
  • text: the unprocessed text of the command.
  • command: the name of the command, extracted from the text.
  • args: A list of command arguments, extracted from the text.
  • commit_id: The command's numeric index in the queue, if it was queued for commit (else None); see #Access levels.
  • user_level: The user's access level; see #Committing.
  • flag and flag_group: constants indicating the status of the command. A human-readable explanation suitable for error output is returned by explain. Possible values:
    flag flag_group explain
    USER_BANNED IGNORED You are banned from giving me commands
    NOT_COMMAND IGNORED That is not recognized as a command
    BLANK_ARGS ERROR Arguments cannot be blank
    NOT_ALLOWED ERROR You have insufficient access to issue that command
    CANNOT_COMMIT ERROR You have insufficient access to issue that command, and it cannot be committed
    NO_SUCH_COMMIT_ID ERROR No commit id
    MUST_COMMIT MUST_COMMIT The command has been queued for !commit id
    OKAY OKAY The command was parsed and validated, and awaits implementation
  • flag_text: a more specific human-readable error message; usually None.

Public methods[edit]

__init__
( commands, users, callback=None, banned=None, command_prefix='!~', command_delimiter='<>', handle_commit=True, no_commit_commands=[], commit_req_user_level=1, commit_imp_user_level=2 )

Instantiates and configures the CommandParser.

  • commands (dict of lists of str): A dictionary mapping command lists to their integer access level. See #Access levels.
  • users (dict of lists of str): A dictionary mapping user hostmasks lists to their integer access level. See #Access levels.
  • callback (obj or None): A class instance with methods for handling commands; see #Command handling.
  • banned (list of str): A list of regular expression patterns. Any user whose hostmask matches one of these patterns is ignored, and the #Command data object returned with the CommandParser.USER_BANNED flag.
  • command_prefix (str): A string indicating individual characters to recognize as prefixes of a command if they occur at the start of the line.
  • command_delimiter (str): A string indicating individual characters to recognize as argument delimiters.
  • handle_commit (bool): Enable #Committing; if False, always returns the #Command data object with a CommandParser.NOT_ALLOWED flag.
  • no_commit_commands (list of str): A list of commands which cannot be committed; commit and cancel are included automatically. See #Committing.
  • commit_req_user_level (int): The minimum access level required to queue a command for committing. See #Access levels and #Committing.
  • commit_imp_user_level (int): The minimum access level required to commit a queued command (regardless of this setting, a user can never commit a command with an access level higher than their own). See #Access levels and #Committing.
handle
( data )

Parses data from IRC, processes it if it is a command, and returns a #Command data object. If it is a command and a callback was passed to the constructor, calls the relevant callback method (see #Command handling).

  • data (obj): An object describing the command to process, which will be extended with additional data (see #Command data object) and returned. See resolve for required fields.
resolve
( data )

Parses data from IRC with no validation or processing. This is invoked internally by handle.

  • data (obj): An object describing the command to process, which will be extended with additional data (see #Command data object) and returned. The object must have the following fields:
    • text (str): the unprocessed text of the command, like !help foo.
    • mask (str): a string identifying the user issuing the command for regex comparison to the ban list, like Pathoschild!Jesse@wikimedia/Pathoschild (eg, IRC hostmask).
    • host (str): a string uniquely identifying the user issuing the command for exact comparison to the user list, like wikimedia/Pathoschild (eg, host portion of IRC hostmask).
name
( flag )

Returns the string representation of the given flag (eg, name(ERROR) = 'ERROR').

explain
( data )

Returns a human-readable explanation of the #Command data object's flags, suitable for error display (see #Command data object flags).

listQueued
()
Returns a list of ids assigned to commands in the command queue (see #Committing).
queue
( data )

Stores a copy of the given #Command data object in the queue, and returns its unique ID.

peekQueue
( id )

Returns a copy of the queued command with the given ID (or raises a KeyError exception).

  • id (int): The unique ID of the command to get a copy of.
filterByQueued
( ids )

Returns a tuple of lists (queued, not_queued), which splits the given list of ids into two based on whether there is a command queued with each unique ID.

  • ids (list of ints): The list of ids to filter.
parseQueueId
( ids )

Returns a list of queue IDs described by the input string.

  • ids (str): A string describing a set of queue IDs; one of "all", a single numeric ID, or an inclusive range like "start id:end id".
unqueue
( id )

Removes the #Command data object from the queue, and returns it.

  • id (int): The unique ID of the command to unqueue.
commit
( id )

Removes the #Command data object from the queue, and invokes its handler (see #Committing).

  • id (int): The unique ID of the command to commit.
cancel
( id )

Removes the #Command data object from the queue, and returns it. (This simply invokes unqueue.)

  • id (int): The unique ID of the command to cancel.

Private methods[edit]

_setFlags
( data, flag, flag_text=None )

Sets the flag, flag_group, and flag_text properties of the given #Command data object.

  • data (obj): The #Command data object to set the flags on.
  • flag (int): The flag constant to set at the object's status (see #Command data object).
  • flag_text (str): The optional more specific error message to use instead of the generic error for that flag.
_callback
( data, flag, flag_text=None )

Sets the flag properties of the #Command data object (see _setFlags), calls the most appropriate callback method to handle it (see __init__), and returns the object.

  • data (obj): The #Command data object to set the flags on.
  • flag (int): The flag constant to set at the object's status (see #Command data object).
  • flag_text (str): The optional more specific error message to use instead of the generic error for that flag.

See also[edit]