pixel-puzzle-game 0.4.0__tar.gz

pixel_puzzle_game-0.4.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

pixel_puzzle_game-0.4.0/LICENSE

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

pixel_puzzle_game-0.4.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: pixel-puzzle-game
+Version: 0.4.0
+Summary: A pixel art guessing quiz game
+Project-URL: Homepage, https://github.com/luca/Pixel-Puzzle
+Project-URL: Issues, https://github.com/luca/Pixel-Puzzle/issues
+Author: Luca Barden
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,game,pixel-art,quiz
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.14
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Pixel Puzzle
+
+A pixel art guessing quiz game. The server reads image files from a folder
+you point it at, exposes a small JSON API listing them, and ships a static
+front-end that turns those images into a guess-the-pixel-art quiz.
+
+## Features
+
+- FastAPI backend with a single `/api/images` JSON endpoint.
+- Static front-end (vanilla HTML/CSS/JS) bundled with the package.
+- Long-lived cache headers for versioned assets, `no-cache` for `index.html`.
+- GZip middleware for text payloads.
+- Image-folder caching keyed on directory mtime.
+- Environment-driven configuration (`HOST`, `PORT`, `IMAGE_FOLDER`).
+
+## Requirements
+
+- Python 3.14 or newer.
+
+## Installation
+
+Install with [`uv`](https://docs.astral.sh/uv/) as a standalone tool:
+
+```bash
+uv tool install pixel-puzzle
+```
+
+Or, alternatively, run it ephemerally:
+
+```bash
+uvx pixel-puzzle
+```
+
+Or, install it into a project virtual environment with:
+
+```bash
+uv add pixel-puzzle
+```
+
+## Usage
+
+Drop pixel art images (`.png`, `.jpg`, `.jpeg`) into a directory, then point
+the server at it via the `IMAGE_FOLDER` environment variable (default: a
+folder named `images` in the current working directory):
+
+```bash
+IMAGE_FOLDER=/path/to/pixel-art pixel-puzzle
+```
+
+Open <http://localhost:8000> and start guessing.
+
+### Configuration
+
+| Variable        | Default              | Description                              |
+|-----------------|----------------------|------------------------------------------|
+| `HOST`          | `0.0.0.0`            | Interface for uvicorn to bind.           |
+| `PORT`          | `8000`               | TCP port for the HTTP server.            |
+| `IMAGE_FOLDER`  | `./images`           | Directory scanned for image files.       |
+
+## Development
+
+Clone the repository and sync the dev environment:
+
+```bash
+git clone https://github.com/luca/Pixel-Puzzle.git
+cd Pixel-Puzzle
+uv sync --extra dev
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Run the server from a working copy:
+
+```bash
+uv run pixel-puzzle
+```
+
+## Project layout
+
+```
+src/pixel_puzzle/
+    __init__.py
+    __main__.py        # console-script entry point
+    app.py             # FastAPI application
+    static/            # HTML, JS, CSS, fonts
+tests/
+pyproject.toml
+```
+
+## License
+
+MIT. See the project metadata in `pyproject.toml` for the canonical notice.

pixel_puzzle_game-0.4.0/README.md

@@ -0,0 +1,96 @@
+# Pixel Puzzle
+
+A pixel art guessing quiz game. The server reads image files from a folder
+you point it at, exposes a small JSON API listing them, and ships a static
+front-end that turns those images into a guess-the-pixel-art quiz.
+
+## Features
+
+- FastAPI backend with a single `/api/images` JSON endpoint.
+- Static front-end (vanilla HTML/CSS/JS) bundled with the package.
+- Long-lived cache headers for versioned assets, `no-cache` for `index.html`.
+- GZip middleware for text payloads.
+- Image-folder caching keyed on directory mtime.
+- Environment-driven configuration (`HOST`, `PORT`, `IMAGE_FOLDER`).
+
+## Requirements
+
+- Python 3.14 or newer.
+
+## Installation
+
+Install with [`uv`](https://docs.astral.sh/uv/) as a standalone tool:
+
+```bash
+uv tool install pixel-puzzle
+```
+
+Or, alternatively, run it ephemerally:
+
+```bash
+uvx pixel-puzzle
+```
+
+Or, install it into a project virtual environment with:
+
+```bash
+uv add pixel-puzzle
+```
+
+## Usage
+
+Drop pixel art images (`.png`, `.jpg`, `.jpeg`) into a directory, then point
+the server at it via the `IMAGE_FOLDER` environment variable (default: a
+folder named `images` in the current working directory):
+
+```bash
+IMAGE_FOLDER=/path/to/pixel-art pixel-puzzle
+```
+
+Open <http://localhost:8000> and start guessing.
+
+### Configuration
+
+| Variable        | Default              | Description                              |
+|-----------------|----------------------|------------------------------------------|
+| `HOST`          | `0.0.0.0`            | Interface for uvicorn to bind.           |
+| `PORT`          | `8000`               | TCP port for the HTTP server.            |
+| `IMAGE_FOLDER`  | `./images`           | Directory scanned for image files.       |
+
+## Development
+
+Clone the repository and sync the dev environment:
+
+```bash
+git clone https://github.com/luca/Pixel-Puzzle.git
+cd Pixel-Puzzle
+uv sync --extra dev
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Run the server from a working copy:
+
+```bash
+uv run pixel-puzzle
+```
+
+## Project layout
+
+```
+src/pixel_puzzle/
+    __init__.py
+    __main__.py        # console-script entry point
+    app.py             # FastAPI application
+    static/            # HTML, JS, CSS, fonts
+tests/
+pyproject.toml
+```
+
+## License
+
+MIT. See the project metadata in `pyproject.toml` for the canonical notice.

pixel_puzzle_game-0.4.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pixel-puzzle-game"
+version = "0.4.0"
+description = "A pixel art guessing quiz game"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Luca Barden" }]
+keywords = ["pixel-art", "game", "quiz", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+    "fastapi>=0.100.0",
+    "uvicorn[standard]>=0.20.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+pixel-puzzle = "pixel_puzzle.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/luca/Pixel-Puzzle"
+Issues = "https://github.com/luca/Pixel-Puzzle/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pixel_puzzle"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pixel_puzzle",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pixel_puzzle_game-0.4.0/src/pixel_puzzle/__init__.py

@@ -0,0 +1,7 @@
+"""Pixel Puzzle — a pixel art guessing quiz game."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

pixel_puzzle_game-0.4.0/src/pixel_puzzle/__main__.py

@@ -0,0 +1,22 @@
+"""Console-script entry point: ``pixel-puzzle``."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import uvicorn
+
+logger = logging.getLogger("pixel_puzzle")
+
+
+def main() -> None:
+    """Start the FastAPI app under uvicorn."""
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+    logger.info(f"Starting server on {host}:{port}")
+    uvicorn.run("pixel_puzzle.app:app", host=host, port=port, reload=False)
+
+
+if __name__ == "__main__":
+    main()

pixel_puzzle_game-0.4.0/src/pixel_puzzle/app.py

@@ -0,0 +1,125 @@
+"""FastAPI application for the Pixel Puzzle game.
+
+Static assets (HTML, JS, CSS, fonts) are shipped inside the package and
+resolved at runtime via :mod:`importlib.resources`, so the app works both
+from a working copy and from an installed wheel.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from importlib.resources import files
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.responses import Response
+from starlette.staticfiles import StaticFiles as StarletteStaticFiles
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger("pixel_puzzle")
+
+# Location of the bundled `static/` directory inside the installed package.
+STATIC_DIR = files("pixel_puzzle").joinpath("static")
+
+# Allow operators to point at a directory of images outside the package.
+IMAGE_FOLDER = os.getenv("IMAGE_FOLDER", os.path.join(os.getcwd(), "images"))
+
+_images_cache: list[str] | None = None
+_images_cache_mtime: float | None = None
+
+CACHE_IMMUTABLE = "public, max-age=31536000, immutable"
+CACHE_NO_CACHE = "no-cache"
+
+
+class CachedStaticFiles(StarletteStaticFiles):
+    """StaticFiles with long-lived cache headers for versioned assets."""
+
+    async def get_response(self, path: str, scope) -> Response:
+        response = await super().get_response(path, scope)
+        if response.status_code == 200:
+            response.headers["Cache-Control"] = CACHE_IMMUTABLE
+        return response
+
+
+app = FastAPI(title="Pixel Puzzle")
+app.add_middleware(GZipMiddleware, minimum_size=512)
+
+if not os.path.exists(IMAGE_FOLDER):
+    try:
+        os.makedirs(IMAGE_FOLDER, exist_ok=True)
+        logger.info(f"Created missing image directory at: {IMAGE_FOLDER}")
+    except Exception as e:
+        logger.error(f"Could not create image directory {IMAGE_FOLDER}: {e}")
+
+app.mount("/static", CachedStaticFiles(directory=str(STATIC_DIR)), name="static")
+
+if os.path.exists(IMAGE_FOLDER):
+    app.mount("/images", StaticFiles(directory=IMAGE_FOLDER), name="images")
+else:
+    logger.warning(
+        f"Image folder {IMAGE_FOLDER} does not exist. /images path will not be mounted properly."
+    )
+
+
+def get_images_list() -> list[str]:
+    global _images_cache, _images_cache_mtime
+
+    if not os.path.exists(IMAGE_FOLDER):
+        logger.warning(f"Image folder {IMAGE_FOLDER} does not exist.")
+        return []
+
+    try:
+        folder_mtime = os.path.getmtime(IMAGE_FOLDER)
+        if _images_cache is not None and _images_cache_mtime == folder_mtime:
+            return _images_cache
+
+        files_in_dir = sorted(os.listdir(IMAGE_FOLDER))
+        _images_cache = [
+            f"/images/{f}"
+            for f in files_in_dir
+            if f.lower().endswith((".png", ".jpg", ".jpeg"))
+        ]
+        _images_cache_mtime = folder_mtime
+        return _images_cache
+    except Exception as e:
+        logger.error(f"Error reading image folder {IMAGE_FOLDER}: {e}")
+        return []
+
+
+@app.get("/", response_class=HTMLResponse)
+def index():
+    index_path = STATIC_DIR.joinpath("index.html")
+    if index_path.is_file():
+        return FileResponse(str(index_path), headers={"Cache-Control": CACHE_NO_CACHE})
+    return HTMLResponse(
+        "<html><body><h1>Pixel Puzzle</h1>"
+        "<p>Frontend template not found.</p></body></html>",
+        status_code=404,
+    )
+
+
+@app.get("/favicon.ico", include_in_schema=False)
+def favicon():
+    favicon_path = STATIC_DIR.joinpath("favicon.svg")
+    if favicon_path.is_file():
+        return FileResponse(
+            str(favicon_path),
+            media_type="image/svg+xml",
+            headers={"Cache-Control": CACHE_IMMUTABLE},
+        )
+    return HTMLResponse(status_code=404)
+
+
+@app.get("/api/images")
+def api_images():
+    images = get_images_list()
+    return JSONResponse(content={"images": images})