py-multibase 2.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.
- multibase/__init__.py +26 -0
- multibase/converters.py +264 -0
- multibase/exceptions.py +25 -0
- multibase/multibase.py +291 -0
- py_multibase-2.0.0.dist-info/METADATA +149 -0
- py_multibase-2.0.0.dist-info/RECORD +10 -0
- py_multibase-2.0.0.dist-info/WHEEL +5 -0
- py_multibase-2.0.0.dist-info/licenses/AUTHORS.rst +6 -0
- py_multibase-2.0.0.dist-info/licenses/LICENSE +10 -0
- py_multibase-2.0.0.dist-info/top_level.txt +1 -0
multibase/__init__.py
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""Top-level package for py-multibase."""
|
|
2
|
+
|
|
3
|
+
__author__ = """Dhruv Baldawa"""
|
|
4
|
+
__email__ = "dhruv@dhruvb.com"
|
|
5
|
+
__version__ = "2.0.0"
|
|
6
|
+
|
|
7
|
+
from .exceptions import ( # noqa: F401
|
|
8
|
+
DecodingError,
|
|
9
|
+
InvalidMultibaseStringError,
|
|
10
|
+
MultibaseError,
|
|
11
|
+
UnsupportedEncodingError,
|
|
12
|
+
)
|
|
13
|
+
from .multibase import ( # noqa: F401
|
|
14
|
+
ENCODINGS,
|
|
15
|
+
ComposedDecoder,
|
|
16
|
+
Decoder,
|
|
17
|
+
Encoder,
|
|
18
|
+
Encoding,
|
|
19
|
+
decode,
|
|
20
|
+
encode,
|
|
21
|
+
get_codec,
|
|
22
|
+
get_encoding_info,
|
|
23
|
+
is_encoded,
|
|
24
|
+
is_encoding_supported,
|
|
25
|
+
list_encodings,
|
|
26
|
+
)
|
multibase/converters.py
ADDED
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
from io import BytesIO
|
|
2
|
+
from itertools import zip_longest
|
|
3
|
+
|
|
4
|
+
from baseconv import BaseConverter
|
|
5
|
+
from morphys import ensure_bytes
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class BaseStringConverter(BaseConverter):
|
|
9
|
+
def encode(self, bytes):
|
|
10
|
+
number = int.from_bytes(bytes, byteorder="big", signed=False)
|
|
11
|
+
return ensure_bytes(super().encode(number))
|
|
12
|
+
|
|
13
|
+
def bytes_to_int(self, bytes):
|
|
14
|
+
length = len(bytes)
|
|
15
|
+
base = len(self.digits)
|
|
16
|
+
value = 0
|
|
17
|
+
|
|
18
|
+
for i, x in enumerate(bytes):
|
|
19
|
+
value += self.digits.index(chr(x)) * base ** (length - (i + 1))
|
|
20
|
+
return value
|
|
21
|
+
|
|
22
|
+
def decode(self, bytes):
|
|
23
|
+
decoded_int = self.bytes_to_int(bytes)
|
|
24
|
+
# See https://docs.python.org/3.5/library/stdtypes.html#int.to_bytes for more about the magical expression
|
|
25
|
+
# below
|
|
26
|
+
decoded_data = decoded_int.to_bytes((decoded_int.bit_length() + 7) // 8, byteorder="big")
|
|
27
|
+
return decoded_data
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class Base16StringConverter(BaseStringConverter):
|
|
31
|
+
def __init__(self, digits):
|
|
32
|
+
super().__init__(digits)
|
|
33
|
+
self.uppercase = digits.isupper()
|
|
34
|
+
|
|
35
|
+
def encode(self, bytes):
|
|
36
|
+
result = "".join([f"{byte:02x}" for byte in bytes])
|
|
37
|
+
if self.uppercase:
|
|
38
|
+
result = result.upper()
|
|
39
|
+
return ensure_bytes(result)
|
|
40
|
+
|
|
41
|
+
def decode(self, data):
|
|
42
|
+
# Base16 decode is case-insensitive, normalize to our digits case
|
|
43
|
+
if isinstance(data, bytes):
|
|
44
|
+
data_str = data.decode("utf-8")
|
|
45
|
+
else:
|
|
46
|
+
data_str = data
|
|
47
|
+
# Convert to match our digits case
|
|
48
|
+
if self.uppercase:
|
|
49
|
+
data_str = data_str.upper()
|
|
50
|
+
else:
|
|
51
|
+
data_str = data_str.lower()
|
|
52
|
+
return super().decode(data_str.encode("utf-8"))
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
class BaseByteStringConverter:
|
|
56
|
+
ENCODE_GROUP_BYTES = 1
|
|
57
|
+
ENCODING_BITS = 1
|
|
58
|
+
DECODING_BITS = 1
|
|
59
|
+
|
|
60
|
+
def __init__(self, digits, pad=False):
|
|
61
|
+
self.digits = digits
|
|
62
|
+
self.pad = pad
|
|
63
|
+
|
|
64
|
+
def _chunk_with_padding(self, iterable, n, fillvalue=None):
|
|
65
|
+
"Collect data into fixed-length chunks or blocks"
|
|
66
|
+
# _chunk_with_padding('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
|
|
67
|
+
args = [iter(iterable)] * n
|
|
68
|
+
return zip_longest(*args, fillvalue=fillvalue)
|
|
69
|
+
|
|
70
|
+
def _chunk_without_padding(self, iterable, n):
|
|
71
|
+
return map("".join, zip(*[iter(iterable)] * n))
|
|
72
|
+
|
|
73
|
+
def _encode_bytes(self, bytes_, group_bytes, encoding_bits, decoding_bits, output_chars):
|
|
74
|
+
buffer = BytesIO(bytes_)
|
|
75
|
+
encoded_bytes = BytesIO()
|
|
76
|
+
input_length = len(bytes_)
|
|
77
|
+
|
|
78
|
+
while True:
|
|
79
|
+
byte_ = buffer.read(group_bytes)
|
|
80
|
+
if not byte_:
|
|
81
|
+
break
|
|
82
|
+
|
|
83
|
+
# convert all bytes to a binary format and concatenate them into a 24bit string
|
|
84
|
+
binstringfmt = f"{{:0{encoding_bits}b}}"
|
|
85
|
+
binstring = "".join([binstringfmt.format(x) for x in byte_])
|
|
86
|
+
# break the 24 bit length string into pieces of 6 bits each and convert them to integer
|
|
87
|
+
digits = (int("".join(x), 2) for x in self._chunk_with_padding(binstring, decoding_bits, "0"))
|
|
88
|
+
|
|
89
|
+
for digit in digits:
|
|
90
|
+
# convert binary representation to an integer
|
|
91
|
+
encoded_bytes.write(ensure_bytes(self.digits[digit]))
|
|
92
|
+
|
|
93
|
+
result = encoded_bytes.getvalue()
|
|
94
|
+
|
|
95
|
+
# Add padding if needed (RFC 4648)
|
|
96
|
+
if self.pad:
|
|
97
|
+
remainder = input_length % group_bytes
|
|
98
|
+
if remainder > 0:
|
|
99
|
+
# For partial groups, we need to pad the output
|
|
100
|
+
# The padding makes the output length a multiple of output_chars
|
|
101
|
+
chars_produced = len(result)
|
|
102
|
+
# Calculate padding needed to reach next multiple of output_chars
|
|
103
|
+
padding_needed = output_chars - (chars_produced % output_chars)
|
|
104
|
+
result += ensure_bytes("=" * padding_needed)
|
|
105
|
+
|
|
106
|
+
return result
|
|
107
|
+
|
|
108
|
+
def _decode_bytes(self, bytes_, group_bytes, decoding_bits, encoding_bits):
|
|
109
|
+
# Remove padding if present
|
|
110
|
+
if self.pad:
|
|
111
|
+
bytes_ = bytes_.rstrip(b"=")
|
|
112
|
+
|
|
113
|
+
buffer = BytesIO()
|
|
114
|
+
decoded_bytes = BytesIO()
|
|
115
|
+
|
|
116
|
+
for byte_ in bytes_.decode():
|
|
117
|
+
idx = self.digits.index(byte_)
|
|
118
|
+
buffer.write(bytes([idx]))
|
|
119
|
+
|
|
120
|
+
buffer.seek(0)
|
|
121
|
+
while True:
|
|
122
|
+
byte_ = buffer.read(group_bytes)
|
|
123
|
+
if not byte_:
|
|
124
|
+
break
|
|
125
|
+
|
|
126
|
+
# convert all bytes to a binary format and concatenate them into a 8, 16, 24bit string
|
|
127
|
+
binstringfmt = f"{{:0{decoding_bits}b}}"
|
|
128
|
+
binstring = "".join([binstringfmt.format(x) for x in byte_])
|
|
129
|
+
|
|
130
|
+
# break the 24 bit length string into pieces of 8 bits each and convert them to integer
|
|
131
|
+
digits = [int("".join(x), 2) for x in self._chunk_without_padding(binstring, encoding_bits)]
|
|
132
|
+
|
|
133
|
+
for digit in digits:
|
|
134
|
+
decoded_bytes.write(bytes([digit]))
|
|
135
|
+
|
|
136
|
+
return decoded_bytes.getvalue()
|
|
137
|
+
|
|
138
|
+
def encode(self, bytes):
|
|
139
|
+
raise NotImplementedError
|
|
140
|
+
|
|
141
|
+
def decode(self, bytes):
|
|
142
|
+
return NotImplementedError
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
class Base64StringConverter(BaseByteStringConverter):
|
|
146
|
+
def encode(self, bytes):
|
|
147
|
+
return self._encode_bytes(ensure_bytes(bytes), 3, 8, 6, 4)
|
|
148
|
+
|
|
149
|
+
def decode(self, bytes):
|
|
150
|
+
return self._decode_bytes(ensure_bytes(bytes), 4, 6, 8)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
class Base32StringConverter(BaseByteStringConverter):
|
|
154
|
+
def encode(self, bytes):
|
|
155
|
+
return self._encode_bytes(ensure_bytes(bytes), 5, 8, 5, 8)
|
|
156
|
+
|
|
157
|
+
def decode(self, bytes):
|
|
158
|
+
return self._decode_bytes(ensure_bytes(bytes), 8, 5, 8)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
class Base256EmojiConverter:
|
|
162
|
+
"""Base256 emoji encoding using 256 unique emoji characters.
|
|
163
|
+
|
|
164
|
+
This implementation uses the exact same hardcoded emoji alphabet as
|
|
165
|
+
js-multiformats and go-multibase reference implementations to ensure
|
|
166
|
+
full compatibility. The alphabet is curated from Unicode emoji frequency
|
|
167
|
+
data, excluding modifier-based emojis (such as flags) that are bigger
|
|
168
|
+
than one single code point.
|
|
169
|
+
"""
|
|
170
|
+
|
|
171
|
+
# Hardcoded emoji alphabet matching js-multiformats and go-multibase
|
|
172
|
+
# This is the exact same alphabet used in reference implementations
|
|
173
|
+
# Source: js-multiformats/src/bases/base256emoji.ts and go-multibase/base256emoji.go
|
|
174
|
+
_EMOJI_ALPHABET = (
|
|
175
|
+
"🚀🪐☄🛰🌌" # Space
|
|
176
|
+
"🌑🌒🌓🌔🌕🌖🌗🌘" # Moon
|
|
177
|
+
"🌍🌏🌎" # Earth
|
|
178
|
+
"🐉" # Dragon
|
|
179
|
+
"☀" # Sun
|
|
180
|
+
"💻🖥💾💿" # Computer
|
|
181
|
+
# Rest from Unicode emoji frequency data (most used first)
|
|
182
|
+
"😂❤😍🤣😊🙏💕😭😘👍"
|
|
183
|
+
"😅👏😁🔥🥰💔💖💙😢🤔"
|
|
184
|
+
"😆🙄💪😉☺👌🤗💜😔😎"
|
|
185
|
+
"😇🌹🤦🎉💞✌✨🤷😱😌"
|
|
186
|
+
"🌸🙌😋💗💚😏💛🙂💓🤩"
|
|
187
|
+
"😄😀🖤😃💯🙈👇🎶😒🤭"
|
|
188
|
+
"❣😜💋👀😪😑💥🙋😞😩"
|
|
189
|
+
"😡🤪👊🥳😥🤤👉💃😳✋"
|
|
190
|
+
"😚😝😴🌟😬🙃🍀🌷😻😓"
|
|
191
|
+
"⭐✅🥺🌈😈🤘💦✔😣🏃"
|
|
192
|
+
"💐☹🎊💘😠☝😕🌺🎂🌻"
|
|
193
|
+
"😐🖕💝🙊😹🗣💫💀👑🎵"
|
|
194
|
+
"🤞😛🔴😤🌼😫⚽🤙☕🏆"
|
|
195
|
+
"🤫👈😮🙆🍻🍃🐶💁😲🌿"
|
|
196
|
+
"🧡🎁⚡🌞🎈❌✊👋😰🤨"
|
|
197
|
+
"😶🤝🚶💰🍓💢🤟🙁🚨💨"
|
|
198
|
+
"🤬✈🎀🍺🤓😙💟🌱😖👶"
|
|
199
|
+
"🥴▶➡❓💎💸⬇😨🌚🦋"
|
|
200
|
+
"😷🕺⚠🙅😟😵👎🤲🤠🤧"
|
|
201
|
+
"📌🔵💅🧐🐾🍒😗🤑🌊🤯"
|
|
202
|
+
"🐷☎💧😯💆👆🎤🙇🍑❄"
|
|
203
|
+
"🌴💣🐸💌📍🥀🤢👅💡💩"
|
|
204
|
+
"👐📸👻🤐🤮🎼🥵🚩🍎🍊"
|
|
205
|
+
"👼💍📣🥂"
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
def __init__(self):
|
|
209
|
+
# Verify alphabet length
|
|
210
|
+
if len(self._EMOJI_ALPHABET) != 256:
|
|
211
|
+
raise ValueError(f"EMOJI_ALPHABET must contain exactly 256 characters, got {len(self._EMOJI_ALPHABET)}")
|
|
212
|
+
# Create mapping from byte value to emoji character
|
|
213
|
+
self.byte_to_emoji = {i: self._EMOJI_ALPHABET[i] for i in range(256)}
|
|
214
|
+
# Create reverse mapping from emoji character to byte value
|
|
215
|
+
# This matches the approach in js-multiformats and go-multibase
|
|
216
|
+
self.emoji_to_byte = {emoji: byte for byte, emoji in self.byte_to_emoji.items()}
|
|
217
|
+
|
|
218
|
+
def encode(self, bytes_) -> bytes:
|
|
219
|
+
"""Encode bytes to emoji string.
|
|
220
|
+
|
|
221
|
+
:param bytes_: Bytes to encode
|
|
222
|
+
:type bytes_: bytes or str
|
|
223
|
+
:return: UTF-8 encoded emoji string
|
|
224
|
+
:rtype: bytes
|
|
225
|
+
"""
|
|
226
|
+
bytes_ = ensure_bytes(bytes_)
|
|
227
|
+
result = []
|
|
228
|
+
for byte_val in bytes_:
|
|
229
|
+
result.append(self.byte_to_emoji[byte_val])
|
|
230
|
+
return "".join(result).encode("utf-8")
|
|
231
|
+
|
|
232
|
+
def decode(self, bytes_) -> bytes:
|
|
233
|
+
"""Decode emoji string to bytes.
|
|
234
|
+
|
|
235
|
+
Decodes character-by-character, matching the behavior of js-multiformats
|
|
236
|
+
and go-multibase reference implementations. Each emoji in the alphabet
|
|
237
|
+
is a single Unicode code point, so we can safely iterate character by
|
|
238
|
+
character.
|
|
239
|
+
|
|
240
|
+
:param bytes_: UTF-8 encoded emoji string
|
|
241
|
+
:type bytes_: bytes or str
|
|
242
|
+
:return: Decoded bytes
|
|
243
|
+
:rtype: bytes
|
|
244
|
+
:raises ValueError: if an invalid emoji character is encountered
|
|
245
|
+
"""
|
|
246
|
+
bytes_ = ensure_bytes(bytes_, "utf8")
|
|
247
|
+
# Decode UTF-8 to get emoji string
|
|
248
|
+
emoji_str = bytes_.decode("utf-8")
|
|
249
|
+
result = bytearray()
|
|
250
|
+
# Iterate character by character (Python string iteration handles
|
|
251
|
+
# single code point emojis correctly, matching js-multiformats and go-multibase)
|
|
252
|
+
for char in emoji_str:
|
|
253
|
+
if char not in self.emoji_to_byte:
|
|
254
|
+
raise ValueError(f"Non-base256emoji character: {char}")
|
|
255
|
+
result.append(self.emoji_to_byte[char])
|
|
256
|
+
return bytes(result)
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
class IdentityConverter:
|
|
260
|
+
def encode(self, x):
|
|
261
|
+
return x
|
|
262
|
+
|
|
263
|
+
def decode(self, x):
|
|
264
|
+
return x
|
multibase/exceptions.py
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Custom exceptions for multibase encoding/decoding errors."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class MultibaseError(ValueError):
|
|
5
|
+
"""Base exception for all multibase errors."""
|
|
6
|
+
|
|
7
|
+
pass
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class UnsupportedEncodingError(MultibaseError):
|
|
11
|
+
"""Raised when an encoding is not supported."""
|
|
12
|
+
|
|
13
|
+
pass
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class InvalidMultibaseStringError(MultibaseError):
|
|
17
|
+
"""Raised when a multibase string is invalid or cannot be decoded."""
|
|
18
|
+
|
|
19
|
+
pass
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class DecodingError(MultibaseError):
|
|
23
|
+
"""Raised when decoding fails."""
|
|
24
|
+
|
|
25
|
+
pass
|
multibase/multibase.py
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
from collections import namedtuple
|
|
2
|
+
|
|
3
|
+
from morphys import ensure_bytes
|
|
4
|
+
|
|
5
|
+
from .converters import (
|
|
6
|
+
Base16StringConverter,
|
|
7
|
+
Base32StringConverter,
|
|
8
|
+
Base64StringConverter,
|
|
9
|
+
Base256EmojiConverter,
|
|
10
|
+
BaseStringConverter,
|
|
11
|
+
IdentityConverter,
|
|
12
|
+
)
|
|
13
|
+
from .exceptions import (
|
|
14
|
+
DecodingError,
|
|
15
|
+
InvalidMultibaseStringError,
|
|
16
|
+
UnsupportedEncodingError,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
Encoding = namedtuple("Encoding", "encoding,code,converter")
|
|
20
|
+
CODE_LENGTH = 1
|
|
21
|
+
ENCODINGS = [
|
|
22
|
+
Encoding("identity", b"\x00", IdentityConverter()),
|
|
23
|
+
Encoding("base2", b"0", BaseStringConverter("01")),
|
|
24
|
+
Encoding("base8", b"7", BaseStringConverter("01234567")),
|
|
25
|
+
Encoding("base10", b"9", BaseStringConverter("0123456789")),
|
|
26
|
+
Encoding("base16", b"f", Base16StringConverter("0123456789abcdef")),
|
|
27
|
+
Encoding("base16upper", b"F", Base16StringConverter("0123456789ABCDEF")),
|
|
28
|
+
Encoding("base32hex", b"v", Base32StringConverter("0123456789abcdefghijklmnopqrstuv")),
|
|
29
|
+
Encoding("base32hexupper", b"V", Base32StringConverter("0123456789ABCDEFGHIJKLMNOPQRSTUV")),
|
|
30
|
+
Encoding("base32hexpad", b"t", Base32StringConverter("0123456789abcdefghijklmnopqrstuv", pad=True)),
|
|
31
|
+
Encoding("base32hexpadupper", b"T", Base32StringConverter("0123456789ABCDEFGHIJKLMNOPQRSTUV", pad=True)),
|
|
32
|
+
Encoding("base32", b"b", Base32StringConverter("abcdefghijklmnopqrstuvwxyz234567")),
|
|
33
|
+
Encoding("base32upper", b"B", Base32StringConverter("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567")),
|
|
34
|
+
Encoding("base32pad", b"c", Base32StringConverter("abcdefghijklmnopqrstuvwxyz234567", pad=True)),
|
|
35
|
+
Encoding("base32padupper", b"C", Base32StringConverter("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567", pad=True)),
|
|
36
|
+
Encoding("base32z", b"h", BaseStringConverter("ybndrfg8ejkmcpqxot1uwisza345h769")),
|
|
37
|
+
Encoding("base36", b"k", BaseStringConverter("0123456789abcdefghijklmnopqrstuvwxyz")),
|
|
38
|
+
Encoding("base36upper", b"K", BaseStringConverter("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ")),
|
|
39
|
+
Encoding("base58flickr", b"Z", BaseStringConverter("123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ")),
|
|
40
|
+
Encoding("base58btc", b"z", BaseStringConverter("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")),
|
|
41
|
+
Encoding("base64", b"m", Base64StringConverter("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/")),
|
|
42
|
+
Encoding(
|
|
43
|
+
"base64pad",
|
|
44
|
+
b"M",
|
|
45
|
+
Base64StringConverter("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", pad=True),
|
|
46
|
+
),
|
|
47
|
+
Encoding(
|
|
48
|
+
"base64url",
|
|
49
|
+
b"u",
|
|
50
|
+
Base64StringConverter("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"),
|
|
51
|
+
),
|
|
52
|
+
Encoding(
|
|
53
|
+
"base64urlpad",
|
|
54
|
+
b"U",
|
|
55
|
+
Base64StringConverter("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_", pad=True),
|
|
56
|
+
),
|
|
57
|
+
Encoding("base256emoji", "🚀".encode(), Base256EmojiConverter()),
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
ENCODINGS_LOOKUP = {}
|
|
61
|
+
for codec in ENCODINGS:
|
|
62
|
+
ENCODINGS_LOOKUP[codec.encoding] = codec
|
|
63
|
+
ENCODINGS_LOOKUP[codec.code] = codec
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def encode(encoding, data):
|
|
67
|
+
"""
|
|
68
|
+
Encodes the given data using the encoding that is specified
|
|
69
|
+
|
|
70
|
+
:param str encoding: encoding to use, should be one of the supported encoding
|
|
71
|
+
:param data: data to encode
|
|
72
|
+
:type data: str or bytes
|
|
73
|
+
:return: multibase encoded data
|
|
74
|
+
:rtype: bytes
|
|
75
|
+
:raises UnsupportedEncodingError: if the encoding is not supported
|
|
76
|
+
"""
|
|
77
|
+
data = ensure_bytes(data, "utf8")
|
|
78
|
+
try:
|
|
79
|
+
return ENCODINGS_LOOKUP[encoding].code + ENCODINGS_LOOKUP[encoding].converter.encode(data)
|
|
80
|
+
except KeyError:
|
|
81
|
+
raise UnsupportedEncodingError(f"Encoding {encoding} not supported.")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def get_codec(data):
|
|
85
|
+
"""
|
|
86
|
+
Returns the codec used to encode the given data
|
|
87
|
+
|
|
88
|
+
:param data: multibase encoded data
|
|
89
|
+
:type data: str or bytes
|
|
90
|
+
:return: the :py:obj:`multibase.Encoding` object for the data's codec
|
|
91
|
+
:raises InvalidMultibaseStringError: if the codec is not supported
|
|
92
|
+
"""
|
|
93
|
+
data = ensure_bytes(data, "utf8")
|
|
94
|
+
# Check for base256emoji first (4-byte UTF-8 prefix)
|
|
95
|
+
if len(data) >= 4:
|
|
96
|
+
emoji_prefix = data[:4]
|
|
97
|
+
if emoji_prefix in ENCODINGS_LOOKUP:
|
|
98
|
+
return ENCODINGS_LOOKUP[emoji_prefix]
|
|
99
|
+
|
|
100
|
+
# Check for single-byte prefixes
|
|
101
|
+
try:
|
|
102
|
+
key = data[:CODE_LENGTH]
|
|
103
|
+
codec = ENCODINGS_LOOKUP[key]
|
|
104
|
+
except KeyError:
|
|
105
|
+
raise InvalidMultibaseStringError(f"Can not determine encoding for {data}")
|
|
106
|
+
else:
|
|
107
|
+
return codec
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def is_encoded(data):
|
|
111
|
+
"""
|
|
112
|
+
Checks if the given data is encoded or not
|
|
113
|
+
|
|
114
|
+
:param data: multibase encoded data
|
|
115
|
+
:type data: str or bytes
|
|
116
|
+
:return: if the data is encoded or not
|
|
117
|
+
:rtype: bool
|
|
118
|
+
"""
|
|
119
|
+
try:
|
|
120
|
+
get_codec(data)
|
|
121
|
+
return True
|
|
122
|
+
except (ValueError, InvalidMultibaseStringError):
|
|
123
|
+
return False
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def is_encoding_supported(encoding):
|
|
127
|
+
"""
|
|
128
|
+
Check if an encoding is supported.
|
|
129
|
+
|
|
130
|
+
:param encoding: encoding name to check
|
|
131
|
+
:type encoding: str
|
|
132
|
+
:return: True if encoding is supported, False otherwise
|
|
133
|
+
:rtype: bool
|
|
134
|
+
"""
|
|
135
|
+
return encoding in ENCODINGS_LOOKUP
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def list_encodings():
|
|
139
|
+
"""
|
|
140
|
+
List all supported encodings.
|
|
141
|
+
|
|
142
|
+
:return: list of encoding names
|
|
143
|
+
:rtype: list
|
|
144
|
+
"""
|
|
145
|
+
return [enc.encoding for enc in ENCODINGS]
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def get_encoding_info(encoding):
|
|
149
|
+
"""
|
|
150
|
+
Get information about a specific encoding.
|
|
151
|
+
|
|
152
|
+
:param encoding: encoding name
|
|
153
|
+
:type encoding: str
|
|
154
|
+
:return: Encoding namedtuple with encoding, code, and converter
|
|
155
|
+
:rtype: Encoding
|
|
156
|
+
:raises UnsupportedEncodingError: if encoding is not supported
|
|
157
|
+
"""
|
|
158
|
+
if encoding not in ENCODINGS_LOOKUP:
|
|
159
|
+
raise UnsupportedEncodingError(f"Encoding {encoding} not supported.")
|
|
160
|
+
return ENCODINGS_LOOKUP[encoding]
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def decode(data, return_encoding=False):
|
|
164
|
+
"""
|
|
165
|
+
Decode the multibase decoded data
|
|
166
|
+
|
|
167
|
+
:param data: multibase encoded data
|
|
168
|
+
:type data: str or bytes
|
|
169
|
+
:param return_encoding: if True, return tuple (encoding, decoded_data)
|
|
170
|
+
:type return_encoding: bool
|
|
171
|
+
:return: decoded data, or tuple (encoding, decoded_data) if return_encoding=True
|
|
172
|
+
:rtype: bytes or tuple
|
|
173
|
+
:raises InvalidMultibaseStringError: if the data is not multibase encoded
|
|
174
|
+
:raises DecodingError: if decoding fails
|
|
175
|
+
"""
|
|
176
|
+
data = ensure_bytes(data, "utf8")
|
|
177
|
+
try:
|
|
178
|
+
codec = get_codec(data)
|
|
179
|
+
# Handle base256emoji which has a 4-byte prefix
|
|
180
|
+
prefix_length = len(codec.code)
|
|
181
|
+
decoded = codec.converter.decode(data[prefix_length:])
|
|
182
|
+
if return_encoding:
|
|
183
|
+
return (codec.encoding, decoded)
|
|
184
|
+
return decoded
|
|
185
|
+
except (InvalidMultibaseStringError, UnsupportedEncodingError):
|
|
186
|
+
# Re-raise these specific exceptions as-is since they already provide
|
|
187
|
+
# appropriate context about what went wrong (invalid format or unsupported encoding)
|
|
188
|
+
raise
|
|
189
|
+
except Exception as e:
|
|
190
|
+
# Wrap all other exceptions (e.g., converter errors, invalid data)
|
|
191
|
+
# in DecodingError to provide consistent error handling
|
|
192
|
+
raise DecodingError(f"Failed to decode multibase data: {e}") from e
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
class Encoder:
|
|
196
|
+
"""Reusable encoder for a specific encoding."""
|
|
197
|
+
|
|
198
|
+
def __init__(self, encoding):
|
|
199
|
+
"""
|
|
200
|
+
Initialize an encoder for a specific encoding.
|
|
201
|
+
|
|
202
|
+
:param encoding: encoding name to use
|
|
203
|
+
:type encoding: str
|
|
204
|
+
:raises UnsupportedEncodingError: if encoding is not supported
|
|
205
|
+
"""
|
|
206
|
+
if encoding not in ENCODINGS_LOOKUP:
|
|
207
|
+
raise UnsupportedEncodingError(f"Encoding {encoding} not supported.")
|
|
208
|
+
self.encoding = encoding
|
|
209
|
+
self._codec = ENCODINGS_LOOKUP[encoding]
|
|
210
|
+
|
|
211
|
+
def encode(self, data):
|
|
212
|
+
"""
|
|
213
|
+
Encode data using this encoder's encoding.
|
|
214
|
+
|
|
215
|
+
:param data: data to encode
|
|
216
|
+
:type data: str or bytes
|
|
217
|
+
:return: multibase encoded data
|
|
218
|
+
:rtype: bytes
|
|
219
|
+
"""
|
|
220
|
+
data = ensure_bytes(data, "utf8")
|
|
221
|
+
return self._codec.code + self._codec.converter.encode(data)
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
class Decoder:
|
|
225
|
+
"""Reusable decoder for multibase data."""
|
|
226
|
+
|
|
227
|
+
def __init__(self):
|
|
228
|
+
"""Initialize a decoder."""
|
|
229
|
+
pass
|
|
230
|
+
|
|
231
|
+
def decode(self, data, return_encoding=False):
|
|
232
|
+
"""
|
|
233
|
+
Decode multibase encoded data.
|
|
234
|
+
|
|
235
|
+
:param data: multibase encoded data
|
|
236
|
+
:type data: str or bytes
|
|
237
|
+
:param return_encoding: if True, return tuple (encoding, decoded_data)
|
|
238
|
+
:type return_encoding: bool
|
|
239
|
+
:return: decoded data, or tuple (encoding, decoded_data) if return_encoding=True
|
|
240
|
+
:rtype: bytes or tuple
|
|
241
|
+
:raises InvalidMultibaseStringError: if the data is not multibase encoded
|
|
242
|
+
:raises DecodingError: if decoding fails
|
|
243
|
+
"""
|
|
244
|
+
return decode(data, return_encoding=return_encoding)
|
|
245
|
+
|
|
246
|
+
def or_(self, other_decoder):
|
|
247
|
+
"""
|
|
248
|
+
Compose this decoder with another, trying this one first.
|
|
249
|
+
|
|
250
|
+
This allows trying multiple decoders in sequence.
|
|
251
|
+
|
|
252
|
+
:param other_decoder: another decoder to try if this one fails
|
|
253
|
+
:type other_decoder: Decoder
|
|
254
|
+
:return: a composed decoder
|
|
255
|
+
:rtype: ComposedDecoder
|
|
256
|
+
"""
|
|
257
|
+
return ComposedDecoder([self, other_decoder])
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
class ComposedDecoder:
|
|
261
|
+
"""A decoder that tries multiple decoders in sequence."""
|
|
262
|
+
|
|
263
|
+
def __init__(self, decoders):
|
|
264
|
+
"""
|
|
265
|
+
Initialize a composed decoder.
|
|
266
|
+
|
|
267
|
+
:param decoders: list of decoders to try in order
|
|
268
|
+
:type decoders: list
|
|
269
|
+
"""
|
|
270
|
+
self.decoders = decoders
|
|
271
|
+
|
|
272
|
+
def decode(self, data, return_encoding=False):
|
|
273
|
+
"""
|
|
274
|
+
Try to decode with each decoder in sequence.
|
|
275
|
+
|
|
276
|
+
:param data: multibase encoded data
|
|
277
|
+
:type data: str or bytes
|
|
278
|
+
:param return_encoding: if True, return tuple (encoding, decoded_data)
|
|
279
|
+
:type return_encoding: bool
|
|
280
|
+
:return: decoded data, or tuple (encoding, decoded_data) if return_encoding=True
|
|
281
|
+
:rtype: bytes or tuple
|
|
282
|
+
:raises DecodingError: if all decoders fail
|
|
283
|
+
"""
|
|
284
|
+
last_error = None
|
|
285
|
+
for decoder in self.decoders:
|
|
286
|
+
try:
|
|
287
|
+
return decoder.decode(data, return_encoding=return_encoding)
|
|
288
|
+
except (InvalidMultibaseStringError, DecodingError) as e:
|
|
289
|
+
last_error = e
|
|
290
|
+
continue
|
|
291
|
+
raise DecodingError(f"All decoders failed. Last error: {last_error}") from last_error
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: py-multibase
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Multibase implementation for Python
|
|
5
|
+
Author-email: Dhruv Baldawa <dhruv@dhruvb.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/multiformats/py-multibase
|
|
8
|
+
Project-URL: Download, https://github.com/multiformats/py-multibase/tarball/2.0.0
|
|
9
|
+
Keywords: multibase
|
|
10
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Natural Language :: English
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Requires-Python: <4.0,>=3.10
|
|
21
|
+
Description-Content-Type: text/x-rst
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
License-File: AUTHORS.rst
|
|
24
|
+
Requires-Dist: python-baseconv<2.0,>=1.2.0
|
|
25
|
+
Requires-Dist: six<2.0,>=1.10.0
|
|
26
|
+
Requires-Dist: morphys<2.0,>=1.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: Sphinx>=5.0.0; extra == "dev"
|
|
29
|
+
Requires-Dist: build>=0.9.0; extra == "dev"
|
|
30
|
+
Requires-Dist: bump-my-version>=1.2.0; extra == "dev"
|
|
31
|
+
Requires-Dist: mypy; extra == "dev"
|
|
32
|
+
Requires-Dist: pre-commit; extra == "dev"
|
|
33
|
+
Requires-Dist: pytest; extra == "dev"
|
|
34
|
+
Requires-Dist: pytest-runner; extra == "dev"
|
|
35
|
+
Requires-Dist: ruff; extra == "dev"
|
|
36
|
+
Requires-Dist: towncrier<25,>=24; extra == "dev"
|
|
37
|
+
Requires-Dist: tox>=4.10.0; extra == "dev"
|
|
38
|
+
Requires-Dist: twine; extra == "dev"
|
|
39
|
+
Requires-Dist: watchdog>=3.0.0; extra == "dev"
|
|
40
|
+
Requires-Dist: wheel>=0.31.0; extra == "dev"
|
|
41
|
+
Dynamic: license-file
|
|
42
|
+
|
|
43
|
+
py-multibase
|
|
44
|
+
------------
|
|
45
|
+
|
|
46
|
+
.. image:: https://img.shields.io/pypi/v/py-multibase.svg
|
|
47
|
+
:target: https://pypi.python.org/pypi/py-multibase
|
|
48
|
+
|
|
49
|
+
.. image:: https://github.com/multiformats/py-multibase/actions/workflows/tox.yml/badge.svg
|
|
50
|
+
:target: https://github.com/multiformats/py-multibase/actions
|
|
51
|
+
|
|
52
|
+
.. image:: https://readthedocs.org/projects/py-multibase/badge/?version=stable
|
|
53
|
+
:target: https://py-multibase.readthedocs.io/en/stable/?badge=stable
|
|
54
|
+
:alt: Documentation Status
|
|
55
|
+
|
|
56
|
+
`Multibase <https://github.com/multiformats/multibase>`_ implementation for Python
|
|
57
|
+
|
|
58
|
+
Multibase is a protocol for distinguishing base encodings and other simple string encodings, and for ensuring full compatibility with program interfaces.
|
|
59
|
+
|
|
60
|
+
It answers the question: Given data d encoded into string s, how can I tell what base d is encoded with?
|
|
61
|
+
|
|
62
|
+
Base encodings exist because transports have restrictions, use special in-band sequences, or must be human-friendly.
|
|
63
|
+
When systems chose a base to use, it is not always clear which base to use, as there are many tradeoffs in the decision.
|
|
64
|
+
Multibase is here to save programs and programmers from worrying about which encoding is best.
|
|
65
|
+
|
|
66
|
+
It solves the biggest problem: a program can use multibase to take input or produce output in whichever base is desired.
|
|
67
|
+
|
|
68
|
+
The important part is that the value is self-describing, letting other programs elsewhere know what encoding it is using.
|
|
69
|
+
|
|
70
|
+
* Free software: MIT license
|
|
71
|
+
* Documentation: https://py-multibase.readthedocs.io.
|
|
72
|
+
* Python versions: Python 3.10, 3.11, 3.12, 3.13, 3.14
|
|
73
|
+
|
|
74
|
+
Installation
|
|
75
|
+
============
|
|
76
|
+
|
|
77
|
+
.. code-block:: shell
|
|
78
|
+
|
|
79
|
+
$ pip install py-multibase
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
Sample Usage
|
|
83
|
+
============
|
|
84
|
+
|
|
85
|
+
.. code-block:: python
|
|
86
|
+
|
|
87
|
+
>>> # encoding a buffer
|
|
88
|
+
>>> from multibase import encode, decode
|
|
89
|
+
>>> encode('base58btc', 'hello world')
|
|
90
|
+
b'zStV1DL6CwTryKyV'
|
|
91
|
+
>>> encode('base64', 'hello world')
|
|
92
|
+
b'mGhlbGxvIHdvcmxk'
|
|
93
|
+
>>> # decoding a multibase
|
|
94
|
+
>>> decode('mGhlbGxvIHdvcmxk')
|
|
95
|
+
b'hello world'
|
|
96
|
+
>>> decode(b'zStV1DL6CwTryKyV')
|
|
97
|
+
b'hello world'
|
|
98
|
+
>>> decode(encode('base2', b'hello world'))
|
|
99
|
+
b'hello world'
|
|
100
|
+
|
|
101
|
+
>>> # Using reusable Encoder/Decoder classes
|
|
102
|
+
>>> from multibase import Encoder, Decoder
|
|
103
|
+
>>> encoder = Encoder('base64')
|
|
104
|
+
>>> encoded1 = encoder.encode('data1')
|
|
105
|
+
>>> encoded2 = encoder.encode('data2')
|
|
106
|
+
|
|
107
|
+
>>> decoder = Decoder()
|
|
108
|
+
>>> decoded = decoder.decode(encoded1)
|
|
109
|
+
|
|
110
|
+
>>> # Getting encoding information
|
|
111
|
+
>>> from multibase import get_encoding_info, list_encodings, is_encoding_supported
|
|
112
|
+
>>> info = get_encoding_info('base64')
|
|
113
|
+
>>> print(info.encoding, info.code)
|
|
114
|
+
base64 b'm'
|
|
115
|
+
>>> all_encodings = list_encodings()
|
|
116
|
+
>>> is_encoding_supported('base64')
|
|
117
|
+
True
|
|
118
|
+
|
|
119
|
+
>>> # Decode with encoding return
|
|
120
|
+
>>> encoding, data = decode(encoded1, return_encoding=True)
|
|
121
|
+
>>> print(f'Encoded with {encoding}: {data}')
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
Supported codecs
|
|
125
|
+
================
|
|
126
|
+
|
|
127
|
+
* base2
|
|
128
|
+
* base8
|
|
129
|
+
* base10
|
|
130
|
+
* base16
|
|
131
|
+
* base16upper
|
|
132
|
+
* base32hex
|
|
133
|
+
* base32hexupper
|
|
134
|
+
* base32hexpad
|
|
135
|
+
* base32hexpadupper
|
|
136
|
+
* base32
|
|
137
|
+
* base32upper
|
|
138
|
+
* base32pad
|
|
139
|
+
* base32padupper
|
|
140
|
+
* base32z
|
|
141
|
+
* base36
|
|
142
|
+
* base36upper
|
|
143
|
+
* base58flickr
|
|
144
|
+
* base58btc
|
|
145
|
+
* base64
|
|
146
|
+
* base64pad
|
|
147
|
+
* base64url
|
|
148
|
+
* base64urlpad
|
|
149
|
+
* base256emoji
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
multibase/__init__.py,sha256=3A5Kh2eB5TogiH_pdSe1utMenwgwAMsGr9zIJsB3VV0,516
|
|
2
|
+
multibase/converters.py,sha256=OIv8wrc1FYg4F2Na14AcqAiDCxQ0QBFHS-tztpA4Wxs,9885
|
|
3
|
+
multibase/exceptions.py,sha256=QfXPjc34yfKC0HUV57iMVaxgY0z-snuvbwMMwXC35GQ,497
|
|
4
|
+
multibase/multibase.py,sha256=Wcju1MjulQxw7Za6A7OH3yuth4BkScQ7haz3FEcMbTA,10242
|
|
5
|
+
py_multibase-2.0.0.dist-info/licenses/AUTHORS.rst,sha256=5HhInll7iC-oHHKtIThnLbhFqQlb8beic-8oCz7IAXo,73
|
|
6
|
+
py_multibase-2.0.0.dist-info/licenses/LICENSE,sha256=5dMPN_jqBC8RoSCBvVx6CLBe0wo0AEqDv6PZgHZEqbg,1072
|
|
7
|
+
py_multibase-2.0.0.dist-info/METADATA,sha256=jgtLgae7weLiJlFu2NoZe6cvR_E5IxOLlMQmylZ2FAc,4835
|
|
8
|
+
py_multibase-2.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
|
|
9
|
+
py_multibase-2.0.0.dist-info/top_level.txt,sha256=G7JJdQUUMHXja30zZ3FYpbei8k8_C3HVx4muR55vKZc,10
|
|
10
|
+
py_multibase-2.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
|
|
2
|
+
MIT License
|
|
3
|
+
|
|
4
|
+
Copyright (c) 2017, Dhruv Baldawa
|
|
5
|
+
|
|
6
|
+
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:
|
|
7
|
+
|
|
8
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
9
|
+
|
|
10
|
+
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.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
multibase
|