pixlub 0.3.0__tar.gz

pixlub-0.3.0/LICENSE

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

pixlub-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# Source distribution: setuptools adds the package, README and tests/test_*.py;
+# the tests also need their fixtures, and the examples ship alongside.
+include tests/conftest.py
+recursive-include examples *.py
+global-exclude __pycache__ *.py[cod]

pixlub-0.3.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: pixlub
+Version: 0.3.0
+Summary: Official Python SDK for the Pixlub image API.
+License-Expression: MIT
+Project-URL: Homepage, https://pixlub.com
+Project-URL: Documentation, https://pixlub.com/en/docs/api/getting-started
+Project-URL: Modules, https://pixlub.com/en/docs/modules
+Project-URL: API reference, https://api.pixlub.com/docs
+Project-URL: Source, https://github.com/pixlub/pixlub-python
+Project-URL: Issues, https://github.com/pixlub/pixlub-python/issues
+Keywords: pixlub,image,image processing,background removal,api,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# pixlub
+
+Official Python SDK for the [Pixlub](https://pixlub.com) API. Python 3.9+, one
+dependency: [httpx](https://www.python-httpx.org/).
+
+Documentation: [getting started with the API](https://pixlub.com/en/docs/api/getting-started)
+and [every module, its inputs and settings](https://pixlub.com/en/docs/modules).
+
+## Install
+
+```bash
+pip install pixlub
+```
+
+## Quick start
+
+1. Create an API key in your Pixlub dashboard. API keys need a paid plan.
+2. Put it in an environment variable, never in your source code:
+
+   ```bash
+   export PIXLUB_API_KEY="pix.xxxxxxxx.xxxxxxxx..."
+   ```
+
+3. Run a tool:
+
+   ```python
+   import pixlub
+
+   client = pixlub.Client()
+   result = client.tools.run("removeBgApi", image="photo.jpg")
+   result.save(f"photo-nobg{result.extension}")
+   ```
+
+`result.extension` matches the produced file: `.webp` for `removeBgApi`, `.png`
+for most tools. `save()` refuses to replace an existing file unless
+`overwrite=True`.
+
+## Results
+
+```python
+result = client.tools.run("faceBlurApi", image="photo.jpg", params={"mode": "auto"})
+
+result.image            # bytes of the produced file (None if the tool only returns data)
+result.data             # the data output, parsed JSON
+result.cost             # credits charged
+result.credits_balance  # credits left
+result.output("out")    # an output by key, or by name ("image", "data", "file")
+for output in result.outputs:
+    print(output.key, output.name, output.content_type, len(output.content))
+```
+
+In a batch, output keys get the rank of the file: `out#0`, `out#1`… Each
+`output.url` is a download link valid for one hour.
+
+## Tools and settings
+
+```python
+for tool in client.tools.list(executable_only=True):
+    print(tool.id, [i.id for i in tool.inputs], [o.key for o in tool.outputs])
+
+schema = client.tools.schema("flip")  # JSON Schema of the settings
+client.tools.run("flip", image="photo.jpg", params={"axis": "v"})
+```
+
+Invalid settings raise `InvalidRequestError`, with the reasons in `details`.
+
+## Several files
+
+A tool with several inputs takes `inputs=`, keyed by input id. An input that
+takes several files takes a list:
+
+```python
+client.tools.run("mask", inputs={"image": "photo.png", "mask": "mask.png"})
+client.tools.run("merge", inputs={"base": "bg.png", "overlay": ["1.png", "2.png"]})
+client.tools.run("flip", image=["a.png", "b.png", "c.png"], params={"axis": "h"})  # 3 runs
+```
+
+When `tool.inputs[i].per_file` is true, each file is a separate run, charged
+separately. A palette is passed in `params`, as a list of colors.
+
+A file is a path, bytes, or a binary file object. To use a file from the web,
+pass a `pixlub.SourceURL`; a plain string is always a local path.
+
+```python
+client.tools.run("removeBgApi", image=pixlub.SourceURL("https://example.com/photo.jpg"))
+```
+
+Large files are handled automatically: call `run()` the same way.
+
+## Limits
+
+| Limit | Value |
+| --- | --- |
+| File size, by plan | Free 10 MiB, Basic 50 MiB, Pro 3 GiB |
+| File size, by tool | images 100 MiB, video and audio 3 GiB, Office 250 MiB |
+| Image size | 40 megapixels |
+| Files per run | 64 |
+| Runs | 30 a minute per account, bursts of 10 |
+| Download links | 1 hour |
+
+## Async
+
+`AsyncClient` has the same methods:
+
+```python
+import asyncio
+import pixlub
+
+
+async def main() -> None:
+    async with pixlub.AsyncClient() as client:
+        result = await client.tools.run("removeBgApi", image="photo.jpg")
+        result.save(f"photo-nobg{result.extension}")
+
+
+asyncio.run(main())
+```
+
+## Timeouts
+
+`run()` waits for long runs until they finish, up to `job_timeout` (30 minutes
+by default). After that, `JobTimeoutError` gives the `job_id`: the run may
+still finish and may have been charged, so check it with `GET /v1/jobs/{job_id}`
+rather than running the tool again.
+
+```python
+client = pixlub.Client(timeout=30, job_timeout=600)
+result = client.tools.run("removeBgApi", image="photo.jpg", job_timeout=3600)
+```
+
+## Errors
+
+API errors and refused arguments raise a `pixlub.PixlubError`. A wrong argument
+type raises `TypeError`; a file that `save()` cannot write raises `OSError`.
+
+| Exception | When |
+| --- | --- |
+| `ConfigurationError` | Missing or malformed key or base URL. |
+| `InvalidInputError` | An argument was refused before anything was sent. |
+| `UnknownToolError` | Unknown tool id. |
+| `InvalidRequestError` | HTTP 400 or 422: invalid settings (`details`), `image_too_large` (`max_pixels`)… |
+| `FileTooLargeError` | HTTP 413: file too large for the tool or your plan (`max_bytes`). |
+| `AuthenticationError` | HTTP 401: unknown or revoked key. |
+| `InsufficientCreditsError` | HTTP 402: not enough credits (`required_credits`). |
+| `PermissionDeniedError` | HTTP 403: not included in your plan (`code`, `limit`). |
+| `NotFoundError` | HTTP 404. |
+| `RateLimitError` | HTTP 429: too many requests (`retry_after`). Never charged. |
+| `ServerError`, `ServiceUnavailableError` | HTTP 5xx (`retry_after`). |
+| `APIConnectionError`, `APITimeoutError` | No answer (`request_sent`). |
+| `JobTimeoutError` | A run outlived `job_timeout` (`job_id`). |
+| `UnexpectedResponseError` | The answer could not be read. |
+
+Every `APIError` has `http_status`, `code` and `message`.
+
+```python
+try:
+    result = client.tools.run("removeBgApi", image="photo.jpg")
+except pixlub.InsufficientCreditsError as error:
+    print("Top up your credits:", error.required_credits)
+except pixlub.APIError as error:
+    print(f"Refused ({error.http_status}): {error.message}")
+```
+
+## Retries and credits
+
+The SDK retries a request only when it cannot cause a second charge, up to
+`max_retries` times (2 by default, 0 to disable), and waits as long as the API
+asks. Arguments are checked before anything is sent: a mistake costs nothing.
+After a timeout or a server error on a run, check your balance before running
+it again.
+
+## Configuration
+
+| Argument | Environment variable | Default |
+| --- | --- | --- |
+| `api_key` | `PIXLUB_API_KEY` | required |
+| `base_url` | `PIXLUB_BASE_URL` | `https://api.pixlub.com` (`http://` only for localhost) |
+| `timeout` | | 10 s connect, 180 s read, 60 s write |
+| `job_timeout` | | 1800 s |
+| `max_retries` | | 2 (0 to 5) |
+| `max_input_bytes` | | 3 GiB |
+| `http_client` | | a new `httpx.Client` (pass one for proxies or custom TLS) |
+
+## Examples
+
+[`examples/`](https://github.com/pixlub/pixlub-python/tree/main/examples):
+`quickstart.py` for a first script, `batch_async.py` for many images at once.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy
+```
+
+Live tests run against a real API, and running a tool costs credits:
+
+```bash
+PIXLUB_BASE_URL=https://api.pixlub.com PIXLUB_API_KEY=... pytest tests/test_live.py
+```
+
+## License
+
+MIT: see [LICENSE](https://github.com/pixlub/pixlub-python/blob/main/LICENSE).

pixlub-0.3.0/README.md

@@ -0,0 +1,206 @@
+# pixlub
+
+Official Python SDK for the [Pixlub](https://pixlub.com) API. Python 3.9+, one
+dependency: [httpx](https://www.python-httpx.org/).
+
+Documentation: [getting started with the API](https://pixlub.com/en/docs/api/getting-started)
+and [every module, its inputs and settings](https://pixlub.com/en/docs/modules).
+
+## Install
+
+```bash
+pip install pixlub
+```
+
+## Quick start
+
+1. Create an API key in your Pixlub dashboard. API keys need a paid plan.
+2. Put it in an environment variable, never in your source code:
+
+   ```bash
+   export PIXLUB_API_KEY="pix.xxxxxxxx.xxxxxxxx..."
+   ```
+
+3. Run a tool:
+
+   ```python
+   import pixlub
+
+   client = pixlub.Client()
+   result = client.tools.run("removeBgApi", image="photo.jpg")
+   result.save(f"photo-nobg{result.extension}")
+   ```
+
+`result.extension` matches the produced file: `.webp` for `removeBgApi`, `.png`
+for most tools. `save()` refuses to replace an existing file unless
+`overwrite=True`.
+
+## Results
+
+```python
+result = client.tools.run("faceBlurApi", image="photo.jpg", params={"mode": "auto"})
+
+result.image            # bytes of the produced file (None if the tool only returns data)
+result.data             # the data output, parsed JSON
+result.cost             # credits charged
+result.credits_balance  # credits left
+result.output("out")    # an output by key, or by name ("image", "data", "file")
+for output in result.outputs:
+    print(output.key, output.name, output.content_type, len(output.content))
+```
+
+In a batch, output keys get the rank of the file: `out#0`, `out#1`… Each
+`output.url` is a download link valid for one hour.
+
+## Tools and settings
+
+```python
+for tool in client.tools.list(executable_only=True):
+    print(tool.id, [i.id for i in tool.inputs], [o.key for o in tool.outputs])
+
+schema = client.tools.schema("flip")  # JSON Schema of the settings
+client.tools.run("flip", image="photo.jpg", params={"axis": "v"})
+```
+
+Invalid settings raise `InvalidRequestError`, with the reasons in `details`.
+
+## Several files
+
+A tool with several inputs takes `inputs=`, keyed by input id. An input that
+takes several files takes a list:
+
+```python
+client.tools.run("mask", inputs={"image": "photo.png", "mask": "mask.png"})
+client.tools.run("merge", inputs={"base": "bg.png", "overlay": ["1.png", "2.png"]})
+client.tools.run("flip", image=["a.png", "b.png", "c.png"], params={"axis": "h"})  # 3 runs
+```
+
+When `tool.inputs[i].per_file` is true, each file is a separate run, charged
+separately. A palette is passed in `params`, as a list of colors.
+
+A file is a path, bytes, or a binary file object. To use a file from the web,
+pass a `pixlub.SourceURL`; a plain string is always a local path.
+
+```python
+client.tools.run("removeBgApi", image=pixlub.SourceURL("https://example.com/photo.jpg"))
+```
+
+Large files are handled automatically: call `run()` the same way.
+
+## Limits
+
+| Limit | Value |
+| --- | --- |
+| File size, by plan | Free 10 MiB, Basic 50 MiB, Pro 3 GiB |
+| File size, by tool | images 100 MiB, video and audio 3 GiB, Office 250 MiB |
+| Image size | 40 megapixels |
+| Files per run | 64 |
+| Runs | 30 a minute per account, bursts of 10 |
+| Download links | 1 hour |
+
+## Async
+
+`AsyncClient` has the same methods:
+
+```python
+import asyncio
+import pixlub
+
+
+async def main() -> None:
+    async with pixlub.AsyncClient() as client:
+        result = await client.tools.run("removeBgApi", image="photo.jpg")
+        result.save(f"photo-nobg{result.extension}")
+
+
+asyncio.run(main())
+```
+
+## Timeouts
+
+`run()` waits for long runs until they finish, up to `job_timeout` (30 minutes
+by default). After that, `JobTimeoutError` gives the `job_id`: the run may
+still finish and may have been charged, so check it with `GET /v1/jobs/{job_id}`
+rather than running the tool again.
+
+```python
+client = pixlub.Client(timeout=30, job_timeout=600)
+result = client.tools.run("removeBgApi", image="photo.jpg", job_timeout=3600)
+```
+
+## Errors
+
+API errors and refused arguments raise a `pixlub.PixlubError`. A wrong argument
+type raises `TypeError`; a file that `save()` cannot write raises `OSError`.
+
+| Exception | When |
+| --- | --- |
+| `ConfigurationError` | Missing or malformed key or base URL. |
+| `InvalidInputError` | An argument was refused before anything was sent. |
+| `UnknownToolError` | Unknown tool id. |
+| `InvalidRequestError` | HTTP 400 or 422: invalid settings (`details`), `image_too_large` (`max_pixels`)… |
+| `FileTooLargeError` | HTTP 413: file too large for the tool or your plan (`max_bytes`). |
+| `AuthenticationError` | HTTP 401: unknown or revoked key. |
+| `InsufficientCreditsError` | HTTP 402: not enough credits (`required_credits`). |
+| `PermissionDeniedError` | HTTP 403: not included in your plan (`code`, `limit`). |
+| `NotFoundError` | HTTP 404. |
+| `RateLimitError` | HTTP 429: too many requests (`retry_after`). Never charged. |
+| `ServerError`, `ServiceUnavailableError` | HTTP 5xx (`retry_after`). |
+| `APIConnectionError`, `APITimeoutError` | No answer (`request_sent`). |
+| `JobTimeoutError` | A run outlived `job_timeout` (`job_id`). |
+| `UnexpectedResponseError` | The answer could not be read. |
+
+Every `APIError` has `http_status`, `code` and `message`.
+
+```python
+try:
+    result = client.tools.run("removeBgApi", image="photo.jpg")
+except pixlub.InsufficientCreditsError as error:
+    print("Top up your credits:", error.required_credits)
+except pixlub.APIError as error:
+    print(f"Refused ({error.http_status}): {error.message}")
+```
+
+## Retries and credits
+
+The SDK retries a request only when it cannot cause a second charge, up to
+`max_retries` times (2 by default, 0 to disable), and waits as long as the API
+asks. Arguments are checked before anything is sent: a mistake costs nothing.
+After a timeout or a server error on a run, check your balance before running
+it again.
+
+## Configuration
+
+| Argument | Environment variable | Default |
+| --- | --- | --- |
+| `api_key` | `PIXLUB_API_KEY` | required |
+| `base_url` | `PIXLUB_BASE_URL` | `https://api.pixlub.com` (`http://` only for localhost) |
+| `timeout` | | 10 s connect, 180 s read, 60 s write |
+| `job_timeout` | | 1800 s |
+| `max_retries` | | 2 (0 to 5) |
+| `max_input_bytes` | | 3 GiB |
+| `http_client` | | a new `httpx.Client` (pass one for proxies or custom TLS) |
+
+## Examples
+
+[`examples/`](https://github.com/pixlub/pixlub-python/tree/main/examples):
+`quickstart.py` for a first script, `batch_async.py` for many images at once.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy
+```
+
+Live tests run against a real API, and running a tool costs credits:
+
+```bash
+PIXLUB_BASE_URL=https://api.pixlub.com PIXLUB_API_KEY=... pytest tests/test_live.py
+```
+
+## License
+
+MIT: see [LICENSE](https://github.com/pixlub/pixlub-python/blob/main/LICENSE).

pixlub-0.3.0/examples/batch_async.py

@@ -0,0 +1,45 @@
+"""Run one tool on many images, a few at a time.
+
+    python examples/batch_async.py out/ photo1.jpg photo2.jpg photo3.jpg
+
+At most CONCURRENCY runs at once. A failed image is reported and the others carry on.
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+import pixlub
+
+TOOL = "removeBgApi"
+CONCURRENCY = 4
+
+
+async def process(
+    client: pixlub.AsyncClient, gate: asyncio.Semaphore, index: int, source: Path, out_dir: Path
+) -> str:
+    async with gate:
+        try:
+            result = await client.tools.run(TOOL, image=source)
+        except pixlub.PixlubError as error:
+            return f"FAILED {source.name}: {error}"
+        # The index keeps two inputs with the same file name from overwriting each other.
+        target = out_dir / f"{index:03d}-{source.stem}-{TOOL}{result.extension}"
+        result.save(target, overwrite=True)
+        return f"ok {source.name} -> {target}"
+
+
+async def main(out_dir: Path, sources: list) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    gate = asyncio.Semaphore(CONCURRENCY)
+    async with pixlub.AsyncClient() as client:
+        lines = await asyncio.gather(
+            *(process(client, gate, i, Path(s), out_dir) for i, s in enumerate(sources, 1))
+        )
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        raise SystemExit("usage: python examples/batch_async.py <out-dir> <image> [<image> ...]")
+    asyncio.run(main(Path(sys.argv[1]), sys.argv[2:]))

pixlub-0.3.0/examples/quickstart.py

@@ -0,0 +1,38 @@
+"""List the tools, then remove the background of an image.
+
+export PIXLUB_API_KEY=pix....
+python examples/quickstart.py photo.jpg
+"""
+
+import sys
+
+import pixlub
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: python examples/quickstart.py <image>")
+        return 2
+
+    client = pixlub.Client()
+    tools = client.tools.list(executable_only=True)
+    print(f"{len(tools)} tools available, for example: {', '.join(t.id for t in tools[:5])}")
+
+    try:
+        result = client.tools.run("removeBgApi", image=sys.argv[1])
+    except pixlub.InsufficientCreditsError as error:
+        print(f"Not enough credits: {error}")
+        return 1
+    except pixlub.APIError as error:
+        print(f"The API refused the run: {error}")
+        return 1
+
+    output = result.save(f"output{result.extension}", overwrite=True)
+    print(f"Saved {output} ({len(result.image)} bytes)")
+    if result.credits_balance is not None:
+        print(f"Credits left: {result.credits_balance}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pixlub-0.3.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+# 77: first setuptools to read `license` as an SPDX expression (PEP 639).
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pixlub"
+# The version lives in src/pixlub/_version.py only (read without importing the package).
+dynamic = ["version"]
+description = "Official Python SDK for the Pixlub image API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["pixlub", "image", "image processing", "background removal", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://pixlub.com"
+Documentation = "https://pixlub.com/en/docs/api/getting-started"
+Modules = "https://pixlub.com/en/docs/modules"
+"API reference" = "https://api.pixlub.com/docs"
+Source = "https://github.com/pixlub/pixlub-python"
+Issues = "https://github.com/pixlub/pixlub-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5", "mypy>=1.10"]
+
+[tool.setuptools.dynamic]
+version = { attr = "pixlub._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pixlub = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+strict = true
+files = ["src/pixlub"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests assert on purpose, and the examples are scripts, not library code.
+"tests/**" = ["S"]
+"examples/**" = ["S"]

pixlub-0.3.0/setup.cfg

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