Skip to content
Merged
118 changes: 118 additions & 0 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`mw_api` is a Python library for interacting with the MediaWiki API. It provides a high-level interface for bot operations on Wikimedia projects (Wikipedia, MDWiki, etc.) including page editing, category traversal, and database operations.

## Development Commands

### Running Tests

```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_MainPage.py

# Run with markers
pytest -m unit # Unit tests only
pytest -m "not slow" # Skip slow tests
pytest -m network # Network-dependent tests

# Run single test function
pytest tests/test_MainPage.py::test_page_exists -v
```

### Installing Dependencies

```bash
pip install -r requirements.in
```

## Architecture

### Entry Point: ALL_APIS

The `ALL_APIS` class (`mw_api/pages_bots/all_apis.py`) is the central entry point. It handles authentication and provides factory methods for the three main components:

```python
from mw_api import ALL_APIS
api = ALL_APIS(lang='en', family='wikipedia', username='user', password='pwd')

page = api.MainPage('Title') # Page operations
cat_members = api.CatDepth('Category:...') # Category traversal
new_api = api.NEW_API() # General API queries
```

### Core Components

1. **MainPage** (`mw_api/super/S_Page/super_page.py`) - Page interactions:
- `get_text()`, `save()`, `create()`, `purge()`
- `exists()`, `namespace()`, `get_categories()`, `get_templates()`
- `can_edit()` - Bot edit validation

2. **NEW_API** (`mw_api/super/S_API/bot_api.py`) - General MediaWiki API queries:
- `Search()`, `Get_All_pages()`, `Get_Newpages()`
- `Find_pages_exists_or_not()`, `Get_langlinks_for_list()`
- `Get_template_pages()`, `get_revisions()`

3. **CatDepth** (`mw_api/super/S_Category/catdepth_new.py`) - Recursive category traversal

### Session Management

`SessionManager` (`mw_api/core/container.py`) manages HTTP sessions and authentication state. It replaces global mutable state with dependency injection for testability.

### Login Flow

`Login` class (`mw_api/super/super_login.py`) handles authentication. The `login_bot` instance is passed through the component hierarchy.

### Protocols

Type protocols are defined in `mw_api/core/protocols.py`:
- `LoginBotProtocol` - Interface for login bot instances
- `SessionProtocol` - HTTP session interface

### Supporting Modules

- `mw_api/api_utils/botEdit.py` - Bot edit validation logic
- `mw_api/api_utils/txtlib.py` - Wikitext parsing utilities
- `mw_api/api_utils/wd_sparql.py` - Wikidata SPARQL queries
- `mw_api/DB_bots/db_bot.py` - SQLite wrapper (LiteDB)
- `mw_api/DB_bots/pymysql_bot.py` - MySQL operations

### Logging

The library uses `colorlog` for colored console output. Logging is auto-configured on import via `mw_api/__init__.py`. Messages can contain color tags like `<<lightgreen>>` for formatted output.

## Module Organization

```
mw_api/
__init__.py # Public exports
all_apis.py # Re-exports ALL_APIS
pages_bots/all_apis.py # ALL_APIS implementation
core/
container.py # SessionManager
protocols.py # Type protocols
config.py # BotConfig
exceptions.py # Custom exceptions
super/
S_Page/ # MainPage, PAGE_APIS
S_API/ # NEW_API, BOTS_APIS
S_Category/ # CatDepth, CategoryDepth
super_login.py # Login class
api_utils/ # Utilities (botEdit, txtlib, etc.)
DB_bots/ # Database operations
auth/ # Authentication components
api/ # Low-level API client
```

## Key Patterns

- **Dependency Injection**: The `login_bot` instance is passed to all components that need API access
- **Lazy Loading**: Page data is fetched on-demand (e.g., `get_text()` loads text when first accessed)
- **Caching**: `@lru_cache` is used for operations like title processing
- **Protocols**: Use protocols for type hints to avoid tight coupling between modules
3 changes: 0 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,4 @@ tests/super_login_old.py
super/S_Login/jar.py
super/S_Login/mwclient.pyyy.py
wait_time_errors.bash
super/Login_db/bot1.py
super/Login_db/lite.py
/.claude
.github/workflows/python-publish.yml
12 changes: 9 additions & 3 deletions mw_api/api_utils/ask_bot.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,23 @@

"""

import difflib
import logging

from ..core.config import get_default_config
from . import printe

logger = logging.getLogger(__name__)
yes_answer = ["y", "a", "", "Y", "A", "all", "aaa"]

Save_or_Ask = {}


def showDiff(text, newtext):
logger.info("Showing diff between current and new text...")
diff = difflib.unified_diff(text.splitlines(), newtext.splitlines(), lineterm="")
for line in diff:
logger.info(line)


class ASK_BOT:
def __init__(self):
pass
Expand Down Expand Up @@ -48,7 +54,7 @@ def ask_put(
if text or newtext:
if not config.no_diff and not nodiff:
if len(newtext) < 70000 and len(text) < 70000 or config.show_diff:
printe.showDiff(text, newtext)
showDiff(text, newtext)
else:
logger.info("showDiff error..")
# ---
Expand Down
Loading
Loading