py-multibase 2.0.0__tar.gz → 2.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.
Files changed (43) hide show
  1. {py_multibase-2.0.0 → py_multibase-2.1.0}/CONTRIBUTING.rst +5 -0
  2. {py_multibase-2.0.0 → py_multibase-2.1.0}/HISTORY.rst +39 -0
  3. {py_multibase-2.0.0 → py_multibase-2.1.0}/PKG-INFO +10 -4
  4. {py_multibase-2.0.0 → py_multibase-2.1.0}/README.rst +5 -1
  5. py_multibase-2.1.0/docs/api_reference.rst +26 -0
  6. {py_multibase-2.0.0 → py_multibase-2.1.0}/multibase/__init__.py +2 -1
  7. {py_multibase-2.0.0 → py_multibase-2.1.0}/multibase/converters.py +55 -34
  8. {py_multibase-2.0.0 → py_multibase-2.1.0}/multibase/multibase.py +62 -17
  9. {py_multibase-2.0.0 → py_multibase-2.1.0}/py_multibase.egg-info/PKG-INFO +10 -4
  10. {py_multibase-2.0.0 → py_multibase-2.1.0}/py_multibase.egg-info/SOURCES.txt +6 -1
  11. {py_multibase-2.0.0 → py_multibase-2.1.0}/py_multibase.egg-info/requires.txt +3 -1
  12. py_multibase-2.1.0/py_multibase.egg-info/top_level.txt +2 -0
  13. {py_multibase-2.0.0 → py_multibase-2.1.0}/pyproject.toml +23 -4
  14. py_multibase-2.1.0/tests/test_benchmarks.py +27 -0
  15. py_multibase-2.1.0/tests/test_fuzz.py +36 -0
  16. {py_multibase-2.0.0 → py_multibase-2.1.0}/tests/test_multibase.py +65 -0
  17. py_multibase-2.1.0/tests/test_roundtrip.py +74 -0
  18. py_multibase-2.1.0/tests/test_spec.py +46 -0
  19. py_multibase-2.1.0/tests/test_spec_vectors.py +56 -0
  20. py_multibase-2.0.0/docs/api_reference.rst +0 -12
  21. py_multibase-2.0.0/py_multibase.egg-info/top_level.txt +0 -1
  22. {py_multibase-2.0.0 → py_multibase-2.1.0}/AUTHORS.rst +0 -0
  23. {py_multibase-2.0.0 → py_multibase-2.1.0}/LICENSE +0 -0
  24. {py_multibase-2.0.0 → py_multibase-2.1.0}/MANIFEST.in +0 -0
  25. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/Makefile +0 -0
  26. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/_build/html/_static/file.png +0 -0
  27. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/_build/html/_static/minus.png +0 -0
  28. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/_build/html/_static/plus.png +0 -0
  29. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/authors.rst +0 -0
  30. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/conf.py +0 -0
  31. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/contributing.rst +0 -0
  32. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/history.rst +0 -0
  33. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/index.rst +0 -0
  34. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/installation.rst +0 -0
  35. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/make.bat +0 -0
  36. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/modules.rst +0 -0
  37. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/multibase.rst +0 -0
  38. {py_multibase-2.0.0 → py_multibase-2.1.0}/docs/usage.rst +0 -0
  39. {py_multibase-2.0.0 → py_multibase-2.1.0}/multibase/exceptions.py +0 -0
  40. {py_multibase-2.0.0 → py_multibase-2.1.0}/py_multibase.egg-info/dependency_links.txt +0 -0
  41. {py_multibase-2.0.0 → py_multibase-2.1.0}/py_multibase.egg-info/not-zip-safe +0 -0
  42. {py_multibase-2.0.0 → py_multibase-2.1.0}/setup.cfg +0 -0
  43. {py_multibase-2.0.0 → py_multibase-2.1.0}/tests/__init__.py +0 -0
@@ -114,6 +114,11 @@ The project provides several ``make`` targets to help with development:
114
114
  * ``make test`` - Run the test suite with pytest using the default Python version.
115
115
  For testing across multiple Python versions, use ``tox`` instead.
116
116
 
117
+ * ``make docs`` / ``make docs-ci`` - Build the Sphinx documentation locally (with
118
+ warnings treated as errors). API stub pages are generated with
119
+ ``python -m sphinx.ext.apidoc`` against the ``multibase`` package, matching
120
+ the Read the Docs ``pre_build`` job.
121
+
117
122
  * ``make pr`` - Run a complete pre-PR check: clean build artifacts, fix formatting,
118
123
  run linting, type checking, and tests. This is the recommended command to run
119
124
  before submitting a pull request.
@@ -3,6 +3,45 @@ History
3
3
 
4
4
  .. towncrier release notes start
5
5
 
