Mwbot

https://docs.rs/mwbot/latest/
Admin
Mwbot is a batteries-included framework for building bots and tools for MediaWiki wikis, building on...
Tokens:82,886
Snippets:586
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Rust: Bot Initialization Builders

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Provides methods for creating a `Builder` instance for the `Bot` struct. Supports initialization using a wiki URL for standard setups and a combination of API and REST URLs for legacy systems.

```rust
impl Bot {
    /// Build a `Bot` instance programmatically.
    ///
    /// The wiki's URL should be the path where api.php and rest.php can be
    /// found (aka the "script path"). By default it is usually something
    /// like `https://wiki.example.org/w/`.
    pub fn builder(wiki_url: String) -> Builder {
        Builder::new(wiki_url)
    }

    /// For older wikis (pre-1.42) that use RESTBase or the old Parsoid rest.php API.
    pub fn builder_with_legacy_rest(
        api_url: String,
        rest_url: String,
    ) -> Builder {
        Builder::new_with_api_url(api_url, rest_url)
    }
}
```

--------------------------------

### Get Page from Database info in Rust

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This code demonstrates how to retrieve a `Page` from database namespace and dbkey. It uses TitleCodec to validate and create title from database, then gets `Page` instance.

```Rust
pub fn page_from_database(
&self,
namespace: i32,
dbkey: &str,
) -> Result<Page> {
let title = self
.config
.codec
.new_title_from_database(namespace, dbkey)?
.remove_fragment();
self.page_from_title(title)
}
```

--------------------------------

### AllRedirects - Initialize and Configure Generator

Source: https://docs.rs/mwbot/latest/mwbot/generators/allredirects/struct

Provides methods to initialize and configure the `AllRedirects` generator. This includes setting the namespace, starting and stopping page titles, and specifying a prefix for filtering results. Configuration is done using a builder pattern.

```rust
pub fn new() -> Self
pub fn namespace(self, value: impl Into<u32>) -> Self
pub fn with_namespace(self, value: impl Into<Option<u32>>) -> Self
pub fn set_namespace(&mut self, value: impl Into<Option<u32>>)
pub fn from(self, value: impl Into<String>) -> Self
pub fn with_from(self, value: impl Into<Option<String>>) -> Self
pub fn set_from(&mut self, value: impl Into<Option<String>>)
pub fn to(self, value: impl Into<String>) -> Self
pub fn with_to(self, value: impl Into<Option<String>>) -> Self
pub fn set_to(&mut self, value: impl Into<Option<String>>)
pub fn prefix(self, value: impl Into<String>) -> Self
pub fn with_prefix(self, value: impl Into<Option<String>>) -> Self
pub fn set_prefix(&mut self, value: impl Into<Option<String>>)
pub fn sort(self, value: impl Into<SortDirection>) -> Self
pub fn with_sort(self, value: impl Into<Option<SortDirection>>) -> Self
pub fn set_sort(&mut self, value: impl Into<Option<SortDirection>>)
```

--------------------------------

### Reading a Wikipedia Page with mwbot

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Demonstrates how to initialize a MediaWiki bot from default configuration, retrieve a specific page, and extract the text content of its lead section. This example uses the parsoid crate for HTML parsing and assumes a valid configuration file exists.

```rust
# async fn demo() -> mwbot::Result<()>
# {
# use parsoid::prelude::*;
# 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"));
# Ok(())
# }
```

--------------------------------

### UserContribs Initialization and Configuration Methods

Source: https://docs.rs/mwbot/latest/mwbot/generators/user_contribs/struct

Provides methods for creating and configuring a UserContribs generator. These methods allow setting various parameters like start time, end time, users, and more, returning a modified UserContribs instance for chaining.

```rust
pub fn new() -> Self
pub fn start(self, value: impl Into<Timestamp>) -> Self
pub fn with_start(self, value: impl Into<Option<Timestamp>>) -> Self
pub fn set_start(&mut self, value: impl Into<Option<Timestamp>>)
pub fn end(self, value: impl Into<Timestamp>) -> Self
pub fn with_end(self, value: impl Into<Option<Timestamp>>) -> Self
pub fn set_end(&mut self, value: impl Into<Option<Timestamp>>)
pub fn users(self, value: impl Into<Vec<String>>) -> Self
pub fn with_users(self, value: impl Into<Option<Vec<String>>>) -> Self
pub fn set_users(&mut self, value: impl Into<Option<Vec<String>>>)
pub fn user_ids(self, value: impl Into<Vec<u64>>) -> Self
pub fn with_user_ids(self, value: impl Into<Option<Vec<u64>>>) -> Self
pub fn set_user_ids(&mut self, value: impl Into<Option<Vec<u64>>>)
pub fn user_prefix(self, value: impl Into<String>) -> Self
pub fn with_user_prefix(self, value: impl Into<Option<String>>) -> Self
pub fn set_user_prefix(&mut self, value: impl Into<Option<String>>)
pub fn user_ip_range(self, value: impl Into<String>) -> Self
pub fn with_user_ip_range(self, value: impl Into<Option<String>>) -> Self
pub fn set_user_ip_range(&mut self, value: impl Into<Option<String>>)
pub fn dir(self, value: impl Into<Direction>) -> Self
pub fn with_dir(self, value: impl Into<Option<Direction>>) -> Self
pub fn set_dir(&mut self, value: impl Into<Option<Direction>>)
pub fn namespaces(self, value: impl Into<Vec<u32>>) -> Self
pub fn with_namespaces(self, value: impl Into<Option<Vec<u32>>>) -> Self
pub fn set_namespaces(&mut self, value: impl Into<Option<Vec<u32>>>)
pub fn filter(self, value: impl Into<Vec<String>>) -> Self
pub fn with_filter(self, value: impl Into<Option<Vec<String>>>) -> Self
pub fn set_filter(&mut self, value: impl Into<Option<Vec<String>>>)
pub fn tags(self, value: impl Into<Vec<String>>) -> Self
pub fn with_tags(self, value: impl Into<Option<Vec<String>>>) -> Self
pub fn set_tags(&mut self, value: impl Into<Option<Vec<String>>>)
```

--------------------------------

### Configure Page Enumeration Start Point in Rust

Source: https://docs.rs/mwbot/latest/mwbot/generators/allpages/struct

Methods to specify the starting page title for the enumeration. This allows resuming or targeting a specific section of the page list.

```rust
pub fn from(self, value: impl Into<String>) -> Self
pub fn with_from(self, value: impl Into<Option<String>>) -> Self
pub fn set_from(&mut self, value: impl Into<Option<String>>)
```

--------------------------------

### Rust: Test API Get Request

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Tests the basic functionality of the bot's API client by making a simple 'query' action request. It asserts that the request does not return an error.

```rust
#[tokio::test]
async fn test_get_api() {
    let bot = testwp().await;
    // No errors
    bot.api().get_value(&[("action", "query")]).await.unwrap();
}
```

--------------------------------

### Initialize AllPages Generator in Rust

Source: https://docs.rs/mwbot/latest/mwbot/generators/allpages/struct

Provides a constructor for the AllPages struct, allowing for the creation of a new generator instance. This is the starting point for configuring and initiating the page enumeration process.

```rust
pub fn new() -> Self
```

--------------------------------

### Get Page by Title in Rust

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This snippet shows how to retrieve a `Page` object using its title. It leverages the `TitleCodec` to validate the title and create a `Page` instance. It ensures that the provided title is a valid local page.

```Rust
pub fn page(&self, title: &str) -> Result<Page> {
let title = self.config.codec.new_title(title)?.remove_fragment();
self.page_from_title(title)
}
```

--------------------------------

### Test MediaWiki Bot Categories

Source: https://docs.rs/mwbot/latest/src/mwbot/page

Verifies the retrieval of categories associated with a MediaWiki page. This test initializes a bot, gets a page, and asserts that the returned categories match the expected list, specifically `["Category:Mwbot-rs"]`.

```rust
#[tokio::test]
async fn test_categories() {
    let bot = testwp().await;
    assert_eq!(
        bot.page("Mwbot-rs/Categorized")
            .unwrap()
            .categories()
            .await
            .unwrap()
            .unwrap(),
        ["Category:Mwbot-rs"]
    );
}
```

--------------------------------

### Get Wikitext for Wiki Page (Rust)

Source: https://docs.rs/mwbot/latest/src/mwbot/page

Retrieves the wikitext content for a wiki page, prioritizing a specific revision if available, otherwise fetching the latest. It constructs API query parameters and parses the response to extract the content. Handles missing pages and potential errors during API interaction.

```rust
/// Get wikitext for self.baserevid if it's set, or the latest revision otherwise
pub async fn wikitext(&self) -> Result<String> {
    let mut params: Vec<(&'static str, String)> = vec![
        ("action", "query".to_string()),
        ("titles", self.title().to_string()),
        ("prop", "revisions".to_string()),
        ("rvprop", "content|ids".to_string()),
        ("rvslots", "main".to_string()),
    ];
    if let Some(revid) = self.baserevid.get() {
        params.push(("rvstartid", revid.to_string()));
        params.push(("rvendid", revid.to_string()));
    }
    let resp = self.bot.api.get_value(&params).await?;
    let page = resp["query"]["pages"][0].as_object().unwrap();
    if page.contains_key("missing") {
        Err(Error::PageDoesNotExist(self.title().to_string()))
    } else {
        match page.get("revisions") {
            Some(revisions) => {
                let revision = &revisions[0];
                let _ =
                    self.baserevid.set(revision["revid"].as_u64().unwrap());
                Ok(revision["slots"]["main"]["content"]
                    .as_str()
                    .unwrap()
                    .to_string())
            }
            None => {
                // Most likely invalid title, either way revision
                // doesn't exist
                Err(Error::PageDoesNotExist(self.title().to_string()))
            }
        }
    }
}
```

--------------------------------

### Get Canonical URL for a Page (Rust)

Source: https://docs.rs/mwbot/latest/src/mwbot/page

Retrieves the canonical URL for a given MediaWiki page. This method is asynchronous and returns a Result containing a string slice representing the URL or an error. It relies on the `info()` method to fetch page details.

```Rust
/// Get the canonical URL for this page
pub async fn url(&self) -> Result<&str> {
    Ok(&self.info().await?.canonicalurl)
}
```

--------------------------------

### Rust QueryPage Generator for MediaWiki

Source: https://docs.rs/mwbot/latest/src/mwbot/generators/querypage

Defines the QueryPage struct in Rust for the mwbot library, which acts as a generator for fetching data from QueryPage-based special pages on MediaWiki. It utilizes derive macros to map struct fields to API parameters. The generated data can be iterated over, and an example test case demonstrates fetching 'ListDuplicatedFiles'.

```rust
// SPDX-FileCopyrightText: 2023 Misato Kano <me@mirror-kt.dev>
// SPDX-License-Identifier: GPL-3.0-or-later
//! Generator for QueryPage-based special pages
//!
//! See the [`QueryPage`] type documentation for specifics.
use super::Generator;

