makememe 0.1.0__py3-none-any.whl

makememe-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: makememe
+Version: 0.1.0
+Summary: A tiny zero-dependency CLI for generating memes via the free memegen.link API. Agent-friendly.
+Project-URL: Homepage, https://pypi.org/project/makememe/
+Project-URL: memegen.link API, https://api.memegen.link
+Author: Dhruv Mehra
+License: MIT
+License-File: LICENSE
+Keywords: agent,claude,cli,codex,meme,memegen
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# meme
+
+A tiny, zero-dependency CLI for generating memes via the free
+[memegen.link](https://memegen.link) API. No API key, no signup, stdlib-only.
+
+Built to be **agent-friendly**: predictable stdout, a `--json` mode, and a
+bundled Claude Code skill so coding agents (Claude Code, Codex, etc.) can drive
+it directly.
+
+```bash
+meme drake "not reading docs" "reading docs" -o out.png
+```
+
+## Install
+
+Requires Python 3.8+.
+
+```bash
+pip install makememe
+# or, as an isolated tool:
+uv tool install makememe      # or: pipx install makememe
+```
+
+Run once without installing:
+
+```bash
+uvx --from makememe meme drake "a" "b"
+```
+
+## Usage
+
+```bash
+meme <template> "top line" "bottom line" [-o out.png]
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-o, --out` | output file (default `meme.png`) |
+| `--bg URL` | use a custom background image instead of a template |
+| `--ext` | `png` (default), `jpg`, `webp`, or `gif` |
+| `--style` / `--font` | template style variant / font override |
+| `--print-url` | print the image URL, don't download |
+| `--json` | machine-readable output (for scripts/agents) |
+| `--list` | list available template ids |
+
+### Examples
+
+```bash
+meme drake "manual deploys" "ci/cd"
+meme same "after I sold" "if I held" "same picture"
+meme --bg https://example.com/pic.png "_" "DODGED"
+meme regret "SOLD @ 620" "NOW 780 (+26%)" --print-url
+meme --list
+meme --list --json
+```
+
+### Text that starts with `-`
+
+If a caption line begins with `-` (e.g. `"-26%"`), put `--` before your lines so
+it isn't parsed as a flag:
+
+```bash
+meme regret --json -- "-26%" "WHY"
+```
+
+(Put flags like `--json`/`-o` *before* the `--`.)
+
+## For agents (Claude Code / Codex / scripts)
+
+The tool is designed to be parsed:
+
+- **Plain mode** prints *only the output path* to stdout (status goes to stderr),
+  so `path=$(meme drake "a" "b")` just works.
+- **`--json` mode** prints a single JSON object:
+
+  ```json
+  { "path": "meme.png", "bytes": 12345, "url": "https://api.memegen.link/..." }
+  ```
+
+  `--list --json` returns the template catalog as JSON; `--print-url --json`
+  returns `{"url": "..."}`; failures return `{"error": "...", "url": "..."}`
+  with a non-zero exit code.
+
+Typical agent flow:
+
+```bash
+meme --list --json                       # discover template ids
+meme drake "old way" "new way" --json    # generate, capture the path
+```
+
+### Claude Code skill
+
+A ready-made skill lives in [`skill/meme/`](skill/meme/SKILL.md). Install it so
+Claude Code auto-discovers the tool:
+
+```bash
+# user-level (all projects)
+mkdir -p ~/.claude/skills
+cp -r skill/meme ~/.claude/skills/meme
+
+# or project-level
+mkdir -p .claude/skills
+cp -r skill/meme .claude/skills/meme
+```
+
+Then just ask Claude Code things like *"make a drake meme about writing tests"*
+and it will call `meme` for you.
+
+## Robustness
+
+The CLI is built to fail gracefully, never with a raw traceback:
+
+- Network errors, dead hosts, bad template ids (404), oversized text (414), and
+  non-image backgrounds (415) all exit non-zero with a one-line message — and
+  **no partial/garbage file is written**.
+- `Ctrl-C` exits cleanly (code 130); piping into `head` etc. won't spew a
+  `BrokenPipeError`.
+- Arbitrary text — emoji, CJK, `% # & / ? " \`, tabs, control chars, 10k-char
+  lines — is escaped safely.
+
+Run the test suite (stdlib only, no network needed):
+
+```bash
+python -m unittest discover -s tests
+```
+
+## How it works
+
+It builds a memegen.link URL from your template + text (handling all the fiddly
+path-segment escaping — spaces, `_`, `-`, `?`, `/`, `%`, etc.), downloads the
+image, and saves it. That's the whole trick.
+
+## License
+
+MIT

makememe-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+memecli/__init__.py,sha256=EE9SwxUJO-M12n6gndkv9FRmwGpUVLp6in5PnNabgKs,248
+memecli/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+memecli/cli.py,sha256=5SXEU2hMt3Q-uvEFHZRW_XmV6mutQ_jeChfWD81T3nU,6359
+makememe-0.1.0.dist-info/METADATA,sha256=7xhT3cJmr5rdEeqAQxkG-t1jO-Gkjm-_XNeYK29DcMY,4303
+makememe-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+makememe-0.1.0.dist-info/entry_points.txt,sha256=ljxdezWRFBcA7ejxPFh_gEnuxKRf9MISdSYdC94VXBA,42
+makememe-0.1.0.dist-info/licenses/LICENSE,sha256=gguAGcIQbbkCVERLQSJFmckVv0LJD-mHUA5ygWMzofQ,1068
+makememe-0.1.0.dist-info/RECORD,,

makememe-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

makememe-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+meme = memecli.cli:main

makememe-0.1.0.dist-info/licenses/LICENSE

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

memecli/__init__.py

@@ -0,0 +1,6 @@
+"""meme - a tiny zero-dependency CLI over the free memegen.link API."""
+
+from .cli import build_url, download, escape, get_templates, main
+
+__version__ = "0.1.0"
+__all__ = ["main", "build_url", "escape", "download", "get_templates", "__version__"]

memecli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

memecli/cli.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+meme - a tiny CLI over the free memegen.link API.
+
+Builds a meme image URL from a template + text lines, downloads it, saves an
+image. No API key, no third-party dependencies (Python stdlib only). Handles URL
+escaping so you never hit the bare-% problem.
+
+Examples:
+    meme drake "not reading docs" "reading docs"
+    meme regret "SOLD IRCTC @ Rs620" "NOW Rs780 (+26%) WHY"
+    meme same "after I sold" "if I held" "same picture"
+    meme --bg https://example.com/pic.png "_" "DODGED"
+    meme drake "a" "b" --print-url        # just print the URL, don't download
+    meme drake "a" "b" --json             # machine-readable output for agents
+    meme --list                           # list available template ids
+    meme --list --json                    # template ids as JSON
+
+Find templates: https://api.memegen.link/templates/  (or `meme --list`)
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.parse
+import urllib.request
+
+API = "https://api.memegen.link"
+
+
+# memegen path-segment escaping. Order matters: escape the escape chars first.
+# Confirmed from the API: space->_, _->__, -->--, ?->~q, newline->~n, "->''
+# Others use memegen's documented tilde codes; verify with --print-url if unsure.
+def escape(text):
+    if text == "":
+        return "_"  # memegen renders an empty line as a single underscore
+    text = text.replace("_", "__").replace("-", "--")
+    text = text.replace(" ", "_").replace("\n", "~n")
+    text = text.replace("?", "~q").replace('"', "''").replace("/", "~s")
+    # let quote percent-encode the rest (%, #, etc) - memegen decodes %25 reliably.
+    # keep the memegen tokens we just produced intact.
+    return urllib.parse.quote(text, safe="_~'.!*()")
+
+
+def build_url(template, lines, ext="png", bg=None, style=None, font=None):
+    parts = [escape(l) for l in lines] if lines else ["_"]
+    base = "custom" if bg else template
+    path = "/".join(parts)
+    url = f"{API}/images/{base}/{path}.{ext}"
+    q = {}
+    if bg:
+        q["background"] = bg
+    if style:
+        q["style"] = style
+    if font:
+        q["font"] = font
+    if q:
+        url += "?" + urllib.parse.urlencode(q)
+    return url
+
+
+def get_templates(timeout=20):
+    req = urllib.request.Request(
+        f"{API}/templates/", headers={"User-Agent": "meme-cli"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.load(r)
+
+
+def list_templates(as_json=False):
+    data = get_templates()
+    if as_json:
+        slim = [
+            {"id": t["id"], "lines": t.get("lines"), "name": t["name"]}
+            for t in data
+        ]
+        print(json.dumps(slim, indent=2))
+        return
+    for t in data:
+        print(f"{t['id']:<18} {t.get('lines', '?')} lines  {t['name']}")
+
+
+def download(url, out, timeout=30):
+    req = urllib.request.Request(url, headers={"User-Agent": "meme-cli"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        data = r.read()
+    with open(out, "wb") as f:
+        f.write(data)
+    return len(data)
+
+
+def build_parser():
+    ap = argparse.ArgumentParser(
+        prog="meme", description="Generate a meme via memegen.link.",
+        epilog="Tip: if a text line starts with '-' (e.g. \"-26%\"), put '--' "
+               "before your lines so it isn't read as a flag:\n"
+               "  meme regret --json -- \"-26%\" \"WHY\"",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("template", nargs="?",
+                    help="template id (see --list), or any id when using --bg")
+    ap.add_argument("lines", nargs="*", help="text lines, in order")
+    ap.add_argument("-o", "--out", default="meme.png",
+                    help="output file (default meme.png)")
+    ap.add_argument("--bg",
+                    help="custom background image URL (uses the 'custom' template)")
+    ap.add_argument("--ext", default="png", choices=["png", "jpg", "webp", "gif"])
+    ap.add_argument("--style", help="template style variant, if any")
+    ap.add_argument("--font", help="font name (see /fonts/)")
+    ap.add_argument("--print-url", action="store_true",
+                    help="print the URL and exit, no download")
+    ap.add_argument("--json", action="store_true",
+                    help="emit machine-readable JSON (good for agents/scripts)")
+    ap.add_argument("--list", action="store_true",
+                    help="list template ids and exit")
+    return ap
+
+
+def _run(argv=None):
+    ap = build_parser()
+    args = ap.parse_args(argv)
+
+    if args.list:
+        try:
+            list_templates(as_json=args.json)
+        except Exception as e:
+            sys.exit(f"could not fetch templates: {e}")
+        return
+
+    if not args.template and not args.bg:
+        ap.error("a template id is required (or use --bg for a custom background)")
+
+    # with --bg there is no template positional, so fold it back into the lines
+    if args.bg:
+        lines = ([args.template] if args.template else []) + args.lines
+        template = "custom"
+    else:
+        lines = args.lines
+        template = args.template
+
+    url = build_url(template, lines, args.ext, args.bg, args.style, args.font)
+
+    if args.print_url:
+        if args.json:
+            print(json.dumps({"url": url}))
+        else:
+            print(url)
+        return
+
+    try:
+        n = download(url, args.out)
+    except Exception as e:
+        if args.json:
+            print(json.dumps({"error": str(e), "url": url}))
+            sys.exit(1)
+        sys.exit(f"download failed: {e}\nurl was: {url}")
+
+    if args.json:
+        print(json.dumps({"path": args.out, "bytes": n, "url": url}))
+    else:
+        print(args.out)                   # stdout: just the path, easy to capture
+        print(f"saved {n} bytes from {url}", file=sys.stderr)
+
+
+def main(argv=None):
+    """Entry point. Wraps _run so the CLI never dies with a raw traceback."""
+    try:
+        return _run(argv)
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        sys.exit(130)
+    except BrokenPipeError:
+        # downstream closed the pipe (e.g. `meme --list | head`). Silence the
+        # traceback Python would otherwise emit when flushing stdout at exit.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()