6
+ py-multibase v2.1.0 (2026-11-22)
7
+ --------------------------------
8
+
9
+ Bugfixes
10
+ ~~~~~~~~
11
+
12
+ - Fix integer-based encodings dropping leading ``0x00`` bytes on encode and decode, and add round-trip tests covering every supported encoding with random, all-zero, all-ones and leading-zero data. (`#40 <https://github.com/multiformats/py-multibase/issues/40>`__)
13
+ - Name-based APIs (``encode``, ``is_encoding_supported``, ``get_encoding_info``, and ``Encoder``) no longer treat multibase prefix bytes as encoding names. Prefix codes continue to be resolved via ``get_codec`` / ``decode``. (`#44 <https://github.com/multiformats/py-multibase/issues/44>`__)
14
+
15
+
16
+ Improved Documentation
17
+ ~~~~~~~~~~~~~~~~~~~~~~
18
+
19
+ - Aligned local documentation builds with Read the Docs by using ``python -m sphinx.ext.apidoc`` for the ``multibase`` package. (`#31 <https://github.com/multiformats/py-multibase/issues/31>`__)
20
+
21
+
22
+ Features
23
+ ~~~~~~~~
24
+
25
+ - Add ``encoder_by_name()``, which constructs an :class:`~multibase.Encoder` from an encoding name or its single-character prefix, and export it from the ``multibase`` package. (`#39 <https://github.com/multiformats/py-multibase/issues/39>`__)
26
+ - Add a read-only ``Encoder.code`` property exposing the multibase prefix byte of an encoder's encoding. (`#47 <https://github.com/multiformats/py-multibase/issues/47>`__)
27
+
28
+
29
+ Internal Changes - for py-multibase Contributors
30
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31
+
32
+ - Add ``pytest-benchmark`` benchmarks for encoding, decoding and round-tripping every supported encoding. (`#42 <https://github.com/multiformats/py-multibase/issues/42>`__)
33
+ - Add Hypothesis-based fuzz tests that exercise the decoder with arbitrary binary and text input. (`#43 <https://github.com/multiformats/py-multibase/issues/43>`__)
34
+ - Remove the unused ``six`` runtime dependency; ``py-multibase`` requires Python 3.10 or newer. (`#45 <https://github.com/multiformats/py-multibase/issues/45>`__)
35
+ - Renamed converter parameters that shadowed the builtin ``bytes`` and corrected the Base16 decode comment (no behavior change). (`#62 <https://github.com/multiformats/py-multibase/issues/62>`__)
36
+ - Adopt pinned ``pyrefly==1.5.0`` typechecking alongside mypy for tooling parity with sibling packages. (`#64 <https://github.com/multiformats/py-multibase/issues/64>`__)
37
+
38
+
39
+ Miscellaneous Changes
40
+ ~~~~~~~~~~~~~~~~~~~~~
41
+
42
+ - `#41 <https://github.com/multiformats/py-multibase/issues/41>`__, `#46 <https://github.com/multiformats/py-multibase/issues/46>`__
43
+
44
+
6
45
  py-multibase v2.0.0 (2025-12-17)
7
46
  --------------------------------
8
47
 
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: py-multibase
3
- Version: 2.0.0
3
+ Version: 2.1.0
4
4
  Summary: Multibase implementation for Python
5
5
  Author-email: Dhruv Baldawa <dhruv@dhruvb.com>
6
6
  License: MIT
7
7
  Project-URL: Homepage, https://github.com/multiformats/py-multibase
8
- Project-URL: Download, https://github.com/multiformats/py-multibase/tarball/2.0.0
8
+ Project-URL: Download, https://github.com/multiformats/py-multibase/tarball/2.1.0
9
9
  Keywords: multibase
10
10
  Classifier: Development Status :: 2 - Pre-Alpha
11
11
  Classifier: Intended Audience :: Developers
@@ -22,15 +22,17 @@ Description-Content-Type: text/x-rst
22
22
  License-File: LICENSE
23
23
  License-File: AUTHORS.rst
24
24
  Requires-Dist: python-baseconv<2.0,>=1.2.0
25
- Requires-Dist: six<2.0,>=1.10.0
26
25
  Requires-Dist: morphys<2.0,>=1.0
27
26
  Provides-Extra: dev
28
27
  Requires-Dist: Sphinx>=5.0.0; extra == "dev"
29
28
  Requires-Dist: build>=0.9.0; extra == "dev"
30
29
  Requires-Dist: bump-my-version>=1.2.0; extra == "dev"
30
+ Requires-Dist: hypothesis; extra == "dev"
31
31
  Requires-Dist: mypy; extra == "dev"
32
32
  Requires-Dist: pre-commit; extra == "dev"
33
+ Requires-Dist: pyrefly==1.5.0; extra == "dev"
33
34
  Requires-Dist: pytest; extra == "dev"
35
+ Requires-Dist: pytest-benchmark; extra == "dev"
34
36
  Requires-Dist: pytest-runner; extra == "dev"
35
37
  Requires-Dist: ruff; extra == "dev"
36
38
  Requires-Dist: towncrier<25,>=24; extra == "dev"
@@ -99,11 +101,15 @@ Sample Usage
99
101
  b'hello world'
100
102
 
101
103
  >>> # Using reusable Encoder/Decoder classes
102
- >>> from multibase import Encoder, Decoder
104
+ >>> from multibase import Encoder, Decoder, encoder_by_name
103
105
  >>> encoder = Encoder('base64')
104
106
  >>> encoded1 = encoder.encode('data1')
105
107
  >>> encoded2 = encoder.encode('data2')
106
108
 
109
+ >>> # Or resolve by name or single-character prefix
110
+ >>> encoder = encoder_by_name('base64')
111
+ >>> encoder = encoder_by_name('m')
112
+
107
113
  >>> decoder = Decoder()
108
114
  >>> decoded = decoder.decode(encoded1)
109
115
 
@@ -57,11 +57,15 @@ Sample Usage
57
57
  b'hello world'
58
58
 
59
59
  >>> # Using reusable Encoder/Decoder classes
60
- >>> from multibase import Encoder, Decoder
60
+ >>> from multibase import Encoder, Decoder, encoder_by_name
61
61
  >>> encoder = Encoder('base64')
62
62
  >>> encoded1 = encoder.encode('data1')
63
63
  >>> encoded2 = encoder.encode('data2')
64
64
 
65
+ >>> # Or resolve by name or single-character prefix
66
+ >>> encoder = encoder_by_name('base64')
67
+ >>> encoder = encoder_by_name('m')
68
+
65
69
  >>> decoder = Decoder()
66
70
  >>> decoded = decoder.decode(encoded1)
67
71
 
