sampledoc 0.1.0__py3-none-any.whl

sampledoc/__init__.py

@@ -0,0 +1,89 @@
+"""Small, localized, reproducible sample office documents.
+
+>>> import sampledoc
+>>> sampledoc.languages()
+('en', 'cs', 'de', ...)
+>>> data = sampledoc.document("text", "de")      # the German report, as .odt bytes
+>>> sampledoc.generate("out/", languages=["en"])  # every sample, written to disk
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from os import PathLike
+from pathlib import Path
+from typing import NamedTuple
+
+from . import _language, odf, ooxml, pdf, plain
+from ._language import languages, load
+from .names import file_names, manifest, query
+
+__all__ = [
+    "SAMPLES",
+    "Sample",
+    "document",
+    "file_name",
+    "file_names",
+    "generate",
+    "languages",
+    "manifest",
+    "query",
+]
+
+__version__ = "0.1.0"
+
+
+class Sample(NamedTuple):
+    extension: str
+    build: Callable[[dict], bytes]
+    description: str
+
+
+# Every kind of sample, by the name it is written under. The first three are the
+# documents the screenshots open; the rest fill the folder around them.
+SAMPLES: dict[str, Sample] = {
+    "text": Sample("odt", odf.odt, "a quarterly report with a table of costs"),
+    "sheet": Sample("ods", odf.ods, "a budget over two sheets"),
+    "slides": Sample("odp", odf.odp, "a three slide project plan"),
+    "word": Sample("docx", ooxml.docx, "a service agreement with an appendix"),
+    "cells": Sample("xlsx", ooxml.xlsx, "a small table of sales figures"),
+    "deck": Sample("pptx", ooxml.pptx, "a single titled, bulleted slide"),
+    "paper": Sample("pdf", pdf.pdf, "an invoice over two pages"),
+    "rows": Sample("csv", plain.csv, "a contact list"),
+    "notes": Sample("txt", plain.txt, "the report as plain text notes"),
+}
+
+
+def file_name(sample: str, language: str) -> str:
+    """The name a sample is written under, e.g. ``sample-text-de.odt``."""
+    return f"sample-{sample}-{language}.{SAMPLES[sample].extension}"
+
+
+def document(sample: str, language: str = "en") -> bytes:
+    """One sample, as the bytes of its file. The same arguments give the same bytes."""
+    if sample not in SAMPLES:
+        raise KeyError(f"no sample called {sample!r}; there are {', '.join(SAMPLES)}")
+
+    return SAMPLES[sample].build(load(language))
+
+
+def generate(
+    directory: str | PathLike,
+    languages: Iterable[str] | None = None,
+    samples: Iterable[str] | None = None,
+) -> list[Path]:
+    """Write samples into `directory`, creating it if need be.
+
+    Every sample in every language unless narrowed down. Returns the paths written.
+    """
+    target = Path(directory)
+    target.mkdir(parents=True, exist_ok=True)
+
+    written = []
+    for language in languages or _language.languages():
+        for sample in samples or SAMPLES:
+            path = target / file_name(sample, language)
+            path.write_bytes(document(sample, language))
+            written.append(path)
+
+    return written

sampledoc/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

sampledoc/_language.py

@@ -0,0 +1,37 @@
+"""The wording of the samples, one JSON file per language under `languages/`.
+
+Adding a language is adding a file: copy `en.json`, translate the strings, keep
+the keys. Nothing else in the package lists the languages.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+
+FALLBACK = "en"
+
+
+@cache
+def languages() -> tuple[str, ...]:
+    """Every language there is a file for, English first and the rest by code."""
+    found = sorted(
+        entry.name.removesuffix(".json")
+        for entry in resources.files(__package__).joinpath("languages").iterdir()
+        if entry.name.endswith(".json")
+    )
+    found.remove(FALLBACK)
+
+    return (FALLBACK, *found)
+
+
+@cache
+def load(language: str) -> dict:
+    """The wording for one language, as written in its file."""
+    if language not in languages():
+        raise KeyError(f"no samples written in {language!r}; there are {', '.join(languages())}")
+
+    text = resources.files(__package__).joinpath("languages", f"{language}.json").read_text("utf-8")
+
+    return json.loads(text)

sampledoc/_table.py