/// Get a list provided by a QueryPage-based special page.
///
/// See [API documentation](https://www.mediawiki.org/wiki/API:Querypage) for more details.
#[derive(Generator)]
#[params(generator = "querypage", gqplimit = "max")]
pub struct QueryPage {
    #[param("gqppage")]
    special_page: String,
    #[param("gqpoffset")]
    offset: Option<u64>,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::tests::testwp;

    #[tokio::test]
    async fn test_list_duplicated_files() {
        let bot = testwp().await;
        let gen = QueryPage::new("ListDuplicatedFiles");

        let mut pages = gen.generate(&bot);
        let mut count = 0;

        while let Some(page) = pages.recv().await {
            let page = page.unwrap();
            dbg!(page.title());

            if count >= 5 {
                break;
            }
            count += 1;
        }
        assert_eq!(count, 5);
    }
}
```

--------------------------------

### UserContribs API

Source: https://docs.rs/mwbot/latest/mwbot/generators/user_contribs/struct

This section details the UserContribs API endpoint, which is used to fetch a user's contributions. It provides methods to set various parameters such as start time, end time, specific users, user IDs, namespaces, filters, and tags.

```APIDOC
## GET /w/api.php?action=query&list=usercontribs

### Description
Lists a user's contributions. This endpoint is part of the MediaWiki API and can be accessed via the `mwbot` crate with the `generators` feature.

