Wikipedia-API 0.13.0__tar.gz → 0.14.0__tar.gz

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/API.rst

@@ -7,7 +7,9 @@ Wikipedia
 * ``page(title, ns=Namespace.MAIN)``
 * ``pages(titles)`` — create a ``PagesDict`` of lazy pages (no network call)
 * ``coordinates(page, *, limit=10, primary='primary', prop=('globe',), distance_from_point=None (GeoPoint), distance_from_page=None)`` → ``list[Coordinate]``
-* ``images(page, *, limit=10, images=None, direction=Direction.ASCENDING)`` → ``PagesDict``
+* ``images(page, *, limit=10, images=None, direction=Direction.ASCENDING)`` → ``ImagesDict``
+* ``imageinfo(image, *, prop=('url', 'width', 'height', ...), limit=1)`` → ``list[ImageInfo]``
+* ``batch_imageinfo(images, *, prop=('url', 'width', 'height', ...), limit=1)`` → ``dict[str, list[ImageInfo]]``
 * ``geosearch(*, coord=None (GeoPoint), page=None, bbox=None (GeoBox), radius=500, max_dim=None, sort='distance', limit=10, ns=Namespace.MAIN, prop=None)`` → ``PagesDict``
 * ``random(*, limit=1, ns=Namespace.MAIN, filter_redir='nonredirects')`` → ``PagesDict``
 * ``search(query, *, ns=Namespace.MAIN, limit=10, prop=None, info=None, sort='relevance')`` → ``SearchResults``
@@ -22,7 +24,9 @@ Same constructor parameters as ``Wikipedia``.  All methods are coroutines
 * ``page(title, ns=Namespace.MAIN)`` — returns an ``AsyncWikipediaPage`` (no network call)
 * ``pages(titles)`` — create an ``AsyncPagesDict`` of lazy pages (no network call)
 * ``await coordinates(page, ...)`` → ``list[Coordinate]``
-* ``await images(page, ...)`` → ``PagesDict``
+* ``await images(page, ...)`` → ``ImagesDict``
+* ``await imageinfo(image, ...)`` → ``list[ImageInfo]``
+* ``await batch_imageinfo(images, ...)`` → ``dict[str, list[ImageInfo]]``
 * ``await geosearch(...)`` → ``PagesDict``
 * ``await random(...)`` → ``PagesDict``
 * ``await search(query, ...)`` → ``SearchResults``
@@ -46,7 +50,7 @@ WikipediaPage
 * ``categories`` - categories this page belongs to ({title: ``WikipediaPage``})
 * ``categorymembers`` - pages in this category, when ``ns=Namespace.CATEGORY`` ({title: ``WikipediaPage``})
 * ``coordinates`` - geographic coordinates (list of ``Coordinate``); triggers ``coordinates`` API call with default params
-* ``images`` - images/files on this page (``PagesDict``); triggers ``images`` API call with default params
+* ``images`` - images/files on this page (``ImagesDict``); triggers ``images`` API call with default params
 * ``geosearch_meta`` - ``GeoSearchMeta`` or ``None``; set when page came from ``geosearch()`` (plain property, no fetch)
 * ``search_meta`` - ``SearchMeta`` or ``None``; set when page came from ``search()`` (plain property, no fetch)
 * ``displaytitle``
@@ -87,7 +91,7 @@ return coroutines (awaitable with ``await``).
 * ``await page.categories`` — awaitable property; ``{title: AsyncWikipediaPage}`` dict
 * ``await page.categorymembers`` — awaitable property; ``{title: AsyncWikipediaPage}`` dict
 * ``await page.coordinates`` — awaitable property; ``list[Coordinate]``
-* ``await page.images`` — awaitable property; ``PagesDict``
+* ``await page.images`` — awaitable property; ``ImagesDict``
 * ``page.geosearch_meta`` — plain property; ``GeoSearchMeta | None`` (no await)
 * ``page.search_meta`` — plain property; ``SearchMeta | None`` (no await)
 * ``await page.exists()`` — coroutine method; lazily fetches ``pageid`` via ``info`` if not yet cached
@@ -103,6 +107,60 @@ WikipediaPageSection
 * ``section_by_title(title)``
 * ``full_text(level=1)`` - rendered text of this section and all descendants
 
