mwclient

package module
v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Jul 20, 2023 License: CC0-1.0 Imports: 16 Imported by: 25

README

go-mwclient

go-mwclient is a Go package for interacting with the MediaWiki JSON API.

go-mwclient aims to be a thin wrapper around the MediaWiki API that takes care of the most tedious parts of interacting with the API (such as authentication and query continuation), but it does not aim to abstract away all the functionality of the API.

go-mwclient v1 uses version 2 of the MediaWiki JSON API.

The canonical import path for this package is

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

Documentation:

As of v1.0.0, go-mwclient uses semantic versioning. The master branch contains the most recent v1.x.x release.

Installation

go get -u cgt.name/pkg/go-mwclient

Example

package main

import (
    "fmt"

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

func main() {
    // 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)
    }

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

    // Specify parameters to send.
    parameters := map[string]string{
        "action":   "query",
        "list":     "recentchanges",
        "rclimit":  "2",
        "rctype":   "edit",
        "continue": "",
    }

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

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

Dependencies

Other than the standard library, go-mwclient depends on the following third party, open source packages:

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

params package

The params package is based on the net/url package from the Go standard library, which is released under a BSD-style license. See params/LICENSE.

Contributions to the params package as part of this project are released to the public domain via CC0, as noted above and specified in the COPYING file.

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.

go-mwclient v1 uses version 2 of the MW JSON API.

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 {
	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 map (from the cgt.name/pkg/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

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.

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

DefaultUserAgent is the HTTP User-Agent used by default.

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 {

	// 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

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) 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. Note that the request may automatically be converted to a POST request if the parameters it is passed are too large; the MediaWiki API accepts POST on all endpoints. 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. Note that the request may automatically be converted to a POST request if the parameters it is passed are too large; the MediaWiki API accepts POST on all endpoints. 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. Do not use Login with OAuth.

func (*Client) Logout

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

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

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

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

func (*Client) SetHTTPClient added in v1.1.0

func (w *Client) SetHTTPClient(httpc *http.Client)

SetHTTPClient overrides the default http.Client.

func (*Client) SetHTTPTimeout

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.

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.

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

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