### Method
GET

### Endpoint
/w/api.php?action=query&list=usercontribs

### Parameters
#### Query Parameters
- **ucuser** (string) - Required - The username whose contributions are to be listed.
- **ucstart** (Timestamp) - Optional - Timestamp to start counting contributions from.
- **ucend** (Timestamp) - Optional - Timestamp to stop counting contributions at.
- **ucuserids** (list of uint64) - Optional - List of user IDs whose contributions are to be listed.
- **ucprefix** (string) - Optional - Match usernames starting with this prefix.
- **uciprange** (string) - Optional - Match contributions from users within this IP range.
- **ucdir** (Direction) - Optional - Direction to sort results (ascending/descending).
- **ucnamespace** (list of uint32) - Optional - List of namespaces to show contributions from.
- **uctitle** (string) - Optional - Filter contributions to a specific page title.
- **ucprop** (list of string) - Optional - What properties to include in the usercontribs output.
- **ucfilter** (list of string) - Optional - Filter criteria for contributions.
- **uctag** (list of string) - Optional - Filter contributions by tag.
- **uclimit** (string) - Optional - How many contributions to return.
- **uccontinue** (string) - Optional - Continue retrieving results from where the previous request left off.

### Request Example
```json
{
  "action": "query",
  "list": "usercontribs",
  "ucuser": "ExampleUser",
  "uclimit": "10"
}
```

### Response
#### Success Response (200)
- **query.usercontribs** (array) - A list of user contribution items.
  - **pageid** (integer) - The page ID.
  - **ns** (integer) - The namespace.
  - **title** (string) - The page title.
  - **revid** (integer) - The revision ID.
  - **parentid** (integer) - The parent revision ID.
  - **user** (string) - The username.
  - **userid** (integer) - The user ID.
  - **timestamp** (string) - The timestamp of the contribution.
  - **size** (integer) - The size of the revision.
  - **sizediff** (integer) - The difference in size from the previous revision.
  - **comment** (string) - The edit summary.
  - **tags** (array of strings) - Tags associated with the edit.

#### Response Example
```json
{
  "batchcomplete": "",
  "continue": {
    "uccontinue": "20230101000000|...",
    "continue": "||"
  },
  "query": {
    "usercontribs": [
      {
        "pageid": 12345,
        "ns": 0,
        "title": "Example Page",
        "revid": 67890,
        "parentid": 67889,
        "user": "ExampleUser",
        "userid": 11223,
        "timestamp": "2023-10-27T10:00:00Z",
        "size": 123,
        "sizediff": 45,
        "comment": "Added some content",
        "tags": []
      }
    ]
  }
}
```

