py-multicodec 1.0.0__py3-none-any.whl

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.
multicodec/__init__.py ADDED
@@ -0,0 +1,80 @@
1
+ """Top-level package for py-multicodec."""
2
+
3
+ __author__ = """Dhruv Baldawa"""
4
+ __email__ = "dhruv@dhruvb.com"
5
+ __version__ = "1.0.0"
6
+
7
+ # Core Code type
8
+ from .code import (
9
+ RESERVED_END,
10
+ RESERVED_START,
11
+ Code,
12
+ is_reserved,
13
+ known_codes,
14
+ )
15
+
16
+ # Exceptions
17
+ from .exceptions import (
18
+ CodecError,
19
+ DecodeError,
20
+ EncodeError,
21
+ MulticodecError,
22
+ UnknownCodecError,
23
+ )
24
+
25
+ # Original multicodec functions
26
+ from .multicodec import add_prefix, extract_prefix, get_codec, get_prefix, is_codec, remove_prefix
27
+
28
+ # Serialization support
29
+ from .serialization import (
30
+ Codec,
31
+ JSONCodec,
32
+ RawCodec,
33
+ decode,
34
+ encode,
35
+ get_registered_codec,
36
+ is_codec_registered,
37
+ json_codec,
38
+ list_registered_codecs,
39
+ raw_codec,
40
+ register_codec,
41
+ unregister_codec,
42
+ )
43
+
44
+ __all__ = [
45
+ # Constants
46
+ "RESERVED_END",
47
+ "RESERVED_START",
48
+ # Code type
49
+ "Code",
50
+ # Serialization base classes
51
+ "Codec",
52
+ "CodecError",
53
+ "DecodeError",
54
+ "EncodeError",
55
+ # Built-in codecs
56
+ "JSONCodec",
57
+ # Exceptions
58
+ "MulticodecError",
59
+ "RawCodec",
60
+ "UnknownCodecError",
61
+ # Original functions
62
+ "add_prefix",
63
+ "decode",
64
+ # Serialization functions
65
+ "encode",
66
+ "extract_prefix",
67
+ "get_codec",
68
+ "get_prefix",
69
+ "get_registered_codec",
70
+ "is_codec",
71
+ "is_codec_registered",
72
+ "is_reserved",
73
+ "json_codec",
74
+ "known_codes",
75
+ "list_registered_codecs",
76
+ "raw_codec",
77
+ "register_codec",
78
+ "remove_prefix",
79
+ "unregister_codec",
80
+ ]
multicodec/code.py ADDED
@@ -0,0 +1,467 @@
1
+ """
2
+ Multicodec Code type and core functionality.
3
+
4
+ This module provides:
5
+ - Code class for type-safe codec handling
6
+ - ReservedStart and ReservedEnd constants
7
+ - KnownCodes() function to list all registered codes
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from .constants import CODE_TABLE, NAME_TABLE
13
+
14
+ # ReservedStart is the (inclusive) start of the reserved range of codes that
15
+ # are safe to use for internal purposes.
16
+ RESERVED_START: int = 0x300000
17
+
18
+ # ReservedEnd is the (inclusive) end of the reserved range of codes that are
19
+ # safe to use for internal purposes.
20
+ RESERVED_END: int = 0x3FFFFF
21
+
22
+
23
+ class Code:
24
+ """
25
+ Code describes an integer reserved in the multicodec table.
26
+
27
+ This class provides:
28
+ - Type-safe codec handling
29
+ - String conversion (name lookup)
30
+ - Set from string (name or hex number)
31
+ - Tag lookup
32
+
33
+ Example:
34
+ >>> code = Code(0x12)
35
+ >>> str(code)
36
+ 'sha2-256'
37
+ >>> code = Code.from_string("sha2-256")
38
+ >>> int(code)
39
+ 18
40
+ """
41
+
42
+ __slots__ = ("_value",)
43
+
44
+ def __init__(self, value: int) -> None:
45
+ """Initialize a Code with an integer value."""
46
+ if not isinstance(value, int):
47
+ raise TypeError(f"Code value must be an integer, got {type(value).__name__}")
48
+ if value < 0:
49
+ raise ValueError("Code value must be non-negative")
50
+ self._value = value
51
+
52
+ @classmethod
53
+ def from_string(cls, text: str) -> Code:
54
+ """
55
+ Create a Code from a string, interpreting it as a multicodec name or number.
56
+
57
+ The input string can be the name or number for a known code. A number can be
58
+ in decimal or hexadecimal format (with 0x prefix).
59
+
60
+ Numbers in the reserved range 0x300000-0x3FFFFF are also accepted.
61
+
62
+ :param str text: The codec name or number
63
+ :return: A Code instance
64
+ :rtype: Code
65
+ :raises ValueError: If the text is not a valid codec
66
+ """
67
+ # Try parsing as a number first (cheap operation)
68
+ try:
69
+ n = int(text, 0) # base 0 allows decimal, hex (0x), octal (0o), binary (0b)
70
+ code = cls(n)
71
+ # Accept if in reserved range
72
+ if RESERVED_START <= n <= RESERVED_END:
73
+ return code
74
+ # Accept if known code
75
+ if n in CODE_TABLE:
76
+ return code
77
+ except ValueError:
78
+ pass
79
+
80
+ # Try matching by name
81
+ if text in NAME_TABLE:
82
+ return cls(NAME_TABLE[text])
83
+
84
+ raise ValueError(f'unknown multicodec: "{text}"')
85
+
86
+ def set(self, text: str) -> None:
87
+ """
88
+ Set the code from a string.
89
+
90
+ :param str text: The codec name or number
91
+ :raises ValueError: If the text is not a valid codec
92
+ """
93
+ new_code = Code.from_string(text)
94
+ self._value = new_code._value
95
+
96
+ def __int__(self) -> int:
97
+ """Return the integer value of the code."""
98
+ return self._value
99
+
100
+ def __index__(self) -> int:
101
+ """Support using Code in contexts that require an integer index."""
102
+ return self._value
103
+
104
+ def __str__(self) -> str:
105
+ """
106
+ Return the string name of the code.
107
+
108
+ Returns the codec name if known, otherwise returns the hex representation.
109
+ """
110
+ if self._value in CODE_TABLE:
111
+ return CODE_TABLE[self._value]
112
+ return f"Code(0x{self._value:x})"
113
+
114
+ def __repr__(self) -> str:
115
+ """Return a detailed representation of the code."""
116
+ if self._value in CODE_TABLE:
117
+ return f"Code({CODE_TABLE[self._value]!r}, 0x{self._value:x})"
118
+ return f"Code(0x{self._value:x})"
119
+
120
+ def __eq__(self, other: object) -> bool:
121
+ """Check equality with another Code or integer."""
122
+ if isinstance(other, Code):
123
+ return self._value == other._value
124
+ if isinstance(other, int):
125
+ return self._value == other
126
+ return NotImplemented
127
+
128
+ def __hash__(self) -> int:
129
+ """Return hash of the code value."""
130
+ return hash(self._value)
131
+
132
+ def __lt__(self, other: Code | int) -> bool:
133
+ """Compare less than."""
134
+ if isinstance(other, Code):
135
+ return self._value < other._value
136
+ if isinstance(other, int):
137
+ return self._value < other
138
+ return NotImplemented
139
+
140
+ def __le__(self, other: Code | int) -> bool:
141
+ """Compare less than or equal."""
142
+ if isinstance(other, Code):
143
+ return self._value <= other._value
144
+ if isinstance(other, int):
145
+ return self._value <= other
146
+ return NotImplemented
147
+
148
+ def __gt__(self, other: Code | int) -> bool:
149
+ """Compare greater than."""
150
+ if isinstance(other, Code):
151
+ return self._value > other._value
152
+ if isinstance(other, int):
153
+ return self._value > other
154
+ return NotImplemented
155
+
156
+ def __ge__(self, other: Code | int) -> bool:
157
+ """Compare greater than or equal."""
158
+ if isinstance(other, Code):
159
+ return self._value >= other._value
160
+ if isinstance(other, int):
161
+ return self._value >= other
162
+ return NotImplemented
163
+
164
+ @property
165
+ def name(self) -> str:
166
+ """Return the codec name, or '<unknown>' if not found."""
167
+ return CODE_TABLE.get(self._value, "<unknown>")
168
+
169
+ def tag(self) -> str:
170
+ """
171
+ Return the tag for this codec.
172
+
173
+ Tags categorize codecs (e.g., "multihash", "multiaddr", "ipld", etc.)
174
+ """
175
+ return _get_tag(self._value)
176
+
177
+
178
+ def _get_tag(code: int) -> str:
179
+ """Get the tag for a codec code (mirrors go-multicodec's Tag() method)."""
180
+ name = CODE_TABLE.get(code, "")
181
+
182
+ # CID
183
+ if name in ("cidv1", "cidv2", "cidv3"):
184
+ return "cid"
185
+
186
+ # Encryption
187
+ if name in ("aes-gcm-256",):
188
+ return "encryption"
189
+
190
+ # Filecoin
191
+ if name in ("fil-commitment-unsealed", "fil-commitment-sealed"):
192
+ return "filecoin"
193
+
194
+ # Hash (non-multihash)
195
+ if name in (
196
+ "murmur3-x64-64",
197
+ "murmur3-32",
198
+ "murmur3-128",
199
+ "crc32",
200
+ "crc64-ecma",
201
+ "crc64-nvme",
202
+ "murmur3-x64-128",
203
+ "sha256a",
204
+ "xxh-32",
205
+ "xxh-64",
206
+ "xxh3-64",
207
+ "xxh3-128",
208
+ ):
209
+ return "hash"
210
+
211
+ # Holochain
212
+ if "holochain" in name:
213
+ return "holochain"
214
+
215
+ # IPLD
216
+ if name in (
217
+ "cbor",
218
+ "raw",
219
+ "dag-pb",
220
+ "dag-cbor",
221
+ "libp2p-key",
222
+ "git-raw",
223
+ "torrent-info",
224
+ "torrent-file",
225
+ "blake3-hashseq",
226
+ "leofcoin-block",
227
+ "leofcoin-tx",
228
+ "leofcoin-pr",
229
+ "dag-jose",
230
+ "dag-cose",
231
+ "eth-block",
232
+ "eth-block-list",
233
+ "eth-tx-trie",
234
+ "eth-tx",
235
+ "eth-tx-receipt-trie",
236
+ "eth-tx-receipt",
237
+ "eth-state-trie",
238
+ "eth-account-snapshot",
239
+ "eth-storage-trie",
240
+ "eth-receipt-log-trie",
241
+ "eth-receipt-log",
242
+ "bitcoin-block",
243
+ "bitcoin-tx",
244
+ "bitcoin-witness-commitment",
245
+ "zcash-block",
246
+ "zcash-tx",
247
+ "stellar-block",
248
+ "stellar-tx",
249
+ "decred-block",
250
+ "decred-tx",
251
+ "dash-block",
252
+ "dash-tx",
253
+ "swarm-manifest",
254
+ "swarm-feed",
255
+ "beeson",
256
+ "dag-json",
257
+ "swhid-1-snp",
258
+ "json",
259
+ "rdfc-1",
260
+ "json-jcs",
261
+ ):
262
+ return "ipld"
263
+
264
+ # Key
265
+ if any(
266
+ k in name
267
+ for k in (
268
+ "-pub",
269
+ "-priv",
270
+ "secp256k1",
271
+ "bls12_381",
272
+ "x25519",
273
+ "ed25519",
274
+ "p256",
275
+ "p384",
276
+ "p521",
277
+ "ed448",
278
+ "x448",
279
+ "sr25519",
280
+ "rsa",
281
+ "sm2",
282
+ "mlkem",
283
+ "jwk",
284
+ )
285
+ ):
286
+ return "key"
287
+
288
+ # Libp2p
289
+ if name in ("libp2p-peer-record", "libp2p-relay-rsvp"):
290
+ return "libp2p"
291
+
292
+ # Multiaddr
293
+ if name in (
294
+ "ip4",
295
+ "tcp",
296
+ "dccp",
297
+ "ip6",
298
+ "ip6zone",
299
+ "ipcidr",
300
+ "dns",
301
+ "dns4",
302
+ "dns6",
303
+ "dnsaddr",
304
+ "sctp",
305
+ "udp",
306
+ "p2p-webrtc-star",
307
+ "p2p-webrtc-direct",
308
+ "p2p-stardust",
309
+ "p2p-circuit",
310
+ "udt",
311
+ "utp",
312
+ "unix",
313
+ "thread",
314
+ "p2p",
315
+ "https",
316
+ "onion",
317
+ "onion3",
318
+ "garlic64",
319
+ "garlic32",
320
+ "tls",
321
+ "sni",
322
+ "noise",
323
+ "shs",
324
+ "quic",
325
+ "quic-v1",
326
+ "webtransport",
327
+ "certhash",
328
+ "ws",
329
+ "wss",
330
+ "p2p-websocket-star",
331
+ "http",
332
+ "http-path",
333
+ "webrtc-direct",
334
+ "webrtc",
335
+ "plaintextv2",
336
+ "scion",
337
+ "memory",
338
+ ):
339
+ return "multiaddr"
340
+
341
+ # Multiformat
342
+ if name in ("multicodec", "multihash", "multiaddr", "multibase", "varsig"):
343
+ return "multiformat"
344
+
345
+ # Multihash
346
+ if any(
347
+ h in name
348
+ for h in (
349
+ "identity",
350
+ "sha1",
351
+ "sha2-",
352
+ "sha3-",
353
+ "shake-",
354
+ "keccak-",
355
+ "blake2b-",
356
+ "blake2s-",
357
+ "blake3",
358
+ "dbl-sha2-",
359
+ "md4",
360
+ "md5",
361
+ "bmt",
362
+ "ripemd-",
363
+ "x11",
364
+ "kangarootwelve",
365
+ "sm3-",
366
+ "poseidon-",
367
+ "skein",
368
+ )
369
+ ):
370
+ return "multihash"
371
+
372
+ # Namespace
373
+ if name in (
374
+ "path",
375
+ "lbry",
376
+ "streamid",
377
+ "ipld-ns",
378
+ "ipfs-ns",
379
+ "swarm-ns",
380
+ "ipns-ns",
381
+ "zeronet",
382
+ "dnslink",
383
+ "skynet-ns",
384
+ "arweave-ns",
385
+ "subspace-ns",
386
+ "kumandra-ns",
387
+ ):
388
+ return "namespace"
389
+
390
+ # Serialization
391
+ if name in (
392
+ "protobuf",
393
+ "rlp",
394
+ "bencode",
395
+ "messagepack",
396
+ "car",
397
+ "car-index-sorted",
398
+ "car-multihash-index-sorted",
399
+ "ipns-record",
400
+ "x509-certificate",
401
+ "ssz",
402
+ ):
403
+ return "serialization"
404
+
405
+ # Transport
406
+ if name in (
407
+ "transport-bitswap",
408
+ "transport-graphsync-filecoinv1",
409
+ "transport-ipfs-gateway-http",
410
+ ):
411
+ return "transport"
412
+
413
+ # Varsig
414
+ if name in (
415
+ "nonstandard-sig",
416
+ "es256k",
417
+ "bls12_381-g1-sig",
418
+ "bls12_381-g2-sig",
419
+ "eddsa",
420
+ "eip-191",
421
+ "es256",
422
+ "es384",
423
+ "es512",
424
+ "rs256",
425
+ ):
426
+ return "varsig"
427
+
428
+ # Zeroxcert
429
+ if name in ("zeroxcert-imprint-256",):
430
+ return "zeroxcert"
431
+
432
+ return "<unknown>"
433
+
434
+
435
+ # Cache for known codes list
436
+ _known_codes: list[Code] | None = None
437
+
438
+
439
+ def known_codes() -> list[Code]:
440
+ """
441
+ Return a list of all codes registered in the multicodec table.
442
+
443
+ The returned list should be treated as read-only.
444
+
445
+ :return: List of all known Code objects
446
+ :rtype: list[Code]
447
+ """
448
+ global _known_codes
449
+ if _known_codes is None:
450
+ _known_codes = [Code(code) for code in sorted(CODE_TABLE.keys())]
451
+ return _known_codes
452
+
453
+
454
+ def is_reserved(code: int | Code) -> bool:
455
+ """
456
+ Check if a code falls within the reserved range.
457
+
458
+ The reserved range (0x300000-0x3FFFFF) is designated for internal
459
+ and experimental use.
460
+
461
+ :param code: The codec code to check
462
+ :return: True if the code is in the reserved range
463
+ :rtype: bool
464
+ """
465
+ if isinstance(code, Code):
466
+ code = int(code)
467
+ return RESERVED_START <= code <= RESERVED_END