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
- Variables
- type APIError
- type APIWarnings
- type BriefRevision
- type CaptchaError
- type Client
- func (w *Client) DumpCookies() []*http.Cookie
- func (w *Client) Edit(p params.Values) error
- func (w *Client) Get(p params.Values) (*jason.Object, error)
- func (w *Client) GetPageByID(pageID string) (content string, timestamp string, err error)
- func (w *Client) GetPageByName(pageName string) (content string, timestamp string, err error)
- func (w *Client) GetPagesByID(pageIDs ...string) (pages map[string]BriefRevision, err error)
- func (w *Client) GetPagesByName(pageNames ...string) (pages map[string]BriefRevision, err error)
- func (w *Client) GetRaw(p params.Values) ([]byte, error)
- func (w *Client) GetToken(tokenName string) (string, error)
- func (w *Client) LoadCookies(cookies []*http.Cookie)
- func (w *Client) Login(username, password string) error
- func (w *Client) Logout() error
- func (w *Client) NewQuery(p params.Values) *Query
- func (w *Client) OAuth(consumerToken, consumerSecret, accessToken, accessSecret string) error
- func (w *Client) Post(p params.Values) (*jason.Object, error)
- func (w *Client) PostRaw(p params.Values) ([]byte, error)
- func (w *Client) SetDebug(wr io.Writer)
- func (w *Client) SetHTTPClient(httpc *http.Client)
- func (w *Client) SetHTTPTimeout(timeout time.Duration)
- type Maxlag
- type Query
Constants ¶
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.
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)
const DefaultUserAgent = "go-mwclient (https://github.com/cgt/go-mwclient)"
DefaultUserAgent is the HTTP User-Agent used by default.
Variables ¶
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().
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
Code, Info string
}
APIError represents a MediaWiki API error.
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 ¶
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 ¶
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 ¶
DumpCookies exports the cookies stored in the client.
func (*Client) Edit ¶
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 ¶
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 ¶
GetPageByID gets the content of a page (specified by its id) and the timestamp of its most recent revision.
func (*Client) GetPageByName ¶
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 ¶
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 ¶
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 ¶
LoadCookies imports cookies into the client.
func (*Client) Login ¶
Login attempts to login using the provided username and password. Do not use Login with OAuth.
func (*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. Do not use Logout with OAuth.
func (*Client) NewQuery ¶
NewQuery instantiates a new query with the given parameters. Automatically sets action=query and continue= on the provided params.Values.
func (*Client) OAuth ¶
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 ¶
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 ¶
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 ¶
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
SetHTTPClient overrides the default http.Client.
func (*Client) SetHTTPTimeout ¶
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.