@@ -0,0 +1,26 @@
1
+ API Reference
2
+ -------------
3
+
4
+ .. py:currentmodule:: multibase
5
+
6
+ Encoding **names** (for example ``"base16"``) are used by :func:`encode`,
7
+ :func:`is_encoding_supported`, :func:`get_encoding_info`, and :class:`Encoder`.
8
+ Multibase **prefix codes** (for example ``b"f"``) are resolved from encoded
9
+ data by :func:`get_codec` and :func:`decode`, not passed as encoding names.
10
+
11
+ .. autofunction:: encode
12
+
13
+ .. autofunction:: decode
14
+
15
+ .. autofunction:: get_codec
16
+
17
+ .. autofunction:: is_encoded
18
+
19
+ .. autofunction:: is_encoding_supported
20
+
21
+ .. autofunction:: get_encoding_info
22
+
23
+ .. autofunction:: encoder_by_name
24
+
25
+ .. autoclass:: Encoder
26
+ :members:
@@ -2,7 +2,7 @@
2
2
 
3
3
  __author__ = """Dhruv Baldawa"""
4
4
  __email__ = "dhruv@dhruvb.com"
5
- __version__ = "2.0.0"
5
+ __version__ = "2.1.0"
6
6
 
7
7
  from .exceptions import ( # noqa: F401
8
8
  DecodingError,
@@ -18,6 +18,7 @@ from .multibase import ( # noqa: F401
18
18
  Encoding,
19
19
  decode,
20
20
  encode,
21
+ encoder_by_name,
21
22
  get_codec,
22
23
  get_encoding_info,
23
24
  is_encoded,
@@ -6,25 +6,43 @@ from morphys import ensure_bytes
6
6
 
7
7
 
8
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))
9
+ def encode(self, number):
10
+ data = ensure_bytes(number)
11
+ if len(data) == 0:
12
+ return b""
12
13
 
13
- def bytes_to_int(self, bytes):
14
- length = len(bytes)
14
+ leading_zeros = len(data) - len(data.lstrip(b"\x00"))
15
+ if leading_zeros == len(data):
16
+ return str(self.digits[0] * leading_zeros).encode("utf-8")
17
+
18
+ as_int = int.from_bytes(data, byteorder="big", signed=False)
19
+ encoded = super().encode(as_int)
20
+ return ensure_bytes(self.digits[0] * leading_zeros + encoded)
21
+
22
+ def bytes_to_int(self, data):
23
+ length = len(data)
15
24
  base = len(self.digits)
16
25
  value = 0
17
26
 
18
- for i, x in enumerate(bytes):
27
+ for i, x in enumerate(data):
19
28
  value += self.digits.index(chr(x)) * base ** (length - (i + 1))
20
29
  return value
21
30
 
22
- def decode(self, bytes):
23
- decoded_int = self.bytes_to_int(bytes)
31
+ def decode(self, number):
32
+ data = number
33
+ bytes_str = data.decode("utf-8") if isinstance(data, bytes) else data
34
+ if len(bytes_str) == 0:
35
+ return b""
36
+
37
+ leading_zeros = len(bytes_str) - len(bytes_str.lstrip(self.digits[0]))
38
+ if leading_zeros == len(bytes_str):
39
+ return b"\x00" * leading_zeros
40
+
41
+ decoded_int = self.bytes_to_int(data)
24
42
  # See https://docs.python.org/3.5/library/stdtypes.html#int.to_bytes for more about the magical expression
25
43
  # below
