mediawiki-abusefilter

Python client for working with MediaWiki AbuseFilters.

It provides a simple interface for listing, searching, creating, editing, and reviewing filters from Python.

Installation

pip install mediawiki-abusefilter

Quick start

import mediawiki_abusefilter as mwaf

filters = mwaf.filters(
    "https://example.org",
    username="MyBot@mybotpassword",
    password="BOT_PASSWORD"
)

filter = filters.get(123)

print(filter.description)
print(filter.rules)

The authentication object can also be created separately and reused:

auth = mwaf.auth(
    "https://example.org",
    username="MyBot@mybotpassword",
    password="BOT_PASSWORD"
)

filters = mwaf.filters("https://example.org", auth=auth)

Listing filters

filters.list()

Filters can be narrowed by status and visibility:

filters.list(enabled=True)
filters.list(public=True)
filters.list(private=True)

To search by text:

matches = filters.search("spam")

Large result sets can be limited with limit:

filters.list(limit=100)
filters.search("spam", limit=20)

Creating a filter

filter = filters.create(
    "Low edit count edits",
    "page_namespace == 0 & user_editcount < 10"
)

Filters can also be created with notes, actions, and other options:

filter = filters.create(
    "Example filter",
    "page_namespace == 0",
    notes="Created for testing",
    enabled=False,
    public=False,
    actions={
        "warn": "abusefilter-warning",
        "tag": ["review", "test"]
    }
)

Use dry_run=True to preview a new filter without saving it:

change = filters.create(
    "Example filter",
    "page_namespace == 0",
    dry_run=True
)

print(change)

Editing a filter

Get the filter and change only the values you need:

filter = filters.get(123)

filter.edit(description="Updated description")
filter.edit(enabled=False)
filter.edit(public=False)

Values that are not supplied are left unchanged.

Several changes can be made together:

filter.edit(
    description="Updated filter",
    rules="page_namespace == 0 & user_editcount < 20",
    enabled=True,
    public=True,
    actions={"warn": "abusefilter-warning"}
)

Notes

Notes are appended by default:

filter.edit(notes="Changed the edit-count limit")

To replace the existing notes:

filter.edit(
    notes="Updated notes",
    notes_mode="replace"
)

To clear the notes:

filter.edit(
    notes="",
    notes_mode="replace"
)

Notes can also include the current account and date:

filter.edit(
    notes="Changed the rule",
    sign_notes=True
)

Rule changes

Replace the complete rule:

filter.edit(
    rules="page_namespace == 0"
)

Or modify part of the existing rule:

filter.edit(replace=("old text", "new text"))
filter.edit(append=" & user_editcount < 20")
filter.edit(prepend="page_namespace == 0 & ")
filter.edit(remove=" & page_namespace == 1")
filter.edit(regex=(r"user_editcount\s*<\s*10", "user_editcount < 20"))

Replacement operations are strict by default. Use strict=False when a missing match should not raise an error:

filter.edit(
    replace=("old text", "new text"),
    strict=False
)

Actions

Actions can be configured when creating or editing a filter:

filter.edit(
    actions={
        "warn": "abusefilter-warning",
        "disallow": "abusefilter-disallowed",
        "blockautopromote": True,
        "block": {
            "talk": True,
            "anonymous": "1 day",
            "user": "1 day"
        },
        "tag": ["review", "bot"],
        "throttle": {
            "count": 5,
            "period": 120,
            "groups": "user"
        }
    }
)

Set an action to False to remove it:

filter.edit(
    actions={
        "warn": False,
        "tag": False
    }
)

History

Filter history is available through history():

for entry in filter.history(limit=20):
    print(
        entry["id"],
        entry["user"],
        entry["description"]
    )

Previewing changes

Use dry_run=True to inspect a change before applying it:

change = filter.edit(
    description="Preview only",
    rules="page_namespace == 0",
    dry_run=True
)

print(change)

Changes made through edit() and create() are verified by default.

Set verify=False when you specifically need to skip that verification:

filter.edit(
    rules="page_namespace == 0",
    verify=False
)

Account information

The current account can be inspected with whoami():

info = filters.whoami()

print(info["name"])
print(info["groups"])

Delete

filter.delete()

Requirements

Python 3.9 or newer.

Documentation

Full API documentation and usage examples are available on Read the Docs.

License

MIT