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

{wikipedia_api-0.12.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.12.0 → wikipedia_api-0.14.0}/CHANGES.rst

@@ -1,6 +1,20 @@
 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
+------
+
+* Pass parameters to the underlying htttp client - `PR 520`_
+
+.. _PR 520: https://github.com/martin-majlis/Wikipedia-API/pull/520
+
 0.12.0
 ------
 

{wikipedia_api-0.12.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.12.0 → wikipedia_api-0.14.0}/DESIGN.rst

@@ -34,25 +34,85 @@ File Layout
 
     wikipediaapi/
     ├── __init__.py              # Public exports
-    ├── _http_client.py          # Transport layer
-    │   ├── BaseHTTPClient       # Shared retry & config logic
-    │   ├── SyncHTTPClient       # Blocking httpx.Client
-    │   └── AsyncHTTPClient      # Non-blocking httpx.AsyncClient
-    ├── _resources.py            # API layer
-    │   ├── BaseWikipediaResource  # Param builders, parsers, dispatchers
-    │   ├── WikipediaResource      # Sync public API methods
-    │   └── AsyncWikipediaResource # Async public API methods
-    ├── _types.py                # Typed dataclasses (GeoPoint, GeoBox, Coordinate, GeoSearchMeta, SearchMeta, SearchResults)
-    ├── _params.py               # Query parameter dataclasses (CoordinatesParams, ImagesParams, …)
-    ├── _pages_dict.py           # PagesDict / AsyncPagesDict (dict subclasses with batch methods)
+    ├── 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
+    │   ├── sync_http_client.py   # Blocking httpx.Client
+    │   ├── async_http_client.py  # Non-blocking httpx.AsyncClient
+    │   ├── retry_utils.py        # Retry utilities
+    │   └── retry_after_wait.py   # Retry-After header handling
+    ├── _resources/              # API layer package
+    │   ├── __init__.py
+    │   ├── base_wikipedia_resource.py  # Param builders, parsers, dispatchers
+    │   ├── wikipedia_resource.py      # Sync public API methods
+    │   └── async_wikipedia_resource.py # Async public API methods
+    ├── _types/                  # Typed dataclasses package
+    │   ├── __init__.py
+    │   ├── coordinate.py         # Coordinate dataclass
+    │   ├── 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
+    │   ├── __init__.py
+    │   ├── base_params.py       # Base parameter class
+    │   ├── coordinates_params.py # CoordinatesParams
+    │   ├── geo_search_params.py  # GeoSearchParams
+    │   ├── images_params.py      # ImagesParams
+    │   ├── random_params.py      # RandomParams
+    │   ├── search_params.py      # SearchParams
+    │   └── protocols.py          # Protocol constants
+    ├── _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
+    │   ├── images_dict.py        # ImagesDict (sync)
+    │   └── async_images_dict.py  # AsyncImagesDict
+    ├── _enums/                  # Enums package
+    │   ├── __init__.py
+    │   ├── coordinate_type.py    # CoordinateType enum
+    │   ├── coordinates_prop.py  # CoordinatesProp enum
+    │   ├── direction.py          # Direction enum
+    │   ├── geosearch_sort.py     # GeoSearchSort enum
+    │   ├── globe.py              # Globe enum
+    │   ├── namespace.py          # Namespace enum
+    │   ├── redirect_filter.py    # RedirectFilter enum
+    │   ├── search_info.py        # SearchInfo enum
+    │   ├── search_prop.py        # SearchProp enum
+    │   ├── search_qi_profile.py  # SearchQiProfile enum
+    │   ├── search_sort.py        # SearchSort enum
+    │   └── search_what.py        # SearchWhat enum
+    ├── exceptions/              # Exception classes package
+    │   ├── __init__.py
+    │   ├── wikipedia_exception.py      # Base exception
+    │   ├── wiki_connection_error.py     # Connection errors
+    │   ├── wiki_http_error.py            # HTTP errors
+    │   ├── wiki_http_timeout_error.py   # Timeout errors
+    │   ├── wiki_invalid_json_error.py   # JSON parsing errors
+    │   └── wiki_rate_limit_error.py     # Rate limiting errors
     ├── wikipedia.py             # Wikipedia (sync concrete client)
     ├── async_wikipedia.py       # AsyncWikipedia (async concrete client)
     ├── _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             # Namespace / WikiNamespace
+    └── namespace.py             # Legacy namespace module (redirects to _enums.namespace)
 
 
 Class Hierarchy
