bookbarcode 0.4.1__tar.gz

bookbarcode-0.4.1/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to BookBarcode are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.1] - 2026-09-20
+
+### Added
+
+- Added a project changelog reconstructed from declared package versions,
+  release tags, and commit history.
+- Added GitHub Actions CI across Python 3.9-3.13 on Linux, with a gated
+  distribution build and metadata check.
+- Added a generated barcode preview using the example ISBN from the
+  International ISBN Agency's Users' Manual.
+
+### Changed
+
+- Reworked README onboarding around explicit CLI, Python API, and agent entry
+  points, with complete PyPI and editable-development installation paths.
+- Replaced project-specific ISBN examples and test fixtures with published
+  reference examples, and made PyPI the primary installation path.
+
+## [0.4.0] - 2026-09-02
+
+### Added
+
+- Added the typed `LayoutSpec -> resolve_layout() -> ResolvedBarcodeLayout ->
+  BarcodeGeometry` measurement pipeline.
+- Added a canonical measurement dependency DAG documenting derivation and
+  constraint relationships.
+- Added public geometry and resolved-layout types for callers that need an
+  explicit, fully resolved representation.
+- Added stronger PDF artifact inspection for page dimensions, process-black
+  commands, barcode modules, guard bars, human-readable digits, and physical
+  geometry.
+- Added negative tests for tampered SVG and PDF artifacts.
+- Added end-to-end JSON adapter tests for generation, verification, path,
+  overwrite, and invalid-input behavior.
+- Added `USE_TOOL.md` as the agent operating procedure and expanded
+  `SKILL.yaml` as the canonical machine-readable tool contract.
+- Added English usage and KDY reference documentation alongside the Turkish
+  guides.
+
+### Changed
+
+- Both SVG and PDF renderers now consume the same resolved barcode geometry.
+- Layout resolution now rejects non-standard geometry that violates mandatory
+  module, quiet-zone, guard-extension, or vertical-layout constraints.
+- SVG and PDF verification calculations are more independent from renderer
+  implementation helpers.
+- README and user guides now explain output selection, custom layouts,
+  overwrite policy, assigned ISBN hyphenation, and production preflight.
+- Package metadata, licensing, source manifests, and development dependencies
+  were prepared for public distribution.
+
+### Safety
+
+- Bundle writes now perform preflight checks before producing either output,
+  reducing avoidable partial SVG/PDF bundles.
+- Generated artifacts are verified before atomic replacement of their target
+  files.
+
+## [0.3.0] - 2026-08-31
+
+### Added
+
+- Introduced the reusable typed `bookbarcode` Python package.
+- Added immutable `Barcode` and `BarcodeLayout` public APIs.
+- Added ISBN-13 normalization and checksum validation for `978` and `979`
+  prefixes.
+- Added deterministic 95-module EAN-13 encoding and shared millimetre-based
+  geometry.
+- Added editable SVG and process-black CMYK PDF renderers.
+- Added serialized artifact verification for SVG and PDF outputs.
+- Added the `bookbarcode` human CLI and JSON agent-tool entrypoint.
+- Added normal 35 x 19 mm and minimum 26 x 14 mm KDY presets.
+- Added validated atomic file writes with explicit overwrite protection.
+- Added package, CLI, and adapter test suites, type information, examples,
+  Turkish documentation, and agent maintenance guidance.
+
+### Changed
+
+- Replaced the original single-file prototype with separated ISBN, EAN,
+  layout, geometry, rendering, verification, I/O, CLI, and adapter modules.
+
+## [0.1.0] - 2026-08-25
+
+### Added
+
+- Added the initial standalone ISBN-13/EAN-13 SVG generator prototype.
+- Added basic physical barcode sizing, guard bars, quiet zones, visible ISBN
+  text, and CMYK intent metadata.
+
+[Unreleased]: https://github.com/Aues12/BookBarcode/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/Aues12/BookBarcode/releases/tag/v0.4.1
+[0.4.0]: https://github.com/Aues12/BookBarcode/releases/tag/v0.4.0
+[0.3.0]: https://github.com/Aues12/BookBarcode/commit/4c047fd04b94878b9d242302b8d7676389ccc0a5
+[0.1.0]: https://github.com/Aues12/BookBarcode/commit/2e80d18b6c895f2cc99d724e0a4d97e256daccfc

