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

{wikipedia_api-0.14.0 → wikipedia_api-0.14.1}/.gitignore

@@ -18,6 +18,13 @@ eggs/
 lib/
 lib64/
 parts/
+
+# IDE and editor files
+.DS_Store
+.claude/
+CLAUDE.md
+PR_DESCRIPTION.md
+wikipedia-api-specification
 sdist/
 var/
 *.egg-info/

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

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+0.14.1
+------
+
+* pageid for images is deterministic - `PR 549`_
+
+.. _PR 549: https://github.com/martin-majlis/Wikipedia-API/pull/549
+
 0.14.0
 ------
 

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

@@ -103,14 +103,21 @@ File Layout
     │   ├── 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
+    ├── _wikipedia/              # Concrete client package
+    │   ├── __init__.py
+    │   ├── wikipedia.py         # Wikipedia (sync concrete client)
+    │   └── async_wikipedia.py   # AsyncWikipedia (async concrete client)
+    ├── _page/                   # Page object package
+    │   ├── __init__.py
+    │   ├── _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_page_section.py # WikipediaPageSection
+    ├── _image/                  # Image/file page object package
+    │   ├── __init__.py
+    │   ├── _base_wikipedia_image.py  # BaseWikipediaImage (shared image state & methods)
+    │   ├── wikipedia_image.py        # WikipediaImage (lazy sync file page object)
+    │   └── async_wikipedia_image.py  # AsyncWikipediaImage (lazy async file page object)
     ├── extract_format.py        # ExtractFormat enum (WIKI / HTML)
     └── namespace.py             # Legacy namespace module (redirects to _enums.namespace)
 
@@ -131,8 +138,9 @@ The inheritance chains are::
     BaseWikipediaPage
     ├── WikipediaPage
     ├── AsyncWikipediaPage
-    ├── WikipediaImage
-    └── AsyncWikipediaImage
+    └── BaseWikipediaImage
+        ├── WikipediaImage
+        └── AsyncWikipediaImage
 
 Concrete clients compose one transport and one API mixin::
 
@@ -159,6 +167,9 @@ The subclasses are responsible for the fundamentally different parts:
   ``await page.summary`` first.
 * ``exists()`` — sync auto-fetches via ``self.pageid``; async is a
   coroutine method that lazily fetches ``pageid`` via ``info``.
+  **Invariant**: When ``exists()`` returns ``True``, ``pageid`` returns a
+  positive integer; when ``exists()`` returns ``False``, ``pageid`` returns a
+  negative integer. Both values are deterministic based on ``abs(hash(title))``.
 * All data-fetching surface (``summary``, ``langlinks``, ``pageid``, …)
   — explicit ``@property`` in both; async properties return coroutines
   (``await page.summary``, ``await page.pageid``, etc.).
@@ -531,7 +542,7 @@ and stores results under ``raw["query"]["pages"][id]["templates"]``.
 Step 2 — Add a Return-Type Attribute to BaseWikipediaPage
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In ``_base_wikipedia_page.py``, add a cache slot in
+In ``_page/_base_wikipedia_page.py``, add a cache slot in
 ``BaseWikipediaPage.__init__``::
 
     self._templates: dict[str, Any] = {}
@@ -637,7 +648,7 @@ Step 6 — Add the Async Method to AsyncWikipediaResource
 Step 7 — Add a Lazy Property to WikipediaPage
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In ``wikipedia_page.py``::
+In ``_page/wikipedia_page.py``::
 
     @property
     def templates(self) -> PagesDict:
@@ -649,7 +660,7 @@ In ``wikipedia_page.py``::
 Step 8 — Add a Lazy Coroutine Property to AsyncWikipediaPage
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In ``async_wikipedia_page.py``, the ``@property`` returns a coroutine
+In ``_page/async_wikipedia_page.py``, the ``@property`` returns a coroutine
 created by a nested ``async def``; callers do ``await page.templates``::
 
     @property

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Wikipedia-API
-Version: 0.14.0
+Version: 0.14.1
 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
@@ -26,7 +26,7 @@ Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: click==8.3.1
+Requires-Dist: click==8.3.2
 Requires-Dist: httpx==0.28.1
 Requires-Dist: tenacity==9.1.4
 Description-Content-Type: text/x-rst

wikipedia_api-0.14.1/SKILLS/README.md