@@ -70,7 +130,9 @@ The inheritance chains are::
 
     BaseWikipediaPage
     ├── WikipediaPage
-    └── AsyncWikipediaPage
+    ├── AsyncWikipediaPage
+    ├── WikipediaImage
+    └── AsyncWikipediaImage
 
 Concrete clients compose one transport and one API mixin::
 
@@ -228,12 +290,12 @@ Full Class Diagram
 Transport Layer
 ---------------
 
-``_http_client.py`` implements three classes.
+``_http_client/`` package implements the HTTP transport layer with three classes.
 
 BaseHTTPClient
 ~~~~~~~~~~~~~~
 
-Abstract base that holds shared configuration (language, variant,
+Abstract base in ``base_http_client.py`` that holds shared configuration (language, variant,
 user-agent, extract format, retry parameters, extra API params) and
 the ``_check_and_correct_params()`` validator.  It does **not** make
 HTTP requests directly.
@@ -241,14 +303,14 @@ HTTP requests directly.
 SyncHTTPClient
 ~~~~~~~~~~~~~~
 
-Provides a blocking ``_get(language, params) -> dict`` method backed by
+Provides a blocking ``_get(language, params) -> dict`` method in ``sync_http_client.py`` backed by
 ``httpx.Client``.  Retry logic uses ``tenacity`` with exponential
 backoff; ``Retry-After`` headers are honoured for HTTP 429 responses.
 
 AsyncHTTPClient
 ~~~~~~~~~~~~~~~
 
-Provides an ``async def _get(language, params) -> dict`` coroutine
+Provides an ``async def _get(language, params) -> dict`` coroutine in ``async_http_client.py``
 backed by ``httpx.AsyncClient``.  Retry logic mirrors
 ``SyncHTTPClient`` but uses ``tenacity``'s ``AsyncRetrying``.
 
@@ -256,16 +318,21 @@ Both clients construct the endpoint URL as::
 
     https://{language}.wikipedia.org/w/api.php
 
+Additional utilities:
+
+- ``retry_utils.py`` - Common retry utilities and helpers
+- ``retry_after_wait.py`` - Retry-After header handling logic
+
 
 API Layer
 ---------
 
-``_resources.py`` implements three classes.
+``_resources/`` package implements the API layer with three classes.
 
 BaseWikipediaResource
 ~~~~~~~~~~~~~~~~~~~~~
 
-Pure mixin with no HTTP transport.  Contains:
+Pure mixin in ``base_wikipedia_resource.py`` with no HTTP transport.  Contains:
 
 * **Parameter builders** (``_*_params``) — each returns a ``dict``
   ready to pass to the dispatcher.
@@ -279,7 +346,7 @@ Pure mixin with no HTTP transport.  Contains:
 WikipediaResource
 ~~~~~~~~~~~~~~~~~
 
-Thin synchronous mixin.  Each public API method (``extracts``,
+Thin synchronous mixin in ``wikipedia_resource.py``.  Each public API method (``extracts``,
 ``info``, ``langlinks``, ``links``, ``backlinks``, ``categories``,
 ``categorymembers``) is a one-liner that delegates to the appropriate
 sync dispatch helper::
@@ -293,7 +360,7 @@ sync dispatch helper::
 AsyncWikipediaResource
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Mirror of ``WikipediaResource`` using async dispatch helpers::
+Mirror of ``WikipediaResource`` using async dispatch helpers in ``async_wikipedia_resource.py``::
 
     async def extracts(self, page, **kwargs):
         return await self._async_dispatch_prop(
@@ -472,7 +539,7 @@ In ``_base_wikipedia_page.py``, add a cache slot in
 Step 3 — Add the Parameter Builder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In ``BaseWikipediaResource`` (``_resources.py``), add::
+In ``BaseWikipediaResource`` (``_resources/base_wikipedia_resource.py``), add::
 
     def _templates_params(self, page: WikipediaPage) -> dict[str, Any]:
         """
@@ -495,7 +562,7 @@ In ``BaseWikipediaResource`` (``_resources.py``), add::
 Step 4 — Add the Response Parser
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In ``BaseWikipediaResource``, add::
+In ``BaseWikipediaResource`` (``_resources/base_wikipedia_resource.py``), add::
 
     def _build_templates(
         self, extract: Any, page: WikipediaPage
@@ -691,19 +758,20 @@ preserved when adding new functionality.
   ``_build_*`` implementations without duplication.
 * All raises must be documented in the docstring.
 
-**Typed data (``_types.py``)**
+**Typed data (``_types/`` package)**
 
-* ``GeoPoint``, ``GeoBox``, ``Coordinate``, ``GeoSearchMeta``, ``SearchMeta`` —
-  frozen ``@dataclass`` value objects used by the new query submodule
-  methods.
-* ``SearchResults`` — a wrapper around a ``PagesDict`` that adds
-  ``totalhits`` and ``suggestion`` from the ``searchinfo`` block.
+* ``coordinate.py`` — ``Coordinate`` frozen ``@dataclass`` value objects
+* ``geo_point.py`` — ``GeoPoint`` frozen ``@dataclass`` value objects
+* ``geo_box.py`` — ``GeoBox`` frozen ``@dataclass`` value objects
+* ``geo_search_meta.py`` — ``GeoSearchMeta`` frozen ``@dataclass`` value objects
+* ``search_meta.py`` — ``SearchMeta`` frozen ``@dataclass`` value objects
+* ``search_results.py`` — ``SearchResults`` wrapper around ``PagesDict``
 
-**Parameter dataclasses (``_params.py``)**
+**Parameter dataclasses (``_params/`` package)**
 
-* Each query submodule has a frozen ``@dataclass`` (e.g.
-  ``CoordinatesParams``, ``ImagesParams``) that maps clean Python
-  names to MediaWiki API parameter names with a configurable prefix.
+Each query submodule has a frozen ``@dataclass`` (e.g.
+``CoordinatesParams``, ``ImagesParams``) that maps clean Python
+names to MediaWiki API parameter names with a configurable prefix.
 * Pipe-separated MediaWiki parameters (for example ``prop``, ``info``,
   and ``images``) are exposed as iterable-only inputs in the Python API.
   They are normalized to ``"|"``-joined strings in ``__post_init__``
@@ -712,6 +780,31 @@ preserved when adding new functionality.
   API call; ``cache_key()`` returns a hashable tuple for per-parameter
   caching.
 
+**Enums (``_enums/`` package)**
+
+Strongly-typed enums for API parameters:
+* ``coordinate_type.py`` — ``CoordinateType`` enum for coordinate filtering
+* ``coordinates_prop.py`` — ``CoordinatesProp`` enum for coordinate properties
+* ``direction.py`` — ``Direction`` enum for sort direction
+* ``geosearch_sort.py`` — ``GeoSearchSort`` enum for geographic search sorting
+* ``globe.py`` — ``Globe`` enum for celestial bodies
+* ``namespace.py`` — ``Namespace`` enum for MediaWiki namespaces
+* ``redirect_filter.py`` — ``RedirectFilter`` enum for redirect filtering
+* ``search_info.py`` — ``SearchInfo`` enum for search metadata
+* ``search_prop.py`` — ``SearchProp`` enum for search properties
+* ``search_qi_profile.py`` — ``SearchQiProfile`` enum for query-independent ranking
+* ``search_sort.py`` — ``SearchSort`` enum for search sorting
+* ``search_what.py`` — ``SearchWhat`` enum for search type
+
+**Exceptions (``exceptions/`` package)**
+
+* ``wikipedia_exception.py`` — ``WikipediaException`` base exception
+* ``wiki_connection_error.py`` — ``WikiConnectionError`` for connection failures
+* ``wiki_http_error.py`` — ``WikiHttpError`` for HTTP errors
+* ``wiki_http_timeout_error.py`` — ``WikiHttpTimeoutError`` for timeouts
+* ``wiki_invalid_json_error.py`` — ``WikiInvalidJsonError`` for JSON parsing errors
+* ``wiki_rate_limit_error.py`` — ``WikiRateLimitError`` for rate limiting
+
 **Per-parameter caching**
 
 * ``coordinates`` and ``images`` support different parameter sets per
@@ -747,3 +840,89 @@ preserved when adding new functionality.
 * ``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.12.0 → wikipedia_api-0.14.0}/DEVELOPMENT.rst

@@ -1,20 +1,23 @@
 Development
 ===========
 
-Prerequisities
+Prerequisites
 --------------
+
 * Make
-* Python3.10+
+* Python 3.10+
 * Pip
 
 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
-* ``make run-coverage`` - run code coverage
+* ``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/``
 * ``make release`` - creates new release as well as git tag