wiktionary-api 0.1.0__py3-none-any.whl

wikt/__init__.py

@@ -0,0 +1,11 @@
+"""Python client for the Wikimedia Wiktionary REST API."""
+
+from .client import Wiktionary
+from .util import pdf_from_bytes
+
+__all__ = [
+    "Wiktionary",
+    "pdf_from_bytes",
+]
+
+__version__ = "0.1.0"

wikt/client.py

@@ -0,0 +1,754 @@
+"""Python Wiktionary API.
+
+Synchronous client for the English Wiktionary Wikimedia REST API
+(``rest_v1``) plus Commons Core helpers for downloading media bytes.
+
+OpenAPI spec: https://en.wiktionary.org/api/rest_v1/?spec
+Interactive docs: https://en.wiktionary.org/api/rest_v1/#/
+"""
+
+# pylint: disable=too-many-lines,too-many-public-methods,too-many-arguments,too-many-positional-arguments
+from __future__ import annotations
+
+from pathlib import Path
+from pprint import pprint
+
+import requests
+
+from . import util
+
+_DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
+)
+
+_MATH_TYPES = frozenset({"tex", "inline-tex", "chem"})
+_MATH_RENDER_FORMATS = frozenset({"svg", "mml", "png"})
+
+
+def _pdf_url(base: str, title: str, pdf_format: str | None, pdf_type: str | None) -> str:
+    """Build ``/page/pdf/{title}/{format}/{type}`` with validated options."""
+    if pdf_format is None:
+        format_ = "a4"
+    elif pdf_format in ["a4", "letter", "legal"]:
+        format_ = pdf_format
+    else:
+        raise ValueError("Invalid format. Valid formats are 'a4', 'letter', 'legal'.")
+
+    if pdf_type is None:
+        type_ = "desktop"
+    elif pdf_type in ["desktop", "mobile"]:
+        type_ = pdf_type
+    else:
+        raise ValueError("Invalid type. Valid types are 'desktop', 'mobile'.")
+
+    return f"{base}/page/pdf/{title}/{format_}/{type_}"
+
+
+def _parse_media_types_filter(media_types_filter: str | list[str] | None) -> list[str] | None:
+    """Normalize and validate a media-type filter (``image``/``audio``/``video``)."""
+    if not media_types_filter:
+        return None
+
+    if isinstance(media_types_filter, str):
+        valid_media_types = [media_types_filter.lower()]
+    else:
+        valid_media_types = [media_type.lower() for media_type in media_types_filter]
+
+    for media_type in valid_media_types:
+        if media_type not in ["image", "audio", "video"]:
+            raise ValueError(
+                f"Invalid media type '{media_type}'. Valid media types are "
+                "'image', 'audio', 'video'."
+            )
+
+    return valid_media_types
+
+
+def _media_titles_to_fetch(media_file_list: list, valid_media_types: list[str] | None) -> list[str]:
+    """Return media titles from a media-list payload, optionally filtered by type."""
+    titles = []
+    for item in media_file_list:
+        if valid_media_types and str(item["type"]).lower() not in valid_media_types:
+            continue
+        titles.append(item["title"])
+    return titles
+
+
+def _optional_params(**kwargs) -> dict:
+    """Drop ``None`` values so optional query params are omitted."""
+    return {key: value for key, value in kwargs.items() if value is not None}
+
+
+def _page_resource_url(base: str, resource: str, title: str, revision: int | None = None) -> str:
+    """Build ``/page/{resource}/{title}[/revision]``."""
+    if revision is not None:
+        return f"{base}/page/{resource}/{title}/{revision}"
+    return f"{base}/page/{resource}/{title}"
+
+
+def _transform_url(
+    base: str, source: str, target: str, title: str | None = None, revision: int | None = None
+) -> str:
+    """Build ``/transform/{source}/to/{target}[/title[/revision]]``."""
+    path = f"/transform/{source}/to/{target}"
+    if title is not None:
+        path += f"/{title}"
+        if revision is not None:
+            path += f"/{revision}"
+    return f"{base}{path}"
+
+
+def _request_headers(
+    accept_language: str | None = None, if_match: str | None = None, output_mode: str | None = None
+) -> dict:
+    """Build optional request headers used by several REST routes."""
+    headers = {}
+    if accept_language is not None:
+        headers["Accept-Language"] = accept_language
+    if if_match is not None:
+        headers["If-Match"] = if_match
+    if output_mode is not None:
+        headers["output-mode"] = output_mode
+    return headers
+
+
+def _transform_form(
+    wikitext: str | None = None,
+    html: str | None = None,
+    body_only: bool | None = None,
+    stash: bool | None = None,
+) -> dict:
+    """Build multipart/form fields for transform endpoints."""
+    data = {}
+    if wikitext is not None:
+        data["wikitext"] = wikitext
+    if html is not None:
+        data["html"] = html
+    if body_only is not None:
+        data["body_only"] = body_only
+    if stash is not None:
+        data["stash"] = stash
+    return data
+
+
+class Wiktionary:
+    """
+    Synchronous Python wrapper for the Wiktionary REST API.
+
+    Covers every path in the live OpenAPI spec at
+    ``https://en.wiktionary.org/api/rest_v1/?spec``, plus PDF rendering
+    (available on the service but omitted from the published spec) and
+    Commons Core helpers for downloading media bytes.
+
+    Wikimedia requires a descriptive User-Agent with your application name
+    and a contact email or URL.
+    """
+
+    def __init__(self, app_name: str, contact_info: str, timeout: int = 30):
+        self.base = "https://en.wiktionary.org/api/rest_v1"
+        self.media_base = "https://api.wikimedia.org/core/v1/commons"
+        self.app_name = app_name
+        self.contact_info = contact_info
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"User-Agent": _DEFAULT_USER_AGENT})
+        self.set_user_agent(self.app_name, self.contact_info)
+
+    def set_user_agent(self, app_name: str, contact_info: str) -> None:
+        """
+        Set the User-Agent header (required by Wikimedia API policy).
+
+        Parameters:
+            app_name: Application name.
+            contact_info: Email address or contact URL.
+        """
+        self.session.headers.update({"User-Agent": f"{app_name} ({contact_info})"})
+
+    # ------------------------------------------------------------------
+    # Page content
+    # ------------------------------------------------------------------
+
+    def page(self) -> list:
+        """
+        List page-related API entry points.
+
+        Endpoint: ``GET /page/``
+        Stability: Stable
+        """
+        response = self.session.get(f"{self.base}/page/", timeout=self.timeout)
+        return response.json()["items"]
+
+    def get_definition(self, term: str, redirect: bool | None = None) -> list:
+        """
+        Get term definitions extracted from Wiktionary content.
+
+        Parameters:
+            term: Term to define.
+            redirect: If ``False``, redirect pages return HTTP 200 instead of 302.
+
+        Endpoint: ``GET /page/definition/{term}``
+        Stability: Stable
+        """
+        url = f"{self.base}/page/definition/{term}"
+        response = self.session.get(
+            url,
+            params=_optional_params(redirect=redirect),
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def get_revision(self, title: str, revision: int | None = None) -> dict:
+        """
+        Fetch revision metadata for a title.
+
+        Parameters:
+            title: Page title (underscores; percent-encode if needed).
+            revision: Optional specific revision ID. Latest if omitted.
+
+        Endpoint: ``GET /page/title/{title}/{revision}``
+        Stability: Stable
+        """
+        if revision is not None:
+            url = f"{self.base}/page/title/{title}/{revision}"
+        else:
+            url = f"{self.base}/page/title/{title}"
+
+        items = self.session.get(url, timeout=self.timeout).json()["items"]
+        if items:
+            return items[0]
+        return {}
+
+    def get_html(
+        self,
+        title: str,
+        revision: int | None = None,
+        redirect: bool | None = None,
+        stash: bool | None = None,
+        accept_language: str | None = None,
+    ) -> str:
+        """
+        Get HTML for a title (optionally a specific revision).
+
+        Endpoint: ``GET /page/html/{title}/{revision}``
+        Stability: Stable
+        """
+        url = _page_resource_url(self.base, "html", title, revision)
+        headers = _request_headers(accept_language=accept_language)
+        response = self.session.get(
+            url,
+            params=_optional_params(redirect=redirect, stash=stash),
+            headers=headers or None,
+            timeout=self.timeout,
+        )
+        return response.text
+
+    def get_lint(self, title: str, revision: int | None = None) -> dict | list:
+        """
+        Get linter errors for a page.
+
+        Endpoint: ``GET /page/lint/{title}/{revision}``
+        Stability: Stable
+        """
+        url = _page_resource_url(self.base, "lint", title, revision)
+        return self.session.get(url, timeout=self.timeout).json()
+
+    def get_mobile_html(
+        self, title: str, revision: int | None = None, redirect: bool | None = None
+    ) -> str:
+        """
+        Get page HTML optimized for mobile consumption.
+
+        Endpoint: ``GET /page/mobile-html/{title}/{revision}``
+        Stability: Stable
+        """
+        url = _page_resource_url(self.base, "mobile-html", title, revision)
+        response = self.session.get(
+            url,
+            params=_optional_params(redirect=redirect),
+            timeout=self.timeout,
+        )
+        return response.text
+
+    def get_mobile_html_offline_resources(self, title: str, revision: int | None = None) -> dict:
+        """
+        Get styles and scripts for offline mobile-html pages.
+
+        Endpoint: ``GET /page/mobile-html-offline-resources/{title}/{revision}``
+        Stability: Stable
+        """
+        url = _page_resource_url(self.base, "mobile-html-offline-resources", title, revision)
+        return self.session.get(url, timeout=self.timeout).json()
+
+    def get_media_file_list(self, title: str, revision: int | None = None) -> list:
+        """
+        List media items used on a wiki page (images, audio, video).
+
+        Endpoint: ``GET /page/media-list/{title}/{revision}``
+        Stability: Unstable
+        """
+        url = _page_resource_url(self.base, "media-list", title, revision)
+        return self.session.get(url, timeout=self.timeout).json()["items"]
+
+    def get_pdf(
+        self, title: str, pdf_format: str | None = None, pdf_type: str | None = None
+    ) -> bytes:
+        """
+        Render a page as PDF bytes.
+
+        Parameters:
+            title: Page title.
+            pdf_format: ``a4`` (default), ``letter``, or ``legal``.
+            pdf_type: ``desktop`` (default) or ``mobile``.
+
+        Endpoint: ``GET /page/pdf/{title}/{format}/{type}``
+        Stability: Experimental (available on the service; not in OpenAPI ``?spec``)
+        """
+        url = _pdf_url(self.base, title, pdf_format, pdf_type)
+        return self.session.get(url, timeout=self.timeout).content
+
+    def download_pdf(
+        self,
+        title: str,
+        pdf_format: str | None = None,
+        pdf_type: str | None = None,
+        output_name: str | None = None,
+    ) -> bool:
+        """
+        Download a PDF for ``title`` and save it to disk.
+
+        Returns:
+            ``True`` on success, ``False`` if the download or save fails.
+        """
+        output_name_ = output_name if output_name else f"{title}.pdf"
+        try:
+            pdf_bytes = self.get_pdf(title, pdf_format=pdf_format, pdf_type=pdf_type)
+            util.pdf_from_bytes(pdf_bytes, True, output_name_)
+            return True
+        except Exception as exc:  # pylint: disable=broad-except
+            print(exc)
+            return False
+
+    def get_media_files(
+        self,
+        title: str,
+        revision: int | None = None,
+        media_types_filter: str | list[str] | None = None,
+    ) -> dict[str, bytes]:
+        """
+        Download media file bytes used on a page via the Commons Core API.
+
+        Parameters:
+            title: Page title.
+            revision: Optional page revision.
+            media_types_filter: ``image``, ``audio``, ``video``, or a list of those.
+
+        Returns:
+            Mapping of media file title → file bytes.
+        """
+        media_file_list = self.get_media_file_list(title, revision)
+        valid_media_types = _parse_media_types_filter(media_types_filter)
+        titles = _media_titles_to_fetch(media_file_list, valid_media_types)
+
+        media_files: dict[str, bytes] = {}
+        for file_name in titles:
+            file_site = f"{self.media_base}/file/{file_name}"
+            file_url = self.session.get(file_site, timeout=self.timeout).json()["original"]["url"]
+            media_files[file_name] = self.session.get(file_url, timeout=self.timeout).content
+        return media_files
+
+    def download_media_files(
+        self,
+        title: str,
+        revision: int | None = None,
+        media_types_filter: str | list[str] | None = None,
+        download_path: str | Path | None = None,
+    ) -> bool:
+        """
+        Download media files for a page and write them to ``download_path``.
+
+        Returns:
+            ``True`` on success, ``False`` on filesystem errors.
+        """
+        media_files = self.get_media_files(title, revision, media_types_filter)
+        dest_dir = Path(download_path) if download_path is not None else Path()
+        try:
+            for file_name, file_content in media_files.items():
+                output_path = dest_dir / file_name.removeprefix("File:")
+                with open(output_path, "wb") as handle:
+                    handle.write(file_content)
+            return True
+        except Exception as exc:  # pylint: disable=broad-except
+            print(exc)
+            return False
+
+    # ------------------------------------------------------------------
+    # Data / citation / mobile assets / reading lists
+    # ------------------------------------------------------------------
+
+    def get_citation(self, format_: str, query: str, accept_language: str | None = None) -> dict:
+        """
+        Get citation data for an article identifier.
+
+        Endpoint: ``GET /data/citation/{format}/{query}``
+        Stability: Stable
+        """
+        url = f"{self.base}/data/citation/{format_}/{query}"
+        headers = _request_headers(accept_language=accept_language)
+        response = self.session.get(url, headers=headers or None, timeout=self.timeout)
+        return response.json()
+
+    def get_mobile_css(self, type_: str) -> str:
+        """
+        Get CSS for mobile apps.
+
+        Endpoint: ``GET /data/css/mobile/{type}``
+        """
+        response = self.session.get(f"{self.base}/data/css/mobile/{type_}", timeout=self.timeout)
+        return response.text
+
+    def get_mobile_javascript(self, type_: str) -> str:
+        """
+        Get JavaScript for mobile apps.
+
+        Endpoint: ``GET /data/javascript/mobile/{type}``
+        """
+        response = self.session.get(
+            f"{self.base}/data/javascript/mobile/{type_}", timeout=self.timeout
+        )
+        return response.text
+
+    def get_i18n(self, type_: str) -> dict:
+        """
+        Get internationalization info.
+
+        Endpoint: ``GET /data/i18n/{type}``
+        """
+        response = self.session.get(f"{self.base}/data/i18n/{type_}", timeout=self.timeout)
+        return response.json()
+
+    def get_lists(self, next_: str | None = None, sort: str | None = None) -> dict:
+        """
+        Get all reading lists for the authenticated user.
+
+        Endpoint: ``GET /data/lists/``
+        """
+        response = self.session.get(
+            f"{self.base}/data/lists/",
+            params=_optional_params(next=next_, sort=sort),
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def create_list(self, data: dict, csrf_token: str) -> dict:
+        """
+        Create a reading list.
+
+        Endpoint: ``POST /data/lists/``
+        """
+        response = self.session.post(
+            f"{self.base}/data/lists/",
+            params={"csrf_token": csrf_token},
+            json=data,
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def create_lists_batch(self, batch: list, csrf_token: str) -> dict:
+        """
+        Create multiple reading lists.
+
+        Endpoint: ``POST /data/lists/batch``
+        """
+        response = self.session.post(
+            f"{self.base}/data/lists/batch",
+            params={"csrf_token": csrf_token},
+            json={"batch": batch},
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def get_list_changes_since(self, date: str, next_: str | None = None) -> dict:
+        """
+        Get recent changes to reading lists since ``date``.
+
+        Endpoint: ``GET /data/lists/changes/since/{date}``
+        """
+        response = self.session.get(
+            f"{self.base}/data/lists/changes/since/{date}",
+            params=_optional_params(next=next_),
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def get_lists_for_page(self, project: str, title: str, next_: str | None = None) -> dict:
+        """
+        Get lists that contain a given page.
+
+        Endpoint: ``GET /data/lists/pages/{project}/{title}``
+        """
+        response = self.session.get(
+            f"{self.base}/data/lists/pages/{project}/{title}",
+            params=_optional_params(next=next_),
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def setup_lists(self, csrf_token: str) -> dict:
+        """
+        Opt in to reading lists.
+
+        Endpoint: ``POST /data/lists/setup``
+        """
+        response = self.session.post(
+            f"{self.base}/data/lists/setup",
+            params={"csrf_token": csrf_token},
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def teardown_lists(self, csrf_token: str) -> dict:
+        """
+        Opt out of reading lists.
+
+        Endpoint: ``POST /data/lists/teardown``
+        """
+        response = self.session.post(
+            f"{self.base}/data/lists/teardown",
+            params={"csrf_token": csrf_token},
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def update_list(self, list_id: int, data: dict, csrf_token: str) -> dict:
+        """
+        Update a reading list.
+
+        Endpoint: ``PUT /data/lists/{id}``
+        """
+        response = self.session.put(
+            f"{self.base}/data/lists/{list_id}",
+            params={"csrf_token": csrf_token},
+            json=data,
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def delete_list(self, list_id: int) -> dict:
+        """
+        Delete a reading list.
+
+        Endpoint: ``DELETE /data/lists/{id}``
+        """
+        response = self.session.delete(f"{self.base}/data/lists/{list_id}", timeout=self.timeout)
+        return response.json()
+
+    def get_list_entries(
+        self, list_id: int, next_: str | None = None, sort: str | None = None
+    ) -> dict:
+        """
+        Get all entries of a reading list.
+
+        Endpoint: ``GET /data/lists/{id}/entries/``
+        """
+        response = self.session.get(
+            f"{self.base}/data/lists/{list_id}/entries/",
+            params=_optional_params(next=next_, sort=sort),
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def create_list_entry(self, list_id: int, data: dict, csrf_token: str) -> dict:
+        """
+        Create a list entry.
+
+        Endpoint: ``POST /data/lists/{id}/entries/``
+        """
+        response = self.session.post(
+            f"{self.base}/data/lists/{list_id}/entries/",
+            params={"csrf_token": csrf_token},
+            json=data,
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def create_list_entries_batch(self, list_id: int, batch: list, csrf_token: str) -> dict:
+        """
+        Create multiple list entries.
+
+        Endpoint: ``POST /data/lists/{id}/entries/batch``
+        """
+        response = self.session.post(
+            f"{self.base}/data/lists/{list_id}/entries/batch",
+            params={"csrf_token": csrf_token},
+            json={"batch": batch},
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def delete_list_entry(self, list_id: int, entry_id: int) -> dict:
+        """
+        Delete a list entry.
+
+        Endpoint: ``DELETE /data/lists/{id}/entries/{entry_id}``
+        """
+        response = self.session.delete(
+            f"{self.base}/data/lists/{list_id}/entries/{entry_id}",
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    # ------------------------------------------------------------------
+    # Transforms
+    # ------------------------------------------------------------------
+
+    def transform_wikitext_to_html(
+        self,
+        wikitext: str,
+        title: str | None = None,
+        revision: int | None = None,
+        body_only: bool | None = None,
+        stash: bool | None = None,
+    ) -> str:
+        """
+        Transform Wikitext to HTML.
+
+        Endpoint: ``POST /transform/wikitext/to/html[/{title}[/{revision}]]``
+        Stability: Stable
+        """
+        url = _transform_url(self.base, "wikitext", "html", title, revision)
+        response = self.session.post(
+            url,
+            data=_transform_form(wikitext=wikitext, body_only=body_only, stash=stash),
+            timeout=self.timeout,
+        )
+        return response.text
+
+    def transform_html_to_wikitext(
+        self,
+        html: str,
+        title: str | None = None,
+        revision: int | None = None,
+        if_match: str | None = None,
+    ) -> str:
+        """
+        Transform HTML to Wikitext.
+
+        Endpoint: ``POST /transform/html/to/wikitext[/{title}[/{revision}]]``
+        Stability: Stable
+        """
+        url = _transform_url(self.base, "html", "wikitext", title, revision)
+        headers = _request_headers(if_match=if_match)
+        response = self.session.post(
+            url,
+            data=_transform_form(html=html),
+            headers=headers or None,
+            timeout=self.timeout,
+        )
+        return response.text
+
+    def transform_wikitext_to_lint(
+        self, wikitext: str, title: str | None = None, revision: int | None = None
+    ) -> dict | list:
+        """
+        Check Wikitext for lint errors.
+
+        Endpoint: ``POST /transform/wikitext/to/lint[/{title}[/{revision}]]``
+        Stability: Stable
+        """
+        url = _transform_url(self.base, "wikitext", "lint", title, revision)
+        response = self.session.post(
+            url,
+            data=_transform_form(wikitext=wikitext),
+            timeout=self.timeout,
+        )
+        return response.json()
+
+    def transform_wikitext_to_mobile_html(
+        self,
+        wikitext: str,
+        title: str,
+        accept_language: str | None = None,
+        output_mode: str | None = None,
+    ) -> str:
+        """
+        Transform Wikitext to mobile HTML.
+
+        Endpoint: ``POST /transform/wikitext/to/mobile-html/{title}``
+        Stability: Stable
+        """
+        url = _transform_url(self.base, "wikitext", "mobile-html", title)
+        headers = _request_headers(accept_language=accept_language, output_mode=output_mode)
+        response = self.session.post(
+            url,
+            data=_transform_form(wikitext=wikitext),
+            headers=headers or None,
+            timeout=self.timeout,
+        )
+        return response.text
+
+    # ------------------------------------------------------------------
+    # Math
+    # ------------------------------------------------------------------
+
+    def check_math(self, type_: str, formula: str) -> dict:
+        """
+        Check and normalize a TeX (or chem) formula.
+
+        The returned dict includes ``resource_location`` from the
+        ``x-resource-location`` response header (hash for render/formula).
+
+        Endpoint: ``POST /media/math/check/{type}``
+        Stability: Deprecated on this host (prefer Math API on wikimedia.org)
+        """
+        if type_ not in _MATH_TYPES:
+            raise ValueError(f"Invalid math type '{type_}'. Valid types are {sorted(_MATH_TYPES)}.")
+
+        response = self.session.post(
+            f"{self.base}/media/math/check/{type_}",
+            data={"q": formula},
+            timeout=self.timeout,
+        )
+        result = response.json()
+        result["resource_location"] = response.headers.get("x-resource-location")
+        return result
+
+    def get_math_formula(self, hash_: str) -> dict:
+        """
+        Get a previously stored formula by hash.
+
+        Endpoint: ``GET /media/math/formula/{hash}``
+        Stability: Deprecated on this host
+        """
+        response = self.session.get(f"{self.base}/media/math/formula/{hash_}", timeout=self.timeout)
+        return response.json()
+
+    def render_math(self, format_: str, hash_: str) -> bytes:
+        """
+        Render a previously checked formula (``svg``, ``mml``, or ``png``).
+
+        Endpoint: ``GET /media/math/render/{format}/{hash}``
+        Stability: Deprecated on this host
+        """
+        if format_ not in _MATH_RENDER_FORMATS:
+            raise ValueError(
+                f"Invalid render format '{format_}'. Valid formats are "
+                f"{sorted(_MATH_RENDER_FORMATS)}."
+            )
+
+        response = self.session.get(
+            f"{self.base}/media/math/render/{format_}/{hash_}",
+            timeout=self.timeout,
+        )
+        return response.content
+
+
+def main() -> None:
+    """Demo entry point."""
+    wiki = Wiktionary("WiktionaryPy", "example@example.com")
+    pprint(wiki.get_definition("hello"))
+    pprint(dict(wiki.session.headers))
+
+
+if __name__ == "__main__":
+    main()

wikt/util.py

@@ -0,0 +1,52 @@
+"""Util functions for the Wiktionary API"""
+
+from io import BytesIO
+
+from PyPDF2 import PdfReader, PdfWriter
+
+
+def pdf_from_bytes(pdf_bytes: bytes, save: bool = False, output_file_path: str | None = None):
+    """
+    Parse PDF bytes into a ``PdfWriter``, optionally saving to disk.
+
+    Args:
+        pdf_bytes: Raw PDF payload (e.g. from ``Wiktionary.get_pdf``).
+        save: When ``True``, write the PDF to ``output_file_path``.
+        output_file_path: Destination path ending in ``.pdf`` (required if ``save``).
+
+    Returns:
+        A ``PdfWriter`` with the copied pages, or ``None`` if parsing fails.
+
+    Raises:
+        ValueError: If ``save`` is set without a valid ``.pdf`` output path.
+    """
+
+    if save and not output_file_path:
+        raise ValueError("save is true but output_file_path is not provided/empty")
+
+    if save and not output_file_path.endswith(".pdf"):
+        raise ValueError("output_file does not end with '.pdf'")
+
+    try:
+        # Create an in-memory stream from the bytes
+        bytes_stream = BytesIO(pdf_bytes)
+
+        # Read the PDF from the stream
+        pdf_reader = PdfReader(bytes_stream)
+
+        # Create a new PDF writer
+        pdf_writer = PdfWriter()
+
+        # Add all pages from the reader to the writer
+        for page in pdf_reader.pages:
+            pdf_writer.add_page(page)
+
+        if save:
+            with open(output_file_path, "wb") as output_file:
+                pdf_writer.write(output_file)
+
+        return pdf_writer
+
+    except Exception as e:  # pylint: disable=broad-except
+        print(f"Error creating PDF from bytes: {e}")
+    return None

wiktionary_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: wiktionary-api
+Version: 0.1.0
+Summary: Synchronous Python client for the Wikimedia Wiktionary REST API
+Project-URL: Homepage, https://github.com/NebilI/WiktionaryPythonAPI
+Project-URL: Repository, https://github.com/NebilI/WiktionaryPythonAPI
+Project-URL: Issues, https://github.com/NebilI/WiktionaryPythonAPI/issues
+Project-URL: Documentation, https://github.com/NebilI/WiktionaryPythonAPI#readme
+Author: Nebil Ibrahim
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dictionary,requests,rest-api,wikimedia,wiktionary
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pypdf2<4,>=3.0.1
+Requires-Dist: requests<3,>=2.32
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# WiktionaryPythonAPI
+
+Synchronous Python client for the [Wiktionary REST API](https://en.wiktionary.org/api/rest_v1/#/) and related [Commons Core](https://api.wikimedia.org/wiki/Core_REST_API) media downloads.
+
+**PyPI:** `wiktionary-api` · **Import:** `wikt`
+
+Covers **all 41** path patterns in the live OpenAPI spec (`?spec`), plus PDF rendering and Commons helpers. See [docs/ENDPOINTS.md](docs/ENDPOINTS.md) for the full path → method map.
+
+## Install
+
+Works with any PEP 517 installer:
+
+```bash
+pip install wiktionary-api
+```
+
+```bash
+uv add wiktionary-api
+```
+
+```bash
+poetry add wiktionary-api
+```
+
+Requires **Python 3.10+**.
+
+## Quick start
+
+Wikimedia requires a descriptive [User-Agent](https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy) with your application name and a contact email or URL.
+
+```python
+from wikt import Wiktionary
+
+wiki = Wiktionary("MyApp", "you@example.com")
+
+# Definitions (Wiktionary-specific)
+print(wiki.get_definition("hello"))
+
+# HTML / revision metadata
+print(wiki.get_html("hello")[:200])
+print(wiki.get_revision("hello"))
+
+# Math (check → render)
+checked = wiki.check_math("tex", "E=mc^2")
+svg = wiki.render_math("svg", checked["resource_location"])
+```
+
+## API surface (summary)
+
+| Area | Examples |
+|------|----------|
+| Page content | `page`, `get_definition`, `get_html`, `get_lint`, `get_mobile_html`, `get_revision`, `get_media_file_list`, `get_pdf` |
+| Data / mobile | `get_citation`, `get_mobile_css`, `get_mobile_javascript`, `get_i18n` |
+| Reading lists | `get_lists`, `create_list`, `update_list`, `delete_list`, entry CRUD, setup/teardown |
+| Transforms | `transform_wikitext_to_html`, `transform_html_to_wikitext`, `transform_wikitext_to_lint`, `transform_wikitext_to_mobile_html` |
+| Math | `check_math`, `get_math_formula`, `render_math` |
+| Commons helpers | `get_media_files`, `download_media_files` |
+
+Method docstrings document parameters, return types, and REST paths. Official sandbox: https://en.wiktionary.org/api/rest_v1/#/
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+# or: uv sync --all-extras
+ruff check src tests
+ruff format src tests
+pytest tests/ -v
+```
+
+### Publishing
+
+Releases publish to PyPI on `v*` tags via trusted publishing. See [.github/PYPI_PUBLISHING.md](.github/PYPI_PUBLISHING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

wiktionary_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+wikt/__init__.py,sha256=J-_pjAD4mCWIAeIYc0yCNwREUyyjvPGPViQG1wg-V2g,202
+wikt/client.py,sha256=ItO1HA5GDzaKdHIorKeU-N5gHnExhmgUX_tPLRNbrsU,25509
+wikt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wikt/util.py,sha256=s9Id49WZb7-PhdjnkbIB6e-vguQAPVTn50opUJtbesc,1622
+wiktionary_api-0.1.0.dist-info/METADATA,sha256=xxEad86OFwhTApEipjy0NP5OA10SuTIjqYjkaQWBb-Q,3722
+wiktionary_api-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+wiktionary_api-0.1.0.dist-info/licenses/LICENSE,sha256=2ZUv95E4ju6IepiCtjKlOhODaXbdqgf-W30wkXh4FmE,1070
+wiktionary_api-0.1.0.dist-info/RECORD,,

wiktionary_api-0.1.0.dist-info/WHEEL

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

wiktionary_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nebil Ibrahim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.