pixabay-client 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,34 @@
1
+ # Publishes to PyPI when a tag like v0.1.0 is pushed. Uses PyPI Trusted Publishing: no token is stored anywhere.
2
+ # One-time setup on pypi.org: Account -> Publishing -> add a pending publisher: owner grasshopperpebbles-oss,
3
+ # repository pixabay-client, workflow publish.yml, environment pypi.
4
+ name: publish
5
+ on:
6
+ push:
7
+ tags: ["v*"]
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ - uses: actions/setup-python@v5
14
+ with:
15
+ python-version: "3.12"
16
+ - run: pip install -e ".[dev]" build
17
+ - run: pytest -q
18
+ - run: python -m build
19
+ - uses: actions/upload-artifact@v4
20
+ with:
21
+ name: dist
22
+ path: dist/
23
+ publish:
24
+ needs: build
25
+ runs-on: ubuntu-latest
26
+ environment: pypi
27
+ permissions:
28
+ id-token: write
29
+ steps:
30
+ - uses: actions/download-artifact@v4
31
+ with:
32
+ name: dist
33
+ path: dist/
34
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,16 @@
1
+ name: test
2
+ on: [push, pull_request]
3
+ jobs:
4
+ test:
5
+ runs-on: ubuntu-latest
6
+ strategy:
7
+ matrix:
8
+ python: ["3.10", "3.11", "3.12", "3.13"]
9
+ steps:
10
+ - uses: actions/checkout@v4
11
+ - uses: actions/setup-python@v5
12
+ with:
13
+ python-version: ${{ matrix.python }}
14
+ - run: pip install -e ".[dev]"
15
+ - run: pytest -q
16
+ - run: mypy
@@ -0,0 +1,8 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ .pytest_cache/
4
+ .mypy_cache/
5
+ dist/
6
+ build/
7
+ .venv/
8
+ .env
@@ -0,0 +1,7 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (unreleased)
4
+
5
+ - First release: images and videos (search, get by id, paging), sync and async clients, 24-hour cache, rate-limit
6
+ handling with retry, safe downloads from Pixabay hosts only (every redirect hop is checked too), credit lines, key redaction, `exclude_people` filter.
7
+ - The repository lives at `github.com/grasshopperpebbles-oss/pixabay-client` (moved from `grasshopperpebbles` before the first release); the package URLs and the PyPI publisher setup point there.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Les Green
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,107 @@
1
+ Metadata-Version: 2.5
2
+ Name: pixabay-client
3
+ Version: 0.1.0
4
+ Summary: A typed Pixabay API client (sync and async) that follows Pixabay's API rules for you: caching, rate limits, downloads and credit.
5
+ Project-URL: Homepage, https://github.com/grasshopperpebbles-oss/pixabay-client
6
+ Project-URL: Source, https://github.com/grasshopperpebbles-oss/pixabay-client
7
+ Project-URL: Issues, https://github.com/grasshopperpebbles-oss/pixabay-client/issues
8
+ Author: Les Green
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: api,async,client,images,pixabay,stock photos
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: httpx<1,>=0.27
23
+ Provides-Extra: dev
24
+ Requires-Dist: mypy>=1.11; extra == 'dev'
25
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
26
+ Requires-Dist: pytest>=8; extra == 'dev'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # pixabay-client
30
+
31
+ A typed Python client for the [Pixabay API](https://pixabay.com/api/docs/), sync and async, that **follows
32
+ Pixabay's API rules for you**:
33
+
34
+ - **Caching:** Pixabay asks that requests be cached for 24 hours. Results are cached in memory for 24 hours by
35
+ default (bring your own cache, or turn it off).
36
+ - **Rate limits:** reads `X-RateLimit-*` headers, waits when the window is used up, and retries a `429` after the
37
+ reset time.
38
+ - **No hotlinking:** Pixabay forbids permanent hotlinking. `download()` saves the picture for you, and only ever
39
+ fetches from Pixabay's own hosts, including after redirects.
40
+ - **Credit:** `image.credit` / `image.credit_html` give the "where it's from" line Pixabay asks you to show.
41
+ - **Your key stays private:** never in `repr`, error messages or logs (httpx's request log line is redacted).
42
+ - **Safe by default:** `safesearch` is on unless you turn it off; optional `exclude_people=True` drops hits
43
+ tagged with people.
44
+ - Images **and** videos, typed results (`py.typed`), Python 3.10+, one dependency (`httpx`).
45
+
46
+ ```bash
47
+ pip install pixabay-client
48
+ ```
49
+
50
+ ## Use
51
+
52
+ ```python
53
+ from pixabay_client import PixabayClient
54
+
55
+ with PixabayClient("YOUR_KEY") as px: # or set PIXABAY_API_KEY
56
+ result = px.search_images("tabby cat", image_type="photo", per_page=20)
57
+ for img in result.hits:
58
+ print(img.id, img.tags, img.webformat.url, img.credit)
59
+
60
+ img = px.get_image(result.hits[0].id)
61
+ px.download(img, dest="cat.jpg") # size: "large" (default), "webformat" or "preview"
62
+
63
+ for img in px.iter_images("fox", max_results=100): # pages for you
64
+ ...
65
+
66
+ videos = px.search_videos("waves", video_type="film")
67
+ clip = videos.hits[0].renditions["medium"] # large / medium / small / tiny (missing ones left out)
68
+ ```
69
+
70
+ Async:
71
+
72
+ ```python
73
+ from pixabay_client import AsyncPixabayClient
74
+
75
+ async with AsyncPixabayClient() as px:
76
+ result = await px.search_images("owl")
77
+ data = await px.download(result.hits[0])
78
+ ```
79
+
80
+ ### Errors
81
+
82
+ | Exception | When |
83
+ |---|---|
84
+ | `AuthError` | missing or invalid API key |
85
+ | `NotFound` | `get_image` / `get_video` with an id Pixabay does not have |
86
+ | `RateLimited` | still rate limited after the retries (`retries=2` by default) |
87
+ | `ServiceError` | Pixabay answered 5xx or could not be reached |
88
+ | `PixabayError` | base class; any other error |
89
+
90
+ ### Options
91
+
92
+ `PixabayClient(key=None, *, cache=MemoryCache(), cache_ttl=86400, retries=2, max_wait=60, timeout=20,
93
+ transport=None)`. `cache=None` turns caching off; any object with `get(key)` / `set(key, value, ttl)` works as a
94
+ cache (Redis, disk…). Waits longer than `max_wait` seconds raise `RateLimited` instead of sleeping.
95
+
96
+ ## Pixabay's terms
97
+
98
+ You need a free API key from [pixabay.com/api/docs](https://pixabay.com/api/docs/). The API is for real human
99
+ requests: no systematic mass downloads. Show your users where pictures come from. Read the
100
+ [Pixabay content license](https://pixabay.com/service/license-summary/): depicted people, trademarks and
101
+ privacy rights can still apply to a picture.
102
+
103
+ Not affiliated with Pixabay.
104
+
105
+ ## License
106
+
107
+ MIT
@@ -0,0 +1,79 @@
1
+ # pixabay-client
2
+
3
+ A typed Python client for the [Pixabay API](https://pixabay.com/api/docs/), sync and async, that **follows
4
+ Pixabay's API rules for you**:
5
+
6
+ - **Caching:** Pixabay asks that requests be cached for 24 hours. Results are cached in memory for 24 hours by
7
+ default (bring your own cache, or turn it off).
8
+ - **Rate limits:** reads `X-RateLimit-*` headers, waits when the window is used up, and retries a `429` after the
9
+ reset time.
10
+ - **No hotlinking:** Pixabay forbids permanent hotlinking. `download()` saves the picture for you, and only ever
11
+ fetches from Pixabay's own hosts, including after redirects.
12
+ - **Credit:** `image.credit` / `image.credit_html` give the "where it's from" line Pixabay asks you to show.
13
+ - **Your key stays private:** never in `repr`, error messages or logs (httpx's request log line is redacted).
14
+ - **Safe by default:** `safesearch` is on unless you turn it off; optional `exclude_people=True` drops hits
15
+ tagged with people.
16
+ - Images **and** videos, typed results (`py.typed`), Python 3.10+, one dependency (`httpx`).
17
+
18
+ ```bash
19
+ pip install pixabay-client
20
+ ```
21
+
22
+ ## Use
23
+
24
+ ```python
25
+ from pixabay_client import PixabayClient
26
+
27
+ with PixabayClient("YOUR_KEY") as px: # or set PIXABAY_API_KEY
28
+ result = px.search_images("tabby cat", image_type="photo", per_page=20)
29
+ for img in result.hits:
30
+ print(img.id, img.tags, img.webformat.url, img.credit)
31
+
32
+ img = px.get_image(result.hits[0].id)
33
+ px.download(img, dest="cat.jpg") # size: "large" (default), "webformat" or "preview"
34
+
35
+ for img in px.iter_images("fox", max_results=100): # pages for you
36
+ ...
37
+
38
+ videos = px.search_videos("waves", video_type="film")
39
+ clip = videos.hits[0].renditions["medium"] # large / medium / small / tiny (missing ones left out)
40
+ ```
41
+
42
+ Async:
43
+
44
+ ```python
45
+ from pixabay_client import AsyncPixabayClient
46
+
47
+ async with AsyncPixabayClient() as px:
48
+ result = await px.search_images("owl")
49
+ data = await px.download(result.hits[0])
50
+ ```
51
+
52
+ ### Errors
53
+
54
+ | Exception | When |
55
+ |---|---|
56
+ | `AuthError` | missing or invalid API key |
57
+ | `NotFound` | `get_image` / `get_video` with an id Pixabay does not have |
58
+ | `RateLimited` | still rate limited after the retries (`retries=2` by default) |
59
+ | `ServiceError` | Pixabay answered 5xx or could not be reached |
60
+ | `PixabayError` | base class; any other error |
61
+
62
+ ### Options
63
+
64
+ `PixabayClient(key=None, *, cache=MemoryCache(), cache_ttl=86400, retries=2, max_wait=60, timeout=20,
65
+ transport=None)`. `cache=None` turns caching off; any object with `get(key)` / `set(key, value, ttl)` works as a
66
+ cache (Redis, disk…). Waits longer than `max_wait` seconds raise `RateLimited` instead of sleeping.
67
+
68
+ ## Pixabay's terms
69
+
70
+ You need a free API key from [pixabay.com/api/docs](https://pixabay.com/api/docs/). The API is for real human
71
+ requests: no systematic mass downloads. Show your users where pictures come from. Read the
72
+ [Pixabay content license](https://pixabay.com/service/license-summary/): depicted people, trademarks and
73
+ privacy rights can still apply to a picture.
74
+
75
+ Not affiliated with Pixabay.
76
+
77
+ ## License
78
+
79
+ MIT
@@ -0,0 +1,46 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.25"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "pixabay-client"
7
+ version = "0.1.0"
8
+ description = "A typed Pixabay API client (sync and async) that follows Pixabay's API rules for you: caching, rate limits, downloads and credit."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Les Green" }]
13
+ requires-python = ">=3.10"
14
+ dependencies = ["httpx>=0.27,<1"]
15
+ keywords = ["pixabay", "images", "stock photos", "api", "client", "async"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Typing :: Typed",
25
+ "Framework :: AsyncIO",
26
+ ]
27
+
28
+ [project.urls]
29
+ Homepage = "https://github.com/grasshopperpebbles-oss/pixabay-client"
30
+ Source = "https://github.com/grasshopperpebbles-oss/pixabay-client"
31
+ Issues = "https://github.com/grasshopperpebbles-oss/pixabay-client/issues"
32
+
33
+ [project.optional-dependencies]
34
+ dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.11"]
35
+
36
+ [tool.hatch.build.targets.wheel]
37
+ packages = ["src/pixabay_client"]
38
+
39
+ [tool.pytest.ini_options]
40
+ asyncio_mode = "auto"
41
+ asyncio_default_fixture_loop_scope = "function"
42
+ testpaths = ["tests"]
43
+
44
+ [tool.mypy]
45
+ strict = true
46
+ files = ["src"]
@@ -0,0 +1,11 @@
1
+ """pixabay-client: a typed Pixabay API client that follows Pixabay's API rules for you."""
2
+ from ._core import Cache, MemoryCache
3
+ from .client import AsyncPixabayClient, PixabayClient
4
+ from .errors import AuthError, NotFound, PixabayError, RateLimited, ServiceError
5
+ from .models import Image, RateLimit, Rendition, SearchResult, Video, VideoRendition
6
+
7
+ __all__ = [
8
+ "AsyncPixabayClient", "AuthError", "Cache", "Image", "MemoryCache", "NotFound", "PixabayClient", "PixabayError",
9
+ "RateLimit", "RateLimited", "Rendition", "SearchResult", "ServiceError", "Video", "VideoRendition",
10
+ ]
11
+ __version__ = "0.1.0"
@@ -0,0 +1,214 @@
1
+ """What the sync and async clients share: parameters, the cache, rate limits, errors and key redaction."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import logging
6
+ import os
7
+ import re
8
+ import threading
9
+ import time
10
+ from collections.abc import Callable, Iterable, Mapping
11
+ from typing import Any, Literal, Protocol
12
+
13
+ import httpx
14
+
15
+ from .errors import AuthError, NotFound, PixabayError, RateLimited, ServiceError
16
+ from .models import Image, RateLimit, SearchResult, Video
17
+
18
+ API = "https://pixabay.com/api/"
19
+ VIDEO_API = "https://pixabay.com/api/videos/"
20
+ DAY = 24 * 3600
21
+ DOWNLOAD_HOSTS = ("pixabay.com", "cdn.pixabay.com")
22
+ Size = Literal["large", "webformat", "preview"]
23
+
24
+ # Tags that mark a hit as showing people (exclude_people=True). A tag match, not a guarantee.
25
+ PEOPLE_TAGS = frozenset({
26
+ "people", "person", "man", "woman", "men", "women", "girl", "girls", "boy", "boys", "child", "children", "kid",
27
+ "kids", "baby", "human", "humans", "lady", "guy", "couple", "family", "model", "teen", "teenager", "adult",
28
+ })
29
+
30
+
31
+ class Cache(Protocol):
32
+ def get(self, key: str) -> Any | None: ...
33
+ def set(self, key: str, value: Any, ttl: float) -> None: ...
34
+
35
+
36
+ class MemoryCache:
37
+ """A small thread-safe in-memory TTL cache (the default)."""
38
+
39
+ def __init__(self, max_items: int = 1000, clock: Callable[[], float] = time.monotonic) -> None:
40
+ self._items: dict[str, tuple[float, Any]] = {}
41
+ self._max = max_items
42
+ self._clock = clock
43
+ self._lock = threading.Lock()
44
+
45
+ def get(self, key: str) -> Any | None:
46
+ with self._lock:
47
+ item = self._items.get(key)
48
+ if item is None:
49
+ return None
50
+ if item[0] <= self._clock():
51
+ del self._items[key]
52
+ return None
53
+ return item[1]
54
+
55
+ def set(self, key: str, value: Any, ttl: float) -> None:
56
+ with self._lock:
57
+ if len(self._items) >= self._max:
58
+ self._items.pop(next(iter(self._items))) # the oldest
59
+ self._items[key] = (self._clock() + ttl, value)
60
+
61
+
62
+ class _RedactKey(logging.Filter):
63
+ _key = re.compile(r"([?&]key=)[^&\s'\"]+")
64
+
65
+ def filter(self, record: logging.LogRecord) -> bool:
66
+ if record.args:
67
+ record.msg = record.getMessage()
68
+ record.args = None
69
+ if isinstance(record.msg, str):
70
+ record.msg = self._key.sub(r"\1***", record.msg)
71
+ return True
72
+
73
+
74
+ def install_log_redaction() -> None:
75
+ """httpx logs every request URL, and Pixabay wants the key in the URL: redact it (once per logger)."""
76
+ for name in ("httpx", "httpcore"):
77
+ logger = logging.getLogger(name)
78
+ if not any(isinstance(f, _RedactKey) for f in logger.filters):
79
+ logger.addFilter(_RedactKey())
80
+
81
+
82
+ def resolve_key(key: str | None) -> str:
83
+ key = key or os.environ.get("PIXABAY_API_KEY", "")
84
+ if not key:
85
+ raise AuthError("No Pixabay API key: pass one or set PIXABAY_API_KEY.")
86
+ return key
87
+
88
+
89
+ def _flag(v: bool) -> str:
90
+ return "true" if v else "false"
91
+
92
+
93
+ def image_params(q: str | None, *, lang: str, image_type: str, orientation: str, category: str | None,
94
+ min_width: int, min_height: int, colors: Iterable[str] | None, editors_choice: bool,
95
+ safesearch: bool, order: str, page: int, per_page: int) -> dict[str, str]:
96
+ p = _shared(q, lang=lang, category=category, min_width=min_width, min_height=min_height,
97
+ editors_choice=editors_choice, safesearch=safesearch, order=order, page=page, per_page=per_page)
98
+ p.update(image_type=image_type, orientation=orientation)
99
+ if colors:
100
+ p["colors"] = ",".join(colors)
101
+ return p
102
+
103
+
104
+ def video_params(q: str | None, *, lang: str, video_type: str, category: str | None, min_width: int,
105
+ min_height: int, editors_choice: bool, safesearch: bool, order: str, page: int,
106
+ per_page: int) -> dict[str, str]:
107
+ p = _shared(q, lang=lang, category=category, min_width=min_width, min_height=min_height,
108
+ editors_choice=editors_choice, safesearch=safesearch, order=order, page=page, per_page=per_page)
109
+ p["video_type"] = video_type
110
+ return p
111
+
112
+
113
+ def _shared(q: str | None, *, lang: str, category: str | None, min_width: int, min_height: int,
114
+ editors_choice: bool, safesearch: bool, order: str, page: int, per_page: int) -> dict[str, str]:
115
+ if q is not None and len(q) > 100:
116
+ raise ValueError("Pixabay search terms are at most 100 characters.")
117
+ if not 3 <= per_page <= 200:
118
+ raise ValueError("per_page must be between 3 and 200.")
119
+ if page < 1:
120
+ raise ValueError("page starts at 1.")
121
+ p = {"lang": lang, "min_width": str(min_width), "min_height": str(min_height),
122
+ "editors_choice": _flag(editors_choice), "safesearch": _flag(safesearch), "order": order,
123
+ "page": str(page), "per_page": str(per_page)}
124
+ if q:
125
+ p["q"] = q
126
+ if category:
127
+ p["category"] = category
128
+ return p
129
+
130
+
131
+ def cache_key(url: str, params: Mapping[str, str]) -> str:
132
+ return url + "?" + "&".join(f"{k}={params[k]}" for k in sorted(params)) # the API key is never part of it
133
+
134
+
135
+ def check(response: httpx.Response) -> Any:
136
+ """The JSON body of a good answer; else the matching error (Pixabay answers errors in plain text)."""
137
+ if response.status_code == 200:
138
+ try:
139
+ return response.json()
140
+ except json.JSONDecodeError as e:
141
+ raise ServiceError("Pixabay sent an answer that is not JSON.") from e
142
+ text = response.text.strip()[:200]
143
+ if response.status_code == 429:
144
+ raise RateLimited("Pixabay rate limit exceeded.", retry_after=reset_seconds(response))
145
+ if response.status_code >= 500:
146
+ raise ServiceError(f"Pixabay error {response.status_code}.")
147
+ low = text.lower()
148
+ if "api key" in low:
149
+ raise AuthError("Invalid or missing Pixabay API key.")
150
+ # Live 2026-11-09: "[ERROR 400] Image #N does not exist." (older answers said "out of valid range").
151
+ if "does not exist" in low or "out of valid range" in low:
152
+ raise NotFound("Pixabay has no item with that id.")
153
+ raise PixabayError(f"Pixabay error {response.status_code}: {_scrub(text)}")
154
+
155
+
156
+ def _scrub(text: str) -> str:
157
+ return re.sub(r"key=[^&\s]+", "key=***", text)
158
+
159
+
160
+ def reset_seconds(response: httpx.Response) -> float:
161
+ try:
162
+ return max(0.0, float(response.headers.get("X-RateLimit-Reset", "60")))
163
+ except ValueError:
164
+ return 60.0
165
+
166
+
167
+ def read_rate_limit(response: httpx.Response, now: float) -> RateLimit | None:
168
+ h = response.headers
169
+ if "X-RateLimit-Remaining" not in h:
170
+ return None
171
+ try:
172
+ return RateLimit(int(h.get("X-RateLimit-Limit", "0")), int(h["X-RateLimit-Remaining"]),
173
+ now + reset_seconds(response))
174
+ except ValueError:
175
+ return None
176
+
177
+
178
+ def _parse(make: Callable[[dict[str, Any]], Any], raw: Any) -> list[Any]:
179
+ """Each hit that reads cleanly; one malformed hit is skipped, not fatal to the whole answer."""
180
+ out = []
181
+ for h in raw if isinstance(raw, list) else []:
182
+ try:
183
+ out.append(make(h))
184
+ except (KeyError, TypeError, ValueError, AttributeError):
185
+ continue
186
+ return out
187
+
188
+
189
+ def images_result(data: dict[str, Any], page: int, per_page: int, exclude_people: bool) -> SearchResult[Image]:
190
+ hits: list[Image] = _parse(Image.from_api, data.get("hits"))
191
+ if exclude_people:
192
+ hits = [h for h in hits if not PEOPLE_TAGS.intersection(t.lower() for t in h.tags)]
193
+ return SearchResult(int(data.get("total", 0)), int(data.get("totalHits", 0)), hits, page, per_page)
194
+
195
+
196
+ def videos_result(data: dict[str, Any], page: int, per_page: int) -> SearchResult[Video]:
197
+ return SearchResult(int(data.get("total", 0)), int(data.get("totalHits", 0)),
198
+ _parse(Video.from_api, data.get("hits")), page, per_page)
199
+
200
+
201
+ MAX_DOWNLOAD_REDIRECTS = 5
202
+
203
+
204
+ def check_download_url(url: str | httpx.URL) -> httpx.URL:
205
+ """The URL, if it is https on one of Pixabay's own hosts; else ValueError. Checked before every hop."""
206
+ u = httpx.URL(str(url)) if url else httpx.URL("")
207
+ if u.scheme != "https" or u.host not in DOWNLOAD_HOSTS:
208
+ raise ValueError("Downloads come only from Pixabay's own hosts over https.")
209
+ return u
210
+
211
+
212
+ def download_url(item: Image, size: Size) -> str:
213
+ url = {"large": item.large, "webformat": item.webformat, "preview": item.preview}[size].url
214
+ return str(check_download_url(url))
@@ -0,0 +1,280 @@
1
+ """The sync and async clients. Same methods, same rules; the async one awaits."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import time
6
+ from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Iterator
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ import httpx
11
+
12
+ from . import _core
13
+ from ._core import API, DAY, VIDEO_API, Cache, MemoryCache, Size
14
+ from .errors import NotFound, RateLimited, ServiceError
15
+ from .models import Image, RateLimit, SearchResult, Video
16
+
17
+ _UNSET: Any = object()
18
+
19
+
20
+ class _Base:
21
+ def __init__(self, key: str | None, cache: Cache | None, cache_ttl: float, retries: int, max_wait: float,
22
+ clock: Callable[[], float]) -> None:
23
+ self._key = _core.resolve_key(key)
24
+ self._cache: Cache | None = MemoryCache() if cache is _UNSET else cache
25
+ self._ttl = cache_ttl
26
+ self._retries = retries
27
+ self._max_wait = max_wait
28
+ self._clock = clock
29
+ self.rate_limit: RateLimit | None = None
30
+ _core.install_log_redaction()
31
+
32
+ def __repr__(self) -> str:
33
+ return f"{type(self).__name__}(key=***)"
34
+
35
+ def _wait_before(self) -> float:
36
+ """Seconds to wait before the next call: the window is used up and has not reset yet."""
37
+ rl = self.rate_limit
38
+ if rl is None or rl.remaining > 0:
39
+ return 0.0
40
+ return max(0.0, rl.reset_at - self._clock())
41
+
42
+ def _too_long(self, wait: float) -> None:
43
+ if wait > self._max_wait:
44
+ raise RateLimited(f"Pixabay rate limit: the wait ({wait:.0f} s) is longer than max_wait.", wait)
45
+
46
+ def _cached(self, url: str, params: dict[str, str]) -> tuple[str, Any | None]:
47
+ key = _core.cache_key(url, params)
48
+ return key, (self._cache.get(key) if self._cache is not None else None)
49
+
50
+ def _store(self, key: str, data: Any) -> None:
51
+ if self._cache is not None:
52
+ self._cache.set(key, data, self._ttl)
53
+
54
+
55
+ class PixabayClient(_Base):
56
+ """Pixabay API client. `key` defaults to the PIXABAY_API_KEY environment variable."""
57
+
58
+ def __init__(self, key: str | None = None, *, cache: Cache | None = _UNSET, cache_ttl: float = DAY,
59
+ retries: int = 2, max_wait: float = 60.0, timeout: float = 20.0,
60
+ transport: httpx.BaseTransport | None = None, sleep: Callable[[float], None] = time.sleep,
61
+ clock: Callable[[], float] = time.monotonic) -> None:
62
+ super().__init__(key, cache, cache_ttl, retries, max_wait, clock)
63
+ self._http = httpx.Client(timeout=timeout, transport=transport, follow_redirects=True)
64
+ self._sleep = sleep
65
+
66
+ def __enter__(self) -> PixabayClient:
67
+ return self
68
+
69
+ def __exit__(self, *exc: object) -> None:
70
+ self.close()
71
+
72
+ def close(self) -> None:
73
+ self._http.close()
74
+
75
+ def _get(self, url: str, params: dict[str, str]) -> Any:
76
+ key, hit = self._cached(url, params)
77
+ if hit is not None:
78
+ return hit
79
+ for attempt in range(self._retries + 1):
80
+ wait = self._wait_before()
81
+ if wait:
82
+ self._too_long(wait)
83
+ self._sleep(wait)
84
+ try:
85
+ response = self._http.get(url, params={**params, "key": self._key})
86
+ except httpx.HTTPError as e:
87
+ raise ServiceError(f"Pixabay could not be reached ({type(e).__name__}).") from None
88
+ self.rate_limit = _core.read_rate_limit(response, self._clock()) or self.rate_limit
89
+ try:
90
+ data = _core.check(response)
91
+ except RateLimited as e:
92
+ if attempt == self._retries:
93
+ raise
94
+ self._too_long(e.retry_after)
95
+ self._sleep(e.retry_after)
96
+ continue
97
+ self._store(key, data)
98
+ return data
99
+ raise AssertionError("unreachable")
100
+
101
+ def search_images(self, q: str | None = None, *, lang: str = "en", image_type: str = "all",
102
+ orientation: str = "all", category: str | None = None, min_width: int = 0, min_height: int = 0,
103
+ colors: Iterable[str] | None = None, editors_choice: bool = False, safesearch: bool = True,
104
+ order: str = "popular", page: int = 1, per_page: int = 20,
105
+ exclude_people: bool = False) -> SearchResult[Image]:
106
+ params = _core.image_params(q, lang=lang, image_type=image_type, orientation=orientation, category=category,
107
+ min_width=min_width, min_height=min_height, colors=colors,
108
+ editors_choice=editors_choice, safesearch=safesearch, order=order, page=page,
109
+ per_page=per_page)
110
+ return _core.images_result(self._get(API, params), page, per_page, exclude_people)
111
+
112
+ def iter_images(self, q: str | None = None, *, max_results: int = 100, per_page: int = 50,
113
+ **kwargs: Any) -> Iterator[Image]:
114
+ """Every hit, page after page, up to max_results (and Pixabay's own cap)."""
115
+ seen, page = 0, 1
116
+ while seen < max_results:
117
+ res = self.search_images(q, page=page, per_page=per_page, **kwargs)
118
+ for hit in res.hits:
119
+ if seen == max_results:
120
+ return
121
+ seen += 1
122
+ yield hit
123
+ if not res.hits or page * per_page >= res.total_hits:
124
+ return
125
+ page += 1
126
+
127
+ def get_image(self, image_id: int) -> Image:
128
+ data = self._get(API, {"id": str(image_id)})
129
+ hits = _core.images_result(data, 1, 1, False).hits
130
+ return hits[0] if hits else _not_found()
131
+
132
+ def search_videos(self, q: str | None = None, *, lang: str = "en", video_type: str = "all",
133
+ category: str | None = None, min_width: int = 0, min_height: int = 0,
134
+ editors_choice: bool = False, safesearch: bool = True, order: str = "popular", page: int = 1,
135
+ per_page: int = 20) -> SearchResult[Video]:
136
+ params = _core.video_params(q, lang=lang, video_type=video_type, category=category, min_width=min_width,
137
+ min_height=min_height, editors_choice=editors_choice, safesearch=safesearch,
138
+ order=order, page=page, per_page=per_page)
139
+ return _core.videos_result(self._get(VIDEO_API, params), page, per_page)
140
+
141
+ def get_video(self, video_id: int) -> Video:
142
+ data = self._get(VIDEO_API, {"id": str(video_id)})
143
+ hits = _core.videos_result(data, 1, 1).hits
144
+ return hits[0] if hits else _not_found()
145
+
146
+ def download(self, image: Image, *, size: Size = "large", dest: str | Path | None = None) -> Any:
147
+ """The picture's bytes, or with `dest` saved there (returns the Path). Pixabay forbids permanent
148
+ hotlinking: download what you keep."""
149
+ url = httpx.URL(_core.download_url(image, size))
150
+ try:
151
+ for _ in range(_core.MAX_DOWNLOAD_REDIRECTS + 1):
152
+ response = self._http.get(url, follow_redirects=False)
153
+ if not response.is_redirect:
154
+ break
155
+ url = _core.check_download_url(response.next_request.url if response.next_request else "")
156
+ else:
157
+ raise ServiceError("The download redirected too many times.")
158
+ response.raise_for_status()
159
+ except httpx.HTTPError as e:
160
+ raise ServiceError(f"The download failed ({type(e).__name__}).") from None
161
+ return _save(response.content, dest)
162
+
163
+
164
+ class AsyncPixabayClient(_Base):
165
+ """The async twin of PixabayClient."""
166
+
167
+ def __init__(self, key: str | None = None, *, cache: Cache | None = _UNSET, cache_ttl: float = DAY,
168
+ retries: int = 2, max_wait: float = 60.0, timeout: float = 20.0,
169
+ transport: httpx.AsyncBaseTransport | None = None,
170
+ sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
171
+ clock: Callable[[], float] = time.monotonic) -> None:
172
+ super().__init__(key, cache, cache_ttl, retries, max_wait, clock)
173
+ self._http = httpx.AsyncClient(timeout=timeout, transport=transport, follow_redirects=True)
174
+ self._sleep = sleep
175
+
176
+ async def __aenter__(self) -> AsyncPixabayClient:
177
+ return self
178
+
179
+ async def __aexit__(self, *exc: object) -> None:
180
+ await self.close()
181
+
182
+ async def close(self) -> None:
183
+ await self._http.aclose()
184
+
185
+ async def _get(self, url: str, params: dict[str, str]) -> Any:
186
+ key, hit = self._cached(url, params)
187
+ if hit is not None:
188
+ return hit
189
+ for attempt in range(self._retries + 1):
190
+ wait = self._wait_before()
191
+ if wait:
192
+ self._too_long(wait)
193
+ await self._sleep(wait)
194
+ try:
195
+ response = await self._http.get(url, params={**params, "key": self._key})
196
+ except httpx.HTTPError as e:
197
+ raise ServiceError(f"Pixabay could not be reached ({type(e).__name__}).") from None
198
+ self.rate_limit = _core.read_rate_limit(response, self._clock()) or self.rate_limit
199
+ try:
200
+ data = _core.check(response)
201
+ except RateLimited as e:
202
+ if attempt == self._retries:
203
+ raise
204
+ self._too_long(e.retry_after)
205
+ await self._sleep(e.retry_after)
206
+ continue
207
+ self._store(key, data)
208
+ return data
209
+ raise AssertionError("unreachable")
210
+
211
+ async def search_images(self, q: str | None = None, *, lang: str = "en", image_type: str = "all",
212
+ orientation: str = "all", category: str | None = None, min_width: int = 0,
213
+ min_height: int = 0, colors: Iterable[str] | None = None, editors_choice: bool = False,
214
+ safesearch: bool = True, order: str = "popular", page: int = 1, per_page: int = 20,
215
+ exclude_people: bool = False) -> SearchResult[Image]:
216
+ params = _core.image_params(q, lang=lang, image_type=image_type, orientation=orientation, category=category,
217
+ min_width=min_width, min_height=min_height, colors=colors,
218
+ editors_choice=editors_choice, safesearch=safesearch, order=order, page=page,
219
+ per_page=per_page)
220
+ return _core.images_result(await self._get(API, params), page, per_page, exclude_people)
221
+
222
+ async def iter_images(self, q: str | None = None, *, max_results: int = 100, per_page: int = 50,
223
+ **kwargs: Any) -> AsyncIterator[Image]:
224
+ seen, page = 0, 1
225
+ while seen < max_results:
226
+ res = await self.search_images(q, page=page, per_page=per_page, **kwargs)
227
+ for hit in res.hits:
228
+ if seen == max_results:
229
+ return
230
+ seen += 1
231
+ yield hit
232
+ if not res.hits or page * per_page >= res.total_hits:
233
+ return
234
+ page += 1
235
+
236
+ async def get_image(self, image_id: int) -> Image:
237
+ data = await self._get(API, {"id": str(image_id)})
238
+ hits = _core.images_result(data, 1, 1, False).hits
239
+ return hits[0] if hits else _not_found()
240
+
241
+ async def search_videos(self, q: str | None = None, *, lang: str = "en", video_type: str = "all",
242
+ category: str | None = None, min_width: int = 0, min_height: int = 0,
243
+ editors_choice: bool = False, safesearch: bool = True, order: str = "popular",
244
+ page: int = 1, per_page: int = 20) -> SearchResult[Video]:
245
+ params = _core.video_params(q, lang=lang, video_type=video_type, category=category, min_width=min_width,
246
+ min_height=min_height, editors_choice=editors_choice, safesearch=safesearch,
247
+ order=order, page=page, per_page=per_page)
248
+ return _core.videos_result(await self._get(VIDEO_API, params), page, per_page)
249
+
250
+ async def get_video(self, video_id: int) -> Video:
251
+ data = await self._get(VIDEO_API, {"id": str(video_id)})
252
+ hits = _core.videos_result(data, 1, 1).hits
253
+ return hits[0] if hits else _not_found()
254
+
255
+ async def download(self, image: Image, *, size: Size = "large", dest: str | Path | None = None) -> Any:
256
+ url = httpx.URL(_core.download_url(image, size))
257
+ try:
258
+ for _ in range(_core.MAX_DOWNLOAD_REDIRECTS + 1):
259
+ response = await self._http.get(url, follow_redirects=False)
260
+ if not response.is_redirect:
261
+ break
262
+ url = _core.check_download_url(response.next_request.url if response.next_request else "")
263
+ else:
264
+ raise ServiceError("The download redirected too many times.")
265
+ response.raise_for_status()
266
+ except httpx.HTTPError as e:
267
+ raise ServiceError(f"The download failed ({type(e).__name__}).") from None
268
+ return _save(response.content, dest)
269
+
270
+
271
+ def _not_found() -> Any:
272
+ raise NotFound("Pixabay has no item with that id.")
273
+
274
+
275
+ def _save(content: bytes, dest: str | Path | None) -> bytes | Path:
276
+ if dest is None:
277
+ return content
278
+ path = Path(dest)
279
+ path.write_bytes(content)
280
+ return path
@@ -0,0 +1,26 @@
1
+ """Errors. Messages never contain the API key."""
2
+ from __future__ import annotations
3
+
4
+
5
+ class PixabayError(Exception):
6
+ """Base class for every error this client raises."""
7
+
8
+
9
+ class AuthError(PixabayError):
10
+ """The API key is missing or invalid."""
11
+
12
+
13
+ class NotFound(PixabayError):
14
+ """No image or video with that id."""
15
+
16
+
17
+ class RateLimited(PixabayError):
18
+ """Still rate limited after the retries (or the wait would exceed max_wait)."""
19
+
20
+ def __init__(self, message: str, retry_after: float = 60.0) -> None:
21
+ super().__init__(message)
22
+ self.retry_after = retry_after
23
+
24
+
25
+ class ServiceError(PixabayError):
26
+ """Pixabay answered 5xx, sent something unreadable, or could not be reached."""
@@ -0,0 +1,128 @@
1
+ """Typed Pixabay results."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass, field
5
+ from html import escape
6
+ from typing import Any, Generic, TypeVar
7
+ from urllib.parse import quote
8
+
9
+ T = TypeVar("T")
10
+
11
+
12
+ def _tags(raw: str) -> tuple[str, ...]:
13
+ return tuple(t.strip() for t in raw.split(",") if t.strip())
14
+
15
+
16
+ def _user_url(user: str, user_id: int) -> str:
17
+ return f"https://pixabay.com/users/{quote(user)}-{user_id}/"
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class Rendition:
22
+ url: str
23
+ width: int
24
+ height: int
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class VideoRendition(Rendition):
29
+ size: int
30
+ thumbnail: str
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class _Hit:
35
+ id: int
36
+ page_url: str
37
+ type: str
38
+ tags: tuple[str, ...]
39
+ views: int
40
+ downloads: int
41
+ likes: int
42
+ comments: int
43
+ user: str
44
+ user_id: int
45
+ user_image_url: str
46
+
47
+ _noun = "Image"
48
+
49
+ @property
50
+ def user_url(self) -> str:
51
+ return _user_url(self.user, self.user_id)
52
+
53
+ @property
54
+ def credit(self) -> str:
55
+ """The plain "where it's from" line Pixabay asks you to show."""
56
+ return f"{self._noun} by {self.user} from Pixabay"
57
+
58
+ @property
59
+ def credit_html(self) -> str:
60
+ """The credit as HTML links (to the author and to the picture's Pixabay page), safely escaped."""
61
+ return (f'{self._noun} by <a href="{escape(self.user_url)}">{escape(self.user)}</a> from '
62
+ f'<a href="{escape(self.page_url)}">Pixabay</a>')
63
+
64
+
65
+ def _common(d: dict[str, Any]) -> dict[str, Any]:
66
+ return {
67
+ "id": int(d["id"]), "page_url": d.get("pageURL", ""), "type": d.get("type", ""),
68
+ "tags": _tags(d.get("tags", "")), "views": int(d.get("views", 0)), "downloads": int(d.get("downloads", 0)),
69
+ "likes": int(d.get("likes", 0)), "comments": int(d.get("comments", 0)), "user": d.get("user", ""),
70
+ "user_id": int(d.get("user_id", 0)), "user_image_url": d.get("userImageURL", ""),
71
+ }
72
+
73
+
74
+ @dataclass(frozen=True)
75
+ class Image(_Hit):
76
+ preview: Rendition = field(default_factory=lambda: Rendition("", 0, 0))
77
+ webformat: Rendition = field(default_factory=lambda: Rendition("", 0, 0)) # max 640 px; URL valid 24 hours
78
+ large: Rendition = field(default_factory=lambda: Rendition("", 0, 0)) # max 1280 px
79
+ width: int = 0 # the original's size
80
+ height: int = 0
81
+ size: int = 0
82
+
83
+ @classmethod
84
+ def from_api(cls, d: dict[str, Any]) -> Image:
85
+ w, h = int(d.get("imageWidth", 0)), int(d.get("imageHeight", 0))
86
+ # Pixabay gives no size for the large rendition: the original scaled to at most 1280 px.
87
+ scale = min(1.0, 1280 / max(w, h, 1))
88
+ return cls(
89
+ **_common(d),
90
+ preview=Rendition(d.get("previewURL", ""), int(d.get("previewWidth", 0)), int(d.get("previewHeight", 0))),
91
+ webformat=Rendition(d.get("webformatURL", ""), int(d.get("webformatWidth", 0)),
92
+ int(d.get("webformatHeight", 0))),
93
+ large=Rendition(d.get("largeImageURL", ""), round(w * scale), round(h * scale)),
94
+ width=w, height=h, size=int(d.get("imageSize", 0)),
95
+ )
96
+
97
+
98
+ @dataclass(frozen=True)
99
+ class Video(_Hit):
100
+ duration: int = 0
101
+ renditions: dict[str, VideoRendition] = field(default_factory=dict) # large, medium, small, tiny (if present)
102
+
103
+ _noun = "Video"
104
+
105
+ @classmethod
106
+ def from_api(cls, d: dict[str, Any]) -> Video:
107
+ renditions = {
108
+ name: VideoRendition(r.get("url", ""), int(r.get("width", 0)), int(r.get("height", 0)),
109
+ int(r.get("size", 0)), r.get("thumbnail", ""))
110
+ for name, r in (d.get("videos") or {}).items() if r.get("url")
111
+ }
112
+ return cls(**_common(d), duration=int(d.get("duration", 0)), renditions=renditions)
113
+
114
+
115
+ @dataclass(frozen=True)
116
+ class SearchResult(Generic[T]):
117
+ total: int # all matches on Pixabay
118
+ total_hits: int # matches reachable through the API (Pixabay caps this, usually at 500)
119
+ hits: list[T]
120
+ page: int
121
+ per_page: int
122
+
123
+
124
+ @dataclass(frozen=True)
125
+ class RateLimit:
126
+ limit: int
127
+ remaining: int
128
+ reset_at: float # clock time when the window resets
File without changes
File without changes
@@ -0,0 +1,68 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from collections.abc import Callable
5
+ from typing import Any
6
+
7
+ import httpx
8
+ import pytest
9
+
10
+ KEY = "test-key-1234567890"
11
+
12
+
13
+ def image_hit(i: int = 1, tags: str = "cat, animal, pet", user: str = "Alice") -> dict[str, Any]:
14
+ return {
15
+ "id": i, "pageURL": f"https://pixabay.com/photos/cat-{i}/", "type": "photo", "tags": tags,
16
+ "previewURL": f"https://cdn.pixabay.com/photo/p{i}_150.jpg", "previewWidth": 150, "previewHeight": 100,
17
+ "webformatURL": f"https://pixabay.com/get/w{i}_640.jpg", "webformatWidth": 640, "webformatHeight": 427,
18
+ "largeImageURL": f"https://pixabay.com/get/l{i}_1280.jpg", "imageWidth": 4000, "imageHeight": 2667,
19
+ "imageSize": 123456, "views": 10, "downloads": 5, "likes": 2, "comments": 1,
20
+ "user_id": 42, "user": user, "userImageURL": "https://cdn.pixabay.com/user/42.jpg",
21
+ }
22
+
23
+
24
+ def video_hit(i: int = 7) -> dict[str, Any]:
25
+ def r(w: int, h: int) -> dict[str, Any]:
26
+ return {"url": f"https://cdn.pixabay.com/video/{i}_{w}.mp4", "width": w, "height": h, "size": w * 10,
27
+ "thumbnail": f"https://cdn.pixabay.com/video/{i}_{w}.jpg"}
28
+ return {
29
+ "id": i, "pageURL": f"https://pixabay.com/videos/v-{i}/", "type": "film", "tags": "sea, wave", "duration": 12,
30
+ "videos": {"large": {"url": "", "width": 0, "height": 0, "size": 0, "thumbnail": ""},
31
+ "medium": r(1920, 1080), "small": r(1280, 720), "tiny": r(960, 540)},
32
+ "views": 1, "downloads": 1, "likes": 1, "comments": 0, "user_id": 9, "user": "Bob", "userImageURL": "",
33
+ }
34
+
35
+
36
+ class Pixabay:
37
+ """A fake Pixabay: records requests; `reply` decides each answer (default: one image hit)."""
38
+
39
+ def __init__(self) -> None:
40
+ self.requests: list[httpx.Request] = []
41
+ self.reply: Callable[[httpx.Request], httpx.Response] = self.ok
42
+
43
+ @staticmethod
44
+ def ok(request: httpx.Request, hits: list[dict[str, Any]] | None = None, remaining: int = 99) -> httpx.Response:
45
+ if request.url.host != "pixabay.com" or not request.url.path.startswith("/api"):
46
+ return httpx.Response(200, content=b"\x89PNG-bytes") # a download
47
+ hits = hits if hits is not None else ([video_hit()] if "videos" in request.url.path else [image_hit()])
48
+ body = {"total": 1000, "totalHits": 500, "hits": hits}
49
+ return httpx.Response(200, text=json.dumps(body), headers={
50
+ "X-RateLimit-Limit": "100", "X-RateLimit-Remaining": str(remaining), "X-RateLimit-Reset": "30"})
51
+
52
+ def handler(self, request: httpx.Request) -> httpx.Response:
53
+ self.requests.append(request)
54
+ return self.reply(request)
55
+
56
+ @property
57
+ def api_calls(self) -> list[httpx.Request]:
58
+ return [r for r in self.requests if r.url.path.startswith("/api")]
59
+
60
+
61
+ @pytest.fixture
62
+ def fake() -> Pixabay:
63
+ return Pixabay()
64
+
65
+
66
+ @pytest.fixture
67
+ def sleeps() -> list[float]:
68
+ return []
@@ -0,0 +1,233 @@
1
+ from __future__ import annotations
2
+
3
+ import logging
4
+ from pathlib import Path
5
+
6
+ import httpx
7
+ import pytest
8
+
9
+ from pixabay_client import (
10
+ AsyncPixabayClient, AuthError, Image, MemoryCache, NotFound, PixabayClient, PixabayError, RateLimited,
11
+ ServiceError, Video,
12
+ )
13
+
14
+ from .conftest import KEY, Pixabay, image_hit
15
+
16
+
17
+ def client(fake: Pixabay, sleeps: list[float], **kw: object) -> PixabayClient:
18
+ return PixabayClient(KEY, transport=httpx.MockTransport(fake.handler), sleep=sleeps.append, **kw) # type: ignore[arg-type]
19
+
20
+
21
+ def test_search_images_maps_params_and_hits(fake: Pixabay, sleeps: list[float]) -> None:
22
+ c = client(fake, sleeps)
23
+ res = c.search_images("tabby cat", image_type="photo", per_page=30, colors=["red", "blue"])
24
+ q = fake.api_calls[0].url.params
25
+ assert q["q"] == "tabby cat" and q["image_type"] == "photo" and q["per_page"] == "30"
26
+ assert q["colors"] == "red,blue" and q["safesearch"] == "true" # safe search on by default
27
+ assert res.total == 1000 and res.total_hits == 500 and res.page == 1
28
+ img = res.hits[0]
29
+ assert isinstance(img, Image) and img.id == 1 and img.tags == ("cat", "animal", "pet")
30
+ assert img.large.url.endswith("l1_1280.jpg") and img.width == 4000 and img.user == "Alice"
31
+
32
+
33
+ def test_query_longer_than_100_characters_is_refused(fake: Pixabay, sleeps: list[float]) -> None:
34
+ with pytest.raises(ValueError):
35
+ client(fake, sleeps).search_images("x" * 101)
36
+ assert fake.requests == []
37
+
38
+
39
+ def test_per_page_bounds(fake: Pixabay, sleeps: list[float]) -> None:
40
+ for bad in (2, 201):
41
+ with pytest.raises(ValueError):
42
+ client(fake, sleeps).search_images("cat", per_page=bad)
43
+
44
+
45
+ def test_results_are_cached_for_24_hours_by_default(fake: Pixabay, sleeps: list[float]) -> None:
46
+ now = [1000.0]
47
+ c = client(fake, sleeps, cache=MemoryCache(clock=lambda: now[0]))
48
+ c.search_images("cat")
49
+ c.search_images("cat")
50
+ assert len(fake.api_calls) == 1
51
+ now[0] += 24 * 3600 + 1
52
+ c.search_images("cat")
53
+ assert len(fake.api_calls) == 2
54
+
55
+
56
+ def test_cache_off(fake: Pixabay, sleeps: list[float]) -> None:
57
+ c = client(fake, sleeps, cache=None)
58
+ c.search_images("cat")
59
+ c.search_images("cat")
60
+ assert len(fake.api_calls) == 2
61
+
62
+
63
+ def test_get_image_and_not_found(fake: Pixabay, sleeps: list[float]) -> None:
64
+ c = client(fake, sleeps)
65
+ assert c.get_image(1).id == 1 and fake.api_calls[0].url.params["id"] == "1"
66
+ fake.reply = lambda r: httpx.Response(400, text='[ERROR 400] "id" is out of valid range.')
67
+ with pytest.raises(NotFound):
68
+ c.get_image(999999999)
69
+ fake.reply = lambda r: httpx.Response(400, text="[ERROR 400] Image #99999999999 does not exist.") # live wording
70
+ with pytest.raises(NotFound):
71
+ c.get_image(99999999999)
72
+
73
+
74
+ def test_bad_key_is_auth_error_and_never_shows_the_key(fake: Pixabay, sleeps: list[float]) -> None:
75
+ fake.reply = lambda r: httpx.Response(400, text="[ERROR 400] Invalid or missing API key (https://pixabay.com/api/docs/).")
76
+ with pytest.raises(AuthError) as e:
77
+ client(fake, sleeps).search_images("cat")
78
+ assert KEY not in str(e.value) and KEY not in repr(e.value)
79
+
80
+
81
+ def test_other_errors(fake: Pixabay, sleeps: list[float]) -> None:
82
+ fake.reply = lambda r: httpx.Response(400, text="[ERROR 400] something else")
83
+ with pytest.raises(PixabayError):
84
+ client(fake, sleeps).search_images("cat")
85
+ fake.reply = lambda r: httpx.Response(503, text="down")
86
+ with pytest.raises(ServiceError):
87
+ client(fake, sleeps, cache=None).search_images("cat")
88
+
89
+
90
+ def test_rate_limit_is_read_and_a_429_waits_and_retries(fake: Pixabay, sleeps: list[float]) -> None:
91
+ c = client(fake, sleeps, cache=None)
92
+ c.search_images("cat")
93
+ assert c.rate_limit is not None and c.rate_limit.limit == 100 and c.rate_limit.remaining == 99
94
+ answers = [httpx.Response(429, text="API rate limit exceeded", headers={"X-RateLimit-Reset": "7"}),
95
+ Pixabay.ok(httpx.Request("GET", "https://pixabay.com/api/"))]
96
+ fake.reply = lambda r: answers.pop(0)
97
+ assert c.search_images("dog").hits
98
+ assert sleeps == [7.0]
99
+
100
+
101
+ def test_429_gives_up_after_retries(fake: Pixabay, sleeps: list[float]) -> None:
102
+ fake.reply = lambda r: httpx.Response(429, text="API rate limit exceeded", headers={"X-RateLimit-Reset": "3"})
103
+ with pytest.raises(RateLimited):
104
+ client(fake, sleeps, cache=None, retries=2).search_images("cat")
105
+ assert sleeps == [3.0, 3.0]
106
+
107
+
108
+ def test_no_requests_left_waits_before_the_next_call(fake: Pixabay, sleeps: list[float]) -> None:
109
+ fake.reply = lambda r: Pixabay.ok(r, remaining=0)
110
+ c = client(fake, sleeps, cache=None, clock=lambda: 0.0)
111
+ c.search_images("cat")
112
+ c.search_images("dog")
113
+ assert sleeps == [30.0] # X-RateLimit-Reset of the first answer
114
+
115
+
116
+ def test_key_never_in_repr_or_logs(fake: Pixabay, sleeps: list[float], caplog: pytest.LogCaptureFixture) -> None:
117
+ c = client(fake, sleeps)
118
+ assert KEY not in repr(c)
119
+ with caplog.at_level(logging.DEBUG):
120
+ c.search_images("cat")
121
+ logging.getLogger("httpx").info("HTTP Request: GET https://pixabay.com/api/?key=%s&q=cat", KEY)
122
+ assert KEY not in caplog.text
123
+
124
+
125
+ def test_key_from_environment(monkeypatch: pytest.MonkeyPatch, fake: Pixabay, sleeps: list[float]) -> None:
126
+ monkeypatch.setenv("PIXABAY_API_KEY", KEY)
127
+ c = PixabayClient(transport=httpx.MockTransport(fake.handler))
128
+ c.search_images("cat")
129
+ assert fake.api_calls[0].url.params["key"] == KEY
130
+ monkeypatch.delenv("PIXABAY_API_KEY")
131
+ with pytest.raises(AuthError):
132
+ PixabayClient()
133
+
134
+
135
+ def test_a_malformed_hit_is_skipped(fake: Pixabay, sleeps: list[float]) -> None:
136
+ fake.reply = lambda r: Pixabay.ok(r, hits=[image_hit(1), {"id": "bad"}, "junk", image_hit(2)])
137
+ assert [h.id for h in client(fake, sleeps).search_images("cat").hits] == [1, 2]
138
+
139
+
140
+ def test_exclude_people_filter(fake: Pixabay, sleeps: list[float]) -> None:
141
+ fake.reply = lambda r: Pixabay.ok(r, hits=[image_hit(1, "cat, pet"), image_hit(2, "woman, cat"),
142
+ image_hit(3, "children, park")])
143
+ res = client(fake, sleeps).search_images("cat", exclude_people=True)
144
+ assert [h.id for h in res.hits] == [1]
145
+
146
+
147
+ def test_download_saves_from_pixabay_only(fake: Pixabay, sleeps: list[float], tmp_path: object) -> None:
148
+ c = client(fake, sleeps)
149
+ img = c.search_images("cat").hits[0]
150
+ assert c.download(img) == b"\x89PNG-bytes"
151
+ assert fake.requests[-1].url.path.endswith("l1_1280.jpg")
152
+ out = c.download(img, size="webformat", dest=tmp_path / "cat.jpg") # type: ignore[operator]
153
+ assert out.read_bytes() == b"\x89PNG-bytes" # type: ignore[union-attr]
154
+ evil = Image.from_api({**image_hit(), "largeImageURL": "http://169.254.169.254/latest"})
155
+ with pytest.raises(ValueError):
156
+ c.download(evil)
157
+
158
+
159
+
160
+ def _redirect_to(location: str): # type: ignore[no-untyped-def]
161
+ def reply(r: httpx.Request) -> httpx.Response:
162
+ if r.url.path.endswith("l1_1280.jpg"):
163
+ return httpx.Response(302, headers={"Location": location})
164
+ return Pixabay.ok(r)
165
+ return reply
166
+
167
+
168
+ def test_download_refuses_a_redirect_off_pixabay(fake: Pixabay, sleeps: list[float]) -> None:
169
+ c = client(fake, sleeps)
170
+ img = c.search_images("cat").hits[0]
171
+ fake.reply = _redirect_to("http://169.254.169.254/latest")
172
+ with pytest.raises(ValueError):
173
+ c.download(img)
174
+ assert all(r.url.host in ("pixabay.com", "cdn.pixabay.com") for r in fake.requests)
175
+
176
+
177
+ def test_download_follows_a_redirect_within_pixabay(fake: Pixabay, sleeps: list[float]) -> None:
178
+ c = client(fake, sleeps)
179
+ img = c.search_images("cat").hits[0]
180
+ fake.reply = _redirect_to("https://cdn.pixabay.com/photo/l1_final.jpg")
181
+ assert c.download(img) == b"\x89PNG-bytes"
182
+ assert fake.requests[-1].url.host == "cdn.pixabay.com"
183
+
184
+
185
+ async def test_async_download_refuses_a_redirect_off_pixabay(fake: Pixabay) -> None:
186
+ async def asleep(_: float) -> None: ...
187
+ async with AsyncPixabayClient(KEY, transport=httpx.MockTransport(fake.handler), sleep=asleep) as c:
188
+ img = (await c.search_images("cat")).hits[0]
189
+ fake.reply = _redirect_to("https://evil.example/x.jpg")
190
+ with pytest.raises(ValueError):
191
+ await c.download(img)
192
+ assert all(r.url.host in ("pixabay.com", "cdn.pixabay.com") for r in fake.requests)
193
+
194
+ def test_credit_lines() -> None:
195
+ img = Image.from_api(image_hit(user="Alice"))
196
+ assert img.credit == "Image by Alice from Pixabay"
197
+ assert 'href="https://pixabay.com/users/Alice-42/"' in img.credit_html
198
+ assert 'href="https://pixabay.com/photos/cat-1/"' in img.credit_html
199
+ assert "<script>" not in Image.from_api(image_hit(user="<script>")).credit_html
200
+
201
+
202
+ def test_videos(fake: Pixabay, sleeps: list[float]) -> None:
203
+ c = client(fake, sleeps)
204
+ res = c.search_videos("sea", video_type="film")
205
+ assert fake.api_calls[0].url.path == "/api/videos/" and fake.api_calls[0].url.params["video_type"] == "film"
206
+ v = res.hits[0]
207
+ assert isinstance(v, Video) and v.duration == 12 and v.renditions["medium"].width == 1920
208
+ assert "large" not in v.renditions # Pixabay sends an empty large rendition when there is none
209
+ assert v.credit == "Video by Bob from Pixabay"
210
+
211
+
212
+ def test_iter_images_pages_until_enough(fake: Pixabay, sleeps: list[float]) -> None:
213
+ fake.reply = lambda r: Pixabay.ok(r, hits=[image_hit(int(r.url.params["page"]) * 10 + i) for i in range(3)])
214
+ ids = [h.id for h in client(fake, sleeps).iter_images("cat", per_page=3, max_results=7)]
215
+ assert ids == [10, 11, 12, 20, 21, 22, 30]
216
+
217
+
218
+ async def test_async_client(fake: Pixabay, sleeps: list[float]) -> None:
219
+ async def asleep(s: float) -> None:
220
+ sleeps.append(s)
221
+ async with AsyncPixabayClient(KEY, transport=httpx.MockTransport(fake.handler), sleep=asleep) as c:
222
+ res = await c.search_images("cat")
223
+ assert res.hits[0].id == 1
224
+ await c.search_images("cat")
225
+ assert len(fake.api_calls) == 1 # cached
226
+ assert await c.download(res.hits[0]) == b"\x89PNG-bytes"
227
+ assert (await c.get_video(7)).id == 7
228
+
229
+
230
+ def test_package_ships_py_typed() -> None:
231
+ import pixabay_client
232
+ marker = Path(pixabay_client.__file__).resolve().parent / "py.typed"
233
+ assert marker.is_file()