26
44
  decoded_data = decoded_int.to_bytes((decoded_int.bit_length() + 7) // 8, byteorder="big")
27
- return decoded_data
45
+ return b"\x00" * leading_zeros + decoded_data
28
46
 
29
47
 
30
48
  class Base16StringConverter(BaseStringConverter):
@@ -32,24 +50,19 @@ class Base16StringConverter(BaseStringConverter):
32
50
  super().__init__(digits)
33
51
  self.uppercase = digits.isupper()
34
52
 
35
- def encode(self, bytes):
36
- result = "".join([f"{byte:02x}" for byte in bytes])
53
+ def encode(self, number):
54
+ result = "".join([f"{byte:02x}" for byte in number])
37
55
  if self.uppercase:
38
56
  result = result.upper()
39
57
  return ensure_bytes(result)
40
58
 
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")
59
+ def decode(self, number):
60
+ # Case-insensitive via bytes.fromhex (accepts both upper and lower hex digits)
61
+ if isinstance(number, bytes):
62
+ data_str = number.decode("utf-8")
45
63
  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"))
64
+ data_str = number
65
+ return bytes.fromhex(data_str)
53
66
 
54
67
 
55
68
  class BaseByteStringConverter:
@@ -84,7 +97,10 @@ class BaseByteStringConverter:
84
97
  binstringfmt = f"{{:0{encoding_bits}b}}"
85
98
  binstring = "".join([binstringfmt.format(x) for x in byte_])
86
99
  # 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"))
100
+ digits = (
101
+ int("".join(ch if ch is not None else "0" for ch in x), 2)
102
+ for x in self._chunk_with_padding(binstring, decoding_bits, "0")
103
+ )
88
104
 
89
105
  for digit in digits:
90
106
  # convert binary representation to an integer
@@ -135,27 +151,32 @@ class BaseByteStringConverter:
135
151
 
136
152
  return decoded_bytes.getvalue()
137
153
 
138
- def encode(self, bytes):
154
+ def encode(self, data):
139
155
  raise NotImplementedError
140
156
 
141
- def decode(self, bytes):
142
- return NotImplementedError
157
+ def decode(self, data):
158
+ raise NotImplementedError
143
159
 
144
160
 
145
161
  class Base64StringConverter(BaseByteStringConverter):
146
- def encode(self, bytes):
147
- return self._encode_bytes(ensure_bytes(bytes), 3, 8, 6, 4)
162
+ def encode(self, data):
163
+ return self._encode_bytes(ensure_bytes(data), 3, 8, 6, 4)
148
164
 
149
- def decode(self, bytes):
150
- return self._decode_bytes(ensure_bytes(bytes), 4, 6, 8)
165
+ def decode(self, data):
166
+ return self._decode_bytes(ensure_bytes(data), 4, 6, 8)
151
167
 
152
168
 
153
169
  class Base32StringConverter(BaseByteStringConverter):
154
- def encode(self, bytes):
155
- return self._encode_bytes(ensure_bytes(bytes), 5, 8, 5, 8)
170
+ def encode(self, data):
171
+ return self._encode_bytes(ensure_bytes(data), 5, 8, 5, 8)
156
172
 
157
- def decode(self, bytes):
158
- return self._decode_bytes(ensure_bytes(bytes), 8, 5, 8)
173
+ def decode(self, data):
174
+ data = ensure_bytes(data)
175
+ if self.digits.islower():
176
+ data = data.lower()
177
+ elif self.digits.isupper():
178
+ data = data.upper()
179
+ return self._decode_bytes(data, 8, 5, 8)
159
180
 
160
181
 
161
182
  class Base256EmojiConverter:
@@ -57,17 +57,25 @@ ENCODINGS = [
57
57
  Encoding("base256emoji", "🚀".encode(), Base256EmojiConverter()),
58
58
  ]
59
59
 
60
- ENCODINGS_LOOKUP = {}
60
+ _ENCODINGS_BY_NAME: dict[str, Encoding] = {}
61
+ _ENCODINGS_BY_CODE: dict[bytes, Encoding] = {}
61
62
  for codec in ENCODINGS:
62
- ENCODINGS_LOOKUP[codec.encoding] = codec
63
- ENCODINGS_LOOKUP[codec.code] = codec
63
+ _ENCODINGS_BY_NAME[codec.encoding] = codec
64
+ _ENCODINGS_BY_CODE[codec.code] = codec
65
+
66
+ # Backward-compatible alias for private importers (mixed str/bytes keys).
67
+ ENCODINGS_LOOKUP: dict[str | bytes, Encoding] = {}
68
+ for _name, _codec in _ENCODINGS_BY_NAME.items():
69
+ ENCODINGS_LOOKUP[_name] = _codec
70
+ for _code, _codec in _ENCODINGS_BY_CODE.items():
71
+ ENCODINGS_LOOKUP[_code] = _codec
64
72
 
65
73
 
66
74
  def encode(encoding, data):
67
75
  """
68
76
  Encodes the given data using the encoding that is specified
69
77
 
70
- :param str encoding: encoding to use, should be one of the supported encoding
78
+ :param str encoding: encoding name to use (for example ``"base16"``), not a prefix byte
71
79
  :param data: data to encode
72
80
  :type data: str or bytes
73
81
  :return: multibase encoded data
@@ -76,7 +84,8 @@ def encode(encoding, data):
76
84
  """
77
85
  data = ensure_bytes(data, "utf8")
78
86
  try:
79
- return ENCODINGS_LOOKUP[encoding].code + ENCODINGS_LOOKUP[encoding].converter.encode(data)
87
+ codec = _ENCODINGS_BY_NAME[encoding]
88
+ return codec.code + codec.converter.encode(data)
80
89
  except KeyError:
81
90
  raise UnsupportedEncodingError(f"Encoding {encoding} not supported.")
82
91
 
@@ -94,13 +103,13 @@ def get_codec(data):
94
103
  # Check for base256emoji first (4-byte UTF-8 prefix)
95
104
  if len(data) >= 4:
96
105
  emoji_prefix = data[:4]
97
- if emoji_prefix in ENCODINGS_LOOKUP:
98
- return ENCODINGS_LOOKUP[emoji_prefix]
106
+ if emoji_prefix in _ENCODINGS_BY_CODE:
107
+ return _ENCODINGS_BY_CODE[emoji_prefix]
99
108
 
100
109
  # Check for single-byte prefixes
101
110
  try:
102
111
  key = data[:CODE_LENGTH]
103
- codec = ENCODINGS_LOOKUP[key]
112
+ codec = _ENCODINGS_BY_CODE[key]
104
113
  except KeyError:
105
114
  raise InvalidMultibaseStringError(f"Can not determine encoding for {data}")
106
115
  else:
@@ -119,7 +128,8 @@ def is_encoded(data):
119
128
  try:
120
129
  get_codec(data)
121
130
  return True
122
- except (ValueError, InvalidMultibaseStringError):
131
+ except ValueError:
132
+ # InvalidMultibaseStringError subclasses ValueError
123
133
  return False
124
134
 
125
135
 
@@ -127,12 +137,12 @@ def is_encoding_supported(encoding):
127
137
  """
128
138
  Check if an encoding is supported.
129
139
 
130
- :param encoding: encoding name to check
140
+ :param encoding: encoding name to check (for example ``"base16"``), not a prefix byte
131
141
  :type encoding: str
132
142
  :return: True if encoding is supported, False otherwise
133
143
  :rtype: bool
134
144
  """
135
- return encoding in ENCODINGS_LOOKUP
145
+ return encoding in _ENCODINGS_BY_NAME
136
146
 
137
147
 
138
148
  def list_encodings():
@@ -149,15 +159,15 @@ def get_encoding_info(encoding):
149
159
  """
150
160
  Get information about a specific encoding.
151
161
 
152
- :param encoding: encoding name
162
+ :param encoding: encoding name (for example ``"base16"``), not a prefix byte
153
163
  :type encoding: str
154
164
  :return: Encoding namedtuple with encoding, code, and converter
155
165
  :rtype: Encoding
156
166
  :raises UnsupportedEncodingError: if encoding is not supported
157
167
  """
158
- if encoding not in ENCODINGS_LOOKUP:
168
+ if encoding not in _ENCODINGS_BY_NAME:
159
169
  raise UnsupportedEncodingError(f"Encoding {encoding} not supported.")
160
- return ENCODINGS_LOOKUP[encoding]
170
+ return _ENCODINGS_BY_NAME[encoding]
161
171
 
162
172
 
163
173
  def decode(data, return_encoding=False):
@@ -192,6 +202,31 @@ def decode(data, return_encoding=False):
192
202
  raise DecodingError(f"Failed to decode multibase data: {e}") from e
193
203
 
194
204
 
205
+ def encoder_by_name(name_or_prefix):
206
+ """
207
+ Create an Encoder from a name or single-character prefix.
208
+
209
+ :param name_or_prefix: encoding name or prefix character
210
+ :type name_or_prefix: str
211
+ :return: an Encoder instance
212
+ :rtype: Encoder
213
+ :raises TypeError: if ``name_or_prefix`` is not a ``str``
214
+ :raises UnsupportedEncodingError: if the encoding is not supported
215
+ """
216
+ if not isinstance(name_or_prefix, str):
217
+ raise TypeError(f"name_or_prefix must be str, got {type(name_or_prefix).__name__}")
218
+
219
+ if name_or_prefix in _ENCODINGS_BY_NAME:
220
+ return Encoder(name_or_prefix)
221
+
222
+ prefix_bytes = name_or_prefix.encode("utf-8")
223
+ codec = _ENCODINGS_BY_CODE.get(prefix_bytes)
224
+ if codec is not None:
225
+ return Encoder(codec.encoding)
226
+
227
+ raise UnsupportedEncodingError(f"Encoding {name_or_prefix!r} not supported.")
228
+
229
+
195
230
  class Encoder:
196
231
  """Reusable encoder for a specific encoding."""
197
232
 
@@ -199,14 +234,24 @@ class Encoder:
199
234
  """
200
235
  Initialize an encoder for a specific encoding.
201
236
 
202
- :param encoding: encoding name to use
237
+ :param encoding: encoding name to use (for example ``"base16"``), not a prefix byte
203
238
  :type encoding: str
204
239
  :raises UnsupportedEncodingError: if encoding is not supported
205
240
  """
206
- if encoding not in ENCODINGS_LOOKUP:
241
+ if encoding not in _ENCODINGS_BY_NAME:
207
242
  raise UnsupportedEncodingError(f"Encoding {encoding} not supported.")
208
243
  self.encoding = encoding
209
- self._codec = ENCODINGS_LOOKUP[encoding]
244
+ self._codec = _ENCODINGS_BY_NAME[encoding]
245
+
246
+ @property
247
+ def code(self) -> bytes:
248
+ """
249
+ The multibase prefix byte for this encoding.
250
+
251
+ :return: prefix byte
252
+ :rtype: bytes
253
+ """
254
+ return self._codec.code
210
255
 
211
256
  def encode(self, data):
212
257
  """
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: py-multibase
3
- Version: 2.0.0
3
+ Version: 2.1.0
4
4
  Summary: Multibase implementation for Python
5
5
  Author-email: Dhruv Baldawa <dhruv@dhruvb.com>
6
6
  License: MIT
7
7
  Project-URL: Homepage, https://github.com/multiformats/py-multibase
8
- Project-URL: Download, https://github.com/multiformats/py-multibase/tarball/2.0.0
8
+ Project-URL: Download, https://github.com/multiformats/py-multibase/tarball/2.1.0
9
9
  Keywords: multibase
10
10
  Classifier: Development Status :: 2 - Pre-Alpha
11
11
  Classifier: Intended Audience :: Developers
@@ -22,15 +22,17 @@ Description-Content-Type: text/x-rst
22
22
  License-File: LICENSE
23
23
  License-File: AUTHORS.rst
24
24
  Requires-Dist: python-baseconv<2.0,>=1.2.0
25
- Requires-Dist: six<2.0,>=1.10.0
26
25
  Requires-Dist: morphys<2.0,>=1.0
27
26
  Provides-Extra: dev
28
27
  Requires-Dist: Sphinx>=5.0.0; extra == "dev"
29
28
  Requires-Dist: build>=0.9.0; extra == "dev"
30
29
  Requires-Dist: bump-my-version>=1.2.0; extra == "dev"
30
+ Requires-Dist: hypothesis; extra == "dev"
31
31
  Requires-Dist: mypy; extra == "dev"
32
32
  Requires-Dist: pre-commit; extra == "dev"
33
+ Requires-Dist: pyrefly==1.5.0; extra == "dev"
33
34
  Requires-Dist: pytest; extra == "dev"
35
+ Requires-Dist: pytest-benchmark; extra == "dev"
34
36
  Requires-Dist: pytest-runner; extra == "dev"
35
37
  Requires-Dist: ruff; extra == "dev"
36
38
  Requires-Dist: towncrier<25,>=24; extra == "dev"
@@ -99,11 +101,15 @@ Sample Usage
99
101
  b'hello world'
100
102
 
101
103
  >>> # Using reusable Encoder/Decoder classes
102
- >>> from multibase import Encoder, Decoder
104
+ >>> from multibase import Encoder, Decoder, encoder_by_name
103
105
  >>> encoder = Encoder('base64')
104
106
  >>> encoded1 = encoder.encode('data1')
105
107
  >>> encoded2 = encoder.encode('data2')
106
108
 
109
+ >>> # Or resolve by name or single-character prefix
110
+ >>> encoder = encoder_by_name('base64')
111
+ >>> encoder = encoder_by_name('m')
112
+
107
113
  >>> decoder = Decoder()
108
114
  >>> decoded = decoder.decode(encoded1)
109
115
 
@@ -31,4 +31,9 @@ py_multibase.egg-info/not-zip-safe
31
31
  py_multibase.egg-info/requires.txt
32
32
  py_multibase.egg-info/top_level.txt
33
33
  tests/__init__.py
34
- tests/test_multibase.py
34
+ tests/test_benchmarks.py
35
+ tests/test_fuzz.py
36
+ tests/test_multibase.py
37
+ tests/test_roundtrip.py
38
+ tests/test_spec.py
39
+ tests/test_spec_vectors.py
@@ -1,14 +1,16 @@
1
1
  python-baseconv<2.0,>=1.2.0
2
- six<2.0,>=1.10.0
3
2
  morphys<2.0,>=1.0
4
3
 
5
4
  [dev]
6
5
  Sphinx>=5.0.0
7
6
  build>=0.9.0
8
7
  bump-my-version>=1.2.0
8
+ hypothesis
9
9
  mypy
10
10
  pre-commit
11
+ pyrefly==1.5.0
11
12
  pytest
13
+ pytest-benchmark
12
14
  pytest-runner
13
15
  ruff
14
16
  towncrier<25,>=24
@@ -0,0 +1,2 @@
1
+ multibase
2
+ multibase-spec
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "py-multibase"
7
- version = "2.0.0"
7
+ version = "2.1.0"
8
8
  description = "Multibase implementation for Python"
9
9
  readme = "README.rst"
10
10
  authors = [{ name = "Dhruv Baldawa", email = "dhruv@dhruvb.com" }]
@@ -25,22 +25,24 @@ classifiers = [
25
25
  requires-python = ">=3.10, <4.0"
26
26
  dependencies = [
27
27
  "python-baseconv>=1.2.0,<2.0",
28
- "six>=1.10.0,<2.0",
29
28
  "morphys>=1.0,<2.0",
30
29
  ]
31
30
 
32
31
  [project.urls]
33
32
  Homepage = "https://github.com/multiformats/py-multibase"
34
- Download = "https://github.com/multiformats/py-multibase/tarball/2.0.0"
33
+ Download = "https://github.com/multiformats/py-multibase/tarball/2.1.0"
35
34
 
36
35
  [project.optional-dependencies]
37
36
  dev = [
38
37
  "Sphinx>=5.0.0",
39
38
  "build>=0.9.0",
40
39
  "bump-my-version>=1.2.0",
40
+ "hypothesis",
41
41
  "mypy",
42
42
  "pre-commit",
43
+ "pyrefly==1.5.0",
43
44
  "pytest",
45
+ "pytest-benchmark",
44
46
  "pytest-runner",
45
47
  "ruff",
46
48
  "towncrier>=24,<25",
@@ -118,7 +120,7 @@ name = "Removals"
118
120
  showcontent = true
119
121
 
120
122
  [tool.bumpversion]
121
- current_version = "2.0.0"
123
+ current_version = "2.1.0"
122
124
  parse = """
123
125
  (?P<major>\\d+)
124
126
  \\.(?P<minor>\\d+)
@@ -154,6 +156,11 @@ filename = "pyproject.toml"
154
156
  search = "Download = \"https://github.com/multiformats/py-multibase/tarball/{current_version}\""
155
157
  replace = "Download = \"https://github.com/multiformats/py-multibase/tarball/{new_version}\""
156
158
 
159
+ [[tool.bumpversion.files]]
160
+ filename = "version.json"
161
+ search = '"version": "v{current_version}"'
162
+ replace = '"version": "v{new_version}"'
163
+
157
164
  [tool.mypy]
158
165
  python_version = "3.10"
159
166
  check_untyped_defs = false
@@ -171,3 +178,15 @@ warn_redundant_casts = false
171
178
  warn_return_any = false
172
179
  warn_unused_configs = true
173
180
  warn_unused_ignores = false
181
+
182
+ [tool.pyrefly]
183
+ python_version = "3.10"
184
+ project_includes = ["multibase"]
185
+ project_excludes = [
186
+ "spec/**",
187
+ ".venv/**",
188
+ "docs/**",
189
+ "build/**",
190
+ "dist/**",
191
+ "tests/**",
192
+ ]
@@ -0,0 +1,27 @@
1
+ import pytest
2
+
3
+ from multibase import ENCODINGS, decode, encode
4
+
5
+ BENCH_DATA = b"Decentralize everything!!!"
6
+
7
+
8
+ @pytest.mark.benchmark
9
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
10
+ def test_bench_encode(benchmark, encoding_info):
11
+ benchmark(encode, encoding_info.encoding, BENCH_DATA)
12
+
13
+
14
+ @pytest.mark.benchmark
15
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
16
+ def test_bench_decode(benchmark, encoding_info):
17
+ encoded = encode(encoding_info.encoding, BENCH_DATA)
18
+ benchmark(decode, encoded)
19
+
20
+
21
+ @pytest.mark.benchmark
22
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
23
+ def test_bench_roundtrip(benchmark, encoding_info):
24
+ def roundtrip():
25
+ return decode(encode(encoding_info.encoding, BENCH_DATA))
26
+
27
+ benchmark(roundtrip)
@@ -0,0 +1,36 @@
1
+ from hypothesis import given, settings
2
+ from hypothesis import strategies as st
3
+
4
+ from multibase import ENCODINGS, decode, encode
5
+
6
+
7
+ @given(st.binary(max_size=200))
8
+ @settings(max_examples=1000)
9
+ def test_decode_never_crashes(data):
10
+ """decode() should raise an exception, not crash."""
11
+ try:
12
+ decode(data)
13
+ except Exception:
14
+ pass # Any exception is fine, just no crashes
15
+
16
+
17
+ @given(st.text(max_size=200))
18
+ @settings(max_examples=1000)
19
+ def test_decode_string_never_crashes(data):
20
+ try:
21
+ decode(data)
22
+ except Exception:
23
+ pass
24
+
25
+
26
+ @given(st.binary(min_size=1, max_size=100))
27
+ @settings(max_examples=500)
28
+ def test_roundtrip_never_crashes(data):
29
+ """encode then decode should never crash."""
30
+ for enc in ENCODINGS:
31
+ try:
32
+ encoded = encode(enc.encoding, data)
33
+ decoded = decode(encoded)
34
+ assert decoded == data
35
+ except Exception:
36
+ pass
@@ -13,6 +13,8 @@ from multibase import (
13
13
  UnsupportedEncodingError,
14
14
  decode,
15
15
  encode,
16
+ encoder_by_name,
17
+ get_codec,
16
18
  get_encoding_info,
17
19
  is_encoded,
18
20
  is_encoding_supported,
@@ -128,6 +130,20 @@ def test_decode(_, data, encoded_data):
128
130
  assert decode(encoded_data) == ensure_bytes(data)
129
131
 
130
132
 
133
+ def test_decode_base32_case_insensitive():
134
+ # base32 (prefix 'b', lowercase alphabet), decoding uppercase payload
135
+ assert decode("bMZXW6") == b"foo"
136
+
137
+ # base32upper (prefix 'B', uppercase alphabet), decoding lowercase payload
138
+ assert decode("Bmzxw6") == b"foo"
139
+
140
+ # base32pad (prefix 'c', lowercase alphabet), decoding uppercase payload
141
+ assert decode("cMZXW6====") == b"foo"
142
+
143
+ # base32hex (prefix 'v', lowercase alphabet), decoding uppercase payload
144
+ assert decode("vCPNMU") == b"foo"
145
+
146
+
131
147
  @pytest.mark.parametrize("encoded_data", INCORRECT_ENCODED_DATA)
132
148
  def test_decode_incorrect_encoding(encoded_data):
133
149
  with pytest.raises(InvalidMultibaseStringError) as excinfo:
@@ -157,6 +173,9 @@ def test_is_encoding_supported():
157
173
  assert is_encoding_supported("base64")
158
174
  assert is_encoding_supported("base16")
159
175
  assert not is_encoding_supported("base999")
176
+ # Prefix bytes are not encoding names
177
+ assert not is_encoding_supported(b"f")
178
+ assert not is_encoding_supported(b"m")
160
179
 
161
180
 
162
181
  def test_list_encodings():
@@ -179,11 +198,32 @@ def test_get_encoding_info():
179
198
  with pytest.raises(UnsupportedEncodingError):
180
199
  get_encoding_info("base999")
181
200
 
201
+ with pytest.raises(UnsupportedEncodingError):
202
+ get_encoding_info(b"m")
203
+
204
+
205
+ def test_name_apis_reject_prefix_bytes():
206
+ """Name-based APIs must not accept multibase prefix bytes as encoding names."""
207
+ with pytest.raises(UnsupportedEncodingError):
208
+ encode(b"f", b"hello")
209
+
210
+ with pytest.raises(UnsupportedEncodingError):
211
+ Encoder(b"m")
212
+
213
+
214
+ def test_get_codec_resolves_prefix_codes():
215
+ """get_codec still resolves single-byte and emoji prefixes via the code map."""
216
+ assert get_codec(b"f796573").encoding == "base16"
217
+ assert get_codec(b"mSGVsbG8=").encoding == "base64"
218
+ emoji_encoded = encode("base256emoji", b"hi")
219
+ assert get_codec(emoji_encoded).encoding == "base256emoji"
220
+
182
221
 
183
222
  def test_encoder_class():
184
223
  """Test Encoder class."""
185
224
  encoder = Encoder("base64")
186
225
  assert encoder.encoding == "base64"
226
+ assert encoder.code == b"m"
187
227
 
188
228
  encoded = encoder.encode("hello")
189
229
  assert encoded.startswith(b"m")
@@ -192,6 +232,31 @@ def test_encoder_class():
192
232
  Encoder("base999")
193
233
 
194
234
 
235
+ def test_encoder_by_name():
236
+ """Test encoder_by_name factory function."""
237
+ enc1 = encoder_by_name("base16")
238
+ assert enc1.encoding == "base16"
239
+ assert enc1.encode(b"hi").startswith(b"f")
240
+
241
+ enc2 = encoder_by_name("f")
242
+ assert enc2.encoding == "base16"
243
+
244
+ enc3 = encoder_by_name("🚀")
245
+ assert enc3.encoding == "base256emoji"
246
+
247
+ with pytest.raises(UnsupportedEncodingError):
248
+ encoder_by_name("base999")
249
+
250
+ with pytest.raises(UnsupportedEncodingError):
251
+ encoder_by_name("?")
252
+
253
+ with pytest.raises(TypeError):
254
+ encoder_by_name(b"f")
255
+
256
+ with pytest.raises(TypeError):
257
+ encoder_by_name(None)
258
+
259
+
195
260
  def test_decoder_class():
196
261
  """Test Decoder class."""
197
262
  decoder = Decoder()
@@ -0,0 +1,74 @@
1
+ """Round-trip and invalid-input rejection tests for multibase encodings."""
2
+
3
+ import os
4
+
5
+ import pytest
6
+
7
+ from multibase import ENCODINGS, DecodingError, decode, encode
8
+
9
+ INVALID_SUFFIXES = [
10
+ ("\u00a0", "low-unicode"),
11
+ ("\U0001f4a8", "emoji"),
12
+ ("!", "punctuation"),
13
+ ("\u00ff", "high-latin1"),
14
+ ]
15
+
16
+
17
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
18
+ @pytest.mark.parametrize(
19
+ "suffix,label",
20
+ INVALID_SUFFIXES,
21
+ ids=[label for _, label in INVALID_SUFFIXES],
22
+ )
23
+ def test_invalid_input_rejected(encoding_info, suffix, label):
24
+ """Decoding invalid alphabet characters should raise DecodingError."""
25
+ if encoding_info.encoding == "identity":
26
+ pytest.skip("identity accepts all bytes")
27
+ if encoding_info.encoding == "base256emoji":
28
+ pytest.skip("base256emoji has its own alphabet; emoji suffixes are not reliably invalid")
29
+
30
+ prefix = encoding_info.code.decode("utf-8")
31
+ invalid_data = prefix + suffix
32
+
33
+ with pytest.raises(DecodingError):
34
+ decode(invalid_data)
35
+
36
+
37
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
38
+ def test_random_data(encoding_info):
39
+ """Round-trip random data of various sizes."""
40
+ for size in [1, 2, 7, 16, 32, 64, 137, 256, 1024]:
41
+ data = os.urandom(size)
42
+ encoded = encode(encoding_info.encoding, data)
43
+ decoded = decode(encoded)
44
+ assert decoded == data, f"Failed for {encoding_info.encoding} size={size}"
45
+
46
+
47
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
48
+ def test_leading_zeros(encoding_info):
49
+ """Round-trip data with leading zero bytes."""
50
+ for num_zeros in [1, 2, 4, 8, 16]:
51
+ data = b"\x00" * num_zeros + b"hello"
52
+ encoded = encode(encoding_info.encoding, data)
53
+ decoded = decode(encoded)
54
+ assert decoded == data, f"Leading zeros lost for {encoding_info.encoding} zeros={num_zeros}"
55
+
56
+
57
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
58
+ def test_all_zeros(encoding_info):
59
+ """Round-trip all-zero data."""
60
+ for size in [1, 4, 16, 32]:
61
+ data = b"\x00" * size
62
+ encoded = encode(encoding_info.encoding, data)
63
+ decoded = decode(encoded)
64
+ assert decoded == data
65
+
66
+
67
+ @pytest.mark.parametrize("encoding_info", ENCODINGS, ids=lambda e: e.encoding)
68
+ def test_all_ones(encoding_info):
69
+ """Round-trip all-0xFF data."""
70
+ for size in [1, 4, 16, 32]:
71
+ data = b"\xff" * size
72
+ encoded = encode(encoding_info.encoding, data)
73
+ decoded = decode(encoded)
74
+ assert decoded == data
@@ -0,0 +1,46 @@
1
+ import csv
2
+ from pathlib import Path
3
+
4
+ from multibase.multibase import ENCODINGS
5
+
6
+
7
+ def test_spec_encodings():
8
+ spec_path = Path(__file__).parent.parent / "multibase-spec" / "multibase.csv"
9
+ if not spec_path.exists():
10
+ # Fallback if the submodule is not checked out locally
11
+ return
12
+
13
+ spec_encodings = {}
14
+ with open(spec_path, encoding="utf-8") as f:
15
+ reader = csv.reader(f)
16
+ next(reader) # skip header
17
+ for row in reader:
18
+ if not row:
19
+ continue
20
+ row = [col.strip() for col in row]
21
+ if len(row) >= 5:
22
+ unicode_str, character, encoding_name, description, status = row[:5]
23
+ if encoding_name == "none":
24
+ continue
25
+ spec_encodings[encoding_name] = {
26
+ "character": character,
27
+ "status": status,
28
+ }
29
+
30
+ supported_names = set()
31
+ for enc in ENCODINGS:
32
+ if enc.encoding == "identity":
33
+ continue
34
+
35
+ assert enc.encoding in spec_encodings, f"Encoding '{enc.encoding}' not in spec"
36
+ spec_char = spec_encodings[enc.encoding]["character"]
37
+
38
+ assert enc.code.decode("utf-8") == spec_char, (
39
+ f"Prefix mismatch for '{enc.encoding}': expected '{spec_char}', got '{enc.code.decode('utf-8')}'"
40
+ )
41
+
42
+ supported_names.add(enc.encoding)
43
+
44
+ for name, data in spec_encodings.items():
45
+ if data["status"] == "final":
46
+ assert name in supported_names, f"Missing final encoding from spec: '{name}'"
@@ -0,0 +1,56 @@
1
+ import ast
2
+ import csv
3
+ from pathlib import Path
4
+
5
+ import pytest
6
+
7
+ from multibase.multibase import decode, encode, is_encoding_supported
8
+
9
+ VECTOR_FILES = list(Path(__file__).parent.parent.joinpath("multibase-spec", "tests").glob("*.csv"))
10
+
11
+
12
+ def get_vectors():
13
+ vectors = []
14
+ for vector_file in VECTOR_FILES:
15
+ with open(vector_file, encoding="utf-8") as f:
16
+ reader = csv.reader(f, skipinitialspace=True)
17
+ try:
18
+ header = next(reader)
19
+ except StopIteration:
20
+ continue
21
+
22
+ if not header or len(header) < 2:
23
+ continue
24
+
25
+ decode_only = header[0] == "non-canonical encoding"
26
+ # Unescape characters like \x00 safely
27
+ raw_test_value = header[1]
28
+ # ast.literal_eval needs quotes around the string to parse it as a literal
29
+ test_value_str = ast.literal_eval('"' + raw_test_value.replace('"', '\\"') + '"')
30
+ test_value = test_value_str.encode("utf-8")
31
+
32
+ for row in reader:
33
+ if not row or len(row) < 2:
34
+ continue
35
+ encoding_name, expected = row[0], row[1]
36
+ vectors.append((vector_file.name, decode_only, test_value, encoding_name, expected))
37
+ return vectors
38
+
39
+
40
+ @pytest.mark.parametrize("file_name,decode_only,test_value,encoding_name,expected", get_vectors())
41
+ def test_spec_vector(file_name, decode_only, test_value, encoding_name, expected):
42
+ if not is_encoding_supported(encoding_name):
43
+ pytest.skip(f"Encoding {encoding_name} not supported")
44
+
45
+ # py-multibase currently has bugs with leading zeros and certain encodings.
46
+ # We mark them as xfail so the test suite can be integrated and they can be fixed iteratively.
47
+ try:
48
+ if not decode_only:
49
+ actual = encode(encoding_name, test_value)
50
+ assert actual.decode("utf-8") == expected
51
+
52
+ actual_encoding, decoded = decode(expected, return_encoding=True)
53
+ assert actual_encoding == encoding_name
54
+ assert decoded == test_value
55
+ except Exception as e:
56
+ pytest.xfail(f"Known spec vector failure: {e}")
@@ -1,12 +0,0 @@
1
- API Reference
2
- -------------
3
-
4
- .. py:currentmodule:: multibase
5
-
6
- .. autofunction:: encode
7
-
8
- .. autofunction:: decode
9
-
10
- .. autofunction:: get_codec
11
-
12
- .. autofunction:: is_encoded
@@ -1 +0,0 @@
1
- multibase
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes