dopememe 0.1.0a1__tar.gz

dopememe-0.1.0a1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.3
+Name: dopememe
+Version: 0.1.0a1
+Summary: dope.meme for Python, and the dopememe CLI: find meme templates, fill them, get images and permanent URLs.
+Keywords: memes,images,api,sdk,cli
+Author: Patrick Higgins
+Author-email: Patrick Higgins <patrick@nicena.me>
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Dist: httpx2>=2.16.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://dope.meme
+Project-URL: Documentation, https://docs.dope.meme
+Description-Content-Type: text/markdown
+
+# dopememe
+
+dope.meme for Python, and the `dopememe` command line: find meme templates, fill them,
+and get images and permanent URLs.
+
+```sh
+pip install dopememe     # the library
+uvx dopememe --help      # or just the CLI
+```
+
+## The library
+
+```python
+from dopememe import Client
+
+client = Client()  # an API key is optional: DOPEMEME_API_KEY, or api_key=
+
+# Find a template by what you want to say, and read what each slot is for.
+page = client.list_templates(q="preferring the new thing", tag=["slots:2"])
+drake = client.retrieve_template(page.data[0].ref)
+
+# Fill it. The URL is permanent, and nothing is stored.
+render = client.render_meme(
+    {
+        "template": "drake-hotline",
+        "slots": {"reject": "Writing SDKs by hand", "prefer": "Generating them"},
+    }
+)
+print(render.url, render.alt)
+
+# The image itself, as bytes.
+image = client.render_image({"template": "drake-hotline", "slots": {"reject": "a", "prefer": "b"}})
+image.save("drake.webp")
+
+# An embeddable URL, built without a request.
+client.embed_url("drake-hotline", ["Writing SDKs by hand", "Generating them"])
+
+# Save one for a short URL that keeps working.
+meme = client.create_meme(recipe={"template": "drake-hotline", "slots": {"prefer": "this"}})
+```
+
+`AsyncClient` does the same with `await`. Lists page with `list_templates_all(…)`.
+Errors are `dopememe.APIError`, with a stable `code` and every problem's `path` and
+`hint`; `RateLimitError` says how long to wait. A `429` is retried after `Retry-After`,
+and so are brief server errors when the request is safe to repeat.
+
+Python 3.11 or newer. One dependency: `httpx2`.
+
+## The command line
+
+```sh
+dopememe search "preferring the new thing"
+dopememe show drake-hotline
+dopememe render drake-hotline "Writing SDKs by hand" "Generating them"            # its URL
+dopememe render drake-hotline "Writing SDKs by hand" "Generating them" -o drake.png
+dopememe render drake-hotline --slot prefer="Generating them" --preview           # inline, in iTerm2, WezTerm or kitty
+dopememe url drake-hotline "Writing SDKs by hand" "Generating them"               # /g/, no request
+dopememe save drake-hotline "Writing SDKs by hand" "Generating them"
+dopememe login                                                                     # save an API key
+```
+
+Texts fill the template's text slots in reading order; `--slot name=text` names them.
+`--recipe file.json` (or `-` for stdin) takes a whole recipe. `--json` prints what the
+API returned, for scripts and agents.

dopememe-0.1.0a1/README.md

@@ -0,0 +1,64 @@
+# dopememe
+
+dope.meme for Python, and the `dopememe` command line: find meme templates, fill them,
+and get images and permanent URLs.
+
+```sh
+pip install dopememe     # the library
+uvx dopememe --help      # or just the CLI
+```
+
+## The library
+
+```python
+from dopememe import Client
+
+client = Client()  # an API key is optional: DOPEMEME_API_KEY, or api_key=
+
+# Find a template by what you want to say, and read what each slot is for.
+page = client.list_templates(q="preferring the new thing", tag=["slots:2"])
+drake = client.retrieve_template(page.data[0].ref)
+
+# Fill it. The URL is permanent, and nothing is stored.
+render = client.render_meme(
+    {
+        "template": "drake-hotline",
+        "slots": {"reject": "Writing SDKs by hand", "prefer": "Generating them"},
+    }
+)
+print(render.url, render.alt)
+
+# The image itself, as bytes.
+image = client.render_image({"template": "drake-hotline", "slots": {"reject": "a", "prefer": "b"}})
+image.save("drake.webp")
+
+# An embeddable URL, built without a request.
+client.embed_url("drake-hotline", ["Writing SDKs by hand", "Generating them"])
+
+# Save one for a short URL that keeps working.
+meme = client.create_meme(recipe={"template": "drake-hotline", "slots": {"prefer": "this"}})
+```
+
+`AsyncClient` does the same with `await`. Lists page with `list_templates_all(…)`.
+Errors are `dopememe.APIError`, with a stable `code` and every problem's `path` and
+`hint`; `RateLimitError` says how long to wait. A `429` is retried after `Retry-After`,
+and so are brief server errors when the request is safe to repeat.
+
+Python 3.11 or newer. One dependency: `httpx2`.
+
+## The command line
+
+```sh
+dopememe search "preferring the new thing"
+dopememe show drake-hotline
+dopememe render drake-hotline "Writing SDKs by hand" "Generating them"            # its URL
+dopememe render drake-hotline "Writing SDKs by hand" "Generating them" -o drake.png
+dopememe render drake-hotline --slot prefer="Generating them" --preview           # inline, in iTerm2, WezTerm or kitty
+dopememe url drake-hotline "Writing SDKs by hand" "Generating them"               # /g/, no request
+dopememe save drake-hotline "Writing SDKs by hand" "Generating them"
+dopememe login                                                                     # save an API key
+```
+
+Texts fill the template's text slots in reading order; `--slot name=text` names them.
+`--recipe file.json` (or `-` for stdin) takes a whole recipe. `--json` prints what the
+API returned, for scripts and agents.

