callhash 1.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.
callhash-1.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HamSCI / Michael Hauan AC0G / Rob Robinett AI6VN
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,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: callhash
3
+ Version: 1.1.0
4
+ Summary: WSJT-X callsign-hash mechanism (Bob Jenkins lookup3, seed 146) plus a per-station accumulator that resolves hashes from <call> announcement markers in decoded jt9 / wsprd output.
5
+ Author: Rob Robinett AI6VN
6
+ Author-email: Michael Hauan AC0G <ac0g@hauan.org>
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://github.com/HamSCI/callhash
9
+ Project-URL: Bug Tracker, https://github.com/HamSCI/callhash/issues
10
+ Keywords: wsjt-x,ham radio,ft8,ft4,wspr,callsign,hash
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Provides-Extra: dev
15
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
16
+ Dynamic: license-file
17
+
18
+ # callhash
19
+
20
+ Pure-Python WSJT-X compound-callsign hash resolution.
21
+
22
+ WSJT-X's FT4/FT8/WSPR packet formats compress compound callsigns
23
+ (e.g. `K1ABC/QRP`, `VE3/K1ABC`) into 22-bit (FT8/FT4) or 15-bit
24
+ (WSPR Type 3) hashes. Receivers maintain a session table that maps
25
+ the hash back to plaintext when the call has been observed in a
26
+ `<call>` first-occurrence message. Both `jt9` and `wsprd` use the
27
+ same hash function — Bob Jenkins lookup3, seed 146.
28
+
29
+ When a per-slot decoder invocation starts with an empty session
30
+ table (the typical case for `psk-recorder`, `meteor-scatter`,
31
+ `wspr-recorder`, or any consumer that drives the decoder one cycle
32
+ at a time), most hashed packets surface as the literal `<...>`
33
+ placeholder — or, when the decoder is told to emit the number
34
+ (`jt9 -Y`, the patched `decode_ft8`), as `<NNNNNNN>`. This library
35
+ reconstructs the table on the consumer side from the same
36
+ announcement markers WSJT-X uses, and substitutes the numeric
37
+ hashes back to plaintext.
38
+
39
+ All three HamSCI recorders use this one library for build
40
+ (`observe`), lookup (`by_hashNN`), and substitution
41
+ (`resolve_token` / `resolve_message` / `parse_message`) — the same
42
+ mechanism everywhere, so a compound call learned on one mode/band
43
+ resolves hashes on another. Every mode hashes with the identical
44
+ `nhash`; only the width differs (22-bit FT8/FT4/MSK144/FST4W,
45
+ 15-bit WSPR-2), and the table keys each width separately.
46
+
47
+ ## Install
48
+
49
+ ```
50
+ pip install callhash
51
+ ```
52
+
53
+ Or from a sibling checkout (HamSCI deployment pattern):
54
+
55
+ ```
56
+ pip install -e /opt/git/sigmond/callhash
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ ```python
62
+ from callhash import CallHashTable, hash22, hash15, nhash
63
+
64
+ # Persistent per-station cache.
65
+ table = CallHashTable.load_or_new("/var/lib/myclient/callhash.json")
66
+
67
+ # Feed any text containing <call> markers; the table extracts them.
68
+ table.observe("260507 1234 -12 +0.45 1250 ` <K1ABC/QRP> CQ FT8")
69
+
70
+ # Look a hash up if you happen to have one.
71
+ table.by_hash22(hash22("K1ABC/QRP")) # → "K1ABC/QRP"
72
+ table.by_hash15(hash15("K1ABC/QRP")) # → "K1ABC/QRP"
73
+
74
+ # Resolve a decoded message: substitutes <NNNNNNN>/<CALL>, drops <...>.
75
+ table.resolve_message("AC0G <2288505> R-12") # → "AC0G K9AN R-12" (if learned)
76
+
77
+ # Or parse a whole message into call fields, resolving hashes via the table.
78
+ from callhash import parse_message
79
+ parse_message("AC0G <2288505> R-12", table=table)
80
+ # → {"message": "AC0G K9AN R-12", "rx_call": "AC0G", "tx_call": "K9AN",
81
+ # "grid": "", "report": -12}
82
+
83
+ # Persist for the next invocation.
84
+ table.save()
85
+ ```
86
+
87
+ ## Public API
88
+
89
+ | Symbol | Purpose |
90
+ | --------------------- | ---------------------------------------------------------------------- |
91
+ | `nhash(key, initval)` | Bob Jenkins lookup3 32-bit hash. `initval=146` matches WSJT-X. |
92
+ | `hash22(call)` | Convenience: `nhash(call) & 0x3FFFFF` (FT8/FT4 compound-call width). |
93
+ | `hash15(call)` | Convenience: `nhash(call) & 0x7FFF` (WSPR Type 3 width). |
94
+ | `hash12(call)` | Convenience: 12-bit mask (some ARRL contest variants). |
95
+ | `hash10(call)` | Convenience: 10-bit mask (narrowest WSJT-X variant). |
96
+ | `CallHashTable` | Persistent accumulator + lookup + substitution + collision guard. |
97
+ | `parse_message(msg, table=None)` | Shared WSJT-X message-field parser (tx/rx/grid/report) + hash substitution. |
98
+
99
+ `CallHashTable` resolves with `resolve_token` / `resolve_message`,
100
+ seeds decoders with `write_wsprd_hashtable` / `write_jt9_calls`
101
+ (both take an `exclude=` predicate), and **guards collisions**: a
102
+ hash slot claimed by two distinct calls is ambiguous, so
103
+ `by_hashNN` returns `None` rather than a guessed (wrong) call. This
104
+ matters because a persistent table accumulates far more calls than
105
+ WSJT-X's per-session table, so collisions — especially in the
106
+ 15-bit space — are common.
107
+
108
+ ## Correctness
109
+
110
+ `nhash` is bit-exact against WSJT-X's canonical
111
+ `lib/wsprcode/nhash.c` (the unmasked variant — note that
112
+ `lib/wsprd/nhash.c` has a 15-bit mask baked into its return). 23
113
+ reference vectors verified, including 11/12/13-byte boundary cases
114
+ that exercise distinct final-block branches in the C code.
115
+
116
+ The `CallHashTable` covers `<call>` announcement extraction,
117
+ hash lookups, token/message substitution, the collision guard,
118
+ atomic JSON persistence (write-tempfile + rename), corrupt-JSON /
119
+ schema-mismatch recovery, and concurrent-observe / concurrent-lookup
120
+ safety. 89 tests total; no live ClickHouse / WSJT-X server required
121
+ to run them.
122
+
123
+ ## Why this lives in its own repo
124
+
125
+ The hash function and bracket-resolution logic are WSJT-X's, not
126
+ sigmond's. They're useful for any FT8/FT4/WSPR consumer — the
127
+ sigmond client suite is the primary user today, but a future
128
+ `hs-uploader` library or any independent log analyser will
129
+ benefit equally. Pure stdlib, no runtime deps, ~200 lines of
130
+ code; small enough to live cleanly on its own.
131
+
132
+ ## License
133
+
134
+ MIT.
@@ -0,0 +1,117 @@
1
+ # callhash
2
+
3
+ Pure-Python WSJT-X compound-callsign hash resolution.
4
+
5
+ WSJT-X's FT4/FT8/WSPR packet formats compress compound callsigns
6
+ (e.g. `K1ABC/QRP`, `VE3/K1ABC`) into 22-bit (FT8/FT4) or 15-bit
7
+ (WSPR Type 3) hashes. Receivers maintain a session table that maps
8
+ the hash back to plaintext when the call has been observed in a
9
+ `<call>` first-occurrence message. Both `jt9` and `wsprd` use the
10
+ same hash function — Bob Jenkins lookup3, seed 146.
11
+
12
+ When a per-slot decoder invocation starts with an empty session
13
+ table (the typical case for `psk-recorder`, `meteor-scatter`,
14
+ `wspr-recorder`, or any consumer that drives the decoder one cycle
15
+ at a time), most hashed packets surface as the literal `<...>`
16
+ placeholder — or, when the decoder is told to emit the number
17
+ (`jt9 -Y`, the patched `decode_ft8`), as `<NNNNNNN>`. This library
18
+ reconstructs the table on the consumer side from the same
19
+ announcement markers WSJT-X uses, and substitutes the numeric
20
+ hashes back to plaintext.
21
+
22
+ All three HamSCI recorders use this one library for build
23
+ (`observe`), lookup (`by_hashNN`), and substitution
24
+ (`resolve_token` / `resolve_message` / `parse_message`) — the same
25
+ mechanism everywhere, so a compound call learned on one mode/band
26
+ resolves hashes on another. Every mode hashes with the identical
27
+ `nhash`; only the width differs (22-bit FT8/FT4/MSK144/FST4W,
28
+ 15-bit WSPR-2), and the table keys each width separately.
29
+
30
+ ## Install
31
+
32
+ ```
33
+ pip install callhash
34
+ ```
35
+
36
+ Or from a sibling checkout (HamSCI deployment pattern):
37
+
38
+ ```
39
+ pip install -e /opt/git/sigmond/callhash
40
+ ```
41
+
42
+ ## Usage
43
+
44
+ ```python
45
+ from callhash import CallHashTable, hash22, hash15, nhash
46
+
47
+ # Persistent per-station cache.
48
+ table = CallHashTable.load_or_new("/var/lib/myclient/callhash.json")
49
+
50
+ # Feed any text containing <call> markers; the table extracts them.
51
+ table.observe("260507 1234 -12 +0.45 1250 ` <K1ABC/QRP> CQ FT8")
52
+
53
+ # Look a hash up if you happen to have one.
54
+ table.by_hash22(hash22("K1ABC/QRP")) # → "K1ABC/QRP"
55
+ table.by_hash15(hash15("K1ABC/QRP")) # → "K1ABC/QRP"
56
+
57
+ # Resolve a decoded message: substitutes <NNNNNNN>/<CALL>, drops <...>.
58
+ table.resolve_message("AC0G <2288505> R-12") # → "AC0G K9AN R-12" (if learned)
59
+
60
+ # Or parse a whole message into call fields, resolving hashes via the table.
61
+ from callhash import parse_message
62
+ parse_message("AC0G <2288505> R-12", table=table)
63
+ # → {"message": "AC0G K9AN R-12", "rx_call": "AC0G", "tx_call": "K9AN",
64
+ # "grid": "", "report": -12}
65
+
66
+ # Persist for the next invocation.
67
+ table.save()
68
+ ```
69
+
70
+ ## Public API
71
+
72
+ | Symbol | Purpose |
73
+ | --------------------- | ---------------------------------------------------------------------- |
74
+ | `nhash(key, initval)` | Bob Jenkins lookup3 32-bit hash. `initval=146` matches WSJT-X. |
75
+ | `hash22(call)` | Convenience: `nhash(call) & 0x3FFFFF` (FT8/FT4 compound-call width). |
76
+ | `hash15(call)` | Convenience: `nhash(call) & 0x7FFF` (WSPR Type 3 width). |
77
+ | `hash12(call)` | Convenience: 12-bit mask (some ARRL contest variants). |
78
+ | `hash10(call)` | Convenience: 10-bit mask (narrowest WSJT-X variant). |
79
+ | `CallHashTable` | Persistent accumulator + lookup + substitution + collision guard. |
80
+ | `parse_message(msg, table=None)` | Shared WSJT-X message-field parser (tx/rx/grid/report) + hash substitution. |
81
+
82
+ `CallHashTable` resolves with `resolve_token` / `resolve_message`,
83
+ seeds decoders with `write_wsprd_hashtable` / `write_jt9_calls`
84
+ (both take an `exclude=` predicate), and **guards collisions**: a
85
+ hash slot claimed by two distinct calls is ambiguous, so
86
+ `by_hashNN` returns `None` rather than a guessed (wrong) call. This
87
+ matters because a persistent table accumulates far more calls than
88
+ WSJT-X's per-session table, so collisions — especially in the
89
+ 15-bit space — are common.
90
+
91
+ ## Correctness
92
+
93
+ `nhash` is bit-exact against WSJT-X's canonical
94
+ `lib/wsprcode/nhash.c` (the unmasked variant — note that
95
+ `lib/wsprd/nhash.c` has a 15-bit mask baked into its return). 23
96
+ reference vectors verified, including 11/12/13-byte boundary cases
97
+ that exercise distinct final-block branches in the C code.
98
+
99
+ The `CallHashTable` covers `<call>` announcement extraction,
100
+ hash lookups, token/message substitution, the collision guard,
101
+ atomic JSON persistence (write-tempfile + rename), corrupt-JSON /
102
+ schema-mismatch recovery, and concurrent-observe / concurrent-lookup
103
+ safety. 89 tests total; no live ClickHouse / WSJT-X server required
104
+ to run them.
105
+
106
+ ## Why this lives in its own repo
107
+
108
+ The hash function and bracket-resolution logic are WSJT-X's, not
109
+ sigmond's. They're useful for any FT8/FT4/WSPR consumer — the
110
+ sigmond client suite is the primary user today, but a future
111
+ `hs-uploader` library or any independent log analyser will
112
+ benefit equally. Pure stdlib, no runtime deps, ~200 lines of
113
+ code; small enough to live cleanly on its own.
114
+
115
+ ## License
116
+
117
+ MIT.
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "callhash"
7
+ version = "1.1.0"
8
+ description = "WSJT-X callsign-hash mechanism (Bob Jenkins lookup3, seed 146) plus a per-station accumulator that resolves hashes from <call> announcement markers in decoded jt9 / wsprd output."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [
12
+ { name = "Michael Hauan AC0G", email = "ac0g@hauan.org" },
13
+ { name = "Rob Robinett AI6VN" },
14
+ ]
15
+ requires-python = ">=3.10"
16
+ keywords = ["wsjt-x", "ham radio", "ft8", "ft4", "wspr", "callsign", "hash"]
17
+ # Pure stdlib — no runtime deps.
18
+ dependencies = []
19
+
20
+ [project.urls]
21
+ Homepage = "https://github.com/HamSCI/callhash"
22
+ "Bug Tracker" = "https://github.com/HamSCI/callhash/issues"
23
+
24
+ [project.optional-dependencies]
25
+ dev = [
26
+ "pytest>=7.0.0",
27
+ ]
28
+
29
+ [tool.setuptools.packages.find]
30
+ where = ["src"]
31
+ include = ["callhash*"]
32
+
33
+ [tool.pytest.ini_options]
34
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,61 @@
1
+ """WSJT-X callsign-hash mechanism — Bob Jenkins lookup3 (seed 146)
2
+ plus an accumulator that resolves hashes from ``<call>`` announcement
3
+ markers in decoded text.
4
+
5
+ Background. WSJT-X's FT4/FT8/WSPR packet formats compress compound
6
+ callsigns (e.g. ``K1ABC/QRP``, ``VE3/K1ABC``) into 22-bit (FT8/FT4)
7
+ or 15-bit (WSPR) hashes; receivers maintain a session table that
8
+ maps the hash back to plaintext when the call has been observed in a
9
+ ``<call>`` first-occurrence message. Both ``jt9`` and ``wsprd`` use
10
+ this same hash function (``nhash`` / Bob Jenkins lookup3, seed 146).
11
+
12
+ Per-slot decoder invocations (psk-recorder, wsprdaemon-client) start
13
+ with an empty session table, so most hashed packets emerge as
14
+ ``<...>`` placeholders. This module reconstructs the table at the
15
+ consumer side from the same announcement markers.
16
+
17
+ Public API:
18
+
19
+ from callhash import CallHashTable, hash22, hash15, nhash
20
+
21
+ table = CallHashTable.load_or_new("/var/lib/<client>/hashtable.json")
22
+ table.observe("260507 1234 -12 +0.45 1250 ` <K1ABC/QRP> CQ FT8")
23
+ table.by_hash22(hash22("K1ABC/QRP")) # → "K1ABC/QRP"
24
+ clean = table.normalise_brackets("<K1ABC/QRP>") # → "K1ABC/QRP"
25
+ clean = table.normalise_brackets("<...>") # → None
26
+ table.save() # persists to JSON
27
+
28
+ The hash function is bit-exact against WSJT-X's canonical
29
+ ``lib/wsprcode/nhash.c`` for all 23 reference vectors in
30
+ ``tests/test_nhash.py`` (including 11/12/13-byte boundary cases that
31
+ exercise distinct final-block branches).
32
+ """
33
+ from ._nhash import (
34
+ MASK10,
35
+ MASK12,
36
+ MASK15,
37
+ MASK22,
38
+ WSJTX_INITVAL,
39
+ hash10,
40
+ hash12,
41
+ hash15,
42
+ hash22,
43
+ nhash,
44
+ )
45
+ from .parse import parse_message
46
+ from .table import CallHashTable
47
+
48
+ __all__ = [
49
+ "CallHashTable",
50
+ "MASK10",
51
+ "MASK12",
52
+ "MASK15",
53
+ "MASK22",
54
+ "WSJTX_INITVAL",
55
+ "hash10",
56
+ "hash12",
57
+ "hash15",
58
+ "hash22",
59
+ "nhash",
60
+ "parse_message",
61
+ ]
@@ -0,0 +1,122 @@
1
+ """Bob Jenkins lookup3 ``nhash`` — Python port of WSJT-X's
2
+ ``lib/wsprd/nhash.c``.
3
+
4
+ WSJT-X uses ``nhash(call, len(call), initval=146)`` as the basis for
5
+ the 22-bit / 15-bit / 12-bit / 10-bit hash values that compress
6
+ compound callsigns into FT4/FT8/WSPR packet payloads. Both
7
+ ``decode_ft8``-style and ``wsprd``-style decoders use the same
8
+ function with the same seed (146) — see
9
+ ``/tmp/wsjtx-mirror/lib/wsprd/wsprd_utils.c:int unpk_(...)`` for the
10
+ WSPR-side call site and ``/tmp/wsjtx-mirror/lib/hash.f90`` for the
11
+ FT8/FT4 side.
12
+
13
+ This port matches the C output bit-exactly for ASCII inputs.
14
+ Cross-validation vectors are in ``tests/test_callhash_nhash.py``,
15
+ generated by compiling the upstream C and capturing its outputs.
16
+ """
17
+ from __future__ import annotations
18
+
19
+ WSJTX_INITVAL = 146 # Seed used by both jt9 and wsprd.
20
+ MASK22 = 0x3FFFFF # FT8/FT4 compound-call hash width.
21
+ MASK15 = 0x7FFF # WSPR Type 3 hash width.
22
+ MASK12 = 0xFFF # ARRL contest hash variant.
23
+ MASK10 = 0x3FF # Smallest WSJT-X hash variant.
24
+
25
+
26
+ def _rot(x: int, k: int) -> int:
27
+ """32-bit rotate-left."""
28
+ return ((x << k) | (x >> (32 - k))) & 0xFFFFFFFF
29
+
30
+
31
+ def _mix(a: int, b: int, c: int) -> tuple[int, int, int]:
32
+ """The mix() macro from nhash.c — six rotate/xor/sub/add rounds."""
33
+ a = (a - c) & 0xFFFFFFFF; a ^= _rot(c, 4); c = (c + b) & 0xFFFFFFFF
34
+ b = (b - a) & 0xFFFFFFFF; b ^= _rot(a, 6); a = (a + c) & 0xFFFFFFFF
35
+ c = (c - b) & 0xFFFFFFFF; c ^= _rot(b, 8); b = (b + a) & 0xFFFFFFFF
36
+ a = (a - c) & 0xFFFFFFFF; a ^= _rot(c, 16); c = (c + b) & 0xFFFFFFFF
37
+ b = (b - a) & 0xFFFFFFFF; b ^= _rot(a, 19); a = (a + c) & 0xFFFFFFFF
38
+ c = (c - b) & 0xFFFFFFFF; c ^= _rot(b, 4); b = (b + a) & 0xFFFFFFFF
39
+ return a, b, c
40
+
41
+
42
+ def _final(a: int, b: int, c: int) -> int:
43
+ """The final() macro from nhash.c — seven rotate/xor/sub rounds."""
44
+ c ^= b; c = (c - _rot(b, 14)) & 0xFFFFFFFF
45
+ a ^= c; a = (a - _rot(c, 11)) & 0xFFFFFFFF
46
+ b ^= a; b = (b - _rot(a, 25)) & 0xFFFFFFFF
47
+ c ^= b; c = (c - _rot(b, 16)) & 0xFFFFFFFF
48
+ a ^= c; a = (a - _rot(c, 4)) & 0xFFFFFFFF
49
+ b ^= a; b = (b - _rot(a, 14)) & 0xFFFFFFFF
50
+ c ^= b; c = (c - _rot(b, 24)) & 0xFFFFFFFF
51
+ return c
52
+
53
+
54
+ def nhash(key: bytes | str, initval: int = WSJTX_INITVAL) -> int:
55
+ """Compute Bob Jenkins lookup3 hash of ``key`` with the given seed.
56
+
57
+ Matches the C output of WSJT-X's ``nhash()`` for ASCII inputs.
58
+ Returns a 32-bit unsigned integer; callers mask down to the bit
59
+ width their protocol uses (see :func:`hash22`, :func:`hash15`).
60
+
61
+ ``key`` may be ``bytes`` or ``str``; strings are encoded as ASCII
62
+ (matching the C call sites that hash Fortran character arrays
63
+ containing callsign text).
64
+ """
65
+ if isinstance(key, str):
66
+ key = key.encode("ascii")
67
+ length = len(key)
68
+ a = b = c = (0xDEADBEEF + length + initval) & 0xFFFFFFFF
69
+
70
+ # Process complete 12-byte blocks as three little-endian uint32s.
71
+ pos = 0
72
+ remaining = length
73
+ while remaining > 12:
74
+ a = (a + int.from_bytes(key[pos : pos + 4], "little")) & 0xFFFFFFFF
75
+ b = (b + int.from_bytes(key[pos + 4 : pos + 8], "little")) & 0xFFFFFFFF
76
+ c = (c + int.from_bytes(key[pos + 8 : pos + 12], "little")) & 0xFFFFFFFF
77
+ a, b, c = _mix(a, b, c)
78
+ remaining -= 12
79
+ pos += 12
80
+
81
+ # Final partial block — emulate the C switch statement, masking
82
+ # so the output matches the C's "read-past-end-then-mask" trick
83
+ # (we just don't read past the end). Zero-length input returns
84
+ # the initial c verbatim.
85
+ if remaining == 0:
86
+ return c
87
+
88
+ tail = key[pos : pos + remaining]
89
+ if remaining >= 9:
90
+ a = (a + int.from_bytes(tail[0:4], "little")) & 0xFFFFFFFF
91
+ b = (b + int.from_bytes(tail[4:8], "little")) & 0xFFFFFFFF
92
+ c_val = int.from_bytes(tail[8:remaining], "little")
93
+ c = (c + c_val) & 0xFFFFFFFF
94
+ elif remaining >= 5:
95
+ a = (a + int.from_bytes(tail[0:4], "little")) & 0xFFFFFFFF
96
+ b_val = int.from_bytes(tail[4:remaining], "little")
97
+ b = (b + b_val) & 0xFFFFFFFF
98
+ else:
99
+ a_val = int.from_bytes(tail[:remaining], "little")
100
+ a = (a + a_val) & 0xFFFFFFFF
101
+
102
+ return _final(a, b, c)
103
+
104
+
105
+ def hash22(call: str) -> int:
106
+ """22-bit hash of ``call`` — used by FT8/FT4 compound-callsign packets."""
107
+ return nhash(call) & MASK22
108
+
109
+
110
+ def hash15(call: str) -> int:
111
+ """15-bit hash of ``call`` — used by WSPR Type 3 packets."""
112
+ return nhash(call) & MASK15
113
+
114
+
115
+ def hash12(call: str) -> int:
116
+ """12-bit hash variant — used by some ARRL-contest message types."""
117
+ return nhash(call) & MASK12
118
+
119
+
120
+ def hash10(call: str) -> int:
121
+ """10-bit hash variant — narrowest WSJT-X hash."""
122
+ return nhash(call) & MASK10
@@ -0,0 +1,132 @@
1
+ """Shared WSJT-X message-field parser.
2
+
3
+ FT8 / FT4 / MSK144 decoders (``decode_ft8``, ``jt9``) emit a freeform
4
+ message body whose grammar is identical across the modes. Every
5
+ recorder consumer — psk-recorder, meteor-scatter, wspr-recorder — needs
6
+ the same best-effort extraction of tx/rx call, grid, and report, *and*
7
+ the same compound-callsign hash substitution via
8
+ :class:`~callhash.table.CallHashTable`.
9
+
10
+ Before this module the extraction was copy-pasted byte-for-byte into
11
+ each recorder's ``ch_tailer.py`` and the table was built but never read,
12
+ so hashed spots lost their call. Centralising it here means one
13
+ implementation that resolves hashes the same way everywhere — the whole
14
+ point of a shared callhash library.
15
+
16
+ ``parse_message`` is intentionally lossy: the raw (hash-resolved)
17
+ message string is always returned in ``message`` so the caller can
18
+ preserve it verbatim; the parsed call/grid/report fields are best-effort.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import re
23
+ from typing import Any, Dict, Optional
24
+
25
+ # Standard callsigns + WSJT-X compound forms:
26
+ # * standard ITU call: K1ABC, AC0G, JA1AAA
27
+ # * suffix-form compound: K1ABC/QRP, K1ABC/MM
28
+ # * prefix-form compound (region/portable): VE3/K1ABC, G/K1ABC, KH6/AC0G
29
+ _CALL_RE = re.compile(
30
+ r"^"
31
+ r"(?:[A-Z0-9]{1,3}/)?" # optional prefix (e.g. "VE3/", "G/")
32
+ r"[A-Z0-9]{1,3}[0-9][A-Z0-9]{0,4}" # standard call body (XX[X][D][YY[Y][Y]])
33
+ r"(?:/[A-Z0-9]{1,4})?" # optional suffix (e.g. "/QRP", "/MM")
34
+ r"$"
35
+ )
36
+ # Maidenhead 6-char form has uppercase field+square but lowercase
37
+ # subsquare (per IARU convention). Tolerate either case for robustness.
38
+ _GRID_RE = re.compile(r"^[A-R]{2}[0-9]{2}(?:[A-Xa-x]{2})?$")
39
+ _REPORT_RE = re.compile(r"^R?([+-]?\d+)$")
40
+
41
+
42
+ def _is_grid(token: str) -> bool:
43
+ """A Maidenhead locator, but never the sign-off ``RR73``. RR73 has a
44
+ locator's shape (a square in the Arctic Ocean), and WSJT-X never
45
+ sends that square: a grid read from it would place every station
46
+ that signs off near the pole."""
47
+ return bool(_GRID_RE.match(token)) and token.upper() != "RR73"
48
+
49
+
50
+ def _plain(token: str) -> Optional[str]:
51
+ """Return a bare callsign token, or ``None`` if it's still bracketed.
52
+
53
+ ``parse_message`` resolves the whole message first, so any token that
54
+ *still* carries angle brackets here (``<...>`` or a numeric hash we've
55
+ never seen announced) is genuinely unrecoverable — drop it from the
56
+ call fields rather than emitting a placeholder.
57
+ """
58
+ if not token or token.startswith("<"):
59
+ return None
60
+ return token
61
+
62
+
63
+ def parse_message(message: str, table: Optional[Any] = None) -> Dict[str, Any]:
64
+ """Parse a decoded FT8/FT4/MSK144 message body.
65
+
66
+ When ``table`` (a :class:`CallHashTable`) is supplied, the message is
67
+ first run through :meth:`CallHashTable.resolve_message` so bracketed
68
+ hashes that we've learned are substituted with plaintext calls — this
69
+ is what stops us shipping ``<...>`` spots whose call we actually know.
70
+
71
+ Recognized shapes (all approximate; freeform messages return empties):
72
+ "CQ <tx_call> [<grid>]" — directed CQ
73
+ "<rx_call> <tx_call> <grid>" — first contact w/ grid
74
+ "<rx_call> <tx_call> R <grid>" — reply that acknowledges, w/ grid
75
+ "<rx_call> <tx_call> [R]<report>" — signal report
76
+ "<rx_call> <tx_call> [73|RR73]" — close
77
+
78
+ Returns a dict with keys ``message`` (the hash-resolved text — callers
79
+ should store THIS, not the raw input), ``tx_call``, ``rx_call``,
80
+ ``grid`` (all ``""`` when absent) and ``report`` (``None`` when absent).
81
+ """
82
+ if table is not None:
83
+ message = table.resolve_message(message)
84
+
85
+ out: Dict[str, Any] = {
86
+ "message": message,
87
+ "tx_call": "",
88
+ "rx_call": "",
89
+ "grid": "",
90
+ "report": None,
91
+ }
92
+ tokens = message.split()
93
+ if not tokens:
94
+ return out
95
+
96
+ if tokens[0] == "CQ":
97
+ # "CQ [target] <tx_call> [grid]" — `target` may be a region tag
98
+ # like "DX", "EU", "POTA" that isn't a callsign. Scan past
99
+ # non-call tokens until the first call-shaped one (the sender),
100
+ # then look for a grid in the remaining tokens.
101
+ for i, tok in enumerate(tokens[1:], start=1):
102
+ candidate = _plain(tok)
103
+ if candidate is not None and _CALL_RE.match(candidate):
104
+ out["tx_call"] = candidate
105
+ for later in tokens[i + 1:]:
106
+ if _is_grid(later):
107
+ out["grid"] = later
108
+ break
109
+ break
110
+ else:
111
+ # <rx_call> <tx_call> [grid|R grid|report|RR73|73]
112
+ rx_candidate = _plain(tokens[0])
113
+ if rx_candidate is not None and _CALL_RE.match(rx_candidate):
114
+ out["rx_call"] = rx_candidate
115
+ if len(tokens) >= 2:
116
+ tx_candidate = _plain(tokens[1])
117
+ if tx_candidate is not None and _CALL_RE.match(tx_candidate):
118
+ out["tx_call"] = tx_candidate
119
+ if len(tokens) >= 3:
120
+ tail = tokens[2]
121
+ if tail == "R" and len(tokens) >= 4 and _is_grid(tokens[3]):
122
+ out["grid"] = tokens[3]
123
+ elif _is_grid(tail):
124
+ out["grid"] = tail
125
+ else:
126
+ m = _REPORT_RE.match(tail)
127
+ if m:
128
+ try:
129
+ out["report"] = int(m.group(1))
130
+ except ValueError:
131
+ pass
132
+ return out