Merge branch 'main' into output-reorder

Author: bartTC

CHANGES.rst

@@ -2,12 +2,40 @@
 Change log
 ==========
 
-8.1 ( 02 April 2025)
+WIP
+===
+
+- Added ``GappedCircleModuleDrawer`` (PIL) to render QR code modules as non-contiguous circles. (BenwestGate in `#373`_)
+- Improved test coveraged (akx in `#315`_)
+- Fixed typos in code that used ``embeded`` instead of ``embedded``. For backwards compatibility, the misspelled parameter names are still accepted but now emit deprecation warnings. These deprecated parameter names will be removed in v9.0. (benjnicholls in `#349`_)
+- Migrate pyproject.toml to PEP 621-compliant [project] metadata format. (hroncok in `#399`_)
+- Allow execution as a Python module. (stefansjs in `#400`_)
+
+  ::
+
+    python -m qrcode --output qrcode.png "hello world"
+
+.. _#315: https://github.com/lincolnloop/python-qrcode/pull/315
+.. _#349: https://github.com/lincolnloop/python-qrcode/pull/349
+.. _#373: https://github.com/lincolnloop/python-qrcode/pull/373
+.. _#399: https://github.com/lincolnloop/python-qrcode/pull/399
+.. _#400: https://github.com/lincolnloop/python-qrcode/pull/400
+
+8.2 (01 May 2025)
+=================
+
+- Optimize QRColorMask apply_mask method for enhanced performance
+- Fix typos on StyledPilImage embeded_* parameters.
+  The old parameters with the typos are still accepted
+  for backward compatibility.
+
+
+8.1 (02 April 2025)
 ====================
 
 - Added support for Python 3.13.
 
-8.0 ( 27 September 2024)
+8.0 (27 September 2024)
 ========================
 
 - Added support for Python 3.11 and 3.12.
@@ -20,10 +48,12 @@ Change log
 
 - Code quality and formatting utilises ruff_.
 
-- Removed ``typing_extensions`` as a dependency, as it's no longer required with
+- Removed ``typing_extensions`` as a dependency, as it's no longer required
+  with having Python 3.9+ as a requirement.
   having Python 3.9+ as a requirement.
 
-- Only allow high error correction rate (`qrcode.ERROR_CORRECT_H`) when generating
+- Only allow high error correction rate (`qrcode.ERROR_CORRECT_H`)
+  when generating
   QR codes with embedded images to ensure content is readable
 
 .. _Poetry: https://python-poetry.org

README.rst

@@ -211,7 +211,7 @@ circles by reducing this less than the default of ``Decimal(1)``.
 
 The ``StyledPilImage`` additionally accepts an optional ``color_mask``
 parameter to change the colors of the QR Code, and an optional
-``embeded_image_path`` to embed an image in the center of the code.
+``embedded_image_path`` to embed an image in the center of the code.
 
 Other color masks:
 
@@ -232,7 +232,7 @@ and an embedded image:
 
     img_1 = qr.make_image(image_factory=StyledPilImage, module_drawer=RoundedModuleDrawer())
     img_2 = qr.make_image(image_factory=StyledPilImage, color_mask=RadialGradiantColorMask())
-    img_3 = qr.make_image(image_factory=StyledPilImage, embeded_image_path="/path/to/image.png")
+    img_3 = qr.make_image(image_factory=StyledPilImage, embedded_image_path="/path/to/image.png")
 
 Examples
 ========

pyproject.toml

@@ -1,16 +1,16 @@
 [build-system]
-requires = ["poetry-core"]
+requires = ["poetry-core>=2"]
 build-backend = "poetry.core.masonry.api"
 
-[tool.poetry]
+[project]
 name = "qrcode"
-version = "8.1"
-packages = [{include = "qrcode"}]
+version = "8.2"
 description = "QR Code image generator"
-authors = ["Lincoln Loop <[email protected]>"]
-license = "BSD"
-readme = ["README.rst", "CHANGES.rst"]
-homepage = "https://github.com/lincolnloop/python-qrcode"
+authors = [
+    { name = "Lincoln Loop", email = "[email protected]" },
+]
+license = { text = "BSD-3-Clause" }
+dynamic = [ "readme" ]
 keywords = ["qr", "denso-wave", "IEC18004"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -28,6 +28,31 @@ classifiers = [
     "Topic :: Multimedia :: Graphics",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
+requires-python = "~=3.9"
+dependencies = [
+    "colorama; sys_platform == 'win32'",
+    "deprecation",
+]
+
+
+[project.optional-dependencies]
+pil = ["pillow >=9.1.0"]
+png = ["pypng"]
+all = ["pypng", "pillow >=9.1.0"]
+
+[project.urls]
+homepage = "https://github.com/lincolnloop/python-qrcode"
+repository = "https://github.com/lincolnloop/python-qrcode.git"
+documentation = "https://github.com/lincolnloop/python-qrcode#readme"
+changelog = "https://github.com/lincolnloop/python-qrcode/blob/main/CHANGES.rst"
+"Bug Tracker" = "https://github.com/lincolnloop/python-qrcode/issues"
+
+[project.scripts]
+qr = "qrcode.console_scripts:main"
+
+[tool.poetry]
+packages = [{include = "qrcode"}]
+readme = ["README.rst", "CHANGES.rst"]
 
 # There is no support for data files yet.
 # https://github.com/python-poetry/poetry/issues/9519
@@ -36,21 +61,6 @@ classifiers = [
 #     { destination = "share/man/man1", from = [ "doc/qr.1" ] },
 # ]
 
-[tool.poetry.scripts]
-qr = 'qrcode.console_scripts:main'
-
-
-[tool.poetry.dependencies]
-python = "^3.9"
-colorama = {version = "*", platform = "win32"}
-pypng = {version = "*", optional = true}
-pillow = {version = ">=9.1.0", optional = true}
-
-[tool.poetry.extras]
-pil = ["pillow"]
-png = ["pypng"]
-all = ["pypng","pillow"]
-
 [tool.poetry.group.dev.dependencies]
 pytest = {version = "*"}
 pytest-cov = {version = "*"}
@@ -71,3 +81,17 @@ date-format =" %%-d %%B %%Y"
 prereleaser.middle = [
     "qrcode.release.update_manpage"
 ]
+
+[tool.coverage.run]
+source = ["qrcode"]
+parallel = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "@abc.abstractmethod",
+    "@overload",
+    "if (typing\\.)?TYPE_CHECKING:",
+    "pragma: no cover",
+    "raise NotImplementedError"
+]
+skip_covered = true

qrcode/__main__.py

@@ -0,0 +1,3 @@
+from .console_scripts import main
+
+main()

qrcode/image/base.py

@@ -10,7 +10,7 @@
 DrawerAliases = dict[str, tuple[type[QRModuleDrawer], dict[str, Any]]]
 
 
-class BaseImage:
+class BaseImage(abc.ABC):
     """
     Base QRCode image output class.
     """

qrcode/image/styledpil.py

@@ -1,5 +1,12 @@
-import qrcode.image.base
+from __future__ import annotations
+
+import warnings
+from typing import overload
+
+import deprecation
 from PIL import Image
+
+import qrcode.image.base
 from qrcode.image.styles.colormasks import QRColorMask, SolidFillColorMask
 from qrcode.image.styles.moduledrawers import SquareModuleDrawer
 
@@ -29,7 +36,7 @@ class StyledPilImage(qrcode.image.base.BaseImageWithDrawer):
     data integrity A resampling filter can be specified (defaulting to
     PIL.Image.Resampling.LANCZOS) for resizing; see PIL.Image.resize() for possible
     options for this parameter.
-    The image size can be controlled by `embeded_image_ratio` which is a ratio
+    The image size can be controlled by `embedded_image_ratio` which is a ratio
     between 0 and 1 that's set in relation to the overall width of the QR code.
     """
 
@@ -41,14 +48,32 @@ class StyledPilImage(qrcode.image.base.BaseImageWithDrawer):
 
     def __init__(self, *args, **kwargs):
         self.color_mask = kwargs.get("color_mask", SolidFillColorMask())
-        embeded_image_path = kwargs.get("embeded_image_path", None)
-        self.embeded_image = kwargs.get("embeded_image", None)
-        self.embeded_image_ratio = kwargs.get("embeded_image_ratio", 0.25)
-        self.embeded_image_resample = kwargs.get(
-            "embeded_image_resample", Image.Resampling.LANCZOS
+
+        if kwargs.get("embeded_image_path") or kwargs.get("embeded_image"):
+            warnings.warn(
+                "The 'embeded_*' parameters are deprecated. Use 'embedded_image_path' "
+                "or 'embedded_image' instead. The 'embeded_*' parameters will be "
+                "removed in v9.0.",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+
+        # allow embeded_ parameters with typos for backwards compatibility
+        embedded_image_path = kwargs.get(
+            "embedded_image_path", kwargs.get("embeded_image_path", None)
+        )
+        self.embedded_image = kwargs.get(
+            "embedded_image", kwargs.get("embeded_image", None)
+        )
+        self.embedded_image_ratio = kwargs.get(
+            "embedded_image_ratio", kwargs.get("embeded_image_ratio", 0.25)
+        )
+        self.embedded_image_resample = kwargs.get(
+            "embedded_image_resample",
+            kwargs.get("embeded_image_resample", Image.Resampling.LANCZOS),
         )
-        if not self.embeded_image and embeded_image_path:
-            self.embeded_image = Image.open(embeded_image_path)
+        if not self.embedded_image and embedded_image_path:
+            self.embedded_image = Image.open(embedded_image_path)
 
         # the paint_color is the color the module drawer will use to draw upon
         # a canvas During the color mask process, pixels that are paint_color
@@ -59,12 +84,18 @@ def __init__(self, *args, **kwargs):
 
         super().__init__(*args, **kwargs)
 
+    @overload
+    def drawrect(self, row, col):
+        """
+        Not used.
+        """
+
     def new_image(self, **kwargs):
         mode = (
             "RGBA"
             if (
                 self.color_mask.has_transparency
-                or (self.embeded_image and "A" in self.embeded_image.getbands())
+                or (self.embedded_image and "A" in self.embedded_image.getbands())
             )
             else "RGB"
         )
@@ -79,23 +110,32 @@ def init_new_image(self):
 
     def process(self):
         self.color_mask.apply_mask(self._img)
-        if self.embeded_image:
-            self.draw_embeded_image()
-
+        if self.embedded_image:
+            self.draw_embedded_image()
+
+    @deprecation.deprecated(
+        deprecated_in="9.0",
+        removed_in="8.3",
+        current_version="8.2",
+        details="Use draw_embedded_image() instead",
+    )
     def draw_embeded_image(self):
-        if not self.embeded_image:
+        return self.draw_embedded_image()
+
+    def draw_embedded_image(self):
+        if not self.embedded_image:
             return
         total_width, _ = self._img.size
         total_width = int(total_width)
-        logo_width_ish = int(total_width * self.embeded_image_ratio)
+        logo_width_ish = int(total_width * self.embedded_image_ratio)
         logo_offset = (
             int((int(total_width / 2) - int(logo_width_ish / 2)) / self.box_size)
             * self.box_size
         )  # round the offset to the nearest module
         logo_position = (logo_offset, logo_offset)
         logo_width = total_width - logo_offset * 2
-        region = self.embeded_image
-        region = region.resize((logo_width, logo_width), self.embeded_image_resample)
+        region = self.embedded_image
+        region = region.resize((logo_width, logo_width), self.embedded_image_resample)
         if "A" in region.getbands():
             self._img.alpha_composite(region, logo_position)
         else:
@@ -104,8 +144,7 @@ def draw_embeded_image(self):
     def save(self, stream, format=None, **kwargs):
         if format is None:
             format = kwargs.get("kind", self.kind)
-        if "kind" in kwargs:
-            del kwargs["kind"]
+        kwargs.pop("kind", None)
         self._img.save(stream, format=format, **kwargs)
 
     def __getattr__(self, name):

qrcode/image/styles/colormasks.py

@@ -27,24 +27,33 @@ class QRColorMask:
     def initialize(self, styledPilImage, image):
         self.paint_color = styledPilImage.paint_color
 
-    def apply_mask(self, image):
+    def apply_mask(self, image, use_cache=False):
         width, height = image.size
+        pixels = image.load()
+        fg_color_cache = {} if use_cache else None
         for x in range(width):
             for y in range(height):
+                current_color = pixels[x, y]
+                if current_color == self.back_color:
+                    continue
+                if use_cache and current_color in fg_color_cache:
+                    pixels[x, y] = fg_color_cache[current_color]
+                    continue
                 norm = self.extrap_color(
-                    self.back_color, self.paint_color, image.getpixel((x, y))
+                    self.back_color, self.paint_color, current_color
                 )
                 if norm is not None:
-                    image.putpixel(
-                        (x, y),
-                        self.interp_color(
-                            self.get_bg_pixel(image, x, y),
-                            self.get_fg_pixel(image, x, y),
-                            norm,
-                        ),
+                    new_color = self.interp_color(
+                        self.get_bg_pixel(image, x, y),
+                        self.get_fg_pixel(image, x, y),
+                        norm,
                     )
+                    pixels[x, y] = new_color
+
+                    if use_cache:
+                        fg_color_cache[current_color] = new_color
                 else:
-                    image.putpixel((x, y), self.get_bg_pixel(image, x, y))
+                    pixels[x, y] = self.get_bg_pixel(image, x, y)
 
     def get_fg_pixel(self, image, x, y):
         raise NotImplementedError("QRModuleDrawer.paint_fg_pixel")
@@ -103,7 +112,7 @@ def apply_mask(self, image):
             # the individual pixel comparisons that the base class uses, which
             # would be a lot faster. (In fact doing this would probably remove
             # the need for the B&W optimization above.)
-            QRColorMask.apply_mask(self, image)
+            QRColorMask.apply_mask(self, image, use_cache=True)
 
     def get_fg_pixel(self, image, x, y):
         return self.front_color

qrcode/image/styles/moduledrawers/__init__.py

@@ -1,10 +1,11 @@
 # For backwards compatibility, importing the PIL drawers here.
 try:
     from .pil import CircleModuleDrawer  # noqa: F401
+    from .pil import GappedCircleModuleDrawer  # noqa: F401
     from .pil import GappedSquareModuleDrawer  # noqa: F401
     from .pil import HorizontalBarsDrawer  # noqa: F401
     from .pil import RoundedModuleDrawer  # noqa: F401
     from .pil import SquareModuleDrawer  # noqa: F401
     from .pil import VerticalBarsDrawer  # noqa: F401
-except ImportError:
+except ImportError:  # pragma: no cover
     pass