dopememe-0.1.0a1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "dopememe"
+version = "0.1.0a1"
+description = "dope.meme for Python, and the dopememe CLI: find meme templates, fill them, get images and permanent URLs."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx2>=2.16.0"]
+keywords = [
+    "memes",
+    "images",
+    "api",
+    "sdk",
+    "cli",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Patrick Higgins"
+email = "patrick@nicena.me"
+
+[project.urls]
+Homepage = "https://dope.meme"
+Documentation = "https://docs.dope.meme"
+
+[project.scripts]
+dopememe = "dopememe.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"

dopememe-0.1.0a1/pyproject.toml.orig

@@ -0,0 +1,24 @@
+[project]
+name = "dopememe"
+version = "0.1.0a1"
+description = "dope.meme for Python, and the dopememe CLI: find meme templates, fill them, get images and permanent URLs."
+readme = "README.md"
+authors = [{ name = "Patrick Higgins", email = "patrick@nicena.me" }]
+requires-python = ">=3.11"
+dependencies = ["httpx2>=2.16.0"]
+keywords = ["memes", "images", "api", "sdk", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://dope.meme"
+Documentation = "https://docs.dope.meme"
+
+[project.scripts]
+dopememe = "dopememe.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"

dopememe-0.1.0a1/src/dopememe/__init__.py

@@ -0,0 +1,116 @@
+"""dope.meme for Python: find meme templates, fill them, and get images and permanent URLs.
+
+from dopememe import Client
+
+client = Client()
+render = client.render_meme(
+    {"template": "drake-hotline", "slots": {"reject": "Writing SDKs", "prefer": "Generating them"}}
+)
+print(render.url, render.alt)
+"""
+
+from dopememe._client import DEFAULT_BASE_URL, DEFAULT_IMAGE_BASE_URL, AsyncClient, Client
+from dopememe._operations import API_VERSION, ERROR_CODES
+from dopememe._version import __version__
+from dopememe.errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    DopememeError,
+    RateLimitError,
+)
+from dopememe.images import RenderedImage
+
+# generated: begin
+from dopememe.types import (
+    Anchor,
+    ApiKey,
+    ApiKeyList,
+    AssetFill,
+    At,
+    CreateKey,
+    Example,
+    Facet,
+    Fill,
+    Image,
+    Instance,
+    Item,
+    ItemList,
+    ItemSummary,
+    Me,
+    Meme,
+    MemeList,
+    NewApiKey,
+    Number,
+    Output,
+    Placement,
+    PointAt,
+    Problem,
+    ProblemDetail,
+    Recipe,
+    Render,
+    SaveMeme,
+    Slot,
+    SlotSummary,
+    StyleOverride,
+    TagValue,
+    TextFill,
+    Version,
+    VersionList,
+    Vocabulary,
+)
+
+# generated: end
+
+__all__ = [
+    "API_VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_IMAGE_BASE_URL",
+    "ERROR_CODES",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncClient",
+    "Client",
+    "DopememeError",
+    "RateLimitError",
+    "RenderedImage",
+    "__version__",
+    # generated: begin
+    "Anchor",
+    "ApiKey",
+    "ApiKeyList",
+    "AssetFill",
+    "At",
+    "CreateKey",
+    "Example",
+    "Facet",
+    "Fill",
+    "Image",
+    "Instance",
+    "Item",
+    "ItemList",
+    "ItemSummary",
+    "Me",
+    "Meme",
+    "MemeList",
+    "NewApiKey",
+    "Number",
+    "Output",
+    "Placement",
+    "PointAt",
+    "Problem",
+    "ProblemDetail",
+    "Recipe",
+    "Render",
+    "SaveMeme",
+    "Slot",
+    "SlotSummary",
+    "StyleOverride",
+    "TagValue",
+    "TextFill",
+    "Version",
+    "VersionList",
+    "Vocabulary",
+    # generated: end
+]

dopememe-0.1.0a1/src/dopememe/_client.py

@@ -0,0 +1,363 @@
+"""The HTTP clients: configuration, retries, errors and images. The operations themselves
+are generated (`_operations.py`)."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import time
+from collections.abc import Iterable, Mapping
+from types import TracebackType
+from typing import Any, Self
+
+import httpx2
+
+from dopememe._operations import AsyncOperations, SyncOperations
+from dopememe._version import __version__
+from dopememe.errors import APIConnectionError, APITimeoutError, error_for
+from dopememe.images import EXTENSIONS, Format, RenderedImage, Size, embed_path, image_query
+from dopememe.types import Recipe
+
+DEFAULT_BASE_URL = "https://api.dope.meme"
+DEFAULT_IMAGE_BASE_URL = "https://i.dope.meme"
+# Statuses worth another try: over a limit, or a server or proxy that's briefly unwell.
+RETRYABLE = {429, 502, 503, 504}
+# Longer than this, and a 429 is raised rather than waited out.
+MAX_RETRY_AFTER = 60.0
+
+
+class _Config:
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None,
+        image_base_url: str | None,
+        max_retries: int,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("DOPEMEME_API_KEY")
+        base = base_url or os.environ.get("DOPEMEME_BASE_URL")
+        self.base_url = (base or DEFAULT_BASE_URL).rstrip("/")
+        # Images have their own host in production; elsewhere the API serves them too.
+        image_base = image_base_url or os.environ.get("DOPEMEME_IMAGE_BASE_URL")
+        self.image_base_url = (image_base or (base or DEFAULT_IMAGE_BASE_URL)).rstrip("/")
+        self.max_retries = max_retries
+        self.headers = {"User-Agent": f"dopememe-python/{__version__}"}
+
+    def request_args(
+        self, method: str, path: str, query: Mapping[str, Any] | None, body: Any, accept: str
+    ) -> dict[str, Any]:
+        url = path if "://" in path else self.base_url + path
+        headers = {**self.headers, "Accept": accept}
+        # Only the API sees the key: image URLs are public, and may be another host's.
+        if self.api_key and url.startswith(self.base_url + "/v1/"):
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        args: dict[str, Any] = {"method": method, "url": url, "headers": headers}
+        if query:
+            args["params"] = {k: v for k, v in query.items() if v is not None}
+        if body is not None:
+            # Commands (create_meme's fields) arrive with every argument; send the ones set.
+            args["json"] = (
+                {k: v for k, v in body.items() if v is not None} if isinstance(body, dict) else body
+            )
+        return args
+
+    def retry_delay(
+        self, attempt: int, status: int | None, headers: Mapping[str, str], idempotent: bool
+    ) -> float | None:
+        """Seconds to wait before trying again, or None to give up."""
+        if attempt >= self.max_retries:
+            return None
+        if status is not None and status not in RETRYABLE:
+            return None
+        # A 429 was refused before it did anything; anything else only retries if it's safe.
+        if status != 429 and not idempotent:
+            return None
+        after = headers.get("retry-after")
+        if after and after.isdigit():
+            return float(after) if float(after) <= MAX_RETRY_AFTER else None
+        return min(0.5 * 2**attempt, 8.0) * random.uniform(0.75, 1.25)
+
+
+class Client(SyncOperations):
+    """dope.meme, synchronously.
+
+    The API key comes from `api_key` or `DOPEMEME_API_KEY`, and is optional: anonymous
+    callers can search, render and save unlisted memes, with lower rate limits.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        image_base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx2.Client | None = None,
+    ) -> None:
+        self._config = _Config(api_key, base_url, image_base_url, max_retries)
+        self._http = http_client or httpx2.Client(timeout=timeout)
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    @property
+    def image_base_url(self) -> str:
+        return self._config.image_base_url
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotent: bool = True,
+        accept: str = "application/json",
+    ) -> httpx2.Response:
+        args = self._config.request_args(method, path, query, body, accept)
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(**args)
+            except httpx2.TransportError as error:
+                delay = self._config.retry_delay(attempt, None, {}, idempotent)
+                if delay is None:
+                    kind = (
+                        APITimeoutError
+                        if isinstance(error, httpx2.TimeoutException)
+                        else APIConnectionError
+                    )
+                    raise kind(str(error) or type(error).__name__) from error
+            else:
+                if response.is_success:
+                    return response
+                delay = self._config.retry_delay(
+                    attempt, response.status_code, response.headers, idempotent
+                )
+                if delay is None:
+                    raise error_for(response.status_code, response.content, response.headers)
+            time.sleep(delay)
+            attempt += 1
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        idempotent: bool = True,
+    ) -> Any:
+        response = self._send(method, path, query=query, body=body, idempotent=idempotent)
+        return response.json() if response.content else None
+
+    def render_image(self, recipe: Recipe) -> RenderedImage:
+        """Render a meme and get the image itself, in the recipe's `output` format.
+
+        Its permanent URL, identity and alt text come with it. Nothing is stored."""
+        response = self._send("POST", "/v1/render", body=recipe, accept="image/*")
+        return RenderedImage._from_response(response.content, response.headers)
+
+    def embed_url(
+        self,
+        template: str,
+        texts: Iterable[str] = (),
+        *,
+        format: Format = "png",
+        size: Size | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> str:
+        """An embeddable `/g/` URL, built here without a request: texts fill the
+        template's text slots in reading order. Unpinned templates follow their latest
+        version; pin one (`drake-hotline@1`) for an image that never changes."""
+        path = embed_path(template, texts, format=format, size=size, width=width, height=height)
+        return self.image_base_url + path
+
+    def fetch_image(self, url: str) -> RenderedImage:
+        """Any dope.meme image URL (`/i/…` or `/g/…`), as bytes."""
+        response = self._send("GET", url, accept="image/*")
+        return RenderedImage._from_response(response.content, response.headers)
+
+    def generate_image(
+        self,
+        template: str,
+        texts: Iterable[str] = (),
+        *,
+        format: Format = "png",
+        size: Size | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> RenderedImage:
+        """The image at `embed_url(template, texts, …)`."""
+        return self.fetch_image(
+            self.embed_url(template, texts, format=format, size=size, width=width, height=height)
+        )
+
+    def retrieve_image(
+        self,
+        id: str,
+        *,
+        format: Format = "png",
+        size: Size | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> RenderedImage:
+        """A permanent image by its token (`r1.…`) or saved meme ID (`m_…`)."""
+        query = image_query(size, width, height)
+        return self.fetch_image(f"{self.image_base_url}/i/{id}.{EXTENSIONS[format]}{query}")
+
+
+class AsyncClient(AsyncOperations):
+    """dope.meme, with `async`/`await`. Everything `Client` does, awaited."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        image_base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        self._config = _Config(api_key, base_url, image_base_url, max_retries)
+        self._http = http_client or httpx2.AsyncClient(timeout=timeout)
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    @property
+    def image_base_url(self) -> str:
+        return self._config.image_base_url
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotent: bool = True,
+        accept: str = "application/json",
+    ) -> httpx2.Response:
+        args = self._config.request_args(method, path, query, body, accept)
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(**args)
+            except httpx2.TransportError as error:
+                delay = self._config.retry_delay(attempt, None, {}, idempotent)
+                if delay is None:
+                    kind = (
+                        APITimeoutError
+                        if isinstance(error, httpx2.TimeoutException)
+                        else APIConnectionError
+                    )
+                    raise kind(str(error) or type(error).__name__) from error
+            else:
+                if response.is_success:
+                    return response
+                delay = self._config.retry_delay(
+                    attempt, response.status_code, response.headers, idempotent
+                )
+                if delay is None:
+                    raise error_for(response.status_code, response.content, response.headers)
+            await asyncio.sleep(delay)
+            attempt += 1
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        idempotent: bool = True,
+    ) -> Any:
+        response = await self._send(method, path, query=query, body=body, idempotent=idempotent)
+        return response.json() if response.content else None
+
+    async def render_image(self, recipe: Recipe) -> RenderedImage:
+        """Render a meme and get the image itself. See `Client.render_image`."""
+        response = await self._send("POST", "/v1/render", body=recipe, accept="image/*")
+        return RenderedImage._from_response(response.content, response.headers)
+
+    def embed_url(
+        self,
+        template: str,
+        texts: Iterable[str] = (),
+        *,
+        format: Format = "png",
+        size: Size | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> str:
+        """An embeddable `/g/` URL. See `Client.embed_url`."""
+        path = embed_path(template, texts, format=format, size=size, width=width, height=height)
+        return self.image_base_url + path
+
+    async def fetch_image(self, url: str) -> RenderedImage:
+        """Any dope.meme image URL (`/i/…` or `/g/…`), as bytes."""
+        response = await self._send("GET", url, accept="image/*")
+        return RenderedImage._from_response(response.content, response.headers)
+
+    async def generate_image(
+        self,
+        template: str,
+        texts: Iterable[str] = (),
+        *,
+        format: Format = "png",
+        size: Size | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> RenderedImage:
+        """The image at `embed_url(template, texts, …)`."""
+        return await self.fetch_image(
+            self.embed_url(template, texts, format=format, size=size, width=width, height=height)
+        )
+
+    async def retrieve_image(
+        self,
+        id: str,
+        *,
+        format: Format = "png",
+        size: Size | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> RenderedImage:
+        """A permanent image by its token (`r1.…`) or saved meme ID (`m_…`)."""
+        query = image_query(size, width, height)
+        return await self.fetch_image(f"{self.image_base_url}/i/{id}.{EXTENSIONS[format]}{query}")