nima-persianguard 1.0.0__tar.gz

nima_persianguard-1.0.0/LICENSE

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

nima_persianguard-1.0.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: nima-persianguard
+Version: 1.0.0
+Summary: PersianGuard: modular Persian shaping/layout validation and infographic renderer with a single-pass RTL contract.
+Author: Nima Esmaili
+License: MIT
+Keywords: persian,rtl,bidi,arabic-reshaper,infographic,pillow
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0
+Provides-Extra: rtl
+Requires-Dist: arabic-reshaper>=3.0; extra == "rtl"
+Requires-Dist: python-bidi>=0.4; extra == "rtl"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: arabic-reshaper>=3.0; extra == "dev"
+Requires-Dist: python-bidi>=0.4; extra == "dev"
+Dynamic: license-file
+
+# nima_persianguard
+
+A clean, modular Python package extracted from the original PersianGuard
+infographic scripts (`nima_persianguard.py`,
+`Persian_Infographic-Nima_PersianGuard.py`). It preserves the exact text
+content, layout constants and rendering behavior while separating concerns
+into validation, layout, shaping and rendering modules with a stable public
+API and CLI.
+
+## Single-pass RTL contract
+
+The package enforces the audited contract from
+`shaping_bidi_review_report.txt`:
+
+1. **Logical source only** — every text entering the engine is validated by
+   `validate_source`: Arabic presentation forms (`U+FB50..U+FDFF`,
+   `U+FE70..U+FEFF`) and bidi control characters (`LRE/RLE/LRO/RLO/PDF/
+   LRI/RLI/FSI/PDI`) are rejected, so pre-shaped or visual-order text can
+   never enter the pipeline.
+2. **Shaping exactly once** — `arabic_reshaper.reshape` and
+   `bidi.algorithm.get_display` are combined only inside `shape()`. The final
+   display strings are produced once per line in the layout pass and cached
+   on the block (`display_lines`); the render pass draws the cached strings
+   verbatim and never reshapes. Intermediate measurement/wrapping passes are
+   direction-agnostic (they shape candidates only transiently to obtain
+   metrics and never store them).
+3. **No mirroring** — no canvas/coordinate flip or `ImageOps.mirror` exists;
+   directional work happens solely through Pillow text anchors
+   (`"ra"`, `"ma"`, `"la"`).
+
+The pytest suite (`tests/`) asserts these properties directly, e.g. that the
+render pass never re-applies `get_display` to already-final display lines and
+that a double-shaped source is rejected by `validate_source`.
+
+## Public API
+
+```python
+from nima_persianguard import NimaPersianGuard, build_scene
+
+guard = build_scene(3000, 2000)      # full default infographic
+image = guard.render()               # validates + renders (single pass)
+guard.update_text("title", "...")    # any change marks the scene dirty
+image = guard.render()               # full re-validation + re-render
+```
+
+Other entry points:
+
+- `NimaPersianGuard(width, height, font_path)` — empty canvas engine;
+  `add_text`, `update_text`, `set_font_size`, `resize_canvas`, `validate`,
+  `render`, `save`.
+- `nima_persianguard.validation.validate_source(text)` — logical-Unicode gate.
+- `nima_persianguard.textops.shape(text)` — the single shaping point
+  (`get_display(reshape(text))`).
+
+## CLI
+
+```
+python -m nima_persianguard --width 3000 --height 2000 -o out.png
+```
+
+Running the module rebuilds the default infographic, performs the mandatory
+resize/re-render invalidation check (2700×1800 → 3000×2000), exercises the
+font-size / text-update hooks and writes an optimized PNG.
+
+## Dependencies
+
+- Required: `Pillow`
+- Optional extras (recommended, used by the original renderer when
+  available): `arabic-reshaper`, `python-bidi`
+
+```
+pip install Pillow
+pip install arabic-reshaper python-bidi   # optional
+```
+
+Font: the original scripts use `/usr/share/fonts/truetype/Vazir.ttf`
+(`Vazir.ttf`); pass an alternative path via `NimaPersianGuard(font_path=...)`
+or `--font`.
+
+## Example
+
+`examples/recreate_infographic.py` recreates the original infographic with
+the packaged API:
+
+```
+python examples/recreate_infographic.py -o persian_infographic.png
+```
+
+## Tests
+
+```
+pytest tests/
+```
+
+Tests focus on the single-pass RTL contract: `shape` is the only shaping
+point, final display lines are cached and never reshaped again, and the
+render pass consumes cached strings.
+
+## Zeno v2 submission note
+
+For the Zeno v2 submission of *Nima Persiangard*:
+
+1. **What to submit**
+   - the full source archive `nima_persianguard_package.zip` (this package:
+     `nima_persianguard/`, `examples/`, `tests/`, `pyproject.toml`,
+     `README.md`, `LICENSE`), and
+   - the final rendered PNG produced by the example/CLI
+     (`persian_infographic_persianguard_v2.png`, 3000×2000, optimized).
+2. **How to describe the single-pass RTL guarantee** (use this wording or a
+   close paraphrase):
+   > "Every Persian string is supplied as logical Unicode and is validated at
+   > the boundary (`validate_source` rejects presentation forms and bidi
+   > control characters). Shaping (`arabic_reshaper.reshape`) followed by bidi
+   > reordering (`bidi.algorithm.get_display`) is applied exactly once, only
+   > in the final render pass, on cached per-line display strings. All
+   > intermediate measurement and layout passes are direction-agnostic and
+   > never produce or mutate display strings. There is no canvas flip, no
+   > mirror and no second shaping, so text cannot be reversed or
+   > double-shaped; this is enforced by automated contract tests in
+   > `tests/test_contract.py`."
+3. Reference `docs/shaping_bidi_review_report.txt` (verbatim audit report)
+   and `docs/current_texts.txt` (verbatim user Persian text) as supporting
+   evidence.
+
+## License
+
+MIT — see `LICENSE`.

