go-mwclient: gitlab.com/melancholera/go-mwclient Index | Files | Directories

package mwclient

import "gitlab.com/melancholera/go-mwclient"

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.

// Initialize a *Client with New(), specifying the wiki's API URL
// and your HTTP User-Agent. Try to use a meaningful User-Agent.
w, err := mwclient.New("https://en.wikipedia.org/w/api.php", "myWikibot")
if err != nil {
	panic(err) // Malformed URL

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

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 map (from the gitlab.com/melancholera/go-mwclient/params package), receive a response and an error.

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


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, rather than a map[string]string. This is because url.Values must support multiple keys with the same name.

The literal syntax for a map[string][]string is rather cumbersome because the value is a slice rather than just a string, and the MediaWiki API actually does not use multiple keys when multiple values for the same key is required. Instead, one key is used and the values are separated by pipes (|). It is therefore very simple to write multi-value values in params.Values literals while

params.Values makes it simple to write multi-value values in literals while avoiding the cumbersome []string literals for the most common case where the is only value.

See documentation for the params package for more information.

Because of the way type identity works in Go, it is possible for callers to pass a plain map[string]string rather than a params.Values. It is only necessary for users to use params.Values directly if they wish to use params.Values's methods. It makes no difference to go-mwclient.

Error handling

If an API call fails 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 APIError or an APIWarnings object, both of which implement the error interface. The "Raw" request methods do not check for API errors or warnings.

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.


Package Files

cookies.go core.go doc.go edit.go errors.go files.go query.go site.go


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

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

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:

const DefaultUserAgent = "[https://gitlab.com/melancholera/go-mwclient go-mwclient]"

DefaultUserAgent is the HTTP User-Agent used by default.


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.

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.

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

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

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

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

type APIError Uses

type APIError struct {
    Code, Info string

APIError represents a MediaWiki API error.

func (APIError) Error Uses

func (e APIError) Error() string

type APIWarnings Uses

type APIWarnings []struct {
    Module, Info string

APIWarnings represents a collection of MediaWiki API warnings.

func (APIWarnings) Error Uses

func (w APIWarnings) Error() string

type BriefRevision Uses

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

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

type CaptchaError Uses

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 Uses

func (e CaptchaError) Error() string

type Client Uses

type Client struct {

    // HTTP user agent
    UserAgent string
    // API token cache.
    // Maps from name of token (e.g., "csrf") to token value.
    // Use GetToken to obtain tokens.
    Tokens map[string]string
    // Maxlag contains maxlag configuration for Client.
    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 Uses

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

The userAgent parameter will be joined with the DefaultUserAgent const and used as HTTP User-Agent. If userAgent is an empty string, DefaultUserAgent will be used by itself as User-Agent. The User-Agent set by New can be overriden by setting the UserAgent field on the returned *Client.

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) Download Uses

func (w *Client) Download(filename string) (io.ReadCloser, error)

Download creates a copy of a file to a ReadCloser and an applicable error. Note that filename should be, for instance, "Test.jpg" and NOT "File:Test.jpg" or "Fichier:Test.jpg". The namespace should be ommitted. The File namespace will be added automatically and normalization would convert page titles to their canonical form, that is, changing the namespace to their localized form.

func (*Client) DownloadToFile Uses

func (w *Client) DownloadToFile(remote, local string, overwrite bool) error

DownloadToFile downloads File:remote to a file named local. Note that remote should be, for instance, "Test.jpg" and NOT "File:Test.jpg" or "Fichier:Test.jpg". The namespace should be ommitted. Returns an error if it could not download said file, if local is blank or invalid, or if local exists in the current folder, unless if overwrite is set to True. Local file will be overwritten if overwrite is set to True.

func (*Client) DumpCookies Uses

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

DumpCookies exports the cookies stored in the client.

func (*Client) Edit Uses

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:


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

	"pageid":   "709377",
	"text":     "Complete new text for page",
	"summary":  "Take that, page!",
	"notminor": "",

If p is nil then it will return an error

func (*Client) Get Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

LoadCookies imports cookies into the client.

func (*Client) LocalizedNamespace Uses

func (w *Client) LocalizedNamespace(canonical string) (string, error)

LocalizedNamespace returns the localized version of some canonical namespace and an error

func (*Client) Login Uses

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

Login attempts to login using the provided username and password. Do not use Login with OAuth.

func (*Client) Logout Uses

func (w *Client) Logout() error

Logout sends a logout request to the API. Logout does not take into account whether or not a user is actually logged in. Do not use Logout with OAuth.

func (*Client) Namespaces Uses

func (w *Client) Namespaces() (map[string]string, error)

Namespaces returns a map[string]string containing the canonical names for a page's namespaces as keys and the localized names as values. This means that, for fr.wikipedia.org, Namespaces["Talk"] will return "Discussion" as the localized term for the Talk namespace.

func (*Client) NewQuery Uses

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

NewQuery instantiates a new query with the given parameters. Automatically sets action=query and continue= on the provided params.Values.

func (*Client) OAuth Uses

func (w *Client) OAuth(consumerToken, consumerSecret, accessToken, accessSecret string) error

OAuth configures OAuth authentication. After calling OAuth, future requests will be authenticated. OAuth does not make any API calls, so authentication failures will appear in response to the first API call after OAuth has been configured. Do not mix use of OAuth with Login/Logout.

func (*Client) Post Uses

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 Uses

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) PostToken Uses

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

PostToken acts like GetToken but performs a POST Request instead of a GET Request. May be useful if GetToken cannot get the token properly, e.g., in uploading files.

func (*Client) Replace Uses

func (w *Client) Replace(old, new string, p params.Values) error

Replace replaces all text in a given page using strings.ReplaceAll. All matches of old will be replaced by new. If old is empty, it matches at the beginning of the string and after each UTF-8 sequence, yielding up to k+1 replacements for a k-rune page content. If the page has been edited between when the Page is downloaded via GetPageByName and when the edits are written via Edit, it will result in an editconflict. Default edit summary is "Replaced '`old`' with '`new`'. Edited using `w.UserAgent`". p is similar to that of Edit. p example:

	"pageid":   "709377",
	"summary":  "Replaced some text",	// will override default edit summary
	"notminor": "",

Either p["title"] or p["pageid"] must be set. p["pageid"] overrides p["title"], even if p["pageid"] were blank. If p is nil then it will return an error.

func (*Client) SetDebug Uses

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

func (*Client) SetHTTPTimeout Uses

func (w *Client) SetHTTPTimeout(timeout time.Duration)

SetHTTPTimeout overrides the default HTTP client timeout of 30 seconds. This is not related to the maxlag timeout.

func (*Client) Upload Uses

func (w *Client) Upload(file io.Reader, filename string, p params.Values) (*jason.Object, error)

Upload performs a simple upload of a file to some filename and returns the response. Note that this will not provide page contents and edit summary, among other parameters that should be set manually in parameters. The p (params.Values) argument should contain parameters from:


p example:

	"filename":       "Some file.jpg",       // "File:" will be added anyway; will override filename
	"comment":        "Uploaded osomething", // will override default upload comment
	"text":           "Look at this file I uploaded!",
	"ignorewarnings": "",  // ignorewarnings specified means true even if blank

If p is nil then it is as if no optional parameters were passed. If p["filename"] exists then it overrides filename. Upload will set the 'action' and 'token' parameters automatically, but if the token field in p is non-empty, Upload will not override it. Setting p["url"], p["chunk"], p["filekey"], or p["sessionkey"] may yield undefined behavior. The default comment is "Uploaded via w.UserAgent".

func (*Client) Version Uses

func (w *Client) Version() (*semver.Version, error)

Version returns the semantic version (https://github.com/Masterminds/semver) of the MediaWiki server the Client is tied to.

type Maxlag Uses

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 Uses

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.

Query is most useful for retrieving large result sets that may not fit in a single response. For simple queries that are known to always return small result sets it likely makes more sense to just make the query directly with the *Client.Get method.

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() {
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 Uses

func (q *Query) Err() error

Err returns the first error encountered by the Next method.

func (*Query) Next Uses

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 Uses

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

Resp returns the API response retrieved by the Next method.


paramsPackage params is a MediaWiki specific replacement for parts of net/url.

Package mwclient imports 19 packages (graph) and is imported by 1 packages. Updated 2020-02-11. Refresh now. Tools for package owners.