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
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  property containing the full HTML returned with the error, and a   property with the HTTP response code.
 * jsonerror
 * The response string could not be decoded. The object will also contain a  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  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  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.


 * AnomieBOT&#58;&#58;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 . 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 . 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  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&#58;&#58;API&#58;&#58;copy_truncate_file( $from, $to, $fh )
 * Copy file  to   (gzipping on the way), then truncate via.


 * $api->rotate_logs
 * Rotate the log files.


 * $api->warn( $message )
 * AnomieBOT&#58;&#58;API->warn( $message )
 * $api->log( $message )
 * AnomieBOT&#58;&#58;API->log( $message )
 * $api->debug( $bitmask, $message )
 * AnomieBOT&#58;&#58;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  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  value. Valid values are specified by the API, currently ,  ,  , or  . The default is.
 * 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->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  and returns the database handle.
 * If  is not set in conf.ini, dies instead.
 * replaces a  token in  . 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, 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  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  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  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  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, 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  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 true] value for.


 * $api->logout
 * Log the bot out.


 * $api->gettoken( $type )
 * $api->gettoken( $type, %options )
 * Obtain a token of the specified type (see the  module). Available options are:
 * Title
 * In addition to the token, fetch information for the specified title.
 * Redir
 * Follow redirects, if  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  and set this to the appropriate token as detailed at Template:bots#Message notification opt out.
 * NoExclusion
 * Do not check for bots / nobots in . Don't do this frivolously.
 * links
 * images
 * templates
 * categories
 * [etc]
 * If specified, the corresponding API  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,  will include all the page links and the hidden categories in the returned object.
 * Valid keys are all prop modules.
 * and  are always queried, with ,  , and.
 * The object returned will have properties  and   as usual,   holding the token,   holding the timestamp,   holding the current user's rights, and if   was specified the properties returned for a query of that title.
 * If the bot is not logged in,  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, with the following differences:
 * is always passed.
 * is set, unless  is true.
 * In addition to the options available for, the following are available:
 * EditRedir
 * is defaulted to true. This causes  to be set false.
 * The object returned here must be passed to.


 * $api->edit( $token, $text, $summary, $minor, $bot, %params )
 * Perform an edit to the page.
 * Note that the default configuration uses the  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  must be obtained from   with the target file name passed as  . 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  was used), specify the returned file key here to complete the upload.   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 :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  is not used.
 * Text
 * Initial file page text if the file does not already exist, rather than using.
 * 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 . The object contains the same properties as that returned by , plus the following:
 * can_suppressredirect
 * True if the  parameter to   will be honored (i.e. the user has the 'suppressredirect' right).


 * $api->move( $token, $totitle, $reason, $movetalk, $noredirect )
 * Move the page to.


 * $api->action( $token, %param )
 * Perform an action that doesn't have a custom function.  must contain an "action" key, as well as any other keys needed for the action ("token" may be omitted).

UTILITY METHODS

 * AnomieBOT&#58;&#58;API&#58;&#58;load( $file )
 * Load the task contained in the specified file, if it hasn't already been loaded.


 * $AnomieBOT&#58;&#58;API&#58;&#58;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  or.

COPYRIGHT
Copyright 2008–2013 Anomie

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