MediaWiki::API man page on Debian

Man page or keyword search:  
man Server   8174 pages
apropos Keyword Search (all sections)
Output format
Debian logo
[printable version]

MediaWiki::API(3pm)   User Contributed Perl Documentation  MediaWiki::API(3pm)

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

VERSION
       Version 0.35

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.

       ·   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

   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 only

       ·   Create/Edit pages (Mediawiki >= 1.13 )

       ·   Move pages  (Mediawiki >= 1.12 )

       ·   Rollback  (Mediawiki >= 1.12 )

       ·   Delete pages	 (Mediawiki >= 1.12 )

       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 )
       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>.	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>

       ·   AnnoCPAN: Annotated CPAN documentation

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

       ·   CPAN Ratings

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

       ·   Search CPAN

	   <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

COPYRIGHT & LICENSE
       Copyright 2008 - 2010 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/>.

perl v5.10.1			  2010-08-29		   MediaWiki::API(3pm)
[top]

List of man pages available for Debian

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net