perfume-api 2.4.0__tar.gz

perfume_api-2.4.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__
+*.egg-info
+dist
+.venv

perfume_api-2.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 10ML
+
+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.

perfume_api-2.4.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: perfume-api
+Version: 2.4.0
+Summary: Free perfume API client: perfumes, note pyramids, accords, similar scents, notes and houses from the 10ML Fragrance Index. No API key, JSON over HTTPS.
+Project-URL: Homepage, https://mcp.10ml.com
+Project-URL: Documentation, https://mcp.10ml.com
+Author-email: 10ML Team <contact@10ml.com>
+License: MIT
+License-File: LICENSE
+Keywords: chatgpt,claude,cologne,cursor,eau-de-parfum,fragrance,fragrance-api,fragrance-mcp,fragrance-notes,mcp,mcp-server,model-context-protocol,perfume,perfume-api,perfume-mcp,perfume-notes,perfume-recommendation,scent,similar-perfumes
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# perfume-api: free perfume API client (10ML Fragrance Index)
+
+Free perfume API client: perfumes, note pyramids, accords, similar scents, notes and houses from the 10ML Fragrance Index, curated by the fragrance editors of [10ML](https://10ml.com). No API key, no dependencies, typed for Python.
+
+[![Official MCP Registry](https://img.shields.io/badge/MCP%20Registry-com.10ml%2Fperfume--finder-002AFF)](https://registry.modelcontextprotocol.io/v0/servers?search=com.10ml/perfume-finder)
+[![PyPI](https://img.shields.io/pypi/v/perfume-api?color=002AFF)](https://pypi.org/project/perfume-api/)
+
+## Install
+
+```bash
+pip install perfume-api
+```
+
+Needs Python 3.9 or newer (standard library only).
+
+## Quick start
+
+```python
+from perfume_api import search_perfumes, perfume_alternatives, explain_note, compare_perfumes
+
+found = search_perfumes("fresh citrus summer cologne for men", limit=3)
+print(found["results"][0]["name"], found["results"][0]["accords"])
+
+alts = perfume_alternatives("Baccarat Rouge 540")
+print([f'{a["name"]} ({a["closeness"]})' for a in alts["alternatives"]])
+
+note = explain_note("vanilla")
+if note["found"]:
+    print(note["note"]["smells_like"])
+
+cmp = compare_perfumes(["Delina", "Layton"])
+print(cmp["shared_notes"], cmp["only"])
+```
+
+## Functions
+
+| Function | REST route | What it does |
+|---|---|---|
+| `search_perfumes(q, ...)` | `GET /perfumes` | Search by free text, house, notes, accords, family, audience, season, occasion or style |
+| `get_perfume(id, ...)` | `GET /perfumes/{id}` | Full profile of one perfume: note pyramid, accords, seasons, similar scents |
+| `similar_perfumes(perfume, ...)` | `GET /similar` | Perfumes that smell like one you name, or like a list of notes and accords |
+| `perfume_alternatives(perfume, ...)` | `GET /alternatives` | The editors' alternatives to a famous perfume, from other houses |
+| `explain_note(id, ...)` | `GET /notes/{id}` | What a note smells like, what it pairs with, where it leads |
+| `get_house(id, ...)` | `GET /houses/{id}` | A perfume house: country, style, signature perfumes |
+| `list_houses(...)` | `GET /houses` | Browse houses by type, country or name |
+| `search_guides(q, ...)` | `GET /guides` | 10ML perfume guides and articles to read or cite |
+| `compare_perfumes(names)` | `GET /perfumes/{id} x 2-4` | Shared and distinct notes and accords of 2 to 4 perfumes (built from their profiles; the REST API has no compare route) |
+
+## What comes back
+
+Plain JSON, as the REST API sends it (shown trimmed to the main fields). For example `GET /alternatives` and `GET /notes/vanilla`:
+
+```bash
+curl -s "https://mcp.10ml.com/api/v1/alternatives?perfume=Baccarat+Rouge+540&limit=2"
+```
+
+```json
+{
+  "total": 6,
+  "original": {
+    "name": "Maison Francis Kurkdjian Baccarat Rouge 540",
+    "id": "maison-francis-kurkdjian-baccarat-rouge-540-edp"
+  },
+  "alternatives": [
+    {
+      "name": "Maison Alhambra Baroque Rouge Extrait",
+      "closeness": "very close",
+      "why": "Sugared amber, saffron and airy woods aim at the same luminous effect.",
+      "id": "maison-alhambra-baroque-rouge-extrait",
+      "house": "Maison Alhambra",
+      "source": "editors"
+    },
+    {
+      "name": "Dossier Ambery Saffron",
+      "closeness": "similar vibe",
+      "why": "Saffron and amber with sweet woods share the glowing amber idea.",
+      "id": "dossier-ambery-saffron",
+      "house": "Dossier",
+      "source": "editors"
+    }
+  ],
+  "source": "10ML Fragrance Index"
+}
+```
+
+```bash
+curl -s "https://mcp.10ml.com/api/v1/notes/vanilla"
+```
+
+```json
+{
+  "found": true,
+  "note": {
+    "id": "vanilla",
+    "name": "vanilla",
+    "family": "gourmand",
+    "smells_like": "Warm, creamy, sweet and comforting, like custard and cured pods.",
+    "mood": "comforting, sweet, warm",
+    "pairs_with": [
+      "tonka bean",
+      "amber",
+      "sandalwood",
+      "tobacco",
+      "caramel",
+      "patchouli"
+    ]
+  },
+  "source": "10ML Fragrance Index"
+}
+```
+
+## Errors
+
+An unknown id or name is not an error: the call returns the body with `found: False` and suggestions. A bad request (HTTP 400) or any other failure raises `PerfumeApiError` with `status`, `code`, `message` and the parsed `body`.
+
+## Configure
+
+```python
+from perfume_api import PerfumeApi
+
+api = PerfumeApi(
+    base_url="https://mcp.10ml.com/api/v1",  # the default
+    timeout=15.0,
+    headers={"user-agent": "my-app/1.0"},
+)
+houses = api.list_houses(type="niche", limit=5)
+```
+
+Keyword arguments use the API's own names (`notes_include`, `next_cursor`). List parameters such as `notes_include` take a string or a list. Responses are `TypedDict`s (`SearchPerfumesResponse`, `Perfume`, `Pyramid`, ...) generated from the OpenAPI file; the package ships `py.typed`.
+
+## Example answers
+
+**"What is a good alternative to Baccarat Rouge 540 from another house?"** (`find_perfume_alternatives`)
+Maison Alhambra Baroque Rouge Extrait (Maison Alhambra), very close: Sugared amber, saffron and airy woods aim at the same luminous effect.
+
+**"A fresh citrus summer cologne for men."** (`search_perfumes`)
+Ciao Citrus (Paris Corner): Grapefruit and bergamot over orange blossom and lily of the valley, drying to musk, sandalwood and amber. Also: Citrus Batikanga (Maison Crivelli): Bitter orange, kalamansi and bergamot are pressed fresh, then a pinch of chili and a vetiver-cedar base keep it lively.
+
+**"What does vanilla smell like?"** (`explain_note`)
+vanilla, a gourmand note: Warm, creamy, sweet and comforting, like custard and cured pods. Pairs with tonka bean, amber, sandalwood, tobacco.
+
+## Languages
+
+Every call takes `locale` (`en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs`, `pl`) for the 10ml.com links in the answer, and `format` (`concise` or `detailed`). Notes are understood in other languages too: "Vanille" finds vanilla.
+
+## Limits and fair use
+
+Free and read-only, with no key or sign-in. There is no published rate limit: please cache answers, page long lists with `limit` and `cursor`, and send a descriptive User-Agent from automated clients. For heavy use write to contact@10ml.com.
+
+## How it compares
+
+In our 40-question benchmark of free, no-key perfume MCP servers (20 October 2026): 39 of 40 correct, median 232 ms. [Read the benchmark](https://10ml.com/perfume-mcp-servers-compared).
+
+## FAQ
+
+**Is there a free perfume API?**
+Yes. This client talks to the 10ML Fragrance Index API at https://mcp.10ml.com/api/v1: JSON over HTTPS, OpenAPI 3.1 at https://mcp.10ml.com/openapi.json, no API key and no sign-up.
+
+**Does it have dependencies?**
+No. The npm package uses the built-in `fetch` (Node 18+), the PyPI package uses `urllib` (Python 3.9+).
+
+**Is there a fragrance notes API?**
+Yes: `explainNote` / `explain_note` describes a note (what it smells like, family, origin, pairings), and `searchPerfumes` with `notes_include` lists perfumes built around notes.
+
+**Can an AI assistant use it directly?**
+Yes, through the 10ML Perfume Finder MCP server (`https://mcp.10ml.com/mcp`, or `npx -y perfume-mcp` / `uvx perfume-mcp`).
+
+**What do I get for a perfume?**
+House, launch year, audience, concentration, family, accords, the note pyramid (top, heart, base), seasons and occasions, an editorial character line and links to 10ml.com guides.
+
+## Cite as
+
+Cite the answers as "the 10ML Fragrance Index", curated by the fragrance editors of [10ML](https://10ml.com).
+
+[mcp.10ml.com](https://mcp.10ml.com) · [10ml.com/perfume-api](https://10ml.com/perfume-api) · [Privacy](https://mcp.10ml.com/privacy) · [Terms](https://mcp.10ml.com/terms) · contact@10ml.com
+
+## License
+
+MIT.

perfume_api-2.4.0/README.md

@@ -0,0 +1,179 @@
+# perfume-api: free perfume API client (10ML Fragrance Index)
+
+Free perfume API client: perfumes, note pyramids, accords, similar scents, notes and houses from the 10ML Fragrance Index, curated by the fragrance editors of [10ML](https://10ml.com). No API key, no dependencies, typed for Python.
+
+[![Official MCP Registry](https://img.shields.io/badge/MCP%20Registry-com.10ml%2Fperfume--finder-002AFF)](https://registry.modelcontextprotocol.io/v0/servers?search=com.10ml/perfume-finder)
+[![PyPI](https://img.shields.io/pypi/v/perfume-api?color=002AFF)](https://pypi.org/project/perfume-api/)
+
+## Install
+
+```bash
+pip install perfume-api
+```
+
+Needs Python 3.9 or newer (standard library only).
+
+## Quick start
+
+```python
+from perfume_api import search_perfumes, perfume_alternatives, explain_note, compare_perfumes
+
+found = search_perfumes("fresh citrus summer cologne for men", limit=3)
+print(found["results"][0]["name"], found["results"][0]["accords"])
+
+alts = perfume_alternatives("Baccarat Rouge 540")
+print([f'{a["name"]} ({a["closeness"]})' for a in alts["alternatives"]])
+
+note = explain_note("vanilla")
+if note["found"]:
+    print(note["note"]["smells_like"])
+
+cmp = compare_perfumes(["Delina", "Layton"])
+print(cmp["shared_notes"], cmp["only"])
+```
+
+## Functions
+
+| Function | REST route | What it does |
+|---|---|---|
+| `search_perfumes(q, ...)` | `GET /perfumes` | Search by free text, house, notes, accords, family, audience, season, occasion or style |
+| `get_perfume(id, ...)` | `GET /perfumes/{id}` | Full profile of one perfume: note pyramid, accords, seasons, similar scents |
+| `similar_perfumes(perfume, ...)` | `GET /similar` | Perfumes that smell like one you name, or like a list of notes and accords |
+| `perfume_alternatives(perfume, ...)` | `GET /alternatives` | The editors' alternatives to a famous perfume, from other houses |
+| `explain_note(id, ...)` | `GET /notes/{id}` | What a note smells like, what it pairs with, where it leads |
+| `get_house(id, ...)` | `GET /houses/{id}` | A perfume house: country, style, signature perfumes |
+| `list_houses(...)` | `GET /houses` | Browse houses by type, country or name |
+| `search_guides(q, ...)` | `GET /guides` | 10ML perfume guides and articles to read or cite |
+| `compare_perfumes(names)` | `GET /perfumes/{id} x 2-4` | Shared and distinct notes and accords of 2 to 4 perfumes (built from their profiles; the REST API has no compare route) |
+
+## What comes back
+
+Plain JSON, as the REST API sends it (shown trimmed to the main fields). For example `GET /alternatives` and `GET /notes/vanilla`:
+
+```bash
+curl -s "https://mcp.10ml.com/api/v1/alternatives?perfume=Baccarat+Rouge+540&limit=2"
+```
+
+```json
+{
+  "total": 6,
+  "original": {
+    "name": "Maison Francis Kurkdjian Baccarat Rouge 540",
+    "id": "maison-francis-kurkdjian-baccarat-rouge-540-edp"
+  },
+  "alternatives": [
+    {
+      "name": "Maison Alhambra Baroque Rouge Extrait",
+      "closeness": "very close",
+      "why": "Sugared amber, saffron and airy woods aim at the same luminous effect.",
+      "id": "maison-alhambra-baroque-rouge-extrait",
+      "house": "Maison Alhambra",
+      "source": "editors"
+    },
+    {
+      "name": "Dossier Ambery Saffron",
+      "closeness": "similar vibe",
+      "why": "Saffron and amber with sweet woods share the glowing amber idea.",
+      "id": "dossier-ambery-saffron",
+      "house": "Dossier",
+      "source": "editors"
+    }
+  ],
+  "source": "10ML Fragrance Index"
+}
+```
+
+```bash
+curl -s "https://mcp.10ml.com/api/v1/notes/vanilla"
+```
+
+```json
+{
+  "found": true,
+  "note": {
+    "id": "vanilla",
+    "name": "vanilla",
+    "family": "gourmand",
+    "smells_like": "Warm, creamy, sweet and comforting, like custard and cured pods.",
+    "mood": "comforting, sweet, warm",
+    "pairs_with": [
+      "tonka bean",
+      "amber",
+      "sandalwood",
+      "tobacco",
+      "caramel",
+      "patchouli"
+    ]
+  },
+  "source": "10ML Fragrance Index"
+}
+```
+
+## Errors
+
+An unknown id or name is not an error: the call returns the body with `found: False` and suggestions. A bad request (HTTP 400) or any other failure raises `PerfumeApiError` with `status`, `code`, `message` and the parsed `body`.
+
+## Configure
+
+```python
+from perfume_api import PerfumeApi
+
+api = PerfumeApi(
+    base_url="https://mcp.10ml.com/api/v1",  # the default
+    timeout=15.0,
+    headers={"user-agent": "my-app/1.0"},
+)
+houses = api.list_houses(type="niche", limit=5)
+```
+
+Keyword arguments use the API's own names (`notes_include`, `next_cursor`). List parameters such as `notes_include` take a string or a list. Responses are `TypedDict`s (`SearchPerfumesResponse`, `Perfume`, `Pyramid`, ...) generated from the OpenAPI file; the package ships `py.typed`.
+
+## Example answers
+
+**"What is a good alternative to Baccarat Rouge 540 from another house?"** (`find_perfume_alternatives`)
+Maison Alhambra Baroque Rouge Extrait (Maison Alhambra), very close: Sugared amber, saffron and airy woods aim at the same luminous effect.
+
+**"A fresh citrus summer cologne for men."** (`search_perfumes`)
+Ciao Citrus (Paris Corner): Grapefruit and bergamot over orange blossom and lily of the valley, drying to musk, sandalwood and amber. Also: Citrus Batikanga (Maison Crivelli): Bitter orange, kalamansi and bergamot are pressed fresh, then a pinch of chili and a vetiver-cedar base keep it lively.
+
+**"What does vanilla smell like?"** (`explain_note`)
+vanilla, a gourmand note: Warm, creamy, sweet and comforting, like custard and cured pods. Pairs with tonka bean, amber, sandalwood, tobacco.
+
+## Languages
+
+Every call takes `locale` (`en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs`, `pl`) for the 10ml.com links in the answer, and `format` (`concise` or `detailed`). Notes are understood in other languages too: "Vanille" finds vanilla.
+
+## Limits and fair use
+
+Free and read-only, with no key or sign-in. There is no published rate limit: please cache answers, page long lists with `limit` and `cursor`, and send a descriptive User-Agent from automated clients. For heavy use write to contact@10ml.com.
+
+## How it compares
+
+In our 40-question benchmark of free, no-key perfume MCP servers (20 October 2026): 39 of 40 correct, median 232 ms. [Read the benchmark](https://10ml.com/perfume-mcp-servers-compared).
+
+## FAQ
+
+**Is there a free perfume API?**
+Yes. This client talks to the 10ML Fragrance Index API at https://mcp.10ml.com/api/v1: JSON over HTTPS, OpenAPI 3.1 at https://mcp.10ml.com/openapi.json, no API key and no sign-up.
+
+**Does it have dependencies?**
+No. The npm package uses the built-in `fetch` (Node 18+), the PyPI package uses `urllib` (Python 3.9+).
+
+**Is there a fragrance notes API?**
+Yes: `explainNote` / `explain_note` describes a note (what it smells like, family, origin, pairings), and `searchPerfumes` with `notes_include` lists perfumes built around notes.
+
+**Can an AI assistant use it directly?**
+Yes, through the 10ML Perfume Finder MCP server (`https://mcp.10ml.com/mcp`, or `npx -y perfume-mcp` / `uvx perfume-mcp`).
+
+**What do I get for a perfume?**
+House, launch year, audience, concentration, family, accords, the note pyramid (top, heart, base), seasons and occasions, an editorial character line and links to 10ml.com guides.
+
+## Cite as
+
+Cite the answers as "the 10ML Fragrance Index", curated by the fragrance editors of [10ML](https://10ml.com).
+
+[mcp.10ml.com](https://mcp.10ml.com) · [10ml.com/perfume-api](https://10ml.com/perfume-api) · [Privacy](https://mcp.10ml.com/privacy) · [Terms](https://mcp.10ml.com/terms) · contact@10ml.com
+
+## License
+
+MIT.

perfume_api-2.4.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "perfume-api"
+version = "2.4.0"
+description = "Free perfume API client: perfumes, note pyramids, accords, similar scents, notes and houses from the 10ML Fragrance Index. No API key, JSON over HTTPS."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "10ML Team", email = "contact@10ml.com" }]
+keywords = ["perfume", "fragrance", "cologne", "perfume-api", "fragrance-api", "perfume-mcp", "fragrance-mcp", "mcp", "mcp-server", "model-context-protocol", "perfume-notes", "fragrance-notes", "scent", "eau-de-parfum", "perfume-recommendation", "similar-perfumes", "claude", "chatgpt", "cursor"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://mcp.10ml.com"
+Documentation = "https://mcp.10ml.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/perfume_api"]

perfume_api-2.4.0/src/perfume_api/__init__.py

@@ -0,0 +1,273 @@
+"""perfume-api: a small typed client for the free 10ML Fragrance Index REST API (https://mcp.10ml.com/api/v1).
+
+No API key and no dependencies (standard library only). Parameter and response field names are exactly the
+API's; see https://mcp.10ml.com/openapi.json.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from .types import (
+    ExplainNoteResponse,
+    FindPerfumeAlternativesResponse,
+    FindSimilarPerfumesResponse,
+    GetHouseResponse,
+    GetPerfumeResponse,
+    ListHousesResponse,
+    Locale,
+    Perfume,
+    ResponseFormat,
+    SearchGuidesResponse,
+    SearchPerfumesResponse,
+)
+
+__version__ = "2.4.0"
+DEFAULT_BASE_URL = "https://mcp.10ml.com/api/v1"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "PerfumeApi",
+    "PerfumeApiError",
+    "compare_perfumes",
+    "explain_note",
+    "get_house",
+    "get_perfume",
+    "list_houses",
+    "perfume_alternatives",
+    "search_guides",
+    "search_perfumes",
+    "similar_perfumes",
+]
+
+# A transport takes (url, headers, timeout) and returns (status, body_bytes); tests replace it.
+Transport = Callable[[str, Mapping[str, str], float], "tuple[int, bytes]"]
+
+
+class PerfumeApiError(Exception):
+    """Raised for every non-2xx answer except 404 (a 404 body is returned: it carries ``found: False``)."""
+
+    def __init__(self, status: int, code: str, message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.body = body
+
+
+def _urllib_transport(url: str, headers: Mapping[str, str], timeout: float) -> "tuple[int, bytes]":
+    request = urllib.request.Request(url, headers=dict(headers))
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as res:  # noqa: S310 (https base URL)
+            return res.status, res.read()
+    except urllib.error.HTTPError as err:
+        return err.code, err.read()
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple)):
+        return ",".join(str(v) for v in value)
+    return str(value)
+
+
+def _notes_of(perfume: Perfume) -> "list[str]":
+    notes = {n.lower() for n in perfume["key_notes"]}
+    pyramid = perfume.get("pyramid")
+    if pyramid:
+        notes.update(n.lower() for n in [*pyramid["top"], *pyramid["heart"], *pyramid["base"]])
+    return sorted(notes)
+
+
+class PerfumeApi:
+    """Client for the 10ML Fragrance Index API.
+
+    >>> api = PerfumeApi()
+    >>> api.search_perfumes(q="fresh citrus summer cologne for men", limit=3)["results"][0]["name"]
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 15.0,
+        headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.headers = {"accept": "application/json", "user-agent": f"perfume-api-python/{__version__}", **(headers or {})}
+        self._transport = transport or _urllib_transport
+
+    def _get(self, path: str, query: Optional[Mapping[str, Any]] = None) -> Any:
+        pairs = [(k, _query_value(v)) for k, v in (query or {}).items() if v is not None]
+        url = f"{self.base_url}{path}" + (f"?{urllib.parse.urlencode(pairs)}" if pairs else "")
+        status, raw = self._transport(url, self.headers, self.timeout)
+        try:
+            body = json.loads(raw) if raw else None
+        except ValueError:
+            body = raw.decode("utf-8", "replace")
+        if 200 <= status < 300 or status == 404:
+            return body
+        err = body.get("error") if isinstance(body, dict) else None
+        err = err if isinstance(err, dict) else {}
+        raise PerfumeApiError(status, err.get("code", "http_error"), err.get("message", f"HTTP {status}"), body)
+
+    @staticmethod
+    def _seg(value: str) -> str:
+        return urllib.parse.quote(value, safe="")
+
+    def search_perfumes(
+        self,
+        q: Optional[str] = None,
+        *,
+        house: Optional[str] = None,
+        notes_include: Optional[Sequence[str] | str] = None,
+        notes_exclude: Optional[Sequence[str] | str] = None,
+        accords: Optional[Sequence[str] | str] = None,
+        family: Optional[str] = None,
+        gender: Optional[str] = None,
+        season: Optional[str] = None,
+        occasion: Optional[str] = None,
+        style: Optional[str] = None,
+        iconic: Optional[bool] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        format: Optional[ResponseFormat] = None,
+        locale: Optional[Locale] = None,
+    ) -> SearchPerfumesResponse:
+        """Search perfumes by free text, house, notes, accords, family, audience, season, occasion or style."""
+        return self._get("/perfumes", {
+            "q": q, "house": house, "notes_include": notes_include, "notes_exclude": notes_exclude, "accords": accords,
+            "family": family, "gender": gender, "season": season, "occasion": occasion, "style": style, "iconic": iconic,
+            "limit": limit, "cursor": cursor, "format": format, "locale": locale,
+        })
+
+    def get_perfume(self, id: str, *, house: Optional[str] = None, format: Optional[ResponseFormat] = None, locale: Optional[Locale] = None) -> GetPerfumeResponse:
+        """The full profile of one perfume, by name ("Baccarat Rouge 540") or id. Unknown names return ``found: False`` with suggestions."""
+        return self._get(f"/perfumes/{self._seg(id)}", {"house": house, "format": format, "locale": locale})
+
+    def similar_perfumes(
+        self,
+        perfume: Optional[str] = None,
+        *,
+        house: Optional[str] = None,
+        notes: Optional[Sequence[str] | str] = None,
+        accords: Optional[Sequence[str] | str] = None,
+        steer: Optional[str] = None,
+        gender: Optional[str] = None,
+        other_houses_only: Optional[bool] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        format: Optional[ResponseFormat] = None,
+        locale: Optional[Locale] = None,
+    ) -> FindSimilarPerfumesResponse:
+        """Perfumes that smell like one you name, or like a list of notes and accords."""
+        return self._get("/similar", {
+            "perfume": perfume, "house": house, "notes": notes, "accords": accords, "steer": steer, "gender": gender,
+            "other_houses_only": other_houses_only, "limit": limit, "cursor": cursor, "format": format, "locale": locale,
+        })
+
+    def perfume_alternatives(
+        self,
+        perfume: str,
+        *,
+        house: Optional[str] = None,
+        closeness: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        locale: Optional[Locale] = None,
+    ) -> FindPerfumeAlternativesResponse:
+        """The editors' alternatives to a famous perfume, from other houses."""
+        return self._get("/alternatives", {"perfume": perfume, "house": house, "closeness": closeness, "limit": limit, "cursor": cursor, "locale": locale})
+
+    def explain_note(self, id: str, *, format: Optional[ResponseFormat] = None, locale: Optional[Locale] = None) -> ExplainNoteResponse:
+        """What a fragrance note smells like, what it pairs with and where it leads."""
+        return self._get(f"/notes/{self._seg(id)}", {"format": format, "locale": locale})
+
+    def get_house(self, id: str, *, format: Optional[ResponseFormat] = None, locale: Optional[Locale] = None) -> GetHouseResponse:
+        """A perfume house: country, style, what it is known for, signature perfumes."""
+        return self._get(f"/houses/{self._seg(id)}", {"format": format, "locale": locale})
+
+    def list_houses(
+        self,
+        *,
+        type: Optional[str] = None,
+        country: Optional[str] = None,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        locale: Optional[Locale] = None,
+    ) -> ListHousesResponse:
+        """Browse perfume houses by type, country or name fragment."""
+        return self._get("/houses", {"type": type, "country": country, "query": query, "limit": limit, "cursor": cursor, "locale": locale})
+
+    def search_guides(
+        self,
+        q: Optional[str] = None,
+        *,
+        type: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        locale: Optional[Locale] = None,
+    ) -> SearchGuidesResponse:
+        """10ML perfume guides and articles to read or cite."""
+        return self._get("/guides", {"q": q, "type": type, "limit": limit, "cursor": cursor, "locale": locale})
+
+    def compare_perfumes(self, names: Sequence[str], *, format: Optional[ResponseFormat] = None, locale: Optional[Locale] = None) -> "dict[str, Any]":
+        """Compare 2 to 4 perfumes.
+
+        The REST API has no compare route, so this fetches each profile with :meth:`get_perfume` and diffs notes and
+        accords locally. Returns ``perfumes``, ``not_found``, ``same_family``, ``shared_notes``, ``shared_accords`` and
+        ``only`` (per perfume id: the notes and accords no other compared perfume has).
+        """
+        if not 2 <= len(names) <= 4:
+            raise ValueError("compare_perfumes takes 2 to 4 perfumes")
+        with ThreadPoolExecutor(max_workers=len(names)) as pool:
+            answers = list(pool.map(lambda n: self.get_perfume(n, format=format, locale=locale), names))
+        perfumes: "list[Perfume]" = []
+        not_found: "list[str]" = []
+        for name, answer in zip(names, answers):
+            if answer.get("found") and answer.get("perfume"):
+                perfumes.append(answer["perfume"])
+            else:
+                not_found.append(name)
+        notes = [_notes_of(p) for p in perfumes]
+        accords = [[a.lower() for a in p["accords"]] for p in perfumes]
+
+        def in_all(lists: "list[list[str]]") -> "list[str]":
+            return [x for x in lists[0] if all(x in other for other in lists)] if len(lists) > 1 else []
+
+        only: "dict[str, dict[str, list[str]]]" = {}
+        for i, p in enumerate(perfumes):
+            other_notes = {n for j, lst in enumerate(notes) if j != i for n in lst}
+            other_accords = {a for j, lst in enumerate(accords) if j != i for a in lst}
+            only[p["id"]] = {
+                "notes": [n for n in notes[i] if n not in other_notes],
+                "accords": [a for a in accords[i] if a not in other_accords],
+            }
+        return {
+            "perfumes": perfumes,
+            "not_found": not_found,
+            "same_family": len(perfumes) > 1 and all(p["family"] == perfumes[0]["family"] for p in perfumes),
+            "shared_notes": in_all(notes),
+            "shared_accords": in_all(accords),
+            "only": only,
+        }
+
+
+_default = PerfumeApi()
+search_perfumes = _default.search_perfumes
+get_perfume = _default.get_perfume
+similar_perfumes = _default.similar_perfumes
+perfume_alternatives = _default.perfume_alternatives
+explain_note = _default.explain_note
+get_house = _default.get_house
+list_houses = _default.list_houses
+search_guides = _default.search_guides
+compare_perfumes = _default.compare_perfumes

perfume_api-2.4.0/src/perfume_api/types.py

@@ -0,0 +1,274 @@
+"""Generated by scripts/gen-types.mjs from spec/openapi.json (10ML Fragrance Index API 2.3.4). Do not edit by hand."""
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+
+class _PerfumeRequired(TypedDict):
+    id: str
+    name: str
+    house: str
+    gender: Literal["men", "women", "unisex"]
+    family: str
+    accords: list[str]
+    key_notes: list[str]
+    character: str
+    links: list[Link]
+    profile: Literal["full", "core"]
+
+
+class Perfume(_PerfumeRequired, total=False):
+    year: float
+    concentration: str
+    pyramid: Pyramid
+    seasons: list[str]
+    occasions: list[str]
+    styles: list[str]
+    longevity: float
+    projection: float
+    perfumers: list[str]
+    other_versions: list[str]
+
+
+class Link(TypedDict):
+    type: Literal["try", "guide", "note"]
+    title: str
+    url: str
+
+
+class Pyramid(TypedDict):
+    top: list[str]
+    heart: list[str]
+    base: list[str]
+
+
+class _SearchPerfumesResponseRequired(TypedDict):
+    total: float
+    results: list[Perfume]
+    filters: dict[str, str]
+    relaxed: bool
+    source: str
+
+
+class SearchPerfumesResponse(_SearchPerfumesResponseRequired, total=False):
+    next_cursor: str
+    message: str
+
+
+class _GetPerfumeResponseHouseInfoRequired(TypedDict):
+    name: str
+    type: str
+    style: str
+
+
+class GetPerfumeResponseHouseInfo(_GetPerfumeResponseHouseInfoRequired, total=False):
+    country: str
+
+
+class GetPerfumeResponseSimilarItem(TypedDict):
+    id: str
+    name: str
+    house: str
+    closeness: Literal["very close", "similar vibe", "same spirit"]
+    shared_notes: list[str]
+    url: str
+
+
+class _GetPerfumeResponseAlternativesItemRequired(TypedDict):
+    name: str
+    closeness: Literal["very close", "similar vibe", "same spirit"]
+    why: str
+
+
+class GetPerfumeResponseAlternativesItem(_GetPerfumeResponseAlternativesItemRequired, total=False):
+    house: str
+    id: str
+
+
+class _GetPerfumeResponseRequired(TypedDict):
+    found: bool
+    exact: bool
+    source: str
+
+
+class GetPerfumeResponse(_GetPerfumeResponseRequired, total=False):
+    perfume: Perfume
+    house_info: GetPerfumeResponseHouseInfo
+    similar: list[GetPerfumeResponseSimilarItem]
+    alternatives: list[GetPerfumeResponseAlternativesItem]
+    guides: list[Link]
+    suggestions: list[Perfume]
+    message: str
+
+
+class _FindSimilarPerfumesResponseTargetRequired(TypedDict):
+    name: str
+    house: str | None
+    in_index: bool
+    notes: list[str]
+    accords: list[str]
+
+
+class FindSimilarPerfumesResponseTarget(_FindSimilarPerfumesResponseTargetRequired, total=False):
+    id: str
+
+
+class FindSimilarPerfumesResponseResultsItem(TypedDict):
+    perfume: Perfume
+    closeness: Literal["very close", "similar vibe", "same spirit"]
+    shared_notes: list[str]
+    shared_accords: list[str]
+    why: str
+
+
+class _FindSimilarPerfumesResponseRequired(TypedDict):
+    total: float
+    target: FindSimilarPerfumesResponseTarget
+    results: list[FindSimilarPerfumesResponseResultsItem]
+    source: str
+
+
+class FindSimilarPerfumesResponse(_FindSimilarPerfumesResponseRequired, total=False):
+    next_cursor: str
+    message: str
+    unrecognised_notes: list[str]
+
+
+class _FindPerfumeAlternativesResponseOriginalRequired(TypedDict):
+    name: str
+
+
+class FindPerfumeAlternativesResponseOriginal(_FindPerfumeAlternativesResponseOriginalRequired, total=False):
+    house: str
+    id: str
+
+
+class _FindPerfumeAlternativesResponseAlternativesItemRequired(TypedDict):
+    name: str
+    closeness: Literal["very close", "similar vibe", "same spirit"]
+    why: str
+    source: Literal["editors", "similarity"]
+
+
+class FindPerfumeAlternativesResponseAlternativesItem(_FindPerfumeAlternativesResponseAlternativesItemRequired, total=False):
+    house: str
+    id: str
+
+
+class _FindPerfumeAlternativesResponseRequired(TypedDict):
+    total: float
+    original: FindPerfumeAlternativesResponseOriginal
+    alternatives: list[FindPerfumeAlternativesResponseAlternativesItem]
+    links: list[Link]
+    source: str
+
+
+class FindPerfumeAlternativesResponse(_FindPerfumeAlternativesResponseRequired, total=False):
+    next_cursor: str
+    message: str
+    guide: Link
+    other_matches: list[str]
+
+
+class _ExplainNoteResponseNoteRequired(TypedDict):
+    id: str
+    name: str
+    family: str
+    origin: str
+    smells_like: str
+    mood: str
+    also_called: list[str]
+    pairs_with: list[str]
+    similar_notes: list[str]
+
+
+class ExplainNoteResponseNote(_ExplainNoteResponseNoteRequired, total=False):
+    description: str
+
+
+class _ExplainNoteResponseRequired(TypedDict):
+    found: bool
+    source: str
+
+
+class ExplainNoteResponse(_ExplainNoteResponseRequired, total=False):
+    note: ExplainNoteResponseNote
+    famous_perfumes: list[Perfume]
+    links: list[Link]
+    suggestions: list[str]
+    message: str
+
+
+class _ListHousesResponseHousesItemRequired(TypedDict):
+    id: str
+    name: str
+    type: str
+    perfumes_in_index: float
+    known_for: list[str]
+
+
+class ListHousesResponseHousesItem(_ListHousesResponseHousesItemRequired, total=False):
+    country: str
+    founded: float
+
+
+class _ListHousesResponseRequired(TypedDict):
+    total: float
+    houses: list[ListHousesResponseHousesItem]
+    source: str
+
+
+class ListHousesResponse(_ListHousesResponseRequired, total=False):
+    next_cursor: str
+    message: str
+
+
+class _GetHouseResponseHouseRequired(TypedDict):
+    id: str
+    name: str
+    type: str
+    perfumes_in_index: float
+    known_for: list[str]
+    style: str
+    aliases: list[str]
+
+
+class GetHouseResponseHouse(_GetHouseResponseHouseRequired, total=False):
+    country: str
+    founded: float
+
+
+class _GetHouseResponseRequired(TypedDict):
+    found: bool
+    source: str
+
+
+class GetHouseResponse(_GetHouseResponseRequired, total=False):
+    house: GetHouseResponseHouse
+    signature_perfumes: list[Perfume]
+    links: list[Link]
+    suggestions: list[str]
+    message: str
+
+
+class SearchGuidesResponseGuidesItem(TypedDict):
+    title: str
+    type: str
+    topics: list[str]
+    url: str
+    translated: bool
+
+
+class _SearchGuidesResponseRequired(TypedDict):
+    total: float
+    guides: list[SearchGuidesResponseGuidesItem]
+    source: str
+
+
+class SearchGuidesResponse(_SearchGuidesResponseRequired, total=False):
+    next_cursor: str
+    message: str
+
+
+Locale = Literal["en", "de", "fr", "es", "it", "ro", "el", "hu", "cs", "pl"]
+ResponseFormat = Literal["concise", "detailed"]

perfume_api-2.4.0/tests/smoke.py

@@ -0,0 +1,38 @@
+"""Live smoke test against https://mcp.10ml.com/api/v1 (needs internet). Run: PYTHONPATH=src python tests/smoke.py"""
+import time
+
+from perfume_api import (
+    PerfumeApiError, compare_perfumes, explain_note, get_house, get_perfume, list_houses,
+    perfume_alternatives, search_guides, search_perfumes, similar_perfumes,
+)
+
+
+def step(name, fn):
+    t = time.time()
+    fn()
+    print(f"ok  {name} ({int((time.time() - t) * 1000)} ms)")
+
+
+def invalid():
+    try:
+        search_perfumes(limit=99)
+    except PerfumeApiError as err:
+        assert err.status == 400, err.status
+        return
+    raise AssertionError("expected PerfumeApiError")
+
+
+step("search_perfumes", lambda: (lambda r: (r["total"] > 0 and len(r["results"]) == 3) or 1 / 0)(search_perfumes("fresh citrus summer cologne for men", limit=3)))
+step("search_perfumes notes_include list + gender", lambda: search_perfumes(notes_include=["vanilla", "oud"], gender="men", limit=2)["results"])
+step("get_perfume", lambda: (lambda r: r["found"] or 1 / 0)(get_perfume("Baccarat Rouge 540")))
+step("get_perfume unknown -> found False", lambda: (get_perfume("zzzzqq")["found"] is False) or 1 / 0)
+step("similar_perfumes", lambda: (similar_perfumes("Sauvage", limit=3)["results"]) or 1 / 0)
+step("similar_perfumes from notes", lambda: (similar_perfumes(notes=["saffron", "cedar"], limit=2)["results"]) or 1 / 0)
+step("perfume_alternatives", lambda: (perfume_alternatives("Baccarat Rouge 540", limit=3)["alternatives"]) or 1 / 0)
+step("explain_note", lambda: explain_note("ambroxan")["found"] or 1 / 0)
+step("get_house", lambda: get_house("Creed")["found"] or 1 / 0)
+step("list_houses", lambda: (len(list_houses(type="niche", limit=3)["houses"]) == 3) or 1 / 0)
+step("search_guides", lambda: (search_guides("layering", limit=2)["guides"]) or 1 / 0)
+step("compare_perfumes", lambda: (len(compare_perfumes(["Creed Aventus", "Dior Sauvage"])["perfumes"]) == 2) or 1 / 0)
+step("invalid request raises PerfumeApiError", invalid)
+print("perfume-api live smoke: all passed")

perfume_api-2.4.0/tests/test_client.py

@@ -0,0 +1,103 @@
+"""Unit tests with a mocked transport. Run: python -m unittest discover -s tests -v  (from this folder, with PYTHONPATH=src)"""
+import json
+import unittest
+from urllib.parse import parse_qs, urlparse
+
+from perfume_api import DEFAULT_BASE_URL, PerfumeApi, PerfumeApiError
+
+
+def make(handler):
+    calls = []
+
+    def transport(url, headers, timeout):
+        calls.append({"url": url, "headers": dict(headers), "timeout": timeout})
+        status, body = handler(url)
+        return status, (body if isinstance(body, bytes) else json.dumps(body).encode())
+
+    return PerfumeApi(transport=transport), calls
+
+
+def perfume(id, family, key_notes, accords):
+    return {"id": id, "name": id, "house": "H", "gender": "unisex", "family": family, "accords": accords, "key_notes": key_notes, "character": "x", "links": [], "profile": "core"}
+
+
+class ClientTest(unittest.TestCase):
+    def test_default_base_url(self):
+        self.assertEqual(DEFAULT_BASE_URL, "https://mcp.10ml.com/api/v1")
+
+    def test_search_builds_query(self):
+        api, calls = make(lambda u: (200, {"total": 0, "results": [], "filters": {}, "relaxed": False, "source": "s"}))
+        api.search_perfumes("fresh citrus", notes_include=["vanilla", "oud"], gender="men", limit=3, iconic=True)
+        u = urlparse(calls[0]["url"])
+        q = parse_qs(u.query)
+        self.assertEqual(u.path, "/api/v1/perfumes")
+        self.assertEqual(q["q"], ["fresh citrus"])
+        self.assertEqual(q["notes_include"], ["vanilla,oud"])
+        self.assertEqual(q["limit"], ["3"])
+        self.assertEqual(q["iconic"], ["true"])
+        self.assertNotIn("house", q)
+        self.assertEqual(calls[0]["headers"]["accept"], "application/json")
+
+    def test_path_ids_encoded_and_base_url_configurable(self):
+        api, calls = make(lambda u: (200, {"found": True, "exact": True, "source": "s"}))
+        api.base_url = "https://example.test/v1"
+        api.get_perfume("Baccarat Rouge 540", locale="de")
+        api.explain_note("ambroxan")
+        api.get_house("MFK")
+        self.assertEqual(calls[0]["url"], "https://example.test/v1/perfumes/Baccarat%20Rouge%20540?locale=de")
+        self.assertEqual(calls[1]["url"], "https://example.test/v1/notes/ambroxan")
+        self.assertEqual(calls[2]["url"], "https://example.test/v1/houses/MFK")
+
+    def test_each_method_calls_its_route(self):
+        api, calls = make(lambda u: (200, {}))
+        api.similar_perfumes("Sauvage", steer="fresher")
+        api.perfume_alternatives("Delina")
+        api.list_houses(type="niche", limit=2)
+        api.search_guides("layering")
+        self.assertEqual([urlparse(c["url"]).path for c in calls], ["/api/v1/similar", "/api/v1/alternatives", "/api/v1/houses", "/api/v1/guides"])
+
+    def test_404_returns_body(self):
+        api, _ = make(lambda u: (404, {"found": False, "suggestions": [], "message": "no", "source": "s"}))
+        self.assertFalse(api.get_house("nope")["found"])
+
+    def test_400_raises(self):
+        api, _ = make(lambda u: (400, {"error": {"code": "invalid_request", "message": "limit: too big"}}))
+        with self.assertRaises(PerfumeApiError) as ctx:
+            api.search_perfumes(limit=99)
+        self.assertEqual((ctx.exception.status, ctx.exception.code, str(ctx.exception)), (400, "invalid_request", "limit: too big"))
+
+    def test_non_json_server_error_raises(self):
+        api, _ = make(lambda u: (502, b"bad gateway"))
+        with self.assertRaises(PerfumeApiError) as ctx:
+            api.list_houses()
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (502, "http_error"))
+
+    def test_compare(self):
+        data = {
+            "a": perfume("a", "Woody", ["saffron", "cedar", "amber"], ["woody", "sweet"]),
+            "b": perfume("b", "Woody", ["Saffron", "jasmine"], ["woody", "fresh"]),
+        }
+
+        def handler(url):
+            pid = url.split("?")[0].rsplit("/", 1)[1]
+            if pid in data:
+                return 200, {"found": True, "exact": True, "perfume": data[pid], "source": "s"}
+            return 404, {"found": False, "exact": False, "source": "s"}
+
+        api, _ = make(handler)
+        cmp = api.compare_perfumes(["a", "b", "zzz"])
+        self.assertEqual(cmp["not_found"], ["zzz"])
+        self.assertTrue(cmp["same_family"])
+        self.assertEqual(cmp["shared_notes"], ["saffron"])
+        self.assertEqual(cmp["shared_accords"], ["woody"])
+        self.assertEqual(sorted(cmp["only"]["a"]["notes"]), ["amber", "cedar"])
+        self.assertEqual(cmp["only"]["b"], {"notes": ["jasmine"], "accords": ["fresh"]})
+
+    def test_compare_needs_2_to_4(self):
+        api, _ = make(lambda u: (200, {}))
+        with self.assertRaises(ValueError):
+            api.compare_perfumes(["a"])
+
+
+if __name__ == "__main__":
+    unittest.main()