qrforge 1.0.0__tar.gz

qrforge-1.0.0/LICENSE.md

@@ -0,0 +1,7 @@
+MIT License (Modified)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to make derivative works based on the Software, provided that any substantial changes to the Software are clearly distinguished from the original work and are distributed under a different name.
+
+The original copyright notice and disclaimer must be retained 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.

qrforge-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: qrforge
+Version: 1.0.0
+Summary: Generate and heavily customise QR codes (shapes, gradients, shaders, logos, textures) in pure Python; Pillow optional.
+Author: qrforge contributors
+License: MIT
+Keywords: qr,qrcode,barcode,svg,png,generator,art
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: imaging
+Requires-Dist: pillow>=9; extra == "imaging"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# qrforge
+![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-0%20(required)-blue.svg)
+
+An open-source Python library for **generating and art-directing QR codes**: custom module shapes, gradients, shaders, logos, image textures, backgrounds and shadows — output to PNG, SVG, PDF, terminal ANSI, ASCII or Pillow.
+
+*qrforge implements the full QR encoding pipeline (modes, Reed–Solomon error correction, masking, versions 1–40) from scratch against the standard library. There are **zero required dependencies**; [Pillow](https://pillow.readthedocs.io) is used only for non-PNG image formats, PIL images, or JPEG/GIF/WEBP logos. PNG reading/writing is built in.*
+
+> [!NOTE]
+> **qrforge** is intended to produce both *correct* and *beautiful* QR codes. Every rendered symbol is round-trip verified by a bundled decoder, and the test-suite re-rasterises the SVG geometry to prove it reproduces the matrix — so "pretty" never comes at the cost of "scannable".
+
+## Installation
+
+You can install qrforge using pip:
+
+```bash
+pip install qrforge
+```
+
+Or from source:
+
+```bash
+pip install .            # or copy the qrforge/ folder next to your code
+pip install pillow       # optional, only for non-PNG formats / PIL images
+```
+
+## Supported Python Versions
+
+* Python 3.8 / 3.9 / 3.10 / 3.11 / 3.12 (or later)
+
+## Features
+
+* **Correct encoder** – versions 1–40, EC levels L/M/Q/H, optimal numeric/alphanumeric/byte segmentation, automatic mask selection.
+* **Shapes** – square, rounded, dot, diamond, hexagon, star, cross, squircle, leaf, heart etc. plus random-per-module mixes and your own SDF shapes.
+* **Gradients & colours** – hex / `rgb()` / `hsl()` / CSS names; linear, radial and conic gradients for modules, eyes and background.
+* **Shaders** – grain, glow, wave, twist, glitch, chromatic aberration, halftone, duotone, scanlines, vignette etc. plus custom Python or one-line expression shaders.
+* **Logos & textures** – auto knockout zone, round/clip the logo, logo background, stroke, rotation, opacity; paint any image inside the modules.
+* **Outputs** – PNG (pure-Python codec), SVG (tiny vector), PDF (vector), terminal ANSI, ASCII, Pillow, HTML.
+* **22 ready-made presets** and a CLI.
+
+## Usage
+
+### Quickstart
+
+```python
+import qrforge
+
+qrforge.save("https://example.com", "code.png", "neon", scale=12)
+
+qr = qrforge.QR("hello", ec="h")
+qr.use_style(module_shape="dot", fg=["#ff0080", "#7928ca"], logo="logo.png")
+qr.save("poster.png", scale=14)
+qr.save("poster.svg")
+print(qr.terminal())
+```
+
+### Colours & gradients
+
+```python
+qr.use_style(fg=["#ff9a3c", "#ff4d6d", "#7b2ff7"])          # linear
+qr.use_style(fg={"kind":"radial", "colors":["#fff","#1f6feb"]})
+qr.use_style(fg={"kind":"conic",  "colors":["#ff71ce","#01cdfe","#05ffa1"]})
+```
+
+### Shapes & eyes
+
+```python
+qr.use_style(module_shape=["dot","star","hexagon"], seed=3, module_jitter=0.2,
+             eye_shape="rounded", eye_dot_shape="circle")
+
+@qrforge.shape("wave")          # register a custom shape (SDF in module units)
+def wave(x, y, radius=0.0):
+    import math
+    return qrforge.shapes.sd_circle(x, y + 0.08*math.sin(x*9), 0.5)
+```
+
+### Shaders
+
+```python
+qr.use_style(shaders=["wave:amplitude=4,wavelength=36", "chromatic:offset=2"])
+
+@qrforge.shader                 # custom per-pixel shader
+def heat(x, y, color, ctx):
+    return color.mix("#ff4400", ctx.uv(x, y)[1])
+```
+
+### Logos
+
+```python
+qr.use_style(logo="logo.png", logo_size=0.26, logo_shape="rounded",
+             logo_radius=0.4, logo_bg="#ffffff", logo_stroke=("#000", 0.2),
+             logo_rotation=0, logo_opacity=1.0)
+```
+
+### Presets & overrides
+
+Any preset's defaults (colours, shaders,  etc.) can be overridden:
+
+```python
+qrforge.save("hi", "out.png", "neon", fg="#00ff88", scale=12)
+qrforge.presets.get("sunset", bg="#000000")
+```
+
+Presets: `classic dots rounded soft confetti neon sunset blueprint brutal vapor
+film halftone gold ice leaf circuit retro glitch minimal badge starry cross`.
+
+## Correctness
+
+```python
+qr.verify()                      # decodes the symbol again
+from qrforge.verify import decode
+```
+
+## CLI
+
+```bash
+python -m qrforge "https://example.com" -o out.png -p neon -s 12 -e h
+python -m qrforge "hi" --terminal
+python -m qrforge --list-presets --list-shapes --list-shaders
+```
+
+## Testing
+
+```bash
+python -m pytest tests -q
+```
+
+The suite cross-checks the spec tables, Reed–Solomon correction, optimal
+segmentation against a brute-force reference, the PNG codec against Pillow, and
+re-rasterises every preset + the SVG geometry to prove each one still scans.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). If you encounter any issues or have an edge use case, please open an issue using the templates in `.github/ISSUE_TEMPLATE`.
+
+## License
+
+qrforge is released under the terms of the **MIT License (Modified)**. Please see the [LICENSE.md](LICENSE.md) file for the full text.