@@ -0,0 +1,69 @@
+# Wikipedia-API
+
+Python wrapper for the [MediaWiki API](https://www.mediawiki.org/wiki/API:Main_page).
+Provides both synchronous (`Wikipedia`) and asynchronous (`AsyncWikipedia`) clients.
+
+## Installation
+
+```bash
+pip install wikipedia-api
+```
+
+## Client Initialization
+
+```python
+import wikipediaapi
+
+# Basic client — English Wikipedia, plain-text extract format
+wiki = wikipediaapi.Wikipedia(
+    user_agent="MyProject/1.0 (contact@example.com)",
+    language="en"
+)
+
+# HTML extract format (summary and section text returned as HTML fragments)
+wiki_html = wikipediaapi.Wikipedia(
+    user_agent="MyProject/1.0 (contact@example.com)",
+    language="cs",
+    extract_format=wikipediaapi.ExtractFormat.HTML,
+)
+
+# Forward extra parameters to every API request (e.g. auto-follow redirects)
+wiki_extra = wikipediaapi.Wikipedia(
+    user_agent="MyProject/1.0 (contact@example.com)",
+    language="en",
+    extra_api_params={"redirects": "1"},
+)
+
+# Async client — same options, use AsyncWikipedia instead
+wiki_async = wikipediaapi.AsyncWikipedia(
+    user_agent="MyProject/1.0 (contact@example.com)",
+    language="en"
+)
+```
+
+> **User-Agent is required.** MediaWiki blocks requests without a descriptive
+> `User-Agent`. Use the format `AppName/Version (contact)`.
+
+## Quick Start
+
+```python
+import wikipediaapi
+
+wiki = wikipediaapi.Wikipedia(
+    user_agent="MyProject/1.0 (contact@example.com)",
+    language="en"
+)
+
+page = wiki.page("Python (programming language)")
+if page.exists():
+    print(page.title)
+    print(page.summary[:200])
+```
+
+---
+
+## Further Reading
+
+- [python-sync.md](python-sync.md) — Full synchronous API reference with examples
+- [python-async.md](python-async.md) — Full asynchronous API reference with examples
+- [bash.md](bash.md) — CLI command reference with examples

wikipedia_api-0.14.1/SKILLS/bash.md

@@ -0,0 +1,278 @@
+# Wikipedia-API — CLI (Bash)
+
+The `wikipedia-api` CLI is installed automatically with the package.
+
+Full working example: [`examples/example_cli.sh`](../examples/example_cli.sh)
+
+---
+
+## Installation
+
+```bash
+pip install wikipedia-api
+wikipedia-api --version
+```
+
+---
+
+## Global Options
+
+Every command accepts these options:
+
+| Option                 | Description                                     | Default |
+| ---------------------- | ----------------------------------------------- | ------- |
+| `-l, --language`       | Wikipedia language edition                      | `en`    |
+| `-u, --user-agent`     | HTTP User-Agent string                          | —       |
+| `-v, --variant`        | Language variant (e.g. `zh-cn`, `zh-tw`)        | —       |
+| `-f, --extract-format` | Extract format: `wiki` or `html`                | `wiki`  |
+| `-n, --namespace`      | Wikipedia namespace number                      | `0`     |
+| `--max-retries`        | Max retry attempts (0 to disable)               | `3`     |
+| `--retry-wait`         | Base wait between retries (exponential backoff) | `1.0`   |
+| `--json`               | Output as JSON                                  | —       |
+| `-h, --help`           | Show help                                       | —       |
+
+```bash
+# Show all available commands
+wikipedia-api --help
+
+# Show help for a specific command
+wikipedia-api summary --help
+```
+
+---
+
+## Page Metadata
+
+```bash
+# Show page info (pageid, fullurl, editurl, length, lastrevid, etc.)
+wikipedia-api page "Python (programming language)"
+
+# JSON output — includes all info attributes
+wikipedia-api page "Python (programming language)" --json
+
+# Missing page — pageid will be -1 in JSON output
+wikipedia-api page "Wikipedia-API-FooBar-DoesNotExist" --json
+```
+
+---
+
+## Summary
+
+```bash
+wikipedia-api summary "Python (programming language)"
+
+# Summary in Czech
+wikipedia-api summary "Ostrava" --language cs
+
+# Summary in Chinese with variant
+wikipedia-api summary "Python" --language zh --variant zh-cn
+
+# Summary as HTML
+wikipedia-api summary "Ostrava" --language cs --extract-format html
+```
+
+---
+
+## Full Text
+
+```bash
+wikipedia-api text "Python (programming language)"
+
+# Full text as HTML
+wikipedia-api text "Ostrava" --language cs --extract-format html
+```
+
+---
+
+## Sections
+
+```bash
+# List the full section hierarchy
+wikipedia-api sections "Python (programming language)"
+
+wikipedia-api sections "Python (programming language)" --json
+
+# Print the text of a specific section
+wikipedia-api section "Python (programming language)" "Features and philosophy"
+```
+
+---
+
+## Language Links
+
+```bash
+wikipedia-api langlinks "Python (programming language)"
+
+wikipedia-api langlinks "Python (programming language)" --json
+```
+
+---
+
+## Links and Backlinks
+
+```bash
+wikipedia-api links "Python (programming language)"
+
+wikipedia-api links "Python (programming language)" --json
+
+wikipedia-api backlinks "Python (programming language)"
+
+wikipedia-api backlinks "Python (programming language)" --json
+```
+
+---
+
+## Categories and Category Members
+
+```bash
+wikipedia-api categories "Python (programming language)"
+
+wikipedia-api categories "Python (programming language)" --json
+
+# List pages in a category
+wikipedia-api categorymembers "Category:Physics"
+
+# Recursively include subcategory members (depth 1)
+wikipedia-api categorymembers "Category:Physics" --max-level 1
+
+wikipedia-api categorymembers "Category:Physics" --json
+```
+
+---
+
+## Language Variants
+
+```bash
+# Default script
+wikipedia-api summary "Python" --language zh
+
+# Simplified Chinese
+wikipedia-api summary "Python" --language zh --variant zh-cn
+
+# Traditional Chinese
+wikipedia-api summary "Python" --language zh --variant zh-tw
+
+# Singapore Simplified Chinese
+wikipedia-api summary "Python" --language zh --variant zh-sg
+```
+
+---
+
+## Coordinates
+
+```bash
+# Primary coordinate only (default)
+wikipedia-api coordinates "London"
+
+# All coordinates (primary + secondary)
+wikipedia-api coordinates "London" --primary all
+
+wikipedia-api coordinates "London" --json
+
+wikipedia-api coordinates "Mount Everest"
+```
+
+---
+
+## Images and Image Metadata
+
+```bash
+# List image titles used on a page
+wikipedia-api images "Python (programming language)"
+
+wikipedia-api images "Python (programming language)" --json
+
+# Fetch metadata (URL, dimensions, MIME type, uploader, timestamp, etc.)
+wikipedia-api images "Mount Everest" --imageinfo
+
+wikipedia-api images "Mount Everest" --imageinfo --json
+
+# Limit number of images
+wikipedia-api images "Earth" --limit 20 --imageinfo
+```
+
+---
+
+## Geosearch
+
+```bash
+# Search near a coordinate (London city centre)
+wikipedia-api geosearch --coord "51.5074|-0.1278"
+
+# Limit radius and result count
+wikipedia-api geosearch --coord "51.5074|-0.1278" --radius 1000 --limit 5
+
+# Search near a named page
+wikipedia-api geosearch --page "Big Ben" --radius 1000
+
+wikipedia-api geosearch --coord "48.8566|2.3522" --json
+```
+
+---
+
+## Random Pages
+
+```bash
+wikipedia-api random
+
+wikipedia-api random --limit 3
+
+wikipedia-api random --limit 3 --json
+```
+
+---
+
+## Search
+
+```bash
+wikipedia-api search "Python programming"
+
+wikipedia-api search "Python programming" --limit 5
+
+wikipedia-api search "Python programming" --json
+
+# Search in another language
+wikipedia-api search "машинное обучение" --language ru
+```
+
+---
+
+## Retry Configuration
+
+```bash
+# 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
+
+# Aggressive retrying for unreliable connections
+wikipedia-api geosearch --coord "27.9881|86.9250" --max-retries 10 --retry-wait 3.0
+```
+
+---
+
+## Complete Workflow Example
+
+```bash
+UA="MyProject/1.0 (contact@example.com)"
+
+# Explore a page from multiple angles
+wikipedia-api summary "Python (programming language)" --user-agent "$UA"
+wikipedia-api sections "Python (programming language)" --user-agent "$UA"
+wikipedia-api section  "Python (programming language)" "History" --user-agent "$UA"
+wikipedia-api categories "Python (programming language)" --user-agent "$UA"
+wikipedia-api langlinks "Python (programming language)" --user-agent "$UA"
+
+# Follow a language link to German Wikipedia
+wikipedia-api summary "Python (Programmiersprache)" --language de --user-agent "$UA"
+
+# Geographic pages
+wikipedia-api coordinates "Mount Everest" --user-agent "$UA"
+wikipedia-api geosearch --coord "27.9881|86.9250" --radius 5000 --user-agent "$UA"
+wikipedia-api images "Mount Everest" --imageinfo --user-agent "$UA"
+
+# Discovery
+wikipedia-api random --limit 3 --user-agent "$UA"
+wikipedia-api search "Mount Everest" --limit 5 --user-agent "$UA"
+```