+WikipediaImage
+---------------
+Lazy representation of a Wikipedia/Commons file page.  No network call is
+made at construction time; accessing ``imageinfo`` (or any convenience
+property derived from it) triggers the minimum API call needed.
+
+* ``title`` — file title including the ``File:`` prefix
+* ``language`` — two-letter language code
+* ``namespace`` — integer namespace number (6 for files)
+* ``pageid`` — MediaWiki page ID
+* ``imageinfo`` — list of ``ImageInfo`` objects (lazy-fetched; triggers API call)
+* ``url`` — full URL of the file (from first ``ImageInfo``)
+* ``width`` — image width in pixels (from first ``ImageInfo``)
+* ``height`` — image height in pixels (from first ``ImageInfo``)
+* ``size`` — file size in bytes (from first ``ImageInfo``)
+* ``mime`` — MIME type (from first ``ImageInfo``)
+* ``mediatype`` — MediaWiki media type (from first ``ImageInfo``)
+* ``sha1`` — SHA-1 hash of the file (from first ``ImageInfo``)
+* ``timestamp`` — ISO 8601 timestamp of this revision (from first ``ImageInfo``)
+* ``user`` — username of the uploader (from first ``ImageInfo``)
+* ``descriptionurl`` — URL of the file description page (from first ``ImageInfo``)
+* ``descriptionshorturl`` — short URL of the description page (from first ``ImageInfo``)
+
+AsyncWikipediaImage
+--------------------
+Async mirror of ``WikipediaImage``.  All properties that trigger network calls
+are awaitable (use ``await``).
+
+* ``title``, ``language``, ``namespace``, ``pageid`` — plain properties (no await)
+* ``await imageinfo`` — awaitable property; list of ``ImageInfo`` objects
+* ``await url`` — awaitable property; full URL of the file
+* ``await width`` — awaitable property; image width in pixels
+* ``await height`` — awaitable property; image height in pixels
+* ``await size`` — awaitable property; file size in bytes
+* ``await mime`` — awaitable property; MIME type
+* ``await mediatype`` — awaitable property; MediaWiki media type
+* ``await sha1`` — awaitable property; SHA-1 hash of the file
+* ``await timestamp`` — awaitable property; ISO 8601 timestamp
+* ``await user`` — awaitable property; username of uploader
+* ``await descriptionurl`` — awaitable property; description page URL
+* ``await descriptionshorturl`` — awaitable property; short description page URL
+
+ImagesDict
+----------
+A ``dict[str, WikipediaImage]`` subclass with batch convenience methods.
+
+* ``imageinfo(*, prop=_DEFAULT_PROP, limit=1)`` → ``dict[str, list[ImageInfo]]`` — batch-fetch ``imageinfo`` for all images via ``batch_imageinfo()``
+
+AsyncImagesDict
+---------------
+Async mirror of ``ImagesDict``.
+
+* ``await imageinfo(*, prop=_DEFAULT_PROP, limit=1)`` → ``dict[str, list[ImageInfo]]``
+
 ExtractFormat
 -------------
 * ``WIKI`` - plain-text wiki markup (``==Heading==``)
@@ -194,6 +252,24 @@ Frozen dataclass attached to pages returned by ``search()``.
 * ``wordcount: int`` — word count
 * ``timestamp: str`` — last edit timestamp (ISO 8601)
 
+``ImageInfo``
+~~~~~~~~~~~~~
+Frozen dataclass representing one file revision from ``prop=imageinfo``.
+All fields are optional and depend on the ``iiprop`` parameter and file
+availability.
+
+* ``url: str | None`` — full URL of the file
+* ``descriptionurl: str | None`` — URL of the file description page
+* ``descriptionshorturl: str | None`` — short URL of the description page
+* ``width: int | None`` — image width in pixels
+* ``height: int | None`` — image height in pixels
+* ``size: int | None`` — file size in bytes
+* ``mime: str | None`` — MIME type (e.g. ``"image/jpeg"``)
+* ``mediatype: str | None`` — MediaWiki media type (e.g. ``"BITMAP"``)
+* ``sha1: str | None`` — SHA-1 hash of the file content
+* ``timestamp: str | None`` — ISO 8601 timestamp of this revision
+* ``user: str | None`` — username of the uploader
+
 ``SearchResults``
 ~~~~~~~~~~~~~~~~~
 Wrapper returned by ``search()``.

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/CHANGES.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+0.14.0
+------
+
+* Add WikipediaImage, ImagesDict, and imageinfo API - `PR 525`_
+
+.. _PR 525: https://github.com/martin-majlis/Wikipedia-API/pull/525
+
 0.13.0
 ------
 

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/CLI.rst

