mwbot 0.7.1

A MediaWiki bot framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# mwbot

[![crates.io](https://img.shields.io/crates/v/mwbot.svg)](https://crates.io/crates/mwbot)
[![docs.rs](https://img.shields.io/docsrs/mwbot?label=docs.rs)](https://docs.rs/mwbot)
[![docs (main)](https://img.shields.io/badge/doc.wikimedia.org-green?label=docs%40main)](https://doc.wikimedia.org/mwbot-rs/mwbot/mwbot/)
[![pipeline status](https://gitlab.wikimedia.org/repos/mwbot-rs/mwbot/badges/main/pipeline.svg)](https://gitlab.wikimedia.org/repos/mwbot-rs/mwbot/-/commits/main)
[![coverage report](https://img.shields.io/endpoint?url=https%3A%2F%2Fdoc.wikimedia.org%2Fcover%2Fmwbot-rs%2Fmwbot%2Fcoverage%2Fcoverage.json)](https://doc.wikimedia.org/cover/mwbot-rs/mwbot/coverage)

A MediaWiki bot and tool framework

`mwbot` aims to provide a batteries-included framework for building bots
and tools for MediaWiki wikis. It builds on top of the [mwapi](https://docs.rs/mwapi)
and [parsoid](https://docs.rs/parsoid) crates, which offer lower-level APIs.

### Quickstart
#### Configuration
Create a `~/.config/mwbot.toml` file with the following structure:
```toml
wiki_url = "https://en.wikipedia.org/w/"
```

If want to authenticate, add an auth section:
```toml
[auth]
username = "Example"
oauth2_token = "[...]"
```
See [the OAuth documentation](https://www.mediawiki.org/wiki/OAuth/For_Developers#OAuth_2)
for how to get an OAuth 2 token. Using an [owner-only consumer](https://www.mediawiki.org/wiki/OAuth/Owner-only_consumers#OAuth_2)
is the easiest way to do so.

<div class="warning">

On UNIX-like systems, for security, you must make sure the config's
file permissions don't permit reading by other users, or authorization
will fail with a [`ReadableConfig`][ConfigError::ReadableConfig] error. In this case,
`chmod 600 ~/.config/mwbot.toml` can be used to correct the permissions and
make sure the file is only readable and writeable to its owner.

</div>

#### Reading a page
```rust
let bot = mwbot::Bot::from_default_config().await.unwrap();
let page = bot.page("Rust (programming language)")?;
let html = page.html().await?.into_mutable();
// The lead section is the second p tag in the first section
let lead = html.select("section > p")[1].text_contents();
assert!(lead.starts_with("Rust is a multi-paradigm, general-purpose programming language"));
```
Using [`Bot::from_default_config()`] will look in the current directory
for `mwbot.toml` before looking in the user's config directory. A
custom path can be specified by using `Bot::from_config(...)`.

#### Editing a page
```rust
let bot = mwbot::Bot::from_default_config().await.unwrap();
let page = bot.page("Project:Sandbox")?;
let wikitext = "This is a test edit!";
page.save(wikitext, &SaveOptions::summary("test edit!")).await?;
```
`Page.save()` accepts both HTML and wikitext and supports the [`{{nobots}}`](https://en.wikipedia.org/wiki/Template:Bots)
exclusion mechanism, among other features.

#### Next steps
Try using one of the offered [page generators](./generators/index.html) to fetch and operate on
multiple pages.

### Contributing
`mwbot` is the flagship crate of the [`mwbot-rs` project](https://www.mediawiki.org/wiki/Mwbot-rs).
We're always looking for new contributors, please [reach out](https://www.mediawiki.org/wiki/Mwbot-rs#Contributing)
if you're interested!

## License
This crate is released under GPL-3.0-or-later.
See [COPYING](./COPYING) for details.