User:AnomieBOT/source/AnomieBOT/API.pm/doc

NAME

AnomieBOT::API - AnomieBOT API access class

SYNOPSIS

 use AnomieBOT::API;
 
 my $api = AnomieBOT::API->new('/path/to/config_file', 1);
 $api->login();
 $res=$api->query(list=>'allpages',apnamespace=>0,aplimit=>10);

DESCRIPTION

AnomieBOT::API is a class implementing various functions needed by a MediaWiki bot.

RETURN VALUES

Unless otherwise noted, each method returns an object with certain standard properties:

code

A short token indicating the result of the API call. In addition to error codes returnable by the MediaWiki API, the following may be seen:

success: The call succeeded.
httperror: An HTTP error response was returned. The object will also contain a page property containing the full HTML returned with the error, and a httpcode property with the HTTP response code.
jsonerror: The response string could not be decoded. The object will also contain a raw property containing the response string;
wtferror: A "This can't happen" error occurred.
notloggedin: The bot user could not be logged in.
botexcluded: Returned by token-fetching functions if the page contains a bot exclusion template that excludes this bot. The return object will have an extra property type with the value "bydefault", "byname", or "optout".
shutoff: Returned by token-fetching functions if the task's shutoff page is triggered.
pageprotected: Returned by token-fetching functions if the page is protected and the bot lacks the appropriate rights.
pagemissing: Returned by token-fetching functions if the page does not exist (when a non-existent page doesn't make sense).
uploadwarnings: Returned by the upload function if warnings were returned.
notiterable: Returned by $api->iterator() when the result set cannot be iterated.
maxlag: If maxlag is set off or the bot is trying to halt, this error may be returned instead of the bot automatically retrying.

error: A textual description of the error code.

METHODS

Note that this class supports runtime decoratoration, so the complete set of available methods depends on the most recent call to task().

AnomieBOT::API->new( $conffile, $botnum )

Create an instance of the bot.

The config file is simply a list of "key = value"s, one per line; any line whose first non-whitespace character is '#' is considered a comment and is ignored.

Sections within the file are delimited with [name]. Anything set before the first section is considered "defaults" for any sections named "bot #".

In addition, a file may include other files by using a line @include opts filename. Any options begin with a "!" character; the remainder of the line is the filename. By default, the file may have its own defaults section (which is merged with the including file's) and sections; if the "!section" option is given, the file will be considered part of the current section and attempting to include other files or define sections will be considered an error. If the "!ifexists" option is given, it will not be an error if the file doesn't actually exist.

See conf.sample.ini for parameters and defaults. The file permissions must not include world readability, writability, or executability.

Botnum is the instance number of this bot, which controls which of the [bot #] sections of the config file is actually used.

$api->copy( %config )

Get a new AnomieBOT::API with the specified options changed.

$api->DEBUG

$api->DEBUG( $bitmask )

Get/set the debug bitmask. When debugging is enabled, most methods will output useful text to standard error.

Returns the old value of the bitmask.

$api->reopen_logs()

Reopen STDOUT and STDERR to the configured log files.

AnomieBOT::API::copy_truncate_file( $from, $to, $fh )

Copy file $from to $to (gzipping on the way), then truncate via $fh.

$api->rotate_logs()

Rotate the log files.

$api->warn( $message )

AnomieBOT::API->warn( $message )

$api->log( $message )

AnomieBOT::API->log( $message )

$api->debug( $bitmask, $message )

AnomieBOT::API->debug( $debuglevel, $bitmask, $message )

Output messages.

$api->check_commands()

$api->check_commands( $file )

Check if there are any pending commands for this instance. Returns the command, if any, unless the command was "KILL".

An optional filename may be passed to override the normal command file.

$api->read_command()

$api->read_command( $file )

$api->read_command( $file, $nodelete )

Read any pending command; to be called on startup. Returns the command, if any. The pending command is cleared, unless it matches the $nodelete regexp.

An optional filename may be passed to override the normal command file.

$api->send_command( $file, $command )

Sends a command to the specified file, overwriting any pending command (if any). Returns true on success, undef on failure.

$api->onpause()

$api->onpause( \&sub )

Get/set a subroutine to be called when the "pause" command is received. The subroutine will be passed a single argument, 1 when the pause command is received and 0 when it is cleared.

Returns the old subroutine, if any.

$api->halting

Process commands, then return a true value if the bot is supposed to halt.

$api->halting( $value )

Set the return value for future calls to halting().

$api->automaxlag

$api->automaxlag( $bool )

Get/set the auto-continue maxlag flag. Note that task() resets this.

Returns the old value of the flag.

$api->edit_watchlist

$api->edit_watchlist( $value )

Get/set the editing watchlist value. Valid values are specified by the API, currently watch, unwatch, preferences, or nochange. The default is nochange.

Returns the old value.

$api->user

Returns the bot user name.

$api->operator

Returns the bot operator's user name.

$api->task

$api->task( $name )

$api->task( $name, $read_rate, $write_rate, @decoraters )

Get/set the current task.

When called with no arguments, simply returns the current task name.

With arguments, it sets the task name, read/write rate limits, and the current list of decorators. If omitted, it defaults to 0 seconds per read, 10 seconds per write, and no decorators.

$api->read_throttle

$api->read_throttle( $seconds )

Get/set the current read throttle time. If a read is attempted less than $seconds seconds after a previous read or edit, the bot will sleep for the remaining time.

Returns the old throttle.

$api->edit_throttle

$api->edit_throttle( $seconds )

Get/set the current edit throttle time. If an edit is attempted less than $seconds seconds after a previous read or edit, the bot will sleep for the remaining time.

Returns the old throttle.

$api->decorators

$api->decorators( @decorators )

Get/set the current list of decorators. Note that functions are first searched for in the current object (thus a decorator cannot override native functions), then in each decorator in order. If you want to set an empty list of decorators, pass undef as the only argument.

Returns the old list of decorators.

$api->is_trial

Returns a true value if a trial is running. This can be used to disable an unapproved code addition in the live code while running it for trial.

$api->CFG

Access the configuration settings for the current task. The most common use will be along the lines of $api->CFG->{$property}.

$api->store

Returns a hashref tied to persistant storage corresponding to the current task, or undef if no task is set.

Since this is tied to persistant storage, only scalars (no scalar refs), hashrefs, and arrayrefs may be stored in the array. Anything else will cause a fatal error.

$api->cache

Returns an AnomieBOT::API::Cache object, for non-persistant data storage.

$api->connectToReplica( $wiki )

$api->connectToReplica( $wiki, $svc )

Calls DBI->connect and returns the database handle.

If replica_dsn is not set in conf.ini, dies instead.

$svc replaces a $SVC token in replica_dsn. For Tool Forge, pass 'analytics' or 'web'. Defaults to 'web'.

$api->drop_connections

Drops any connections in the Keep-Alive state. Call this if you will not be making API calls for the next 300 seconds.

$api->rawpage( $title )

$api->rawpage( $title, $oldid )

Get the raw wikitext of a page, specified by title and (optionally) revision id. The return object has the following additional properties:

content: Content of the page

As with query(), this method may pause for read throttling or maxlag errors.

$api->query( key => value, ... )

$api->query( \@continues, key => value, ... )

Perform a general MediaWiki API query.

As you should be aware, if an action=query API call is going to return an excessive amount of data, only the first bit will be returned and various continuation parameters will be returned to get the next bit in a future call. The array reference \@continues specifies how to handle that: those multiple calls will be made automatically for all modules not named. Note that you will get errors if your query uses a generator and you specify any non-generator modules without also specifying the generator module. To specify the generator module, prefix the module name with "g|". If for some reason you need to specify the continuation parameter explicitly, join it to the module name with a "|" (e.g. "revisions|rvcontinue"); note this is not recommended.

If \@continues is not provided, the default value consists of the generator or list modules specified in the query, plus "revisions|rvcontinue" (we don't want to download all several-thousand revisions automatically when prop=revisions is in enum mode).

The keys and values are those needed for the API call, with the following exceptions:

action: If omitted, "query" will be assumed. Do not use "login", "edit", "move", or others that have a method provided.
format: If not specified, the json-format response will be decoded as a Perl object, the standard properties will be added, and the object will be returned. This is most likely what you want.; If specified (even as "json"), the raw response text will be returned in the content property of the return object. MediaWiki errors will not be detected.
maxlag: If unspecified, the default value "5" will be used. Maxlag errors are (usually) automatically retried.
__nolog: If specified and true, the query will not be output to the bot log (when debugging is active). Use this if the query contains passwords or other sensitive information.
__errok: Specify an array of MediaWiki error codes that will not be logged. Use this if you expect the query might fail and don't want to clutter the log. For example, you might set ['editconflict'] when calling action=edit if you were expecting edit conflicts.

The return value is normally the API response object, but see above for details.

$api->iterator( key => value, ... )

This function returns an iterator object which iterates over the results of a query. Use it something like this:

 my $iter = $api->iterator( %q )
 while(my $res = $iter->next()){
     # Do stuff
 }

Note that, in order to be iterable, the query must return exactly one node under $res->{'query'}, which must be an arrayref or a hashref.

In addition, exactly one value in the query may be an arrayref. In this case, the query will be iterated to completion in turn for each of the values. For example,

 $api->iterator( titles => ['foo', 'bar', 'baz'], prop => 'info' )

will first query the info for foo, then bar, then baz.

See AnomieBOT::API::Iterator for more information.

$api->paramLimit( $module, $param )

Return the multi-value limit for a parameter.

Returns the limit as an integer, or 0 if there is no limit defined, or an API error response on error.

$api->login()

$api->login( $force )

Try to log the bot in.

Note that the MediaWiki API doesn't actually return an error when the login fails, but it does return a result property indicating success or failure. This is translated into a 'notloggedin' error code.

By default, login will return an empty success response if it determines that the bot is already logged in. You can override this by specifying a true value for $force.

$api->logout()

Log the bot out.

$api->gettoken( $type )

$api->gettoken( $type, %options )

Obtain a token of the specified type (see the meta=tokens module). Available options are:

Title: In addition to the token, fetch information for the specified title.
Redir: Follow redirects, if Title is provided.
NoShutoff: Do not check the shutoff page. Don't do this frivolously.
OptOut: If the intention of this edit is to leave a notification on a user's talk page, set Title and set this to the appropriate token as detailed at Template:bots#Message notification opt out.
NoExclusion: Do not check for {{bots}} / {{nobots}} in Title. Don't do this frivolously.
links
images
templates
categories
[etc]: If specified, the corresponding API prop module will be included in the query. If the value is a hash reference, the key-value pairs will be interpreted as the needed parameters for the module.; For example, links => 1, categories => { show => 'hidden' } will include all the page links and the hidden categories in the returned object.; Valid keys are all prop modules.; revisions and info are always queried, with rvprop=ids|timestamp|content|flags|user|size|comment|tags, rvslots=*, and inprop=protection|talkid|subjectid.

The object returned will have properties code and error as usual, token holding the token, curtimestamp holding the timestamp, rights holding the current user's rights, and if Title was specified the properties returned for a query of that title.

If the bot is not logged in, login(1) will be automatically attempted; if it fails, an error code 'notloggedin' will be returned. If the current user cannot edit the wiki, a 'notallowed' error code will be returned. If the task's shutoff page (User:botname/shutoff/task) is non-empty, an error code 'shutoff' will be returned.

$api->edittoken( $title )

$api->edittoken( $title, %options )

Obtain an edit token for the specified page. This is much like gettoken(), with the following differences:

Title is always passed.
Redir is set, unless EditRedir is true.

In addition to the options available for gettoken(), the following are available:

EditRedir: Redir is defaulted to true. This causes Redir to be set false.

The object returned here must be passed to edit().

$api->edit( $token, $text, $summary, $minor, $bot, %params )

Perform an edit to the page.

Note that the default configuration uses the assert parameter to assert that the current user has the "bot" flag. This means that the edit will fail if your bot is not flagged; the AnomieBOT trial.pl script overrides this default, so bot trials may still be done.

$api->upload( $token, %options )

Upload a file.

The $token must be obtained from $api->gettoken with the target file name passed as Title. To specify the file contents, exactly one of the following options must be given:

Url: Url that the MediaWiki server should download the file from.
HttpStatus: Do not actually upload anything, just return the status of the upload corresponding to the session key specified here.
FileKey: If the initial upload returned warnings (or Stash was used), specify the returned file key here to complete the upload. SessionKey is accepted as an alias for backwards compatability.
File: Filename on the local system to upload, accessible to the bot. Note the file will be read in binary (:raw) mode.
Handle: Open file handle from which the data to upload will be read.
Data: Raw file data to upload.

Additional options are:

Comment: Comment for the upload; note that MediaWiki will also use this for the initial file page text if the file does not already exist and Text is not used.
Text: Initial file page text if the file does not already exist, rather than using Comment.
AsyncDownload: When using Url, setting a true value here tells MediaWiki to return us a session key immediately (which may be passed to HttpStatus in a later call) rather than waiting for the download to actually complete.
IgnoreWarnings: Ignore any warnings.
Stash: Stash file temporarily.

$api->movetoken( $title )

$api->movetoken( $title, %options )

Obtain a move token for the specified page. Options are:

EditRedir: Move the redirect page, instead of the page it points to.
NoShutoff: Do not check the shutoff page. Don't do this frivolously.
NoExclusion: Do not check for {{bots}} / {{nobots}}. Don't do this frivolously.

The object returned here must be passed to move(). The object contains the same properties as that returned by edittoken(), plus the following:

can_suppressredirect: True if the $noredirect parameter to move() will be honored (i.e. the user has the 'suppressredirect' right).

$api->move( $token, $totitle, $reason, $movetalk, $noredirect ): Move the page to $totitle.
$api->action( $token, %param ): Perform an action that doesn't have a custom function. %param must contain an "action" key, as well as any other keys needed for the action ("token" may be omitted).

UTILITY METHODS

AnomieBOT::API::load( $file ): Load the task contained in the specified file, if it hasn't already been loaded.
$AnomieBOT::API::basedir: Returns the base directory for the bot.; Specifically, this returns the directory that contains AnomieBOT/API.pm. Note this may croak if you loaded AnomieBOT::API in some other way than require AnomieBOT::API; or use AnomieBOT::API;.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.