@@ -15,12 +15,35 @@ Every command supports the following options:
 * ``-v, --variant`` — Language variant (e.g. ``zh-cn``, ``zh-tw``)
 * ``-f, --extract-format`` — Extraction format: ``wiki`` or ``html`` (default: ``wiki``)
 * ``-n, --namespace`` — Wikipedia namespace number (default: ``0`` = Main)
+* ``--max-retries`` — Maximum number of retry attempts for transient errors (HTTP 429, 5xx, timeouts, connection errors). Set to ``0`` to disable retries entirely (default: ``3``)
+* ``--retry-wait`` — Base wait time in seconds between retries; actual wait uses exponential backoff (``retry_wait * 2^attempt``). For HTTP 429 the ``Retry-After`` header value is used instead (default: ``1.0``)
 * ``-h, --help`` — Show help for any command
 
 Commands that return lists also support:
 
 * ``--json`` — Output results as JSON
 
+Retry Configuration
+-------------------
+
+Control retry behavior for network issues and rate limiting:
+
+Use custom retry settings::
+
+    wikipedia-api summary "Python (programming language)" --max-retries 5 --retry-wait 2.0
+
+Disable retries entirely (fail fast on first error)::
+
+    wikipedia-api search "Python" --max-retries 0
+
+Use aggressive retrying for unreliable connections::
+
+    wikipedia-api geosearch --coord "51.5074|-0.1278" --max-retries 10 --retry-wait 3.0
+
+Combine with other options::
+
+    wikipedia-api random --limit 5 --max-retries 1 --retry-wait 0.5 --language de
+
 Getting Help
 ------------
 
@@ -173,10 +196,23 @@ Output as JSON::
 
     wikipedia-api images "Python (programming language)" --json
 
+Fetch image metadata (URL, dimensions, MIME type, uploader, etc.) with
+the ``--imageinfo`` flag::
+
+    wikipedia-api images "Mount Everest" --imageinfo
+
+Display imageinfo metadata as JSON::
+
+    wikipedia-api images "Mount Everest" --imageinfo --json
+
 Limit the number of images::
 
     wikipedia-api images "Earth" --limit 50
 
+Combine options::
+
+    wikipedia-api images "Earth" --limit 20 --imageinfo --language de
+
 Geosearch
 ---------
 
@@ -227,8 +263,8 @@ Complete Workflow Example
 
 Fetch a page summary, then explore its sections and links::
 
-    # Get summary
-    wikipedia-api summary "Python (programming language)"
+    # Get summary with custom retry settings
+    wikipedia-api summary "Python (programming language)" --max-retries 5 --retry-wait 2.0
 
     # List sections
     wikipedia-api sections "Python (programming language)"
@@ -248,11 +284,11 @@ Fetch a page summary, then explore its sections and links::
     # Show coordinates for a geographic page
     wikipedia-api coordinates "Mount Everest"
 
-    # Search for pages near a location
-    wikipedia-api geosearch --coord "27.9881|86.9250"
+    # Search for pages near a location with aggressive retrying
+    wikipedia-api geosearch --coord "27.9881|86.9250" --max-retries 10 --retry-wait 3.0
 
-    # Search Wikipedia
-    wikipedia-api search "Mount Everest"
+    # Search Wikipedia with retries disabled
+    wikipedia-api search "Mount Everest" --max-retries 0
 
     # Get random pages
     wikipedia-api random --limit 3

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/DESIGN.rst

@@ -34,6 +34,16 @@ File Layout
 
     wikipediaapi/
     ├── __init__.py              # Public exports
