bh-pixelfuse 1.0.0__tar.gz

bh_pixelfuse-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: bh_pixelfuse
+Version: 1.0.0
+Summary: Embed images into portable text files and extract them back
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.31.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: python-multipart>=0.0.12
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pydantic-settings>=2.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: flake8>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+
+# PixelFuse Backend
+
+FastAPI service that embeds images into portable text files and extracts them back.
+
+## Docs
+
+| # | File | Description |
+|---|------|-------------|
+| 001 | [Overview](docs/001_overview.md) | What PixelFuse does and the text file format |
+| 002 | [API Reference](docs/002_api.md) | Endpoint contracts, fields, and error codes |
+| 003 | [Configuration](docs/003_configuration.md) | Env vars and CLI flags |
+| 004 | [Development](docs/004_development.md) | Local setup, tests, lint, Docker |
+| 005 | [Deployment](docs/005_deployment.md) | Render, CI, self-hosted Docker |
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/convert-embed/` | Upload images → download base64 text file |
+| POST | `/extract-images/` | Upload text file → download ZIP of images |
+
+Supports JPEG, PNG, and HEIC formats. Max 10 files per request (configurable).
+
+**No distortion.** Embed → extract is lossless. Raw image bytes are base64-encoded and decoded back exactly — no re-encoding at any stage.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+pixelfuse serve --reload
+```
+
+## Configuration
+
+All settings are overridable via environment variables prefixed `PIXELFUSE_`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PIXELFUSE_HOST` | `0.0.0.0` | Bind host |
+| `PIXELFUSE_PORT` | `8000` | Bind port |
+| `PIXELFUSE_LOG_LEVEL` | `info` | Uvicorn log level |
+| `PIXELFUSE_MAX_UPLOAD_FILES` | `10` | Max files per request |
+| `PIXELFUSE_ALLOWED_ORIGINS` | *(required)* | CORS origins (JSON array) |
+
+Copy `.env.example` to `.env` for local overrides.
+
+## Development
+
+```bash
+# Lint
+flake8 src tests
+
+# Type check
+mypy src
+
+# All environments
+tox
+```
+
+## Deployment
+
+Deployed on [Render](https://render.com) via `render.yaml`. CI runs on every push via GitHub Actions.

bh_pixelfuse-1.0.0/README.md

@@ -0,0 +1,62 @@
+# PixelFuse Backend
+
+FastAPI service that embeds images into portable text files and extracts them back.
+
+## Docs
+
+| # | File | Description |
+|---|------|-------------|
+| 001 | [Overview](docs/001_overview.md) | What PixelFuse does and the text file format |
+| 002 | [API Reference](docs/002_api.md) | Endpoint contracts, fields, and error codes |
+| 003 | [Configuration](docs/003_configuration.md) | Env vars and CLI flags |
+| 004 | [Development](docs/004_development.md) | Local setup, tests, lint, Docker |
+| 005 | [Deployment](docs/005_deployment.md) | Render, CI, self-hosted Docker |
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/convert-embed/` | Upload images → download base64 text file |
+| POST | `/extract-images/` | Upload text file → download ZIP of images |
+
+Supports JPEG, PNG, and HEIC formats. Max 10 files per request (configurable).
+
+**No distortion.** Embed → extract is lossless. Raw image bytes are base64-encoded and decoded back exactly — no re-encoding at any stage.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+pixelfuse serve --reload
+```
+
+## Configuration
+
+All settings are overridable via environment variables prefixed `PIXELFUSE_`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PIXELFUSE_HOST` | `0.0.0.0` | Bind host |
+| `PIXELFUSE_PORT` | `8000` | Bind port |
+| `PIXELFUSE_LOG_LEVEL` | `info` | Uvicorn log level |
+| `PIXELFUSE_MAX_UPLOAD_FILES` | `10` | Max files per request |
+| `PIXELFUSE_ALLOWED_ORIGINS` | *(required)* | CORS origins (JSON array) |
+
+Copy `.env.example` to `.env` for local overrides.
+
+## Development
+
+```bash
+# Lint
+flake8 src tests
+
+# Type check
+mypy src
+
+# All environments
+tox
+```
+
+## Deployment
+
+Deployed on [Render](https://render.com) via `render.yaml`. CI runs on every push via GitHub Actions.

bh_pixelfuse-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bh_pixelfuse"
+version = "1.0.0"
+description = "Embed images into portable text files and extract them back"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.31.0",
+    "Pillow>=10.0.0",
+    "python-multipart>=0.0.12",
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+    "flake8>=7.0",
+    "mypy>=1.11",
+    "tox>=4.0",
+]
+
+[project.scripts]
+pixelfuse = "pixelfuse.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+envlist = lint, typecheck, test
+isolated_build = true
+
+[testenv:lint]
+deps = flake8>=7.0
+commands = flake8 src tests
+
+[testenv:typecheck]
+deps = mypy>=1.11
+commands = mypy src
+
+[testenv:test]
+extras = dev
+commands = pytest --tb=short -q
+"""

bh_pixelfuse-1.0.0/setup.cfg

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

bh_pixelfuse-1.0.0/src/bh_pixelfuse.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: bh_pixelfuse
+Version: 1.0.0
+Summary: Embed images into portable text files and extract them back
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.31.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: python-multipart>=0.0.12
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pydantic-settings>=2.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: flake8>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+
+# PixelFuse Backend
+
+FastAPI service that embeds images into portable text files and extracts them back.
+
+## Docs
+
+| # | File | Description |
+|---|------|-------------|
+| 001 | [Overview](docs/001_overview.md) | What PixelFuse does and the text file format |
+| 002 | [API Reference](docs/002_api.md) | Endpoint contracts, fields, and error codes |
+| 003 | [Configuration](docs/003_configuration.md) | Env vars and CLI flags |
+| 004 | [Development](docs/004_development.md) | Local setup, tests, lint, Docker |
+| 005 | [Deployment](docs/005_deployment.md) | Render, CI, self-hosted Docker |
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/convert-embed/` | Upload images → download base64 text file |
+| POST | `/extract-images/` | Upload text file → download ZIP of images |
+
+Supports JPEG, PNG, and HEIC formats. Max 10 files per request (configurable).
+
+**No distortion.** Embed → extract is lossless. Raw image bytes are base64-encoded and decoded back exactly — no re-encoding at any stage.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+pixelfuse serve --reload
+```
+
+## Configuration
+
+All settings are overridable via environment variables prefixed `PIXELFUSE_`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PIXELFUSE_HOST` | `0.0.0.0` | Bind host |
+| `PIXELFUSE_PORT` | `8000` | Bind port |
+| `PIXELFUSE_LOG_LEVEL` | `info` | Uvicorn log level |
+| `PIXELFUSE_MAX_UPLOAD_FILES` | `10` | Max files per request |
+| `PIXELFUSE_ALLOWED_ORIGINS` | *(required)* | CORS origins (JSON array) |
+
+Copy `.env.example` to `.env` for local overrides.
+
+## Development
+
+```bash
+# Lint
+flake8 src tests
+
+# Type check
+mypy src
+
+# All environments
+tox
+```
+
+## Deployment
+
+Deployed on [Render](https://render.com) via `render.yaml`. CI runs on every push via GitHub Actions.

bh_pixelfuse-1.0.0/src/bh_pixelfuse.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/bh_pixelfuse.egg-info/PKG-INFO
+src/bh_pixelfuse.egg-info/SOURCES.txt
+src/bh_pixelfuse.egg-info/dependency_links.txt
+src/bh_pixelfuse.egg-info/entry_points.txt
+src/bh_pixelfuse.egg-info/requires.txt
+src/bh_pixelfuse.egg-info/top_level.txt
+src/pixelfuse/__init__.py
+src/pixelfuse/cli.py
+src/pixelfuse/config.py
+src/pixelfuse/main.py
+src/pixelfuse/api/__init__.py
+src/pixelfuse/api/routes/__init__.py
+src/pixelfuse/api/routes/convert.py
+src/pixelfuse/api/routes/extract.py
+tests/test_convert.py
+tests/test_extract.py

bh_pixelfuse-1.0.0/src/bh_pixelfuse.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bh_pixelfuse-1.0.0/src/bh_pixelfuse.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pixelfuse = pixelfuse.cli:cli

bh_pixelfuse-1.0.0/src/bh_pixelfuse.egg-info/requires.txt

@@ -0,0 +1,14 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.31.0
+Pillow>=10.0.0
+python-multipart>=0.0.12
+pydantic>=2.9.0
+pydantic-settings>=2.6.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.24
+httpx>=0.27
+flake8>=7.0
+mypy>=1.11
+tox>=4.0

bh_pixelfuse-1.0.0/src/bh_pixelfuse.egg-info/top_level.txt

@@ -0,0 +1 @@
+pixelfuse

bh_pixelfuse-1.0.0/src/pixelfuse/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

bh_pixelfuse-1.0.0/src/pixelfuse/api/routes/convert.py

@@ -0,0 +1,49 @@
+import base64
+import io
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from fastapi.responses import Response
+from PIL import Image
+
+from pixelfuse.config import get_settings
+
+router = APIRouter()
+
+
+@router.post("/convert-embed/")
+async def convert_embed_images(
+    files: list[UploadFile] = File(...),
+    output_file_name: str = Form(...),
+) -> Response:
+    settings = get_settings()
+    if len(files) > settings.max_upload_files:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Maximum {settings.max_upload_files} files allowed.",
+        )
+
+    blocks: list[str] = [f"Filename: {output_file_name}"]
+
+    for idx, file in enumerate(files):
+        content = await file.read()
+        filename = file.filename or f"image_{idx + 1}"
+        try:
+            if filename.lower().endswith(".heic") or file.content_type == "image/heic":
+                encoded = base64.b64encode(content).decode()
+            else:
+                Image.open(io.BytesIO(content)).verify()
+                encoded = base64.b64encode(content).decode()
+            blocks.append(f"Image {idx + 1} ({filename}):\n{encoded}")
+        except Exception as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Cannot process {filename}: {exc}",
+            ) from exc
+
+    return Response(
+        content="\n\n".join(blocks),
+        media_type="text/plain",
+        headers={
+            "Content-Disposition": f'attachment; filename="{output_file_name}.txt"'
+        },
+    )

bh_pixelfuse-1.0.0/src/pixelfuse/api/routes/extract.py

@@ -0,0 +1,52 @@
+import base64
+import io
+import zipfile
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+from fastapi.responses import StreamingResponse
+from PIL import Image
+
+router = APIRouter()
+
+
+@router.post("/extract-images/")
+async def extract_images_from_text(file: UploadFile = File(...)) -> StreamingResponse:
+    content = await file.read()
+    blocks = content.decode("utf-8").split("\n\n")
+
+    zip_buffer = io.BytesIO()
+    count = 0
+
+    with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zf:
+        for idx, block in enumerate(blocks):
+            if not block.startswith("Image"):
+                continue
+            try:
+                header, encoded = block.split(":", 1)
+                img_data = base64.b64decode(encoded.strip())
+
+                if "heic" in header.lower():
+                    zf.writestr(f"image_{idx + 1}.heic", img_data)
+                else:
+                    img = Image.open(io.BytesIO(img_data))
+                    fmt = (img.format or "PNG").lower()
+                    zf.writestr(f"image_{idx + 1}.{fmt}", img_data)
+
+                count += 1
+            except Exception as exc:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Error processing block {idx + 1}: {exc}",
+                ) from exc
+
+    if count == 0:
+        raise HTTPException(status_code=400, detail="No images found in file.")
+
+    zip_buffer.seek(0)
+    return StreamingResponse(
+        zip_buffer,
+        media_type="application/zip",
+        headers={
+            "Content-Disposition": 'attachment; filename="extracted_images.zip"'
+        },
+    )

bh_pixelfuse-1.0.0/src/pixelfuse/cli.py

@@ -0,0 +1,47 @@
+import argparse
+
+import uvicorn
+
+from pixelfuse.config import get_settings
+
+
+def serve(args: argparse.Namespace) -> None:
+    cfg = get_settings()
+    uvicorn.run(
+        "pixelfuse.main:app",
+        host=args.host or cfg.host,
+        port=args.port or cfg.port,
+        log_level=args.log_level or cfg.log_level,
+        reload=args.reload,
+    )
+
+
+def cli() -> None:
+    parser = argparse.ArgumentParser(
+        prog="pixelfuse",
+        description="PixelFuse — image embedding API server.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve_cmd = sub.add_parser("serve", help="Start the API server.")
+    serve_cmd.add_argument(
+        "--host", default=None, help="Bind host (overrides PIXELFUSE_HOST)"
+    )
+    serve_cmd.add_argument(
+        "--port", type=int, default=None, help="Bind port (overrides PIXELFUSE_PORT)"
+    )
+    serve_cmd.add_argument(
+        "--reload", action="store_true", help="Enable auto-reload (dev only)"
+    )
+    serve_cmd.add_argument(
+        "--log-level", dest="log_level", default=None,
+        help="Log level (overrides PIXELFUSE_LOG_LEVEL)",
+    )
+
+    args = parser.parse_args()
+    if args.command == "serve":
+        serve(args)
+
+
+if __name__ == "__main__":
+    cli()

bh_pixelfuse-1.0.0/src/pixelfuse/config.py

@@ -0,0 +1,25 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    host: str = "0.0.0.0"
+    port: int = 8000
+    allowed_origins: list[str] = []
+    max_upload_files: int = 10
+    log_level: str = "info"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="PIXELFUSE_",
+        env_file_encoding="utf-8",
+    )
+
+
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings

bh_pixelfuse-1.0.0/src/pixelfuse/main.py

@@ -0,0 +1,41 @@
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from pixelfuse.api.routes import convert, extract
+from pixelfuse.config import Settings, get_settings
+
+MAX_UPLOAD_BYTES = 20 * 1024 * 1024  # 20 MB
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    cfg = settings or get_settings()
+    app = FastAPI(
+        title="PixelFuse API",
+        description="Embed images into portable text files and extract them back.",
+        version="1.0.0",
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cfg.allowed_origins,
+        allow_credentials=False,
+        allow_methods=["POST"],
+        allow_headers=["Content-Type"],
+    )
+
+    @app.middleware("http")
+    async def limit_upload_size(request: Request, call_next: object) -> object:
+        content_length = request.headers.get("content-length")
+        if content_length and int(content_length) > MAX_UPLOAD_BYTES:
+            return JSONResponse(
+                status_code=413,
+                content={"detail": "Upload exceeds 20 MB limit."},
+            )
+        return await call_next(request)  # type: ignore[operator]
+
+    app.include_router(convert.router)
+    app.include_router(extract.router)
+    return app
+
+
+app = create_app()

bh_pixelfuse-1.0.0/tests/test_convert.py

@@ -0,0 +1,34 @@
+import io
+
+from httpx import AsyncClient
+from PIL import Image
+
+
+def _make_png() -> bytes:
+    buf = io.BytesIO()
+    Image.new("RGB", (10, 10), color="red").save(buf, format="PNG")
+    return buf.getvalue()
+
+
+async def test_convert_embed_returns_text(client: AsyncClient) -> None:
+    response = await client.post(
+        "/convert-embed/",
+        files=[("files", ("test.png", _make_png(), "image/png"))],
+        data={"output_file_name": "output"},
+    )
+    assert response.status_code == 200
+    assert "Image 1 (test.png)" in response.text
+    assert response.headers["content-disposition"] == (
+        'attachment; filename="output.txt"'
+    )
+
+
+async def test_convert_embed_too_many_files(client: AsyncClient) -> None:
+    files = [("files", (f"img{i}.png", _make_png(), "image/png")) for i in range(11)]
+    response = await client.post(
+        "/convert-embed/",
+        files=files,
+        data={"output_file_name": "output"},
+    )
+    assert response.status_code == 400
+    assert "Maximum" in response.json()["detail"]

bh_pixelfuse-1.0.0/tests/test_extract.py

@@ -0,0 +1,33 @@
+import base64
+import io
+import zipfile
+
+from httpx import AsyncClient
+from PIL import Image
+
+
+def _make_embed_text(filename: str = "test.png") -> bytes:
+    buf = io.BytesIO()
+    Image.new("RGB", (10, 10), color="blue").save(buf, format="PNG")
+    encoded = base64.b64encode(buf.getvalue()).decode()
+    return f"Filename: test\n\nImage 1 ({filename}):\n{encoded}".encode()
+
+
+async def test_extract_images_returns_zip(client: AsyncClient) -> None:
+    response = await client.post(
+        "/extract-images/",
+        files=[("file", ("embed.txt", _make_embed_text(), "text/plain"))],
+    )
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "application/zip"
+    zf = zipfile.ZipFile(io.BytesIO(response.content))
+    assert len(zf.namelist()) == 1
+
+
+async def test_extract_no_images_returns_400(client: AsyncClient) -> None:
+    response = await client.post(
+        "/extract-images/",
+        files=[("file", ("empty.txt", b"no images here", "text/plain"))],
+    )
+    assert response.status_code == 400
+    assert "No images found" in response.json()["detail"]