cletter 0.2.1__tar.gz

cletter-0.2.1/.gitignore

@@ -0,0 +1,10 @@
+/target/
+node_modules/
+
+# Generated release outputs
+**/dist/
+**/LICENSES/
+!LICENSES/
+*.tgz
+__pycache__/
+*.egg-info/

cletter-0.2.1/LICENSES/Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cletter-0.2.1/LICENSES/MIT.txt

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

cletter-0.2.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: cletter
+Version: 0.2.1
+Summary: Locale-correct business correspondence: composes cgreet, cfarewell, cink and cdate
+Project-URL: Homepage, https://github.com/corbet-labs/cletter#readme
+Project-URL: Repository, https://github.com/corbet-labs/cletter
+Project-URL: Issues, https://github.com/corbet-labs/cletter/issues
+License-Expression: Apache-2.0
+License-File: LICENSES/Apache-2.0.txt
+License-File: LICENSES/MIT.txt
+Keywords: correspondence,i18n,locale
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: cdate<0.3,>=0.2.1
+Requires-Dist: cfarewell<0.3,>=0.2.1
+Requires-Dist: cgreet<0.3,>=0.2.1
+Requires-Dist: cink<0.2,>=0.1.4
+Description-Content-Type: text/markdown
+
+# cletter
+
+**Locale-correct correspondence, from salutation to closing.**
+
+[![crates.io](https://img.shields.io/crates/v/cletter.svg)](https://crates.io/crates/cletter) [![npm](https://img.shields.io/npm/v/@corbet-labs/cletter.svg)](https://www.npmjs.com/package/@corbet-labs/cletter) [![Rust API](https://docs.rs/cletter/badge.svg)](https://docs.rs/cletter)
+
+Compose a formal letter from deterministic rules: resolve a document locale, address a recipient, write an application subject, format the date, choose a closing, and prepare a handwritten signature image. Rust, JavaScript, and Python share the same conformance vectors.
+
+```js
+import { salutation } from '@corbet-labs/cletter';
+
+salutation('de-ch', 'Frau Dr. Müller');
+// Sehr geehrte Frau Dr. Müller
+```
+
+## Install
+
+| Environment | Command |
+| --- | --- |
+| Rust / Cargo | `cargo add cletter` |
+| Node.js / npm | `npm install @corbet-labs/cletter` |
+| pnpm | `pnpm add @corbet-labs/cletter` |
+| Yarn | `yarn add @corbet-labs/cletter` |
+| Bun | `bun add @corbet-labs/cletter` |
+| Deno | `deno add npm:@corbet-labs/cletter` |
+
+The 0.2.1 JavaScript distribution includes compiled ESM, CommonJS,
+TypeScript declarations, and a standalone browser module. Node.js 20+ is
+supported; no TypeScript loader is required.
+
+```js
+// CommonJS
+const { salutation } = require('@corbet-labs/cletter');
+```
+
+```html
+<script type="module">
+  import { salutation } from 'https://cdn.jsdelivr.net/npm/@corbet-labs/cletter@0.2.1/dist/browser.js';
+  console.log(salutation('de-ch', 'Frau Dr. Müller'));
+</script>
+```
+
+Python wheels, source distributions, and CLI instructions are in the
+[installation guide](https://github.com/corbet-labs/cletter/blob/main/docs/installation.md).
+JSR publication and Typst availability are listed there explicitly.
+
+## Rust
+
+```rust
+use cletter::{closing, long_date, resolve_locale, salutation};
+
+let locale = resolve_locale(Some("de"), Some("Zürich, Zug"));
+assert_eq!(salutation(&locale, "Frau Dr. Müller"), "Sehr geehrte Frau Dr. Müller");
+assert_eq!(closing(&locale, None), "Freundliche Grüsse");
+assert_eq!(long_date(&locale, 2026, 9, 7).as_deref(), Some("7. September 2026"));
+```
+
+## Python
+
+```python
+from cletter import salutation
+
+assert salutation("de-ch", "Frau Dr. Müller") == 'Sehr geehrte Frau Dr. Müller'
+```
+
+## API
+
+| JavaScript / Python or Rust | Purpose |
+| --- | --- |
+| `resolveLocale` / `resolve_locale` | Language and location → document locale |
+| `salutation`, `opening` | Recipient address or formal opening |
+| `subject` | Application subject with optional prefix override |
+| `closing` | Locale-specific valediction |
+| `longDate` / `long_date` and other date helpers | Gregorian datelines |
+| `applyOrtho` / `apply_ortho` | Explicit `ß` → `ss`, `ẞ` → `SS` for caller-selected `de-ch`/`de-li` prose |
+| `orthographyIssues` / `orthography_issues` | Non-mutating matched source/replacement pairs |
+| `orthographyReplacements` / `orthography_replacements` | Applicable spelling pairs from the shared table |
+| `normalize`, `signatureSize` / `signature_size` | Signature-image preparation |
+| `warnings` | Advisories for incomplete recipient details |
+
+Openings and closings have 40 locale entries. Date formatting currently covers German and English variants; other dates fall back to English. Locale IDs are lowercase in tables and outputs; lookups accept mixed case and explicit overrides win. Subject defaults are for job applications; supply a prefix override for other correspondence. The library produces letter components; your application owns the body, layout, and PDF rendering. Spelling transformations require caller-selected prose: preserve exact names, quotations, URLs and source material; use diagnostics when those boundaries are unavailable.
+
+The self-contained [Typst facade](https://github.com/corbet-labs/cletter/blob/main/typst/README.md) consumes the same greeting, closing and date helpers as the other ports.
+
+## Correspondence family
+
+| Library | Responsibility |
+| --- | --- |
+| [cletter](https://github.com/corbet-labs/cletter) | Compose the correspondence helpers |
+| [cgreet](https://github.com/corbet-labs/cgreet) | German salutations and titles |
+| [cfarewell](https://github.com/corbet-labs/cfarewell) | Locale-specific closings |
+| [cdate](https://github.com/corbet-labs/cdate) | Calendar-date formatting |
+| [cink](https://github.com/corbet-labs/cink) | Handwritten signature images |
+
+
+## Development
+
+Behavior is defined by [the locale tables](https://github.com/corbet-labs/cletter/tree/main/tables)
+and [shared conformance vectors](https://github.com/corbet-labs/cletter/tree/main/tests/vectors).
+Rust, JavaScript, and Python run the same vectors. Selected CI checks exercise
+installed JavaScript tarballs, Python wheels and command-line entrypoints, and
+Typst packages. Release validation records the actual runtime and platform;
+Linux results do not establish native Windows or macOS coverage.
+All five Rust crates forbid unsafe code in their own source.
+
+See [the release guide](https://github.com/corbet-labs/cletter/blob/main/docs/releasing.md)
+for generation, verification, and publication commands.
+
+## License
+
+Copyright 2026 Julian Y. Richard Corbet. Licensed under [Apache-2.0](LICENSES/Apache-2.0.txt). Vendored dependencies retain their notices; `typst/vendor/cgreet/` offers MIT OR Apache-2.0 and the other components use Apache-2.0.

cletter-0.2.1/README.md

@@ -0,0 +1,111 @@
+# cletter
+
+**Locale-correct correspondence, from salutation to closing.**
+
+[![crates.io](https://img.shields.io/crates/v/cletter.svg)](https://crates.io/crates/cletter) [![npm](https://img.shields.io/npm/v/@corbet-labs/cletter.svg)](https://www.npmjs.com/package/@corbet-labs/cletter) [![Rust API](https://docs.rs/cletter/badge.svg)](https://docs.rs/cletter)
+
+Compose a formal letter from deterministic rules: resolve a document locale, address a recipient, write an application subject, format the date, choose a closing, and prepare a handwritten signature image. Rust, JavaScript, and Python share the same conformance vectors.
+
+```js
+import { salutation } from '@corbet-labs/cletter';
+
+salutation('de-ch', 'Frau Dr. Müller');
+// Sehr geehrte Frau Dr. Müller
+```
+
+## Install
+
+| Environment | Command |
+| --- | --- |
+| Rust / Cargo | `cargo add cletter` |
+| Node.js / npm | `npm install @corbet-labs/cletter` |
+| pnpm | `pnpm add @corbet-labs/cletter` |
+| Yarn | `yarn add @corbet-labs/cletter` |
+| Bun | `bun add @corbet-labs/cletter` |
+| Deno | `deno add npm:@corbet-labs/cletter` |
+
+The 0.2.1 JavaScript distribution includes compiled ESM, CommonJS,
+TypeScript declarations, and a standalone browser module. Node.js 20+ is
+supported; no TypeScript loader is required.
+
+```js
+// CommonJS
+const { salutation } = require('@corbet-labs/cletter');
+```
+
+```html
+<script type="module">
+  import { salutation } from 'https://cdn.jsdelivr.net/npm/@corbet-labs/cletter@0.2.1/dist/browser.js';
+  console.log(salutation('de-ch', 'Frau Dr. Müller'));
+</script>
+```
+
+Python wheels, source distributions, and CLI instructions are in the
+[installation guide](https://github.com/corbet-labs/cletter/blob/main/docs/installation.md).
+JSR publication and Typst availability are listed there explicitly.
+
+## Rust
+
+```rust
+use cletter::{closing, long_date, resolve_locale, salutation};
+
+let locale = resolve_locale(Some("de"), Some("Zürich, Zug"));
+assert_eq!(salutation(&locale, "Frau Dr. Müller"), "Sehr geehrte Frau Dr. Müller");
+assert_eq!(closing(&locale, None), "Freundliche Grüsse");
+assert_eq!(long_date(&locale, 2026, 9, 7).as_deref(), Some("7. September 2026"));
+```
+
+## Python
+
+```python
+from cletter import salutation
+
+assert salutation("de-ch", "Frau Dr. Müller") == 'Sehr geehrte Frau Dr. Müller'
+```
+
+## API
+
+| JavaScript / Python or Rust | Purpose |
+| --- | --- |
+| `resolveLocale` / `resolve_locale` | Language and location → document locale |
+| `salutation`, `opening` | Recipient address or formal opening |
+| `subject` | Application subject with optional prefix override |
+| `closing` | Locale-specific valediction |
+| `longDate` / `long_date` and other date helpers | Gregorian datelines |
+| `applyOrtho` / `apply_ortho` | Explicit `ß` → `ss`, `ẞ` → `SS` for caller-selected `de-ch`/`de-li` prose |
+| `orthographyIssues` / `orthography_issues` | Non-mutating matched source/replacement pairs |
+| `orthographyReplacements` / `orthography_replacements` | Applicable spelling pairs from the shared table |
+| `normalize`, `signatureSize` / `signature_size` | Signature-image preparation |
+| `warnings` | Advisories for incomplete recipient details |
+
+Openings and closings have 40 locale entries. Date formatting currently covers German and English variants; other dates fall back to English. Locale IDs are lowercase in tables and outputs; lookups accept mixed case and explicit overrides win. Subject defaults are for job applications; supply a prefix override for other correspondence. The library produces letter components; your application owns the body, layout, and PDF rendering. Spelling transformations require caller-selected prose: preserve exact names, quotations, URLs and source material; use diagnostics when those boundaries are unavailable.
+
+The self-contained [Typst facade](https://github.com/corbet-labs/cletter/blob/main/typst/README.md) consumes the same greeting, closing and date helpers as the other ports.
+
+## Correspondence family
+
+| Library | Responsibility |
+| --- | --- |
+| [cletter](https://github.com/corbet-labs/cletter) | Compose the correspondence helpers |
+| [cgreet](https://github.com/corbet-labs/cgreet) | German salutations and titles |
+| [cfarewell](https://github.com/corbet-labs/cfarewell) | Locale-specific closings |
+| [cdate](https://github.com/corbet-labs/cdate) | Calendar-date formatting |
+| [cink](https://github.com/corbet-labs/cink) | Handwritten signature images |
+
+
+## Development
+
+Behavior is defined by [the locale tables](https://github.com/corbet-labs/cletter/tree/main/tables)
+and [shared conformance vectors](https://github.com/corbet-labs/cletter/tree/main/tests/vectors).
+Rust, JavaScript, and Python run the same vectors. Selected CI checks exercise
+installed JavaScript tarballs, Python wheels and command-line entrypoints, and
+Typst packages. Release validation records the actual runtime and platform;
+Linux results do not establish native Windows or macOS coverage.
+All five Rust crates forbid unsafe code in their own source.
+
+See [the release guide](https://github.com/corbet-labs/cletter/blob/main/docs/releasing.md)
+for generation, verification, and publication commands.
+
+## License
+
+Copyright 2026 Julian Y. Richard Corbet. Licensed under [Apache-2.0](LICENSES/Apache-2.0.txt). Vendored dependencies retain their notices; `typst/vendor/cgreet/` offers MIT OR Apache-2.0 and the other components use Apache-2.0.

cletter-0.2.1/cletter/__init__.py

@@ -0,0 +1,120 @@
+"""Locale-correct correspondence, composed from four focused libraries."""
+
+import re
+from cdate import is_valid_date, long_date, medium_date, month_year, short_date
+from cfarewell import available_locales, closing
+from cgreet import (Region, de_honorific_warning, de_salutation, parse_region,
+                    recipient_salutation_warning, region_uses_comma,
+                    salutation_honorific, salutation_last_name, salutation_surname,
+                    salutation_titles)
+from cink import (DecodedImage, default_max_pixels, exceeds_limits, image_snippet,
+                  normalize, scale_to_fit, signature_size, supported_formats)
+from ._tables import TABLES
+
+_LOCALES = TABLES["locales"]
+_COUNTRIES = TABLES["countries"]
+__all__ = ["normalize_language", "country_from_location", "resolve_locale", "region_for",
+           "opening", "subject", "salutation", "apply_ortho", "orthography_replacements", "orthography_issues", "warnings",
+           "is_valid_date", "long_date", "medium_date", "month_year", "short_date",
+           "available_locales", "closing", "de_honorific_warning", "de_salutation",
+           "parse_region", "recipient_salutation_warning", "region_uses_comma",
+           "salutation_honorific", "salutation_last_name", "salutation_surname",
+           "salutation_titles", "default_max_pixels", "exceeds_limits", "image_snippet",
+           "normalize", "scale_to_fit", "signature_size", "supported_formats"]
+
+
+def normalize_language(value: str) -> str | None:
+    """Normalize mixed case and underscores to a supported lowercase locale ID."""
+    lower = value.strip().replace("_", "-").lower()
+    if lower in _LOCALES["supported"]:
+        return lower
+    base = lower.split("-", 1)[0]
+    return base if base in _LOCALES["supported"] else None
+
+
+def country_from_location(location: str) -> str | None:
+    """Look up country keywords, then Swiss canton names in a location."""
+    text = location.lower().strip()
+    if not text:
+        return None
+    for keyword, code in _COUNTRIES["keywords"].items():
+        if keyword in text:
+            return code
+    for part in re.split("[,;]", text):
+        if part.strip() in _COUNTRIES["cantons"]:
+            return "CH"
+    return None
+
+
+def resolve_locale(language: str | None = None, location: str | None = None) -> str:
+    """Resolve language and an optional location into one document locale."""
+    normalized = normalize_language(language) if language is not None else None
+    normalized = normalized or "en"
+    base = normalized.split("-", 1)[0]
+    country = country_from_location(location) if location is not None else None
+    return normalized if country is None else _LOCALES["variants"].get(base, {}).get(country, base)
+
+
+def _entry(locale: str) -> dict:
+    lower = locale.lower()
+    key = lower if lower in _LOCALES["locales"] else lower.split("-", 1)[0]
+    if key not in _LOCALES["locales"]:
+        key = _LOCALES["fallback"]
+    return _LOCALES["locales"][key]
+
+
+def region_for(locale: str) -> Region | None:
+    """cgreet region for a German-language locale, otherwise None."""
+    return parse_region(_entry(locale).get("region", ""))
+
+
+def opening(locale: str, name: str | None = None, override_opening: str | None = None) -> str:
+    """Named opening or formal address; an explicit override always wins."""
+    if override_opening is not None:
+        return override_opening
+    entry = _entry(locale)
+    clean = name.strip() if name is not None else ""
+    return entry["named"].replace("{name}", clean) if clean else entry["formal"]
+
+
+def subject(locale: str, title: str | None = None, prefix_override: str | None = None) -> str:
+    """Subject prefix plus title, or the locale's unsolicited-application subject."""
+    entry = _entry(locale)
+    clean = title.strip() if title is not None else ""
+    prefix = entry["subject_prefix"] if prefix_override is None else prefix_override
+    return prefix + " " + clean if clean else entry["subject_unsolicited"]
+
+
+def salutation(locale: str, name: str) -> str:
+    """Use cgreet for German locales and the named opening elsewhere."""
+    region = region_for(locale)
+    return de_salutation(name, region) if region is not None else opening(locale, name)
+
+
+def orthography_replacements(locale: str) -> list[list[str]]:
+    """Return a copy of the locale's literal replacement pairs in table order."""
+    return [pair.copy() for pair in _LOCALES["orthography_replacements"]] if _entry(locale)["use_ss"] else []
+
+
+def orthography_issues(locale: str, text: str) -> list[list[str]]:
+    """Report applicable pairs once, without changing caller-selected prose."""
+    return [pair for pair in orthography_replacements(locale) if pair[0] in text]
+
+
+def apply_ortho(locale: str, text: str) -> str:
+    """Apply spelling substitutions to prose; callers exclude names/quotes/URLs/sources.
+
+    Opening, subject, closing and overrides are never transformed implicitly.
+    Use orthography_issues when a protected-content boundary is not available.
+    """
+    for source, replacement in orthography_replacements(locale):
+        text = text.replace(source, replacement)
+    return text
+
+
+def warnings(location: str, locale: str, name: str) -> list[str]:
+    """Nonblocking advisories for a recipient name."""
+    items = [recipient_salutation_warning(location, name)]
+    if region_for(locale) is not None:
+        items.append(de_honorific_warning(location, name))
+    return [item for item in items if item is not None]

cletter-0.2.1/cletter/__main__.py

@@ -0,0 +1,50 @@
+"""JSON command-line bridge for callers in any programming language."""
+import argparse
+import base64
+import dataclasses
+import json
+import sys
+import cletter as api
+
+
+def _json_default(value):
+    if dataclasses.is_dataclass(value):
+        return dataclasses.asdict(value)
+    if isinstance(value, bytes):
+        return base64.b64encode(value).decode("ascii")
+    raise TypeError(f"Cannot serialize {type(value).__name__}")
+
+
+def _reject_constant(value):
+    raise ValueError(f"{value} is not a JSON number")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Call cletter functions with JSON arguments.")
+    parser.add_argument("function", choices=api.__all__)
+    parser.add_argument("arguments", nargs="?", default="[]", help="JSON array of positional arguments or object of keyword arguments; '-' reads UTF-8 stdin")
+    args = parser.parse_args()
+    try:
+        values = json.loads(sys.stdin.buffer.read().decode("utf-8") if args.arguments == "-" else args.arguments, parse_constant=_reject_constant)
+        if not isinstance(values, (list, dict)):
+            raise ValueError("arguments must be a JSON array or object")
+        # Image operations accept the JSON object returned by normalize.
+        if args.function in ("exceeds_limits", "scale_to_fit", "signature_size"):
+            raw = values[0] if isinstance(values, list) else values["image"]
+            if isinstance(raw, dict):
+                raw = dict(raw)
+                raw["bytes"] = base64.b64decode(raw["bytes"], validate=True)
+                image = api.DecodedImage(**raw)
+                if isinstance(values, list):
+                    values[0] = image
+                else:
+                    values["image"] = image
+        fn = getattr(api, args.function)
+        result = fn(*values) if isinstance(values, list) else fn(**values)
+        print(json.dumps(result, default=_json_default, ensure_ascii=True, allow_nan=False))
+    except (ValueError, TypeError, KeyError, IndexError, AttributeError, OverflowError) as error:
+        parser.error(str(error))
+
+
+if __name__ == "__main__":
+    main()

cletter-0.2.1/cletter/_tables.py

@@ -0,0 +1,359 @@
+# Generated by scripts/sync-python.py; edit tables/*.json instead.
+TABLES = {'countries': {'keywords': {'switzerland': 'CH',
+                            'schweiz': 'CH',
+                            'suisse': 'CH',
+                            'svizzera': 'CH',
+                            'germany': 'DE',
+                            'deutschland': 'DE',
+                            'austria': 'AT',
+                            'österreich': 'AT',
+                            'oesterreich': 'AT',
+                            'united kingdom': 'GB',
+                            'uk': 'GB',
+                            'britain': 'GB',
+                            'england': 'GB',
+                            'united states': 'US',
+                            'usa': 'US',
+                            'france': 'FR',
+                            'frankreich': 'FR',
+                            'italy': 'IT',
+                            'italien': 'IT',
+                            'italia': 'IT',
+                            'brazil': 'BR',
+                            'brasil': 'BR',
+                            'brasilien': 'BR',
+                            'mexico': 'MX',
+                            'mexiko': 'MX',
+                            'méxico': 'MX',
+                            'netherlands': 'NL',
+                            'niederlande': 'NL',
+                            'belgium': 'BE',
+                            'belgien': 'BE',
+                            'belgique': 'BE',
+                            'australia': 'AU',
+                            'australien': 'AU',
+                            'portugal': 'PT',
+                            'spain': 'ES',
+                            'spanien': 'ES',
+                            'españa': 'ES',
+                            'liechtenstein': 'LI'},
+               'cantons': ['zürich',
+                           'zurich',
+                           'zh',
+                           'bern',
+                           'be',
+                           'luzern',
+                           'lucerne',
+                           'lu',
+                           'uri',
+                           'ur',
+                           'schwyz',
+                           'sz',
+                           'obwalden',
+                           'ow',
+                           'nidwalden',
+                           'nw',
+                           'glarus',
+                           'gl',
+                           'zug',
+                           'zg',
+                           'freiburg',
+                           'fribourg',
+                           'fr',
+                           'solothurn',
+                           'so',
+                           'basel-stadt',
+                           'bs',
+                           'basel-landschaft',
+                           'bl',
+                           'schaffhausen',
+                           'sh',
+                           'appenzell ausserrhoden',
+                           'ar',
+                           'appenzell innerrhoden',
+                           'ai',
+                           'st. gallen',
+                           'sg',
+                           'graubünden',
+                           'graubuenden',
+                           'gr',
+                           'aargau',
+                           'ag',
+                           'thurgau',
+                           'tg',
+                           'ticino',
+                           'ti',
+                           'vaud',
+                           'vd',
+                           'valais',
+                           'wallis',
+                           'vs',
+                           'neuchâtel',
+                           'neuchatel',
+                           'ne',
+                           'genève',
+                           'geneve',
+                           'geneva',
+                           'ge',
+                           'jura',
+                           'ju']},
+ 'locales': {'locales': {'de': {'formal': 'Sehr geehrte Damen und Herren,',
+                                'named': 'Sehr geehrte/r {name},',
+                                'subject_prefix': 'Bewerbung als',
+                                'subject_unsolicited': 'Initiativbewerbung',
+                                'use_ss': False,
+                                'region': 'de'},
+                         'de-ch': {'formal': 'Sehr geehrte Damen und Herren',
+                                   'named': 'Sehr geehrte/r {name}',
+                                   'subject_prefix': 'Bewerbung als',
+                                   'subject_unsolicited': 'Initiativbewerbung',
+                                   'use_ss': True,
+                                   'region': 'ch'},
+                         'de-li': {'formal': 'Sehr geehrte Damen und Herren',
+                                   'named': 'Sehr geehrte/r {name}',
+                                   'subject_prefix': 'Bewerbung als',
+                                   'subject_unsolicited': 'Initiativbewerbung',
+                                   'use_ss': True,
+                                   'region': 'li'},
+                         'de-at': {'formal': 'Sehr geehrte Damen und Herren,',
+                                   'named': 'Sehr geehrte/r {name},',
+                                   'subject_prefix': 'Bewerbung als',
+                                   'subject_unsolicited': 'Initiativbewerbung',
+                                   'use_ss': False,
+                                   'region': 'at'},
+                         'en': {'formal': 'Dear Sir or Madam,',
+                                'named': 'Dear {name},',
+                                'subject_prefix': 'Application for',
+                                'subject_unsolicited': 'Speculative Application',
+                                'use_ss': False},
+                         'en-gb': {'formal': 'Dear Sir or Madam,',
+                                   'named': 'Dear {name},',
+                                   'subject_prefix': 'Application for',
+                                   'subject_unsolicited': 'Speculative Application',
+                                   'use_ss': False},
+                         'en-us': {'formal': 'Dear Hiring Manager,',
+                                   'named': 'Dear {name},',
+                                   'subject_prefix': 'Application for',
+                                   'subject_unsolicited': 'Speculative Application',
+                                   'use_ss': False},
+                         'fr': {'formal': 'Madame, Monsieur,',
+                                'named': 'Cher/Chère {name},',
+                                'subject_prefix': 'Candidature au poste de',
+                                'subject_unsolicited': 'Candidature spontanée',
+                                'use_ss': False},
+                         'fr-ch': {'formal': 'Madame, Monsieur,',
+                                   'named': 'Cher/Chère {name},',
+                                   'subject_prefix': 'Candidature au poste de',
+                                   'subject_unsolicited': 'Candidature spontanée',
+                                   'use_ss': False},
+                         'it': {'formal': 'Gentile Signora, Egregio Signore,',
+                                'named': 'Gentile {name},',
+                                'subject_prefix': 'Candidatura per',
+                                'subject_unsolicited': 'Candidatura spontanea',
+                                'use_ss': False},
+                         'it-ch': {'formal': 'Gentile Signora, Egregio Signore,',
+                                   'named': 'Gentile {name},',
+                                   'subject_prefix': 'Candidatura per',
+                                   'subject_unsolicited': 'Candidatura spontanea',
+                                   'use_ss': False},
+                         'es': {'formal': 'Estimado/a Señor/a,',
+                                'named': 'Estimado/a {name},',
+                                'subject_prefix': 'Solicitud para el puesto de',
+                                'subject_unsolicited': 'Candidatura espontánea',
+                                'use_ss': False},
+                         'es-mx': {'formal': 'Estimado/a Señor/a,',
+                                   'named': 'Estimado/a {name},',
+                                   'subject_prefix': 'Solicitud para el puesto de',
+                                   'subject_unsolicited': 'Candidatura espontánea',
+                                   'use_ss': False},
+                         'pt': {'formal': 'Prezado(a) Senhor(a),',
+                                'named': 'Prezado(a) {name},',
+                                'subject_prefix': 'Candidatura para',
+                                'subject_unsolicited': 'Candidatura espontânea',
+                                'use_ss': False},
+                         'pt-br': {'formal': 'Prezado(a) Senhor(a),',
+                                   'named': 'Prezado(a) {name},',
+                                   'subject_prefix': 'Candidatura para',
+                                   'subject_unsolicited': 'Candidatura espontânea',
+                                   'use_ss': False},
+                         'nl': {'formal': 'Geachte heer, mevrouw,',
+                                'named': 'Geachte {name},',
+                                'subject_prefix': 'Sollicitatie voor',
+                                'subject_unsolicited': 'Open sollicitatie',
+                                'use_ss': False},
+                         'nl-be': {'formal': 'Geachte heer, mevrouw,',
+                                   'named': 'Geachte {name},',
+                                   'subject_prefix': 'Sollicitatie voor',
+                                   'subject_unsolicited': 'Open sollicitatie',
+                                   'use_ss': False},
+                         'ar': {'formal': 'السيدة/السيد المحترم/ة،',
+                                'named': '{name} المحترم/ة،',
+                                'subject_prefix': 'طلب توظيف لمنصب',
+                                'subject_unsolicited': 'طلب توظيف عام',
+                                'use_ss': False},
+                         'bg': {'formal': 'Уважаеми Дами и Господа,',
+                                'named': 'Уважаеми {name},',
+                                'subject_prefix': 'Кандидатура за',
+                                'subject_unsolicited': 'Инициативна кандидатура',
+                                'use_ss': False},
+                         'cs': {'formal': 'Vážená paní, Vážený pane,',
+                                'named': 'Vážený/á {name},',
+                                'subject_prefix': 'Žádost o pozici',
+                                'subject_unsolicited': 'Žádost z vlastní iniciativy',
+                                'use_ss': False},
+                         'da': {'formal': 'Kære ansættelsesudvalg,',
+                                'named': 'Kære {name},',
+                                'subject_prefix': 'Ansøgning til',
+                                'subject_unsolicited': 'Uopfordret ansøgning',
+                                'use_ss': False},
+                         'el': {'formal': 'Αξιότιμε Κύριε/Κυρία,',
+                                'named': 'Αξιότιμε/η {name},',
+                                'subject_prefix': 'Αίτηση για τη θέση',
+                                'subject_unsolicited': 'Αυθόρμητη αίτηση',
+                                'use_ss': False},
+                         'et': {'formal': 'Lugupeetud daamid ja härrad,',
+                                'named': 'Lugupeetud {name},',
+                                'subject_prefix': 'Kandideerimine positsioonile',
+                                'subject_unsolicited': 'Avaldus omal algatusel',
+                                'use_ss': False},
+                         'fi': {'formal': 'Hyvä vastaanottaja,',
+                                'named': 'Hyvä {name},',
+                                'subject_prefix': 'Hakemus tehtävään',
+                                'subject_unsolicited': 'Avoin hakemus',
+                                'use_ss': False},
+                         'hu': {'formal': 'Tisztelt Hölgyem/Uram!',
+                                'named': 'Tisztelt {name}!',
+                                'subject_prefix': 'Jelentkezés',
+                                'subject_unsolicited': 'Nyílt jelentkezés',
+                                'use_ss': False},
+                         'id': {'formal': 'Dengan hormat,',
+                                'named': 'Yth. {name},',
+                                'subject_prefix': 'Lamaran untuk posisi',
+                                'subject_unsolicited': 'Lamaran terbuka',
+                                'use_ss': False},
+                         'ja': {'formal': '拝啓',
+                                'named': '{name}様',
+                                'subject_prefix': '応募：',
+                                'subject_unsolicited': '自主応募',
+                                'use_ss': False},
+                         'ko': {'formal': '담당자님께,',
+                                'named': '{name}님께,',
+                                'subject_prefix': '지원:',
+                                'subject_unsolicited': '자발적 지원',
+                                'use_ss': False},
+                         'lt': {'formal': 'Gerbiamas (-a),',
+                                'named': 'Gerbiamas (-a) {name},',
+                                'subject_prefix': 'Paraiška pozicijai',
+                                'subject_unsolicited': 'Iniciatyvinė paraiška',
+                                'use_ss': False},
+                         'lv': {'formal': 'Cienījamais kungs/kundze,',
+                                'named': 'Cienījamais/ā {name},',
+                                'subject_prefix': 'Pieteikums uz vakanci',
+                                'subject_unsolicited': 'Iniciatīvas pieteikums',
+                                'use_ss': False},
+                         'nb': {'formal': 'Kjære mottaker,',
+                                'named': 'Kjære {name},',
+                                'subject_prefix': 'Søknad til stillingen som',
+                                'subject_unsolicited': 'Åpen søknad',
+                                'use_ss': False},
+                         'pl': {'formal': 'Szanowni Państwo,',
+                                'named': 'Szanowny/a {name},',
+                                'subject_prefix': 'Aplikacja na stanowisko',
+                                'subject_unsolicited': 'Aplikacja z własnej inicjatywy',
+                                'use_ss': False},
+                         'ro': {'formal': 'Stimată Doamnă/Stimate Domn,',
+                                'named': 'Stimate/ă {name},',
+                                'subject_prefix': 'Candidatură pentru',
+                                'subject_unsolicited': 'Candidatură spontană',
+                                'use_ss': False},
+                         'ru': {'formal': 'Уважаемые дамы и господа,',
+                                'named': 'Уважаемый/ая {name},',
+                                'subject_prefix': 'Заявка на должность',
+                                'subject_unsolicited': 'Инициативное заявление',
+                                'use_ss': False},
+                         'sk': {'formal': 'Vážená pani, Vážený pán,',
+                                'named': 'Vážený/á {name},',
+                                'subject_prefix': 'Žiadosť o pozíciu',
+                                'subject_unsolicited': 'Iniciatívna žiadosť',
+                                'use_ss': False},
+                         'sl': {'formal': 'Spoštovani,',
+                                'named': 'Spoštovani/a {name},',
+                                'subject_prefix': 'Prijava za delovno mesto',
+                                'subject_unsolicited': 'Odprta prijava',
+                                'use_ss': False},
+                         'sv': {'formal': 'Till den det berör,',
+                                'named': 'Bästa {name},',
+                                'subject_prefix': 'Ansökan till tjänsten som',
+                                'subject_unsolicited': 'Spontanansökan',
+                                'use_ss': False},
+                         'tr': {'formal': 'Sayın Yetkili,',
+                                'named': 'Sayın {name},',
+                                'subject_prefix': 'Başvuru:',
+                                'subject_unsolicited': 'Açık başvuru',
+                                'use_ss': False},
+                         'uk': {'formal': 'Шановні пані та панове,',
+                                'named': 'Шановний/а {name},',
+                                'subject_prefix': 'Заявка на посаду',
+                                'subject_unsolicited': 'Ініціативна заявка',
+                                'use_ss': False},
+                         'zh': {'formal': '尊敬的先生/女士：',
+                                'named': '尊敬的{name}：',
+                                'subject_prefix': '求职申请：',
+                                'subject_unsolicited': '自荐信',
+                                'use_ss': False}},
+             'supported': ['ar',
+                           'bg',
+                           'cs',
+                           'da',
+                           'de',
+                           'de-at',
+                           'de-ch',
+                           'de-de',
+                           'de-li',
+                           'el',
+                           'en',
+                           'en-au',
+                           'en-gb',
+                           'en-us',
+                           'es',
+                           'es-es',
+                           'es-mx',
+                           'et',
+                           'fi',
+                           'fr',
+                           'fr-ch',
+                           'fr-fr',
+                           'hu',
+                           'id',
+                           'it',
+                           'it-ch',
+                           'it-it',
+                           'ja',
+                           'ko',
+                           'lt',
+                           'lv',
+                           'nb',
+                           'nl',
+                           'nl-be',
+                           'nl-nl',
+                           'pl',
+                           'pt',
+                           'pt-br',
+                           'pt-pt',
+                           'ro',
+                           'ru',
+                           'sk',
+                           'sl',
+                           'sv',
+                           'tr',
+                           'uk',
+                           'zh'],
+             'fallback': 'en',
+             'variants': {'de': {'CH': 'de-ch', 'DE': 'de-de', 'AT': 'de-at', 'LI': 'de-li'},
+                          'fr': {'CH': 'fr-ch', 'FR': 'fr-fr'},
+                          'it': {'CH': 'it-ch', 'IT': 'it-it'},
+                          'en': {'GB': 'en-gb', 'US': 'en-us', 'AU': 'en-au'},
+                          'pt': {'BR': 'pt-br', 'PT': 'pt-pt'},
+                          'es': {'MX': 'es-mx', 'ES': 'es-es'},
+                          'nl': {'BE': 'nl-be', 'NL': 'nl-nl'}},
+             'orthography_replacements': [['ß', 'ss'], ['ẞ', 'SS']]}}

cletter-0.2.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cletter"
+version = "0.2.1"
+description = "Locale-correct business correspondence: composes cgreet, cfarewell, cink and cdate"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSES/*"]
+requires-python = ">=3.10"
+keywords = ["i18n", "correspondence", "locale"]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+
+dependencies = ["cgreet>=0.2.1,<0.3", "cfarewell>=0.2.1,<0.3", "cink>=0.1.4,<0.2", "cdate>=0.2.1,<0.3"]
+
+[project.urls]
+Homepage = "https://github.com/corbet-labs/cletter#readme"
+Repository = "https://github.com/corbet-labs/cletter"
+Issues = "https://github.com/corbet-labs/cletter/issues"
+
+[project.scripts]
+cletter = "cletter.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cletter"]

cletter-0.2.1/scripts/conformance.py

@@ -0,0 +1,58 @@
+"""Run canonical vectors against either the source port or an installed wheel."""
+import base64
+import importlib
+import json
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[2]
+if "--installed" not in sys.argv:
+    sys.path.insert(0, str(ROOT / "py"))
+api = importlib.import_module("cletter")
+
+ARGUMENTS = {
+    "region_parse": ["input"], "region_uses_comma": ["input"],
+    "salutation_last_name": ["input"], "salutation_honorific": ["input"],
+    "salutation_titles": ["input"], "salutation_surname": ["input"],
+    "de_salutation": ["input", "region"],
+    "recipient_salutation_warning": ["location", "input"],
+    "de_honorific_warning": ["location", "input"],
+    "closing": ["locale", "override"], "available_locales": [],
+    "long_date": ["locale", "year", "month", "day"],
+    "medium_date": ["locale", "year", "month", "day"],
+    "short_date": ["locale", "year", "month", "day"],
+    "month_year": ["locale", "year", "month"], "is_supported": ["locale"],
+    "supported_formats": [], "normalize": ["input"],
+    "exceeds_limits": ["image", "max_pixels"], "scale_to_fit": ["image", "max_pixels"],
+    "signature_size": ["image", "height_pt", "max_width_pt"],
+    "image_snippet": ["path", "height_pt", "width_pt"],
+    "resolve_locale": ["language", "location"],
+    "normalize_language": ["input"], "country_from_location": ["input"],
+    "orthography_replacements": ["locale"], "orthography_issues": ["locale", "text"],
+    "opening": ["locale", "person", "override"],
+    "subject": ["locale", "title", "prefix_override"],
+    "salutation": ["locale", "person"], "apply_ortho": ["locale", "text"],
+    "warnings": ["location", "locale", "person"],
+}
+
+files = sorted((ROOT / "tests/vectors").glob("*.json"))
+assert files, "No conformance vectors"
+count = 0
+for file in files:
+    for vector in json.loads(file.read_text(encoding="utf-8")):
+        name = vector["fn"]
+        values = dict(vector)
+        if "fixture" in vector:
+            values["input"] = base64.b64encode((ROOT / "tests/fixtures" / vector["fixture"]).read_bytes()).decode("ascii")
+            if name != "normalize":
+                values["image"] = api.normalize(values["input"])
+        fn = getattr(api, "parse_region" if name == "region_parse" else name)
+        actual = fn(*(values.get(key) for key in ARGUMENTS[name]))
+        if name == "normalize" and actual is not None:
+            actual = {key: getattr(actual, key) for key in ("mime", "width", "height")}
+        if isinstance(actual, tuple):
+            actual = list(actual)
+        if actual != vector["expected"]:
+            raise AssertionError(f"{file.name} :: {vector['name']}: {actual!r} != {vector['expected']!r}")
+        count += 1
+print(f"Python cletter: {count} vectors passed across {len(files)} files")

cletter-0.2.1/scripts/consumer.py

@@ -0,0 +1,106 @@
+"""Verify wheel/sdist contents and installed Python/console entrypoints.
+
+Run with the interpreter in a fresh environment containing the wheel and its
+declared dependencies. This script never adds the source package to sys.path.
+"""
+import argparse
+import base64
+from email.parser import BytesParser
+import importlib
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tarfile
+import tempfile
+import zipfile
+
+ROOT = Path(__file__).resolve().parents[2]
+PACKAGES = [path.name for path in (ROOT / "py").iterdir() if (path / "__init__.py").is_file()]
+if len(PACKAGES) != 1:
+    raise RuntimeError("Expected exactly one source package")
+NAME = PACKAGES[0]
+CASES = {
+    "cgreet": ("de_salutation", ["Frau Dr. Müller", "ch"],
+               {"name": "Frau Dr. Müller", "region": "ch"}, "Sehr geehrte Frau Dr. Müller"),
+    "cfarewell": ("closing", ["DE-LI"], {"locale": "DE-LI"}, "Freundliche Grüsse"),
+    "cdate": ("long_date", ["EN-GB", 2026, 9, 7],
+              {"locale": "EN-GB", "year": 2026, "month": 9, "day": 7}, "7 September 2026"),
+    "cink": ("image_snippet", ["signature.png", 20],
+             {"path": "signature.png", "height_pt": 20}, '#image("signature.png", height: 20pt)'),
+    "cletter": ("salutation", ["DE-LI", "Frau Dr. Müller"],
+                {"locale": "DE-LI", "name": "Frau Dr. Müller"}, "Sehr geehrte Frau Dr. Müller"),
+}
+
+
+def check(condition, message):
+    if not condition:
+        raise AssertionError(message)
+
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument("--wheel", type=Path, required=True)
+parser.add_argument("--sdist", type=Path, required=True)
+args = parser.parse_args()
+licenses = {path.name: path.read_bytes() for path in (ROOT / "LICENSES").iterdir() if path.is_file()}
+check(bool(licenses), "Source licenses are missing")
+with zipfile.ZipFile(args.wheel) as wheel:
+    files = wheel.namelist()
+    check(f"{NAME}/py.typed" in files, "Wheel is missing py.typed")
+    metadata_paths = [path for path in files if path.endswith(".dist-info/METADATA")]
+    check(len(metadata_paths) == 1, "Expected one wheel distribution")
+    metadata = BytesParser().parsebytes(wheel.read(metadata_paths[0]))
+    check(metadata["Name"] == NAME, "Wheel package name differs from repository")
+    check(metadata["License-Expression"] == "Apache-2.0", "Wheel must declare Apache-2.0")
+    check(not any("FSL" in path for path in files), "Wheel retains an obsolete license")
+    for name, expected in licenses.items():
+        check(any(path.endswith("/LICENSES/" + name) and wheel.read(path) == expected for path in files),
+              f"Wheel is missing the original {name}")
+with tarfile.open(args.sdist, "r:gz") as sdist:
+    files = {member.name: member for member in sdist.getmembers() if member.isfile()}
+    for name, expected in licenses.items():
+        check(any(path.endswith("/LICENSES/" + name) and sdist.extractfile(member).read() == expected
+                  for path, member in files.items()), f"Source distribution is missing {name}")
+
+distribution = importlib.metadata.distribution(NAME)
+check(distribution.version == metadata["Version"], "Installed version differs from wheel")
+check(any(entry.group == "console_scripts" and entry.name == NAME and entry.value == f"{NAME}.__main__:main"
+          for entry in distribution.entry_points), "Missing console entrypoint metadata")
+api = importlib.import_module(NAME)
+check(not Path(api.__file__).resolve().is_relative_to(ROOT / "py"), "Imported source tree instead of installed wheel")
+entrypoint = Path(sys.executable).parent / (NAME + (".exe" if os.name == "nt" else ""))
+check(entrypoint.is_file(), "Installer did not create the console entrypoint")
+function, positional, keywords, expected = CASES[NAME]
+
+with tempfile.TemporaryDirectory(prefix=f"{NAME}-python-consumer-") as cwd:
+    def call(command, function, values, *, stdin=False, valid=True):
+        payload = values if isinstance(values, str) else json.dumps(values, ensure_ascii=False)
+        result = subprocess.run(command + [function, "-" if stdin else payload],
+                                input=payload if stdin else None, cwd=cwd, text=True,
+                                encoding="utf-8", capture_output=True, timeout=30)
+        if valid:
+            check(result.returncode == 0, result.stderr)
+            return json.loads(result.stdout)
+        check(result.returncode == 2 and not result.stdout and "Traceback" not in result.stderr,
+              f"Invalid arguments did not produce a clean CLI error: {result}")
+
+    for command in ([sys.executable, "-m", NAME], [str(entrypoint)]):
+        check(call(command, function, positional) == expected, "Positional JSON invocation failed")
+        check(call(command, function, keywords, stdin=True) == expected, "Keyword/stdin invocation failed")
+        call(command, function, "null", valid=False)
+        call(command, function, "[NaN]", valid=False)
+        call(command, function, [], valid=False)
+    if NAME in ("cink", "cletter"):
+        encoded = base64.b64encode(b'<svg xmlns="http://www.w3.org/2000/svg"/>').decode("ascii")
+        decoded = call([str(entrypoint)], "normalize", [encoded])
+        check(decoded["bytes"] == encoded and decoded["mime"] == "svg", "Image JSON output lost encoded bytes")
+        check(call([str(entrypoint)], "signature_size", {"image": decoded, "height_pt": 20}) is None,
+              "Image JSON output cannot be used as a subsequent input")
+        raster = {"mime": "png", "width": 1, "height": 1, "bytes": ""}
+        check(call([str(entrypoint)], "signature_size", {"image": raster, "height_pt": 10**400}) is None,
+              "An unrepresentable height escaped the JSON bridge")
+        check(call([str(entrypoint)], "signature_size", {"image": raster, "height_pt": 20, "max_width_pt": 10**400}) is None,
+              "An unrepresentable maximum width escaped the JSON bridge")
+print(f"Python {NAME}: installed module, console JSON calls, wheel/sdist licenses and metadata passed")