mwclient

package module
v0.0.0-...-baa4e30 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 24, 2016 License: CC0-1.0 Imports: 15 Imported by: 0

README

go-mwclient

go-mwclient is a library for interacting with the MediaWiki API. The package's actual name is "mwclient", but it is called "go-mwclient" to avoid confusion with similarly named libraries using other languages.

The canonical import path for this package is

import cgt.name/pkg/go-mwclient // imports "mwclient"

Documentation:

Installation

go get cgt.name/pkg/go-mwclient

API stability

go-mwclient's API seems to have stabilized. It probably won't change significantly, if at all.

Example

package main

import (
    "fmt"

    "cgt.name/pkg/go-mwclient"
    "cgt.name/pkg/go-mwclient/params"
)

func main() {
    // Make a Client object and specify the wiki's API URL and your user agent.
    w, err := mwclient.New("https://en.wikipedia.org/w/api.php", "Username's wikibot")
    if err != nil {
        panic(err)
    }

    // Log in.
    err = w.Login("USERNAME", "PASSWORD")
    if err != nil {
        fmt.Println(err)
    }

    // Specify parameters to send.
    parameters := params.Values{
        "action":   "query",
        "list":     "recentchanges",
        "rclimit":  "2",
        "rctype":   "edit",
        "continue": "",
    }

    // Make the request.
    resp, err := w.Get(parameters)
    if err != nil {
        fmt.Println(err)
    }

    // Print the *jason.Object
    fmt.Println(resp)
}

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.

You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.

Documentation

Overview

Package mwclient provides functionality for interacting with the MediaWiki API.

go-mwclient is intended for users who are already familiar with (or are willing to learn) the MediaWiki API. It is intended to make dealing with the API more convenient, but not to hide it.

Basic usage

In the example below, basic usage of go-mwclient is shown. 

wiki, err := mwclient.New("https://wiki.example.com/w/api.php", "my user agent")
if err != nil {
	// Malformed URL or empty user agent
	panic(err)
}

parameters := params.Values{
	"action":   "query",
	"list":     "recentchanges",
}
response, err := wiki.Get(parameters)
if err != nil {
	panic(err)
}

Create a new Client object with the New() constructor, and then you are ready to start making requests to the API. If you wish to make requests to multiple MediaWiki sites, you must create a Client for each of them.

go-mwclient offers a few methods for making arbitrary requests to the API: Get, GetRaw, Post, and PostRaw (see documentation for the methods for details). They all offer the same basic interface: pass a params.Values (from the cgt.name/pkg/go-mwclient/params package), receive a response and an error.

params.Values is similar to (and a fork of) the standard library's net/url.Values. The reason why params.Values is used instead is that url.Values is based on a map[string][]string because it must allow multiple keys with the same name. However, the literal syntax for such a map is rather cumbersome, and the MediaWiki API actually does not use multiple keys when multiple values for the same key is desired. Instead, one key is used and the values are separated by pipes (|). Therefore, the decision to use params.Values (which is based on map[string]string) instead was made.

For convenience, go-mwclient offers several methods for making common requests (login, edit, etc.), but these methods are implemented using the same interface.

Error handling

If an API call fails, for whatever reason, it will return an error. Many things can go wrong during an API call: the network could be down, the API could return an unexpected response (if the API was changed), or perhaps there's an error in your API request.

If the error is an API error or warning (and you used the "non-Raw" Get and Post methods), then the error/warning(s) will be parsed and returned in either an mwclient.APIError or an mwclient.APIWarnings object, both of which implement the error interface.

For more information about API errors and warnings, please see https://www.mediawiki.org/wiki/API:Errors_and_warnings.

If maxlag is enabled, it may be that the API has rejected the requests and the amount of retries (3 by default) have been tried unsuccessfully. In that case, the error will be the variable mwclient.ErrAPIBusy.

Other methods than the core ones (i.e., other methods than Get and Post) may return other errors.

Index

Constants

View Source 
const (
	// AssertNone is used to disable API assertion
	AssertNone assertType = iota
	// AssertUser is used to assert that the client is logged in
	AssertUser
	// AssertBot is used to assert that the client is logged in as a bot
	AssertBot
)

These consts are used as enums for the Client type's Assert field.

View Source 
const (
	CSRFToken                   = "csrf"
	DeleteGlobalAccountToken    = "deleteglobalaccount"
	PatrolToken                 = "patrol"
	RollbackToken               = "rollback"
	SetGlobalAccountStatusToken = "setglobalaccountstatus"
	UserRightsToken             = "userrights"
	WatchToken                  = "watch"
	LoginToken                  = "login"
)

