Wikipedia-API

Wikipedia-API is a Python wrapper for the Wikipedia API. It allows developers to extract various types of data from Wikipedia, including:

• Texts
• Sections
• Links
• Categories
• Translations

The library is built using a decoupled architecture that separates HTTP transport concerns from MediaWiki API logic. This is achieved through two primary layers implemented as abstract mixins:

1. HTTP transport: Handles the mechanics of making requests, including synchronous vs. asynchronous execution, retries, and rate-limit handling.
2. API logic: Handles the construction of MediaWiki query parameters and the parsing of JSON responses into Python objects.

Concrete client classes (like Wikipedia or AsyncWikipedia) are assembled by combining one transport mixin with one API mixin using Python's multiple inheritance. This ensures the API logic layer remains independent of the underlying HTTP library (e.g., httpx).

When adding support for a new MediaWiki action=query submodule, you must first identify which of the two families it belongs to. This choice dictates how you dispatch requests and whether the submodule is tied to a specific page.

• prop= submodules are per-page data fetched using a page title.
• list= submodules are standalone queries not tied to a specific page.

Page objects in Wikipedia-API are created lazily via wiki.page(title). No network call is made during construction. Instead, the first time you access a property (e.g., page.summary), the library triggers the API call. Subsequent accesses to that same property return the cached value.

Key behaviors:

• Lazy Fetching: WikipediaPage._fetch(call) is triggered on the first property access.
• Per-parameter Caching: Some properties like coordinates and images support different parameter sets. Results are cached in page._param_cache[name][cache_key].
• Sentinel Value: The library uses a NOT_CACHED sentinel to distinguish between a property that has never been fetched and a property that was fetched but returned None.

The library provides type aliases (e.g., WikiSearchSort, WikiGlobe) that represent a Union[Enum, str]. When writing your own functions that wrap the Wikipedia API, use these aliases in your type annotations. This allows your functions to accept either the strongly-typed enum or a simple string while remaining type-safe.

from wikipediaapi import WikiSearchSort, WikiGlobe, GeoPoint

def search_wiki(query: str, sort: WikiSearchSort):
    # This function accepts SearchSort.RELEVANCE or "relevance"
    pass

def geo_search_wiki(coord: GeoPoint, sort: WikiGlobe):
    # This function accepts Globe.EARTH or "earth"
    pass

The library uses a composition pattern where concrete client instances (like Wikipedia or AsyncWikipedia) act as the primary entry points and manage the transport layer. These clients produce Page objects (like WikipediaPage or AsyncWikipediaPage) which represent specific Wikipedia articles.

Page objects hold a back-reference to their parent client instance. This allows Page objects to lazily trigger data fetching by calling the client's transport methods only when a specific attribute or property is accessed.

The exists() method and the pageid property follow a deterministic relationship used to indicate the presence of a page:

• If exists() is True: pageid will return a positive integer.
• If exists() is False: pageid will return a negative integer.

Both values are deterministic based on abs(hash(title)).

The extractor produces a flat directory structure. For cassettes containing multiple HTTP interactions, the script generates a separate file for each interaction using an incrementing index.

File Naming Convention: {test_name}_{interaction_index}.json

Example Output Structure:

tests/cassettes-json/
├── TestVcrAsyncPageExistence.test_exists_true_0.json
├── TestVcrAsyncPageExistence.test_exists_false_0.json
├── TestVcrAsyncPageExtractProps.test_summary_0.json
└── ...