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

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

@@ -21,7 +21,8 @@ parts/
 
 # IDE and editor files
 .DS_Store
-.claude/
+.claude/*
+!.claude/skills/
 CLAUDE.md
 PR_DESCRIPTION.md
 wikipedia-api-specification

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

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+0.16.0
+----------
+
+* Allow passing a custom ``transport`` to the underlying ``httpx`` client (e.g. a caching transport such as Hishel) - `PR 659`_
+
+.. _PR 659: https://github.com/martin-majlis/Wikipedia-API/pull/659
+
+0.15.0
+----------
+
+* Make user agent header compliant with Wikimedia Foundation User-Agent policy - `PR 590`_
+
+.. _PR 590: https://github.com/martin-majlis/Wikipedia-API/pull/590
+
 0.14.1
 ------
 

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

@@ -317,6 +317,8 @@ SyncHTTPClient
 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.
+The client defaults to ``httpx.HTTPTransport`` but honours a caller-supplied
+``transport`` kwarg (e.g. a caching transport).
 
 AsyncHTTPClient
 ~~~~~~~~~~~~~~~
@@ -324,6 +326,8 @@ AsyncHTTPClient
 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``.
+The client defaults to ``httpx.AsyncHTTPTransport`` but honours a caller-supplied
+``transport`` kwarg.
 
 Both clients construct the endpoint URL as::
 

wikipedia_api-0.16.0/DEVELOPMENT.rst

@@ -0,0 +1,86 @@
+Development
+===========
+
+Prerequisites
+--------------
+
+* Make
+* Python 3.10+
+* Pip
+
+Makefile targets
+-----------------
+* ``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/``
+* ``make prepare-release VERSION='1.2.3'`` - bumps version files, runs full pre-release checks, and opens a PR from a ``release/1.2.3`` branch
+* ``make create-github-release VERSION='1.2.3'`` - after the PR is merged, creates a GitHub Release with auto-generated notes, triggering PyPI publish
+
+Releasing a New Version
+-----------------------
+
+**During development** — as each PR is merged, add a bullet point describing the
+change under the ``Unreleased`` section at the top of ``CHANGES.rst``::
+
+    Unreleased
+    ----------
+
+    * Add support for foo - `PR 123`_
+
+    .. _PR 123: https://github.com/martin-majlis/Wikipedia-API/pull/123
+
+**When ready to release:**
+
+1. From a clean ``master`` branch, run::
+
+    make prepare-release VERSION='1.2.3'
+
+   This will:
+
+   * Validate the version format and that it is greater than the current version
+   * Check that ``CHANGES.rst`` has an ``Unreleased`` section
+   * Run the full pre-release check suite (tests, type checks, linting, examples)
+   * Create a ``release/1.2.3`` branch
+   * Rename ``Unreleased`` → ``1.2.3`` in ``CHANGES.rst`` and bump all version files
+   * Commit, push the branch, and open a pull request
+
+2. Review and merge the pull request.
+
+3. After the PR is merged, create the GitHub Release::
+
+    make create-github-release VERSION='1.2.3'
+
+   This creates a ``v1.2.3`` tag and GitHub Release with auto-generated release
+   notes (based on merged PRs since the last release), which triggers the
+   ``release.yml`` workflow to publish the package to PyPI.
+
+Usage Statistics
+----------------
+
+* `PIP Downloads`_
+* `Clickpy`_
+* `Libraries.io`_
+* `Deps.dev`_
+
+.. _PIP Downloads: https://pypistats.org/packages/wikipedia-api
+.. _Libraries.io: https://libraries.io/pypi/Wikipedia-API
+.. _Deps.dev: https://deps.dev/pypi/wikipedia-api
+.. _Clickpy: https://clickpy.clickhouse.com/dashboard/wikipedia-api
+
+Underlying API
+--------------
+
+* `API - HP`_
+* `Module - Parse`_
+* `Module - Query`_
+
+.. _API - HP: https://www.mediawiki.org/wiki/API:Main_page
+.. _Module - Parse: https://en.wikipedia.org/w/api.php?action=help&modules=parse
+.. _Module - Query: https://en.wikipedia.org/w/api.php?action=help&modules=query

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: Wikipedia-API
-Version: 0.14.1
+Version: 0.16.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
@@ -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.2
+Requires-Dist: click==8.5.0
 Requires-Dist: httpx==0.28.1
 Requires-Dist: tenacity==9.1.4
 Description-Content-Type: text/x-rst
@@ -89,10 +89,10 @@ Getting single page is straightforward. You have to initialize ``Wikipedia`` (or
 object and ask for page by its name.
 To initialize it, you have to provide:
 
-* `user_agent` to identify your project. Please follow the recommended `format`_.
+* `user_agent` to identify your project. **Must include contact information** (email or website) and follow the Wikimedia Foundation `User-Agent policy`_.
 * `language` to specify language mutation. It has to be one of `supported languages`_.
 
-.. _format: https://meta.wikimedia.org/wiki/User-Agent_policy
+.. _User-Agent policy: https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy
 .. _supported languages: http://meta.wikimedia.org/wiki/List_of_Wikipedias
 
 **Synchronous**
@@ -1045,6 +1045,31 @@ The same options apply to both ``Wikipedia`` and ``AsyncWikipedia``.
         max_retries=0,
     )
 
+Custom HTTP Transport
+~~~~~~~~~~~~~~~~~~~~~~
+
+Any keyword argument that is not recognised by ``Wikipedia`` / ``AsyncWikipedia`` is
+forwarded to the underlying ``httpx`` client. This includes ``transport``, which lets you
+plug in a custom transport such as a caching transport
+(e.g. `Hishel <https://hishel.com/httpx.html>`_). When ``transport`` is omitted, the default
+``httpx.HTTPTransport`` (sync) / ``httpx.AsyncHTTPTransport`` (async) is used.
+
+.. code-block:: python
+
+    import hishel
+    import httpx
+    import wikipediaapi
+
+    # Cache responses so repeated lookups avoid hitting Wikipedia again
+    wiki_wiki = wikipediaapi.Wikipedia(
+        user_agent='MyProjectName (merlin@example.com)',
+        language='en',
+        transport=hishel.CacheTransport(transport=httpx.HTTPTransport()),
+    )
+
+For ``AsyncWikipedia`` use an async transport (e.g.
+``hishel.AsyncCacheTransport(transport=httpx.AsyncHTTPTransport())``).
+
 How To See Underlying API Call
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/README.rst

@@ -56,10 +56,10 @@ Getting single page is straightforward. You have to initialize ``Wikipedia`` (or
 object and ask for page by its name.
 To initialize it, you have to provide:
 
-* `user_agent` to identify your project. Please follow the recommended `format`_.
+* `user_agent` to identify your project. **Must include contact information** (email or website) and follow the Wikimedia Foundation `User-Agent policy`_.
 * `language` to specify language mutation. It has to be one of `supported languages`_.
 
-.. _format: https://meta.wikimedia.org/wiki/User-Agent_policy
+.. _User-Agent policy: https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy
 .. _supported languages: http://meta.wikimedia.org/wiki/List_of_Wikipedias
 
 **Synchronous**
@@ -1012,6 +1012,31 @@ The same options apply to both ``Wikipedia`` and ``AsyncWikipedia``.
         max_retries=0,
     )
 
+Custom HTTP Transport
+~~~~~~~~~~~~~~~~~~~~~~
+
+Any keyword argument that is not recognised by ``Wikipedia`` / ``AsyncWikipedia`` is
+forwarded to the underlying ``httpx`` client. This includes ``transport``, which lets you
+plug in a custom transport such as a caching transport
+(e.g. `Hishel <https://hishel.com/httpx.html>`_). When ``transport`` is omitted, the default
+``httpx.HTTPTransport`` (sync) / ``httpx.AsyncHTTPTransport`` (async) is used.
+
+.. code-block:: python
+
+    import hishel
+    import httpx
+    import wikipediaapi
+
+    # Cache responses so repeated lookups avoid hitting Wikipedia again
+    wiki_wiki = wikipediaapi.Wikipedia(
+        user_agent='MyProjectName (merlin@example.com)',
+        language='en',
+        transport=hishel.CacheTransport(transport=httpx.HTTPTransport()),
+    )
+
+For ``AsyncWikipedia`` use an async transport (e.g.
+``hishel.AsyncCacheTransport(transport=httpx.AsyncHTTPTransport())``).
+
 How To See Underlying API Call
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/README_processed.rst

@@ -56,10 +56,10 @@ Getting single page is straightforward. You have to initialize ``Wikipedia`` (or
 object and ask for page by its name.
 To initialize it, you have to provide:
 
-* `user_agent` to identify your project. Please follow the recommended `format`_.
+* `user_agent` to identify your project. **Must include contact information** (email or website) and follow the Wikimedia Foundation `User-Agent policy`_.
 * `language` to specify language mutation. It has to be one of `supported languages`_.
 
-.. _format: https://meta.wikimedia.org/wiki/User-Agent_policy
+.. _User-Agent policy: https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy
 .. _supported languages: http://meta.wikimedia.org/wiki/List_of_Wikipedias
 
 **Synchronous**
@@ -1012,6 +1012,31 @@ The same options apply to both ``Wikipedia`` and ``AsyncWikipedia``.
         max_retries=0,
     )
 
+Custom HTTP Transport
+~~~~~~~~~~~~~~~~~~~~~~
+
+Any keyword argument that is not recognised by ``Wikipedia`` / ``AsyncWikipedia`` is
+forwarded to the underlying ``httpx`` client. This includes ``transport``, which lets you
+plug in a custom transport such as a caching transport
+(e.g. `Hishel <https://hishel.com/httpx.html>`_). When ``transport`` is omitted, the default
+``httpx.HTTPTransport`` (sync) / ``httpx.AsyncHTTPTransport`` (async) is used.
+
+.. code-block:: python
+
+    import hishel
+    import httpx
+    import wikipediaapi
+
+    # Cache responses so repeated lookups avoid hitting Wikipedia again
+    wiki_wiki = wikipediaapi.Wikipedia(
+        user_agent='MyProjectName (merlin@example.com)',
+        language='en',
+        transport=hishel.CacheTransport(transport=httpx.HTTPTransport()),
+    )
+
+For ``AsyncWikipedia`` use an async transport (e.g.
+``hishel.AsyncCacheTransport(transport=httpx.AsyncHTTPTransport())``).
+
 How To See Underlying API Call
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/examples/example_async.py

@@ -28,7 +28,7 @@ from wikipediaapi import coordinates_prop2str
 # Set to INFO to see the actual API request URLs being made
 logging.basicConfig(level=logging.WARNING)
 
-user_agent = "Wikipedia-API Example (merlin@example.com)"
+user_agent = "MyCoolBot/1.0 (myemail@example.com)"
 
 
 def print_sections(sections, level=0):

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/examples/example_cli.sh

@@ -8,7 +8,7 @@
 
 set -euo pipefail
 
-USER_AGENT="Wikipedia-API Example (merlin@example.com)"
+USER_AGENT="MyCoolBot/1.0 (myemail@example.com)"
 
 # ──────────────────────────────────────────────────────────────────────────────
 # 1. Verify installation

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/examples/example_sync.py

@@ -19,7 +19,7 @@ from wikipediaapi import coordinates_prop2str
 # Set to INFO to see the actual API request URLs being made
 logging.basicConfig(level=logging.WARNING)
 
-user_agent = "Wikipedia-API Example (merlin@example.com)"
+user_agent = "MyCoolBot/1.0 (myemail@example.com)"
 
 # ──────────────────────────────────────────────────────────────────────────────
 # 1. Creating a Wikipedia client

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "Wikipedia-API"
-version = "0.14.1"
+version = "0.16.0"
 description = "Python Wrapper for Wikipedia"
 readme = {file = "README_processed.rst", content-type = "text/x-rst"}
 license = {text = "MIT"}
@@ -32,29 +32,28 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-    "click==8.3.2",
+    "click==8.5.0",
     "httpx==0.28.1",
     "tenacity==9.1.4",
 ]
 
 [dependency-groups]
 dev = [
-    "coverage==7.13.5",
-    "ruff>=0.11.0",
+    "coverage==7.14.3",
+    "ruff==0.16.5",
     "ty==0.0.27",
-    "pre-commit==4.5.1",
-    "pygments==2.20.0",
+    "pre-commit==4.6.0",
+    "pygments==2.21.0",
     "pyupgrade==3.21.2",
-    "pytest==9.0.3",
-    "pytest-asyncio==1.3.0",
+    "pytest==9.1.1",
+    "pytest-asyncio==1.4.0",
     "pytest-cov==7.1.0",
-    "tox==4.52.0",
-    "anyio[trio]==4.13.0",
+    "tox==4.56.1",
+    "anyio[trio]==4.14.2",
     "respx==0.23.1",
-    "types-setuptools==82.0.0.20260408",
-    "pytest-recording>=0.13.2",
-    "vcrpy>=6.0.0",
-    "ty>=0.0.27",
+    "types-setuptools==82.0.0.20260518",
+    "pytest-recording==0.13.4",
+    "vcrpy==8.2.1",
 ]
 doc = [
     "sphinx==9.1.0; python_version >= '3.12'",
@@ -62,11 +61,11 @@ doc = [
 build = [
     "rst2html==2020.7.4",
     "setuptools==82.0.1",
-    "twine>=6.2.0",
-    "wheel==0.46.3",
+    "twine==7.0.0",
+    "wheel==0.48.0",
 ]
 testing = [
-    "anyio[trio]==4.13.0",
+    "anyio[trio]==4.14.2",
     "respx==0.23.1",
 ]
 

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/wikipediaapi/_http_client/async_http_client.py

@@ -48,10 +48,12 @@ class AsyncHTTPClient(BaseHTTPClient):
             :class:`BaseHTTPClient`
         """
         super().__init__(*args, **kwargs)
+        # Use a caller-supplied transport (e.g. a caching transport such as
+        # Hishel) if one was passed; otherwise fall back to the default.
+        self._client_kwargs.setdefault("transport", httpx.AsyncHTTPTransport())
         self._client = httpx.AsyncClient(
             headers=self._default_headers,
             **self._client_kwargs,
-            transport=httpx.AsyncHTTPTransport(),
         )
 
     async def _do_get(self, url: str, params: dict[str, Any]) -> dict[str, Any]:

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/wikipediaapi/_http_client/base_http_client.py

@@ -96,6 +96,10 @@ class BaseHTTPClient(ABC):
         :param kwargs: forwarded to ``httpx`` client constructor
             (e.g. ``timeout=30.0``, ``proxy={'https://': 'http://proxy.example.com:8080'}``,
             ``verify=False``, ``http2=True``); ``timeout`` defaults to ``10.0``.
+            A custom ``transport`` may also be supplied (e.g. a caching
+            transport such as `Hishel <https://hishel.com/httpx.html>`_); when
+            omitted, the default ``httpx.HTTPTransport`` /
+            ``httpx.AsyncHTTPTransport`` is used.
             **Advanced Usage**: These parameters provide direct access to httpx
             capabilities.  For standard Wikipedia API usage, prefer the
             documented parameters above.  Use httpx parameters only for
@@ -116,7 +120,7 @@ class BaseHTTPClient(ABC):
             default_headers.get("User-Agent"),
         )
 
-        default_headers["User-Agent"] = used_user_agent + " (" + USER_AGENT + ")"
+        default_headers["User-Agent"] = used_user_agent + " " + USER_AGENT
 
         self.language = used_language
         self.variant = used_variant
@@ -224,7 +228,8 @@ class BaseHTTPClient(ABC):
         if not user_agent or len(user_agent) < MIN_USER_AGENT_LEN:
             raise AssertionError(
                 "Please, be nice to Wikipedia and specify user agent - "
-                + "https://meta.wikimedia.org/wiki/User-Agent_policy. Current user_agent: '"
+                + "https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_"
+                + "User-Agent_Policy. Current user_agent: '"
                 + str(user_agent)
                 + "' is not sufficient. "
                 + "Use Wikipedia(user_agent='your-user-agent', language='"

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/wikipediaapi/_http_client/sync_http_client.py

@@ -46,10 +46,12 @@ class SyncHTTPClient(BaseHTTPClient):
             :class:`BaseHTTPClient`
         """
         super().__init__(*args, **kwargs)
+        # Use a caller-supplied transport (e.g. a caching transport such as
+        # Hishel) if one was passed; otherwise fall back to the default.
+        self._client_kwargs.setdefault("transport", httpx.HTTPTransport())
         self._client = httpx.Client(
             headers=self._default_headers,
             **self._client_kwargs,
-            transport=httpx.HTTPTransport(),
         )
 
     def _do_get(self, url: str, params: dict[str, Any]) -> dict[str, Any]:

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/wikipediaapi/_version.py

@@ -1,4 +1,4 @@
 """Version information for Wikipedia-API."""
 
-__version__ = (0, 14, 1)
+__version__ = (0, 16, 0)
 __version_str__ = ".".join(str(s) for s in __version__)

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/wikipediaapi/_wikipedia/async_wikipedia.py

@@ -66,7 +66,8 @@ class AsyncWikipedia(AsyncWikipediaResource, AsyncHTTPClient):
         ``1.0``.
     :param kwargs: additional keyword arguments forwarded to
         ``httpx.AsyncClient`` (e.g. ``timeout=30.0``, ``proxies={…}``,
-        ``verify=False``).  **Advanced Usage**: These provide direct
+        ``verify=False``, or a custom ``transport`` such as a caching
+        transport).  **Advanced Usage**: These provide direct
         access to httpx capabilities.  For most use cases, prefer the
         standard parameters above.  Use httpx parameters only for specific
         requirements like custom proxies, SSL configuration, or connection pooling.

{wikipedia_api-0.14.1 → wikipedia_api-0.16.0}/wikipediaapi/_wikipedia/wikipedia.py

@@ -58,7 +58,8 @@ class Wikipedia(WikipediaResource, SyncHTTPClient):
         ``1.0``.
     :param kwargs: additional keyword arguments forwarded to
         ``httpx.Client`` (e.g. ``timeout=30.0``, ``proxies={…}``,
-        ``verify=False``).  **Advanced Usage**: These provide direct
+        ``verify=False``, or a custom ``transport`` such as a caching
+        transport).  **Advanced Usage**: These provide direct
         access to httpx capabilities.  For most use cases, prefer the
         standard parameters above.  Use httpx parameters only for specific
         requirements like custom proxies, SSL configuration, or connection pooling.

wikipedia_api-0.14.1/DEVELOPMENT.rst

@@ -1,47 +0,0 @@
-Development
-===========
-
-Prerequisites
---------------
-
-* Make
-* Python 3.10+
-* Pip
-
-Makefile targets
------------------
-* ``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/``
-* ``make release`` - creates new release as well as git tag
-
-Usage Statistics
-----------------
-
-* `PIP Downloads`_
-* `Clickpy`_
-* `Libraries.io`_
-* `Deps.dev`_
-
-.. _PIP Downloads: https://pypistats.org/packages/wikipedia-api
-.. _Libraries.io: https://libraries.io/pypi/Wikipedia-API
-.. _Deps.dev: https://deps.dev/pypi/wikipedia-api
-.. _Clickpy: https://clickpy.clickhouse.com/dashboard/wikipedia-api
-
-Underlying API
---------------
-
-* `API - HP`_
-* `Module - Parse`_
-* `Module - Query`_
-
-.. _API - HP: https://www.mediawiki.org/wiki/API:Main_page
-.. _Module - Parse: https://en.wikipedia.org/w/api.php?action=help&modules=parse
-.. _Module - Query: https://en.wikipedia.org/w/api.php?action=help&modules=query