pkgprint 0.1.0__tar.gz → 0.2.0__tar.gz

{pkgprint-0.1.0 → pkgprint-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pkgprint
-Version: 0.1.0
+Version: 0.2.0
 Summary: Print and packaging math utilities for developers
 Author: Rishabh
 License: MIT
@@ -13,6 +13,7 @@ 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: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Multimedia :: Graphics
@@ -21,6 +22,7 @@ Classifier: Intended Audience :: Developers
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: Pillow>=9.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: build; extra == "dev"

{pkgprint-0.1.0 → pkgprint-0.2.0}/pkgprint/__init__.py

@@ -2,7 +2,8 @@
 pkgprint — Print & packaging math utilities for developers.
 
 Provides unit conversions, color model conversions, standard paper/box sizes,
-and bleed/margin calculations useful in print, packaging, and design workflows.
+bleed/margin calculations, print-readiness file checking, color accessibility
+checking, and dieline panel calculations.
 
 Example:
     >>> import pkgprint
@@ -16,8 +17,11 @@ from .units import mm_to_inches, inches_to_mm, mm_to_points, points_to_mm, dpi_t
 from .color import cmyk_to_rgb, rgb_to_cmyk, hex_to_rgb, rgb_to_hex
 from .paper import paper_size, list_paper_sizes, box_size
 from .print_specs import add_bleed, safe_margin, trim_size
+from .check import CheckResult, PrintReport, check_dpi, check_color_mode, check_dimensions, full_report
+from .accessibility import ContrastResult, relative_luminance, contrast_ratio, check_wcag_compliance, suggest_darker_or_lighter
+from .dieline import Panel, rsc_flat_size, mailer_flat_size, panel_layout
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     # units
     "mm_to_inches",
@@ -39,4 +43,22 @@ __all__ = [
     "add_bleed",
     "safe_margin",
     "trim_size",
+    # check (print-readiness)
+    "CheckResult",
+    "PrintReport",
+    "check_dpi",
+    "check_color_mode",
+    "check_dimensions",
+    "full_report",
+    # accessibility (WCAG contrast)
+    "ContrastResult",
+    "relative_luminance",
+    "contrast_ratio",
+    "check_wcag_compliance",
+    "suggest_darker_or_lighter",
+    # dieline (box panel layout)
+    "Panel",
+    "rsc_flat_size",
+    "mailer_flat_size",
+    "panel_layout",
 ]

pkgprint-0.2.0/pkgprint/accessibility.py

@@ -0,0 +1,318 @@
+"""
+accessibility.py — Colour accessibility and contrast checking.
+
+Checks whether foreground/background colour pairs (e.g. text on a packaging
+background) have sufficient contrast for legibility, using the WCAG 2.1
+guidelines.
+
+References:
+  - WCAG 2.1 relative luminance formula:
+    https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+  - WCAG 2.1 contrast ratio formula:
+    https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+  - WCAG 2.1 success criterion 1.4.3 (AA) and 1.4.6 (AAA):
+    https://www.w3.org/TR/WCAG21/#contrast-minimum
+
+WCAG contrast thresholds:
+  ┌──────────────────┬────────────┬──────────────┐
+  │ Level / Size     │ Min ratio  │ Typical use  │
+  ├──────────────────┼────────────┼──────────────┤
+  │ AA  / normal     │ 4.5 : 1   │ Body copy    │
+  │ AA  / large      │ 3.0 : 1   │ Headings ≥18pt│
+  │ AAA / normal     │ 7.0 : 1   │ High contrast│
+  │ AAA / large      │ 4.5 : 1   │ Large + high │
+  └──────────────────┴────────────┴──────────────┘
+  "Large" text = bold ≥ 14pt or regular ≥ 18pt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# ---------------------------------------------------------------------------
+# WCAG thresholds
+# ---------------------------------------------------------------------------
+
+_THRESHOLDS: dict[tuple[str, str], float] = {
+    ("AA", "normal"): 4.5,
+    ("AA", "large"): 3.0,
+    ("AAA", "normal"): 7.0,
+    ("AAA", "large"): 4.5,
+}
+
+_VALID_LEVELS = ("AA", "AAA")
+_VALID_SIZES = ("normal", "large")
+
+
+# ---------------------------------------------------------------------------
+# Result dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ContrastResult:
+    """Result of a WCAG contrast compliance check."""
+
+    passed: bool
+    ratio: float          # actual contrast ratio (1–21)
+    required_ratio: float # WCAG threshold for the requested level/size
+    level: str            # "AA" or "AAA"
+    text_size: str        # "normal" or "large"
+    message: str
+
+
+# ---------------------------------------------------------------------------
+# Public functions
+# ---------------------------------------------------------------------------
+
+def relative_luminance(r: int, g: int, b: int) -> float:
+    """Calculate the WCAG 2.1 relative luminance of an sRGB colour.
+
+    Applies the piecewise sRGB gamma correction specified in WCAG 2.1
+    (section 1.4.3) and returns a value in the range [0.0, 1.0], where
+    0.0 is absolute black and 1.0 is absolute white.
+
+    Formula:
+        For each channel c in (R, G, B), normalised to 0–1:
+            c_lin = c / 12.92          if c ≤ 0.04045
+            c_lin = ((c + 0.055) / 1.055) ** 2.4   otherwise
+        L = 0.2126 × R_lin + 0.7152 × G_lin + 0.0722 × B_lin
+
+    Args:
+        r: Red channel (0–255).
+        g: Green channel (0–255).
+        b: Blue channel (0–255).
+
+    Returns:
+        Relative luminance as a float in [0.0, 1.0].
+
+    Raises:
+        TypeError:  If any channel is not a numeric type.
+        ValueError: If any channel is outside 0–255.
+
+    Example:
+        >>> round(relative_luminance(255, 255, 255), 4)
+        1.0
+        >>> round(relative_luminance(0, 0, 0), 4)
+        0.0
+        >>> round(relative_luminance(255, 0, 0), 4)
+        0.2126
+    """
+    for name, val in zip(("r", "g", "b"), (r, g, b)):
+        if not isinstance(val, (int, float)):
+            raise TypeError(f"{name!r} must be a number, got {type(val).__name__!r}")
+        if not (0 <= val <= 255):
+            raise ValueError(f"{name!r} must be in range 0–255, got {val}")
+
+    def _linearise(c: float) -> float:
+        c_norm = c / 255.0
+        if c_norm <= 0.04045:
+            return c_norm / 12.92
+        return ((c_norm + 0.055) / 1.055) ** 2.4
+
+    r_lin = _linearise(r)
+    g_lin = _linearise(g)
+    b_lin = _linearise(b)
+    return 0.2126 * r_lin + 0.7152 * g_lin + 0.0722 * b_lin
+
+
+def contrast_ratio(
+    rgb1: tuple[int, int, int],
+    rgb2: tuple[int, int, int],
+) -> float:
+    """Calculate the WCAG 2.1 contrast ratio between two sRGB colours.
+
+    The ratio is always returned as (L_lighter + 0.05) / (L_darker + 0.05)
+    regardless of the order of the arguments, so the result is always ≥ 1.0.
+
+    Args:
+        rgb1: First colour as an (R, G, B) tuple with values 0–255.
+        rgb2: Second colour as an (R, G, B) tuple with values 0–255.
+
+    Returns:
+        Contrast ratio as a float in [1.0, 21.0], rounded to 2 decimal places.
+
+    Raises:
+        TypeError:  If either argument is not a tuple/list of three numbers.
+        ValueError: If any channel value is outside 0–255.
+
+    Example:
+        >>> contrast_ratio((255, 255, 255), (0, 0, 0))
+        21.0
+        >>> contrast_ratio((0, 0, 0), (0, 0, 0))
+        1.0
+        >>> contrast_ratio((255, 255, 255), (255, 255, 255))
+        1.0
+    """
+    for name, rgb in (("rgb1", rgb1), ("rgb2", rgb2)):
+        if not isinstance(rgb, (tuple, list)) or len(rgb) != 3:
+            raise TypeError(
+                f"{name!r} must be a tuple of three integers (R, G, B), "
+                f"got {type(rgb).__name__!r}"
+            )
+
+    l1 = relative_luminance(*rgb1)
+    l2 = relative_luminance(*rgb2)
+    lighter = max(l1, l2)
+    darker = min(l1, l2)
+    ratio = (lighter + 0.05) / (darker + 0.05)
+    return round(ratio, 2)
+
+
+def check_wcag_compliance(
+    rgb1: tuple[int, int, int],
+    rgb2: tuple[int, int, int],
+    level: str = "AA",
+    text_size: str = "normal",
+) -> ContrastResult:
+    """Check whether two colours meet a WCAG contrast requirement.
+
+    Args:
+        rgb1:      First colour (typically foreground/text) as (R, G, B).
+        rgb2:      Second colour (typically background) as (R, G, B).
+        level:     WCAG conformance level: ``"AA"`` (default) or ``"AAA"``.
+        text_size: ``"normal"`` (default, body copy) or ``"large"``
+                   (bold ≥ 14pt or regular ≥ 18pt).
+
+    Returns:
+        :class:`ContrastResult` with ``.passed``, ``.ratio``,
+        ``.required_ratio``, ``.level``, ``.text_size``, and ``.message``.
+
+    Raises:
+        TypeError:  If any colour argument is not a 3-tuple of numbers.
+        ValueError: If any channel is outside 0–255, *level* is not
+                    ``"AA"``/``"AAA"``, or *text_size* is not
+                    ``"normal"``/``"large"``.
+
+    Example:
+        >>> result = check_wcag_compliance((0, 0, 0), (255, 255, 255))
+        >>> result.passed
+        True
+        >>> result.ratio
+        21.0
+        >>> check_wcag_compliance((120, 120, 120), (255, 255, 255)).passed
+        False
+    """
+    if not isinstance(level, str) or level.upper() not in _VALID_LEVELS:
+        raise ValueError(
+            f"level must be one of {_VALID_LEVELS}, got {level!r}"
+        )
+    if not isinstance(text_size, str) or text_size.lower() not in _VALID_SIZES:
+        raise ValueError(
+            f"text_size must be one of {_VALID_SIZES}, got {text_size!r}"
+        )
+
+    level = level.upper()
+    text_size = text_size.lower()
+    required = _THRESHOLDS[(level, text_size)]
+    ratio = contrast_ratio(rgb1, rgb2)
+    passed = ratio >= required
+
+    if passed:
+        msg = (
+            f"Contrast ratio {ratio:.2f}:1 meets WCAG {level} ({text_size} text) "
+            f"requirement of {required}:1."
+        )
+    else:
+        msg = (
+            f"Contrast ratio {ratio:.2f}:1 does NOT meet WCAG {level} ({text_size} text) "
+            f"requirement of {required}:1. Difference: {required - ratio:.2f}."
+        )
+    return ContrastResult(
+        passed=passed,
+        ratio=ratio,
+        required_ratio=required,
+        level=level,
+        text_size=text_size,
+        message=msg,
+    )
+
+
+def suggest_darker_or_lighter(
+    rgb_text: tuple[int, int, int],
+    rgb_background: tuple[int, int, int],
+    target_ratio: float = 4.5,
+) -> tuple[int, int, int]:
+    """Suggest an adjusted text colour that meets the target contrast ratio.
+
+    The hue is preserved: the function only adjusts brightness by scaling the
+    RGB channels toward black (if the text is lighter than the background) or
+    toward white (if the text is darker than the background).  If the current
+    contrast already meets *target_ratio*, the original colour is returned
+    unchanged.
+
+    This is a practical approximation — it does not use HSL or perceptual
+    colour spaces, so results look natural for most colours but may be
+    unexpected for highly saturated hues near the extreme ends of the scale.
+
+    Args:
+        rgb_text:       Current text colour as (R, G, B).
+        rgb_background: Background colour as (R, G, B).
+        target_ratio:   Desired WCAG contrast ratio. Default is 4.5 (AA normal).
+
+    Returns:
+        Adjusted (R, G, B) tuple that meets or exceeds *target_ratio*,
+        clamped to 0–255. Returns ``(0, 0, 0)`` or ``(255, 255, 255)`` if
+        no adjustment within valid RGB range can meet the target.
+
+    Raises:
+        TypeError:  If any colour argument is not a 3-tuple of numbers, or
+                    *target_ratio* is not numeric.
+        ValueError: If any channel is outside 0–255, or *target_ratio*
+                    is outside 1–21.
+
+    Example:
+        >>> adjusted = suggest_darker_or_lighter((120, 120, 120), (255, 255, 255))
+        >>> r = check_wcag_compliance(adjusted, (255, 255, 255))
+        >>> r.passed
+        True
+    """
+    for name, rgb in (("rgb_text", rgb_text), ("rgb_background", rgb_background)):
+        if not isinstance(rgb, (tuple, list)) or len(rgb) != 3:
+            raise TypeError(
+                f"{name!r} must be a tuple of three integers (R, G, B), "
+                f"got {type(rgb).__name__!r}"
+            )
+    if not isinstance(target_ratio, (int, float)):
+        raise TypeError(
+            f"target_ratio must be a number, got {type(target_ratio).__name__!r}"
+        )
+    if not (1.0 <= target_ratio <= 21.0):
+        raise ValueError(
+            f"target_ratio must be between 1 and 21, got {target_ratio}"
+        )
+
+    # Already passes? Return as-is.
+    if contrast_ratio(rgb_text, rgb_background) >= target_ratio:
+        return tuple(int(c) for c in rgb_text)  # type: ignore[return-value]
+
+    l_bg = relative_luminance(*rgb_background)
+    l_text = relative_luminance(*rgb_text)
+
+    # Decide direction: push text toward black or white.
+    # If text is darker than background (l_text < l_bg) → darken further.
+    # If text is lighter than background → lighten further.
+    should_darken = l_text < l_bg
+
+    # Binary search on a scalar factor t ∈ [0, 1].
+    # t=0 → original text colour, t=1 → black (darken) or white (lighten).
+    lo, hi = 0.0, 1.0
+    for _ in range(64):                     # 64 iterations → precision < 1e-18
+        mid = (lo + hi) / 2
+        if should_darken:
+            candidate = tuple(int(c * (1 - mid)) for c in rgb_text)
+        else:
+            candidate = tuple(int(c + (255 - c) * mid) for c in rgb_text)
+
+        if contrast_ratio(candidate, rgb_background) >= target_ratio:  # type: ignore[arg-type]
+            hi = mid
+        else:
+            lo = mid
+
+    # Return the result at hi (the least-adjusted value that still passes).
+    if should_darken:
+        result = tuple(max(0, int(c * (1 - hi))) for c in rgb_text)
+    else:
+        result = tuple(min(255, int(c + (255 - c) * hi)) for c in rgb_text)
+
+    return result  # type: ignore[return-value]