shinobitools 0.1.0__tar.gz

shinobitools-0.1.0/LICENSE

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

shinobitools-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: shinobitools
+Version: 0.1.0
+Summary: Free image, PDF, video and passport-photo APIs. No key, no account, no dependencies.
+Author: ShinobiTools
+License: MIT
+Project-URL: Homepage, https://shinobitools.com
+Project-URL: Documentation, https://bgninja.com/api.html
+Project-URL: Source, https://github.com/ShinobiTools/shinobitools-py
+Keywords: background-removal,remove-background,pdf,pdf-merge,ocr,passport-photo,video-to-gif,vectorize,svg,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# shinobitools
+
+Python client for the free [ShinobiTools](https://shinobitools.com) APIs.
+No API key, no account, no sign-up, and **no dependencies** — it uses nothing but the
+standard library, so installing it pulls in nothing else.
+
+```bash
+pip install shinobitools
+```
+
+```python
+from shinobitools import remove_background
+
+open("cutout.png", "wb").write(remove_background("photo.jpg"))
+```
+
+That is the whole thing. No client object, no configuration, no key to rotate.
+
+## What it can do
+
+| Function | What happens | Docs |
+|---|---|---|
+| `remove_background(image, background=None)` | Transparent PNG, or composited onto a hex colour | [bgninja.com/api.html](https://bgninja.com/api.html) |
+| `passport_photo(image, country="eu")` | A compliant passport photo, plus the head height it measured | [passportninja.com/api.html](https://passportninja.com/api.html) |
+| `pdf_merge(a, b, ...)` | One PDF out of several | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `pdf_compress(pdf, level="good")` | A smaller PDF | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `ocr_text(pdf)` | The text out of a scanned PDF | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `video_to_gif(video, fps=12, width=480)` | A GIF | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+| `video_to_mp3(video)` | The audio track | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+| `vectorize(image, mode="color")` | An SVG traced from a raster image | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+
+Every function accepts a path, an open file, or raw bytes.
+
+## Examples
+
+```python
+from shinobitools import passport_photo, fetch_result
+
+job = passport_photo("portrait.jpg", country="nl")
+print(job["head_mm"], job["head_range_mm"])     # e.g. 34.2 [32.0, 36.0]
+open("passport.png", "wb").write(fetch_result(job))
+```
+
+The passport endpoint hands back the head height it produced and the range the country
+requires, so you can check compliance in your own code instead of trusting the crop.
+
+```python
+from shinobitools import pdf_merge, ocr_text, vectorize
+
+open("all.pdf", "wb").write(pdf_merge("a.pdf", "b.pdf", "c.pdf"))
+print(ocr_text("scan.pdf")[:200])
+open("logo.svg", "wb").write(vectorize("logo.png"))
+```
+
+## When something goes wrong
+
+```python
+from shinobitools import remove_background, ShinobiError
+
+try:
+    remove_background("notes.txt")
+except ShinobiError as e:
+    print(e.status, e.message)   # 400 can't read this file (TXT) — please upload a photo…
+```
+
+`ShinobiError` carries the HTTP status and the service's own message. A `429` means you
+already have the maximum number of requests running from your address; wait for one to
+finish and retry the same file. There is no daily cap to back off from.
+
+## Limits
+
+These are the free limits, enforced server side. The per-service documentation linked
+above is the authority; this table is a summary.
+
+| | |
+|---|---|
+| Background removal | 99 MB, 30 megapixels, 2 running at once per IP |
+| PDF work | 25 MB per file, 30 pages, 1 job at a time, results kept 45 minutes |
+| Passport photos | 99 MB, 3 running at once per IP, results kept 45 minutes |
+| Video and audio | 400 MB |
+| Requests per day | no cap on any of them |
+
+Nothing is written to disk on the image endpoints: your file is processed in memory and
+the response is the result.
+
+## Why this is free
+
+These services are run by the people who wrote this package, and they stay free because
+enough people find them. The client sends a `src` label so we can see that integrations
+exist at all — please leave it in. If your project lists what it uses, a link back to
+[shinobitools.com](https://shinobitools.com) is the whole business model.
+
+Planning to push serious volume through it? Say hello first via any of the contact pages
+linked above. We would rather hear from you than throttle you.
+
+## Tests
+
+```bash
+python3 tests/test_client.py            # offline
+LIVE=1 python3 tests/test_client.py     # plus one real call
+```
+
+## Licence
+
+MIT.

shinobitools-0.1.0/README.md

@@ -0,0 +1,105 @@
+# shinobitools
+
+Python client for the free [ShinobiTools](https://shinobitools.com) APIs.
+No API key, no account, no sign-up, and **no dependencies** — it uses nothing but the
+standard library, so installing it pulls in nothing else.
+
+```bash
+pip install shinobitools
+```
+
+```python
+from shinobitools import remove_background
+
+open("cutout.png", "wb").write(remove_background("photo.jpg"))
+```
+
+That is the whole thing. No client object, no configuration, no key to rotate.
+
+## What it can do
+
+| Function | What happens | Docs |
+|---|---|---|
+| `remove_background(image, background=None)` | Transparent PNG, or composited onto a hex colour | [bgninja.com/api.html](https://bgninja.com/api.html) |
+| `passport_photo(image, country="eu")` | A compliant passport photo, plus the head height it measured | [passportninja.com/api.html](https://passportninja.com/api.html) |
+| `pdf_merge(a, b, ...)` | One PDF out of several | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `pdf_compress(pdf, level="good")` | A smaller PDF | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `ocr_text(pdf)` | The text out of a scanned PDF | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `video_to_gif(video, fps=12, width=480)` | A GIF | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+| `video_to_mp3(video)` | The audio track | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+| `vectorize(image, mode="color")` | An SVG traced from a raster image | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+
+Every function accepts a path, an open file, or raw bytes.
+
+## Examples
+
+```python
+from shinobitools import passport_photo, fetch_result
+
+job = passport_photo("portrait.jpg", country="nl")
+print(job["head_mm"], job["head_range_mm"])     # e.g. 34.2 [32.0, 36.0]
+open("passport.png", "wb").write(fetch_result(job))
+```
+
+The passport endpoint hands back the head height it produced and the range the country
+requires, so you can check compliance in your own code instead of trusting the crop.
+
+```python
+from shinobitools import pdf_merge, ocr_text, vectorize
+
+open("all.pdf", "wb").write(pdf_merge("a.pdf", "b.pdf", "c.pdf"))
+print(ocr_text("scan.pdf")[:200])
+open("logo.svg", "wb").write(vectorize("logo.png"))
+```
+
+## When something goes wrong
+
+```python
+from shinobitools import remove_background, ShinobiError
+
+try:
+    remove_background("notes.txt")
+except ShinobiError as e:
+    print(e.status, e.message)   # 400 can't read this file (TXT) — please upload a photo…
+```
+
+`ShinobiError` carries the HTTP status and the service's own message. A `429` means you
+already have the maximum number of requests running from your address; wait for one to
+finish and retry the same file. There is no daily cap to back off from.
+
+## Limits
+
+These are the free limits, enforced server side. The per-service documentation linked
+above is the authority; this table is a summary.
+
+| | |
+|---|---|
+| Background removal | 99 MB, 30 megapixels, 2 running at once per IP |
+| PDF work | 25 MB per file, 30 pages, 1 job at a time, results kept 45 minutes |
+| Passport photos | 99 MB, 3 running at once per IP, results kept 45 minutes |
+| Video and audio | 400 MB |
+| Requests per day | no cap on any of them |
+
+Nothing is written to disk on the image endpoints: your file is processed in memory and
+the response is the result.
+
+## Why this is free
+
+These services are run by the people who wrote this package, and they stay free because
+enough people find them. The client sends a `src` label so we can see that integrations
+exist at all — please leave it in. If your project lists what it uses, a link back to
+[shinobitools.com](https://shinobitools.com) is the whole business model.
+
+Planning to push serious volume through it? Say hello first via any of the contact pages
+linked above. We would rather hear from you than throttle you.
+
+## Tests
+
+```bash
+python3 tests/test_client.py            # offline
+LIVE=1 python3 tests/test_client.py     # plus one real call
+```
+
+## Licence
+
+MIT.

shinobitools-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shinobitools"
+version = "0.1.0"
+description = "Free image, PDF, video and passport-photo APIs. No key, no account, no dependencies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "ShinobiTools" }]
+keywords = [
+  "background-removal", "remove-background", "pdf", "pdf-merge", "ocr",
+  "passport-photo", "video-to-gif", "vectorize", "svg", "api-client",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics :: Graphics Conversion",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://shinobitools.com"
+Documentation = "https://bgninja.com/api.html"
+Source = "https://github.com/ShinobiTools/shinobitools-py"
+
+[tool.setuptools.packages.find]
+include = ["shinobitools*"]

shinobitools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shinobitools-0.1.0/shinobitools/__init__.py

@@ -0,0 +1,200 @@
+"""Thin Python client for the free ShinobiTools APIs.
+
+No API key, no account, no dependencies. Every function takes a path (or bytes) and
+returns bytes or a dict, so you can drop it into a script without thinking about it.
+
+    from shinobitools import remove_background
+    open("out.png", "wb").write(remove_background("photo.jpg"))
+
+Docs for the underlying HTTP APIs:
+    https://bgninja.com/api.html                background removal
+    https://scanreviver.com/pdf-api             PDF work and OCR
+    https://passportninja.com/api.html          passport photos
+    https://convert.shinobitools.com/api.html   video, audio and vector
+
+The services are free within published limits and are run by the people who wrote this
+package. If this ends up in something you build, a link back is the whole business model.
+"""
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import urllib.error
+import urllib.request
+import uuid
+
+__version__ = "0.1.0"
+__all__ = [
+    "remove_background", "passport_photo", "pdf_merge", "pdf_compress",
+    "ocr_text", "video_to_gif", "video_to_mp3", "vectorize",
+    "ShinobiError", "SRC",
+]
+
+# Identifies this package to the service. It is the only way we can tell that an
+# integration exists, which is what keeps the APIs worth running. Please leave it.
+SRC = "shinobitools-py"
+
+BGNINJA = "https://bgninja.com"
+SCANREVIVER = "https://scanreviver.com"
+PASSPORTNINJA = "https://passportninja.com"
+CONVERT = "https://convert.shinobitools.com"
+
+TIMEOUT = 300
+
+
+class ShinobiError(RuntimeError):
+    """The service refused the request. `status` is the HTTP code, `message` its reason."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+
+
+def _bytes_van(bestand) -> tuple[bytes, str]:
+    """Accepteert een pad, een open bestand of kale bytes. Geeft (inhoud, naam)."""
+    if isinstance(bestand, (bytes, bytearray)):
+        return bytes(bestand), "upload"
+    if hasattr(bestand, "read"):
+        inhoud = bestand.read()
+        return inhoud, os.path.basename(getattr(bestand, "name", "upload"))
+    with open(bestand, "rb") as f:
+        return f.read(), os.path.basename(str(bestand))
+
+
+def _multipart(velden: dict, bestanden: list[tuple[str, bytes, str]]) -> tuple[bytes, str]:
+    """Bouwt een multipart/form-data-body met alleen de standaardbibliotheek.
+
+    Bewust geen `requests`: dit pakket heeft nul afhankelijkheden, en dat is voor een
+    kleine client een echte eigenschap — wie het installeert krijgt niets anders mee.
+    """
+    grens = f"----shinobitools{uuid.uuid4().hex}"
+    delen: list[bytes] = []
+    for naam, waarde in velden.items():
+        if waarde is None:
+            continue
+        delen.append(
+            f"--{grens}\r\nContent-Disposition: form-data; name=\"{naam}\"\r\n\r\n"
+            f"{waarde}\r\n".encode()
+        )
+    for naam, inhoud, bestandsnaam in bestanden:
+        soort = mimetypes.guess_type(bestandsnaam)[0] or "application/octet-stream"
+        delen.append(
+            f"--{grens}\r\nContent-Disposition: form-data; "
+            f"name=\"{naam}\"; filename=\"{bestandsnaam}\"\r\n"
+            f"Content-Type: {soort}\r\n\r\n".encode()
+        )
+        delen.append(inhoud)
+        delen.append(b"\r\n")
+    delen.append(f"--{grens}--\r\n".encode())
+    return b"".join(delen), f"multipart/form-data; boundary={grens}"
+
+
+# Cloudflare weigert urllib's standaard User-Agent met "403 error code: 1010" (gemeten
+# 02-09-2026 op de echte API). Zonder deze kop faalt élke aanroep uit dit pakket, dus hij
+# hoort in de client en niet in de handleiding.
+UA = f"shinobitools-py/{__version__} (+https://shinobitools.com)"
+
+
+def _post(url: str, velden: dict, bestanden: list[tuple[str, bytes, str]]):
+    velden = {"src": SRC, **velden}
+    body, soort = _multipart(velden, bestanden)
+    req = urllib.request.Request(
+        url, data=body, headers={"Content-Type": soort, "User-Agent": UA})
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
+            rauw = r.read()
+            if "json" in (r.headers.get("Content-Type") or ""):
+                return json.loads(rauw.decode())
+            return rauw
+    except urllib.error.HTTPError as e:
+        rauw = e.read().decode(errors="replace")
+        try:
+            boodschap = json.loads(rauw).get("detail") or json.loads(rauw).get("error") or rauw
+        except Exception:                                        # noqa: BLE001
+            boodschap = rauw
+        raise ShinobiError(e.code, str(boodschap)[:400]) from None
+
+
+def _get(url: str) -> bytes:
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": UA})
+        with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
+            return r.read()
+    except urllib.error.HTTPError as e:
+        raise ShinobiError(e.code, e.read().decode(errors="replace")[:400]) from None
+
+
+# ── bgninja ────────────────────────────────────────────────────────────────────
+def remove_background(image, background: str | None = None) -> bytes:
+    """Remove the background from an image. Returns PNG bytes.
+
+    `background` is a hex colour without the '#', e.g. "ffffff". Leave it out for a
+    transparent background.
+    """
+    inhoud, naam = _bytes_van(image)
+    return _post(f"{BGNINJA}/api/remove", {"bg": background}, [("file", inhoud, naam)])
+
+
+# ── passportninja ──────────────────────────────────────────────────────────────
+def passport_photo(image, country: str = "eu") -> dict:
+    """Turn a portrait into a passport photo. Returns the service's JSON.
+
+    The result includes `head_mm` and `head_range_mm`, so you can check compliance
+    yourself. Add `photo_bytes()` on the returned dict via `fetch_result`.
+    """
+    inhoud, naam = _bytes_van(image)
+    return _post(f"{PASSPORTNINJA}/api/photo", {"country": country}, [("file", inhoud, naam)])
+
+
+def fetch_result(job: dict, key: str = "photo") -> bytes:
+    """Download one of the files a passport job produced, e.g. "photo" or "sheet"."""
+    pad = job[key]
+    return _get(pad if pad.startswith("http") else PASSPORTNINJA + pad)
+
+
+# ── scanreviver ────────────────────────────────────────────────────────────────
+def pdf_merge(*pdfs) -> bytes:
+    """Merge two or more PDFs into one. Returns the merged PDF."""
+    if len(pdfs) < 2:
+        raise ValueError("merging needs at least two PDFs")
+    bestanden = []
+    for p in pdfs:
+        inhoud, naam = _bytes_van(p)
+        bestanden.append(("files", inhoud, naam))
+    job = _post(f"{SCANREVIVER}/api/pdf-merge", {}, bestanden)
+    return _get(f"{SCANREVIVER}/api/pdf-file/{job['id']}")
+
+
+def pdf_compress(pdf, level: str = "good") -> bytes:
+    """Compress a PDF. `level` is the strength the service accepts, "good" by default."""
+    inhoud, naam = _bytes_van(pdf)
+    job = _post(f"{SCANREVIVER}/api/pdf-compress", {"level": level}, [("file", inhoud, naam)])
+    return _get(f"{SCANREVIVER}/api/pdf-file/{job['id']}")
+
+
+def ocr_text(pdf) -> str:
+    """Read the text out of a scanned PDF. Returns the recognised text."""
+    inhoud, naam = _bytes_van(pdf)
+    return _post(f"{SCANREVIVER}/api/ocr-text", {}, [("file", inhoud, naam)])["text"]
+
+
+# ── convert ────────────────────────────────────────────────────────────────────
+def video_to_gif(video, fps: float = 12.0, width: int = 480) -> bytes:
+    """Turn a video into a GIF. Returns GIF bytes."""
+    inhoud, naam = _bytes_van(video)
+    return _post(f"{CONVERT}/api/gif", {"fps": fps, "breedte": width},
+                 [("file", inhoud, naam)])
+
+
+def video_to_mp3(video) -> bytes:
+    """Pull the audio track out of a video. Returns MP3 bytes."""
+    inhoud, naam = _bytes_van(video)
+    return _post(f"{CONVERT}/api/audio", {"formaat": "mp3"}, [("file", inhoud, naam)])
+
+
+def vectorize(image, mode: str = "color") -> bytes:
+    """Trace a raster image into an SVG. Returns SVG bytes. Best on flat artwork."""
+    inhoud, naam = _bytes_van(image)
+    return _post(f"{CONVERT}/api/vectorize", {"modus": mode}, [("file", inhoud, naam)])

shinobitools-0.1.0/shinobitools.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: shinobitools
+Version: 0.1.0
+Summary: Free image, PDF, video and passport-photo APIs. No key, no account, no dependencies.
+Author: ShinobiTools
+License: MIT
+Project-URL: Homepage, https://shinobitools.com
+Project-URL: Documentation, https://bgninja.com/api.html
+Project-URL: Source, https://github.com/ShinobiTools/shinobitools-py
+Keywords: background-removal,remove-background,pdf,pdf-merge,ocr,passport-photo,video-to-gif,vectorize,svg,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# shinobitools
+
+Python client for the free [ShinobiTools](https://shinobitools.com) APIs.
+No API key, no account, no sign-up, and **no dependencies** — it uses nothing but the
+standard library, so installing it pulls in nothing else.
+
+```bash
+pip install shinobitools
+```
+
+```python
+from shinobitools import remove_background
+
+open("cutout.png", "wb").write(remove_background("photo.jpg"))
+```
+
+That is the whole thing. No client object, no configuration, no key to rotate.
+
+## What it can do
+
+| Function | What happens | Docs |
+|---|---|---|
+| `remove_background(image, background=None)` | Transparent PNG, or composited onto a hex colour | [bgninja.com/api.html](https://bgninja.com/api.html) |
+| `passport_photo(image, country="eu")` | A compliant passport photo, plus the head height it measured | [passportninja.com/api.html](https://passportninja.com/api.html) |
+| `pdf_merge(a, b, ...)` | One PDF out of several | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `pdf_compress(pdf, level="good")` | A smaller PDF | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `ocr_text(pdf)` | The text out of a scanned PDF | [scanreviver.com/pdf-api](https://scanreviver.com/pdf-api) |
+| `video_to_gif(video, fps=12, width=480)` | A GIF | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+| `video_to_mp3(video)` | The audio track | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+| `vectorize(image, mode="color")` | An SVG traced from a raster image | [convert.shinobitools.com/api.html](https://convert.shinobitools.com/api.html) |
+
+Every function accepts a path, an open file, or raw bytes.
+
+## Examples
+
+```python
+from shinobitools import passport_photo, fetch_result
+
+job = passport_photo("portrait.jpg", country="nl")
+print(job["head_mm"], job["head_range_mm"])     # e.g. 34.2 [32.0, 36.0]
+open("passport.png", "wb").write(fetch_result(job))
+```
+
+The passport endpoint hands back the head height it produced and the range the country
+requires, so you can check compliance in your own code instead of trusting the crop.
+
+```python
+from shinobitools import pdf_merge, ocr_text, vectorize
+
+open("all.pdf", "wb").write(pdf_merge("a.pdf", "b.pdf", "c.pdf"))
+print(ocr_text("scan.pdf")[:200])
+open("logo.svg", "wb").write(vectorize("logo.png"))
+```
+
+## When something goes wrong
+
+```python
+from shinobitools import remove_background, ShinobiError
+
+try:
+    remove_background("notes.txt")
+except ShinobiError as e:
+    print(e.status, e.message)   # 400 can't read this file (TXT) — please upload a photo…
+```
+
+`ShinobiError` carries the HTTP status and the service's own message. A `429` means you
+already have the maximum number of requests running from your address; wait for one to
+finish and retry the same file. There is no daily cap to back off from.
+
+## Limits
+
+These are the free limits, enforced server side. The per-service documentation linked
+above is the authority; this table is a summary.
+
+| | |
+|---|---|
+| Background removal | 99 MB, 30 megapixels, 2 running at once per IP |
+| PDF work | 25 MB per file, 30 pages, 1 job at a time, results kept 45 minutes |
+| Passport photos | 99 MB, 3 running at once per IP, results kept 45 minutes |
+| Video and audio | 400 MB |
+| Requests per day | no cap on any of them |
+
+Nothing is written to disk on the image endpoints: your file is processed in memory and
+the response is the result.
+
+## Why this is free
+
+These services are run by the people who wrote this package, and they stay free because
+enough people find them. The client sends a `src` label so we can see that integrations
+exist at all — please leave it in. If your project lists what it uses, a link back to
+[shinobitools.com](https://shinobitools.com) is the whole business model.
+
+Planning to push serious volume through it? Say hello first via any of the contact pages
+linked above. We would rather hear from you than throttle you.
+
+## Tests
+
+```bash
+python3 tests/test_client.py            # offline
+LIVE=1 python3 tests/test_client.py     # plus one real call
+```
+
+## Licence
+
+MIT.

shinobitools-0.1.0/shinobitools.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+shinobitools/__init__.py
+shinobitools.egg-info/PKG-INFO
+shinobitools.egg-info/SOURCES.txt
+shinobitools.egg-info/dependency_links.txt
+shinobitools.egg-info/top_level.txt
+tests/test_client.py

shinobitools-0.1.0/shinobitools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shinobitools-0.1.0/shinobitools.egg-info/top_level.txt

@@ -0,0 +1 @@
+shinobitools

shinobitools-0.1.0/tests/test_client.py

@@ -0,0 +1,82 @@
+"""Eén controle die faalt zodra de multipart-opbouw stukgaat.
+
+Dat is het enige echt niet-triviale stuk in dit pakket: de rest is een URL en een
+JSON-sleutel. Draait zonder net.
+
+    python3 tests/test_client.py          # offline, altijd
+    LIVE=1 python3 tests/test_client.py   # ook één echte aanroep naar de API
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from shinobitools import SRC, _bytes_van, _multipart, remove_background  # noqa: E402
+
+
+def test_multipart():
+    body, soort = _multipart({"src": SRC, "bg": "ffffff", "leeg": None},
+                             [("file", b"\x89PNG-nep", "kat.png")])
+    tekst = body.decode("latin-1")
+
+    grens = soort.split("boundary=")[1]
+    assert soort.startswith("multipart/form-data; "), soort
+    # de scheiding moet echt in de body staan, en de body moet erop eindigen
+    assert tekst.startswith(f"--{grens}\r\n"), "body begint niet met de scheiding"
+    assert tekst.endswith(f"--{grens}--\r\n"), "body sluit niet af met de slot-scheiding"
+    # gewone velden
+    assert 'name="src"' in tekst and SRC in tekst
+    assert 'name="bg"' in tekst and "ffffff" in tekst
+    # None-velden horen NIET mee te gaan: anders stuurt de client de tekst "None"
+    assert 'name="leeg"' not in tekst, "een leeg veld werd toch meegestuurd"
+    # bestand met naam, type en de rauwe bytes
+    assert 'name="file"; filename="kat.png"' in tekst
+    assert "Content-Type: image/png" in tekst
+    assert b"\x89PNG-nep" in body, "de bestandsinhoud staat niet in de body"
+    print("  multipart ok")
+
+
+def test_bytes_van():
+    assert _bytes_van(b"abc") == (b"abc", "upload")
+    pad = os.path.join(os.path.dirname(__file__), "_proef.txt")
+    with open(pad, "wb") as f:
+        f.write(b"hallo")
+    try:
+        assert _bytes_van(pad) == (b"hallo", "_proef.txt")
+        with open(pad, "rb") as f:
+            assert _bytes_van(f) == (b"hallo", "_proef.txt")
+    finally:
+        os.remove(pad)
+    print("  bytes_van ok")
+
+
+def test_live():
+    """Alleen met LIVE=1: één echte aanroep, zodat 'het werkt' geen aanname is."""
+    import io
+    import struct
+    import zlib
+
+    def mini_png() -> bytes:                       # 2x2 rood, zonder Pillow
+        def blok(soort, data):
+            return (struct.pack(">I", len(data)) + soort + data
+                    + struct.pack(">I", zlib.crc32(soort + data)))
+        rauw = b"".join(b"\x00" + b"\xff\x00\x00" * 2 for _ in range(2))
+        return (b"\x89PNG\r\n\x1a\n"
+                + blok(b"IHDR", struct.pack(">IIBBBBB", 2, 2, 8, 2, 0, 0, 0))
+                + blok(b"IDAT", zlib.compress(rauw))
+                + blok(b"IEND", b""))
+
+    uit = remove_background(mini_png())
+    assert uit[:8] == b"\x89PNG\r\n\x1a\n", "de service gaf geen PNG terug"
+    print(f"  live ok — {len(uit)} bytes PNG terug")
+    _ = io.BytesIO
+
+
+if __name__ == "__main__":
+    test_multipart()
+    test_bytes_van()
+    if os.environ.get("LIVE"):
+        test_live()
+    else:
+        print("  live overgeslagen (zet LIVE=1)")
+    print("alles ok")