pynamubot 0.1.0__tar.gz

pynamubot-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.3
+Name: pynamubot
+Version: 0.1.0
+Summary: Python client library for TheSeed-based wiki APIs such as NamuWiki.
+Keywords: namuwiki,theseed,wiki,api,bot
+Author: Iodine at NamuWiki
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Dist: lark>=1.3.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: requests>=2.32.5
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: typing-extensions>=4.9.0
+Requires-Dist: selenium>=4.0.0 ; extra == 'puppet'
+Requires-Python: >=3.9
+Provides-Extra: puppet
+Description-Content-Type: text/markdown
+
+# pynamubot
+
+Python client library for TheSeed-based wiki APIs (for example, NamuWiki).
+
+## Installation
+
+```bash
+pip install pynamubot
+```
+
+If you need Selenium-based utilities:
+
+```bash
+pip install "pynamubot[puppet]"
+```
+
+## Quick start
+
+```python
+from pynamubot.api import TheSeedAPIClient
+
+client = TheSeedAPIClient(
+    base_url="https://namu.wiki/api",
+    api_token="YOUR_API_TOKEN",
+)
+
+response = client.edit_get("TestDocument")
+print(response.exists, response.token)
+```
+
+## Requirements
+
+- Python 3.9+
+- A valid API token issued by the target wiki
+
+## Reference
+
+- TheSeed API docs: <https://doc.theseed.io/>

pynamubot-0.1.0/README.md

@@ -0,0 +1,38 @@
+# pynamubot
+
+Python client library for TheSeed-based wiki APIs (for example, NamuWiki).
+
+## Installation
+
+```bash
+pip install pynamubot
+```
+
+If you need Selenium-based utilities:
+
+```bash
+pip install "pynamubot[puppet]"
+```
+
+## Quick start
+
+```python
+from pynamubot.api import TheSeedAPIClient
+
+client = TheSeedAPIClient(
+    base_url="https://namu.wiki/api",
+    api_token="YOUR_API_TOKEN",
+)
+
+response = client.edit_get("TestDocument")
+print(response.exists, response.token)
+```
+
+## Requirements
+
+- Python 3.9+
+- A valid API token issued by the target wiki
+
+## Reference
+
+- TheSeed API docs: <https://doc.theseed.io/>

pynamubot-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "pynamubot"
+version = "0.1.0"
+description = "Python client library for TheSeed-based wiki APIs such as NamuWiki."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Iodine at NamuWiki" },
+]
+keywords = ["namuwiki", "theseed", "wiki", "api", "bot"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "lark>=1.3.1",
+    "pydantic>=2.12.5",
+    "requests>=2.32.5",
+    "structlog>=25.5.0",
+    "typing-extensions>=4.9.0",
+]
+
+[project.optional-dependencies]
+puppet = ["selenium>=4.0.0"]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"

pynamubot-0.1.0/src/pynamubot/__init__.py

@@ -0,0 +1,4 @@
+from .__version__ import __version__
+from .api import TheSeedAPIClient
+
+__all__ = ["TheSeedAPIClient", "__version__"]

pynamubot-0.1.0/src/pynamubot/__version__.py

@@ -0,0 +1,6 @@
+__title__ = "pynamubot"
+__description__ = "A Python client for the Namuwiki API."
+__version__ = "0.1.0"
+__author__ = "Iodine at NamuWiki"
+__license__ = "MIT"
+__copyright__ = "Copyright Iodine at NamuWiki"

pynamubot-0.1.0/src/pynamubot/api/__init__.py

@@ -0,0 +1,4 @@
+from . import schemas
+from .api import TheSeedAPIClient
+
+__all__ = ["TheSeedAPIClient", "schemas"]

pynamubot-0.1.0/src/pynamubot/api/api.py

