forktex-documents 0.1.0__tar.gz

forktex_documents-0.1.0/LICENSE

@@ -0,0 +1,45 @@
+ForkTex Documents -- Dual License
+
+Copyright (C) 2026 FORKTEX S.R.L.
+
+This software is licensed under a dual-license model:
+
+============================================================================
+
+1. OPEN-SOURCE LICENSE -- GNU Affero General Public License v3.0 (AGPL-3.0)
+
+   You may use, modify, and redistribute this software under the terms of the
+   GNU Affero General Public License v3.0 or later, as published by the Free
+   Software Foundation. The full license text is available at:
+   https://www.gnu.org/licenses/agpl-3.0.html
+
+   Key obligations under AGPL-3.0:
+   - Any modified version MUST be released under the same AGPL-3.0 license.
+   - If you run a modified version on a server and let users interact with it
+     over a network, you MUST make the complete source code available to those
+     users under AGPL-3.0.
+   - You MUST preserve all copyright notices and attribution to FORKTEX S.R.L.
+
+============================================================================
+
+2. COMMERCIAL LICENSE
+
+   If you wish to use this software without the obligations of AGPL-3.0 --
+   for example, to keep your modifications proprietary, to embed this software
+   in a closed-source product, or to operate it as part of a commercial service
+   without releasing your source code -- you MUST obtain a commercial license
+   from FORKTEX S.R.L.
+
+   Commercial licensing includes, but is not limited to:
+   - SaaS / hosted deployments generating revenue
+   - Embedding in proprietary products or platforms
+   - Redistribution in closed-source form
+   - Use by organizations exceeding the AGPL-3.0 compliance scope
+
+   For commercial licensing inquiries, contact:
+     info@forktex.com
+
+============================================================================
+
+Unless you have obtained a separate commercial license from FORKTEX S.R.L.,
+your use of this software is governed exclusively by the AGPL-3.0 license.

forktex_documents-0.1.0/NOTICE

@@ -0,0 +1,41 @@
+ForkTex Documents
+Copyright (C) 2026 FORKTEX S.R.L.
+
+This product includes software developed by FORKTEX S.R.L. (info@forktex.com).
+
+`forktex-documents` generates the documents a company issues -- invoices,
+contracts, stock-reception notes, declarations, reports -- from structured
+data. A record is validated by a Pydantic canonical, composed into a typed
+block tree, and projected to HTML, PDF or UBL XML. The rendered page is a view
+over the record, never a source of truth. It ships no company's data: a
+consumer supplies the parties, the lines and the numbering.
+
+LICENSING
+
+This software is dual-licensed:
+
+  1. GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
+     Use it under the AGPL and its obligations apply -- notably that running a
+     modified version over a network requires offering the corresponding source
+     to its users.
+
+  2. A proprietary commercial license from FORKTEX S.R.L.
+
+If you cannot meet the AGPL's obligations -- use in a proprietary product, a
+SaaS deployment, or any context where offering source is not possible -- you
+MUST obtain a commercial license. Contact info@forktex.com.
+
+See the LICENSE file for the full terms of both.
+
+THIRD-PARTY NOTICES
+
+This package depends on, but does not vendor:
+
+  * pydantic   -- MIT
+  * jinja2     -- BSD-3-Clause  (sandboxed text-fragment rendering only)
+  * forktex    -- AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+  * weasyprint -- BSD-3-Clause  (optional, for the `pdf` extra)
+
+The document text carried in this repository's Romanian locale bundle is
+transcribed from statutory and administrative forms; the legal wording is not
+the copyrightable work of FORKTEX S.R.L.

