README.md

# Elixir MediaWiki client

Unofficial client modules for connecting to Wikipedia and other MediaWiki sites from Elixir code.  Supports the Action, EventStreams, and Ores APIs.

API reference for the current version: [Documentation and examples](https://hexdocs.pm/mediawiki_client/api-reference.html)

Overview:
* `Wiki.Action` connects to the [Action API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page),
a rich set of commands to query or edit almost anything on a wiki.
* `Wiki.EventStreams` to access [EventStreams](https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams),
a real-time feed of events.
* `Wiki.Ores` to access the [ORES](https://www.mediawiki.org/wiki/ORES) service [API](https://ores.wikimedia.org/v3/),
machine-learning models for estimating revision and edit quality.

This library is beta-quality, please suggest improvements and consult the [change log](CHANGELOG.md).

## Installation

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

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

Documentation is generated with `mix docs`.

## Usage

A simple call to the action API,

```elixir
"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 detailed usage and more examples.

### Error handling

Methods are all assertive, and will throw a `RuntimeError` with details about the
API error, or a `Tesla.Error` if a network failure is detected.

### Defaults

These parameters are set by default, but can be overridden by including again in an outer caller,

* The `:format` parameter defaults to `:json`.
* `:formatversion` defaults to `2`.

A few configuration variables are available under the `:mediawiki_client` application,
but settings can be omitted and the defaults should work.  Example overrides can be seen in
[config/test.exs](config/test.exs), in this case to mock network access.

* `:eventsource_adapter` - Defaults to `HTTPoison`, this is the http client to
use for the EventStreams HTTP client.
* `:eventstream_endpoint` - API endpoint for `Wiki.EventStreams`, might be
overridden to target a staging server 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>`...

## Development

Find the [project homepage](https://gitlab.com/adamwight/mediawiki_client_ex) on GitLab.
To contribute, please write a bug or merge request, or contact the author.

Several linters are configured, and may be run directly or called transparently
by installing the git pre-push hook,

```shell script
mix git_hooks.install
```

Then, `git push` will run all tests by default.  To push without passing tests, `git push --no-verify` to a branch.

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