@@ -0,0 +1,172 @@
+"""
+TheSeedAPI client for interacting with the API endpoints.
+"""
+
+import time
+from functools import cached_property
+from types import TracebackType
+from typing import Any, Optional
+
+import requests
+import structlog
+from typing_extensions import Self
+
+from ..__version__ import __title__, __version__
+from ..api.schemas import *
+
+
+class Limiter:
+    """
+    A simple rate limiter to enforce a minimum interval between requests.
+
+    Note that NamuWiki's soft rate limit is 1 request per second. Setting interval_seconds to 1.0 is recommended.
+    """
+
+    def __init__(self, interval_seconds: float) -> None:
+        """
+        Initialize the rate limiter.
+
+        :param interval_seconds: The minimum interval between requests in seconds. Setting this to 0 disables rate limiting by not calling sleep at all.
+        """
+        self.interval = float(interval_seconds)
+        if self.interval <= 0.0:
+            self.acquire = lambda: None
+        self.last = float("-inf")
+
+    def acquire(self) -> None:
+        """
+        Acquire the limiter before making a request. This will block if necessary to enforce the rate limit.
+        """
+        now = time.monotonic()
+        elapsed = now - self.last
+        wait = self.interval - elapsed
+        time.sleep(max(0.0, wait))
+        self.last = time.monotonic()
+
+    def __enter__(self) -> Self:
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type: Optional[type[BaseException]], exc_value: Optional[BaseException], traceback: Optional[TracebackType]) -> None:
+        pass
+
+
+class TheSeedAPIClient:
+    """
+    Client for interacting with TheSeedAPI endpoints.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_token: str,
+        logger: Optional[structlog.stdlib.BoundLogger] = None,
+        limiter: Optional[Limiter] = None,
+    ) -> None:
+        """
+        Initialize TheSeedAPI with the API token and base URL.
+
+        :param base_url: The base URL for the API endpoints.
+        :param api_token: The API token string.
+        :param session: An optional requests session to use for the API calls. Defaults to None (creates a new session).
+        :param logger: An optional structlog logger. Defaults to None (creates a new logger).
+        :param limiter: An optional rate limiter. Defaults to None (no limiter).
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_token = api_token
+        headers = {
+            "Authorization": f"Bearer {self.api_token}",
+            "Content-Type": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        self.session = requests.Session()
+        self.session.headers.update(headers)
+        self.logger = logger if logger is not None else structlog.get_logger(__name__)
+        self.limiter = limiter if limiter is not None else Limiter(0.0)
+
+    @cached_property
+    def user_agent(self) -> str:
+        """
+        Get the user agent string for the API client.
+
+        :return: The user agent string.
+        """
+        return f"{requests.utils.default_user_agent()} {__title__}/{__version__}"
+
+    def edit_get(self, document: str) -> EditGETResponse:
+        """
+        Fetch the content of the document.
+
+        :param document: The document to fetch.
+        :return response: A dictionary containing the document text, existence status, and edit token.
+        """
+        url = f"{self.base_url}/edit/{document}"
+        with self.limiter, self.session.get(url) as response:
+            response.raise_for_status()
+            return EditGETResponse.model_validate(response.json())
+
+    def edit_post(self, document: str, body: EditPOSTBody) -> EditPOSTResponse:
+        """
+        Edit the document with new text.
+
+        :param document: The document to edit.
+        :param body: A dictionary containing the new text, log message, and edit token.
+        :return response: A dictionary containing the revision number of the edit.
+        """
+        url = f"{self.base_url}/edit/{document}"
+        with self.limiter, self.session.post(url, json=body) as response:
+            response.raise_for_status()
+            return EditPOSTResponse.model_validate(response.json())
+
+    def backlink(
+        self,
+        document: str,
+        namespace: Optional[str] = None,
+        flag: Optional[int] = None,
+        fromm: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> BacklinkResponse:
+        """
+        Retrieve backlinks for the document.
+
+        Note: The behavior when both fromm and until are not None is not well-defined.
+
+        :param document: The document to retrieve backlinks for.
+        :param namespace: The namespace of documents to query.
+        :param flag: Filter on how document is linked to this document.
+        :param fromm: Paginate from this document (inclusive). Note the double 'm' to avoid Python keyword conflict.
+        :param until: Paginate until this document (inclusive).
+        :return response: A dictionary containing the namespaces, backlinks, and from/to information.
+        """
+        url = f"{self.base_url}/backlink/{document}"
+        params: dict[str, Any] = {
+            "namespace": namespace,
+            "flag": flag,
+            "from": fromm,
+            "until": until,
+        }
+
+        with self.limiter, self.session.get(url, params=params) as response:
+            response.raise_for_status()
+            return BacklinkResponse.model_validate(response.json())
+
+    def discuss(self, document: str) -> list[DiscussResponse]:
+        """
+        Fetch discussions on the document.
+
+        :param document: The document to fetch discussions for.
+        :return response: A list of dictionaries containing the slug, topic, updated date, and status of the discussions.
+        """
+        url = f"{self.base_url}/discuss/{document}"
+        with self.limiter, self.session.get(url) as response:
+            response.raise_for_status()
+            return [DiscussResponse.model_validate(item) for item in response.json()]
+
+    def __del__(self) -> None:
+        self.session.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: Optional[type[BaseException]], exc_value: Optional[BaseException], traceback: Optional[TracebackType]) -> None:
+        self.session.close()

pynamubot-0.1.0/src/pynamubot/api/schemas.py

@@ -0,0 +1,57 @@
+"""
+Typed request and response schema definitions for TheSeedAPI.
+
+This module defines multiple `TypedDict` classes that describe the
+expected structure of JSON request bodies and response payloads
+when interacting with TheSeedAPI using the `requests` library.
+
+Each class is meant to serve as a static typing adi for improved
+editor support, validation, and readability in API-related code.
+
+See <https://doc.theseed.io/> for full API documentation.
+"""
+
+from datetime import datetime
+from typing import Literal, Optional
+from pydantic import BaseModel, Field
+
+
+class EditGETResponse(BaseModel):
+    text: str = Field(description="The content of the document")
+    exists: bool = Field(description="Whether the document exists")
+    token: str = Field(description="The edit token (will be used for edit POST request)")
+
+
+class EditPOSTBody(BaseModel):
+    text: str = Field(description="The edited document text")
+    log: str = Field(description="Edit summary")
+    token: str = Field(description="The edit token (from edit GET request)")
+
+
+class EditPOSTResponse(BaseModel):
+    status: str = Field(description="The status of the edit operation")
+    rev: int = Field(description="The edited revision")
+
+
+class Namespaces(BaseModel):
+    namespace: str = Field(description="The namespace of the document")
+    count: int = Field(description="The number of documents in the namespace")
+
+
+class Backlinks(BaseModel):
+    document: str = Field(description="The document linked to")
+    flags: str = Field(description="Linking flags")
+
+
+class BacklinkResponse(BaseModel):
+    namespaces: list[Namespaces] = Field(description="List of namespaces")
+    backlinks: list[Backlinks] = Field(description="List of backlinks")
+    fromm: Optional[str] = Field(description="Starting point for the query")
+    until: Optional[str] = Field(description="Ending point for the query")
+
+
+class DiscussResponse(BaseModel):
+    slug: str = Field(description="The discussion slug")
+    topic: str = Field(description="The discussion topic")
+    updated_date: datetime = Field(description="The last comment's Unix timestamp")
+    status: Literal["normal", "close", "pause"] = Field(description="The discussion status")

pynamubot-0.1.0/src/pynamubot/jobs/job_core.py

@@ -0,0 +1,35 @@
+from collections import OrderedDict
+from typing import Any, Optional
+
+import structlog
+
+from ..api import TheSeedAPIClient
+
+
+class JobModule:
+    client: TheSeedAPIClient
+
+    def __init__(self, name: Optional[str] = None, logger: Optional[structlog.stdlib.BoundLogger] = None) -> None:
+        self._modules: OrderedDict[str, "JobModule"] = OrderedDict()
+        self.name = name or self.__class__.__name__
+        self.logger = logger or structlog.get_logger(self.name)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        super().__setattr__(key, value)
+        if isinstance(value, JobModule):
+            name, module = key, value
+            self._modules[name] = module
+            if hasattr(self, "client"):
+                self._propagate_attribute(module, "client", self.client)
+
+    def _propagate_attribute(self, module: "JobModule", attr_name: str, attr_value: Any) -> None:
+        if not hasattr(module, attr_name):
+            setattr(module, attr_name, attr_value)
+            for sub_module in module._modules.values():
+                self._propagate_attribute(sub_module, attr_name, attr_value)
+
+    def add_module(self, name: str, module: "JobModule") -> None:
+        """Add a sub-module to this job module."""
+        self._modules[name] = module
+        if hasattr(self, "client"):
+            self._propagate_attribute(module, "client", self.client)

pynamubot-0.1.0/src/pynamubot/jobs/jobs.py

@@ -0,0 +1,420 @@
+import re
+import time
+from typing import Any, Callable
+
+from .. import specific
+from ..api.api import TheSeedAPIClient
+from ..api.schemas import *
+from ..jobs.job_core import JobModule
+from ..utils import josalib
+from ..utils.misc import safe_div
+
+
+def cleanup_backlinks(
+    client: TheSeedAPIClient,
+    halt_discuss_document: str,
+    pairs: list[tuple[str, str, josalib.JosaType]],
+    throttle_seconds: float = 1.0,
+) -> None:
+    job = BacklinkCleanupJob(
+        client=client,
+        halt_discuss_document=halt_discuss_document,
+        pairs=pairs,
+        throttle_seconds=throttle_seconds,
+    )
+    job.execute()
+
+
+def compile_pattern(pairs: list[tuple[str, str, josalib.JosaType]]) -> re.Pattern[str]:
+    before_patterns = "|".join(rf"(?P<before_{i}>{re.escape(before)})" for i, (before, _, _) in enumerate(pairs))
+
+    pattern = rf"""
+        \[\[                         # [[ (start of link)
+        \s*                          # optional whitespace
+        (?:{before_patterns})        # one of the before patterns
+        \s*                          # optional whitespace
+        (?:\|(?P<label>[^[\]]+))?    # optional |label
+        \]\]                         # ]] (end of link)
+        (?P<josa>[가-힣]+)?           # optional josa
+    """
+
+    compiled_pattern = re.compile(pattern, re.VERBOSE)
+    return compiled_pattern
+
+
+def fetch_backlink_documents(client: TheSeedAPIClient, pairs: list[tuple[str, str, josalib.JosaType]]) -> set[str]:
+    documents_to_edit: set[str] = set()
+
+    for before, _, _ in pairs:
+        fromm = None
+
+        while True:
+            response = client.backlink(
+                document=before,
+                namespace=None,
+                flag=specific.namuwiki.BacklinkType.ANY,
+                fromm=fromm,
+            )
+
+            if not response.backlinks:
+                break
+
+            documents_to_edit.update(link.document for link in response.backlinks)
+            fromm = response.until
+
+    return documents_to_edit
+
+
+def catch_halt_signal(client: TheSeedAPIClient, halt_discuss_document: str) -> bool:
+    """Check for a halt signal in the discuss document."""
+    responses = client.discuss(halt_discuss_document)
+    first_normal_response = next((r for r in responses if r.status == "normal"), None)
+    if first_normal_response is not None:
+        return True
+    return False
+
+
+class ThrottleJob(JobModule):
+    def __init__(self, wait_seconds: float = 1.0, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.wait_seconds = max(0.0, float(wait_seconds))
+
+    def __call__(self) -> None:
+        time.sleep(self.wait_seconds)
+
+
+class CatchHaltSignalJob(JobModule):
+    def __init__(self, halt_discuss_document: str, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.halt_discuss_document = halt_discuss_document
+        self._pre_hooks: list[Callable[[], Any]] = []
+
+    def register_pre_hook(self, hook: Callable[[], Any]) -> None:
+        self._pre_hooks.append(hook)
+
+    def __call__(self) -> bool:
+        for hook in self._pre_hooks:
+            hook()
+        return catch_halt_signal(self.client, self.halt_discuss_document)
+
+
+class BacklinkCleanupJob(JobModule):
+    HALT_CHECK_INTERVAL = 100
+
+    def __init__(
+        self,
+        client: TheSeedAPIClient,
+        halt_discuss_document: str,
+        pairs: list[tuple[str, str, josalib.JosaType]],
+        throttle_seconds: float = 1.0,
+        *args: Any,
+        **kwargs: Any,
+    ):
+        super().__init__(*args, **kwargs)
+        self.client = client
+        self.pairs = pairs
+        self.patterns = self._compile_patterns(pairs)
+        self.throttler = ThrottleJob(wait_seconds=throttle_seconds)
+        self.catcher = CatchHaltSignalJob(halt_discuss_document=halt_discuss_document)
+        self.catcher.register_pre_hook(self.throttler)
+
+        self._reset_history()
+
+    def get_history_summary(self) -> dict[str, Any]:
+        """Get a summary of the job execution history with additional metrics."""
+        total_processed = self.history["success"] + self.history["failure"] + self.history["skipped"]
+        return {
+            **self.history,
+            "total_processed": total_processed,
+            "success_rate": safe_div(self.history["success"], total_processed),
+            "avg_occurrences_per_document": safe_div(self.history["occurrences"], total_processed),
+        }
+
+    def _compile_patterns(self, pairs: list[tuple[str, str, josalib.JosaType]]) -> re.Pattern[str]:
+        self.logger.debug(
+            "Compiling regex patterns for backlink cleanup",
+            pattern_count=len(pairs),
+            patterns=[{"before": before, "after": after, "josa_type": josa_type.value} for before, after, josa_type in pairs],
+        )
+
+        before_patterns = "|".join(rf"(?P<before_{i}>{re.escape(before)})" for i, (before, _, _) in enumerate(pairs))
+
+        pattern = rf"""
+            \[\[                         # [[ (start of link)
+            \s*                          # optional whitespace
+            (?:{before_patterns})        # one of the before patterns
+            \s*                          # optional whitespace
+            (?:\|(?P<label>[^[\]]+))?    # optional |label
+            \]\]                         # ]] (end of link)
+            (?P<josa>[가-힣]+)?           # optional josa
+        """
+
+        compiled_pattern = re.compile(pattern, re.VERBOSE)
+        self.logger.debug(
+            "Successfully compiled regex pattern for backlink cleanup",
+            pattern=pattern,
+        )
+        return compiled_pattern
+
+    def execute(self, *args: Any, **kwargs: Any) -> Any:
+        self.logger.info("Starting backlink cleanup job")
+        documents_to_edit = sorted(self._fetch_backlink_documents())
+
+        self.logger.info("Beginning document processing", total_documents=len(documents_to_edit))
+        try:
+            self._process_documents(documents_to_edit)
+        except Exception as e:
+            self.logger.error(
+                "Backlink cleanup job failed",
+                error=str(e),
+                error_type=type(e).__name__,
+                final_stats=self.get_history_summary(),
+            )
+            raise
+        else:
+            self.logger.info(
+                "Backlink cleanup job completed",
+                final_stats=self.get_history_summary(),
+            )
+
+    def _reset_history(self) -> None:
+        """Reset history counters for this execution."""
+        self.history = {
+            "success": 0,
+            "failure": 0,
+            "skipped": 0,
+            "occurrences": 0,
+        }
+
+    def _process_documents(self, documents_to_edit: list[str]) -> None:
+        """Process all documents in the list."""
+        for i, document in enumerate(documents_to_edit):
+            if self._should_check_halt_signal(i):
+                if self._check_halt_and_maybe_return(i):
+                    return
+
+            self._log_document_progress(document, i, len(documents_to_edit))
+            self._process_single_document(document)
+
+    def _should_check_halt_signal(self, index: int) -> bool:
+        """Check if we should check for halt signal at this iteration."""
+        return index % self.HALT_CHECK_INTERVAL == 0
+
+    def _check_halt_and_maybe_return(self, processed_count: int) -> bool:
+        """Check for halt signal and return True if should terminate early."""
+        self.throttler()
+        if self.catcher():
+            self.logger.info(
+                "Halt signal detected - terminating job early",
+                processed_documents=processed_count,
+                final_stats=self.get_history_summary(),
+            )
+            return True
+        return False
+
+    def _log_document_progress(self, document: str, index: int, total: int) -> None:
+        """Log progress for current document."""
+        self.logger.debug(
+            "Processing document",
+            document=document,
+            progress=f"{index + 1}/{total}",
+            percentage=f"{(index + 1) / total: 6.2%}",
+        )
+
+    def _process_single_document(self, document: str) -> None:
+        """Process a single document with error handling."""
+        try:
+            self._edit_document(document)
+        except Exception as e:
+            self.logger.error(
+                "Failed to edit document",
+                document=document,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            self.history["failure"] += 1
+
+    def _fetch_backlink_documents(self) -> set[str]:
+        self.logger.debug("Starting backlink document collection")
+        documents_to_edit: set[str] = set()
+
+        for before, _, _ in self.pairs:
+            self.logger.debug("Fetching backlinks for document", document=before)
+            fromm = None
+
+            while True:
+                self.logger.debug(
+                    "Requesting backlink batch",
+                    source_document=before,
+                    from_cursor=fromm,
+                )
+
+                self.throttler()
+                response = self.client.backlink(
+                    document=before,
+                    namespace=None,
+                    flag=specific.namuwiki.BacklinkType.ANY,
+                    fromm=fromm,
+                )
+
+                if not response.backlinks:
+                    self.logger.debug(
+                        "Reached end of backlinks",
+                        source_document=before,
+                        final_cursor=response.fromm,
+                    )
+                    break
+                else:
+                    self.logger.debug(
+                        "Retrieved backlink batch",
+                        source_document=before,
+                        batch_size=len(response.backlinks),
+                        from_cursor=response.fromm,
+                        until_cursor=response.until,
+                    )
+
+                documents_to_edit.update(link.document for link in response.backlinks)
+                fromm = response.until
+
+        self.logger.info(
+            "Backlink document collection completed",
+            total_unique_documents=len(documents_to_edit),
+            source_documents=[before for before, _, _ in self.pairs],
+        )
+
+        return documents_to_edit
+
+    def _replace_link(self, m: re.Match[str]) -> str:
+        for i, (before, after, josa_type) in enumerate(self.pairs):
+            if m.group(f"before_{i}") is None:
+                continue
+
+            josa_old = m.group("josa")
+            label = m.group("label")
+
+            self.logger.debug(
+                "Processing link replacement",
+                before=before,
+                after=after,
+                original_josa=josa_old,
+                original_label=label,
+                josa_type=josa_type.value,
+            )
+
+            if josa_old is None:
+                josa_new = ""
+            else:
+                try:
+                    fitter = josalib.get_josa_fitter(josa_type)
+                    josa_new = fitter(josa_old)
+                    self.logger.debug(
+                        "Josa transformation successful",
+                        original_josa=josa_old,
+                        transformed_josa=josa_new,
+                    )
+                except josalib.AmbiguousJosaError:
+                    self.logger.debug(
+                        "Ambiguous josa encountered - preserving original",
+                        original_josa=josa_old,
+                        fallback_label=before,
+                    )
+                    label, josa_new = before, josa_old
+
+            if label is None or label == after:
+                result = f"[[{after}]]{josa_new}"
+            else:
+                result = f"[[{after}|{label}]]{josa_new}"
+
+            self.logger.debug(
+                "Link replacement completed",
+                original_match=m.group(0),
+                replacement=result,
+            )
+            return result
+
+        assert False
+
+    def _edit_document(self, document: str):
+        self.logger.debug("Starting document edit", document=document)
+        self.throttler()
+        response = self.client.edit_get(document=document)
+
+        if not response.exists:
+            self._handle_nonexistent_document(document)
+            return
+
+        original_text = response.text
+        edited_text = self.patterns.sub(self._replace_link, original_text)
+
+        matches = list(self.patterns.finditer(original_text))
+        self.history["occurrences"] += len(matches)
+
+        if original_text == edited_text:
+            self._handle_no_changes_needed(document, matches)
+            return
+
+        self._submit_document_changes(document, original_text, edited_text, matches, response.token)
+
+    def _handle_nonexistent_document(self, document: str) -> None:
+        """Handle case where document doesn't exist."""
+        self.logger.debug("Document does not exist - skipping edit", document=document)
+        self.history["failure"] += 1
+
+    def _handle_no_changes_needed(self, document: str, matches: list[re.Match[str]]) -> None:
+        """Handle case where no changes are needed."""
+        self.logger.debug(
+            "No changes needed for document",
+            document=document,
+            pattern_matches=len(matches),
+        )
+        self.history["skipped"] += 1
+
+    def _submit_document_changes(
+        self,
+        document: str,
+        original_text: str,
+        edited_text: str,
+        matches: list[re.Match[str]],
+        token: str,
+    ) -> None:
+        """Submit the document changes to the API."""
+        self.logger.debug(
+            "Submitting document changes",
+            document=document,
+            pattern_matches=len(matches),
+            text_length_change=len(edited_text) - len(original_text),
+        )
+
+        try:
+            self.throttler()
+            response = self.client.edit_post(
+                document=document,
+                body=EditPOSTBody(
+                    text=edited_text,
+                    log="🌳🤖",
+                    token=token,
+                ),
+            )
+            self._handle_successful_edit(document, response.rev)
+        except Exception as e:
+            self._handle_failed_edit(document, e)
+
+    def _handle_successful_edit(self, document: str, revision: Any) -> None:
+        """Handle successful document edit."""
+        self.history["success"] += 1
+        self.logger.debug(
+            "Document edit completed successfully",
+            document=document,
+            revision=revision,
+        )
+
+    def _handle_failed_edit(self, document: str, error: Exception) -> None:
+        """Handle failed document edit."""
+        self.history["failure"] += 1
+        self.logger.error(
+            "Failed to submit document edit",
+            document=document,
+            error=str(error),
+            error_type=type(error).__name__,
+        )
+        raise

pynamubot-0.1.0/src/pynamubot/parse/__init__.py

@@ -0,0 +1,3 @@
+from .parser import get_parser, parse_markup
+
+__all__ = ["get_parser", "parse_markup"]

pynamubot-0.1.0/src/pynamubot/parse/parser.py

@@ -0,0 +1,31 @@
+from importlib.resources import files
+from functools import lru_cache
+
+from lark import Lark, Tree
+
+
+def _load_grammar() -> str:
+    return files("pynamubot.parse").joinpath("theseed.lark").read_text(encoding="utf-8")
+
+
+@lru_cache(maxsize=1)
+def get_parser() -> Lark:
+    try:
+        return Lark(_load_grammar(), parser="lalr")
+    except Exception as exc:
+        raise RuntimeError("The bundled TheSeed grammar is incomplete and cannot be loaded yet.") from exc
+
+
+def parse_markup(text: str) -> Tree:
+    return get_parser().parse(text)
+
+
+class _LazyParser:
+    def parse(self, text: str) -> Tree:
+        return get_parser().parse(text)
+
+    def __getattr__(self, name: str):
+        return getattr(get_parser(), name)
+
+
+parser = _LazyParser()

pynamubot-0.1.0/src/pynamubot/parse/theseed.lark

@@ -0,0 +1,71 @@
+start: document
+
+document: redirect_document | namu_mark
+
+redirect_document: REDIRECT_MARKER internal_link
+internal_link: ANY
+
+namu_mark: (namu_mark_atom | NEWLINE)*
+namu_mark_no_newline: namu_mark_atom*
+namu_mark_atom: paragraph
+              | macro
+              | internal_link
+              | external_link
+              | file
+              | classification
+
+paragraph: paragraph_level1_open
+         | paragraph_level2_open
+         | paragraph_level3_open
+         | paragraph_level4_open
+         | paragraph_level5_open
+         | paragraph_level6_open
+         | paragraph_level1_closed
+         | paragraph_level2_closed
+         | paragraph_level3_closed
+         | paragraph_level4_closed
+         | paragraph_level5_closed
+         | paragraph_level6_closed
+
+paragraph_level1_open: "= " namu_mark_no_newline " ="
+paragraph_level2_open: "== " namu_mark_no_newline " =="
+paragraph_level3_open: "=== " namu_mark_no_newline " ==="
+paragraph_level4_open: "==== " namu_mark_no_newline " ===="
+paragraph_level5_open: "===== " namu_mark_no_newline " ====="
+paragraph_level6_open: "====== " namu_mark_no_newline " ======"
+paragraph_level1_closed: "=# " namu_mark_no_newline " #="
+paragraph_level2_closed: "==# " namu_mark_no_newline " #=="
+paragraph_level3_closed: "===# " namu_mark_no_newline " #==="
+paragraph_level4_closed: "====# " namu_mark_no_newline " #===="
+paragraph_level5_closed: "=====# " namu_mark_no_newline " #====="
+paragraph_level6_closed: "======# " namu_mark_no_newline " #======"
+
+macro: "[" macro_name ("(" arguments ")")? "]"
+macro_name: "age"i
+          | "anchor"i
+          | "dday"i
+          | "include"i
+          | "youtube"i
+          | "nicovideo"i
+          | "kakaotv"i
+          | "pagecount"i
+          | "navertv"i
+          | "vimeo"i
+          | "br"i
+          | "clearfix"i
+          | "date"i
+          | "datetime"i
+          | "footnote"i
+          | "tableofcontents"i
+          | "각주"
+          | "목차"
+
+arguments: ANY
+
+NEWLINE: "\n"
+REDIRECT_MARKER: "#redirect"i | "#넘겨주기"
+EXTERNAL_LINK_PROTOCOL: "http"i
+                      | "https"i
+                      | "ftp"i
+ANY: /.+/
+_ANY: /.+/

pynamubot-0.1.0/src/pynamubot/puppet/__init__.py

@@ -0,0 +1,3 @@
+from .puppet import create_driver
+
+__all__ = ["create_driver"]

pynamubot-0.1.0/src/pynamubot/puppet/puppet.py

@@ -0,0 +1,39 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from selenium.webdriver.remote.webdriver import WebDriver as RemoteWebDriver
+
+
+def create_driver(browser_name: str, *, headless: bool = True) -> "RemoteWebDriver":
+    browser = browser_name.lower()
+
+    if browser == "chrome":
+        from selenium.webdriver import Chrome, ChromeOptions
+
+        options = ChromeOptions()
+        if headless:
+            options.add_argument("--headless=new")
+        return Chrome(options=options)
+
+    if browser == "edge":
+        from selenium.webdriver import Edge, EdgeOptions
+
+        options = EdgeOptions()
+        if headless:
+            options.add_argument("--headless=new")
+        return Edge(options=options)
+
+    if browser == "firefox":
+        from selenium.webdriver import Firefox, FirefoxOptions
+
+        options = FirefoxOptions()
+        if headless:
+            options.add_argument("-headless")
+        return Firefox(options=options)
+
+    if browser == "safari":
+        from selenium.webdriver import Safari
+
+        return Safari()
+
+    raise ValueError(f"Unsupported browser: {browser_name}")

pynamubot-0.1.0/src/pynamubot/specific/__init__.py

@@ -0,0 +1,3 @@
+from . import alphawiki, namuwiki, theseedwiki
+
+__all__ = ["alphawiki", "namuwiki", "theseedwiki"]

pynamubot-0.1.0/src/pynamubot/specific/alphawiki.py

@@ -0,0 +1,22 @@
+import enum
+
+
+class NamespaceType(enum.Enum):
+    CATEGORY = "분류"
+    DOCUMENT = "문서"
+    FRAME = "틀"
+    FILE = "파일"
+    TEMPLATE = "템플릿"
+    USER = "사용자"
+    META = "알파위키"
+    TRASH = "휴지통"
+    SYSTEM = "시스템"
+    FILE_TRASH = "파일휴지통"
+
+
+class BacklinkType(enum.IntEnum):
+    ANY = 0
+    LINK = 1
+    FILE = 2
+    INCLUDE = 4
+    REDIRECT = 8

pynamubot-0.1.0/src/pynamubot/specific/namuwiki.py

@@ -0,0 +1,22 @@
+import enum
+
+
+class NamespaceType(enum.Enum):
+    CATEGORY = "분류"
+    DOCUMENT = "문서"
+    FRAME = "틀"
+    FILE = "파일"
+    TEMPLATE = "템플릿"
+    USER = "사용자"
+    META = "나무위키"
+    TRASH = "휴지통"
+    SYSTEM = "시스템"
+    FILE_TRASH = "파일휴지통"
+
+
+class BacklinkType(enum.IntEnum):
+    ANY = 0
+    LINK = 1
+    FILE = 2
+    INCLUDE = 4
+    REDIRECT = 8

pynamubot-0.1.0/src/pynamubot/specific/theseedwiki.py

@@ -0,0 +1,22 @@
+import enum
+
+
+class NamespaceType(enum.Enum):
+    CATEGORY = "분류"
+    DOCUMENT = "문서"
+    FRAME = "틀"
+    FILE = "파일"
+    TEMPLATE = "템플릿"
+    USER = "사용자"
+    META = "더시드위키"
+    TRASH = "휴지통"
+    SYSTEM = "시스템"
+    FILE_TRASH = "파일휴지통"
+
+
+class BacklinkType(enum.IntEnum):
+    ANY = 0
+    LINK = 1
+    FILE = 2
+    INCLUDE = 4
+    REDIRECT = 8

pynamubot-0.1.0/src/pynamubot/utils/josalib.py

@@ -0,0 +1,201 @@
+from enum import Enum
+from typing import Callable, Union
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+Fitter = Callable[[str], str]
+
+
+class JosaError(Exception): ...
+
+
+class AmbiguousJosaError(JosaError): ...
+
+
+class JosaType(Enum):
+    HAS_JONGSEONG = "HAS_JONGSEONG"
+    NO_JONGSEONG = "NO_JONGSEONG"
+    UNKNOWN = "UNKNOWN"
+
+
+_HAS_TO_NO = [
+    ("과", "와"),
+    ("아", "야"),
+    ("으로", "로"),
+    ("으론", "론"),
+    ("은", "는"),
+    ("을", "를"),
+    ("이", "가"),
+    ("이다", "이다"),  # No change for this case
+    ("이며", "이며"),  # No change for this case
+    ("이면", "면"),  # Remove '이' for this case
+    ("이었", "였"),
+    ("이고", "고"),
+    ("이나", "나"),
+    ("이든", "든"),
+    ("이라", "라"),
+    ("이란", "란"),
+    ("이랑", "랑"),
+    ("이셔", "셔"),
+    ("이셨", "셨"),
+    ("이시여", "시여"),
+    ("이여", "여"),
+    ("이래", "래"),
+    ("이랬", "랬"),
+    ("이렷", "렷"),
+    ("이로", "로"),
+    ("이야", "야"),
+    ("아", "야"),
+]
+
+_NO_TO_HAS = [
+    ("와", "과"),
+    ("로", "으로"),
+    ("론", "으론"),
+    ("는", "은"),
+    ("를", "을"),
+    ("가", "이"),
+    ("다", "이다"),  # Add '이' for this case
+    ("며", "이며"),  # Add '이' for this case
+    ("면", "이면"),  # Add '이' for this case
+    ("였", "이었"),
+    ("고", "이고"),
+    ("나", "이나"),
+    ("든", "이든"),
+    ("라", "이라"),
+    ("란", "이란"),
+    ("랑", "이랑"),
+    ("셔", "이셔"),
+    ("셨", "이셨"),
+    ("시", "이시"),
+    ("여", "이여"),
+    ("래", "이래"),
+    ("랬", "이랬"),
+    ("렷", "이렷"),
+    ("야", "아"),  # Ambiguous: could be '아' or '이야'
+    ("야", "이야"),  # Ambiguous: could be '아' or '이야'
+    ("로서", "으로서"),
+    ("로써", "으로써"),
+]
+
+
+def get_josa_type(string: str) -> JosaType:
+    logger.debug("Determining josa type", string=string)
+
+    if not string:
+        logger.debug("Empty string, returning UNKNOWN")
+        return JosaType.UNKNOWN
+
+    last = string[-1]
+    logger.debug("Last character analysis", char=last, unicode_code=ord(last))
+
+    if not "가" <= last <= "힣":
+        logger.debug("Character not in Hangul range, returning UNKNOWN")
+        return JosaType.UNKNOWN
+
+    jongseong = (ord(last) - 44032) % 28
+
+    if jongseong == 0:
+        logger.debug("No jongseong detected", char=last, result="NO_JONGSEONG")
+        return JosaType.NO_JONGSEONG
+    else:
+        logger.debug(
+            "Jongseong detected",
+            char=last,
+            jongseong_index=jongseong,
+            result="HAS_JONGSEONG",
+        )
+        return JosaType.HAS_JONGSEONG
+
+
+def to_has_jongseong(josa: str) -> str:
+    logger.debug("Converting josa to has_jongseong form", input_josa=josa)
+    old_to_new = _NO_TO_HAS
+
+    if josa == "야":
+        logger.info("Encountered ambiguous josa '야'", josa=josa)
+        raise AmbiguousJosaError()
+
+    new_josa_candidates: list[str] = []
+    for old_josa, new_josa in old_to_new:
+        if josa == old_josa:
+            logger.debug("Exact match found", old_josa=old_josa, new_josa=new_josa)
+            return new_josa
+        if josa.startswith(old_josa):
+            candidate = new_josa + josa[len(old_josa) :]
+            new_josa_candidates.append(candidate)
+            logger.debug(
+                "Partial match found",
+                old_josa=old_josa,
+                new_josa=new_josa,
+                candidate=candidate,
+            )
+
+    if not new_josa_candidates:
+        logger.debug("No matches found, returning original", result=josa)
+        return josa
+    else:
+        result = new_josa_candidates[-1]
+        logger.debug(
+            "Multiple candidates found, returning last",
+            candidates=new_josa_candidates,
+            result=result,
+        )
+        return result
+
+
+def to_no_jongseong(josa: str) -> str:
+    logger.debug("Converting josa to no_jongseong form", input_josa=josa)
+    old_to_new = _HAS_TO_NO
+
+    new_josa_candidates: list[str] = []
+    for old_josa, new_josa in old_to_new:
+        if josa == old_josa:
+            logger.debug("Exact match found", old_josa=old_josa, new_josa=new_josa)
+            return new_josa
+        if josa.startswith(old_josa):
+            candidate = new_josa + josa[len(old_josa) :]
+            new_josa_candidates.append(candidate)
+            logger.debug(
+                "Partial match found",
+                old_josa=old_josa,
+                new_josa=new_josa,
+                candidate=candidate,
+            )
+
+    if not new_josa_candidates:
+        if josa.startswith("이"):
+            result = josa[1:]
+            logger.debug("Fallback: removed leading '이'", original=josa, result=result)
+            return result
+        else:
+            logger.debug("No matches found, returning original", result=josa)
+            return josa
+    else:
+        result = new_josa_candidates[-1]
+        logger.debug(
+            "Multiple candidates found, returning last",
+            candidates=new_josa_candidates,
+            result=result,
+        )
+        return result
+
+
+def get_josa_fitter(string: Union[str, JosaType]) -> Fitter:
+    josa_type = string if isinstance(string, JosaType) else get_josa_type(string)
+    logger.debug("Getting josa fitter", input=string, josa_type=josa_type)
+
+    if josa_type == JosaType.UNKNOWN:
+        logger.info("Unknown josa type encountered", input=string)
+        raise ValueError("Unknown josa type")
+    elif josa_type == JosaType.HAS_JONGSEONG:
+        logger.debug("Returning to_no_jongseong fitter")
+        return to_no_jongseong
+    elif josa_type == JosaType.NO_JONGSEONG:
+        logger.debug("Returning to_has_jongseong fitter")
+        return to_has_jongseong
+    else:
+        logger.info("Unknown josa type encountered", input=string)
+        raise ValueError("Unknown josa type")

pynamubot-0.1.0/src/pynamubot/utils/misc.py

@@ -0,0 +1,16 @@
+def safe_div(numerator: float, denominator: float, safe_value: float = 0.0) -> float:
+    """
+    Safely divides two numbers, returning a safe value if the denominator is zero.
+
+    Args:
+        numerator (float): The numerator of the division.
+        denominator (float): The denominator of the division.
+        safe_value (float, optional): The value to return if the denominator is zero. Defaults to 0.0.
+
+    Returns:
+        float: The result of the division or the safe value if the denominator is zero.
+    """
+    try:
+        return numerator / denominator
+    except ZeroDivisionError:
+        return safe_value