Elixir MediaWiki client View Source

Unofficial client modules for connecting to Wikipedia, Wikidata, and other MediaWiki sites from Elixir code. Supports multiple APIs: Action, EventStreams, and Scoring.

API reference for the current version: Documentation and examples

Overview:

Installation

Install this package by adding mediawiki_client to your dependencies in mix.exs,

def deps do
  [
    {:mediawiki_client, "~> 0.3"}
  ]
end

Documentation is generated with mix docs.

Updating

The change log will have information about new features and any breaking changes. Expect the interfaces to evolve until the 1.0 release is reached.

Usage

Fetch some statistics about German Wikipedia,

"dewiki"
|> Wiki.Site.get!()
|> Wiki.Action.new()
|> Wiki.Action.get!(
  action: :query,
  meta: :siteinfo,
  siprop: :statistics
)
# %Wiki.Action.Session{
#   ...
#   result: %{
#     "batchcomplete" => true,
#     "query" => %{
#       "statistics" => %{
#         "activeusers" => 19687,
#         "admins" => 188,
#         "articles" => 2583285,
#         "edits" => 211219883,
#         "images" => 130199,
#         "jobs" => 0,
#         "pages" => 7163473,
#         "queued-massmessages" => 0,
#         "users" => 3715461
#       }
#     }
#   },
#   ...
# }

See the module documentation for more examples.

Error handling

Methods come in an assertive and a non-assertive form, for example the Wiki.Site.get() method returns an {:ok, ...} or a {:error, ...} tuple, and the Wiki.Site.get!() method raises an error directly.

Defaults

Default action API parameters are,

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

These can be easily overridden:

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

Configuration variables (TODO: refactor away from config) under the :mediawiki_client application will override the built-in adapters. For example:

* `:ores_endpoint` - API endpoint for `Wiki.Ores`.
* `:tesla_adapter` - Defaults to `Tesla.Adapter.Hackney`, a stable client which
performs certificate validation.
* `:user_agent` - Sent in request headers, defaults to `mediawiki_client_ex/<version>`...
config :mediawiki_client,
  # HTTP client to use for EventStreams.  Defaults to `HTTPoison`.
  eventsource_adapter: Wiki.Tests.HTTPoisonMock,
  # API endpoint for `Wiki.EventStreams`.  Defaults to 
  eventstream_endpoint:
  tesla_adapter: Wiki.Tests.TeslaAdapterMock,
  ores_endpoint: "https://ores.test/v3/scores/",

Development

Find the project homepage on GitLab. To contribute, feel free to write an issue, push a merge request, or contact the author.

Several linters are configured, these are called on git push. To install hooks:

shell script mix git_hooks.install

To push without running tests call git push --no-verify, but please don't do this on the main branch.

To generate a test coverage report, shell script mix coveralls.html