+    ├── cli.py                   # Command line interface (main entry point)
+    ├── commands/                # CLI command modules
+    │   ├── __init__.py
+    │   ├── base.py              # Shared utilities and common options
+    │   ├── page_commands.py     # Page content commands
+    │   ├── link_commands.py     # Link-related commands
+    │   ├── category_commands.py # Category commands
+    │   ├── geo_commands.py      # Geographic commands
+    │   ├── image_commands.py    # Image file commands
+    │   └── search_commands.py    # Search and discovery commands
     ├── _http_client/            # Transport layer package
     │   ├── __init__.py
     │   ├── base_http_client.py  # Shared retry & config logic
@@ -52,6 +62,7 @@ File Layout
     │   ├── geo_point.py          # GeoPoint dataclass
     │   ├── geo_box.py            # GeoBox dataclass
     │   ├── geo_search_meta.py    # GeoSearchMeta dataclass
+    │   ├── image_info.py         # ImageInfo dataclass
     │   ├── search_meta.py        # SearchMeta dataclass
     │   └── search_results.py     # SearchResults dataclass
     ├── _params/                 # Query parameter dataclasses package
@@ -63,11 +74,13 @@ File Layout
     │   ├── random_params.py      # RandomParams
     │   ├── search_params.py      # SearchParams
     │   └── protocols.py          # Protocol constants
-    ├── _pages_dict/             # PagesDict package
+    ├── _pages_dict/             # PagesDict and ImagesDict package
     │   ├── __init__.py
     │   ├── base_pages_dict.py   # Base PagesDict functionality
     │   ├── pages_dict.py         # PagesDict (sync)
-    │   └── async_pages_dict.py   # AsyncPagesDict
+    │   ├── async_pages_dict.py   # AsyncPagesDict
+    │   ├── images_dict.py        # ImagesDict (sync)
+    │   └── async_images_dict.py  # AsyncImagesDict
     ├── _enums/                  # Enums package
     │   ├── __init__.py
     │   ├── coordinate_type.py    # CoordinateType enum
@@ -95,6 +108,8 @@ File Layout
     ├── _base_wikipedia_page.py  # BaseWikipediaPage (shared page state & methods)
     ├── wikipedia_page.py        # WikipediaPage (lazy sync page object)
     ├── async_wikipedia_page.py  # AsyncWikipediaPage (lazy async page object)
+    ├── wikipedia_image.py       # WikipediaImage (lazy sync file page object)
+    ├── async_wikipedia_image.py # AsyncWikipediaImage (lazy async file page object)
     ├── wikipedia_page_section.py  # WikipediaPageSection
     ├── extract_format.py        # ExtractFormat enum (WIKI / HTML)
     └── namespace.py             # Legacy namespace module (redirects to _enums.namespace)
@@ -115,7 +130,9 @@ The inheritance chains are::
 
     BaseWikipediaPage
     ├── WikipediaPage
-    └── AsyncWikipediaPage
+    ├── AsyncWikipediaPage
+    ├── WikipediaImage
+    └── AsyncWikipediaImage
 
 Concrete clients compose one transport and one API mixin::
 
@@ -823,3 +840,89 @@ Strongly-typed enums for API parameters:
 * ``geosearch_meta`` and ``search_meta`` are plain ``@property`` in both
   sync and async — they are set by ``geosearch()`` / ``search()`` on
   the wiki client and require no network call on the page itself.