These consts represents MW API token names. They are meant to be used with the GetToken method like so: 

ClientInstance.GetToken(mwclient.CSRFToken)
View Source 
const DefaultUserAgent = "go-mwclient (https://github.com/cgt/go-mwclient)"

If you modify this package, please change the user agent.

Variables

View Source 
var ErrAPIBusy = errors.New("the API is too busy. Try again later")

ErrAPIBusy is the error returned by an API call function when maxlag is enabled, and the API responds that it is busy for each of the in Client.Maxlag.Retries specified amount of retries.

View Source 
var ErrEditNoChange = errors.New("edit successful, but did not change page")

ErrEditNoChange is returned by Client.Edit() when an edit did not change a page but was otherwise successful.

View Source 
var ErrNoArgs = errors.New("no arguments passed")

ErrNoArgs is returned by API call methods that take variadic arguments when no arguments are passed.

View Source 
var ErrPageNotFound = errors.New("wiki page not found")

ErrPageNotFound is returned when a page is not found. See GetPage[s]ByName().

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Code, Info string
}

APIError represents a MediaWiki API error.

func (APIError) Error 

func (e APIError) Error() string

type APIWarnings 

type APIWarnings []struct {
	Module, Info string
}

APIWarnings represents a collection of MediaWiki API warnings.

func (APIWarnings) Error 

func (w APIWarnings) Error() string

type BriefRevision 

type BriefRevision struct {
	Content   string
	Timestamp string
	Error     error
	PageID    string
}

BriefRevision contains basic information on a single revision of a page.

type CaptchaError 

type CaptchaError struct {
	Type     string `json:"type"`
	Mime     string `json:"mime"`
	ID       string `json:"id"`
	URL      string `json:"url"`
	Question string `json:"question"`
}

CaptchaError represents the error returned by the API when it requires the client to solve a CAPTCHA to perform the action requested.

func (CaptchaError) Error 

func (e CaptchaError) Error() string

type Client 

type Client struct {
	UserAgent string
	Tokens    map[string]string
	Maxlag    Maxlag
	// If Assert is assigned the value of consts AssertUser or AssertBot,
	// the 'assert' parameter will be added to API requests with
	// the value 'user' or 'bot', respectively. To disable such assertions,
	// set Assert to AssertNone (set by default by New()).
	Assert assertType
	// contains filtered or unexported fields
}

Client represents the API client.

func New 

func New(inURL, userAgent string) (*Client, error)

New returns a pointer to an initialized Client object. If the provided API URL is invalid (as defined by the net/url package), then it will return nil and the error from url.Parse(). If the user agent is empty, this will also result in an error. The userAgent parameter will be combined with the DefaultUserAgent const to form a meaningful user agent. If this is undesired, the UserAgent field on the Client is exported and can therefore be set manually. New disables maxlag by default. To enable it, simply set Client.Maxlag.On to true. The default timeout is 5 seconds and the default amount of retries is 3.

func (*Client) DumpCookies 

func (w *Client) DumpCookies() []*http.Cookie

DumpCookies exports the cookies stored in the client.

func (*Client) Edit 

func (w *Client) Edit(p params.Values) error

Edit takes a params.Values containing parameters for an edit action and attempts to perform the edit. Edit will return nil if no errors are detected. If the edit was successful, but did not result in a change to the page (i.e., the new text was identical to the current text) then ErrEditNoChange is returned. The p (params.Values) argument should contain parameters from: 

https://www.mediawiki.org/wiki/API:Edit#Parameters

Edit will set the 'action' and 'token' parameters automatically, but if the token field in p is non-empty, Edit will not override it. Edit does not check p for sanity. p example: 

params.Values{
	"pageid":   "709377",
	"text":     "Complete new text for page",
	"summary":  "Take that, page!",
	"notminor": "",
}

func (*Client) Get 

func (w *Client) Get(p params.Values) (*jason.Object, error)

Get performs a GET request with the specified parameters and returns the response as a *jason.Object. Get will return any API errors and/or warnings (if no other errors occur) as the error return value.

func (*Client) GetPageByID 

func (w *Client) GetPageByID(pageID string) (content string, timestamp string, err error)

GetPageByID gets the content of a page (specified by its id) and the timestamp of its most recent revision.

func (*Client) GetPageByName 

func (w *Client) GetPageByName(pageName string) (content string, timestamp string, err error)

GetPageByName gets the content of a page (specified by its name) and the timestamp of its most recent revision.

