Metadata-Version: 2.5
Name: mediawiki-abusefilter
Version: 0.1.3
Summary: A small Python client for creating and modifying MediaWiki AbuseFilters
Project-URL: Repository, https://github.com/MadMaxWP/mediawiki-abusefilter
Project-URL: Issues, https://github.com/MadMaxWP/mediawiki-abusefilter/issues
Author-email: Max <madmax.wp@proton.me>
License-Expression: MIT
License-File: LICENSE
Keywords: abusefilter,bot,mediawiki,wikimedia,wikipedia
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: requests<3,>=2.31
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme<4,>=3; extra == 'docs'
Requires-Dist: sphinx<8,>=7.4.7; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == 'test'
Description-Content-Type: text/markdown

# mediawiki-abusefilter

[![CI](https://github.com/MadMaxWP/mediawiki-abusefilter/actions/workflows/ci.yml/badge.svg)](https://github.com/MadMaxWP/mediawiki-abusefilter/actions/workflows/ci.yml)
[![Documentation status](https://readthedocs.org/projects/mediawiki-abusefilter/badge/?version=latest)](https://mediawiki-abusefilter.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/mediawiki-abusefilter.svg)](https://pypi.org/project/mediawiki-abusefilter/)
[![Python](https://img.shields.io/pypi/pyversions/mediawiki-abusefilter.svg)](https://pypi.org/project/mediawiki-abusefilter/)
[![License](https://img.shields.io/github/license/MadMaxWP/mediawiki-abusefilter.svg)](https://github.com/MadMaxWP/mediawiki-abusefilter/blob/main/LICENSE)
[![Latest Release](https://img.shields.io/github/v/release/MadMaxWP/mediawiki-abusefilter.svg)](https://github.com/MadMaxWP/mediawiki-abusefilter/releases/latest)

Python client for working with MediaWiki AbuseFilters.

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

## Installation

```bash
pip install mediawiki-abusefilter
```

## Quick start

```python
import mediawiki_abusefilter as mwaf

filters = mwaf.filters(
    "https://example.org",
    username="Username",
    password="PASSWORD"
)

filter = filters.get(123)

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

The authentication object can also be created separately and reused:

```python
auth = mwaf.auth(
    "https://example.org",
    username="Username",
    password="PASSWORD"
)

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

## Listing filters

```python
filters.list()
```

Filters can be narrowed by status and visibility:

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

To search by text:

```python
matches = filters.search("spam")
```

Large result sets can be limited with `limit`:

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

## Creating a filter

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

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

```python
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:

```python
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:

```python
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:

```python
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:

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

To replace the existing notes:

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

To clear the notes:

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

Notes can also include the current account and date:

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

## Rule changes

Replace the complete rule:

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

Or modify part of the existing rule:

```python
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:

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

## Actions

Actions can be configured when creating or editing a filter:

```python
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:

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

## History

Filter history is available through `history()`:

```python
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:

```python
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:

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

## Account information

The current account can be inspected with `whoami()`:

```python
info = filters.whoami()

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

## Delete

```python
filter.delete()
```

## Requirements

Python 3.9 or newer.

## Limitations

BotPassword login does not work with this package.

The package uses the MediaWiki web interface for filter creation and editing, which requires a normal user login.

## Documentation

Full API documentation and usage examples are available on [Read the Docs](https://mediawiki-abusefilter.readthedocs.io/en/latest/).

## License

MIT