+
+
+Command Line Interface
+---------------------
+
+The CLI provides a command-line tool for querying Wikipedia using Wikipedia-API.
+It is organized into a modular structure for better maintainability.
+
+**Architecture**
+
+The CLI is split into a main entry point and functional command modules::
+
+    wikipediaapi/
+    ├── cli.py                     # Main CLI entry point (54 lines)
+    └── commands/                  # CLI command modules
+        ├── __init__.py
+        ├── base.py               # Shared utilities and common options
+        ├── page_commands.py      # Page content commands
+        ├── link_commands.py      # Link-related commands
+        ├── category_commands.py  # Category commands
+        ├── geo_commands.py       # Geographic commands
+        └── search_commands.py    # Search and discovery commands
+
+**Main Entry Point (``cli.py``)**
+
+* Sets up the Click command group with version and help options
+* Imports and registers all command modules
+* Provides the ``main()`` function for the console script entry point
+* Reduced from 1481 lines to 54 lines for better maintainability
+
+**Base Module (``commands/base.py``)**
+
+* Contains shared utilities: TypedDict classes, enum validators, formatters
+* Defines common Click options used across all commands
+* Provides helper functions for Wikipedia instance creation and page fetching
+* Centralizes formatting functions for consistent output
+
+**Command Modules**
+
+Each command module groups related functionality:
+
+* ``page_commands.py`` — ``summary``, ``text``, ``sections``, ``section``, ``page``
+* ``link_commands.py`` — ``links``, ``backlinks``, ``langlinks``
+* ``category_commands.py`` — ``categories``, ``categorymembers``
+* ``geo_commands.py`` — ``coordinates``, ``images``, ``geosearch``
+* ``search_commands.py`` — ``search``, ``random``
+
+**Command Pattern**
+
+Each command module follows this pattern:
+
+1. **Business logic functions** — Pure functions that handle Wikipedia API calls
+2. **Formatting functions** — Convert results to text/JSON output
+3. **Click command decorators** — Define CLI interface with options and arguments
+4. **Register function** — Registers commands with the main CLI group
+
+**Benefits of Modular Structure**
+
+* **Maintainable file sizes** — Each module 150-430 lines vs one 1481-line file
+* **Logical organization** — Related commands grouped together
+* **Easier development** — Changes to specific functionality isolated to relevant module
+* **Better testing** — Command modules can be tested independently
+* **Perfect backward compatibility** — All CLI commands work identically to before
+
+**Usage Examples**
+
+The CLI supports all original commands with identical interfaces::
+
+    wikipedia-api summary "Python (programming language)"
+    wikipedia-api links "Python (programming language)" --language cs
+    wikipedia-api categories "Python (programming language)" --json
+    wikipedia-api coordinates "Mount Everest"
+    wikipedia-api geosearch --coord "51.5074|-0.1278"
+    wikipedia-api search "Python programming"
+
+**Adding New Commands**
+
+To add a new CLI command:
+
+1. Choose the appropriate command module based on functionality
+2. Add business logic function (following existing patterns)
+3. Add formatting function for output
+4. Add Click command with proper options and documentation
+5. Register the command in the module's ``register_commands()`` function
+
+The modular structure makes it easy to extend the CLI while maintaining clean organization.

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/DEVELOPMENT.rst

@@ -10,11 +10,13 @@ Prerequisites
 
 Makefile targets
 -----------------
-* ``make run-pre-commit`` - lints source code
+* ``make run-type-check`` - type checks source code (runs ``uv run ty check wikipediaapi/``)
+* ``make run-ruff`` - lints and checks formatting (runs ``ruff check`` and ``ruff format --check``)
 * ``make requirements-all`` - install all requirements
   * ``make requirements`` - install package requirements
   * ``make requirements-dev`` - install development requirements
 * ``make run-tests`` - run unit tests (pytest)
+* ``make run-tests-integration`` - run VCR integration tests (pytest)
 * ``make run-coverage`` - run code coverage (pytest-cov)
 * ``make pypi-html`` - generates single HTML documentation into ``pypi-doc.html``
 * ``make html`` - generates HTML documentation similar to RTFD into folder ``_build/html/``

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Wikipedia-API
-Version: 0.13.0
+Version: 0.14.0
 Summary: Python Wrapper for Wikipedia
 Project-URL: Homepage, https://github.com/martin-majlis/Wikipedia-API
 Project-URL: Repository, https://github.com/martin-majlis/Wikipedia-API
@@ -562,7 +562,8 @@ How To Get Page Images
 ~~~~~~~~~~~~~~~~~~~~~~
 
 To get images (files) used on a page, use ``images()`` on the wiki client or the
-``images`` property on the page.
+``images`` property on the page.  The ``images`` method returns an ``ImagesDict``
+with ``WikipediaImage`` objects that provide lazy access to image metadata.
 
 **Synchronous**
 
@@ -570,12 +571,29 @@ To get images (files) used on a page, use ``images()`` on the wiki client or the
 
     page = wiki_wiki.page('London')
     imgs = wiki_wiki.images(page)
-    for title in imgs:
+    for title, img in imgs.items():
         print(title)
 
     # Or via the page property:
     imgs = page.images
 
