# Elixir MediaWiki client
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](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 process edits as they happen.
* `Wiki.Ores` is a [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.3"}
]
end
```
Documentation is generated with `mix docs`.
## Updating
The [change log](CHANGELOG.md) 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,
```elixir
Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("dewiki")
|> 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.Action.get()` method returns an `{:ok, ...}` or a `{:error, ...}` tuple, and
the `Wiki.Action.get!()` method raises an error directly.
### Configuration
Configuration variables (TODO: refactor away from config) under the
`:mediawiki_client` application will override the built-in adapters.
* `: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>`...
For example:
```elixir
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](https://gitlab.com/adamwight/mediawiki_client_ex) 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
```