qrforge-1.0.0/README.md

@@ -0,0 +1,140 @@
+# qrforge
+![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-0%20(required)-blue.svg)
+
+An open-source Python library for **generating and art-directing QR codes**: custom module shapes, gradients, shaders, logos, image textures, backgrounds and shadows — output to PNG, SVG, PDF, terminal ANSI, ASCII or Pillow.
+
+*qrforge implements the full QR encoding pipeline (modes, Reed–Solomon error correction, masking, versions 1–40) from scratch against the standard library. There are **zero required dependencies**; [Pillow](https://pillow.readthedocs.io) is used only for non-PNG image formats, PIL images, or JPEG/GIF/WEBP logos. PNG reading/writing is built in.*
+
+> [!NOTE]
+> **qrforge** is intended to produce both *correct* and *beautiful* QR codes. Every rendered symbol is round-trip verified by a bundled decoder, and the test-suite re-rasterises the SVG geometry to prove it reproduces the matrix — so "pretty" never comes at the cost of "scannable".
+
+## Installation
+
+You can install qrforge using pip:
+
+```bash
+pip install qrforge
+```
+
+Or from source:
+
+```bash
+pip install .            # or copy the qrforge/ folder next to your code
+pip install pillow       # optional, only for non-PNG formats / PIL images
+```
+
+## Supported Python Versions
+
+* Python 3.8 / 3.9 / 3.10 / 3.11 / 3.12 (or later)
+
+## Features
+
+* **Correct encoder** – versions 1–40, EC levels L/M/Q/H, optimal numeric/alphanumeric/byte segmentation, automatic mask selection.
+* **Shapes** – square, rounded, dot, diamond, hexagon, star, cross, squircle, leaf, heart etc. plus random-per-module mixes and your own SDF shapes.
+* **Gradients & colours** – hex / `rgb()` / `hsl()` / CSS names; linear, radial and conic gradients for modules, eyes and background.
+* **Shaders** – grain, glow, wave, twist, glitch, chromatic aberration, halftone, duotone, scanlines, vignette etc. plus custom Python or one-line expression shaders.
+* **Logos & textures** – auto knockout zone, round/clip the logo, logo background, stroke, rotation, opacity; paint any image inside the modules.
+* **Outputs** – PNG (pure-Python codec), SVG (tiny vector), PDF (vector), terminal ANSI, ASCII, Pillow, HTML.
+* **22 ready-made presets** and a CLI.
+
+## Usage
+
+### Quickstart
+
+```python
+import qrforge
+
+qrforge.save("https://example.com", "code.png", "neon", scale=12)
+
+qr = qrforge.QR("hello", ec="h")
+qr.use_style(module_shape="dot", fg=["#ff0080", "#7928ca"], logo="logo.png")
+qr.save("poster.png", scale=14)
+qr.save("poster.svg")
+print(qr.terminal())
+```
+
+### Colours & gradients
+
+```python
+qr.use_style(fg=["#ff9a3c", "#ff4d6d", "#7b2ff7"])          # linear
+qr.use_style(fg={"kind":"radial", "colors":["#fff","#1f6feb"]})
+qr.use_style(fg={"kind":"conic",  "colors":["#ff71ce","#01cdfe","#05ffa1"]})
+```
+
+### Shapes & eyes
+
+```python
+qr.use_style(module_shape=["dot","star","hexagon"], seed=3, module_jitter=0.2,
+             eye_shape="rounded", eye_dot_shape="circle")
+
+@qrforge.shape("wave")          # register a custom shape (SDF in module units)
+def wave(x, y, radius=0.0):
+    import math
+    return qrforge.shapes.sd_circle(x, y + 0.08*math.sin(x*9), 0.5)
+```
+
+### Shaders
+
+```python
+qr.use_style(shaders=["wave:amplitude=4,wavelength=36", "chromatic:offset=2"])
+
+@qrforge.shader                 # custom per-pixel shader
+def heat(x, y, color, ctx):
+    return color.mix("#ff4400", ctx.uv(x, y)[1])
+```
+
+### Logos
+
+```python
+qr.use_style(logo="logo.png", logo_size=0.26, logo_shape="rounded",
+             logo_radius=0.4, logo_bg="#ffffff", logo_stroke=("#000", 0.2),
+             logo_rotation=0, logo_opacity=1.0)
+```
+
+### Presets & overrides
+
+Any preset's defaults (colours, shaders,  etc.) can be overridden:
+
+```python
+qrforge.save("hi", "out.png", "neon", fg="#00ff88", scale=12)
+qrforge.presets.get("sunset", bg="#000000")
+```
+
+Presets: `classic dots rounded soft confetti neon sunset blueprint brutal vapor
+film halftone gold ice leaf circuit retro glitch minimal badge starry cross`.
+
+## Correctness
+
+```python
+qr.verify()                      # decodes the symbol again
+from qrforge.verify import decode
+```
+
+## CLI
+
+```bash
+python -m qrforge "https://example.com" -o out.png -p neon -s 12 -e h
+python -m qrforge "hi" --terminal
+python -m qrforge --list-presets --list-shapes --list-shaders
+```
+
+## Testing
+
+```bash
+python -m pytest tests -q
+```
+
+The suite cross-checks the spec tables, Reed–Solomon correction, optimal
+segmentation against a brute-force reference, the PNG codec against Pillow, and
+re-rasterises every preset + the SVG geometry to prove each one still scans.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). If you encounter any issues or have an edge use case, please open an issue using the templates in `.github/ISSUE_TEMPLATE`.
+
+## License
+
+qrforge is released under the terms of the **MIT License (Modified)**. Please see the [LICENSE.md](LICENSE.md) file for the full text.