+To fetch detailed metadata about images (URL, dimensions, MIME type, etc.),
+use the ``imageinfo()`` method on the ``ImagesDict``:
+
+.. code-block:: python
+
+    page = wiki_wiki.page('Python_(programming_language)')
+    for title, img in page.images.items():
+        # Lazy properties trigger imageinfo API call on first access:
+        print(f"{title}: {img.url}, {img.width}x{img.height}, {img.mime}")
+
+    # Or batch-fetch imageinfo for all images at once:
+    infos = page.images.imageinfo()
+    for title, info_list in infos.items():
+        if info_list:
+            info = info_list[0]
+            print(f"{title}: {info.url}, {info.width}x{info.height}")
+
 **Asynchronous**
 
 .. code-block:: python
@@ -583,9 +601,25 @@ To get images (files) used on a page, use ``images()`` on the wiki client or the
     async def main():
         page = wiki_wiki.page('London')
         imgs = await wiki_wiki.images(page)
-        for title in imgs:
+        for title, img in imgs.items():
             print(title)
 
+        # Fetch image metadata with lazy properties:
+        page = wiki_wiki.page('Python_(programming_language)')
+        for title, img in (await page.images).items():
+            url = await img.url
+            width = await img.width
+            height = await img.height
+            mime = await img.mime
+            print(f"{title}: {url}, {width}x{height}, {mime}")
+
+        # Or batch-fetch imageinfo for all images:
+        infos = await (await page.images).imageinfo()
+        for title, info_list in infos.items():
+            if info_list:
+                info = info_list[0]
+                print(f"{title}: {info.url}, {info.width}x{info.height}")
+
 How To Search Nearby Pages (Geosearch)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/README.rst

@@ -529,7 +529,8 @@ How To Get Page Images
 ~~~~~~~~~~~~~~~~~~~~~~
 
 To get images (files) used on a page, use ``images()`` on the wiki client or the
-``images`` property on the page.
+``images`` property on the page.  The ``images`` method returns an ``ImagesDict``
+with ``WikipediaImage`` objects that provide lazy access to image metadata.
 
 **Synchronous**
 
@@ -537,12 +538,29 @@ To get images (files) used on a page, use ``images()`` on the wiki client or the
 
     page = wiki_wiki.page('London')
     imgs = wiki_wiki.images(page)
-    for title in imgs:
+    for title, img in imgs.items():
         print(title)
 
     # Or via the page property:
     imgs = page.images
 
+To fetch detailed metadata about images (URL, dimensions, MIME type, etc.),
+use the ``imageinfo()`` method on the ``ImagesDict``:
+
+.. code-block:: python
+
+    page = wiki_wiki.page('Python_(programming_language)')
+    for title, img in page.images.items():
+        # Lazy properties trigger imageinfo API call on first access:
+        print(f"{title}: {img.url}, {img.width}x{img.height}, {img.mime}")
+
+    # Or batch-fetch imageinfo for all images at once:
+    infos = page.images.imageinfo()
+    for title, info_list in infos.items():
+        if info_list:
+            info = info_list[0]
+            print(f"{title}: {info.url}, {info.width}x{info.height}")
+
 **Asynchronous**
 
 .. code-block:: python
@@ -550,9 +568,25 @@ To get images (files) used on a page, use ``images()`` on the wiki client or the
     async def main():
         page = wiki_wiki.page('London')
         imgs = await wiki_wiki.images(page)
-        for title in imgs:
+        for title, img in imgs.items():
             print(title)
 
+        # Fetch image metadata with lazy properties:
+        page = wiki_wiki.page('Python_(programming_language)')
+        for title, img in (await page.images).items():
+            url = await img.url
+            width = await img.width
+            height = await img.height
+            mime = await img.mime
+            print(f"{title}: {url}, {width}x{height}, {mime}")
+
+        # Or batch-fetch imageinfo for all images:
+        infos = await (await page.images).imageinfo()
+        for title, info_list in infos.items():
+            if info_list:
+                info = info_list[0]
+                print(f"{title}: {info.url}, {info.width}x{info.height}")
+
 How To Search Nearby Pages (Geosearch)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{wikipedia_api-0.13.0 → wikipedia_api-0.14.0}/README_processed.rst

@@ -529,7 +529,8 @@ How To Get Page Images
 ~~~~~~~~~~~~~~~~~~~~~~
 
 To get images (files) used on a page, use ``images()`` on the wiki client or the
