Provided by: libmediawiki-api-perl_0.39-1_all bug

NAME

       MediaWiki::API - Provides a Perl interface to the MediaWiki API
       (http://www.mediawiki.org/wiki/API)

VERSION

       Version 0.39

SYNOPSIS

       This module provides an interface between Perl and the MediaWiki API
       (http://www.mediawiki.org/wiki/API) allowing creation of scripts to automate editing and
       extraction of data from MediaWiki driven sites like Wikipedia.

         use MediaWiki::API;

         my $mw = MediaWiki::API->new();
         $mw->{config}->{api_url} = 'http://en.wikipedia.org/w/api.php';

         # log in to the wiki
         $mw->login( { lgname => 'username', lgpassword => 'password' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

         # get a list of articles in category
         my $articles = $mw->list ( {
           action => 'query',
           list => 'categorymembers',
           cmtitle => 'Category:Perl',
           cmlimit => 'max' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

         # and print the article titles
         foreach (@{$articles}) {
             print "$_->{title}\n";
         }

         # get user info
         my $userinfo = $mw->api( {
           action => 'query',
           meta => 'userinfo',
           uiprop => 'blockinfo|hasmsg|groups|rights|options|editcount|ratelimits' } );

           ...

FUNCTIONS

   MediaWiki::API->new( $config_hashref )
       Returns a MediaWiki API object. You can pass a config as a hashref when calling new, or
       set the configuration later. When creating a new object, defaults for max lag and retries
       are set.

         my $mw = MediaWiki::API->new( { api_url => 'http://en.wikipedia.org/w/api.php' }  );

       Configuration options are

       •   api_url = 'Path to mediawiki api.php';

       •   files_url = 'Base url for files'; (needed if the api returns a relative URL for images
           like /images/a/picture.jpg)

       •   upload_url = 'http://en.wikipedia.org/wiki/Special:Upload'; (path to the upload
           special page which is required if you want to upload images)

       •   on_error = Function reference to call if an error occurs in the module.

       •   use_http_get = Boolean 0 or 1 (defaults to 0). If set to 1, the perl module will use
           http GET method for accessing the api. By default it uses the POST method. Note that
           the module will still use POST for the api calls that require POST no matter what the
           value of this configuration option. Currently the following actions will work with
           GET: query, logout, purge, paraminfo - see get_actions configuration below.

       •   get_actions = Hashref (defaults to { 'query' => 1, 'logout' => 1, purge' => 1,
           'paraminfo' => 1 } ). This contains the API actions that are supported by the http GET
           method if it is enabled. Some wikis may have extensions that add more functions that
           work with an http GET request. If so, you can add actions as needed.

       •   retries = Integer value; The number of retries to send an API request if an http error
           or JSON decoding error occurs. Defaults to 0 (try only once - don't retry). If
           max_retries is set to 4, and the wiki is down, the error won't be reported until after
           the 5th connection attempt.

       •   retry_delay = Integer value in seconds; The amount of time to wait before retrying a
           request if an HTTP error or JSON decoding error occurs.

       •   max_lag = Integer value in seconds; Wikipedia runs on a database cluster and as such
           high edit rates cause the slave servers to lag. If this config option is set then if
           the lag is more then the value of max_lag, the api will wait before retrying the
           request. 5 is a recommended value. More information about this subject can be found at
           http://www.mediawiki.org/wiki/Manual:Maxlag_parameter. note the config option includes
           an underscore so match the naming scheme of the other configuration options.

       •   max_lag_delay = Integer value in seconds; This configuration option specified the
           delay to wait before retrying a request when the server has reported a lag more than
           the value of max_lag. This defaults to 5 if using the max_lag configuration option.

       •   max_lag_retries = Integer value; The number of retries to send an API request if the
           server has reported a lag more than the value of max_lag. If the maximum retries is
           reached, an error is returned. Setting this to a negative value like -1 will mean the
           request is resent until the servers max_lag is below the threshold or another error
           occurs. Defaults to 4.

       •   no_proxy = Boolean; Set to 1 to Disable use of any proxy set in the environment. Note
           by default if you have proxy environment variables set, then the module will attempt
           to use them. This feature was added at version 0.29. Versions below this ignore any
           proxy settings, but you can set this yourself by doing
           MediaWiki::API->{ua}->env_proxy() after creating a new instance of the API class. More
           information about env_proxy can be found at
           http://search.cpan.org/~gaas/libwww-perl-5.834/lib/LWP/UserAgent.pm#Proxy_attributes

       An example for the on_error configuration could be something like:

         $mw->{config}->{on_error} = \&on_error;

         sub on_error {
           print "Error code: " . $mw->{error}->{code} . "\n";
           print $mw->{error}->{stacktrace}."\n";
           die;
         }

       Errors are stored in $mw->{error}->{code} with more information in
       $mw->{error}->{details}. $mw->{error}->{stacktrace} includes the details and a stacktrace
       to locate where any problems originated from (in some code which uses this module for
       example).

       The error codes are as follows

       •   ERR_NO_ERROR = 0 (No error)

       •   ERR_CONFIG   = 1 (An error with the configuration)

       •   ERR_HTTP     = 2 (An http related connection error)

       •   ERR_API      = 3 (An error returned by the MediaWiki API)

       •   ERR_LOGIN    = 4 (An error logging in to the MediaWiki)

       •   ERR_EDIT     = 5 (An error with an editing function)

       •   ERR_PARAMS   = 6 (An error with parameters passed to a helper function)

       •   ERR_UPLOAD   = 7 (An error with the file upload facility)

       •   ERR_DOWNLOAD = 8 (An error with downloading a file)

       Other useful parameters and objects in the MediaWiki::API object are

       •   MediaWiki::API->{ua} = The LWP::UserAgent object. You could modify this to get or
           modify the cookies (MediaWiki::API->{ua}->cookie_jar) or to change the UserAgent
           string sent by this perl module (MediaWiki::API->{ua}->agent)

       •   MediaWiki::API->{response} = the last response object returned by the LWP::UserAgent
           after an API request.

   MediaWiki::API->login( $query_hashref )
       Logs in to a MediaWiki. Parameters are those used by the MediaWiki API
       (http://www.mediawiki.org/wiki/API:Login). Returns a hashref with some login details, or
       undef on login failure. If Mediawiki sends requests a LoginToken the login is attempted
       again, but with the token sent from the initial login. Errors are stored in
       MediaWiki::API->{error}->{code} and MediaWiki::API->{error}->{details}.

         my $mw = MediaWiki::API->new( { api_url => 'http://en.wikipedia.org/w/api.php' }  );

         #log in to the wiki
         $mw->login( {lgname => 'username', lgpassword => 'password' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

   MediaWiki::API->api( $query_hashref, $options_hashref )
       Call the MediaWiki API interface. Parameters are passed as a hashref which are described
       on the MediaWiki API page (http://www.mediawiki.org/wiki/API). returns a hashref with the
       results of the call or undef on failure with the error code and details stored in
       MediaWiki::API->{error}->{code} and MediaWiki::API->{error}->{details}. MediaWiki::API
       uses the LWP::UserAgent module to send the http requests to the MediaWiki API. After any
       API call, the response object returned by LWP::UserAgent is available in $mw->{response}.
       This function will NOT modify the input query_hashref in any way.

         binmode STDOUT, ':utf8';

         # get the name of the site
         if ( my $ref = $mw->api( { action => 'query', meta => 'siteinfo' } ) ) {
           print $ref->{query}->{general}->{sitename};
         }

         # list of titles for "Albert Einstein" in different languages.
         my $titles = $mw->api( {
           action => 'query',
           titles => 'Albert Einstein',
           prop => 'langlinks',
           lllimit => 'max' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

         my ($pageid,$langlinks) = each ( %{ $titles->{query}->{pages} } );

         foreach ( @{ $langlinks->{langlinks} } ) {
           print "$_->{'*'}\n";
         }

       MediaWiki's API uses UTF-8 and any 8 bit character string parameters are encoded
       automatically by the API call. If your parameters are already in UTF-8 this will be
       detected and the encoding will be skipped. If your parameters for some reason contain
       UTF-8 data but no UTF-8 flag is set (i.e. you did not use the "use utf8;" pragma) you
       should prevent re-encoding by passing an option skip_encoding => 1 in the $options_hash.
       For example:

        my $mw = MediaWiki::API->new();
        $mw->{config}->{api_url} = 'http://fr.wiktionary.org/w/api.php';

        my $query = {action => 'query',
          list => 'categorymembers',
          cmlimit => 'max'};

        $query->{cmtitle} ="Cat\x{e9}gorie:moyen_fran\x{e7}ais"; # latin1 string
        $mw->list ( $query ); # ok

        $query->{cmtitle} = "Cat". pack("U", 0xe9)."gorie:moyen_fran".pack("U",0xe7)."ais"; # unicode string
        $mw->list ( $query ); # ok

        $query->{cmtitle} ="Cat\x{c3}\x{a9}gorie:moyen_fran\x{c3}\x{a7}ais";  # unicode data without utf-8 flag
        # $mw->list ( $query ); # NOT OK
        $mw->list ( $query, {skip_encoding => 1} ); # ok

       If you are calling an API function which requires a file upload, e.g. import or upload,
       specify the file to upload as an arrayref containing the local filename. The API may
       return a warning, for example to say the file is a duplicate. To ignore warnings and force
       an upload, use ignorewarnings => 1. All the parameters as with everything else can be
       found on the MediaWiki API page.

        $mw->api( {
          action => 'import',
          xml => ['wiki_dump.xml']
         } );

        $mw->api( {
          action => 'upload',
          filename => 'test.png',
          comment => 'a test image',
          file => ['test.png'],
         } );

       You can also give the data to be uploaded directly, should you want to read the data in
       yourself. In this case, supply an arrayref with three parameters, starting with an
       "undef", followed by the filename, and then a Content => $data pair containing the data.

        $mw->api( {
          action => 'import',
          xml => [ undef, 'wiki_dump.xml', Content => $data ]
         } );

        $mw->api( {
          action => 'upload',
          filename => 'test.png',
          comment => 'a test image',
          file => [ undef, 'test.png', Content => $data ],
         } );

   MediaWiki::API->logout()
       Log the current user out and clear associated cookies and edit tokens.

   MediaWiki::API->edit( $query_hashref, $options_hashref )
       A helper function for doing edits using the MediaWiki API. Parameters are passed as a
       hashref which are described on the MediaWiki API editing page
       (http://www.mediawiki.org/wiki/API:Changing_wiki_content). Note that you need
       $wgEnableWriteAPI = true in your LocalSettings.php to use these features. This function
       will modify the input hashref.

       Currently

       •   Create/Edit pages (Mediawiki >= 1.13 )

       •   Move pages (Mediawiki >= 1.12 )

       •   Rollback (Mediawiki >= 1.12 )

       •   Delete pages (Mediawiki >= 1.12 )

       •   Upload images (Mediawiki >= 1.16 )

       •   Import pages (Mediawiki >= 1.15 )

       •   (Un)protect pages (Mediawiki >= 1.12 )

       •   (Un)block users (Mediawiki >= 1.12 )

       •   (Un)watch a page (Mediawiki >= 1.18 )

       •   Email user (Mediawiki >= 1.14 )

       •   Patrol changes (Mediawiki >= 1.14 )

       are supported via this call. Use this call to edit pages without having to worry about
       getting an edit token from the API first. The function will cache edit tokens to speed up
       future edits (Except for rollback edits, which are not cachable).

       Returns a hashref with the results of the call or undef on failure with the error code and
       details stored in MediaWiki::API->{error}->{code} and MediaWiki::API->{error}->{details}.

       The options hashref currently has one optional parameter (skip_encoding => 1). This is
       described above in the MediaWiki::API->api call documentation.

       Here are some example snippets of code. The first example is for adding some text to an
       existing page (if the page doesn't exist nothing will happen). Note that the timestamp for
       the revision we are changing is saved. This allows us to avoid edit conflicts. The value
       is passed back to the edit function, and if someone had edited the page in the meantime,
       an error will be returned.

         my $pagename = "Wikipedia:Sandbox";
         my $ref = $mw->get_page( { title => $pagename } );
         unless ( $ref->{missing} ) {
           my $timestamp = $ref->{timestamp};
           $mw->edit( {
             action => 'edit',
             title => $pagename,
             basetimestamp => $timestamp, # to avoid edit conflicts
             text => $ref->{'*'} . "\nAdditional text" } )
             || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};
         }

       The following code deletes a page with the name "DeleteMe". You can specify a reason for
       the deletion, otherwise a generated reason will be used.

         # delete a page
         $mw->edit( {
           action => 'delete', title => 'DeleteMe', reason => 'no longer needed' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

       This code moves a page from MoveMe to MoveMe2.

         # move a page
         $mw->edit( {
           action => 'move', from => 'MoveMe', to => 'MoveMe2' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

       The following scrippet rolls back one or more edits from user MrVandal. If the user is not
       the last editor of the page, an error will be returned. If no user is passed, the edits
       for whoever last changed the page will be rolled back.

         $mw->edit( {
           action => 'rollback', title => 'Sandbox', user => 'MrVandal' } )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

   MediaWiki::API->get_page( $params_hashref )
       A helper function for getting the most recent page contents (and other metadata) for a
       page. It calls the lower level api function with a revisions query to get the most recent
       revision.

         # get some page contents
         my $page = $mw->get_page( { title => 'Main Page' } );
         # print page contents
         print $page->{'*'};

       Returns a hashref with the following keys or undef on an error. If the page is missing
       then the returned hashref will contain only ns, title and a key called "missing".

       •   '*' - contents of page

       •   'pageid' - page id of page

       •   'revid' - revision id of page

       •   'timestamp' - timestamp of revision

       •   'user' - user who made revision

       •   'title' - the title of the page

       •   'ns' - the namespace the page is in

       •   'size' - size of page in bytes

       Full information about these can be read on
       (http://www.mediawiki.org/wiki/API:Query_-_Properties#revisions_.2F_rv)

   MediaWiki::API->list( $query_hashref, $options_hashref )
       A helper function for getting lists using the MediaWiki API. Parameters are passed as a
       hashref which are described on the MediaWiki API editing page
       (http://www.mediawiki.org/wiki/API:Query_-_Lists). This function modifies the input
       query_hashref.

       This function will return a reference to an array of hashes or undef on failure. It
       handles getting lists of data from the MediaWiki api, continuing the request with another
       connection if needed. The options_hashref currently has three parameters:

       •   max => value

       •   hook => \&function_hook

       •   skip_encoding => 1

       The value of max specifies the maximum "queries" which will be used to pull data out. For
       example the default limit per query is 10 items, but this can be raised to 500 for normal
       users and higher for sysops and bots. If the limit is raised to 500 and max was set to 2,
       a maximum of 1000 results would be returned.

       If you wish to process large lists, for example the articles in a large category, you can
       pass a hook function, which will be passed a reference to an array of results for each
       query connection.

       The skip_encoding parameter works as described above in the MediaWiki::API->api call
       documentation.

         binmode STDOUT, ':utf8';

         # process the first 400 articles in the main namespace in the category "Surnames".
         # get 100 at a time, with a max of 4 and pass each 100 to our hook.
         $mw->list ( { action => 'query',
                       list => 'categorymembers',
                       cmtitle => 'Category:Surnames',
                       cmnamespace => 0,
                       cmlimit=>'100' },
                     { max => 4, hook => \&print_articles } )
         || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

         # print the name of each article
         sub print_articles {
           my ($ref) = @_;
           foreach (@$ref) {
             print "$_->{title}\n";
           }
         }

   MediaWiki::API->upload( $params_hashref )
       This function is deprecated. For uploading on mediawiki versions 1.16 or later, you are
       recommended to use MediaWiki::API->edit or MediaWiki::API->api directly, which has much
       better error handling, and supports uploading files by just passing a filename.

       A function to upload files to a MediaWiki. This function does not use the MediaWiki API
       currently as support for file uploading is not yet implemented. Instead it uploads using
       the Special:Upload page, and as such an additional configuration value is needed.

         my $mw = MediaWiki::API->new( {
          api_url => 'http://en.wikipedia.org/w/api.php' }  );
         # configure the special upload location.
         $mw->{config}->{upload_url} = 'http://en.wikipedia.org/wiki/Special:Upload';

       The upload function is then called as follows

         # upload a file to MediaWiki
         open FILE, "myfile.jpg" or die $!;
         binmode FILE;
         my ($buffer, $data);
         while ( read(FILE, $buffer, 65536) )  {
           $data .= $buffer;
         }
         close(FILE);

         $mw->upload( { title => 'file.jpg',
                        summary => 'This is the summary to go on the Image:file.jpg page',
                        data => $data } ) || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

       Error checking is limited. Also note that the module will force a file upload, ignoring
       any warning for file size or overwriting an old file.

   MediaWiki::API->download( $params_hashref )
       A function to download images/files from a MediaWiki. A file url may need to be configured
       if the api returns a relative URL.

         my $mw = MediaWiki::API->new( {
           api_url => 'http://www.exotica.org.uk/mediawiki/api.php' }  );
         # configure the file url. Wikipedia doesn't need this but the ExoticA wiki does.
         $mw->{config}->{files_url} = 'http://www.exotica.org.uk';

       The download function is then called as follows

         my $file = $mw->download( { title => 'Image:Mythic-Beasts_Logo.png'} )
           || die $mw->{error}->{code} . ': ' . $mw->{error}->{details};

       If the file does not exist (on the wiki) an empty string is returned. If the file is
       unable to be downloaded undef is returned.

AUTHOR

       Jools 'BuZz' Wills, "<buzz [at] exotica.org.uk>"

BUGS

       Please report any bugs or feature requests to "bug-mediawiki-api at rt.cpan.org", or
       through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MediaWiki-API
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MediaWiki-API>.  I will be notified, and
       then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc MediaWiki::API

       You can also look for information at:

       •   RT: CPAN's request tracker

           http://rt.cpan.org/NoAuth/Bugs.html?Dist=MediaWiki-API
           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MediaWiki-API>

       •   AnnoCPAN: Annotated CPAN documentation

           http://annocpan.org/dist/MediaWiki-API <http://annocpan.org/dist/MediaWiki-API>

       •   CPAN Ratings

           http://cpanratings.perl.org/d/MediaWiki-API <http://cpanratings.perl.org/d/MediaWiki-
           API>

       •   Search CPAN

           http://search.cpan.org/dist/MediaWiki-API <http://search.cpan.org/dist/MediaWiki-API>

ACKNOWLEDGEMENTS

       •   Carl Beckhorn (cbeckhorn [at] fastmail.fm) for ideas and support

       •   Stuart 'Kyzer' Caie (kyzer [at] 4u.net) for UnExoticA perl code and support

       •   Edward Chernenko (edwardspec [at] gmail.com) for his earlier MediaWiki module

       •   Dan Collins (EN.WP.ST47 [at] gmail.com) for bug reports and patches

       •   Jonas 'Spectral' Nyren (spectral [at] ludd.luth.se) for hints and tips!

       •   Jason 'XtC' Skelly (xtc [at] amigaguide.org) for moral support

       •   Nikolay Shaplov (n [at] shaplov.ru) for utf-8 patches and testing

       •   Jeremy Muhlich (jmuhlich [at] bitflood.org) for utf-8 patches and testing for api
           upload support patch

COPYRIGHT & LICENSE

       Copyright 2008 - 2012 Jools Wills, all rights reserved.

       This program is free software: you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation, either
       version 3 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program.
       If not, see <http://www.gnu.org/licenses/>.