#### Error Handling
- **API errors** will be returned in a standard MediaWiki API error format.
```

--------------------------------

### Get Language Links (Rust)

Source: https://docs.rs/mwbot/latest/src/mwbot/page

Retrieves inter-language links for a MediaWiki page, provided the 'generators' feature is enabled. This asynchronous function returns an Option containing a HashMap of language codes to page titles, or None if the page doesn't exist or has no links. It uses the `LangLinks` generator.

```Rust
/// Get the inter-language links of the latest revision, if the page exists.
#[cfg(feature = "generators")]
#[cfg_attr(docsrs, doc(cfg(feature = "generators")))]
pub async fn language_links(
    &self,
) -> Result<Option<HashMap<String, String>>> {
    if self.info.initialized() && !self.exists().await? {
        return Ok(None);
    }
    let mut gen = 
        LangLinks::new(vec![self.title().to_string()]).generate(&self.bot);
    let page = gen.recv().await.unwrap()?;
    debug_assert_eq!(page.title, self.title());
    debug_assert!(gen.recv().await.is_none());
    if page.missing || page.invalid {
        return Ok(None);
    }
    let links = page
        .langlinks
        .into_iter()
        .map(|item| (item.lang, item.title))
        .collect();
    Ok(Some(links))
}
```

--------------------------------

### Get Page by ID in Rust

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This snippet shows how to retrieve a `Page` using its page ID. It queries the MediaWiki API to fetch page information, creates a `Title` object, and constructs the `Page` instance. It includes error handling for invalid page IDs and API response issues.

```Rust
pub async fn page_from_id(&self, page_id: u64) -> Result<Page> {
let mut resp: page::InfoResponse = mwapi_responses::query_api(
&self.api,
[("pageids", page_id.to_string())],
)
.await?;
let info = resp
.query
.pages
.pop()
.expect("API response returned 0 pages");
let title = self.config.codec.new_title(&info.title)?.remove_fragment();
if !title.is_local_page() {
return Err(Error::InvalidPage);
}
Ok(Page {
bot: self.clone(),
title,
title_text: Default::default(),
info: Arc::new(info.clone().into()),
baserevid: info
.lastrevid
.map_or_else(OnceCell::new, OnceCell::with_value),
})
}
```

--------------------------------

### Initialize Bot with Configuration in Rust

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This code snippet demonstrates how to initialize a bot instance with a given configuration. It sets up the user agent, retrieves site information, configures the title codec, and handles optional parameters like marking edits as bot edits.

```Rust
interval.set_missed_tick_behavior(time::MissedTickBehavior::Delay);
Some(Arc::new(Mutex::new(interval)))
} else {
None
};
let api = api
.set_user_agent(&user_agent)
.build()
.await
.map_err(Error::from)?;
let siteinfo = siteinfo::get_siteinfo(&api).await?;
let http = api.http_client().clone();
Ok(Self {
api,
parsoid: ParsoidClient::new_with_client(
&config
.rest_url
.clone()
.or_else(|| {
config.wiki_url.as_ref().map(|w| format!("{w}rest.php"))
})
.ok_or(ConfigError::MissingSiteURL)?,
http,
)?,
config: Arc::new(BotConfig {
username,
codec: TitleCodec::from_site_info(siteinfo)
.map_err(Error::from)?,
mark_as_bot: config.edit.mark_as_bot.unwrap_or(true),
respect_nobots: config.edit.respect_nobots.unwrap_or(true),
}),
state: BotState { save_timer },
})
```

--------------------------------

### Bot Initialization

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This section details the construction of the Bot client, which requires configuration, username, and user agent information.

```APIDOC
## Bot::new

### Description
Initializes a new `Bot` instance with the provided configuration, username, and user agent.

### Method
`new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// This is a conceptual example as `Bot::new` is a constructor.
// Actual usage would involve passing configuration structs.
let config = BotConfig { /* ... */ };
let username = "my_bot";
let user_agent = "MyBot/1.0";
let bot = Bot::new(config, username, user_agent).await?;
```

### Response
#### Success Response (Result<Bot>)
- **Ok(Bot)**: A successfully constructed `Bot` instance.

#### Response Example
```rust
// Successful initialization returns a Bot instance.
// Error handling would be done via `?` or `match`.
```

### Error Handling
- **ConfigError::MissingSiteURL**: If the site URL is not provided in the configuration.
- **mwapi::Error**: If there are issues during API client initialization or site info retrieval.
```

--------------------------------

### Namespace Name Lookup

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Gets the name for a given namespace ID.

```APIDOC
## Bot::namespace_name

