pkgprint 0.1.0__tar.gz

pkgprint-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,171 @@
+# 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/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-0.1.0/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))