pkgprint 0.1.0__py3-none-any.whl

pkgprint/__init__.py

@@ -0,0 +1,42 @@
+"""
+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.
+
+Example:
+    >>> import pkgprint
+    >>> pkgprint.mm_to_inches(210)
+    8.267716535433071
+    >>> pkgprint.paper_size("A4")
+    (210, 297)
+"""
+
+from .units import mm_to_inches, inches_to_mm, mm_to_points, points_to_mm, dpi_to_ppi, ppi_to_dpi
+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
+
+__version__ = "0.1.0"
+__all__ = [
+    # units
+    "mm_to_inches",
+    "inches_to_mm",
+    "mm_to_points",
+    "points_to_mm",
+    "dpi_to_ppi",
+    "ppi_to_dpi",
+    # color
+    "cmyk_to_rgb",
+    "rgb_to_cmyk",
+    "hex_to_rgb",
+    "rgb_to_hex",
+    # paper
+    "paper_size",
+    "list_paper_sizes",
+    "box_size",
+    # print specs
+    "add_bleed",
+    "safe_margin",
+    "trim_size",
+]

pkgprint/color.py

@@ -0,0 +1,200 @@
+"""
+color.py — Color model conversions for print and screen workflows.
+
+Conversion references:
+  - CMYK → RGB:  standard ICC-style formula using key (K) channel.
+  - RGB → CMYK:  inverse of the above (approximate, device-independent).
+  - Hex ↔ RGB:   CSS hex notation, 6-digit only (with optional '#' prefix).
+
+CMYK inputs are accepted in **both** 0–100 and 0–1 ranges and are
+auto-detected: values > 1 are treated as percentage (0–100).
+"""
+
+from __future__ import annotations
+
+
+def _normalise_cmyk(c: float, m: float, y: float, k: float) -> tuple[float, float, float, float]:
+    """Return CMYK values normalised to the 0–1 range."""
+    values = (c, m, y, k)
+    if any(v > 1 for v in values):
+        # Assume 0–100 percentage input
+        c, m, y, k = c / 100, m / 100, y / 100, k / 100
+    return c, m, y, k
+
+
+def cmyk_to_rgb(c: float, m: float, y: float, k: float) -> tuple[int, int, int]:
+    """Convert CMYK colour values to RGB.
+
+    Inputs are accepted in either 0–100 (percentage) or 0–1 range.
+    If any value exceeds 1, all four are treated as percentages.
+
+    Formula (ICC standard):
+        R = 255 × (1 − C) × (1 − K)
+        G = 255 × (1 − M) × (1 − K)
+        B = 255 × (1 − Y) × (1 − K)
+
+    Args:
+        c: Cyan   component (0–100 or 0–1).
+        m: Magenta component (0–100 or 0–1).
+        y: Yellow component (0–100 or 0–1).
+        k: Key (Black) component (0–100 or 0–1).
+
+    Returns:
+        Tuple of (R, G, B) integers in the range 0–255.
+
+    Raises:
+        ValueError: If any normalised value falls outside 0–1.
+
+    Example:
+        >>> cmyk_to_rgb(0, 100, 100, 0)   # pure red in CMYK
+        (255, 0, 0)
+        >>> cmyk_to_rgb(0, 0, 0, 0)       # white
+        (255, 255, 255)
+        >>> cmyk_to_rgb(0, 0, 0, 100)     # black
+        (0, 0, 0)
+    """
+    for name, val in zip(("c", "m", "y", "k"), (c, m, y, k)):
+        if not isinstance(val, (int, float)):
+            raise TypeError(f"{name!r} must be a number, got {type(val).__name__!r}")
+
+    c, m, y, k = _normalise_cmyk(c, m, y, k)
+
+    for name, val in zip(("c", "m", "y", "k"), (c, m, y, k)):
+        if not (0.0 <= val <= 1.0):
+            raise ValueError(f"{name!r} must be in range 0–1 (or 0–100), got {val}")
+
+    r = round(255 * (1 - c) * (1 - k))
+    g = round(255 * (1 - m) * (1 - k))
+    b = round(255 * (1 - y) * (1 - k))
+    return (r, g, b)
+
+
+def rgb_to_cmyk(r: int, g: int, b: int) -> tuple[float, float, float, float]:
+    """Convert RGB colour values to approximate CMYK.
+
+    This is a device-independent approximation (no ICC profile).
+    Output values are in the 0–100 percentage range, rounded to 2 dp.
+
+    Formula:
+        K = 1 − max(R, G, B) / 255
+        C = (1 − R/255 − K) / (1 − K)   [0 when K=1]
+        M = (1 − G/255 − K) / (1 − K)
+        Y = (1 − B/255 − K) / (1 − K)
+
+    Args:
+        r: Red   channel (0–255).
+        g: Green channel (0–255).
+        b: Blue  channel (0–255).
+
+    Returns:
+        Tuple of (C, M, Y, K) floats in the range 0.0–100.0.
+
+    Raises:
+        ValueError: If any channel is outside 0–255.
+
+    Example:
+        >>> rgb_to_cmyk(255, 0, 0)    # red
+        (0.0, 100.0, 100.0, 0.0)
+        >>> rgb_to_cmyk(0, 0, 0)      # black
+        (0.0, 0.0, 0.0, 100.0)
+        >>> rgb_to_cmyk(255, 255, 255)  # white
+        (0.0, 0.0, 0.0, 0.0)
+    """
+    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}")
+
+    r_, g_, b_ = r / 255, g / 255, b / 255
+    k = 1 - max(r_, g_, b_)
+
+    if k == 1.0:
+        # Pure black — avoid division by zero
+        return (0.0, 0.0, 0.0, 100.0)
+
+    c = (1 - r_ - k) / (1 - k)
+    m = (1 - g_ - k) / (1 - k)
+    y = (1 - b_ - k) / (1 - k)
+
+    return (
+        round(c * 100, 2),
+        round(m * 100, 2),
+        round(y * 100, 2),
+        round(k * 100, 2),
+    )
+
+
+def hex_to_rgb(hex_code: str) -> tuple[int, int, int]:
+    """Convert a CSS hex colour string to an RGB tuple.
+
+    Accepts 6-digit hex strings with or without a leading '#'.
+    3-digit shorthand (e.g. ``#fff``) is also supported and expanded.
+
+    Args:
+        hex_code: Hex colour string, e.g. ``"#FF5733"`` or ``"ff5733"``.
+
+    Returns:
+        Tuple of (R, G, B) integers in the range 0–255.
+
+    Raises:
+        ValueError: If *hex_code* is not a valid 3- or 6-digit hex colour.
+
+    Example:
+        >>> hex_to_rgb("#FF5733")
+        (255, 87, 51)
+        >>> hex_to_rgb("ffffff")
+        (255, 255, 255)
+        >>> hex_to_rgb("#000")
+        (0, 0, 0)
+    """
+    if not isinstance(hex_code, str):
+        raise TypeError(f"hex_code must be a string, got {type(hex_code).__name__!r}")
+
+    code = hex_code.strip().lstrip("#")
+
+    if len(code) == 3:
+        code = "".join(ch * 2 for ch in code)
+
+    if len(code) != 6:
+        raise ValueError(
+            f"Invalid hex colour {hex_code!r}: expected 3 or 6 hex digits (with optional '#')."
+        )
+
+    try:
+        r = int(code[0:2], 16)
+        g = int(code[2:4], 16)
+        b = int(code[4:6], 16)
+    except ValueError:
+        raise ValueError(f"Invalid hex colour {hex_code!r}: contains non-hex characters.")
+
+    return (r, g, b)
+
+
+def rgb_to_hex(r: int, g: int, b: int) -> str:
+    """Convert RGB integers to a CSS hex colour string (uppercase, with '#').
+
+    Args:
+        r: Red   channel (0–255).
+        g: Green channel (0–255).
+        b: Blue  channel (0–255).
+
+    Returns:
+        Uppercase hex string, e.g. ``"#FF5733"``.
+
+    Raises:
+        ValueError: If any channel is outside 0–255.
+
+    Example:
+        >>> rgb_to_hex(255, 87, 51)
+        '#FF5733'
+        >>> rgb_to_hex(0, 0, 0)
+        '#000000'
+    """
+    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}")
+
+    return "#{:02X}{:02X}{:02X}".format(int(r), int(g), int(b))