nima_persianguard-1.0.0/README.md

@@ -0,0 +1,127 @@
+# nima_persianguard
+
+A clean, modular Python package extracted from the original PersianGuard
+infographic scripts (`nima_persianguard.py`,
+`Persian_Infographic-Nima_PersianGuard.py`). It preserves the exact text
+content, layout constants and rendering behavior while separating concerns
+into validation, layout, shaping and rendering modules with a stable public
+API and CLI.
+
+## Single-pass RTL contract
+
+The package enforces the audited contract from
+`shaping_bidi_review_report.txt`:
+
+1. **Logical source only** — every text entering the engine is validated by
+   `validate_source`: Arabic presentation forms (`U+FB50..U+FDFF`,
+   `U+FE70..U+FEFF`) and bidi control characters (`LRE/RLE/LRO/RLO/PDF/
+   LRI/RLI/FSI/PDI`) are rejected, so pre-shaped or visual-order text can
+   never enter the pipeline.
+2. **Shaping exactly once** — `arabic_reshaper.reshape` and
+   `bidi.algorithm.get_display` are combined only inside `shape()`. The final
+   display strings are produced once per line in the layout pass and cached
+   on the block (`display_lines`); the render pass draws the cached strings
+   verbatim and never reshapes. Intermediate measurement/wrapping passes are
+   direction-agnostic (they shape candidates only transiently to obtain
+   metrics and never store them).
+3. **No mirroring** — no canvas/coordinate flip or `ImageOps.mirror` exists;
+   directional work happens solely through Pillow text anchors
+   (`"ra"`, `"ma"`, `"la"`).
+
+The pytest suite (`tests/`) asserts these properties directly, e.g. that the
+render pass never re-applies `get_display` to already-final display lines and
+that a double-shaped source is rejected by `validate_source`.
+
+## Public API
+
+```python
+from nima_persianguard import NimaPersianGuard, build_scene
+
+guard = build_scene(3000, 2000)      # full default infographic
+image = guard.render()               # validates + renders (single pass)
+guard.update_text("title", "...")    # any change marks the scene dirty
+image = guard.render()               # full re-validation + re-render
+```
+
+Other entry points:
+
+- `NimaPersianGuard(width, height, font_path)` — empty canvas engine;
+  `add_text`, `update_text`, `set_font_size`, `resize_canvas`, `validate`,
+  `render`, `save`.
+- `nima_persianguard.validation.validate_source(text)` — logical-Unicode gate.
+- `nima_persianguard.textops.shape(text)` — the single shaping point
+  (`get_display(reshape(text))`).
+
+## CLI
+
+```
+python -m nima_persianguard --width 3000 --height 2000 -o out.png
+```
+
+Running the module rebuilds the default infographic, performs the mandatory
+resize/re-render invalidation check (2700×1800 → 3000×2000), exercises the
+font-size / text-update hooks and writes an optimized PNG.
+
+## Dependencies
+
+- Required: `Pillow`
+- Optional extras (recommended, used by the original renderer when
+  available): `arabic-reshaper`, `python-bidi`
+
+```
+pip install Pillow
+pip install arabic-reshaper python-bidi   # optional
+```
+
+Font: the original scripts use `/usr/share/fonts/truetype/Vazir.ttf`
+(`Vazir.ttf`); pass an alternative path via `NimaPersianGuard(font_path=...)`
+or `--font`.
+
+## Example
+
+`examples/recreate_infographic.py` recreates the original infographic with
+the packaged API:
+
+```
+python examples/recreate_infographic.py -o persian_infographic.png
+```
+
+## Tests
+
+```
+pytest tests/
+```
+
+Tests focus on the single-pass RTL contract: `shape` is the only shaping
+point, final display lines are cached and never reshaped again, and the
+render pass consumes cached strings.
+
+## Zeno v2 submission note
+
+For the Zeno v2 submission of *Nima Persiangard*:
+
+1. **What to submit**
+   - the full source archive `nima_persianguard_package.zip` (this package:
+     `nima_persianguard/`, `examples/`, `tests/`, `pyproject.toml`,
+     `README.md`, `LICENSE`), and
+   - the final rendered PNG produced by the example/CLI
+     (`persian_infographic_persianguard_v2.png`, 3000×2000, optimized).
+2. **How to describe the single-pass RTL guarantee** (use this wording or a
+   close paraphrase):
+   > "Every Persian string is supplied as logical Unicode and is validated at
+   > the boundary (`validate_source` rejects presentation forms and bidi
+   > control characters). Shaping (`arabic_reshaper.reshape`) followed by bidi
+   > reordering (`bidi.algorithm.get_display`) is applied exactly once, only
+   > in the final render pass, on cached per-line display strings. All
+   > intermediate measurement and layout passes are direction-agnostic and
+   > never produce or mutate display strings. There is no canvas flip, no
+   > mirror and no second shaping, so text cannot be reversed or
+   > double-shaped; this is enforced by automated contract tests in
+   > `tests/test_contract.py`."
+3. Reference `docs/shaping_bidi_review_report.txt` (verbatim audit report)
+   and `docs/current_texts.txt` (verbatim user Persian text) as supporting
+   evidence.
+
+## License
+
+MIT — see `LICENSE`.

