pexafy 0.1.0__tar.gz

pexafy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

pexafy-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.env

pexafy-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Synchronous and asynchronous clients
+- Text search, image search, similar photos, facets, collections, usage
+- Cursor paging handled by `iter_search`
+- Typed exceptions, retries on timeouts and 5xx, `Retry-After` honoured
+- `pexafy` command line client

pexafy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Bug reports and pull requests are welcome.
+
+## Reporting a bug
+
+Open an issue with what you ran, what you expected, and what happened instead.
+A minimal reproduction saves a lot of back and forth.
+
+## Pull requests
+
+- Keep the change focused — one concern per PR.
+- Add a test if you are fixing a bug or adding behaviour.
+- `ruff check .` and `pytest` should pass before you push.
+
+## Development
+
+```bash
+git clone https://github.com/Pexafy/pexafy-python.git
+cd pexafy-python
+pip install -e ".[dev]"
+pytest
+```

pexafy-0.1.0/LICENSE

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

pexafy-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: pexafy
+Version: 0.1.0
+Summary: Python client for the Pexafy stock photo search API
+Project-URL: Homepage, https://pexafy.com
+Project-URL: Documentation, https://docs.pexafy.com
+Project-URL: Source, https://github.com/Pexafy/pexafy-python
+Project-URL: Issues, https://github.com/Pexafy/pexafy-python/issues
+Author-email: Marouane Tijani <marouane@pexafy.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,image search,semantic search,stock photos
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pexafy-python
+
+Python client for the [Pexafy](https://pexafy.com) image search API. Search a
+catalogue of free stock photos by describing what you want, or by handing it an
+image to match.
+
+```bash
+pip install pexafy
+```
+
+## Getting started
+
+```python
+from pexafy import Client
+
+client = Client("your-api-key")
+
+for photo in client.search("a quiet street in the rain", per_page=5):
+    print(photo.urls.regular, "-", photo.alt_text)
+```
+
+The key comes from your [dashboard](https://pexafy.com/dashboard/); the free
+tier does not ask for a card. If you would rather not put it in the code, the
+client picks up `PEXAFY_API_KEY` from the environment.
+
+## Writing queries
+
+Search runs on meaning, not keywords, so full sentences work better than a pile
+of nouns. `two people hiking on a ridge at dawn` finds what you would expect;
+`hiking dawn people` gives you a worse ranking, because you have thrown away
+the relationships between the words.
+
+Filters narrow the result set after the semantic match:
+
+```python
+result = client.search(
+    "an empty office at night",
+    orientation="landscape",
+    color_name="blue",
+    source=["Pexels", "Unsplash"],
+    per_page=20,
+)
+
+print(len(result), "photos in", result.took_ms, "ms")
+```
+
+List filters accept either a list or a comma separated string.
+
+## Paging
+
+A single call returns one page. `iter_search` follows the cursor for you and
+yields photos until the results run out or you have seen enough:
+
+```python
+for photo in client.iter_search("vintage typewriter", max_results=200):
+    download(photo.urls.large)
+```
+
+## Search by image
+
+Pass a path, raw bytes, or an open file:
+
+```python
+similar = client.search_by_image("moodboard/reference.jpg", per_page=12)
+```
+
+If you already have a photo id, `client.similar(photo_id)` is cheaper — the
+image does not have to be uploaded and encoded again.
+
+## Async
+
+The same surface, awaitable:
+
+```python
+import asyncio
+from pexafy import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        pages = await asyncio.gather(
+            client.search("desert road"),
+            client.search("snow covered pines"),
+        )
+    for page in pages:
+        print(len(page))
+
+asyncio.run(main())
+```
+
+## Errors
+
+Everything raised inherits from `PexafyError`. The ones worth catching
+separately:
+
+```python
+from pexafy import errors
+
+try:
+    client.search("...")
+except errors.RateLimitError as exc:
+    time.sleep(exc.retry_after or 60)
+except errors.AuthenticationError:
+    ...          # key is missing, malformed or revoked
+except errors.APIError as exc:
+    print(exc.status_code, exc.code, exc.request_id)
+```
+
+`request_id` is worth logging. It is the fastest way to get an answer if you
+need to ask about a specific call.
+
+Timeouts and 5xx responses are retried twice with backoff, and `Retry-After` is
+honoured when the server sends it. Set `max_retries=0` if you would rather
+handle that yourself.
+
+## Command line
+
+```
+$ pexafy search "morning fog over pine trees" -n 3
+0.847  019e0eb8-b028-73cb-9296-dfa70f557bc9   4000x2667   green      Pexels     https://...
+0.812  019e4c9b-3022-7660-b43d-e730b8435f24   6000x4000   green      Unsplash   https://...
+0.798  019e4f39-66d4-7ef2-bc9b-eb5340fd243e   3648x5472   grey       Pexels     https://...
+```
+
+`pexafy photo <id>`, `pexafy similar <id>` and `pexafy usage` are also there.
+Add `--json` to any of them for the raw response.
+
+## Attribution
+
+Photos come from several providers with different licence terms. Every photo
+carries an `attribution` object with a ready made credit line:
+
+```python
+photo.attribution.plain   # Photo by J. Doe
+photo.attribution.html    # <a href="...">J. Doe</a>
+```
+
+Check `photo.license_type` if your use depends on it.
+
+## Reference
+
+| Method | What it does |
+| --- | --- |
+| `search(q, **filters)` | one page of results |
+| `iter_search(q, max_results=None, **filters)` | every page, cursor handled |
+| `search_by_image(image, **filters)` | match an image you supply |
+| `get_photo(photo_id)` | one photo by id |
+| `similar(photo_id, **filters)` | photos close to an existing one |
+| `colors()` `sources()` `orientations()` `licenses()` | filter values you can use |
+| `suggest_photographers(q)` `photographer(username)` | photographer lookup |
+| `collections()` `create_collection(name)` `add_to_collection(id, photo_id)` | saved sets |
+| `usage()` `usage_daily()` `usage_monthly()` `usage_by_key()` | where you are against your quota |
+
+Full API documentation is at [docs.pexafy.com](https://docs.pexafy.com).
+
+## Requirements
+
+Python 3.9 or newer. The only dependency is `httpx`.
+
+## Licence
+
+MIT.

pexafy-0.1.0/README.md

@@ -0,0 +1,161 @@
+# pexafy-python
+
+Python client for the [Pexafy](https://pexafy.com) image search API. Search a
+catalogue of free stock photos by describing what you want, or by handing it an
+image to match.
+
+```bash
+pip install pexafy
+```
+
+## Getting started
+
+```python
+from pexafy import Client
+
+client = Client("your-api-key")
+
+for photo in client.search("a quiet street in the rain", per_page=5):
+    print(photo.urls.regular, "-", photo.alt_text)
+```
+
+The key comes from your [dashboard](https://pexafy.com/dashboard/); the free
+tier does not ask for a card. If you would rather not put it in the code, the
+client picks up `PEXAFY_API_KEY` from the environment.
+
+## Writing queries
+
+Search runs on meaning, not keywords, so full sentences work better than a pile
+of nouns. `two people hiking on a ridge at dawn` finds what you would expect;
+`hiking dawn people` gives you a worse ranking, because you have thrown away
+the relationships between the words.
+
+Filters narrow the result set after the semantic match:
+
+```python
+result = client.search(
+    "an empty office at night",
+    orientation="landscape",
+    color_name="blue",
+    source=["Pexels", "Unsplash"],
+    per_page=20,
+)
+
+print(len(result), "photos in", result.took_ms, "ms")
+```
+
+List filters accept either a list or a comma separated string.
+
+## Paging
+
+A single call returns one page. `iter_search` follows the cursor for you and
+yields photos until the results run out or you have seen enough:
+
+```python
+for photo in client.iter_search("vintage typewriter", max_results=200):
+    download(photo.urls.large)
+```
+
+## Search by image
+
+Pass a path, raw bytes, or an open file:
+
+```python
+similar = client.search_by_image("moodboard/reference.jpg", per_page=12)
+```
+
+If you already have a photo id, `client.similar(photo_id)` is cheaper — the
+image does not have to be uploaded and encoded again.
+
+## Async
+
+The same surface, awaitable:
+
+```python
+import asyncio
+from pexafy import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        pages = await asyncio.gather(
+            client.search("desert road"),
+            client.search("snow covered pines"),
+        )
+    for page in pages:
+        print(len(page))
+
+asyncio.run(main())
+```
+
+## Errors
+
+Everything raised inherits from `PexafyError`. The ones worth catching
+separately:
+
+```python
+from pexafy import errors
+
+try:
+    client.search("...")
+except errors.RateLimitError as exc:
+    time.sleep(exc.retry_after or 60)
+except errors.AuthenticationError:
+    ...          # key is missing, malformed or revoked
+except errors.APIError as exc:
+    print(exc.status_code, exc.code, exc.request_id)
+```
+
+`request_id` is worth logging. It is the fastest way to get an answer if you
+need to ask about a specific call.
+
+Timeouts and 5xx responses are retried twice with backoff, and `Retry-After` is
+honoured when the server sends it. Set `max_retries=0` if you would rather
+handle that yourself.
+
+## Command line
+
+```
+$ pexafy search "morning fog over pine trees" -n 3
+0.847  019e0eb8-b028-73cb-9296-dfa70f557bc9   4000x2667   green      Pexels     https://...
+0.812  019e4c9b-3022-7660-b43d-e730b8435f24   6000x4000   green      Unsplash   https://...
+0.798  019e4f39-66d4-7ef2-bc9b-eb5340fd243e   3648x5472   grey       Pexels     https://...
+```
+
+`pexafy photo <id>`, `pexafy similar <id>` and `pexafy usage` are also there.
+Add `--json` to any of them for the raw response.
+
+## Attribution
+
+Photos come from several providers with different licence terms. Every photo
+carries an `attribution` object with a ready made credit line:
+
+```python
+photo.attribution.plain   # Photo by J. Doe
+photo.attribution.html    # <a href="...">J. Doe</a>
+```
+
+Check `photo.license_type` if your use depends on it.
+
+## Reference
+
+| Method | What it does |
+| --- | --- |
+| `search(q, **filters)` | one page of results |
+| `iter_search(q, max_results=None, **filters)` | every page, cursor handled |
+| `search_by_image(image, **filters)` | match an image you supply |
+| `get_photo(photo_id)` | one photo by id |
+| `similar(photo_id, **filters)` | photos close to an existing one |
+| `colors()` `sources()` `orientations()` `licenses()` | filter values you can use |
+| `suggest_photographers(q)` `photographer(username)` | photographer lookup |
+| `collections()` `create_collection(name)` `add_to_collection(id, photo_id)` | saved sets |
+| `usage()` `usage_daily()` `usage_monthly()` `usage_by_key()` | where you are against your quota |
+
+Full API documentation is at [docs.pexafy.com](https://docs.pexafy.com).
+
+## Requirements
+
+Python 3.9 or newer. The only dependency is `httpx`.
+
+## Licence
+
+MIT.

pexafy-0.1.0/examples/async_batch.py

@@ -0,0 +1,31 @@
+"""Run several searches at once.
+
+Filling one page per section of a document is the common case, and there is no
+reason to do it serially.
+
+    PEXAFY_API_KEY=... python async_batch.py
+"""
+
+import asyncio
+
+from pexafy import AsyncClient
+
+SECTIONS = [
+    "an empty office at night",
+    "hands typing on a mechanical keyboard",
+    "a server room seen from the doorway",
+    "someone reading on a train",
+]
+
+
+async def main():
+    async with AsyncClient() as client:
+        pages = await asyncio.gather(*(client.search(q, per_page=3) for q in SECTIONS))
+
+    for query, page in zip(SECTIONS, pages):
+        print(f"\n{query}")
+        for photo in page:
+            print(f"   {photo.urls.small}")
+
+
+asyncio.run(main())

pexafy-0.1.0/examples/basic_search.py

@@ -0,0 +1,18 @@
+"""The smallest useful thing: search and print what came back.
+
+    PEXAFY_API_KEY=... python basic_search.py "a quiet street in the rain"
+"""
+
+import sys
+
+from pexafy import Client
+
+query = sys.argv[1] if len(sys.argv) > 1 else "a quiet street in the rain"
+
+with Client() as client:
+    result = client.search(query, per_page=5)
+    print(f"{len(result)} photos in {result.took_ms:.0f} ms\n")
+    for photo in result:
+        print(f"{photo.relevance_score:.3f}  {photo.alt_text}")
+        print(f"        {photo.urls.regular}")
+        print(f"        {photo.attribution.plain}\n")

pexafy-0.1.0/examples/download_a_set.py

@@ -0,0 +1,32 @@
+"""Page through results and save the files.
+
+Shows the two things that matter when you pull more than one page: let
+iter_search follow the cursor, and stop on your own terms rather than draining
+the whole catalogue.
+
+    PEXAFY_API_KEY=... python download_a_set.py "vintage typewriter" 25
+"""
+
+import sys
+from pathlib import Path
+
+import httpx
+
+from pexafy import Client, errors
+
+query = sys.argv[1] if len(sys.argv) > 1 else "vintage typewriter"
+count = int(sys.argv[2]) if len(sys.argv) > 2 else 25
+
+out = Path("downloads")
+out.mkdir(exist_ok=True)
+
+with Client() as client, httpx.Client(timeout=60) as http:
+    try:
+        for photo in client.iter_search(query, max_results=count, orientation="landscape"):
+            target = out / f"{photo.photo_id}.jpg"
+            if target.exists():
+                continue
+            target.write_bytes(http.get(photo.urls.large).content)
+            print(f"saved {target}  ({photo.attribution.plain})")
+    except errors.RateLimitError as exc:
+        print(f"quota reached, retry in {exc.retry_after or 60:.0f}s")

pexafy-0.1.0/examples/match_an_image.py

@@ -0,0 +1,25 @@
+"""Find photos that look like one you already have.
+
+Useful for building a moodboard around a reference, or finding an alternative
+to an image you cannot license.
+
+    PEXAFY_API_KEY=... python match_an_image.py reference.jpg
+"""
+
+import sys
+
+from pexafy import Client
+
+reference = sys.argv[1]
+
+with Client() as client:
+    result = client.search_by_image(reference, per_page=8)
+
+    for photo in result:
+        print(f"{photo.relevance_score:.3f}  {photo.color_name:<8} {photo.urls.small}")
+
+    # If you plan to keep going from one of these, use its id rather than
+    # uploading the image again — no encoding round trip.
+    if len(result):
+        more = client.similar(result[0].photo_id, per_page=8)
+        print(f"\n{len(more)} more like the top result")

pexafy-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pexafy"
+version = "0.1.0"
+description = "Python client for the Pexafy stock photo search API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{name = "Marouane Tijani", email = "marouane@pexafy.com"}]
+keywords = ["stock photos", "image search", "semantic search", "api client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "respx>=0.20", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://pexafy.com"
+Documentation = "https://docs.pexafy.com"
+Source = "https://github.com/Pexafy/pexafy-python"
+Issues = "https://github.com/Pexafy/pexafy-python/issues"
+
+[project.scripts]
+pexafy = "pexafy.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pexafy"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+# Optional[...] rather than `| None` — the package still supports 3.9, and the
+# postponed-annotation trick is easy to break by accident in a dataclass.
+ignore = ["UP007", "UP045"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

pexafy-0.1.0/src/pexafy/__init__.py

@@ -0,0 +1,61 @@
+"""Python client for the Pexafy image search API.
+
+    from pexafy import Client
+
+    client = Client("your-api-key")
+    for photo in client.search("a quiet street in the rain", per_page=10):
+        print(photo.urls.regular)
+
+Get a key at https://pexafy.com — the free tier does not need a card.
+"""
+
+__version__ = "0.1.0"
+
+from .client import DEFAULT_BASE_URL, AsyncClient, Client
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError_,
+    NotFoundError,
+    PermissionError_,
+    PexafyError,
+    RateLimitError,
+    ServerError,
+    TimeoutError_,
+    ValidationError,
+)
+from .models import (
+    Attribution,
+    Collection,
+    CollectionItem,
+    Pagination,
+    Photo,
+    Photographer,
+    PhotoUrls,
+    SearchResult,
+)
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "DEFAULT_BASE_URL",
+    "Photo",
+    "PhotoUrls",
+    "Attribution",
+    "Photographer",
+    "Collection",
+    "CollectionItem",
+    "Pagination",
+    "SearchResult",
+    "PexafyError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError_",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "ServerError",
+    "TimeoutError_",
+    "ConnectionError_",
+    "__version__",
+]