mwclient-cli 0.1.0__py3-none-any.whl

mwclient-cli/__init__.py

@@ -0,0 +1,5 @@
+"""mwclient-cli package."""
+
+from .cli import run
+
+__all__ = ["run"]

mwclient-cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

mwclient-cli/cli.py

@@ -0,0 +1,401 @@
+"""Command-line wrapper for mwclient."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import importlib
+import inspect
+import json
+import os
+import sys
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+import html2text
+
+_ENTITY_LOCATIONS = {
+    "site": ("mwclient.client", "Site"),
+    "page": ("mwclient.page", "Page"),
+    "image": ("mwclient.image", "Image"),
+}
+
+
+class HelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """Preserve newlines in help text."""
+
+
+def resolve_entity_class(entity: str) -> Any:
+    module_name, class_name = _ENTITY_LOCATIONS[entity]
+    module = importlib.import_module(module_name)
+    return getattr(module, class_name)
+
+
+def list_public_methods(entity: str) -> dict[str, Any]:
+    cls = resolve_entity_class(entity)
+    methods: dict[str, Any] = {}
+    for name, member in inspect.getmembers(cls, predicate=callable):
+        if name.startswith("_"):
+            continue
+        methods[name] = member
+    return methods
+
+
+def parse_cli_value(raw: str) -> Any:
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return raw
+
+
+def parse_keyword_args(items: list[str]) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {}
+    for item in items:
+        if "=" not in item:
+            raise ValueError(f"invalid --kw value '{item}', expected key=value")
+        key, raw_value = item.split("=", 1)
+        if not key:
+            raise ValueError("empty --kw key is not allowed")
+        kwargs[key] = parse_cli_value(raw_value)
+    return kwargs
+
+
+def normalize_result(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, bytes):
+        return {
+            "__type__": "bytes",
+            "base64": base64.b64encode(value).decode("ascii"),
+            "size": len(value),
+        }
+    if isinstance(value, Mapping):
+        return {str(key): normalize_result(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [normalize_result(item) for item in value]
+    return repr(value)
+
+
+def build_site(args: argparse.Namespace) -> Any:
+    site_class = resolve_entity_class("site")
+    site = site_class(
+        args.host,
+        path=args.path,
+        ext=args.ext,
+        scheme=args.scheme,
+        do_init=not args.no_init,
+        force_login=not args.allow_anon,
+        clients_useragent=args.clients_useragent,
+    )
+    if args.username:
+        site.login(args.username, args.password)
+    return site
+
+
+def build_target(site: Any, args: argparse.Namespace) -> Any:
+    if args.command == "site":
+        return site
+    if args.command == "page":
+        return site.pages[args.title]
+    if args.command == "image":
+        return site.images[args.title]
+    raise ValueError(f"unsupported command {args.command}")
+
+
+def print_json(value: Any, indent: int | None) -> None:
+    json.dump(normalize_result(value), sys.stdout, indent=indent, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def print_text(value: str) -> None:
+    sys.stdout.write(value.rstrip("\n"))
+    sys.stdout.write("\n")
+
+
+def print_method_list(entity: str) -> int:
+    methods = list_public_methods(entity)
+    for name in sorted(methods):
+        signature = inspect.signature(methods[name])
+        print(f"{entity}.{name}{signature}")
+    return 0
+
+
+def html_to_markdown(value: str) -> str:
+    converter = html2text.HTML2Text()
+    converter.body_width = 0
+    converter.ignore_images = False
+    converter.ignore_links = False
+    return converter.handle(value).strip()
+
+
+def normalize_page_title(value: str) -> str:
+    return value.replace("_", " ").strip()
+
+
+def extract_parse_html(parse_result: Any) -> str | None:
+    if not isinstance(parse_result, Mapping):
+        return None
+    text_data = parse_result.get("text")
+    if not isinstance(text_data, Mapping):
+        return None
+    text_html = text_data.get("*")
+    return text_html if isinstance(text_html, str) else None
+
+
+def maybe_convert_markdown(args: argparse.Namespace, target: Any, result: Any) -> Any:
+    if not getattr(args, "markdown", False):
+        return result
+
+    if args.command == "page" and args.method == "text" and isinstance(result, str):
+        parse_data = target.site.parse(text=result, title=getattr(target, "name", None))
+        parse_html = extract_parse_html(parse_data)
+        title = normalize_page_title(
+            str(getattr(target, "name", getattr(target, "title", args.title)))
+        )
+        heading = f"# {title}".strip()
+        if parse_html:
+            body = html_to_markdown(parse_html).strip()
+            return f"{heading}\n\n{body}" if body else heading
+        body = result.strip()
+        return f"{heading}\n\n{body}" if body else heading
+
+    if args.command == "site" and args.method == "parse":
+        parse_html = extract_parse_html(result)
+        if parse_html:
+            return html_to_markdown(parse_html)
+        return result
+
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mwclient-cli",
+        formatter_class=HelpFormatter,
+        description=(
+            "Command-line wrapper around mwclient\n\n"
+            "Use one of these targets:\n"
+            "  site  methods from mwclient.Site\n"
+            "  page  methods from mwclient.page.Page\n"
+            "  image methods from mwclient.image.Image"
+        ),
+        epilog=(
+            "Examples:\n"
+            "  mwclient-cli methods site\n"
+            "  mwclient-cli --host host.docker.internal --scheme http --path /w/ "
+            "page \"Main Page\" text\n"
+            "  mwclient-cli --host host.docker.internal --scheme http --path /w/ "
+            "site search --arg space --kw what=text --max-items 5"
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default=os.getenv("MWCLI_HOST"),
+        metavar="HOST",
+        help="Wiki host (no scheme). Env fallback: MWCLI_HOST",
+    )
+    parser.add_argument(
+        "--path",
+        default=os.getenv("MWCLI_PATH", "/w/"),
+        metavar="PATH",
+        help="MediaWiki script path with trailing slash. Default: /w/. Env: MWCLI_PATH",
+    )
+    parser.add_argument(
+        "--ext",
+        default=os.getenv("MWCLI_EXT", ".php"),
+        metavar="EXT",
+        help="Script extension. Default: .php. Env: MWCLI_EXT",
+    )
+    parser.add_argument(
+        "--scheme",
+        default=os.getenv("MWCLI_SCHEME", "https"),
+        metavar="SCHEME",
+        help="URL scheme: http or https. Default: https. Env: MWCLI_SCHEME",
+    )
+    parser.add_argument(
+        "--username",
+        default=os.getenv("MWCLI_USERNAME"),
+        metavar="USERNAME",
+        help="Login username. If set, --password is required. Env: MWCLI_USERNAME",
+    )
+    parser.add_argument(
+        "--password",
+        default=os.getenv("MWCLI_PASSWORD"),
+        metavar="PASSWORD",
+        help="Login password. If set, --username is required. Env: MWCLI_PASSWORD",
+    )
+    parser.add_argument(
+        "--clients-useragent",
+        default=os.getenv("MWCLI_USER_AGENT"),
+        metavar="UA",
+        help="Custom user-agent prefix. Env: MWCLI_USER_AGENT",
+    )
+    parser.add_argument(
+        "--allow-anon",
+        action="store_true",
+        help="Allow unauthenticated edits (sets force_login=False on Site)",
+    )
+    parser.add_argument(
+        "--no-init",
+        action="store_true",
+        help="Skip initial site_init() call during Site creation",
+    )
+    parser.add_argument(
+        "--indent",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Pretty-print JSON output with N-space indentation",
+    )
+    parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help=(
+            "Convert content-read methods to Markdown "
+            "(currently: page text, site parse)"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        required=True,
+        title="commands",
+        metavar="COMMAND",
+    )
+
+    methods_parser = subparsers.add_parser(
+        "methods",
+        formatter_class=HelpFormatter,
+        help="list available methods on site/page/image targets",
+        description="List callable public methods and signatures.",
+        epilog=(
+            "Examples:\n"
+            "  mwclient-cli methods all\n"
+            "  mwclient-cli methods page"
+        ),
+    )
+    methods_parser.add_argument(
+        "entity",
+        choices=["site", "page", "image", "all"],
+        help="Target entity to inspect",
+    )
+
+    for entity in ("site", "page", "image"):
+        entity_parser = subparsers.add_parser(
+            entity,
+            formatter_class=HelpFormatter,
+            help=f"call {entity} method by name",
+            description=(
+                f"Call public method on {entity} target.\n"
+                "Arguments passed via repeated --arg and --kw options."
+            ),
+            epilog=(
+                "Examples:\n"
+                f"  mwclient-cli --host HOST {entity} "
+                + ("\"Main Page\" " if entity == "page" else "\"Example.png\" " if entity == "image" else "")
+                + "METHOD --arg VALUE --kw key=value\n"
+                f"  mwclient-cli methods {entity}"
+            ),
+        )
+        if entity in {"page", "image"}:
+            entity_parser.add_argument("title", help=f"{entity} title")
+        entity_parser.add_argument("method", help=f"{entity} method name")
+        entity_parser.add_argument(
+            "--arg",
+            action="append",
+            default=[],
+            metavar="VALUE",
+            help="Positional method arg (JSON parsed, fallback to string)",
+        )
+        entity_parser.add_argument(
+            "--kw",
+            action="append",
+            default=[],
+            metavar="KEY=VALUE",
+            help="Keyword method arg (value JSON parsed, fallback to string)",
+        )
+        entity_parser.add_argument(
+            "--stream",
+            action="store_true",
+            help="Stream list/tuple results as one JSON object per line",
+        )
+        entity_parser.add_argument(
+            "--max-items",
+            type=int,
+            default=None,
+            metavar="N",
+            help="Limit number of emitted items for iterator/list results",
+        )
+        entity_parser.add_argument(
+            "--markdown",
+            action="store_true",
+            default=argparse.SUPPRESS,
+            help="Convert content-read methods to Markdown",
+        )
+
+    return parser
+
+
+def run(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "methods":
+        if args.entity == "all":
+            for entity in ("site", "page", "image"):
+                print_method_list(entity)
+            return 0
+        return print_method_list(args.entity)
+
+    if not args.host:
+        parser.error("missing --host (or env MWCLI_HOST)")
+
+    if bool(args.username) != bool(args.password):
+        parser.error("set both --username and --password or neither")
+
+    positionals = [parse_cli_value(raw) for raw in args.arg]
+    try:
+        kwargs = parse_keyword_args(args.kw)
+    except ValueError as exc:
+        parser.error(str(exc))
+
+    target = build_target(build_site(args), args)
+    methods = list_public_methods(args.command)
+    if args.method not in methods:
+        parser.error(f"unknown method {args.command}.{args.method}")
+    method = getattr(target, args.method)
+
+    result = method(*positionals, **kwargs)
+    result = maybe_convert_markdown(args, target, result)
+    if isinstance(result, Iterator):
+        max_items = args.max_items
+        count = 0
+        for item in result:
+            print_json(item, args.indent)
+            count += 1
+            if max_items is not None and count >= max_items:
+                break
+        return 0
+
+    if args.stream and isinstance(result, (list, tuple)):
+        max_items = args.max_items
+        items = result if max_items is None else result[:max_items]
+        for item in items:
+            print_json(item, args.indent)
+        return 0
+
+    if args.markdown and isinstance(result, str):
+        print_text(result)
+    else:
+        print_json(result, args.indent)
+    return 0
+
+
+def main() -> None:
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":
+    main()

mwclient_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: mwclient-cli
+Version: 0.1.0
+Summary: CLI wrapper around mwclient
+Requires-Python: >=3.10
+Requires-Dist: html2text==2025.4.15
+Requires-Dist: mwclient==0.11.0
+Provides-Extra: test
+Requires-Dist: pytest==9.0.2; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mwcli
+
+CLI wrapper around `mwclient`. Built for Agents.
+
+Exposes `mwclient` methods from 3 targets:
+- `site` -> `mwclient.Site`
+- `page` -> `mwclient.page.Page`
+- `image` -> `mwclient.image.Image`
+
+## Install
+
+From project dir:
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+## Command shape
+
+```bash
+python -m mwcli [connection flags] <site|page|image> <target args> <method> [--arg ...] [--kw ...] [--markdown]
+```
+
+Connection flags:
+- `--host` required (or `MWCLI_HOST`)
+- `--scheme` default `https`
+- `--path` default `/w/`
+- `--ext` default `.php`
+- `--username`, `--password` optional auth
+
+Method args:
+- `--arg VALUE` positional arg, JSON-parsed when possible
+- `--kw KEY=VALUE` keyword arg, value JSON-parsed when possible
+- `--max-items N` cap iterator/list output
+- `--stream` print list/tuple one JSON per line
+- `--markdown` convert content-read output to Markdown (see below)
+
+Tip: quote strings with spaces/pipes.
+
+## Discover available methods
+
+```bash
+python -m mwcli methods all
+python -m mwcli methods site
+python -m mwcli methods page
+python -m mwcli methods image
+```
+
+## All commands
+
+Top-level commands:
+
+- `python -m mwcli methods {all|site|page|image}`
+- `python -m mwcli site <method> [--arg ...] [--kw ...]`
+- `python -m mwcli page "<title>" <method> [--arg ...] [--kw ...]`
+- `python -m mwcli image "<title>" <method> [--arg ...] [--kw ...]`
+
+`site` methods (mwclient 0.11.0):
+
+- `allcategories`, `allimages`, `alllinks`, `allpages`, `allusers`
+- `api`, `ask`, `blocks`, `checkuserlog`, `chunk_upload`, `clientlogin`
+- `deletedrevisions`, `email`, `expandtemplates`, `exturlusage`
+- `get`, `get_token`, `handle_api_result`, `logevents`, `login`
+- `parse`, `patrol`, `post`, `random`, `raw_api`, `raw_call`, `raw_index`
+- `recentchanges`, `require`, `revisions`, `search`, `site_init`
+- `upload`, `usercontributions`, `users`, `version_tuple_from_generator`, `watchlist`
+
+`page` methods:
+
+- `append`, `backlinks`, `can`, `categories`, `delete`, `edit`, `embeddedin`
+- `extlinks`, `get_token`, `handle_edit_error`, `images`, `iwlinks`, `langlinks`, `links`
+- `move`, `normalize_title`, `prepend`, `purge`, `redirects_to`, `resolve_redirect`
+- `revisions`, `save`, `strip_namespace`, `templates`, `text`, `touch`
+
+`image` methods:
+
+- all `page` methods, plus:
+- `download`, `duplicatefiles`, `imagehistory`, `imageusage`
+
+To confirm runtime command surface on your installed version:
+
+```bash
+python -m mwcli methods all
+```
+
+## Main usage examples
+
+### Get page content
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  page "Main Page" text
+```
+
+Read one section:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  page "Main Page" text --kw section=1
+```
+
+Read as Markdown (`page text` uses `site parse` + `html2text`):
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  page "Main Page" text --markdown
+```
+
+The markdown output starts with:
+
+```md
+# Main Page
+```
+
+### Search
+
+Full text search:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site search --arg "space" --kw what=text --max-items 10
+```
+
+Title-only search:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site search --arg "Main" --kw what=title --max-items 10
+```
+
+### Authentication + edit
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  --username "Admin" --password "secret" \
+  page "Sandbox" edit \
+  --arg "Edited from mwcli ~~~~" \
+  --kw summary="mwcli test edit" \
+  --kw bot=false
+```
+
+### File upload
+
+Local file upload:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  --username "Admin" --password "secret" \
+  site upload \
+  --kw file="/tmp/example.png" \
+  --kw filename="Example.png" \
+  --kw description="Uploaded by mwcli"
+```
+
+Upload from URL:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  --username "Admin" --password "secret" \
+  site upload \
+  --kw url="https://example.com/example.png" \
+  --kw filename="ExampleFromURL.png"
+```
+
+### Semantic MediaWiki ask API
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site ask --arg '[[Category:Item]]|?Has author|?Has status' --max-items 20
+```
+
+With an explicit title context:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site ask --arg '[[Category:Item]]|?Has author' --kw title="Main Page" --max-items 20
+```
+
+Fetch all SMW properties for a page (`smwbrowse`):
+
+```bash
+python -m mwcli --indent 2 --host host.docker.internal --scheme http --path /w/ \
+  site raw_api --arg smwbrowse --arg GET --kw browse=subject \
+  --kw params='"{\"subject\":\"Main Page\",\"ns\":0}"'
+```
+
+Note: `smwbrowse` expects `params` as a JSON string, so pass a JSON object wrapped as a quoted string (double-encoded).
+
+### Arbitrary API calls
+
+Use `get` / `post` / `api` / `raw_api` directly.
+
+Get siteinfo:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site get --arg query --kw meta=siteinfo --kw siprop='general|namespaces'
+```
+
+Generic `api` call with GET method:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site api --arg query --arg GET --kw prop=info --kw titles="Main Page"
+```
+
+Raw API (no extra wrapper logic):
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site raw_api --arg query --arg GET --kw list=search --kw srsearch=space
+```
+
+Parse wikitext/HTML directly as Markdown:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site parse --kw text=$'== Header ==\n\nBody' --markdown
+```
+
+`--markdown` currently applies to:
+
+- `page text`
+- `site parse`
+
+Implementation uses `html2text`: https://pypi.org/project/html2text/
+
+### Page and image list iterators
+
+Recent changes:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  site recentchanges --kw prop='title|timestamp|user|comment' --max-items 5
+```
+
+Image usage:
+
+```bash
+python -m mwcli --host host.docker.internal --scheme http --path /w/ \
+  image "Example.png" imageusage --max-items 10
+```
+
+## Env vars
+
+You can use env vars instead of flags:
+
+- `MWCLI_HOST`
+- `MWCLI_PATH` (default `/w/`)
+- `MWCLI_EXT` (default `.php`)
+- `MWCLI_SCHEME` (default `https`)
+- `MWCLI_USERNAME`
+- `MWCLI_PASSWORD`
+- `MWCLI_USER_AGENT`
+
+Then run shorter commands, for example:
+
+```bash
+export MWCLI_HOST=host.docker.internal
+export MWCLI_SCHEME=http
+export MWCLI_PATH=/w/
+python -m mwcli site search --arg "space" --kw what=text --max-items 5
+```

mwclient_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mwclient-cli/__init__.py,sha256=ijQ-WRX2098384M1mIsFFZuAQsN2yd9cdMSlUPs-_ss,69
+mwclient-cli/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+mwclient-cli/cli.py,sha256=nfpGfZhhrt6K9-BuQ-rPX51HmW5KBlQFQMhaZKyqzFE,12458
+mwclient_cli-0.1.0.dist-info/METADATA,sha256=ShUr_rt3zc64UN7G_JmoX0oD27NoZYWfhyL5Tm0b-2w,6959
+mwclient_cli-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mwclient_cli-0.1.0.dist-info/entry_points.txt,sha256=kwASmUbnKbzvecArk8v0BWnoQQHQBnEvxV7cc0OnONI,48
+mwclient_cli-0.1.0.dist-info/RECORD,,

mwclient_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mwclient_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mwcli = mwclient-cli.cli:main