Szerkesztő:BinBot/listshop.py

This module will create something like this: Szerkesztő:BinBot/BinBot kicsiny listaboltja.

#!/usr/bin/env python3
"""
This module maintains a page that collects bot-refreshed lists.

Given a page that lists several lists with their most recent update, e.g.
hu:Szerkesztő:BinBot/BinBot kicsiny listaboltja (we call it a listshop),
and several lists that are maintained by bot (not neccessarily the same one)
and need the users' attention, the bots may refresh this page, so that users
may watch this one for tasks they regularly do.
This is not a standalone bot, rather a module that your bot can import.
So this is for those who can write simple bots on their own, not for end users.

A sample listshop is shown at hu:user:BinBot/BinBot kicsiny listaboltja.

The module will refresh the appropriate box on listshop page that belongs
to the specified maintenance list (e.g. list of pages with a certain template)
and the list of the five most recent change on top of the page.

The title of the listshop also comes from your script as a parameter, thus
several listshops may be maintained in one project.
Multiple bots may edit the sane listshop. Due to low expected frequency, the
module is currently not safe against edit conflicts.

The module has nothing to do with the main activity of your bot.
The purpose is to create central listshops that users may easily watch.

Usage:
Prepare the page
1. Create the listshop like the above page. Put somewhere these lines:
<!-- begin recentchanges -->
<!-- end recentchanges -->
That's where the recent changes will be placed between these two lines.

2. Create the boxes. The link to your listpage should be wired in. Each box
should have <!-- begin <hook> --><!-- end <hook> --> part, where <hook> stands
for any alphanumerical identifier that is unique for that box.
It is not neccessary to follow the box design of my sample page. You are free
to use any form. The spirit of the page is in the above HTML comments.

Call the function:
import listshop
listshop.refresh(title, hook, my_list_title, editsum, notice, bot)
"""
#
# (C) Bináris, 2023
#
# Distributed under the terms of the MIT license.
#

import re
import pywikibot
from pywikibot.exceptions import NoPageError

site = pywikibot.Site()

class NoHookError(AttributeError):
    """The page has no such hook."""

def _regex(hook: str) -> re.Pattern:
    string = fr'(?s)(<!-- begin {hook} -->\n?)(.*?)(\n?<!-- end {hook} -->)'
    return re.compile(string)

def refresh(title, hook, my_list_title: str,
            editsum: str = '',
            notice: str = '',
            bot: bool = True) -> None:
    """
    Refresh the listshop.

    param listshop: title of the listshop without brackets
    param hook: unique identifier within the listshop
    param my_list_title: title of your lists without brackets
    param editsum: this will be the edit summary on your behalf, e.g.
        '[[Wikipedia:List of possibly vandalised pages]] refreshed, 123 items'
        If omitted, a standard summary will be created from my_list_title.
    param notice: an extra nessage to users, e.g. number of items on your list.
        If present, will be shown in the box. Be short, fit in the box. :-)
    param bot: if False, the edit will appear in recent changes for everyone

    :raises NoPageError: incorrect listshop title
    :raises NoHookError: listshop has no such hook
    Will not handle every possible error such as protected pages, because
    it is designed to use with a few concrete pages.
    """

    # TODO: i18n if the scripts get into the framework
    if site.lang == 'hu':
        refreshed = 'Frissítve'
        noticeword = 'Megjegyzés'
    else:
        refreshed = 'Refreshed'
        noticeword = 'Notice'

    page = pywikibot.Page(site, title)
    try:
        text = page.get()
    except NoPageError:
        raise NoPageError(page, 'Please check the title of the listshop.')
    m = _regex(hook).search(text)
    if not hook or not m:
        raise NoHookError(f'Page has no hook "{hook}" or it is malformed.')
    box = f'{refreshed}: ~~~~'
    if notice:
        box = f'* {noticeword}: {notice}\n* ' + box
    box = m.group(1) + box + m.group(3)
    text = text.replace(m.group(), box)
    
    lead = _regex('recentchanges').search(text)
    try:
        lines = lead.group(2)
        old = lines[1:].split('\n*')
        old = old[:4]
        newlines = '\n*'.join(old)
        newlines = lead.group(1) \
            + f'* [[{my_list_title}]] {refreshed.lower()}: ~~~~~\n*' \
            + newlines \
            + lead.group(3)
        text = text.replace(lead.group(), newlines)
    except AttributeError:
        print(
            "The lead section of the listshop is corrupted, couldn't refresh.")
            
    summary = editsum if editsum else f'{refreshed}: [[{my_list_title}]]'
    # Botflag will soon be depracated, change 'botflag' to 'bot'!
    page.put(text, summary, botflag=bot)

And here is a little sample how to use it:

#!/usr/bin/env python3
"""This is a simple boilerplate to use the listshop module."""

'''Your imports here'''
import listshop

'''
Your own stuff comes here.
Create a maintenance list and save it.
'''

# Finally:
title = 'user:BinBot/BinBot kicsiny listaboltja'  # A sample listshop
listshop.refresh(title, 'teszt', 'Wikipedia:Hypotethical page', 'Bottest', 
                 notice='123 items found.', bot=False)