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.
- pixabay_client-0.1.0/.github/workflows/publish.yml +34 -0
- pixabay_client-0.1.0/.github/workflows/test.yml +16 -0
- pixabay_client-0.1.0/.gitignore +8 -0
- pixabay_client-0.1.0/CHANGELOG.md +7 -0
- pixabay_client-0.1.0/LICENSE +21 -0
- pixabay_client-0.1.0/PKG-INFO +107 -0
- pixabay_client-0.1.0/README.md +79 -0
- pixabay_client-0.1.0/pyproject.toml +46 -0
- pixabay_client-0.1.0/src/pixabay_client/__init__.py +11 -0
- pixabay_client-0.1.0/src/pixabay_client/_core.py +214 -0
- pixabay_client-0.1.0/src/pixabay_client/client.py +280 -0
- pixabay_client-0.1.0/src/pixabay_client/errors.py +26 -0
- pixabay_client-0.1.0/src/pixabay_client/models.py +128 -0
- pixabay_client-0.1.0/src/pixabay_client/py.typed +0 -0
- pixabay_client-0.1.0/tests/__init__.py +0 -0
- pixabay_client-0.1.0/tests/conftest.py +68 -0
- pixabay_client-0.1.0/tests/test_client.py +233 -0
|
@@ -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,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()
|