pkgprint/paper.py

@@ -0,0 +1,174 @@
+"""
+paper.py — Standard paper and packaging box sizes.
+
+All dimensions are in millimetres (mm).
+
+Paper size references:
+  - ISO 216 A-series: https://www.iso.org/standard/36631.html
+  - ISO 216 B-series: same standard.
+  - ANSI paper sizes: ANSI/ASME Y14.1
+  - US common sizes (Letter, Legal, Tabloid): industry convention.
+
+Box size references:
+  - RSC (Regular Slotted Container): TAPPI T 802
+  - Mailer / literature mailer: common postal sizing conventions.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Paper sizes (width × height) in mm — portrait orientation
+# ---------------------------------------------------------------------------
+
+_PAPER_SIZES: dict[str, tuple[int, int]] = {
+    # ISO A-series
+    "A0": (841, 1189),
+    "A1": (594, 841),
+    "A2": (420, 594),
+    "A3": (297, 420),
+    "A4": (210, 297),
+    "A5": (148, 210),
+    "A6": (105, 148),
+    "A7": (74, 105),
+    "A8": (52, 74),
+    # ISO B-series
+    "B0": (1000, 1414),
+    "B1": (707, 1000),
+    "B2": (500, 707),
+    "B3": (353, 500),
+    "B4": (250, 353),
+    "B5": (176, 250),
+    "B6": (125, 176),
+    # ISO C-series (envelope)
+    "C4": (229, 324),
+    "C5": (162, 229),
+    "C6": (114, 162),
+    # US / ANSI sizes
+    "Letter": (216, 279),
+    "Legal": (216, 356),
+    "Tabloid": (279, 432),
+    "Executive": (184, 267),
+    "ANSI A": (216, 279),
+    "ANSI B": (279, 432),
+    "ANSI C": (432, 559),
+    "ANSI D": (559, 864),
+    "ANSI E": (864, 1118),
+    # Business card sizes — two regional standards exist:
+    "Business Card ISO": (85, 55),  # ISO 7810 ID-1 / European standard (85×55mm)
+    "Business Card US":  (89, 51),  # North American standard (3.5"×2" = 88.9×50.8mm, rounded)
+    # Postcard
+    "Postcard": (148, 105),
+    # Square social-media-friendly
+    "Square Small": (130, 130),
+    "Square Large": (210, 210),
+}
+
+# ---------------------------------------------------------------------------
+# Packaging / box sizes (length × width × height) in mm
+# ---------------------------------------------------------------------------
+
+_BOX_SIZES: dict[str, tuple[int, int, int]] = {
+    # RSC (Regular Slotted Container) — common e-commerce shipping boxes
+    "RSC Small":  (200, 150, 100),   # ~6L mailer
+    "RSC Medium": (305, 229, 152),   # ~10L standard shipper
+    "RSC Large":  (406, 305, 203),   # ~25L large shipper
+    # Literature / document mailers
+    "Mailer A4":  (320, 230, 30),    # fits A4 flat
+    "Mailer A5":  (230, 160, 20),    # fits A5 flat
+    # Gift / retail boxes
+    "Gift Small":  (150, 100, 50),
+    "Gift Medium": (220, 170, 80),
+    "Gift Large":  (300, 220, 110),
+    # Pizza-style tuck-top (common for cosmetics / pharma)
+    "Tuck Small":  (80, 50, 20),
+    "Tuck Medium": (120, 80, 35),
+    "Tuck Large":  (170, 110, 50),
+}
+
+
+def paper_size(name: str) -> tuple[int, int]:
+    """Return the (width, height) in mm for a named standard paper size.
+
+    Lookup is **case-insensitive** and ignores leading/trailing whitespace.
+
+    Args:
+        name: Paper size name, e.g. ``"A4"``, ``"letter"``, ``"Legal"``.
+
+    Returns:
+        Tuple of (width, height) in millimetres (portrait orientation).
+
+    Raises:
+        KeyError: If *name* is not a recognised paper size.
+
+    Example:
+        >>> paper_size("A4")
+        (210, 297)
+        >>> paper_size("letter")
+        (216, 279)
+    """
+    if not isinstance(name, str):
+        raise TypeError(f"name must be a string, got {type(name).__name__!r}")
+
+    # Case-insensitive lookup
+    normalised = name.strip()
+    for key, dims in _PAPER_SIZES.items():
+        if key.lower() == normalised.lower():
+            return dims
+
+    available = ", ".join(sorted(_PAPER_SIZES))
+    raise KeyError(
+        f"Unknown paper size {name!r}. "
+        f"Call list_paper_sizes() to see all options.\nAvailable: {available}"
+    )
+
+
+def list_paper_sizes() -> list[str]:
+    """Return a sorted list of all supported paper size names.
+
+    Returns:
+        Alphabetically sorted list of size name strings.
+
+    Example:
+        >>> names = list_paper_sizes()
+        >>> "A4" in names
+        True
+        >>> "Letter" in names
+        True
+    """
+    return sorted(_PAPER_SIZES.keys())
+
+
+def box_size(style: str) -> tuple[int, int, int]:
+    """Return standard packaging box dimensions (L × W × H) in mm.
+
+    Lookup is **case-insensitive** and ignores leading/trailing whitespace.
+
+    Args:
+        style: Box style name, e.g. ``"RSC Medium"``, ``"Mailer A4"``,
+               ``"Gift Large"``.
+
+    Returns:
+        Tuple of (length, width, height) in millimetres.
+
+    Raises:
+        KeyError: If *style* is not a recognised box style.
+
+    Example:
+        >>> box_size("RSC Medium")
+        (305, 229, 152)
+        >>> box_size("mailer a4")
+        (320, 230, 30)
+    """
+    if not isinstance(style, str):
+        raise TypeError(f"style must be a string, got {type(style).__name__!r}")
+
+    normalised = style.strip()
+    for key, dims in _BOX_SIZES.items():
+        if key.lower() == normalised.lower():
+            return dims
+
+    available = ", ".join(sorted(_BOX_SIZES))
+    raise KeyError(
+        f"Unknown box style {style!r}. "
+        f"Available styles: {available}"
+    )

pkgprint/print_specs.py

@@ -0,0 +1,181 @@
+"""
+print_specs.py — Print production math: bleed, safe margin, and trim size.
+
+All dimensions are in millimetres (mm).
+
+Terminology:
+  - Bleed:       Extra artwork beyond the trim edge, cut away during finishing.
+                 Ensures colour/image reaches the physical edge with no white gaps.
+                 Industry default: 3 mm on each side (ISO / offset litho).
+  - Trim size:   The finished dimensions after cutting.
+  - Safe margin: Inner padding inside the trim where critical content should stay,
+                 to avoid it being accidentally cut or visually too close to the edge.
+                 Typical recommendation: 3–5 mm inside the trim line.
+
+Reference: FOGRA / ISO 12647-2 for offset print bleed conventions.
+"""
+
+from __future__ import annotations
+
+
+def _validate_dimension(value: float, name: str) -> None:
+    """Raise TypeError/ValueError for invalid dimension values."""
+    if not isinstance(value, (int, float)):
+        raise TypeError(f"{name!r} must be a number, got {type(value).__name__!r}")
+    if value <= 0:
+        raise ValueError(f"{name!r} must be positive, got {value}")
+
+
+def _validate_offset(value: float, name: str) -> None:
+    """Raise TypeError/ValueError for invalid offset/margin values."""
+    if not isinstance(value, (int, float)):
+        raise TypeError(f"{name!r} must be a number, got {type(value).__name__!r}")
+    if value < 0:
+        raise ValueError(f"{name!r} cannot be negative, got {value}")
+
+
+def add_bleed(
+    width: float,
+    height: float,
+    bleed_mm: float = 3.0,
+) -> tuple[float, float]:
+    """Return artwork dimensions with bleed added to all four sides.
+
+    Bleed is added symmetrically: ``bleed_mm`` is added to **each** side,
+    so the total increase per axis is ``2 × bleed_mm``.
+
+    Args:
+        width:    Trim width in mm (must be positive).
+        height:   Trim height in mm (must be positive).
+        bleed_mm: Bleed amount per side in mm. Default is 3 mm (industry standard).
+
+    Returns:
+        Tuple of (bleed_width, bleed_height) in mm.
+
+    Raises:
+        TypeError:  If any argument is not numeric.
+        ValueError: If *width* or *height* is not positive, or *bleed_mm* is negative.
+
+    Example:
+        >>> add_bleed(89, 51)            # business card with 3 mm bleed
+        (95, 57)
+        >>> add_bleed(210, 297, bleed_mm=5)  # A4 with 5 mm bleed
+        (220, 307)
+        >>> add_bleed(210, 297, bleed_mm=0)  # no bleed
+        (210, 297)
+    """
+    _validate_dimension(width, "width")
+    _validate_dimension(height, "height")
+    _validate_offset(bleed_mm, "bleed_mm")
+
+    bleed_width = width + 2 * bleed_mm
+    bleed_height = height + 2 * bleed_mm
+    # Return int if values are whole numbers, otherwise float
+    bleed_width = int(bleed_width) if bleed_width == int(bleed_width) else bleed_width
+    bleed_height = int(bleed_height) if bleed_height == int(bleed_height) else bleed_height
+    return (bleed_width, bleed_height)
+
+
+def safe_margin(
+    width: float,
+    height: float,
+    margin_mm: float = 5.0,
+) -> tuple[float, float]:
+    """Return the safe content area after subtracting margins from all sides.
+
+    The safe area is the inner region where critical content (text, logos)
+    should be placed.  ``margin_mm`` is subtracted from **each** side, so the
+    total reduction per axis is ``2 × margin_mm``.
+
+    Args:
+        width:     Trim width in mm (must be positive).
+        height:    Trim height in mm (must be positive).
+        margin_mm: Margin per side in mm. Default is 5 mm.
+
+    Returns:
+        Tuple of (safe_width, safe_height) in mm.
+
+    Raises:
+        TypeError:  If any argument is not numeric.
+        ValueError: If *width* or *height* is not positive, *margin_mm* is
+                    negative, or the margin exceeds half the dimension.
+
+    Example:
+        >>> safe_margin(210, 297)              # A4 with 5 mm margins
+        (200, 287)
+        >>> safe_margin(89, 51, margin_mm=3)   # business card with 3 mm margins
+        (83, 45)
+    """
+    _validate_dimension(width, "width")
+    _validate_dimension(height, "height")
+    _validate_offset(margin_mm, "margin_mm")
+
+    safe_w = width - 2 * margin_mm
+    safe_h = height - 2 * margin_mm
+
+    if safe_w <= 0:
+        raise ValueError(
+            f"margin_mm={margin_mm} is too large for width={width}: "
+            f"safe width would be {safe_w} mm."
+        )
+    if safe_h <= 0:
+        raise ValueError(
+            f"margin_mm={margin_mm} is too large for height={height}: "
+            f"safe height would be {safe_h} mm."
+        )
+
+    safe_w = int(safe_w) if safe_w == int(safe_w) else safe_w
+    safe_h = int(safe_h) if safe_h == int(safe_h) else safe_h
+    return (safe_w, safe_h)
+
+
+def trim_size(
+    width: float,
+    height: float,
+    bleed_mm: float = 3.0,
+) -> tuple[float, float]:
+    """Reverse-calculate trim size from artwork dimensions that include bleed.
+
+    The inverse of :func:`add_bleed`.  Given a canvas/file size that already
+    has bleed, return the final trim (finished) dimensions.
+
+    Args:
+        width:    Artwork width including bleed, in mm (must be positive).
+        height:   Artwork height including bleed, in mm (must be positive).
+        bleed_mm: Bleed amount per side in mm. Default is 3 mm.
+
+    Returns:
+        Tuple of (trim_width, trim_height) in mm.
+
+    Raises:
+        TypeError:  If any argument is not numeric.
+        ValueError: If *width* or *height* is not positive, *bleed_mm* is
+                    negative, or the bleed exceeds the available dimension.
+
+    Example:
+        >>> trim_size(95, 57)             # back-calc from business card with bleed
+        (89, 51)
+        >>> trim_size(220, 307, bleed_mm=5)
+        (210, 297)
+    """
+    _validate_dimension(width, "width")
+    _validate_dimension(height, "height")
+    _validate_offset(bleed_mm, "bleed_mm")
+
+    trim_w = width - 2 * bleed_mm
+    trim_h = height - 2 * bleed_mm
+
+    if trim_w <= 0:
+        raise ValueError(
+            f"bleed_mm={bleed_mm} is too large for width={width}: "
+            f"trim width would be {trim_w} mm."
+        )
+    if trim_h <= 0:
+        raise ValueError(
+            f"bleed_mm={bleed_mm} is too large for height={height}: "
+            f"trim height would be {trim_h} mm."
+        )
+
+    trim_w = int(trim_w) if trim_w == int(trim_w) else trim_w
+    trim_h = int(trim_h) if trim_h == int(trim_h) else trim_h
+    return (trim_w, trim_h)

pkgprint/units.py

@@ -0,0 +1,163 @@
+"""
+units.py — Measurement unit conversions for print and packaging.
+
+Conversion references:
+  - 1 inch  = 25.4 mm            (ISO 1)
+  - 1 point = 1/72 inch          (PostScript / CSS pt)
+  - DPI/PPI are numerically equivalent for these conversions;
+    the functions are provided as semantic aliases for clarity.
+"""
+
+
+def mm_to_inches(mm: float) -> float:
+    """Convert millimetres to inches.
+
+    Args:
+        mm: Length in millimetres.
+
+    Returns:
+        Equivalent length in inches.
+
+    Raises:
+        TypeError: If *mm* is not a numeric type.
+
+    Example:
+        >>> mm_to_inches(25.4)
+        1.0
+        >>> mm_to_inches(210)   # A4 width
+        8.267716535433071
+    """
+    if not isinstance(mm, (int, float)):
+        raise TypeError(f"mm must be a number, got {type(mm).__name__!r}")
+    return mm / 25.4
+
+
+def inches_to_mm(inches: float) -> float:
+    """Convert inches to millimetres.
+
+    Args:
+        inches: Length in inches.
+
+    Returns:
+        Equivalent length in millimetres.
+
+    Raises:
+        TypeError: If *inches* is not a numeric type.
+
+    Example:
+        >>> inches_to_mm(1.0)
+        25.4
+        >>> inches_to_mm(8.5)   # US Letter width
+        215.9
+    """
+    if not isinstance(inches, (int, float)):
+        raise TypeError(f"inches must be a number, got {type(inches).__name__!r}")
+    return inches * 25.4
+
+
+def mm_to_points(mm: float) -> float:
+    """Convert millimetres to typographic points (PostScript / CSS pt).
+
+    1 pt = 1/72 inch = 25.4/72 mm ≈ 0.35278 mm
+
+    Args:
+        mm: Length in millimetres.
+
+    Returns:
+        Equivalent length in points.
+
+    Raises:
+        TypeError: If *mm* is not a numeric type.
+
+    Example:
+        >>> round(mm_to_points(25.4), 4)
+        72.0
+        >>> round(mm_to_points(210), 2)   # A4 width
+        595.28
+    """
+    if not isinstance(mm, (int, float)):
+        raise TypeError(f"mm must be a number, got {type(mm).__name__!r}")
+    return mm * (72 / 25.4)
+
+
+def points_to_mm(points: float) -> float:
+    """Convert typographic points to millimetres.
+
+    Args:
+        points: Length in points (PostScript / CSS pt, 1 pt = 1/72 inch).
+
+    Returns:
+        Equivalent length in millimetres.
+
+    Raises:
+        TypeError: If *points* is not a numeric type.
+
+    Example:
+        >>> round(points_to_mm(72), 4)
+        25.4
+        >>> round(points_to_mm(595.28), 2)
+        210.0
+    """
+    if not isinstance(points, (int, float)):
+        raise TypeError(f"points must be a number, got {type(points).__name__!r}")
+    return points * (25.4 / 72)
+
+
+def dpi_to_ppi(dpi: float) -> float:
+    """Convert print DPI (dots per inch) to screen PPI (pixels per inch).
+
+    DPI and PPI share the same unit (measurements per linear inch), so this
+    function is a semantic alias that returns the value unchanged.  It exists
+    to make intent explicit when bridging print and screen workflows.
+
+    Args:
+        dpi: Resolution in dots per inch.
+
+    Returns:
+        Equivalent resolution in pixels per inch.
+
+    Raises:
+        TypeError:  If *dpi* is not a numeric type.
+        ValueError: If *dpi* is negative.
+
+    Example:
+        >>> dpi_to_ppi(300)
+        300
+        >>> dpi_to_ppi(72.0)
+        72.0
+    """
+    if not isinstance(dpi, (int, float)):
+        raise TypeError(f"dpi must be a number, got {type(dpi).__name__!r}")
+    if dpi < 0:
+        raise ValueError(f"dpi cannot be negative, got {dpi}")
+    return dpi
+
+
+def ppi_to_dpi(ppi: float) -> float:
+    """Convert screen PPI (pixels per inch) to print DPI (dots per inch).
+
+    PPI and DPI share the same unit, so this function is a semantic alias
+    that returns the value unchanged.  It exists to make intent explicit when
+    bridging screen and print workflows.
+
+    Args:
+        ppi: Resolution in pixels per inch.
+
+    Returns:
+        Equivalent resolution in dots per inch.
+
+    Raises:
+        TypeError:  If *ppi* is not a numeric type.
+        ValueError: If *ppi* is negative.
+
+    Example:
+        >>> ppi_to_dpi(96)
+        96
+        >>> ppi_to_dpi(144.0)
+        144.0
+    """
+    if not isinstance(ppi, (int, float)):
+        raise TypeError(f"ppi must be a number, got {type(ppi).__name__!r}")
+    if ppi < 0:
+        raise ValueError(f"ppi cannot be negative, got {ppi}")
+    return ppi

pkgprint-0.1.0.dist-info/LICENSE

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

pkgprint-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.2
+Name: pkgprint
+Version: 0.1.0
+Summary: Print and packaging math utilities for developers
+Author: Rishabh
+License: MIT
+Project-URL: Homepage, https://github.com/Rishabh55122/pkgprint
+Project-URL: Bug Tracker, https://github.com/Rishabh55122/pkgprint/issues
+Keywords: print,packaging,design,cmyk,dpi,bleed,typography
+Classifier: Programming Language :: Python :: 3
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# pkgprint
+
+**Print and packaging math utilities for Python developers.**
+
+[![PyPI version](https://badge.fury.io/py/pkgprint.svg)](https://pypi.org/project/pkgprint/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`pkgprint` is a zero-dependency Python library that handles the fiddly maths behind print and packaging production: unit conversions, colour model translations, standard paper and box sizes, and bleed/margin arithmetic.
+
+---
+
+## Installation
+
+```bash
+pip install pkgprint
+```
+
+---
+
+## Quick Start
+
+```python
+import pkgprint
+
+# Get A4 dimensions and convert to inches
+w, h = pkgprint.paper_size("A4")
+print(pkgprint.mm_to_inches(w), pkgprint.mm_to_inches(h))
+# → 8.267716535433071 11.692913385826772
+
+# Add 3 mm bleed to a business card
+bleed_w, bleed_h = pkgprint.add_bleed(89, 51, bleed_mm=3)
+print(bleed_w, bleed_h)
+# → 95 57
+
+# Convert a brand colour from CMYK to RGB
+rgb = pkgprint.cmyk_to_rgb(0, 100, 100, 0)   # Pantone-ish red
+print(rgb)
+# → (255, 0, 0)
+
+# Convert back from hex to RGB
+print(pkgprint.hex_to_rgb("#FF5733"))
+# → (255, 87, 51)
+```
+
+---
+
+## API Reference
+
+### `units` — Measurement Conversions
+
+| Function | Description |
+|---|---|
+| `mm_to_inches(mm)` | Millimetres → inches |
+| `inches_to_mm(inches)` | Inches → millimetres |
+| `mm_to_points(mm)` | Millimetres → typographic points (1 pt = 1/72 in) |
+| `points_to_mm(points)` | Points → millimetres |
+| `dpi_to_ppi(dpi)` | DPI → PPI (semantic alias, same unit) |
+| `ppi_to_dpi(ppi)` | PPI → DPI (semantic alias, same unit) |
+
+```python
+import pkgprint
+
+pkgprint.mm_to_inches(25.4)     # → 1.0
+pkgprint.inches_to_mm(8.5)      # → 215.9  (US Letter width)
+pkgprint.mm_to_points(210)      # → 595.28 (A4 width in points)
+pkgprint.points_to_mm(72)       # → 25.4
+pkgprint.dpi_to_ppi(300)        # → 300
+pkgprint.ppi_to_dpi(96)         # → 96
+```
+
+---
+
+### `color` — Colour Model Conversions
+
+| Function | Description |
+|---|---|
+| `cmyk_to_rgb(c, m, y, k)` | CMYK → RGB. Accepts 0–100 **or** 0–1 inputs. |
+| `rgb_to_cmyk(r, g, b)` | RGB → approximate CMYK (device-independent). |
+| `hex_to_rgb(hex_code)` | CSS hex string → RGB tuple. Supports `#fff` shorthand. |
+| `rgb_to_hex(r, g, b)` | RGB tuple → uppercase CSS hex string. |
+
+```python
+import pkgprint
+
+pkgprint.cmyk_to_rgb(0, 100, 100, 0)   # → (255, 0, 0)  red
+pkgprint.cmyk_to_rgb(0, 1, 1, 0)       # → (255, 0, 0)  same, 0–1 range
+pkgprint.rgb_to_cmyk(0, 0, 255)         # → (100.0, 100.0, 0.0, 0.0)  blue
+pkgprint.hex_to_rgb("#FF5733")          # → (255, 87, 51)
+pkgprint.hex_to_rgb("#fff")             # → (255, 255, 255)  shorthand ok
+pkgprint.rgb_to_hex(255, 87, 51)        # → '#FF5733'
+```
+
+---
+
+### `paper` — Standard Sizes
+
+| Function | Description |
+|---|---|
+| `paper_size(name)` | `(width, height)` in mm for a named paper size. Case-insensitive. |
+| `list_paper_sizes()` | Sorted list of all supported paper size names. |
+| `box_size(style)` | `(length, width, height)` in mm for a named packaging box. Case-insensitive. |
+
+**Supported paper sizes:** ISO A0–A8, B0–B6, C4–C6 (envelopes), Letter, Legal, Tabloid, Executive, ANSI A–E, Business Card, Postcard, and more.
+
+**Supported box styles:** RSC Small/Medium/Large, Mailer A4/A5, Gift Small/Medium/Large, Tuck Small/Medium/Large.
+
+```python
+import pkgprint
+
+pkgprint.paper_size("A4")           # → (210, 297)
+pkgprint.paper_size("letter")       # → (216, 279)  case-insensitive
+pkgprint.box_size("RSC Medium")     # → (305, 229, 152)
+pkgprint.list_paper_sizes()         # → ['A0', 'A1', ..., 'Tabloid', ...]
+```
+
+---
+
+### `print_specs` — Print Production Math
+
+| Function | Description |
+|---|---|
+| `add_bleed(width, height, bleed_mm=3)` | Trim size → artwork size with bleed on all four sides. |
+| `safe_margin(width, height, margin_mm=5)` | Trim size → safe content area (removes margins). |
+| `trim_size(width, height, bleed_mm=3)` | Artwork size (with bleed) → trim size. |
+
+```python
+import pkgprint
+
+# Business card: 89 × 51 mm → with 3 mm bleed → 95 × 57 mm
+pkgprint.add_bleed(89, 51)               # → (95, 57)
+
+# A4 safe content area with 5 mm margins
+pkgprint.safe_margin(210, 297, margin_mm=5)  # → (200, 287)
+
+# Reverse: what is the trim size of a 220 × 307 mm file with 5 mm bleed?
+pkgprint.trim_size(220, 307, bleed_mm=5)     # → (210, 297)
+```
+
+---
+
+## Build & Publish
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build source + wheel
+python -m build
+
+# Test publish (TestPyPI)
+twine upload --repository testpypi dist/*
+
+# Real publish
+twine upload dist/*
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install pytest
+pytest
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pkgprint-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pkgprint/__init__.py,sha256=ulgXTBBGuKYIajYYCaDUVWnv4GJ7GD6Jwr9azFUk8rI,1045
+pkgprint/color.py,sha256=BZ6Xl_Kr7cXOAZJ2hPzFxTVYn2wNmJL5qm0M0mao95c,6278
+pkgprint/paper.py,sha256=PqWh6aUiven9_qES6AyPQd9dK5JmybZNGkgVltpAO8Q,5252
+pkgprint/print_specs.py,sha256=p_7RxHNFlsvfQ5d09oZvey_Vqucvr8Xeul5Jo4uHUuo,6434
+pkgprint/units.py,sha256=wdeRkdypAw2-gbnj21bqHcFSlX1h0SMsk_zS6OyUus0,4292
+pkgprint-0.1.0.dist-info/LICENSE,sha256=NKgQ3-TWgHdRTQX1pYHv12yIXKOQ5_AUxjm_MMGI4LM,1064
+pkgprint-0.1.0.dist-info/METADATA,sha256=6usdQcQ0gu0FiUsOFnIBRVIPJvWOMuFQ-7blt1UzI5o,6156
+pkgprint-0.1.0.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
+pkgprint-0.1.0.dist-info/top_level.txt,sha256=BauSMV774J8U8YJnExtUUcw_yjTTe4ngEsrznqEDqzM,9
+pkgprint-0.1.0.dist-info/RECORD,,

pkgprint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pkgprint-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pkgprint