func (*Client) GetPagesByID 

func (w *Client) GetPagesByID(pageIDs ...string) (pages map[string]BriefRevision, err error)

GetPagesByID gets the content of pages (specified by id). Returns a map of input page names to BriefRevisions.

func (*Client) GetPagesByName 

func (w *Client) GetPagesByName(pageNames ...string) (pages map[string]BriefRevision, err error)

GetPagesByName gets the contents of multiple pages (specified by their names). Returns a map of input page names to BriefRevisions.

func (*Client) GetRaw 

func (w *Client) GetRaw(p params.Values) ([]byte, error)

GetRaw performs a GET request with the specified parameters and returns the raw JSON response as a []byte. Unlike Get, GetRaw does not check for API errors/warnings. GetRaw is useful when you want to decode the JSON into a struct for easier and safer use.

func (*Client) GetToken 

func (w *Client) GetToken(tokenName string) (string, error)

GetToken returns a specified token (and an error if this is not possible). If the token is not already available in the Client.Tokens map, it will attempt to retrieve it via the API. tokenName should be "edit" (or whatever), not "edittoken". The token consts (e.g., mwclient.CSRFToken) should be used as the tokenName argument.

func (*Client) LoadCookies 

func (w *Client) LoadCookies(cookies []*http.Cookie)

LoadCookies imports cookies into the client.

func (*Client) Login 

func (w *Client) Login(username, password string) error

Login attempts to login using the provided username and password. Login sets Client.Assert to AssertUser if login is successful.

func (*Client) Logout 

func (w *Client) Logout()

Logout sends a logout request to the API. Logout does not take into account whether or not a user is actually logged in. Logout sets Client.Assert to AssertNone.

func (*Client) NewQuery 

func (w *Client) NewQuery(p params.Values) *Query

NewQuery instantiates a new query with the given parameters.

func (*Client) Post 

func (w *Client) Post(p params.Values) (*jason.Object, error)

Post performs a POST request with the specified parameters and returns the response as a *jason.Object. Post will return any API errors and/or warnings (if no other errors occur) as the error return value.

func (*Client) PostRaw 

func (w *Client) PostRaw(p params.Values) ([]byte, error)

PostRaw performs a POST request with the specified parameters and returns the raw JSON response as a []byte. Unlike Post, PostRaw does not check for API errors/warnings. PostRaw is useful when you want to decode the JSON into a struct for easier and safer use.

func (*Client) SetDebug 

func (w *Client) SetDebug(wr io.Writer)

SetDebug takes an io.Writer to which HTTP requests and responses made by Client will be dumped with httputil to as they are sent and received. To disable, set to nil (default).

type Maxlag 

type Maxlag struct {
	// If true, API requests will set the maxlag parameter.
	On bool
	// The maxlag parameter to send to the server.
	Timeout string
	// Specifies how many times to retry a request before returning with an error.
	Retries int
	// contains filtered or unexported fields
}

Maxlag contains maxlag configuration for Client. See https://www.mediawiki.org/wiki/Manual:Maxlag_parameter

type Query 

type Query struct {
	// contains filtered or unexported fields
}

Query provides a simple interface to deal with query continuations. A Query should be instantiated through the NewQuery method on the Client type. Once you have instantiated a Query, call the Next method to retrieve the first set of results from the API. If Next returns false, then either you have received all the results for the query or an error occurred. If an error occurs, it will be available through the Err method. If Next returns true, then there are more results to be retrieved and another call to Next will retrieve the next results.

The following example will retrieve all the pages that are in the category "Soap": 

p := params.Values{
	"list": "categorymembers",
	"cmtitle": "Category:Soap",
}
q := w.NewQuery(p) // w being an instantiated Client
for q.Next() {
	fmt.Println(q.Resp())
}
if q.Err() != nil {
	// handle the error
}

See https://www.mediawiki.org/wiki/API:Query for more details on how to query the MediaWiki API.

func (Query) Err 

func (q Query) Err() error

Err returns the first error encountered by the Next method.

func (*Query) Next 

func (q *Query) Next() (done bool)

Next retrieves the next set of results from the API and makes them available through the Resp method. Next returns true if new results are available through Resp or false if there were no more results to request or if an error occurred.

func (Query) Resp 

func (q Query) Resp() *jason.Object

Resp returns the API response retrieved by the Next method.

Source Files

View all Source files

Directories

Path Synopsis
Package params is a MediaWiki specific replacement for parts of net/url.
 Package params is a MediaWiki specific replacement for parts of net/url.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.