jsonl-utf8-guard 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Senanur Çetin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,174 @@
1
+ Metadata-Version: 2.4
2
+ Name: jsonl-utf8-guard
3
+ Version: 0.1.0
4
+ Summary: Dependency-free, privacy-safe UTF-8 JSONL validator that never prints input records
5
+ Author: Senanur Çetin
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/senanurcetin/offline-jsonl-workshop
8
+ Project-URL: Changelog, https://github.com/senanurcetin/offline-jsonl-workshop/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/senanurcetin/offline-jsonl-workshop/issues
10
+ Keywords: jsonl,utf-8,validation,privacy,offline
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Utilities
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ # Red → Green: UTF-8 JSONL Validation Workshop
27
+
28
+ A small original, dependency-free, offline Python example showing how Unicode characters differ from UTF-8 bytes. Intended as a potential hands-on Claude Code / open-source community workshop. **No workshop or attendance is claimed to have taken place.**
29
+
30
+ ## English
31
+
32
+ Requirements: Python 3.10+; no cloud, API keys, paid services, or extra packages.
33
+
34
+ Run from this directory:
35
+
36
+ ~~~powershell
37
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
38
+ py -3 -m unittest discover -p "test_*.py" -v
39
+ py -3 red_green_demo.py
40
+ ~~~
41
+
42
+ For a minimal reproducer, compare the character count of the rocket emoji (1) with its UTF-8 byte length (4). A limit expressed in bytes must check the latter. This verifier reads JSONL with a bounded buffer, validates UTF-8 strictly, **rejects ambiguous duplicate object keys (including nested and Unicode-escaped duplicates)**, and emits **only the number of JSON objects**. It does not print any input records.
43
+
44
+ The `red_green_demo.py` command automatically creates an intentionally buggy copy in a temporary directory, confirms that the targeted regression test fails there, and reruns the same test against the original corrected code. It verifies that the working source was never modified. You can also inspect the two implementations manually in a disposable copy.
45
+
46
+ Security and scope: No network requests, code execution of user JSON, original-content logging, input modification, or credentials. The example is educational, not a general production parser.
47
+
48
+ ## Türkçe
49
+
50
+ Gereksinimler: Python 3.10+; hesap, bulut, API anahtarı veya ek paket gerekmez.
51
+
52
+ ~~~powershell
53
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
54
+ py -3 -m unittest discover -p "test_*.py" -v
55
+ py -3 red_green_demo.py
56
+ ~~~
57
+
58
+ Temel problem: 🚀 emojisi 1 Unicode karakteri olmasına rağmen UTF-8 ile 4 bayt yer kaplar. Eğer bir akış işleyici boyut sınırını bayt cinsinden ilan ediyorsa karakter sayısını değil gerçek bayt sayısını kontrol etmelidir.
59
+
60
+ `red_green_demo.py` hatalı sürümü geçici bir dizinde oluşturur; regresyon testinin burada **beklenen şekilde başarısız** olduğunu ve orijinal, doğru kodda **başarılı** olduğunu otomatik doğrular. Kaynak dosyanın değiştirilmediğini de SHA-256 ile kontrol eder. Doğrulayıcı JSON nesnelerindeki **tekrarlanan anahtarları**, iç içe ve Unicode escape ile yazılmış olanlar dahil, reddeder; böylece son değerin sessizce öncekinin üzerine yazılması önlenir. Örnek yerel çalışır, dışarı veri göndermez ve dosya içeriğini veya hassas anahtar adlarını çıktıda paylaşmaz.
61
+
62
+ **Durum:** Atölye içeriği geliştirilmiştir. Gerçek etkinlik, katılımcı, sponsorluk veya program kabulü iddiası yoktur.
63
+
64
+
65
+ ## Public source and standalone offline package
66
+
67
+ This workshop is independently authored example material, **not** an official Anthropic product, partnership, certification, or an Anthropic-maintained repository. The source is provided under the MIT license in `LICENSE`. No workshop has been hosted.
68
+
69
+ The original development workspace contains a separate release builder (`prepare_workshop_release.py`) that packages this workshop reproducibly from an explicit allowlist. The builder is not required to use the extracted archive. The archive contains this README, bilingual runbook, sample, license, three scripts, three test modules, and a `SHA256SUMS` manifest. It excludes backups, credentials and local handoff files.
70
+
71
+ After extracting the ZIP into its own directory:
72
+
73
+ ~~~powershell
74
+ py -3 -m unittest discover -p "test_*.py" -q
75
+ py -3 verify_release.py
76
+ py -3 red_green_demo.py
77
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
78
+ ~~~
79
+
80
+ Rebuilding the package with the same source bytes produces the same ZIP hash. A SHA-256 sidecar is emitted beside the ZIP. Public repository: https://github.com/senanurcetin/offline-jsonl-workshop. The reusable offline ZIP can be built locally; it is not claimed as a published GitHub Release. Git checkouts preserve source bytes for the accompanying `SHA256SUMS` manifest via `.gitattributes`.
81
+
82
+ ### Public repository integrity check
83
+
84
+ After cloning the public repository, or extracting the offline ZIP, run `py -3 verify_release.py` in the project directory. This local, dependency-free command validates every expected file against `SHA256SUMS`. It rejects malformed, duplicate, unexpected or path-traversal manifest entries, detects changed or missing source files, and does not reveal source contents. Git's `.gitattributes` preserves the manifest-verified bytes on Windows, macOS and Linux.
85
+
86
+ ### Türkçe — Yayımlanan dosyaları doğrulama
87
+
88
+ GitHub deposunu klonladıktan veya ZIP paketini çıkardıktan sonra proje klasöründe `py -3 verify_release.py` komutunu çalıştır. Araç, beklenen tüm kaynak dosyalarını `SHA256SUMS` ile karşılaştırır; değiştirilmiş veya eksik dosyaları, hatalı veya yinelenmiş manifest kayıtlarını ve klasör dışına erişim girişimlerini reddeder. Ek paket veya ağ bağlantısı gerekmez; dosya içeriği ekrana yazdırılmaz.
89
+
90
+
91
+ ### Verify the ZIP without extracting it (English)
92
+
93
+ The verifier can inspect a local workshop ZIP **without extraction**:
94
+
95
+ ~~~powershell
96
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip"
97
+ ~~~
98
+
99
+ This checks the exact expected members, rejects duplicate, unsafe, symlinked, encrypted, oversized or missing ZIP entries, and verifies source bytes against the bundled SHA256SUMS. It performs no network requests and does not execute archive contents.
100
+
101
+ **Integrity is not authenticity:** An attacker who replaces both files *and* the included manifest could produce another self-consistent ZIP. To authenticate a download, also compare the full ZIP SHA-256 against a checksum obtained from a trusted independent channel. This repository does not claim a published ZIP release.
102
+
103
+ ### ZIP paketini çıkarmadan doğrula (Türkçe)
104
+
105
+ Bir ZIP dosyasının içeriğini klasöre açmadan kontrol etmek için:
106
+
107
+ ~~~powershell
108
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip"
109
+ ~~~
110
+
111
+ Bu işlem ZIP içindeki beklenen dosyaları ve SHA256SUMS değerlerini doğrular; yinelenen, eksik, güvensiz, sembolik bağlantılı ve aşırı büyük kayıtları reddeder. Ağ bağlantısı veya ZIP içindeki kodun çalıştırılması gerekmez.
112
+
113
+ **Bütünlük, kaynak kimliğini kanıtlamaz:** Dosyalarla birlikte manifest de değiştirilmişse sahte bir paket kendi içinde tutarlı görünebilir. Gerçek kaynağı doğrulamak için ZIP dosyasının SHA-256 değerini ayrıca güvenilir bir kanaldan alınan değerle karşılaştırın.
114
+
115
+
116
+ ### Independently trusted ZIP SHA-256 (English)
117
+
118
+ Checking the hash manifest inside a ZIP proves internal consistency, not
119
+ the identity of the publisher. For stronger verification, get the **complete
120
+ ZIP file's SHA-256** from a trusted independent channel, and pass that value
121
+ explicitly alongside the local ZIP path:
122
+
123
+ ~~~powershell
124
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip" --expected-archive-sha256 "<trusted_64_character_lowercase_sha256>"
125
+ ~~~
126
+
127
+ The tool verifies the **exact bytes it subsequently parses**, then validates
128
+ the internal allowlisted source checksums. It rejects malformed and mismatched
129
+ trusted hashes, requires the --archive flag, and does not use an internet connection.
130
+ A checksum supplied by the same untrusted download location does **not** by
131
+ itself prove publisher authenticity. No release signature or externally
132
+ trusted checksum distribution is claimed by this project.
133
+
134
+ ### Haricî güvenilir ZIP SHA-256 kontrolü (Türkçe)
135
+
136
+ ZIP içindeki SHA256SUMS dosyasının doğrulanması, paketin yalnızca kendi
137
+ içinde tutarlı olduğunu gösterir. Paketin tam SHA-256 değerini **bağımsız ve
138
+ güvenilir bir kaynaktan** elde ettiğinizde bunu ayrıca kullanabilirsiniz:
139
+
140
+ ~~~powershell
141
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip" --expected-archive-sha256 "<guvenilir_64_karakter_kucuk_harf_sha256>"
142
+ ~~~
143
+
144
+ Bu kontrol, arşivin tüm baytlarını güvenilir değerle karşılaştırır ve ardından
145
+ içerik manifestini doğrular. Hatalı hash biçimi veya uyuşmayan değer reddedilir.
146
+ İnternet, ücretli servis veya arşivi açıp içindeki kodu çalıştırmak gerekmez.
147
+ ZIP ve doğrulama değeri aynı güvenilmeyen kaynaktan alındıysa işlem tek başına
148
+ kaynağın özgünlüğünü kanıtlamaz.
149
+
150
+
151
+ ### Trusted SHA-256 sidecar file (English)
152
+
153
+ A local release builder may produce a `workshop.zip.sha256` file containing
154
+ the exact format `<64 lowercase hex digits> workshop.zip`. When the checksum
155
+ file comes from an **independently trusted channel**, verify the ZIP without
156
+ copying the hash manually:
157
+
158
+ ```powershell
159
+ py -3 verify_release.py --archive "offline-jsonl-workshop.zip" --trusted-sha256-file "offline-jsonl-workshop.zip.sha256"
160
+ ```
161
+
162
+ The reader accepts a single LF or CRLF-terminated record, verifies the ZIP
163
+ filename, rejects oversized or malformed checksum files and symlinks, and
164
+ uses the same bounded archive verification. This option cannot be combined
165
+ with `--expected-archive-sha256`. **A sidecar downloaded alongside an
166
+ untrusted ZIP does not independently authenticate its publisher.**
167
+
168
+ ### Güvenilir SHA-256 yan dosyası (Türkçe)
169
+
170
+ ZIP'in SHA-256 değerini içeren bir `.sha256` dosyasını **bağımsız ve güvenilir
171
+ bir kaynaktan** aldıysanız `--trusted-sha256-file` seçeneğiyle kullanabilirsiniz.
172
+ Araç, ZIP dosya adını ve SHA-256 biçimini denetler; Windows CRLF ve Linux LF
173
+ satır sonlarını destekler. ZIP ile aynı güvenilmeyen kaynaktan indirilen yan
174
+ dosya, tek başına yayıncının kimliğini kanıtlamaz.
@@ -0,0 +1,149 @@
1
+ # Red → Green: UTF-8 JSONL Validation Workshop
2
+
3
+ A small original, dependency-free, offline Python example showing how Unicode characters differ from UTF-8 bytes. Intended as a potential hands-on Claude Code / open-source community workshop. **No workshop or attendance is claimed to have taken place.**
4
+
5
+ ## English
6
+
7
+ Requirements: Python 3.10+; no cloud, API keys, paid services, or extra packages.
8
+
9
+ Run from this directory:
10
+
11
+ ~~~powershell
12
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
13
+ py -3 -m unittest discover -p "test_*.py" -v
14
+ py -3 red_green_demo.py
15
+ ~~~
16
+
17
+ For a minimal reproducer, compare the character count of the rocket emoji (1) with its UTF-8 byte length (4). A limit expressed in bytes must check the latter. This verifier reads JSONL with a bounded buffer, validates UTF-8 strictly, **rejects ambiguous duplicate object keys (including nested and Unicode-escaped duplicates)**, and emits **only the number of JSON objects**. It does not print any input records.
18
+
19
+ The `red_green_demo.py` command automatically creates an intentionally buggy copy in a temporary directory, confirms that the targeted regression test fails there, and reruns the same test against the original corrected code. It verifies that the working source was never modified. You can also inspect the two implementations manually in a disposable copy.
20
+
21
+ Security and scope: No network requests, code execution of user JSON, original-content logging, input modification, or credentials. The example is educational, not a general production parser.
22
+
23
+ ## Türkçe
24
+
25
+ Gereksinimler: Python 3.10+; hesap, bulut, API anahtarı veya ek paket gerekmez.
26
+
27
+ ~~~powershell
28
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
29
+ py -3 -m unittest discover -p "test_*.py" -v
30
+ py -3 red_green_demo.py
31
+ ~~~
32
+
33
+ Temel problem: 🚀 emojisi 1 Unicode karakteri olmasına rağmen UTF-8 ile 4 bayt yer kaplar. Eğer bir akış işleyici boyut sınırını bayt cinsinden ilan ediyorsa karakter sayısını değil gerçek bayt sayısını kontrol etmelidir.
34
+
35
+ `red_green_demo.py` hatalı sürümü geçici bir dizinde oluşturur; regresyon testinin burada **beklenen şekilde başarısız** olduğunu ve orijinal, doğru kodda **başarılı** olduğunu otomatik doğrular. Kaynak dosyanın değiştirilmediğini de SHA-256 ile kontrol eder. Doğrulayıcı JSON nesnelerindeki **tekrarlanan anahtarları**, iç içe ve Unicode escape ile yazılmış olanlar dahil, reddeder; böylece son değerin sessizce öncekinin üzerine yazılması önlenir. Örnek yerel çalışır, dışarı veri göndermez ve dosya içeriğini veya hassas anahtar adlarını çıktıda paylaşmaz.
36
+
37
+ **Durum:** Atölye içeriği geliştirilmiştir. Gerçek etkinlik, katılımcı, sponsorluk veya program kabulü iddiası yoktur.
38
+
39
+
40
+ ## Public source and standalone offline package
41
+
42
+ This workshop is independently authored example material, **not** an official Anthropic product, partnership, certification, or an Anthropic-maintained repository. The source is provided under the MIT license in `LICENSE`. No workshop has been hosted.
43
+
44
+ The original development workspace contains a separate release builder (`prepare_workshop_release.py`) that packages this workshop reproducibly from an explicit allowlist. The builder is not required to use the extracted archive. The archive contains this README, bilingual runbook, sample, license, three scripts, three test modules, and a `SHA256SUMS` manifest. It excludes backups, credentials and local handoff files.
45
+
46
+ After extracting the ZIP into its own directory:
47
+
48
+ ~~~powershell
49
+ py -3 -m unittest discover -p "test_*.py" -q
50
+ py -3 verify_release.py
51
+ py -3 red_green_demo.py
52
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
53
+ ~~~
54
+
55
+ Rebuilding the package with the same source bytes produces the same ZIP hash. A SHA-256 sidecar is emitted beside the ZIP. Public repository: https://github.com/senanurcetin/offline-jsonl-workshop. The reusable offline ZIP can be built locally; it is not claimed as a published GitHub Release. Git checkouts preserve source bytes for the accompanying `SHA256SUMS` manifest via `.gitattributes`.
56
+
57
+ ### Public repository integrity check
58
+
59
+ After cloning the public repository, or extracting the offline ZIP, run `py -3 verify_release.py` in the project directory. This local, dependency-free command validates every expected file against `SHA256SUMS`. It rejects malformed, duplicate, unexpected or path-traversal manifest entries, detects changed or missing source files, and does not reveal source contents. Git's `.gitattributes` preserves the manifest-verified bytes on Windows, macOS and Linux.
60
+
61
+ ### Türkçe — Yayımlanan dosyaları doğrulama
62
+
63
+ GitHub deposunu klonladıktan veya ZIP paketini çıkardıktan sonra proje klasöründe `py -3 verify_release.py` komutunu çalıştır. Araç, beklenen tüm kaynak dosyalarını `SHA256SUMS` ile karşılaştırır; değiştirilmiş veya eksik dosyaları, hatalı veya yinelenmiş manifest kayıtlarını ve klasör dışına erişim girişimlerini reddeder. Ek paket veya ağ bağlantısı gerekmez; dosya içeriği ekrana yazdırılmaz.
64
+
65
+
66
+ ### Verify the ZIP without extracting it (English)
67
+
68
+ The verifier can inspect a local workshop ZIP **without extraction**:
69
+
70
+ ~~~powershell
71
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip"
72
+ ~~~
73
+
74
+ This checks the exact expected members, rejects duplicate, unsafe, symlinked, encrypted, oversized or missing ZIP entries, and verifies source bytes against the bundled SHA256SUMS. It performs no network requests and does not execute archive contents.
75
+
76
+ **Integrity is not authenticity:** An attacker who replaces both files *and* the included manifest could produce another self-consistent ZIP. To authenticate a download, also compare the full ZIP SHA-256 against a checksum obtained from a trusted independent channel. This repository does not claim a published ZIP release.
77
+
78
+ ### ZIP paketini çıkarmadan doğrula (Türkçe)
79
+
80
+ Bir ZIP dosyasının içeriğini klasöre açmadan kontrol etmek için:
81
+
82
+ ~~~powershell
83
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip"
84
+ ~~~
85
+
86
+ Bu işlem ZIP içindeki beklenen dosyaları ve SHA256SUMS değerlerini doğrular; yinelenen, eksik, güvensiz, sembolik bağlantılı ve aşırı büyük kayıtları reddeder. Ağ bağlantısı veya ZIP içindeki kodun çalıştırılması gerekmez.
87
+
88
+ **Bütünlük, kaynak kimliğini kanıtlamaz:** Dosyalarla birlikte manifest de değiştirilmişse sahte bir paket kendi içinde tutarlı görünebilir. Gerçek kaynağı doğrulamak için ZIP dosyasının SHA-256 değerini ayrıca güvenilir bir kanaldan alınan değerle karşılaştırın.
89
+
90
+
91
+ ### Independently trusted ZIP SHA-256 (English)
92
+
93
+ Checking the hash manifest inside a ZIP proves internal consistency, not
94
+ the identity of the publisher. For stronger verification, get the **complete
95
+ ZIP file's SHA-256** from a trusted independent channel, and pass that value
96
+ explicitly alongside the local ZIP path:
97
+
98
+ ~~~powershell
99
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip" --expected-archive-sha256 "<trusted_64_character_lowercase_sha256>"
100
+ ~~~
101
+
102
+ The tool verifies the **exact bytes it subsequently parses**, then validates
103
+ the internal allowlisted source checksums. It rejects malformed and mismatched
104
+ trusted hashes, requires the --archive flag, and does not use an internet connection.
105
+ A checksum supplied by the same untrusted download location does **not** by
106
+ itself prove publisher authenticity. No release signature or externally
107
+ trusted checksum distribution is claimed by this project.
108
+
109
+ ### Haricî güvenilir ZIP SHA-256 kontrolü (Türkçe)
110
+
111
+ ZIP içindeki SHA256SUMS dosyasının doğrulanması, paketin yalnızca kendi
112
+ içinde tutarlı olduğunu gösterir. Paketin tam SHA-256 değerini **bağımsız ve
113
+ güvenilir bir kaynaktan** elde ettiğinizde bunu ayrıca kullanabilirsiniz:
114
+
115
+ ~~~powershell
116
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip" --expected-archive-sha256 "<guvenilir_64_karakter_kucuk_harf_sha256>"
117
+ ~~~
118
+
119
+ Bu kontrol, arşivin tüm baytlarını güvenilir değerle karşılaştırır ve ardından
120
+ içerik manifestini doğrular. Hatalı hash biçimi veya uyuşmayan değer reddedilir.
121
+ İnternet, ücretli servis veya arşivi açıp içindeki kodu çalıştırmak gerekmez.
122
+ ZIP ve doğrulama değeri aynı güvenilmeyen kaynaktan alındıysa işlem tek başına
123
+ kaynağın özgünlüğünü kanıtlamaz.
124
+
125
+
126
+ ### Trusted SHA-256 sidecar file (English)
127
+
128
+ A local release builder may produce a `workshop.zip.sha256` file containing
129
+ the exact format `<64 lowercase hex digits> workshop.zip`. When the checksum
130
+ file comes from an **independently trusted channel**, verify the ZIP without
131
+ copying the hash manually:
132
+
133
+ ```powershell
134
+ py -3 verify_release.py --archive "offline-jsonl-workshop.zip" --trusted-sha256-file "offline-jsonl-workshop.zip.sha256"
135
+ ```
136
+
137
+ The reader accepts a single LF or CRLF-terminated record, verifies the ZIP
138
+ filename, rejects oversized or malformed checksum files and symlinks, and
139
+ uses the same bounded archive verification. This option cannot be combined
140
+ with `--expected-archive-sha256`. **A sidecar downloaded alongside an
141
+ untrusted ZIP does not independently authenticate its publisher.**
142
+
143
+ ### Güvenilir SHA-256 yan dosyası (Türkçe)
144
+
145
+ ZIP'in SHA-256 değerini içeren bir `.sha256` dosyasını **bağımsız ve güvenilir
146
+ bir kaynaktan** aldıysanız `--trusted-sha256-file` seçeneğiyle kullanabilirsiniz.
147
+ Araç, ZIP dosya adını ve SHA-256 biçimini denetler; Windows CRLF ve Linux LF
148
+ satır sonlarını destekler. ZIP ile aynı güvenilmeyen kaynaktan indirilen yan
149
+ dosya, tek başına yayıncının kimliğini kanıtlamaz.
@@ -0,0 +1,174 @@
1
+ Metadata-Version: 2.4
2
+ Name: jsonl-utf8-guard
3
+ Version: 0.1.0
4
+ Summary: Dependency-free, privacy-safe UTF-8 JSONL validator that never prints input records
5
+ Author: Senanur Çetin
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/senanurcetin/offline-jsonl-workshop
8
+ Project-URL: Changelog, https://github.com/senanurcetin/offline-jsonl-workshop/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/senanurcetin/offline-jsonl-workshop/issues
10
+ Keywords: jsonl,utf-8,validation,privacy,offline
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Utilities
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ # Red → Green: UTF-8 JSONL Validation Workshop
27
+
28
+ A small original, dependency-free, offline Python example showing how Unicode characters differ from UTF-8 bytes. Intended as a potential hands-on Claude Code / open-source community workshop. **No workshop or attendance is claimed to have taken place.**
29
+
30
+ ## English
31
+
32
+ Requirements: Python 3.10+; no cloud, API keys, paid services, or extra packages.
33
+
34
+ Run from this directory:
35
+
36
+ ~~~powershell
37
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
38
+ py -3 -m unittest discover -p "test_*.py" -v
39
+ py -3 red_green_demo.py
40
+ ~~~
41
+
42
+ For a minimal reproducer, compare the character count of the rocket emoji (1) with its UTF-8 byte length (4). A limit expressed in bytes must check the latter. This verifier reads JSONL with a bounded buffer, validates UTF-8 strictly, **rejects ambiguous duplicate object keys (including nested and Unicode-escaped duplicates)**, and emits **only the number of JSON objects**. It does not print any input records.
43
+
44
+ The `red_green_demo.py` command automatically creates an intentionally buggy copy in a temporary directory, confirms that the targeted regression test fails there, and reruns the same test against the original corrected code. It verifies that the working source was never modified. You can also inspect the two implementations manually in a disposable copy.
45
+
46
+ Security and scope: No network requests, code execution of user JSON, original-content logging, input modification, or credentials. The example is educational, not a general production parser.
47
+
48
+ ## Türkçe
49
+
50
+ Gereksinimler: Python 3.10+; hesap, bulut, API anahtarı veya ek paket gerekmez.
51
+
52
+ ~~~powershell
53
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
54
+ py -3 -m unittest discover -p "test_*.py" -v
55
+ py -3 red_green_demo.py
56
+ ~~~
57
+
58
+ Temel problem: 🚀 emojisi 1 Unicode karakteri olmasına rağmen UTF-8 ile 4 bayt yer kaplar. Eğer bir akış işleyici boyut sınırını bayt cinsinden ilan ediyorsa karakter sayısını değil gerçek bayt sayısını kontrol etmelidir.
59
+
60
+ `red_green_demo.py` hatalı sürümü geçici bir dizinde oluşturur; regresyon testinin burada **beklenen şekilde başarısız** olduğunu ve orijinal, doğru kodda **başarılı** olduğunu otomatik doğrular. Kaynak dosyanın değiştirilmediğini de SHA-256 ile kontrol eder. Doğrulayıcı JSON nesnelerindeki **tekrarlanan anahtarları**, iç içe ve Unicode escape ile yazılmış olanlar dahil, reddeder; böylece son değerin sessizce öncekinin üzerine yazılması önlenir. Örnek yerel çalışır, dışarı veri göndermez ve dosya içeriğini veya hassas anahtar adlarını çıktıda paylaşmaz.
61
+
62
+ **Durum:** Atölye içeriği geliştirilmiştir. Gerçek etkinlik, katılımcı, sponsorluk veya program kabulü iddiası yoktur.
63
+
64
+
65
+ ## Public source and standalone offline package
66
+
67
+ This workshop is independently authored example material, **not** an official Anthropic product, partnership, certification, or an Anthropic-maintained repository. The source is provided under the MIT license in `LICENSE`. No workshop has been hosted.
68
+
69
+ The original development workspace contains a separate release builder (`prepare_workshop_release.py`) that packages this workshop reproducibly from an explicit allowlist. The builder is not required to use the extracted archive. The archive contains this README, bilingual runbook, sample, license, three scripts, three test modules, and a `SHA256SUMS` manifest. It excludes backups, credentials and local handoff files.
70
+
71
+ After extracting the ZIP into its own directory:
72
+
73
+ ~~~powershell
74
+ py -3 -m unittest discover -p "test_*.py" -q
75
+ py -3 verify_release.py
76
+ py -3 red_green_demo.py
77
+ py -3 jsonl_utf8_guard.py --input sample_events.jsonl
78
+ ~~~
79
+
80
+ Rebuilding the package with the same source bytes produces the same ZIP hash. A SHA-256 sidecar is emitted beside the ZIP. Public repository: https://github.com/senanurcetin/offline-jsonl-workshop. The reusable offline ZIP can be built locally; it is not claimed as a published GitHub Release. Git checkouts preserve source bytes for the accompanying `SHA256SUMS` manifest via `.gitattributes`.
81
+
82
+ ### Public repository integrity check
83
+
84
+ After cloning the public repository, or extracting the offline ZIP, run `py -3 verify_release.py` in the project directory. This local, dependency-free command validates every expected file against `SHA256SUMS`. It rejects malformed, duplicate, unexpected or path-traversal manifest entries, detects changed or missing source files, and does not reveal source contents. Git's `.gitattributes` preserves the manifest-verified bytes on Windows, macOS and Linux.
85
+
86
+ ### Türkçe — Yayımlanan dosyaları doğrulama
87
+
88
+ GitHub deposunu klonladıktan veya ZIP paketini çıkardıktan sonra proje klasöründe `py -3 verify_release.py` komutunu çalıştır. Araç, beklenen tüm kaynak dosyalarını `SHA256SUMS` ile karşılaştırır; değiştirilmiş veya eksik dosyaları, hatalı veya yinelenmiş manifest kayıtlarını ve klasör dışına erişim girişimlerini reddeder. Ek paket veya ağ bağlantısı gerekmez; dosya içeriği ekrana yazdırılmaz.
89
+
90
+
91
+ ### Verify the ZIP without extracting it (English)
92
+
93
+ The verifier can inspect a local workshop ZIP **without extraction**:
94
+
95
+ ~~~powershell
96
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip"
97
+ ~~~
98
+
99
+ This checks the exact expected members, rejects duplicate, unsafe, symlinked, encrypted, oversized or missing ZIP entries, and verifies source bytes against the bundled SHA256SUMS. It performs no network requests and does not execute archive contents.
100
+
101
+ **Integrity is not authenticity:** An attacker who replaces both files *and* the included manifest could produce another self-consistent ZIP. To authenticate a download, also compare the full ZIP SHA-256 against a checksum obtained from a trusted independent channel. This repository does not claim a published ZIP release.
102
+
103
+ ### ZIP paketini çıkarmadan doğrula (Türkçe)
104
+
105
+ Bir ZIP dosyasının içeriğini klasöre açmadan kontrol etmek için:
106
+
107
+ ~~~powershell
108
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip"
109
+ ~~~
110
+
111
+ Bu işlem ZIP içindeki beklenen dosyaları ve SHA256SUMS değerlerini doğrular; yinelenen, eksik, güvensiz, sembolik bağlantılı ve aşırı büyük kayıtları reddeder. Ağ bağlantısı veya ZIP içindeki kodun çalıştırılması gerekmez.
112
+
113
+ **Bütünlük, kaynak kimliğini kanıtlamaz:** Dosyalarla birlikte manifest de değiştirilmişse sahte bir paket kendi içinde tutarlı görünebilir. Gerçek kaynağı doğrulamak için ZIP dosyasının SHA-256 değerini ayrıca güvenilir bir kanaldan alınan değerle karşılaştırın.
114
+
115
+
116
+ ### Independently trusted ZIP SHA-256 (English)
117
+
118
+ Checking the hash manifest inside a ZIP proves internal consistency, not
119
+ the identity of the publisher. For stronger verification, get the **complete
120
+ ZIP file's SHA-256** from a trusted independent channel, and pass that value
121
+ explicitly alongside the local ZIP path:
122
+
123
+ ~~~powershell
124
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip" --expected-archive-sha256 "<trusted_64_character_lowercase_sha256>"
125
+ ~~~
126
+
127
+ The tool verifies the **exact bytes it subsequently parses**, then validates
128
+ the internal allowlisted source checksums. It rejects malformed and mismatched
129
+ trusted hashes, requires the --archive flag, and does not use an internet connection.
130
+ A checksum supplied by the same untrusted download location does **not** by
131
+ itself prove publisher authenticity. No release signature or externally
132
+ trusted checksum distribution is claimed by this project.
133
+
134
+ ### Haricî güvenilir ZIP SHA-256 kontrolü (Türkçe)
135
+
136
+ ZIP içindeki SHA256SUMS dosyasının doğrulanması, paketin yalnızca kendi
137
+ içinde tutarlı olduğunu gösterir. Paketin tam SHA-256 değerini **bağımsız ve
138
+ güvenilir bir kaynaktan** elde ettiğinizde bunu ayrıca kullanabilirsiniz:
139
+
140
+ ~~~powershell
141
+ py -3 verify_release.py --archive "path\to\offline-jsonl-workshop.zip" --expected-archive-sha256 "<guvenilir_64_karakter_kucuk_harf_sha256>"
142
+ ~~~
143
+
144
+ Bu kontrol, arşivin tüm baytlarını güvenilir değerle karşılaştırır ve ardından
145
+ içerik manifestini doğrular. Hatalı hash biçimi veya uyuşmayan değer reddedilir.
146
+ İnternet, ücretli servis veya arşivi açıp içindeki kodu çalıştırmak gerekmez.
147
+ ZIP ve doğrulama değeri aynı güvenilmeyen kaynaktan alındıysa işlem tek başına
148
+ kaynağın özgünlüğünü kanıtlamaz.
149
+
150
+
151
+ ### Trusted SHA-256 sidecar file (English)
152
+
153
+ A local release builder may produce a `workshop.zip.sha256` file containing
154
+ the exact format `<64 lowercase hex digits> workshop.zip`. When the checksum
155
+ file comes from an **independently trusted channel**, verify the ZIP without
156
+ copying the hash manually:
157
+
158
+ ```powershell
159
+ py -3 verify_release.py --archive "offline-jsonl-workshop.zip" --trusted-sha256-file "offline-jsonl-workshop.zip.sha256"
160
+ ```
161
+
162
+ The reader accepts a single LF or CRLF-terminated record, verifies the ZIP
163
+ filename, rejects oversized or malformed checksum files and symlinks, and
164
+ uses the same bounded archive verification. This option cannot be combined
165
+ with `--expected-archive-sha256`. **A sidecar downloaded alongside an
166
+ untrusted ZIP does not independently authenticate its publisher.**
167
+
168
+ ### Güvenilir SHA-256 yan dosyası (Türkçe)
169
+
170
+ ZIP'in SHA-256 değerini içeren bir `.sha256` dosyasını **bağımsız ve güvenilir
171
+ bir kaynaktan** aldıysanız `--trusted-sha256-file` seçeneğiyle kullanabilirsiniz.
172
+ Araç, ZIP dosya adını ve SHA-256 biçimini denetler; Windows CRLF ve Linux LF
173
+ satır sonlarını destekler. ZIP ile aynı güvenilmeyen kaynaktan indirilen yan
174
+ dosya, tek başına yayıncının kimliğini kanıtlamaz.
@@ -0,0 +1,9 @@
1
+ LICENSE
2
+ README.md
3
+ jsonl_utf8_guard.py
4
+ pyproject.toml
5
+ jsonl_utf8_guard.egg-info/PKG-INFO
6
+ jsonl_utf8_guard.egg-info/SOURCES.txt
7
+ jsonl_utf8_guard.egg-info/dependency_links.txt
8
+ jsonl_utf8_guard.egg-info/entry_points.txt
9
+ jsonl_utf8_guard.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ jsonl-utf8-guard = jsonl_utf8_guard:main
@@ -0,0 +1 @@
1
+ jsonl_utf8_guard
@@ -0,0 +1,112 @@
1
+ """Dependency-free JSONL verifier for an offline Claude Code workshop.
2
+
3
+ Measures raw UTF-8 bytes rather than the number of Unicode characters.
4
+ The command never prints or uploads input records.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import argparse
9
+ import json
10
+ import sys
11
+ from collections.abc import Iterator
12
+ from pathlib import Path
13
+ from typing import Any, BinaryIO
14
+
15
+ DEFAULT_MAX_BYTES = 65_536
16
+
17
+
18
+ class JSONLValidationError(ValueError):
19
+ """An invalid input record, identified by its physical line number."""
20
+
21
+
22
+ def _reject_json_constant(value: str) -> None:
23
+ raise ValueError("Non-finite JSON numbers are not supported")
24
+
25
+
26
+ def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
27
+ """Reject ambiguous JSON object members without echoing sensitive names."""
28
+ data: dict[str, Any] = {}
29
+ for key, value in pairs:
30
+ if key in data:
31
+ raise ValueError("Duplicate JSON object key")
32
+ data[key] = value
33
+ return data
34
+
35
+
36
+ def iter_jsonl_records(
37
+ source: BinaryIO, *, max_bytes: int = DEFAULT_MAX_BYTES
38
+ ) -> Iterator[dict[str, Any]]:
39
+ """Yield JSON objects while imposing a strict per-record byte limit.
40
+
41
+ Bounded readline(max_bytes + 3) allows a trailing CRLF; longer records
42
+ are rejected before their potentially sensitive content is parsed.
43
+ """
44
+ if not isinstance(max_bytes, int) or isinstance(max_bytes, bool) or max_bytes < 1:
45
+ raise ValueError("max_bytes must be a positive integer")
46
+
47
+ line_number = 0
48
+ while True:
49
+ raw = source.readline(max_bytes + 3)
50
+ if not raw:
51
+ return
52
+ line_number += 1
53
+ payload = raw[:-1] if raw.endswith(b"\n") else raw
54
+ if payload.endswith(b"\r"):
55
+ payload = payload[:-1]
56
+ if len(payload) > max_bytes:
57
+ raise JSONLValidationError(
58
+ f"Line {line_number}: exceeds {max_bytes} UTF-8 bytes"
59
+ )
60
+ if not payload.strip():
61
+ continue
62
+ try:
63
+ text = payload.decode("utf-8", errors="strict")
64
+ except UnicodeDecodeError as exc:
65
+ raise JSONLValidationError(
66
+ f"Line {line_number}: invalid UTF-8 encoding"
67
+ ) from exc
68
+ try:
69
+ data = json.loads(
70
+ text,
71
+ parse_constant=_reject_json_constant,
72
+ object_pairs_hook=_reject_duplicate_keys,
73
+ )
74
+ except RecursionError as exc:
75
+ raise JSONLValidationError(
76
+ f"Line {line_number}: JSON nesting is too deep"
77
+ ) from exc
78
+ except ValueError as exc:
79
+ raise JSONLValidationError(
80
+ f"Line {line_number}: invalid JSON"
81
+ ) from exc
82
+ if not isinstance(data, dict):
83
+ raise JSONLValidationError(
84
+ f"Line {line_number}: expected a JSON object"
85
+ )
86
+ yield data
87
+
88
+
89
+ def count_jsonl(source: BinaryIO, *, max_bytes: int = DEFAULT_MAX_BYTES) -> int:
90
+ return sum(1 for _ in iter_jsonl_records(source, max_bytes=max_bytes))
91
+
92
+
93
+ def main(argv: list[str] | None = None) -> int:
94
+ parser = argparse.ArgumentParser(description=__doc__)
95
+ parser.add_argument("--input", type=Path, help="Input file; omit for stdin")
96
+ parser.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES)
97
+ args = parser.parse_args(argv)
98
+ try:
99
+ if args.input is None:
100
+ count = count_jsonl(sys.stdin.buffer, max_bytes=args.max_bytes)
101
+ else:
102
+ with args.input.open("rb") as source:
103
+ count = count_jsonl(source, max_bytes=args.max_bytes)
104
+ except (OSError, ValueError) as exc:
105
+ print(f"Validation failed: {exc}", file=sys.stderr)
106
+ return 2
107
+ print(json.dumps({"status": "ok", "records": count, "max_bytes": args.max_bytes}))
108
+ return 0
109
+
110
+
111
+ if __name__ == "__main__":
112
+ raise SystemExit(main())
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "jsonl-utf8-guard"
7
+ version = "0.1.0"
8
+ description = "Dependency-free, privacy-safe UTF-8 JSONL validator that never prints input records"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Senanur Çetin" }]
14
+ keywords = ["jsonl", "utf-8", "validation", "privacy", "offline"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Environment :: Console",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: OS Independent",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3 :: Only",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Topic :: Utilities",
26
+ ]
27
+ dependencies = []
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/senanurcetin/offline-jsonl-workshop"
31
+ Changelog = "https://github.com/senanurcetin/offline-jsonl-workshop/blob/main/CHANGELOG.md"
32
+ Issues = "https://github.com/senanurcetin/offline-jsonl-workshop/issues"
33
+
34
+ [project.scripts]
35
+ jsonl-utf8-guard = "jsonl_utf8_guard:main"
36
+
37
+ [tool.setuptools]
38
+ py-modules = ["jsonl_utf8_guard"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+