mwclient

package module
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Feb 2, 2020 License: MIT Imports: 19 Imported by: 1

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.

The canonical import path for this package is

import gitlab.com/melancholera/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 gitlab.com/melancholera/go-mwclient

Example

package main

import (
    "fmt"

    "gitlab.com/melancholera/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:

More information in LICENSE.md and NOTICES.md.

MIT License

Copyright (c) 2019 Vibrio Melancholia and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Up to commit a3c2125a58513016d41ede1a0978f7a16f2612ca

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.

files.go from github.com/sadbox/mediawiki

files.go contains code that has been taken from or at least inspired from github.com/sadbox/mediawiki, which is licensed under the MIT license.

Licenses for other software used

This project would not have been possible if it weren't for the dependencies it uses. Copyright information can be viewed in NOTICES.md.

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. 

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

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 = "[https://gitlab.com/melancholera/go-mwclient 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) Download 

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 

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 

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. p example: 

params.Values{
	"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 

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

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

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

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

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 

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

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 

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: 

params.Values{
	"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 

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 

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 

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: 

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

p example: 

params.Values{
	"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 

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 

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.

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.