-``images`` property on the page.
+``images`` property on the page.  The ``images`` method returns an ``ImagesDict``
+with ``WikipediaImage`` objects that provide lazy access to image metadata.
 
 **Synchronous**
 
@@ -537,12 +538,29 @@ To get images (files) used on a page, use ``images()`` on the wiki client or the
 
     page = wiki_wiki.page('London')
     imgs = wiki_wiki.images(page)
-    for title in imgs:
+    for title, img in imgs.items():
         print(title)
 
     # Or via the page property:
     imgs = page.images
 
+To fetch detailed metadata about images (URL, dimensions, MIME type, etc.),
+use the ``imageinfo()`` method on the ``ImagesDict``:
+
+.. code-block:: python
+
+    page = wiki_wiki.page('Python_(programming_language)')
+    for title, img in page.images.items():
+        # Lazy properties trigger imageinfo API call on first access:
+        print(f"{title}: {img.url}, {img.width}x{img.height}, {img.mime}")
+
+    # Or batch-fetch imageinfo for all images at once:
+    infos = page.images.imageinfo()
+    for title, info_list in infos.items():
+        if info_list:
+            info = info_list[0]
+            print(f"{title}: {info.url}, {info.width}x{info.height}")
+
 **Asynchronous**
 
 .. code-block:: python
@@ -550,9 +568,25 @@ To get images (files) used on a page, use ``images()`` on the wiki client or the
     async def main():
         page = wiki_wiki.page('London')
         imgs = await wiki_wiki.images(page)
-        for title in imgs:
+        for title, img in imgs.items():
             print(title)
 
+        # Fetch image metadata with lazy properties:
+        page = wiki_wiki.page('Python_(programming_language)')
+        for title, img in (await page.images).items():
+            url = await img.url
+            width = await img.width
+            height = await img.height
+            mime = await img.mime
+            print(f"{title}: {url}, {width}x{height}, {mime}")
+
+        # Or batch-fetch imageinfo for all images:
+        infos = await (await page.images).imageinfo()
+        for title, info_list in infos.items():
+            if info_list:
+                info = info_list[0]
+                print(f"{title}: {info.url}, {info.width}x{info.height}")
+
 How To Search Nearby Pages (Geosearch)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

wikipedia_api-0.14.0/SKILLS/category_deep_dive/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: category-deep-dive
+description: Traverse a Wikipedia category tree, listing articles and subcategories
+  at each level. Use when you want to explore the full scope of a topic area or build
+  a hierarchical index of pages under a category.
+argument-hint: [Category:Name] [max-depth]
+---
+
+# Category Deep Dive
+
+## Overview
+
+Fetch a Wikipedia category page and walk its member tree recursively:
+
+1. **Category page** — verify it exists and report direct member counts
+2. **Direct members** — list articles and subcategories at depth 0
+3. **Recursion** — descend into each subcategory up to `MAX_LEVEL` deep
+
+## When to use
+
+- You want to enumerate all pages belonging to a broad topic
+- You are building a dataset or index from a Wikipedia category tree
+- You need to understand the sub-structure of a large category
+
+## Parameters
+
+| Parameter   | Description                                       | Default              |
+| ----------- | ------------------------------------------------- | -------------------- |
+| `CATEGORY`  | Full category title including `Category:` prefix  | `"Category:Physics"` |
+| `MAX_LEVEL` | Maximum recursion depth (0 = direct members only) | `1`                  |
+| `language`  | Wikipedia language edition                        | `en`                 |
+
+## Examples
+
+- Sync Python: [sync.py](sync.py)
+- Async Python: [async.py](async.py)
+- CLI: [cli.sh](cli.sh)
+
+## Notes
+
+- Category pages have namespace `14` (`Namespace.CATEGORY`); check `page.ns` to
+  distinguish subcategories from articles when recursing.
+- `categorymembers` is a lazy property — each subcategory you recurse into triggers
+  a new API call.
+- Large categories (e.g. `Category:Living people`) can have thousands of members;
+  use `MAX_LEVEL = 0` and paginate carefully to avoid very long runs.
+- CLI `--max-level` maps directly to the recursion depth parameter.