View Source Wiki.Action (mediawiki_client v0.4.0)

Adapter to the MediaWiki Action API

Most commands return a pipeable Wiki.Action.Session, which can be reused repeatedly.

Anonymous requests,

Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("dewiki")
|> Wiki.Action.new()
|> Wiki.Action.get!(
  action: :query,
  meta: :siteinfo,
  siprop: :statistics
)
# %Wiki.Action.Session{
#   __client__: %Tesla.Client{
#     adapter: {Tesla.Adapter.Hackney, :call, [[]]},
#     fun: nil,
#     post: [],
#     pre: [
#       {Tesla.Middleware.BaseUrl, :call, ["https://de.wikipedia.org/w/api.php"]},
#       {Tesla.Middleware.Compression, :call, [[format: "gzip"]]},
#       {Wiki.StatefulClient.CookieJar, :call, [[]]},
#       {Tesla.Middleware.FormUrlencoded, :call, [[]]},
#       {Tesla.Middleware.Headers, :call,
#       [[{"user-agent", "mediawiki_client_ex/0.2.6 (spam@ludd.net)"}]]},
#       {Tesla.Middleware.JSON, :call, [[]]}
#     ]
#   },
#   result: %{
#     "batchcomplete" => true,
#     "query" => %{
#       "statistics" => %{
#         "activeusers" => 19393,
#         "admins" => 188,
#         "articles" => 2583636,
#         "edits" => 211249646,
#         "images" => 130213,
#         "jobs" => 0,
#         "pages" => 7164514,
#         "queued-massmessages" => 0,
#         "users" => 3716049
#       }
#     }
#   },
#   state: [
#     cookies: %{
#       "GeoIP" => "DE:BE:Berlin:52.57:13.42:v4",
#       "WMF-Last-Access" => "04-Jun-2021",
#       "WMF-Last-Access-Global" => "04-Jun-2021"
#     }
#   ]
# }

Commands can be pipelined while accumulating results, and logged-in user permissions delegated by supplying a bot password.

Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("enwiki")
|> Wiki.Action.new(
  accumulate: true
)
|> Wiki.Action.authenticate!(
  Application.get_env(:example_app, :bot_username),
  Application.get_env(:example_app, :bot_password)
)
|> Wiki.Action.get!(
  action: :query,
  meta: :tokens,
  type: :csrf
)
|> (&Wiki.Action.post!(&1,
  action: :edit,
  title: "Sandbox",
  assert: :user,
  token: &1.result["query"]["tokens"]["csrftoken"],
  appendtext: "~~~~ was here."
)).()
|> Map.get(:result)

Streaming results from multiple requests using continuation,

Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("dewiki")
|> Wiki.Action.new()
|> Wiki.Action.stream(
  action: :query,
  list: :recentchanges,
  rclimit: 5
)
|> Stream.take(10)
|> Enum.flat_map(fn response -> response["query"]["recentchanges"] end)
|> Enum.map(fn rc -> rc["timestamp"] <> " " <> rc["title"] end)

wikibase

Wikibase

The Wikidata project provides structured data for other wiki projects, and can be accessed through the Action API.

Examples:

Search for entities called "alphabet",

Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("wikidatawiki")
|> Wiki.Action.new()
|> Wiki.Action.get!(
    action: :wbsearchentities,
    search: "alphabet",
    language: :en
)

Search for entities with "Frank Zappa" anywhere in the description or contents,

Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("wikidatawiki")
|> Wiki.Action.new()
|> Wiki.Action.get!(
    action: :wbsearchentities,
    search: "alphabet",
    language: :en
)

Retrieve all data about a specific entity with ID "Q42",

Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("wikidatawiki")
|> Wiki.Action.new()
|> Wiki.Action.get!(
    action: :wbgetentities,
    ids: "Q42"
)

defaults

Defaults

A few parameters are automatically added for convenience, but can be overridden if desired:

  • The :format parameter defaults to :json.
  • :formatversion defaults to 2.

Overriding to get pretty-printed JSON and the older response structure,

Wiki.Action.get!(
  action: query,
  meta: siteinfo,
  siprop: namespaces,
  format: jsonfm,
  formatversion: 1
)

Link to this section Summary

Types

  • :accumulate - Merge results from each step of a pipeline, rather than overwriting with the latest response.
  • :adapter - Override the HTTP adapter
  • :debug - Turn on verbose logging by setting to true
  • :user_agent - Override the user-agent header string

Functions

Assertive variant of authenticate

Make requests to authenticate a client session. This should only be done using a bot username and password, which can be created for any normal user account.

Assertive variant of get.

Make an API GET request

Create a new client session

Assertive variant of post.

Make an API POST request.

Make a GET request and follow continuations until exhausted or the stream is closed.

Link to this section Types

@type client_option() ::
  {:accumulate, true}
  | {:adapter, module()}
  | {:debug, true}
  | {:user_agent, binary()}
@type client_options() :: [client_option()]
  • :accumulate - Merge results from each step of a pipeline, rather than overwriting with the latest response.
  • :adapter - Override the HTTP adapter
  • :debug - Turn on verbose logging by setting to true
  • :user_agent - Override the user-agent header string

Link to this section Functions

Link to this function

authenticate!(session, username, password)

View Source
@spec authenticate!(Wiki.Action.Session.t(), String.t(), String.t()) ::
  Wiki.Action.Session.t()

Assertive variant of authenticate

Link to this function

authenticate(session, username, password)

View Source

Make requests to authenticate a client session. This should only be done using a bot username and password, which can be created for any normal user account.

arguments

Arguments

  • session - Base session pointing to a wiki.
  • username - Bot username, may be different than the final logged-in username.
  • password - Bot password. Protect this string, it allows others to take on-wiki actions on your behalf.

return-value

Return value

Authenticated session object.

Assertive variant of get.

Make an API GET request

arguments

Arguments

  • session - Wiki.Action.Session object.
  • params - Keyword list of query parameters as atoms or strings.

return-value

Return value

Session object with its .result populated.

Create a new client session

arguments

Arguments

  • site - SiteMatrix.Spec or raw api.php endpoint for the wiki you will connect to. For example, "https://en.wikipedia.org/w/api.php".
  • opts - configuration options which modify client behavior

Assertive variant of post.

Make an API POST request.

arguments

Arguments

  • session - Wiki.Action.Session object. If credentials are required for this action, you should have created this object with the authenticate/3 function.
  • params - Keyword list of query parameters as atoms or strings.

return-value

Return value

Session object with a populated :result attribute.

@spec stream(
  Wiki.Action.Session.t(),
  keyword()
) :: Enumerable.t()

Make a GET request and follow continuations until exhausted or the stream is closed.

arguments

Arguments

  • session - Wiki.Action.Session object.
  • params - Keyword list of query parameters as atoms or strings.

return-value

Return value

Enumerable Stream, where each returned chunk is a raw result map, possibly containing multiple records. This corresponds to session.result from the other entry points.