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 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
+ )
@@ -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
@@ -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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (80.9.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,6 @@
1
+ Contributors
2
+ ------------
3
+
4
+ * @cardoso-neto
5
+ * @dhruvbaldawa
6
+ * @pinnaculum
@@ -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