### Description
Retrieves the name of a [`Namespace`](https://docs.rs/mwtitle/latest/mwtitle/struct.Namespace.html) given its numeric ID. Returns `None` if the ID is not recognized.

### Method
`namespace_name`

### Endpoint
N/A (Method on `Bot` struct)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **namespace_id** (`i32`) - Required - The numeric ID of the namespace.

### Request Example
```rust
// Get name for namespace ID 0 (typically 'Main')
let main_ns_name = bot.namespace_name(0);
// Get name for namespace ID 2 (typically 'User')
let user_ns_name = bot.namespace_name(2);
```

### Response
#### Success Response (Option<&'a str>)
- **Some(&str)**: The string name of the namespace if found.
- **None**: If the provided namespace ID is not recognized by the wiki's configuration.

#### Response Example
```rust
// If namespace ID 0 is 'Main' and ID 2 is 'User':
// assert_eq!(bot.namespace_name(0), Some("Main"));
// assert_eq!(bot.namespace_name(2), Some("User"));
// assert_eq!(bot.namespace_name(100), None); // Assuming ID 100 doesn't exist
```
```

--------------------------------

### Namespace ID Lookup

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Gets the numeric ID for a given namespace.

```APIDOC
## Bot::namespace_id

### Description
Retrieves the numeric ID for a given [`Namespace`](https://docs.rs/mwtitle/latest/mwtitle/struct.Namespace.html). Returns `None` if the namespace is not recognized.

### Method
`namespace_id`

### Endpoint
N/A (Method on `Bot` struct)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **namespace** (`impl Into<Namespace<'a>>`) - Required - A value that can be converted into a `Namespace` (e.g., a string name like "User" or a numeric ID).

### Request Example
```rust
// Get ID for the 'User' namespace
let user_ns_id = bot.namespace_id("User");
// Get ID for namespace ID 2 (typically 'User')
let ns_id_2 = bot.namespace_id(2);
```

### Response
#### Success Response (Option<i32>)
- **Some(i32)**: The numeric ID of the namespace if found.
- **None**: If the provided namespace is not recognized by the wiki's configuration.

#### Response Example
```rust
// If 'User' namespace exists and has ID 2:
// assert_eq!(bot.namespace_id("User"), Some(2));
// assert_eq!(bot.namespace_id(2), Some(2));
// assert_eq!(bot.namespace_id("NonExistentNamespace"), None);
```
```

--------------------------------

### Configure mwbot with TOML

Source: https://docs.rs/mwbot/latest/index

Demonstrates how to create a configuration file for the mwbot crate using TOML format. This includes setting the wiki URL and optional authentication details. Ensure correct file permissions for sensitive information.

```toml
wiki_url = "https://en.wikipedia.org/w/"

[auth]
username = "Example"
oauth2_token = "[...]"
```

--------------------------------

### GET /wiki/api.php (embeddedin generator)

Source: https://docs.rs/mwbot/latest/src/mwbot/generators/mod

Retrieves a list of pages that transclude a specified template. This generator is part of the MediaWiki API's capabilities for finding inter-page relationships.

```APIDOC
## GET /wiki/api.php (embeddedin generator)

### Description
Retrieves pages that transclude the given template. This endpoint utilizes the MediaWiki API's `embeddedin` generator to find pages referencing a specific template.

### Method
GET

### Endpoint
/wiki/api.php

### Query Parameters
- **action** (string) - Required - Set to `query` to use the query module.
- **format** (string) - Required - The format of the response (e.g., `json`).
- **generator** (string) - Required - Set to `embeddedin` to use this generator.
- **geititle** (string) - Required - The title of the template to find transclusions for.
- **geinamespace** (integer or list of integers) - Optional - Filters results to pages within the specified namespace(s).
- **geifilterredir** (string) - Optional - Filters how redirects are handled. Possible values: `all`, `nonredirects`, `redirects`.
- **geidir** (string) - Optional - The direction to sort the results. Possible values: `ascending`, `descending`.
- **geilimit** (string) - Optional - The maximum number of results to return. Often set to `max` for the maximum allowed by the API.

### Request Example
```json
{
  "action": "query",
  "format": "json",
  "generator": "embeddedin",
  "geititle": "Template:Example",
  "geilimit": "max"
}
```

### Response
#### Success Response (200)
- **batchcomplete** (boolean) - Indicates if the query is complete.
- **continue** (object) - Contains parameters for continuing a paginated query.
- **query** (object) - Contains the list of pages that transclude the template.
  - **pages** (object) - An object where keys are page IDs and values are page details.
    - **pageid** (integer) - The unique identifier for the page.
    - **ns** (integer) - The namespace of the page.
    - **title** (string) - The title of the page.

#### Response Example
```json
{
  "batchcomplete": true,
  "query": {
    "pages": {
      "123": {
        "pageid": 123,
        "ns": 0,
        "title": "Page Name 1"
      },
      "456": {
        "pageid": 456,
        "ns": 0,
        "title": "Another Page"
      }
    }
  }
}
```
```

--------------------------------

### Rust: Load Bot Configuration from Default Path

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Asynchronously loads the bot's configuration from a default TOML file. It first checks the current directory for `mwbot.toml` and then falls back to platform-specific configuration directories. Ensures file permissions are checked if authentication credentials are present.

```rust
pub async fn from_default_config() -> Result<Self, ConfigError> {
    let path = {
        let first = Path::new("mwbot.toml");
        if first.exists() {
            first.to_path_buf()
        } else {
            dirs::config_dir()
                .expect("Cannot find config directory")
                .join("mwbot.toml")
        }
    };
    Self::from_path(&path).await
}
```

--------------------------------

### GET /api/langlinks

Source: https://docs.rs/mwbot/latest/src/mwbot/generators/langlinks

Retrieves all language links from the provided pages to other languages. This endpoint is part of the mwbot-rs library and allows for fetching multilingual link data.

```APIDOC
## GET /api/langlinks

### Description
Retrieves all language links from the provided pages to other languages. This endpoint is part of the mwbot-rs library and allows for fetching multilingual link data.

See [API documentation](https://www.mediawiki.org/wiki/API:Langlinks) for more details.

### Method
GET

### Endpoint
/api/langlinks

### Parameters
#### Query Parameters
- **titles** (string[]) - Required - The titles of the pages to get language links for.
- **lang** (string) - Optional - Filter language links to a specific language code.
- **lang_title** (string) - Optional - Filter language links by a specific page title in a target language.
- **sort** (SortDirection) - Optional - The direction to sort the language links (ascending or descending).
- **lang_name_locale** (string) - Optional - The language to use for the names of the languages.

### Request Example
(This is a conceptual example as the actual request is made via the mwbot-rs library)
```rust
use mwbot::generators::langlinks::LangLinks;

let bot = testwp().await; // Assuming testwp() provides an authenticated Bot instance
let gen = LangLinks::new(vec!["Mwbot-rs/Langlink".to_string()]);
let mut links = gen.generate(&bot);
```

### Response
#### Success Response (200)
- **langlinks** (LangLinksResponseItem[]) - A list of language link objects, each containing details about a link to another language version of the page.

#### Response Example
```json
{
  "langlinks": [
    {
      "lang": "en",
      "langname": "English",
      "title": "Stick style",
      "url": "https://en.wikipedia.org/wiki/Stick_style"
    }
  ]
}
```
```

--------------------------------

### PagesWithProp::new Constructor

Source: https://docs.rs/mwbot/latest/mwbot/generators/pageswithprop/struct

Creates a new instance of PagesWithProp. Requires a property name as input. This is the entry point for configuring the page listing.

```rust
pub fn new(prop_name: impl Into<String>) -> Self
```

--------------------------------

### Generator generate Method for PagesWithProp

Source: https://docs.rs/mwbot/latest/mwbot/generators/pageswithprop/struct

Implements the generate method for the Generator trait. This starts the generator and returns a Receiver to asynchronously process the generated pages.

```rust
fn generate(self, bot: &Bot) -> Receiver<Self::Output>
```

--------------------------------

### Rust: Initialize Bot from Parsed Configuration

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Initializes the `Bot` instance from a parsed `config::Config` struct. It configures the `ApiClient` with details such as API URL, max lag, error format, and retry limits. It also handles different authentication methods (BotPassword, OAuth2) and constructs the user agent string.

```rust
async fn from_config(config: config::Config) -> Result<Self, ConfigError> {
    let mut api = ApiClient::builder(
        &config
            .api_url
            .clone()
            .or_else(|| {
                config.wiki_url.as_ref().map(|w| format!("{w}api.php"))
            })
            .ok_or(ConfigError::MissingSiteURL)?,
    )
    .set_maxlag(config.general.maxlag.unwrap_or(5))
    .set_errorformat(ErrorFormat::Wikitext);
    if let Some(limit) = config.general.retry_limit {
        api = api.set_retry_limit(limit);
    }
    let mut user_agent = vec![];
    if let Some(extra) = config.general.user_agent {
        user_agent.push(extra);
    }
    // FIXME: do better
    let mut username = None;
    if let Some(auth) = config.auth {
        match &auth {
            config::Auth::BotPassword { username, password } => {
                info!("Logging in as {} with password", username);
                api = api.set_botpassword(username, password);
            }
            config::Auth::OAuth2 {
                username,
                oauth2_token,
            } => {
                info!("Logging in as {} with OAuth2 token", username);
                api = api.set_oauth2_token(oauth2_token);
            }
        }
        let normalized = normalize_username(auth.username());
        user_agent.push(format!("User:{}", &normalized));
        username = Some(normalized);
    }
    user_agent.push(format!("mwbot-rs/{}", env!("CARGO_PKG_VERSION")));
    let user_agent = user_agent.join(" ");
    let save_delay = config.edit.save_delay.unwrap_or(10);
    let save_timer = if save_delay > 0 {
        let mut interval =
            time::interval(time::Duration::from_secs(save_delay));

```

--------------------------------

### Get Namespace ID in Rust

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This snippet demonstrates how to obtain the numeric ID of a given namespace. It leverages the `TitleCodec` to retrieve the namespace map and find the corresponding ID.

```Rust
pub fn namespace_id<'a, N: Into<Namespace<'a>>>(
&self,
namespace: N,
) -> Option<i32> {
self.title_codec().namespace_map().get_id(namespace)
}
```

--------------------------------

### TitleCodec Initialization

Source: https://docs.rs/mwbot/latest/mwbot/struct

Methods for creating and initializing a TitleCodec instance.

```APIDOC
## TitleCodec Initialization

### `new`

**Description**: Constructs a new `TitleCodec` using the given fields. In most cases, it is easier to construct one from site info methods.

**Parameters**:
- `namespace_map` (NamespaceMap) - Required - The map of namespaces.
- `interwiki_set` (InterwikiSet) - Required - The set of interwiki links.
- `local_interwiki_set` (InterwikiSet) - Required - The set of local interwiki links.
- `main_page` (String) - Required - The name of the main page.
- `lang` (String) - Required - The language code.
- `legal_title_chars` (String) - Required - A string containing all legal title characters.

### `new_from_iters`

**Description**: Creates a new `TitleCodec` by getting namespaces, namespace aliases, and interwikis from iterators.

**Parameters**:
- `namespaces` (N: IntoIterator<Item = NamespaceInfo>) - Required - An iterator for namespace information.
- `namespace_aliases` (A: IntoIterator<Item = NamespaceAlias>) - Required - An iterator for namespace alias information.
- `interwikis` (I: IntoIterator<Item = Interwiki>) - Required - An iterator for interwiki information.
- `main_page` (String) - Required - The name of the main page.
- `lang` (String) - Required - The language code.
- `legal_title_chars` (String) - Required - A string containing all legal title characters.

### `from_site_info`

**Description**: Creates a new `TitleCodec` using the provided `SiteInfo`. The `SiteInfo` must include a non-empty `interwiki_map` field to enable the resulting `TitleCodec` to correctly parse titles with interwikis, but an empty `interwiki_map` is not an error.

**Parameters**:
- `site_info` (SiteInfo) - Required - The site information object.

### `new` (impl for TitleCodec)

**Description**: Constructs a new `TitleCodec` using the given fields. In most cases, it is easier to do so from one of the siteinfo methods.

**Parameters**:
- `namespace_map` (NamespaceMap) - Required - The map of namespaces.
- `interwiki_set` (InterwikiSet) - Required - The set of interwiki links.
- `local_interwiki_set` (InterwikiSet) - Required - The set of local interwiki links.
- `main_page` (String) - Required - The name of the main page.
- `lang` (String) - Required - The language code.
- `legal_title_chars` (String) - Required - A string containing all legal title characters.

### `new_from_iters` (impl for TitleCodec)

**Description**: Creates a new `TitleCodec` getting namespaces, namespace aliases, and interwikis from iterators.

**Parameters**:
- `namespaces` (N: IntoIterator<Item = NamespaceInfo>) - Required - An iterator for namespace information.
- `namespace_aliases` (A: IntoIterator<Item = NamespaceAlias>) - Required - An iterator for namespace alias information.
- `interwikis` (I: IntoIterator<Item = Interwiki>) - Required - An iterator for interwiki information.
- `main_page` (String) - Required - The name of the main page.
- `lang` (String) - Required - The language code.
- `legal_title_chars` (String) - Required - A string containing all legal title characters.

### `from_site_info` (impl for TitleCodec)

**Description**: Creates a new `TitleCodec` using the provided `SiteInfo`. The `SiteInfo` must include a non-empty `interwiki_map` field to enable the resulting `TitleCodec` to correctly parse titles with interwikis, but an empty `interwiki_map` is not an error.

**Parameters**:
- `site_info` (SiteInfo) - Required - The site information object.
```

--------------------------------

### Rust: Get Namespace Name

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Retrieves the string name for a given namespace. It uses a title codec to map namespaces to their string representations. Accepts various types that can be converted into a Namespace.

```rust
pub fn namespace_name<'a, N: Into<Namespace<'a>>>(
        &self,
        namespace: N,
    ) -> Option<&str> {
        self.title_codec().namespace_map().get_name(namespace)
    }
```

--------------------------------

### Rust: Load Bot Configuration from Specified Path

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Asynchronously loads the bot's configuration from a given file path. It reads the TOML file, parses it, and performs a file permission check if authentication details are included. This method allows for explicit configuration file management.

```rust
/// Load Bot configuration from the specified path.
///
/// Under UNIX-like systems, the configuration file must only be readable by its owner!
pub async fn from_path(path: &Path) -> Result<Self, ConfigError> {
    debug!("Reading config from {:?}", path);
    let config: config::Config =
        toml::from_str(&std::fs::read_to_string(path)?)?;
    // Check file permissions if there are credentials
    if config.auth.is_some() {
        check_file_permissions(path)?;
    }
    Self::from_config(config).await
}
```

--------------------------------

### Initialize Logging in Rust

Source: https://docs.rs/mwbot/latest/index

Demonstrates how to initialize logging for the mwbot application using the `init_logging` function. Logging can be further configured by setting the `RUST_LOG` environment variable.

```rust
mwbot::init_logging();
```

--------------------------------

### Configure Title Prefix for Filtering in Rust

Source: https://docs.rs/mwbot/latest/mwbot/generators/allpages/struct

Methods to set a prefix for filtering page titles. This allows retrieving only pages whose titles start with a specified string, useful for targeted searches.

```rust
pub fn prefix(self, value: impl Into<String>) -> Self
pub fn with_prefix(self, value: impl Into<Option<String>>) -> Self
pub fn set_prefix(&mut self, value: impl Into<Option<String>>)
```

--------------------------------

### Rust: Initialize Test Bot Configuration

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

Creates and initializes a Bot instance for testing purposes using configuration from environment variables. It attempts to use OAuth2 authentication if MWAPI_USERNAME and MWAPI_TOKEN are set.

```rust
pub(crate) async fn testwp() -> Bot {
    let username = std::env::var("MWAPI_USERNAME");
    let token = std::env::var("MWAPI_TOKEN");
    let auth = if let (Ok(username), Ok(oauth2_token)) = (username, token) {
        Some(config::Auth::OAuth2 {
            username,
            oauth2_token,
        })
    } else {
        None
    };

    Bot::from_config(config::Config {
        wiki_url: Some("https://test.wikipedia.org/w/".to_string()),
        api_url: None,
        rest_url: None,
        auth,
        general: Default::default(),
        edit: Default::default(),
    })
    .await
    .unwrap()
}
```

--------------------------------

### Get Page by Title Object in Rust

Source: https://docs.rs/mwbot/latest/src/mwbot/lib

This snippet illustrates how to obtain a `Page` object from a `Title` object. It checks if the title represents a local page before creating the `Page` instance, returning an error if the page is invalid.

```Rust
pub fn page_from_title(&self, title: Title) -> Result<Page> {
if !title.is_local_page() {
return Err(Error::InvalidPage);
}
Ok(Page {
bot: self.clone(),
title,
title_text: Default::default(),
info: Default::default(),
baserevid: Default::default(),
})
}
```

--------------------------------

### Test MediaWiki Bot Templates

Source: https://docs.rs/mwbot/latest/src/mwbot/page

Tests the functionality for retrieving templates transcluded on a MediaWiki page. It initializes a bot, fetches a page, and asserts that the list of templates contains the expected template name, e.g., 'Main Page'.

```rust
#[tokio::test]
async fn test_templates() {
    let bot = testwp().await;
    assert!(bot
        .page("Mwbot-rs/Transcluded")
        .unwrap()
        .templates(None)
        .await
        .unwrap()
        .unwrap()
        .contains(&"Main Page".to_string()));
}
```

--------------------------------

### mwbot Builder - Configuration Methods

Source: https://docs.rs/mwbot/latest/src/mwbot/builder

This Rust code defines the `Builder` struct and its associated methods for configuring a `mwbot::Bot` instance. It includes methods to set authentication (BotPassword, OAuth2), API and REST URLs, general bot settings (maxlag, retry limit, user agent), and edit-specific settings (mark as bot, save delay, respect nobots).

```rust
1/*
2Copyright (C) 2022 Kunal Mehta <legoktm@debian.org>
3
4This program is free software: you can redistribute it and/or modify
5it under the terms of the GNU General Public License as published by
6the Free Software Foundation, either version 3 of the License, or
7(at your option) any later version.
8
9This program is distributed in the hope that it will be useful,
10but WITHOUT ANY WARRANTY; without even the implied warranty of
11MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12GNU General Public License for more details.
13
14You should have received a copy of the GNU General Public License
15along with this program.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18use crate::config::{Auth, Config};
19
20/// Build a `mwbot::Bot` instance programmatically
21pub struct Builder {
22    config: Config,
23}
24
25impl Builder {
26    pub(crate) fn new(wiki_url: String) -> Self {
27        Self {
28            config: Config {
29                wiki_url: Some(wiki_url),
30                auth: None,
31                general: Default::default(),
32                edit: Default::default(),
33                ..Default::default()
34            },
35        }
36    }
37
38    pub(crate) fn new_with_api_url(api_url: String, rest_url: String) -> Self {
39        Self {
40            config: Config {
41                api_url: Some(api_url),
42                rest_url: Some(rest_url),
43                auth: None,
44                general: Default::default(),
45                edit: Default::default(),
46                ..Default::default()
47            },
48        }
49    }
50
51    pub fn set_botpassword(
52        mut self,
53        username: String,
54        password: String,
55    ) -> Self {
56        self.config.auth = Some(Auth::BotPassword { username, password });
57        self
58    }
59
60    pub fn set_oauth2_token(mut self, username: String, token: String) -> Self {
61        self.config.auth = Some(Auth::OAuth2 {
62            username,
63            oauth2_token: token,
64        });
65        self
66    }
67
68    pub fn set_maxlag(mut self, maxlag: u32) -> Self {
69        self.config.general.maxlag = Some(maxlag);
70        self
71    }
72
73    pub fn set_retry_limit(mut self, retry_limit: u32) -> Self {
74        self.config.general.retry_limit = Some(retry_limit);
75        self
76    }
77
78    /// This adds the provided string to the User-agent, it does not
79    /// override the default generated one.
80    pub fn set_user_agent(mut self, user_agent: String) -> Self {
81        self.config.general.user_agent = Some(user_agent);
82        self
83    }
84
85    pub fn set_mark_as_bot(mut self, mark_as_bot: bool) -> Self {
86        self.config.edit.mark_as_bot = Some(mark_as_bot);
87        self
88    }
89
90    pub fn set_save_delay(mut self, save_delay: u64) -> Self {
91        self.config.edit.save_delay = Some(save_delay);
92        self
93    }
94
95    pub fn set_respect_nobots(mut self, respect_nobots: bool) -> Self {
96        self.config.edit.respect_nobots = Some(respect_nobots);
97        self
98    }
99
100    pub async fn build(self) -> Result<crate::Bot, crate::ConfigError> {
101        crate::Bot::from_config(self.config).await
102    }
103}

```

--------------------------------

### Generator Trait Implementation for FileUsage - Rust

Source: https://docs.rs/mwbot/latest/mwbot/generators/file/struct

Shows the implementation of the Generator trait for the FileUsage struct in Rust. This includes defining the output type and methods for generating API parameters and starting the generation process.

```rust
type Output = Result<Page, Error>
fn params(&self) -> HashMap<&'static str, String>
fn generate(self, bot: &Bot) -> Receiver<Self::Output>
```

--------------------------------

### Manually Create TitleCodec

Source: https://docs.rs/mwbot/latest/mwbot/struct

Constructs a new TitleCodec instance with manually provided configuration details including namespace map, interwiki sets, main page, language, and legal title characters. This is useful when site information is not readily available.

```Rust
pub fn new(
    namespace_map: NamespaceMap,
    interwiki_set: InterwikiSet,
    local_interwiki_set: InterwikiSet,
    main_page: String,
    lang: String,
    legal_title_chars: String,
) -> Result<TitleCodec, Error>
```
Tokens:
Raw