forktex_documents-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: forktex-documents
+Version: 0.1.0
+Summary: A framework for generating documents from structured data: typed blocks that render themselves, canonicals that compute their own totals, and cited mandates. Document types belong to consumers.
+License-Expression: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+License-File: LICENSE
+License-File: NOTICE
+Author: FORKTEX
+Author-email: info@forktex.com
+Requires-Python: >=3.14,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Legal Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Printing
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+Provides-Extra: pdf
+Requires-Dist: forktex (>=0.10,<0.11)
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: pydantic (>=2.12)
+Requires-Dist: weasyprint (>=62) ; extra == "pdf"
+Project-URL: Bug Tracker, https://github.com/forktex/forktex-documents/issues
+Project-URL: Changelog, https://github.com/forktex/forktex-documents/blob/master/CHANGELOG.md
+Project-URL: Documentation, https://github.com/forktex/forktex-documents/tree/master/docs
+Project-URL: Homepage, https://forktex.com
+Project-URL: Repository, https://github.com/forktex/forktex-documents
+Description-Content-Type: text/markdown
+
+# forktex-documents
+
+A framework for generating documents from structured data. It ships the
+vocabulary and the machinery — **not** document types: an invoice, a contract, a
+delivery note are things a consumer defines, because what they must contain is
+a fact about a business and a jurisdiction, not about a renderer.
+
+```
+data (JSON)  →  canonical (Pydantic)  →  block tree  →  HTML → PDF
+                        ↘  read directly for a machine projection (XML, JSON…)
+```
+
+A PDF here is a **view over an object**, never a source of truth. The canonical
+record is the document; the page is one projection of it. A machine projection
+reads the canonical directly rather than the block tree — you cannot recover
+"19% VAT on this line" from a table cell that says `19%`, which is why the two
+representations both exist.
+
+## Install
+
+```bash
+pip install forktex-documents          # canonical, blocks, HTML
+pip install "forktex-documents[pdf]"   # + PDF, via WeasyPrint
+```
+
+PDF is an extra because WeasyPrint pulls native libraries (cairo, pango) that a
+consumer producing only HTML or a machine projection should not have to install.
+
+## What it does
+
+A consumer declares its own canonical, and gets validation, composition and
+rendering from the framework:
+
+```python
+from forktex_documents import FamilyCanonical, Mandate, ParagraphBlock, known
+
+@known
+class DeliveryNote(FamilyCanonical):
+    family = "logistics"
+    mandates = (
+        Mandate(
+            path="carrier",
+            authority="acme-logistics",
+            reference="ops:carrier-is-named",
+            reason="A note with no carrier cannot be chased when the goods do not arrive.",
+        ),
+    )
+    reference: str
+    carrier: str
+
+    def blocks(self, profile):
+        return (ParagraphBlock(text=f"Carried by {self.carrier}."),)
+
+note = DeliveryNote(reference="DN-1", carrier="Speedy")
+note.check()                      # raises if a mandate is unsatisfied
+note.blocks(profile)              # a typed block tree, ready to project
+```
+
+See [`examples/showcase.py`](examples/showcase.py) for a document exercising
+every block kind.
+
+## The ideas worth knowing
+
+**Derived values are never stored.** A consumer's totals, VAT subtotals and
+expiry dates are `computed_field`s on its own canonical — and this package is
+what makes that hold. Every model sets `extra="forbid"`, so a record carrying a
+hand-written `total` is a validation error rather than a silent disagreement,
+and a stored total that was tampered with is dropped and recomputed on load.
+A structural guarantee rather than a review rule.
+
+**Mandates are cited and conditional.** What a jurisdiction requires is data:
+a path, the authority, the legal reference, and *why*. Conditions read computed
+flags, so a retail stock-reception note demands a selling price while a
+cost-method one does not, and a delivery showing quantity differences demands a
+three-member committee and a third copy — because those are the rules the form
+actually carries.
+
+**Fiscal facts are time-versioned.** VAT rates resolve against the document's
+own date, so re-rendering a July 2025 Romanian invoice reproduces 19% rather
+than silently restating it at the current 21%. A date no schedule covers raises
+instead of guessing.
+
+**Blocks render themselves.** Twenty-five typed block kinds form a closed
+discriminated union, each emitting its own HTML. There is no template language
+deciding layout — the only templating is sandboxed *text* substitution for
+locale fragments, where a clause has placeholders to resolve.
+
+**Identifiers are validated, not merely shaped.** CUI and CNP check digits,
+IBAN mod-97 across every country's length rule, per-member-state VAT formats.
+A transposed digit in a national id files a real document against the wrong
+person; the checksum is what catches it.
+
+## What is *not* here
+
+No invoice, no contract, no delivery note, and no jurisdiction. There is no
+`RO_VAT_RATES`, no CUI or CNP check digit, and no default country, language or
+currency anywhere — a default jurisdiction is a wrong jurisdiction for everyone
+else, quietly. A consumer supplies its own:
+
+- a `LegislationProfile` with its date format, separators, currency and mandates
+- a `VatSchedule` with its rates and their validity windows
+- national identifier validators, registered into `NATIONAL_TAX_ID_VALIDATORS`
+- the numbers already spent, passed to a register as `BURNED`
+
+## Layout
+
+```
+domain/     blocks, canonical, mandates, entities, fiscal, localization, theme,
+            registry, series  ↑ no I/O — `grep Path domain/` is empty, by test
+render/     the HTML projector, inline SVG charts, the asset port
+```
+
+Imports run one way: `domain → render → facade`.
+
+## Development
+
+```bash
+make install     # poetry install --with dev
+make ci          # format, lint, licences, docs, types, audit, tests, build, smoke
+make reference   # rewrite committed reference renders — then read the diff
+make docs        # render the design records in sources/ into docs/
+```
+
+`make ci` re-renders every reference document and diffs it byte-for-byte
+against the committed HTML. A generated artefact that was hand-edited, or a
+change that altered output nobody intended, fails the build.
+
+The design notes in [`docs/`](docs/) are generated the same way, from JSON
+records in [`sources/`](sources/) via
+[`forktex-knowledge`](https://pypi.org/project/forktex-knowledge/) — the
+library eats its own principle, so a hand-edited page fails the gate rather
+than becoming a second author. Start with
+[everything-is-a-document](docs/everything-is-a-document.md) for why a page is
+never a source of truth, then
+[mandates-are-cited-data](docs/mandates-are-cited-data.md) for why a legal
+requirement travels with its citation.
+
+## Licence
+
+Dual-licensed: **AGPL-3.0-or-later**, or a commercial licence from FORKTEX
+S.R.L. for use in proprietary products, SaaS deployments, or any context where
+the AGPL's obligations cannot be met. See `LICENSE` and `NOTICE`, or contact
+info@forktex.com.
+

forktex_documents-0.1.0/README.md

@@ -0,0 +1,143 @@
+# forktex-documents
+
+A framework for generating documents from structured data. It ships the
+vocabulary and the machinery — **not** document types: an invoice, a contract, a
+delivery note are things a consumer defines, because what they must contain is
+a fact about a business and a jurisdiction, not about a renderer.
+
+```
+data (JSON)  →  canonical (Pydantic)  →  block tree  →  HTML → PDF
+                        ↘  read directly for a machine projection (XML, JSON…)
+```
+
+A PDF here is a **view over an object**, never a source of truth. The canonical
+record is the document; the page is one projection of it. A machine projection
+reads the canonical directly rather than the block tree — you cannot recover
+"19% VAT on this line" from a table cell that says `19%`, which is why the two
+representations both exist.
+
+## Install
+
+```bash
+pip install forktex-documents          # canonical, blocks, HTML
+pip install "forktex-documents[pdf]"   # + PDF, via WeasyPrint
+```
+
+PDF is an extra because WeasyPrint pulls native libraries (cairo, pango) that a
+consumer producing only HTML or a machine projection should not have to install.
+
+## What it does
+
+A consumer declares its own canonical, and gets validation, composition and
+rendering from the framework:
+
+```python
+from forktex_documents import FamilyCanonical, Mandate, ParagraphBlock, known
+
+@known
+class DeliveryNote(FamilyCanonical):
+    family = "logistics"
+    mandates = (
+        Mandate(
+            path="carrier",
+            authority="acme-logistics",
+            reference="ops:carrier-is-named",
+            reason="A note with no carrier cannot be chased when the goods do not arrive.",
+        ),
+    )
+    reference: str
+    carrier: str
+
+    def blocks(self, profile):
+        return (ParagraphBlock(text=f"Carried by {self.carrier}."),)
+
+note = DeliveryNote(reference="DN-1", carrier="Speedy")
+note.check()                      # raises if a mandate is unsatisfied
+note.blocks(profile)              # a typed block tree, ready to project
+```
+
+See [`examples/showcase.py`](examples/showcase.py) for a document exercising
+every block kind.
+
+## The ideas worth knowing
+
+**Derived values are never stored.** A consumer's totals, VAT subtotals and
+expiry dates are `computed_field`s on its own canonical — and this package is
+what makes that hold. Every model sets `extra="forbid"`, so a record carrying a
+hand-written `total` is a validation error rather than a silent disagreement,
+and a stored total that was tampered with is dropped and recomputed on load.
+A structural guarantee rather than a review rule.
+
+**Mandates are cited and conditional.** What a jurisdiction requires is data:
+a path, the authority, the legal reference, and *why*. Conditions read computed
+flags, so a retail stock-reception note demands a selling price while a
+cost-method one does not, and a delivery showing quantity differences demands a
+three-member committee and a third copy — because those are the rules the form
+actually carries.
+
+**Fiscal facts are time-versioned.** VAT rates resolve against the document's
+own date, so re-rendering a July 2025 Romanian invoice reproduces 19% rather
+than silently restating it at the current 21%. A date no schedule covers raises
+instead of guessing.
+
+**Blocks render themselves.** Twenty-five typed block kinds form a closed
+discriminated union, each emitting its own HTML. There is no template language
+deciding layout — the only templating is sandboxed *text* substitution for
+locale fragments, where a clause has placeholders to resolve.
+
+**Identifiers are validated, not merely shaped.** CUI and CNP check digits,
+IBAN mod-97 across every country's length rule, per-member-state VAT formats.
+A transposed digit in a national id files a real document against the wrong
+person; the checksum is what catches it.
+
+## What is *not* here
+
+No invoice, no contract, no delivery note, and no jurisdiction. There is no
+`RO_VAT_RATES`, no CUI or CNP check digit, and no default country, language or
+currency anywhere — a default jurisdiction is a wrong jurisdiction for everyone
+else, quietly. A consumer supplies its own:
+
+- a `LegislationProfile` with its date format, separators, currency and mandates
+- a `VatSchedule` with its rates and their validity windows
+- national identifier validators, registered into `NATIONAL_TAX_ID_VALIDATORS`
+- the numbers already spent, passed to a register as `BURNED`
+
+## Layout
+
+```
+domain/     blocks, canonical, mandates, entities, fiscal, localization, theme,
+            registry, series  ↑ no I/O — `grep Path domain/` is empty, by test
+render/     the HTML projector, inline SVG charts, the asset port
+```
+
+Imports run one way: `domain → render → facade`.
+
+## Development
+
+```bash
+make install     # poetry install --with dev
+make ci          # format, lint, licences, docs, types, audit, tests, build, smoke
+make reference   # rewrite committed reference renders — then read the diff
+make docs        # render the design records in sources/ into docs/
+```
+
+`make ci` re-renders every reference document and diffs it byte-for-byte
+against the committed HTML. A generated artefact that was hand-edited, or a
+change that altered output nobody intended, fails the build.
+
+The design notes in [`docs/`](docs/) are generated the same way, from JSON
+records in [`sources/`](sources/) via
+[`forktex-knowledge`](https://pypi.org/project/forktex-knowledge/) — the
+library eats its own principle, so a hand-edited page fails the gate rather
+than becoming a second author. Start with
+[everything-is-a-document](docs/everything-is-a-document.md) for why a page is
+never a source of truth, then
+[mandates-are-cited-data](docs/mandates-are-cited-data.md) for why a legal
+requirement travels with its citation.
+
+## Licence
+
+Dual-licensed: **AGPL-3.0-or-later**, or a commercial licence from FORKTEX
+S.R.L. for use in proprietary products, SaaS deployments, or any context where
+the AGPL's obligations cannot be met. See `LICENSE` and `NOTICE`, or contact
+info@forktex.com.

forktex_documents-0.1.0/pyproject.toml

@@ -0,0 +1,155 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Documents.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+[project]
+name = "forktex-documents"
+version = "0.1.0"
+description = "A framework for generating documents from structured data: typed blocks that render themselves, canonicals that compute their own totals, and cited mandates. Document types belong to consumers."
+authors = [
+    {name = "FORKTEX",email = "info@forktex.com"}
+]
+readme = "README.md"
+# Dual-licensed: AGPL-3.0-or-later for OSS use; a proprietary commercial
+# license is also available (see LICENSE + NOTICE; info@forktex.com).
+license = "AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.14,<4.0"
+# 4 - Beta: the vocabulary is proven — it was extracted from a working consumer
+# that renders thirteen real documents across four families. What has not been
+# proven is a *second* consumer pushing on the seams, which is what would justify
+# promoting this to 5.
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Legal Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Printing",
+    "Topic :: Text Processing :: Markup :: HTML",
+    "Typing :: Typed",
+]
+dependencies = [
+    # The shared substrate. Consumed, not re-implemented: `forktex.error` supplies
+    # the one exception hierarchy this package's errors are leaves of, and
+    # `forktex.types` supplies the frozen value-object base every model derives
+    # from. Pinned to a minor range because both are surfaces we track closely.
+    "forktex>=0.10,<0.11",
+    # Every model, every validator, every computed total. The design rule that
+    # derived values are never stored is enforced by `computed_field` plus
+    # `extra="forbid"`, so this is load-bearing rather than convenience.
+    "pydantic>=2.12",
+    # Sandboxed rendering of *text fragments* only — a locale bundle's clause and
+    # declaration text, where a placeholder must resolve against document data.
+    # No template decides layout: blocks render themselves in Python. That
+    # distinction is why the dependency is small and stays that way.
+    "jinja2>=3.1",
+]
+
+[project.optional-dependencies]
+# PDF is optional because the canonical, the block tree and the HTML projection
+# are useful without it, and WeasyPrint pulls native libraries (cairo, pango)
+# that a consumer producing only HTML or UBL should not be made to install.
+pdf = ["weasyprint>=62"]
+
+# No [project.scripts]: this is a library. A consumer wires its own entry point,
+# because the asset roots, the theme and the number register are its own.
+
+[project.urls]
+"Homepage" = "https://forktex.com"
+"Repository" = "https://github.com/forktex/forktex-documents"
+"Documentation" = "https://github.com/forktex/forktex-documents/tree/master/docs"
+"Changelog" = "https://github.com/forktex/forktex-documents/blob/master/CHANGELOG.md"
+"Bug Tracker" = "https://github.com/forktex/forktex-documents/issues"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+# The distribution is `forktex-documents` and the import is `forktex_documents`
+# — PEP 503 wants the hyphen on an index, Python wants the underscore in code.
+packages = [{ include = "forktex_documents", from = "src" }]
+# The stylesheet is not a sample: `HtmlProjector` reads `styles/paged.css`
+# through the asset port on every render, so a wheel without it produces
+# unstyled output. Shipped explicitly because it is not a `.py` file and would
+# otherwise be dropped from both the sdist and the wheel.
+include = [
+    { path = "src/forktex_documents/py.typed", format = ["sdist", "wheel"] },
+    { path = "src/forktex_documents/assets/**/*", format = ["sdist", "wheel"] },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.8.0",
+    "pyright>=1.1.350",
+    "pip-audit>=2.7.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+    # The drift gate renders the reference document, and `make render` takes it
+    # to PDF. Without it the example cannot run.
+    "weasyprint>=62",
+    # Renders the design records in `sources/` into `docs/`.
+    "forktex-knowledge (>=0.1.0,<0.2.0)",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "ANN"]
+# RUF001/2/3 flag characters that could be homoglyph attacks in *code*. This library's
+# strings are document text in Romanian, where they are simply correct typography: an
+# en dash in a range ("3–4 săptămâni"), a multiplication sign in a specification
+# ("10 × 450 W"), and — load-bearing — a NO-BREAK SPACE as the thousands separator, which
+# is what stops "201 020,27" being broken across a line in a printed invoice. Replacing
+# them with ASCII would change what the documents say, so the rules are off rather than
+# suppressed line by line.
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.ruff.lint.per-file-ignores]
+# `src/` carries NO exemptions — every module passes the full strict set. A new
+# `Any` in a signature is a prompt to name the type, not to add a line here.
+# Tests and the demo builders are held to the baseline only.
+"tests/**" = ["E1", "E2", "E5", "I", "UP", "B", "SIM", "RUF", "ANN"]
+"examples/**" = ["E1", "E2", "E5", "I", "UP", "B", "SIM", "RUF", "ANN"]
+
+[tool.pyright]
+# src/ only: `python:ci-is-the-gate` type-checks the library, not the demos.
+include = ["src"]
+exclude = ["**/__pycache__"]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+log_cli = false
+log_level = "WARNING"