@@ -0,0 +1,109 @@
+"""The figures every sample that has a table takes its numbers from."""
+
+from __future__ import annotations
+
+import io
+import zipfile
+
+# 1980-01-01, what zip stores when it is given nothing: a rerun with the same
+# words has to produce the same bytes, or every run is a commit
+EPOCH = (1980, 1, 1, 0, 0, 0)
+
+# One accent, used for the report's headings and the slide titles, so the
+# documents read as one set.
+ACCENT = "#1c6fd6"
+RULE = "#d4d9e0"
+
+# What the sheets add up: forty rows over six periods, so there is enough of it
+# to look like a spreadsheet. The first twenty keep the first four figures they
+# had, because the invoice and the .xlsx take slices off the front.
+FIGURES = [
+    [1200, 1450, 1310, 1600, 1380, 1520],
+    [480, 620, 510, 470, 690, 540],
+    [3600, 900, 1200, 750, 830, 1150],
+    [820, 760, 930, 1010, 870, 940],
+    [540, 560, 580, 600, 610, 630],
+    [300, 450, 380, 520, 410, 470],
+    [1100, 1150, 1180, 1240, 1260, 1290],
+    [640, 640, 660, 680, 700, 700],
+    [420, 980, 350, 610, 1240, 380],
+    [260, 280, 270, 300, 290, 310],
+    [890, 910, 940, 980, 1000, 1030],
+    [1500, 400, 620, 350, 480, 390],
+    [340, 360, 350, 370, 380, 390],
+    [220, 220, 230, 230, 240, 240],
+    [180, 620, 210, 240, 190, 660],
+    [410, 430, 400, 450, 440, 460],
+    [760, 820, 690, 900, 850, 780],
+    [950, 480, 1100, 520, 560, 1180],
+    [280, 290, 300, 310, 320, 330],
+    [520, 540, 530, 560, 570, 590],
+    [1340, 1290, 1410, 1360, 1440, 1480],
+    [710, 730, 720, 750, 760, 780],
+    [190, 200, 190, 210, 200, 220],
+    [330, 330, 340, 340, 350, 350],
+    [860, 890, 1240, 910, 930, 960],
+    [240, 250, 260, 260, 270, 280],
+    [120, 130, 120, 140, 130, 150],
+    [460, 170, 180, 490, 180, 190],
+    [580, 610, 550, 640, 600, 670],
+    [150, 160, 170, 160, 180, 170],
+    [210, 230, 220, 250, 240, 260],
+    [390, 390, 400, 410, 410, 420],
+    [270, 1080, 310, 340, 290, 360],
+    [1620, 350, 380, 360, 400, 370],
+    [620, 650, 630, 680, 660, 700],
+    [110, 120, 110, 130, 120, 140],
+    [440, 450, 460, 470, 480, 490],
+    [980, 1020, 640, 1060, 1090, 720],
+    [560, 500, 590, 530, 610, 570],
+    [740, 770, 800, 790, 830, 860],
+]
+
+
+def table(words: dict, columns: int = 4, rows: int = 0, scale: int = 1) -> tuple:
+    """The figures as rows of cells: a header, the items across as many periods
+    as are asked for with their totals, and a totals row under them.
+
+    Narrowed and shortened for the files that are not the budget, so the .xlsx
+    and the invoice hold their own figures rather than the .ods twice.
+
+    As wide as the header a language has words for, so one translated ahead of
+    the others comes out short rather than out of step.
+    """
+    periods = words["periods"][:columns]
+    columns = len(periods)
+    taken = FIGURES[:rows] if rows else FIGURES
+    names = words["rows"][: len(taken)]
+
+    head = [words["item"]] + periods + [words["total"]]
+    body = [
+        [name] + [value * scale for value in figures[:columns]] + [sum(figures[:columns]) * scale]
+        for name, figures in zip(names, taken, strict=False)
+    ]
+    foot = (
+        [words["total"]]
+        + [sum(line[column + 1] for line in body) for column in range(len(periods))]
+        + [sum(line[-1] for line in body)]
+    )
+
+    return head, body, foot
+
+
+def zipped(parts: list[tuple[str, str, bool]]) -> bytes:
+    """A zip of (name, text, stored) parts in the order given, reproducibly.
+
+    Every entry carries the same date, permissions and creating system, so the
+    archive depends on nothing but its contents - not the clock, not the platform.
+    """
+    out = io.BytesIO()
+    with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as archive:
+        for name, text, stored in parts:
+            info = zipfile.ZipInfo(name, date_time=EPOCH)
+            info.external_attr = 0o644 << 16
+            # ZipInfo records the OS it was made on (0 on Windows, 3 elsewhere),
+            # and that byte would make the same samples differ by platform
+            info.create_system = 3
+            archive.writestr(info, text, compress_type=zipfile.ZIP_STORED if stored else zipfile.ZIP_DEFLATED)
+
+    return out.getvalue()

sampledoc/cli.py

@@ -0,0 +1,90 @@
+"""sampledoc [-o DIR] [-l LANG]... [-s SAMPLE]... [--locales FILE] [--no-names]"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from . import SAMPLES, __version__, file_name, generate, languages, manifest
+
+NAMES_FILE = "screenshot-names.json"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="sampledoc",
+        description="Write small, localized, reproducible sample office documents.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path("."),
+        metavar="DIR",
+        help="where to write the samples (default: the current directory)",
+    )
+    parser.add_argument(
+        "-l",
+        "--language",
+        action="append",
+        choices=languages(),
+        metavar="LANG",
+        help="only this language; repeatable (default: all of them)",
+    )
+    parser.add_argument(
+        "-s",
+        "--sample",
+        action="append",
+        choices=list(SAMPLES),
+        metavar="SAMPLE",
+        help="only this kind of sample; repeatable (default: all of them)",
+    )
+    parser.add_argument(
+        "--locales",
+        type=Path,
+        metavar="FILE",
+        help='a JSON object mapping device locales to languages, e.g. {"de-DE": "de"}, '
+        f'copied into {NAMES_FILE} under "locales"',
+    )
+    parser.add_argument(
+        "--no-names",
+        action="store_true",
+        help=f"do not write {NAMES_FILE}",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="list the languages and samples there are, and exit",
+    )
+    args = parser.parse_args(argv)
+
+    if args.list:
+        print("languages:", " ".join(languages()))
+        print("samples:")
+        for name, sample in SAMPLES.items():
+            print(f"  {name:<7} {file_name(name, 'LANG'):<22} {sample.description}")
+        return 0
+
+    locales = None
+    if args.locales:
+        locales = json.loads(args.locales.read_text(encoding="utf-8"))
+        if not isinstance(locales, dict):
+            parser.error(f"{args.locales} does not hold a JSON object")
+
+    written = generate(args.output, languages=args.language, samples=args.sample)
+
+    if not args.no_names:
+        try:
+            details = manifest(locales)
+        except ValueError as error:
+            parser.error(str(error))
+        (args.output / NAMES_FILE).write_text(
+            json.dumps(details, ensure_ascii=False, indent=1, sort_keys=True) + "\n", encoding="utf-8"
+        )
+
+    count = len(args.language or languages())
+    print(f"wrote {len(written)} documents in {count} languages to {args.output}")
+
+    return 0

sampledoc/languages/cs.json

@@ -0,0 +1,209 @@
+{
+  "language": "cs",
+  "report": {
+    "title": "Čtvrtletní zpráva",
+    "lead": "Tým splnil všechny cíle druhého čtvrtletí a nová verze vyšla včas.",
+    "sections": [
+      [
+        "Nejdůležitější",
+        [
+          "Náklady zůstaly pod rozpočtem a k projektu se připojili dva noví partneři.",
+          "Nová verze oslovila za první týden více lidí než ta předchozí za měsíc.",
+          "Podpora odpověděla na devět z deseti dotazů týž den."
+        ]
+      ],
+      [
+        "Náklady a rozpočet",
+        [
+          "Výdaje za software s novými licencemi vzrostly, cestovné opět kleslo.",
+          "Hardware byl jednou vyměněn a podpora zůstala po celé čtvrtletí stabilní.",
+          "Dva servery přešly k novému poskytovateli bez jediného dne výpadku."
+        ]
+      ],
+      [
+        "Příští čtvrtletí",
+        [
+          "Zářijová verze je poslední plánovaná letos.",
+          "V podpoře jsou volná dvě místa, v designu jedno.",
+          "Stěhování kanceláře je v listopadu a rozpočet na ně je schválený."
+        ]
+      ],
+      [
+        "Lidé",
+        [
+          "Na verzi pracovalo šest lidí, dva z nich jsou tu první rok.",
+          "Zástupy na dobu dovolených se domluvily v dubnu a vydržely celé léto.",
+          "Všichni absolvovali školení, které nová licence vyžaduje."
+        ]
+      ],
+      [
+        "Rizika",
+        [
+          "Listopadové stěhování je jediný termín, který nelze posunout.",
+          "Jeden dodavatel dosud nepodepsal nové podmínky a urgujeme ho.",
+          "Náklady na hosting v lednu vzrostou, pokud se smlouva neobnoví dříve."
+        ]
+      ]
+    ],
+    "closing": "Další schůzka je na konci července.",
+    "sheets": [
+      "Přehled",
+      "Náklady"
+    ],
+    "item": "Položka",
+    "total": "Celkem",
+    "periods": [
+      "Led",
+      "Úno",
+      "Bře",
+      "Dub",
+      "Kvě",
+      "Čvn"
+    ],
+    "rows": [
+      "Software",
+      "Cestovné",
+      "Hardware",
+      "Marketing",
+      "Podpora",
+      "Školení",
+      "Licence",
+      "Hosting",
+      "Akce",
+      "Kancelář",
+      "Cloud",
+      "Nábor",
+      "Právní služby",
+      "Pojištění",
+      "Občerstvení",
+      "Doprava",
+      "Reklama",
+      "Poradenství",
+      "Údržba",
+      "Energie",
+      "Vybavení",
+      "Předplatné",
+      "Telefonie",
+      "Internet",
+      "Bezpečnost",
+      "Zálohování",
+      "Domény",
+      "Certifikáty",
+      "Tisk",
+      "Papírnictví",
+      "Poštovné",
+      "Úklid",
+      "Opravy",
+      "Nábytek",
+      "Sklad",
+      "Bankovní poplatky",
+      "Členské příspěvky",
+      "Konference",
+      "Překlady",
+      "Design"
+    ],
+    "slides": [
+      [
+        "Plán projektu",
+        [
+          "Cíle čtvrtletí",
+          "Rozpočet a náklady",
+          "Další kroky"
+        ]
+      ],
+      [
+        "Harmonogram",
+        [
+          "Verze v červnu",
+          "Hodnocení v červenci",
+          "Plánování v srpnu"
+        ]
+      ],
+      [
+        "Tým",
+        [
+          "Dva noví partneři",
+          "Podpora ve třech jazycích",
+          "Školení na podzim"
+        ]
+      ]
+    ]
+  },
+  "contract": {
+    "title": "Smlouva o poskytování služeb",
+    "lead": "Tato smlouva se uzavírá mezi oběma níže uvedenými stranami.",
+    "clauses": [
+      "Dodavatel poskytuje software popsaný v příloze po dobu jednoho roku.",
+      "Platba je splatná do třiceti dnů od vystavení každé faktury.",
+      "Kterákoli strana může smlouvu ukončit s tříměsíční výpovědní lhůtou.",
+      "Změny této smlouvy jsou platné pouze písemně.",
+      "Dodavatel udržuje službu dostupnou v pracovní dny.",
+      "Obě strany zachovávají mlčenlivost o tom, co se o sobě dozvědí.",
+      "Řídí se rakouským právem; místně příslušný je soud ve Vídni.",
+      "Dodavatel uchovává zálohu dat zákazníka po dobu třiceti dnů.",
+      "Požadavky na podporu jsou zodpovězeny do jednoho pracovního dne.",
+      "Zákazník určí jednu osobu, která smí schvalovat změny.",
+      "Ceny platí první rok a každý podzim se přehodnocují.",
+      "Žádná strana nesmí smlouvu bez souhlasu postoupit třetí straně.",
+      "Příloha uvádí zahrnutý software a verzi, od které platí.",
+      "Tato smlouva nahrazuje všechna dřívější ujednání mezi stranami."
+    ]
+  },
+  "invoice": {
+    "number": "Faktura 2026-014",
+    "issued": "Vystaveno 12. června 2026",
+    "due": "Splatnost do 30 dnů",
+    "billed_to": "Odběratel",
+    "subtotal": "Mezisoučet",
+    "vat": "DPH 20 %",
+    "amount_due": "K úhradě",
+    "thanks": "Děkujeme za spolupráci.",
+    "quantity": "Množ.",
+    "unit_price": "Cena za ks"
+  },
+  "contacts": {
+    "headers": [
+      "Jméno a příjmení",
+      "Tým",
+      "E-mail",
+      "Telefon"
+    ],
+    "roles": [
+      "Design",
+      "Podpora",
+      "Prodej",
+      "Vývoj"
+    ]
+  },
+  "files": {
+    "text": "Čtvrtletní zpráva",
+    "sheet": "Rozpočet",
+    "slides": "Plán projektu",
+    "word": "Smlouva",
+    "cells": "Čísla prodejů",
+    "deck": "Setkání týmu",
+    "paper": "Faktura",
+    "rows": "Kontakty",
+    "notes": "Poznámky"
+  },
+  "fillers": {
+    "meeting": "Zápis z porady",
+    "letter": "Dopis pronajímateli",
+    "travel": "Plán cesty",
+    "reading": "Seznam ke čtení",
+    "household": "Rodinný rozpočet",
+    "hours": "Odpracované hodiny",
+    "stocktake": "Inventura",
+    "kickoff": "Zahájení projektu",
+    "course": "Slidy ke kurzu",
+    "lease": "Nájemní smlouva",
+    "resume": "Životopis",
+    "application": "Přihláška",
+    "expenses": "Výdaje",
+    "inventory": "Zásoby",
+    "review": "Čtvrtletní hodnocení",
+    "ticket": "Jízdenka",
+    "warranty": "Záruka",
+    "manual": "Návod"
+  }
+}