pageviewapi 0.5.0__py3-none-any.whl

pageviewapi/__init__.py

@@ -0,0 +1,25 @@
+"""Python client for the Wikimedia Pageview API."""
+
+from pageviewapi.client import (
+    PageviewResponse,
+    ThrottlingException,
+    ZeroOrDataNotLoadedException,
+    __version__,
+    aggregate,
+    legacy_pagecounts,
+    per_article,
+    top,
+    unique_devices,
+)
+
+__all__ = [
+    "__version__",
+    "aggregate",
+    "PageviewResponse",
+    "legacy_pagecounts",
+    "per_article",
+    "ThrottlingException",
+    "top",
+    "unique_devices",
+    "ZeroOrDataNotLoadedException",
+]

pageviewapi/client.py

@@ -0,0 +1,206 @@
+"""Client to wikimedia pageview api.
+
+API doc: https://wikitech.wikimedia.org/wiki/Analytics/AQS/Pageview_API
+Supported endpoints:
+- per-article
+- top
+- aggregate
+- unique-devices
+- legacy/pagecounts
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+from urllib.parse import quote, unquote
+
+import requests
+
+try:
+    __version__ = version("pageviewapi")
+except PackageNotFoundError:
+    __version__ = "0.4.0"
+
+PROJECT_URL = "https://github.com/Commonists/pageview-api"
+USER_AGENT = {"User-Agent": f"Python pageview-api client v{__version__} <{PROJECT_URL}>"}
+
+API_BASE_URL = "https://wikimedia.org/api/rest_v1/metrics"
+
+PA_ENDPOINT = "pageviews/per-article"
+PA_ARGS = "{project}/{access}/{agent}/{page}/{granularity}/{start}/{end}"
+
+TOP_ENDPOINT = "pageviews/top"
+TOP_ARGS = "{project}/{access}/{year}/{month}/{day}"
+
+AG_ENDPOINT = "pageviews/aggregate"
+AG_ARGS = "{project}/{access}/{agent}/{granularity}/{start}/{end}"
+
+UD_ENDPOINT = "unique-devices"
+UD_ARGS = "{project}/{access}/{granularity}/{start}/{end}"
+
+PC_ENDPOINT = "legacy/pagecounts/aggregate"
+PC_ARGS = "{project}/{access_site}/{granularity}/{start}/{end}"
+
+
+class PageviewResponse(dict):  # type: ignore[type-arg]
+    """A Wikimedia Pageview API response with attribute-style read access.
+
+    Recursively wraps nested dicts and lists so the full response tree is
+    navigable via attributes. Dict data keys always take priority over built-in
+    dict methods, so ``response.items`` returns the ``items`` data value rather
+    than the ``dict.items`` method when that key is present.
+
+    Use ``from_json`` rather than the constructor directly when the input may
+    contain nested dicts or lists — the constructor only wraps the top level.
+    """
+
+    def __getattribute__(self, key: str) -> Any:
+        if not key.startswith("_"):
+            try:
+                return dict.__getitem__(self, key)
+            except KeyError:
+                pass
+        return super().__getattribute__(key)
+
+    @classmethod
+    def from_json(cls, obj: Any) -> Any:
+        """Recursively convert a JSON value into a ``PageviewResponse`` tree."""
+        if isinstance(obj, dict):
+            return cls({k: cls.from_json(v) for k, v in obj.items()})
+        if isinstance(obj, list):
+            return [cls.from_json(item) for item in obj]
+        return obj
+
+
+class ZeroOrDataNotLoadedException(Exception):
+    """Raised on 404 — no data or data not yet filled.
+
+    https://wikitech.wikimedia.org/wiki/Analytics/PageviewAPI#Gotchas
+    """
+
+
+class ThrottlingException(Exception):
+    """Raised on 429 — client is sending too many requests.
+
+    https://wikitech.wikimedia.org/wiki/Analytics/PageviewAPI#Gotchas
+    """
+
+
+def per_article(
+    project: str,
+    page: str,
+    start: str,
+    end: str,
+    access: str = "all-access",
+    agent: str = "all-agents",
+    granularity: str = "daily",
+) -> dict[str, Any]:
+    """Per-article pageview counts.
+
+    >>> import pageviewapi
+    >>> pageviewapi.per_article('en.wikipedia', 'Paris', '20151106', '20151120')
+    """
+    args = PA_ARGS.format(
+        project=project,
+        page=_quote_article_name(page),
+        start=start,
+        end=end,
+        access=access,
+        agent=agent,
+        granularity=granularity,
+    )
+    return _api(PA_ENDPOINT, args)
+
+
+def top(
+    project: str,
+    year: int | str,
+    month: int | str,
+    day: int | str,
+    access: str = "all-access",
+) -> dict[str, Any]:
+    """Top 1000 most visited articles for a project on a given date.
+
+    >>> import pageviewapi
+    >>> views = pageviewapi.top('fr.wikipedia', 2015, 11, 14)
+    >>> views['items'][0]['articles'][0]
+    {'article': 'Wikipédia:Accueil_principal', 'rank': 1, 'views': 1600547}
+    """
+    args = TOP_ARGS.format(project=project, access=access, year=year, month=month, day=day)
+    return _api(TOP_ENDPOINT, args)
+
+
+def aggregate(
+    project: str,
+    start: str,
+    end: str,
+    access: str = "all-access",
+    agent: str = "all-agents",
+    granularity: str = "daily",
+) -> dict[str, Any]:
+    """Aggregate pageview counts for a project.
+
+    >>> import pageviewapi
+    >>> pageviewapi.aggregate('fr.wikipedia', '2015100100', '2015103100')
+    """
+    args = AG_ARGS.format(
+        project=project,
+        start=start,
+        end=end,
+        access=access,
+        agent=agent,
+        granularity=granularity,
+    )
+    return _api(AG_ENDPOINT, args)
+
+
+def unique_devices(
+    project: str,
+    start: str,
+    end: str,
+    access: str = "all-access",
+    granularity: str = "daily",
+) -> dict[str, Any]:
+    """Unique devices accessing a project."""
+    args = UD_ARGS.format(project=project, start=start, end=end, access=access, granularity=granularity)
+    return _api(UD_ENDPOINT, args)
+
+
+def legacy_pagecounts(
+    project: str,
+    start: str,
+    end: str,
+    access_site: str = "all-sites",
+    granularity: str = "daily",
+) -> dict[str, Any]:
+    """Legacy pagecounts aggregate.
+
+    >>> import pageviewapi
+    >>> pageviewapi.legacy_pagecounts('fr.wikipedia', '2010010100', '2011010100')
+    """
+    project_arg = "all-projects" if project == "all-projects" else f"{project}.org"
+    args = PC_ARGS.format(
+        project=project_arg,
+        start=start,
+        end=end,
+        access_site=access_site,
+        granularity=granularity,
+    )
+    return _api(PC_ENDPOINT, args)
+
+
+def _api(end_point: str, args: str, api_url: str = API_BASE_URL) -> dict[str, Any]:
+    url = "/".join([api_url, end_point, args])
+    response = requests.get(url, headers=USER_AGENT)
+    if response.status_code == 200:
+        return PageviewResponse.from_json(response.json())
+    elif response.status_code == 404:
+        raise ZeroOrDataNotLoadedException()
+    elif response.status_code == 429:
+        raise ThrottlingException()
+    else:
+        response.raise_for_status()
+        return {}  # unreachable, satisfies type checker
+
+
+def _quote_article_name(page: str) -> str:
+    return quote(unquote(page), safe="")

pageviewapi/period.py

@@ -0,0 +1,41 @@
+"""Helper functions for aggregating pageviews over a time period."""
+
+import datetime
+
+import pageviewapi.client
+
+
+def sum_last(
+    project: str,
+    page: str,
+    last: int = 30,
+    agent: str = "all-agents",
+    access: str = "all-access",
+) -> int:
+    """Total pageviews for a page over the last N days."""
+    views = pageviewapi.client.per_article(project, page, _days_ago(last), _today(), access=access, agent=agent)
+    return sum(daily["views"] for daily in views["items"])
+
+
+def avg_last(
+    project: str,
+    page: str,
+    last: int = 30,
+    agent: str = "all-agents",
+    access: str = "all-access",
+) -> float:
+    """Average daily pageviews for a page over the last N days."""
+    views = pageviewapi.client.per_article(project, page, _days_ago(last), _today(), access=access, agent=agent)
+    return _avg([daily["views"] for daily in views["items"]])
+
+
+def _today() -> str:
+    return datetime.date.today().strftime("%Y%m%d")
+
+
+def _days_ago(days: int) -> str:
+    return (datetime.date.today() - datetime.timedelta(days=days)).strftime("%Y%m%d")
+
+
+def _avg(values: list[int | float]) -> float:
+    return sum(values) / len(values)

pageviewapi-0.5.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: pageviewapi
+Version: 0.5.0
+Summary: Wikimedia Pageview API client
+Project-URL: Homepage, https://github.com/Commonists/pageview-api
+Author-email: Commonists <ps.huard@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.0
+Description-Content-Type: text/markdown
+
+# pageview-api
+[![CI](https://github.com/Commonists/pageview-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Commonists/pageview-api/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Commonists/pageview-api/branch/master/graph/badge.svg)](https://codecov.io/gh/Commonists/pageview-api)
+[![Pypi](https://img.shields.io/pypi/v/pageviewapi.svg?style=flat)](https://pypi.python.org/pypi/pageviewapi)
+[![License](http://img.shields.io/badge/license-MIT-orange.svg?style=flat)](http://opensource.org/licenses/MIT)
+
+Wikimedia Pageview API client for Python 3.10+
+
+Installation
+------------
+In order to install system wide on system using sudo you can use:
+```sh
+pip install git+https://github.com/Commonists/pageview-api.git
+```
+
+Examples
+--------
+
+Number of view on English Wikipedia of article Paris from November 6th to November 20th 2015
+
+```python
+import pageviewapi
+pageviewapi.per_article('en.wikipedia', 'Paris', '20151106', '20151120',
+                        access='all-access', agent='all-agents', granularity='daily')
+```
+
+Aggregation: Get a daily pageview count timeseries of all projects for the month of October 2015
+```python
+import pageviewapi
+pageviewapi.aggregate('fr.wikipedia', '2015100100', '2015103100', access='all-access',
+                      agent='all-agents', granularity='daily')
+```
+
+Most viewed articles on French Wikipedia on November 14th, 2015
+```python
+import pageviewapi
+pageviewapi.top('fr.wikipedia', 2015, 11, 14, access='all-access')
+```
+
+Sum (resp. average) of view during last 30 days
+```python
+import pageviewapi.period
+pageviewapi.period.sum_last('fr.wikipedia', 'Paris', last=30,
+                            access='all-access', agent='all-agents')
+
+pageviewapi.period.avg_last('fr.wikipedia', 'Paris', last=30)
+```
+
+Monthly legacy pagecounts (2008 until end of 2016) on a project
+```python
+import pageviewapi
+pageviewapi.legacy_pagecounts('fr.wikipedia', '2010010100', '2011010100', granularity='monthly')
+```

pageviewapi-0.5.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pageviewapi/__init__.py,sha256=XQuW8nHWyAG_5DbG1w1xmBEWuciq-_hvYfllPAcSMAg,485
+pageviewapi/client.py,sha256=bDB9jZn2J3zRb9aNcrrlKPuWkOUjxTwvDCq49MC3zVk,5998
+pageviewapi/period.py,sha256=CTlTrUAGV-dS4oRFBzgEbcUxL__9aCN9d1VIMp2_xcQ,1153
+pageviewapi-0.5.0.dist-info/METADATA,sha256=bwXjOIoxJoYcD0yeU_7z1j3ErzhbXtfnxawYpnpuntU,2309
+pageviewapi-0.5.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pageviewapi-0.5.0.dist-info/licenses/LICENSE,sha256=K_ASJjZ01tNhhxFx5LTnc8GvQzALj9rsa1KihGESI0c,1078
+pageviewapi-0.5.0.dist-info/RECORD,,

pageviewapi-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pageviewapi-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Commonists
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+