qrforge-1.0.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# Metadata lives in setup.py (the publish workflow seds the version token there),
+# so this file only declares the build backend and tool configuration.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.setuptools]
+# packages are discovered by setup.py via find_packages()

qrforge-1.0.0/qrforge/__init__.py

@@ -0,0 +1,51 @@
+"""qrforge -- generate and style QR codes with no dependencies.
+
+    import qrforge
+
+    qrforge.save("https://example.com", "hello.png", "neon", scale=12)
+
+    qr = qrforge.QR("hello", ec="h")
+    qr.use_style(module_shape="dot", fg=["#ff0080", "#7928ca"], logo="logo.png")
+    qr.save("hello.svg")
+
+Everything (encoding, Reed-Solomon, rasterisation, the PNG codec) is written in
+pure Python against the standard library.  Pillow is used only when you ask for
+a non-PNG format, a PIL image, or a non-PNG logo.
+"""
+
+from .api import Artwork, QR, QRCode, make, png, save, svg, terminal
+from .color import Color
+from .exceptions import DataTooLong, QRForgeError, StyleError, UnsupportedFeature
+from .gradient import Gradient, SolidFill
+from .image import Pixmap
+from .matrix import QRMatrix, build as build_matrix
+from .shaders import Shader, expression, shader
+from .shapes import Shape, custom as shape, register as register_shape
+from .style import Style
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "QR", "QRCode", "Artwork", "make", "save", "svg", "png", "terminal",
+    "Style", "Color", "Gradient", "SolidFill", "Pixmap", "QRMatrix", "build_matrix",
+    "Shader", "shader", "expression", "Shape", "shape", "register_shape",
+    "presets", "shapes", "shaders", "verify",
+    "QRForgeError", "DataTooLong", "StyleError", "UnsupportedFeature",
+    "__version__",
+]
+
+
+def __getattr__(name):
+    """Lazily expose the heavier submodules (``qrforge.presets`` etc.)."""
+    if name in ("presets", "shapes", "shaders", "verify", "matrix", "encoder", "tables", "gf"):
+        from importlib import import_module
+        module = import_module(f".{name}", __name__)
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def preset(name: str) -> Style:
+    """Shortcut for ``qrforge.presets.get(name)``."""
+    from .presets import get
+    return get(name)

qrforge-1.0.0/qrforge/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m qrforge``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())