bookbarcode-0.4.1/LICENSE

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

bookbarcode-0.4.1/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include CHANGELOG.md
+include USE_TOOL.md
+include LICENSE
+include pyproject.toml
+include isbn_barcode.py
+include tool.py
+include SKILL.yaml
+recursive-include bookbarcode *.py py.typed
+recursive-include docs *.md *.svg
+recursive-include examples *.py
+recursive-include tests *.py

bookbarcode-0.4.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: bookbarcode
+Version: 0.4.1
+Summary: Deterministic, print-ready ISBN-13 barcode generation for SVG and CMYK PDF
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Aues12/BookBarcode
+Project-URL: Repository, https://github.com/Aues12/BookBarcode
+Project-URL: Issues, https://github.com/Aues12/BookBarcode/issues
+Keywords: barcode,ean-13,isbn,pdf,svg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# BookBarcode
+
+[![CI](https://github.com/Aues12/BookBarcode/actions/workflows/CI.yml/badge.svg)](https://github.com/Aues12/BookBarcode/actions/workflows/CI.yml)
+
+BookBarcode generates deterministic ISBN-13/EAN-13 barcodes for books.
+It creates editable SVG files and print-ready PDF files, and checks each
+artifact before writing it.
+
+- **PDF** is the recommended final format for printing. It uses true process
+  black: `C:0 M:0 Y:0 K:100`.
+- **SVG** is useful for vector editing and preview. It includes CMYK intent
+  metadata, although colour handling ultimately depends on the SVG application.
+
+The package has no runtime third-party dependencies and supports Python 3.9+.
+
+![BookBarcode example output for ISBN 978-92-95055-12-4](https://raw.githubusercontent.com/Aues12/BookBarcode/main/docs/assets/bookbarcode-preview.svg)
+
+*Example generated from the ISBN used in the International ISBN Agency's
+[Users' Manual](https://www.isbn-international.org/content/isbn-users-manual/29).*
+
+## Choose an entrypoint
+
+| I want to... | Start with |
+|---|---|
+| Generate a barcode from a terminal | [Human CLI](#quick-start) |
+| Use BookBarcode from Python | [Python API](#python-api) |
+| Call BookBarcode from an agent | [JSON agent interface](#agent-tools-json-interface) |
+
+## Quick start
+
+Install the current release from PyPI:
+
+```bash
+python3 -m pip install "bookbarcode==0.4.1"
+```
+
+Generate both formats with a valid ISBN-13:
+
+```bash
+bookbarcode 9789295055124 \
+  --display "ISBN 978-92-95055-12-4"
+```
+
+This creates and verifies these files in the current directory:
+
+```text
+book-barcode.svg
+book-barcode.pdf
+```
+
+The command refuses to replace an existing file unless you add `--overwrite`.
+It writes a temporary sibling, verifies it, then atomically installs it at the
+target path.
+
+For an editable development installation, clone the repository first:
+
+```bash
+git clone https://github.com/Aues12/BookBarcode.git
+cd BookBarcode
+python3 -m pip install -e .
+```
+
+You can also run the command from this repository without installing it:
+
+```bash
+python3 -m bookbarcode.cli 9789295055124 \
+  --display "ISBN 978-92-95055-12-4"
+```
+
+## Common tasks
+
+Create a print-ready PDF at a chosen path:
+
+```bash
+bookbarcode 9789295055124 \
+  --format pdf \
+  --output output/book-barcode
+```
+
+Use the smallest bundled layout when space is constrained:
+
+```bash
+bookbarcode 9789295055124 \
+  --preset minimum \
+  --output output/small-book-barcode
+```
+
+Use assigned ISBN hyphenation in the visible heading:
+
+```bash
+bookbarcode 9780306406157 \
+  --display "ISBN 978-0-306-40615-7" \
+  --output output/book-barcode
+```
+
+Without `--display`, BookBarcode uses a readable `3-3-3-3-1` fallback. This is
+not an assertion about official ISBN registrant ranges; provide the assigned
+hyphenation when it matters.
+
+## Layout and output
+
+| Preset | Dimensions | Best for |
+|---|---:|---|
+| `normal` (default) | 35 × 19 mm | Typical book barcodes |
+| `minimum` | 26 × 14 mm | Space-constrained covers |
+
+By default, BookBarcode writes both SVG and PDF. Use `--format svg` or
+`--format pdf` to select one. `--output` sets the base path, so
+`--output output/barcode` produces `output/barcode.svg` and/or
+`output/barcode.pdf`; the directory must already exist.
+
+Custom total dimensions, data-bar height, and either shared or independent
+side margins are available. The detailed commands and the full option reference
+are in the [English user guide](docs/USAGE.md). Their mandatory formulas,
+dependencies, and constraints are defined by the
+[measurement dependency DAG](docs/MEASUREMENT-DAG.md).
+
+## Python API
+
+Generate content without writing files:
+
+```python
+from bookbarcode import Barcode
+
+barcode = Barcode("9789295055124")
+svg_text = barcode.to_svg()
+pdf_bytes = barcode.to_pdf()
+```
+
+Write verified artifacts explicitly:
+
+```python
+from bookbarcode import Barcode, BarcodeLayout
+
+layout = BarcodeLayout(
+    width_mm=38,
+    height_mm=20,
+    side_margin_mm=3.8,
+    bar_height_mm=12.5,
+)
+barcode = Barcode(
+    "9789295055124",
+    display_text="ISBN 978-92-95055-12-4",
+    layout=layout,
+)
+barcode.write_svg("book-barcode.svg")
+barcode.write_pdf("book-barcode.pdf")
+```
+
+One module (`X`) is the narrowest EAN-13 bar/space unit. Custom margins are
+accepted only when they preserve quiet zones of at least `11X` on the left and
+`7X` on the right.
+
+For explicit intent/resolution separation, use the typed measurement pipeline:
+
+```python
+from bookbarcode import LayoutSpec, build_barcode_geometry, resolve_layout
+
+spec = LayoutSpec.from_preset("normal", side_margin_mm=3.5)
+resolved = resolve_layout(spec)
+geometry = build_barcode_geometry(
+    "9789295055124",
+    "ISBN 978-92-95055-12-4",
+    resolved,
+)
+```
+
+`resolved` contains no optional measurements. `geometry` contains the complete
+title, bar, and human-readable digit positions consumed by both renderers.
+
+## Agent-tools JSON interface
+
+Agent tools can use BookBarcode as a tool by sending a JSON request envelope to
+`isbn_barcode.py` over standard input. The adapter translates that request to
+the same package API used by Python and the CLI; it does not implement barcode
+rules independently.
+
+```bash
+printf '%s' '{
+  "operation": "write_barcode",
+  "params": {
+    "isbn": "9789295055124",
+    "output_base": "/tmp/book-barcode",
+    "layout": {"preset": "normal"}
+  }
+}' | python3 isbn_barcode.py
+```
+
+Supported operations are `generate_svg`, `write_svg`, `write_pdf`,
+`write_barcode`, `verify_svg`, and `verify_pdf`. Agents and runtimes should read
+the [tool usage procedure](USE_TOOL.md); [SKILL.yaml](SKILL.yaml) is the
+canonical local machine-readable manifest.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md) — release history and notable changes by version.
+- [English user guide](docs/USAGE.md) — installation, complete CLI reference,
+  custom layouts, printing guidance, common errors, and examples.
+- [Türkçe kullanım kılavuzu](docs/KULLANIM.md)
+- [Agent tool usage procedure](USE_TOOL.md)
+- [Canonical measurement dependency DAG](docs/MEASUREMENT-DAG.md)
+- [KDY size and colour reference notes](docs/KDY-REFERENCE-NOTES.md)
+- [KDY ölçü ve renk referans notları](docs/KDY-REFERANS-NOTLARI.md)
+
+## Quality and printing
+
+BookBarcode verifies serialized SVG and PDF dimensions, barcode modules, guard
+bars, readable ISBN digits, physical geometry, and colour intent. PDF checks
+parse the content stream rather than trusting the renderer's input geometry.
+For production, keep quiet zones clear, do not scale the barcode
+non-proportionally or rasterize it, and scan a printed sample after printer
+preflight.
+
+Run the test suite from the repository root:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+BookBarcode is released under the [MIT License](LICENSE).

bookbarcode-0.4.1/README.md

@@ -0,0 +1,220 @@
+# BookBarcode
+
+[![CI](https://github.com/Aues12/BookBarcode/actions/workflows/CI.yml/badge.svg)](https://github.com/Aues12/BookBarcode/actions/workflows/CI.yml)
+
+BookBarcode generates deterministic ISBN-13/EAN-13 barcodes for books.
+It creates editable SVG files and print-ready PDF files, and checks each
+artifact before writing it.
+
+- **PDF** is the recommended final format for printing. It uses true process
+  black: `C:0 M:0 Y:0 K:100`.
+- **SVG** is useful for vector editing and preview. It includes CMYK intent
+  metadata, although colour handling ultimately depends on the SVG application.
+
+The package has no runtime third-party dependencies and supports Python 3.9+.
+
+![BookBarcode example output for ISBN 978-92-95055-12-4](https://raw.githubusercontent.com/Aues12/BookBarcode/main/docs/assets/bookbarcode-preview.svg)
+
+*Example generated from the ISBN used in the International ISBN Agency's
+[Users' Manual](https://www.isbn-international.org/content/isbn-users-manual/29).*
+
+## Choose an entrypoint
+
+| I want to... | Start with |
+|---|---|
+| Generate a barcode from a terminal | [Human CLI](#quick-start) |
+| Use BookBarcode from Python | [Python API](#python-api) |
+| Call BookBarcode from an agent | [JSON agent interface](#agent-tools-json-interface) |
+
+## Quick start
+
+Install the current release from PyPI:
+
+```bash
+python3 -m pip install "bookbarcode==0.4.1"
+```
+
+Generate both formats with a valid ISBN-13:
+
+```bash
+bookbarcode 9789295055124 \
+  --display "ISBN 978-92-95055-12-4"
+```
+
+This creates and verifies these files in the current directory:
+
+```text
+book-barcode.svg
+book-barcode.pdf
+```
+
+The command refuses to replace an existing file unless you add `--overwrite`.
+It writes a temporary sibling, verifies it, then atomically installs it at the
+target path.
+
+For an editable development installation, clone the repository first:
+
+```bash
+git clone https://github.com/Aues12/BookBarcode.git
+cd BookBarcode
+python3 -m pip install -e .
+```
+
+You can also run the command from this repository without installing it:
+
+```bash
+python3 -m bookbarcode.cli 9789295055124 \
+  --display "ISBN 978-92-95055-12-4"
+```
+
+## Common tasks
+
+Create a print-ready PDF at a chosen path:
+
+```bash
+bookbarcode 9789295055124 \
+  --format pdf \
+  --output output/book-barcode
+```
+
+Use the smallest bundled layout when space is constrained:
+
+```bash
+bookbarcode 9789295055124 \
+  --preset minimum \
+  --output output/small-book-barcode
+```
+
+Use assigned ISBN hyphenation in the visible heading:
+
+```bash
+bookbarcode 9780306406157 \
+  --display "ISBN 978-0-306-40615-7" \
+  --output output/book-barcode
+```
+
+Without `--display`, BookBarcode uses a readable `3-3-3-3-1` fallback. This is
+not an assertion about official ISBN registrant ranges; provide the assigned
+hyphenation when it matters.
+
+## Layout and output
+
+| Preset | Dimensions | Best for |
+|---|---:|---|
+| `normal` (default) | 35 × 19 mm | Typical book barcodes |
+| `minimum` | 26 × 14 mm | Space-constrained covers |
+
+By default, BookBarcode writes both SVG and PDF. Use `--format svg` or
+`--format pdf` to select one. `--output` sets the base path, so
+`--output output/barcode` produces `output/barcode.svg` and/or
+`output/barcode.pdf`; the directory must already exist.
+
+Custom total dimensions, data-bar height, and either shared or independent
+side margins are available. The detailed commands and the full option reference
+are in the [English user guide](docs/USAGE.md). Their mandatory formulas,
+dependencies, and constraints are defined by the
+[measurement dependency DAG](docs/MEASUREMENT-DAG.md).
+
+## Python API
+
+Generate content without writing files:
+
+```python
+from bookbarcode import Barcode
+
+barcode = Barcode("9789295055124")
+svg_text = barcode.to_svg()
+pdf_bytes = barcode.to_pdf()
+```
+
+Write verified artifacts explicitly:
+
+```python
+from bookbarcode import Barcode, BarcodeLayout
+
+layout = BarcodeLayout(
+    width_mm=38,
+    height_mm=20,
+    side_margin_mm=3.8,
+    bar_height_mm=12.5,
+)
+barcode = Barcode(
+    "9789295055124",
+    display_text="ISBN 978-92-95055-12-4",
+    layout=layout,
+)
+barcode.write_svg("book-barcode.svg")
+barcode.write_pdf("book-barcode.pdf")
+```
+
+One module (`X`) is the narrowest EAN-13 bar/space unit. Custom margins are
+accepted only when they preserve quiet zones of at least `11X` on the left and
+`7X` on the right.
+
+For explicit intent/resolution separation, use the typed measurement pipeline:
+
+```python
+from bookbarcode import LayoutSpec, build_barcode_geometry, resolve_layout
+
+spec = LayoutSpec.from_preset("normal", side_margin_mm=3.5)
+resolved = resolve_layout(spec)
+geometry = build_barcode_geometry(
+    "9789295055124",
+    "ISBN 978-92-95055-12-4",
+    resolved,
+)
+```
+
+`resolved` contains no optional measurements. `geometry` contains the complete
+title, bar, and human-readable digit positions consumed by both renderers.
+
+## Agent-tools JSON interface
+
+Agent tools can use BookBarcode as a tool by sending a JSON request envelope to
+`isbn_barcode.py` over standard input. The adapter translates that request to
+the same package API used by Python and the CLI; it does not implement barcode
+rules independently.
+
+```bash
+printf '%s' '{
+  "operation": "write_barcode",
+  "params": {
+    "isbn": "9789295055124",
+    "output_base": "/tmp/book-barcode",
+    "layout": {"preset": "normal"}
+  }
+}' | python3 isbn_barcode.py
+```
+
+Supported operations are `generate_svg`, `write_svg`, `write_pdf`,
+`write_barcode`, `verify_svg`, and `verify_pdf`. Agents and runtimes should read
+the [tool usage procedure](USE_TOOL.md); [SKILL.yaml](SKILL.yaml) is the
+canonical local machine-readable manifest.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md) — release history and notable changes by version.
+- [English user guide](docs/USAGE.md) — installation, complete CLI reference,
+  custom layouts, printing guidance, common errors, and examples.
+- [Türkçe kullanım kılavuzu](docs/KULLANIM.md)
+- [Agent tool usage procedure](USE_TOOL.md)
+- [Canonical measurement dependency DAG](docs/MEASUREMENT-DAG.md)
+- [KDY size and colour reference notes](docs/KDY-REFERENCE-NOTES.md)
+- [KDY ölçü ve renk referans notları](docs/KDY-REFERANS-NOTLARI.md)
+
+## Quality and printing
+
+BookBarcode verifies serialized SVG and PDF dimensions, barcode modules, guard
+bars, readable ISBN digits, physical geometry, and colour intent. PDF checks
+parse the content stream rather than trusting the renderer's input geometry.
+For production, keep quiet zones clear, do not scale the barcode
+non-proportionally or rasterize it, and scan a printed sample after printer
+preflight.
+
+Run the test suite from the repository root:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+BookBarcode is released under the [MIT License](LICENSE).