# MediaWiki client for Elixir

Unofficial client for connecting to Wikipedia, Wikidata, and other Wikimedia or third-party MediaWiki sites.  Supports most wiki APIs: Action, EventStreams, and Scoring.

Current API reference: [Documentation and examples](https://hexdocs.pm/mediawiki_client/api-reference.html)

## Overview

* `Wiki.Action` is the primary read/write interface for wikis, connecting to the
[Action API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page).
This is a rich set of commands to query or edit almost anything on a wiki.
* `Wiki.EventStreams` is a real-time
[EventStreams](https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams)
feed allowing an application to monitor and process edits as they happen.
* `Wiki.LiftWing` is the general interface to [machine learning models](https://wikitech.wikimedia.org/wiki/Machine_Learning/LiftWing)
* `Wiki.Ores` is the legacy [scoring service](https://www.mediawiki.org/wiki/ORES)
for estimating revision and edit quality.

## Installation

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

```elixir
def deps do
  [
    {:mediawiki_client, "~> 0.5.0"}
  ]
end
```

## Upgrading from previous versions

Please see the [change log](CHANGELOG.md) for a history of breaking changes.
This library is still pre-1.0 and open to suggestions for improvement.

## Livebook examples

A [Livebook](https://livebook.dev/) notebook is included to demonstrate usage.  Start it locally with this command:

```shell
livebook server notebooks/demo.livemd
```

## Quick start

Fetch some statistics about German Wikipedia,

<!-- tabs-open -->

### Request

```elixir
Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("dewiki")
|> Wiki.Action.new()
|> Wiki.Action.get!(
  action: :query,
  meta: :siteinfo,
  siprop: :statistics
)
```

### Response

```elixir
%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
      }
    }
  },
  ...
}
```

<!-- tabs-close -->

Additional examples are included in the [source documentation](https://hexdocs.pm/mediawiki_client/api-reference.html) .

### Error handling

Most methods come in an assertive and a non-assertive form, for example the
`Wiki.Action.get()` method returns an `{:ok, ...}` or a `{:error, ...}` tuple, and
`Wiki.Action.get!()` throws the error directly.

## Development

The [project homepage](https://gitlab.com/adamwight/mediawiki_client_ex) is on GitLab.
To contribute, feel free to start with an issue, push a merge request, or
contact maintainers.

To run all tests,
```shell
mix test.all
```

To generate a test [coverage report](../cover/excoveralls.html),
```shell
mix coveralls.html
```

Documentation is generated with `mix docs`.

## See also

Modular parser for HTML wiki dumps, https://gitlab.com/wmde/technical-wishes/scrape-wiki-html-dump