nima_persianguard-1.0.0/nima_persianguard/__init__.py

@@ -0,0 +1,41 @@
+"""nima_persianguard - modular Persian shaping/layout validation + infographic renderer.
+
+Public API::
+
+    from nima_persianguard import NimaPersianGuard, build_scene, render_infographic
+"""
+
+from .engine import NimaPersianGuard, TextItem
+from .scene import build_scene, SCENE_WIDTH, SCENE_HEIGHT
+from .textops import (TextSourceError, ReorderingSkipped, validate_source,
+                      shape, TextBlock, stats as text_stats)
+from .validator import ValidationReport, ValidationError, validate_layout
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "NimaPersianGuard",
+    "TextItem",
+    "build_scene",
+    "render_infographic",
+    "SCENE_WIDTH",
+    "SCENE_HEIGHT",
+    "validate_source",
+    "shape",
+    "TextBlock",
+    "TextSourceError",
+    "ReorderingSkipped",
+    "ValidationReport",
+    "ValidationError",
+    "validate_layout",
+    "text_stats",
+    "__version__",
+]
+
+
+def render_infographic(path: str, width: int = SCENE_WIDTH,
+                       height: int = SCENE_HEIGHT,
+                       font_path: str = None) -> str:
+    """Build the default 3000x2000 infographic and save it as PNG."""
+    guard = build_scene(width, height, font_path=font_path)
+    return guard.save(path)

nima_persianguard-1.0.0/nima_persianguard/cli.py

@@ -0,0 +1,60 @@
+"""Command-line entrypoint: ``nima-persianguard render`` / ``validate``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from .engine import NimaPersianGuard, DEFAULT_FONT_CANDIDATES
+from .scene import build_scene, SCENE_WIDTH, SCENE_HEIGHT
+
+
+def _common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--width", type=int, default=SCENE_WIDTH)
+    parser.add_argument("--height", type=int, default=SCENE_HEIGHT)
+    parser.add_argument("--font", default=None,
+                        help="path to a Persian-capable TTF (default: auto)")
+    parser.add_argument("--lenient", action="store_true",
+                        help="do not raise on validation issues; report only")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="nima-persianguard",
+        description="PersianGuard: single-pass Persian shaping, validation "
+                    "and infographic rendering.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_render = sub.add_parser("render", help="render the default infographic")
+    _common_args(p_render)
+    p_render.add_argument("-o", "--output", default="persian_infographic.png")
+
+    p_validate = sub.add_parser("validate", help="validate and print a report")
+    _common_args(p_validate)
+
+    args = parser.parse_args(argv)
+    guard = build_scene(args.width, args.height, font_path=args.font)
+    guard.strict = not args.lenient
+
+    if args.command == "validate":
+        report = guard.validate()
+        print(report.summary())
+        return 0 if report.ok else 1
+
+    # mandatory resize/re-render invalidation check
+    w0, h0 = guard.width, guard.height
+    guard.resize_canvas(int(w0 * 0.9), int(h0 * 0.9))
+    guard.resize_canvas(w0, h0)
+    report = guard.validate()
+    if not report.ok:
+        print(report.summary(), file=sys.stderr)
+        return 1
+    path = guard.save(args.output)
+    print("rendered %s (%dx%d, %d text blocks, state=%s)"
+          % (path, guard.width, guard.height, len(guard), guard.state))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())