multiaddr 0.2.0__tar.gz → 0.3.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 (64) hide show
  1. {multiaddr-0.2.0 → multiaddr-0.3.0}/CONTRIBUTING.rst +17 -0
  2. {multiaddr-0.2.0 → multiaddr-0.3.0}/HISTORY.rst +52 -0
  3. {multiaddr-0.2.0 → multiaddr-0.3.0}/PKG-INFO +125 -9
  4. {multiaddr-0.2.0 → multiaddr-0.3.0}/README.rst +117 -2
  5. multiaddr-0.3.0/multiaddr/__init__.py +108 -0
  6. multiaddr-0.3.0/multiaddr/cli.py +61 -0
  7. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/utf8.py +8 -3
  8. multiaddr-0.3.0/multiaddr/codecs/wg.py +88 -0
  9. multiaddr-0.3.0/multiaddr/filters.py +86 -0
  10. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/multiaddr.py +51 -7
  11. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/protocols.py +12 -3
  12. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/transforms.py +15 -35
  13. multiaddr-0.3.0/multiaddr/utils.py +313 -0
  14. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/PKG-INFO +125 -9
  15. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/SOURCES.txt +15 -1
  16. multiaddr-0.3.0/multiaddr.egg-info/entry_points.txt +2 -0
  17. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/requires.txt +6 -5
  18. {multiaddr-0.2.0 → multiaddr-0.3.0}/pyproject.toml +20 -8
  19. multiaddr-0.3.0/tests/test_benchmarks.py +41 -0
  20. multiaddr-0.3.0/tests/test_cli.py +59 -0
  21. multiaddr-0.3.0/tests/test_dial_args.py +27 -0
  22. multiaddr-0.3.0/tests/test_filters.py +55 -0
  23. multiaddr-0.3.0/tests/test_interface_multiaddrs.py +18 -0
  24. multiaddr-0.3.0/tests/test_ip_classification.py +65 -0
  25. {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_multiaddr.py +77 -4
  26. multiaddr-0.3.0/tests/test_net_addr.py +31 -0
  27. multiaddr-0.3.0/tests/test_package_exports.py +79 -0
  28. multiaddr-0.3.0/tests/test_protocol_codec_cache.py +18 -0
  29. {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_protocols.py +115 -1
  30. {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_transforms.py +29 -1
  31. multiaddr-0.3.0/tests/test_transforms_no_debug.py +11 -0
  32. multiaddr-0.2.0/multiaddr/__init__.py +0 -5
  33. multiaddr-0.2.0/multiaddr/utils.py +0 -119
  34. {multiaddr-0.2.0 → multiaddr-0.3.0}/AUTHORS +0 -0
  35. {multiaddr-0.2.0 → multiaddr-0.3.0}/LICENSE-APACHE2 +0 -0
  36. {multiaddr-0.2.0 → multiaddr-0.3.0}/LICENSE-MIT +0 -0
  37. {multiaddr-0.2.0 → multiaddr-0.3.0}/MANIFEST.in +0 -0
  38. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/__init__.py +0 -0
  39. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/certhash.py +0 -0
  40. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/cid.py +0 -0
  41. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/domain.py +0 -0
  42. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/fspath.py +0 -0
  43. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/garlic32.py +0 -0
  44. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/garlic64.py +0 -0
  45. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/http_path.py +0 -0
  46. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/ip4.py +0 -0
  47. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/ip6.py +0 -0
  48. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/ipcidr.py +0 -0
  49. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/memory.py +0 -0
  50. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/onion.py +0 -0
  51. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/onion3.py +0 -0
  52. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/uint16be.py +0 -0
  53. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/exceptions.py +0 -0
  54. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/__init__.py +0 -0
  55. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/base.py +0 -0
  56. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/dns.py +0 -0
  57. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/util.py +0 -0
  58. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/dependency_links.txt +0 -0
  59. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/not-zip-safe +0 -0
  60. {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/top_level.txt +0 -0
  61. {multiaddr-0.2.0 → multiaddr-0.3.0}/setup.cfg +0 -0
  62. {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/__init__.py +0 -0
  63. {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_resolvers.py +0 -0
  64. {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_thin_waist_addresses.py +0 -0
@@ -126,12 +126,29 @@ The project follows a py-libp2p-style development workflow:
126
126
 
127
127
  Use ``make pr`` to run the complete workflow.
128
128
 
129
+ Benchmarks
130
+ ----------
131
+
132
+ Performance benchmarks live in ``tests/test_benchmarks.py`` and are marked with
133
+ ``@pytest.mark.benchmark``. They are excluded from ``make test`` / default CI.
134
+ Run them locally with::
135
+
136
+ make bench
137
+ # or: pytest tests -m benchmark --benchmark-only
138
+
129
139
  Release Notes
130
140
  -------------
131
141
 
132
142
  When contributing, please add a newsfragment file in the ``newsfragments/`` directory.
133
143
  See ``newsfragments/README.md`` for details on the format and types.
134
144
 
145
+ Versioning
146
+ ----------
147
+
148
+ Package version is tracked in ``pyproject.toml``, ``multiaddr/__init__.py``, and
149
+ ``version.json`` (``{"version": "vX.Y.Z"}``, matching go-multiaddr). Bumping the
150
+ release with ``bump-my-version`` updates all three.
151
+
135
152
  Tips
136
153
  ----
137
154
 
@@ -3,6 +3,58 @@ History
3
3
 
4
4
  .. towncrier release notes start
5
5
 
6
+ py-multiaddr v0.3.0 (2026-11-22)
7
+ --------------------------------
8
+
9
+ Bugfixes
10
+ ~~~~~~~~
11
+
12
+ - Fixed an issue where decapsulate produced incorrect results for repeated protocols and substring collisions. (`#109 <https://github.com/multiformats/py-multiaddr/issues/109>`__)
13
+ - Add validation to Multiaddr initialization from bytes to reject invalid sequences immediately (`#110 <https://github.com/multiformats/py-multiaddr/issues/110>`__)
14
+ - Fix `string_iter` to correctly handle unix paths and other path protocols by consuming remaining components (`#112 <https://github.com/multiformats/py-multiaddr/issues/112>`__)
15
+ - Improve WireGuard codec error messages and align validation with the certhash pattern. (`#130 <https://github.com/multiformats/py-multiaddr/issues/130>`__)
16
+ - Fix ruff RUF043 in wg tests and Sphinx docstring warning so ``make pr`` / ``make docs`` pass. (`#145 <https://github.com/multiformats/py-multiaddr/issues/145>`__)
17
+ - Fix ``ip6zone`` being decoded as a value-less protocol: ``protocols()``, ``items()``, ``split()`` and binary parsing now handle zone identifiers of any length (e.g. ``en0``, ``wlan0``). (`#147 <https://github.com/multiformats/py-multiaddr/issues/147>`__)
18
+
19
+
20
+ Features
21
+ ~~~~~~~~
22
+
23
+ - Add draft WireGuard (``wg``) multiaddr protocol support. Public keys are
24
+ encoded as 32-byte Curve25519 values using multibase base64url (``u`` prefix)
25
+ in textual multiaddrs. Protocol code ``0x01C7`` is provisional until
26
+ registered in the upstream multicodec table. (`#107 <https://github.com/multiformats/py-multiaddr/issues/107>`__)
27
+ - Add ``dial_args()`` to convert thin-waist and unix multiaddrs to socket-ready strings. (`#114 <https://github.com/multiformats/py-multiaddr/issues/114>`__)
28
+ - Add ``from_net_addr()`` / ``to_net_addr()`` for socket address tuple conversion. (`#115 <https://github.com/multiformats/py-multiaddr/issues/115>`__)
29
+ - Add IP classification helpers on ``Multiaddr`` objects (``is_ip_loopback``, ``is_public_addr``, ``is_private_addr``, and related predicates). (`#116 <https://github.com/multiformats/py-multiaddr/issues/116>`__)
30
+ - Add ``Filters`` / ``Action`` for accept/deny IP filtering (go-multiaddr parity). (`#117 <https://github.com/multiformats/py-multiaddr/issues/117>`__)
31
+ - Add a command-line interface to decode multiaddrs into structured JSON. (`#119 <https://github.com/multiformats/py-multiaddr/issues/119>`__)
32
+ - Export commonly used symbols directly from ``multiaddr`` package root. (`#121 <https://github.com/multiformats/py-multiaddr/issues/121>`__)
33
+ - Add ``interface_multiaddrs()`` to return local interface addresses as Multiaddr objects. (`#122 <https://github.com/multiformats/py-multiaddr/issues/122>`__)
34
+
35
+
36
+ Internal Changes - for py-multiaddr Contributors
37
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
+
39
+ - Removed leftover debug logging from multiaddr string/bytes transforms. (`#111 <https://github.com/multiformats/py-multiaddr/issues/111>`__)
40
+ - Add ``version.json`` and keep it in sync via bump-my-version (go-multiaddr parity). (`#118 <https://github.com/multiformats/py-multiaddr/issues/118>`__)
41
+ - Add an opt-in pytest-benchmark suite for core multiaddr hot paths (``make bench``). (`#120 <https://github.com/multiformats/py-multiaddr/issues/120>`__)
42
+ - Fixed Windows CI so each tox matrix job runs only its intended environment instead of the full envlist. (`#134 <https://github.com/multiformats/py-multiaddr/issues/134>`__)
43
+ - Pin ``pyrefly==1.2.0`` in the ``dev`` extra so lint CI does not break when newer pyrefly releases add stricter rules. (`#149 <https://github.com/multiformats/py-multiaddr/issues/149>`__)
44
+
45
+
46
+ Miscellaneous Changes
47
+ ~~~~~~~~~~~~~~~~~~~~~
48
+
49
+ - `#151 <https://github.com/multiformats/py-multiaddr/issues/151>`__
50
+
51
+
52
+ Performance Improvements
53
+ ~~~~~~~~~~~~~~~~~~~~~~~~
54
+
55
+ - Cache the codec object on ``Protocol`` so ``size`` and ``path`` avoid repeated lookups. (`#113 <https://github.com/multiformats/py-multiaddr/issues/113>`__)
56
+
57
+
6
58
  py-multiaddr v0.2.0 (2026-03-17)
7
59
  --------------------------------
8
60
 
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: multiaddr
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Python implementation of jbenet's multiaddr
5
5
  Author-email: Steven Buss <steven.buss@gmail.com>
6
6
  Maintainer: acul71
7
7
  Maintainer-email: pacrob <pacrob@protonmail.com>, Manu Sheel Gupta <manu@seeta.in>
8
8
  License: MIT License
9
9
  Project-URL: Homepage, https://github.com/multiformats/py-multiaddr
10
- Project-URL: Download, https://github.com/multiformats/py-multiaddr/tarball/0.2.0
10
+ Project-URL: Download, https://github.com/multiformats/py-multiaddr/tarball/0.3.0
11
11
  Keywords: multiaddr
12
12
  Classifier: Development Status :: 2 - Pre-Alpha
13
13
  Classifier: Intended Audience :: Developers
@@ -28,10 +28,10 @@ Requires-Dist: dnspython>=2.7.0
28
28
  Requires-Dist: idna
29
29
  Requires-Dist: netaddr
30
30
  Requires-Dist: psutil
31
- Requires-Dist: py-cid>=0.3.1
32
- Requires-Dist: py-multicodec>=0.2.0
33
- Requires-Dist: py-multibase
34
- Requires-Dist: py-multihash
31
+ Requires-Dist: py-cid>=0.6.0
32
+ Requires-Dist: py-multicodec>=1.1.0
33
+ Requires-Dist: py-multibase>=2.1.0
34
+ Requires-Dist: py-multihash>=4.0.0
35
35
  Requires-Dist: trio-typing>=0.0.4
36
36
  Requires-Dist: trio>=0.26.0
37
37
  Requires-Dist: varint
@@ -42,9 +42,10 @@ Requires-Dist: bump_my_version>=1.2.0; extra == "dev"
42
42
  Requires-Dist: coverage>=6.5.0; extra == "dev"
43
43
  Requires-Dist: mypy; extra == "dev"
44
44
  Requires-Dist: pre-commit; extra == "dev"
45
- Requires-Dist: pyrefly; extra == "dev"
45
+ Requires-Dist: pyrefly==1.2.0; extra == "dev"
46
46
  Requires-Dist: pyright; extra == "dev"
47
47
  Requires-Dist: pytest; extra == "dev"
48
+ Requires-Dist: pytest-benchmark; extra == "dev"
48
49
  Requires-Dist: pytest-cov; extra == "dev"
49
50
  Requires-Dist: pytest-runner; extra == "dev"
50
51
  Requires-Dist: pytest-trio>=0.5.2; extra == "dev"
@@ -100,6 +101,60 @@ Requirements
100
101
  Usage
101
102
  =====
102
103
 
104
+ CLI Tool
105
+ --------
106
+
107
+ py-multiaddr provides a command line interface to inspect multiaddrs and decode them into structured JSON.
108
+
109
+ .. code-block:: bash
110
+
111
+ $ multiaddr /ip4/1.2.3.4/tcp/80
112
+ {
113
+ "string": "/ip4/1.2.3.4/tcp/80",
114
+ "packed": "0x0401020304060050",
115
+ "packedSize": 8,
116
+ "components": [
117
+ {
118
+ "protocol": "ip4",
119
+ "code": 4,
120
+ "value": "1.2.3.4",
121
+ "rawValue": "0x01020304"
122
+ },
123
+ {
124
+ "protocol": "tcp",
125
+ "code": 6,
126
+ "value": "80",
127
+ "rawValue": "0x0050"
128
+ }
129
+ ]
130
+ }
131
+
132
+ You can also pass a hex-encoded multiaddr prefixed with ``0x``, e.g.
133
+ ``multiaddr 0x0401020304060050``. Use the ``-c`` or ``--compact`` flag to
134
+ output on a single line.
135
+
136
+ IP Classification
137
+ -----------------
138
+
139
+ You can easily classify the IP components of multiaddrs (e.g. check for loopback, private networks, or NAT64):
140
+
141
+ .. code-block:: python
142
+
143
+ from multiaddr import Multiaddr, is_private_addr, is_ip_loopback
144
+
145
+ ma1 = Multiaddr("/ip4/192.168.1.1/tcp/80")
146
+ print(is_private_addr(ma1)) # True
147
+ print(is_ip_loopback(ma1)) # False
148
+
149
+ ma2 = Multiaddr("/ip4/127.0.0.1")
150
+ print(is_private_addr(ma2)) # True
151
+ print(is_ip_loopback(ma2)) # True
152
+
153
+ Other available helpers include ``is_public_addr``, ``is_ip_unspecified``,
154
+ ``is_ip6_link_local``, ``is_thin_waist``, and ``is_nat64_ipv4_converted_ipv6_addr``.
155
+ These operate on ``Multiaddr`` objects; ``is_wildcard`` / ``is_link_local_ip``
156
+ remain available for raw IP strings.
157
+
103
158
  Simple
104
159
  ------
105
160
 
@@ -232,16 +287,77 @@ Multiaddr supports DNS-based address resolution using the DNSADDR protocol. This
232
287
 
233
288
  For comprehensive examples including bootstrap node resolution, protocol comparison, and py-libp2p integration, see the `DNS examples <https://github.com/multiformats/py-multiaddr/tree/master/examples/dns>`_ in the examples directory.
234
289
 
290
+ IP Filtering
291
+ ------------
292
+
293
+ Accept/deny IP ranges for multiaddrs, similar to go-multiaddr ``Filters``:
294
+
295
+
296
+ .. code-block:: python
297
+
298
+ from multiaddr import Action, Filters, Multiaddr
299
+
300
+ filters = Filters()
301
+ filters.add_filter("10.0.0.0/8", Action.DENY)
302
+ assert filters.addr_blocked(Multiaddr("/ip4/10.1.2.3/tcp/80"))
303
+ assert not filters.addr_blocked(Multiaddr("/ip4/8.8.8.8/tcp/53"))
304
+
305
+ See ``examples/filters/filters_example.py`` for a printable demo.
306
+
307
+ Socket dial arguments
308
+ ---------------------
309
+
310
+ Convert thin-waist and unix multiaddrs to ``(network, address)`` pairs suitable
311
+ for ``socket.connect()``:
312
+
313
+
314
+ .. code-block:: python
315
+
316
+ from multiaddr import Multiaddr, dial_args
317
+
318
+ print(dial_args(Multiaddr("/ip4/1.2.3.4/tcp/80")))
319
+ # ('tcp4', '1.2.3.4:80')
320
+ print(dial_args(Multiaddr("/ip6/::1/tcp/80")))
321
+ # ('tcp6', '[::1]:80')
322
+ print(dial_args(Multiaddr("/unix/var/run/docker.sock")))
323
+ # ('unix', '/var/run/docker.sock')
324
+
325
+ See ``examples/dial_args/dial_args_example.py`` for a printable demo.
326
+
327
+ Socket address conversion
328
+ -------------------------
329
+
330
+ Convert between Python socket address tuples and multiaddrs:
331
+
332
+
333
+ .. code-block:: python
334
+
335
+ from multiaddr import from_net_addr, to_net_addr
336
+
337
+ ma = from_net_addr(("1.2.3.4", 80))
338
+ print(ma)
339
+ # /ip4/1.2.3.4/tcp/80
340
+ print(to_net_addr(ma))
341
+ # ('1.2.3.4', 80)
342
+ print(from_net_addr(("::1", 53), transport="udp"))
343
+ # /ip6/::1/udp/53
344
+
345
+ See ``examples/net_addr/net_addr_example.py`` for a printable demo.
346
+
235
347
  Thin Waist Address Validation
236
348
  -----------------------------
237
349
 
238
- Multiaddr provides thin waist address validation functionality to process multiaddrs and expand wildcard addresses to all available network interfaces. This is particularly useful for server configuration, network discovery, and dynamic port management.
239
350
 
240
351
 
241
352
  .. code-block:: python
242
353
 
243
354
  from multiaddr import Multiaddr
244
- from multiaddr.utils import get_thin_waist_addresses, get_network_addrs
355
+ from multiaddr.utils import get_thin_waist_addresses, get_network_addrs, interface_multiaddrs
356
+
357
+ # List local interfaces as Multiaddr objects
358
+ for ma in interface_multiaddrs():
359
+ print(ma)
360
+ # Multiaddr('/ip4/192.168.1.10'), ...
245
361
 
246
362
  # Network interface discovery
247
363
  ipv4_addrs = get_network_addrs(4)
@@ -40,6 +40,60 @@ Requirements
40
40
  Usage
41
41
  =====
42
42
 
43
+ CLI Tool
44
+ --------
45
+
46
+ py-multiaddr provides a command line interface to inspect multiaddrs and decode them into structured JSON.
47
+
48
+ .. code-block:: bash
49
+
50
+ $ multiaddr /ip4/1.2.3.4/tcp/80
51
+ {
52
+ "string": "/ip4/1.2.3.4/tcp/80",
53
+ "packed": "0x0401020304060050",
54
+ "packedSize": 8,
55
+ "components": [
56
+ {
57
+ "protocol": "ip4",
58
+ "code": 4,
59
+ "value": "1.2.3.4",
60
+ "rawValue": "0x01020304"
61
+ },
62
+ {
63
+ "protocol": "tcp",
64
+ "code": 6,
65
+ "value": "80",
66
+ "rawValue": "0x0050"
67
+ }
68
+ ]
69
+ }
70
+
71
+ You can also pass a hex-encoded multiaddr prefixed with ``0x``, e.g.
72
+ ``multiaddr 0x0401020304060050``. Use the ``-c`` or ``--compact`` flag to
73
+ output on a single line.
74
+
75
+ IP Classification
76
+ -----------------
77
+
78
+ You can easily classify the IP components of multiaddrs (e.g. check for loopback, private networks, or NAT64):
79
+
80
+ .. code-block:: python
81
+
82
+ from multiaddr import Multiaddr, is_private_addr, is_ip_loopback
83
+
84
+ ma1 = Multiaddr("/ip4/192.168.1.1/tcp/80")
85
+ print(is_private_addr(ma1)) # True
86
+ print(is_ip_loopback(ma1)) # False
87
+
88
+ ma2 = Multiaddr("/ip4/127.0.0.1")
89
+ print(is_private_addr(ma2)) # True
90
+ print(is_ip_loopback(ma2)) # True
91
+
92
+ Other available helpers include ``is_public_addr``, ``is_ip_unspecified``,
93
+ ``is_ip6_link_local``, ``is_thin_waist``, and ``is_nat64_ipv4_converted_ipv6_addr``.
94
+ These operate on ``Multiaddr`` objects; ``is_wildcard`` / ``is_link_local_ip``
95
+ remain available for raw IP strings.
96
+
43
97
  Simple
44
98
  ------
45
99
 
@@ -172,16 +226,77 @@ Multiaddr supports DNS-based address resolution using the DNSADDR protocol. This
172
226
 
173
227
  For comprehensive examples including bootstrap node resolution, protocol comparison, and py-libp2p integration, see the `DNS examples <https://github.com/multiformats/py-multiaddr/tree/master/examples/dns>`_ in the examples directory.
174
228
 
229
+ IP Filtering
230
+ ------------
231
+
232
+ Accept/deny IP ranges for multiaddrs, similar to go-multiaddr ``Filters``:
233
+
234
+
235
+ .. code-block:: python
236
+
237
+ from multiaddr import Action, Filters, Multiaddr
238
+
239
+ filters = Filters()
240
+ filters.add_filter("10.0.0.0/8", Action.DENY)
241
+ assert filters.addr_blocked(Multiaddr("/ip4/10.1.2.3/tcp/80"))
242
+ assert not filters.addr_blocked(Multiaddr("/ip4/8.8.8.8/tcp/53"))
243
+
244
+ See ``examples/filters/filters_example.py`` for a printable demo.
245
+
246
+ Socket dial arguments
247
+ ---------------------
248
+
249
+ Convert thin-waist and unix multiaddrs to ``(network, address)`` pairs suitable
250
+ for ``socket.connect()``:
251
+
252
+
253
+ .. code-block:: python
254
+
255
+ from multiaddr import Multiaddr, dial_args
256
+
257
+ print(dial_args(Multiaddr("/ip4/1.2.3.4/tcp/80")))
258
+ # ('tcp4', '1.2.3.4:80')
259
+ print(dial_args(Multiaddr("/ip6/::1/tcp/80")))
260
+ # ('tcp6', '[::1]:80')
261
+ print(dial_args(Multiaddr("/unix/var/run/docker.sock")))
262
+ # ('unix', '/var/run/docker.sock')
263
+
264
+ See ``examples/dial_args/dial_args_example.py`` for a printable demo.
265
+
266
+ Socket address conversion
267
+ -------------------------
268
+
269
+ Convert between Python socket address tuples and multiaddrs:
270
+
271
+
272
+ .. code-block:: python
273
+
274
+ from multiaddr import from_net_addr, to_net_addr
275
+
276
+ ma = from_net_addr(("1.2.3.4", 80))
277
+ print(ma)
278
+ # /ip4/1.2.3.4/tcp/80
279
+ print(to_net_addr(ma))
280
+ # ('1.2.3.4', 80)
281
+ print(from_net_addr(("::1", 53), transport="udp"))
282
+ # /ip6/::1/udp/53
283
+
284
+ See ``examples/net_addr/net_addr_example.py`` for a printable demo.
285
+
175
286
  Thin Waist Address Validation
176
287
  -----------------------------
177
288
 
178
- Multiaddr provides thin waist address validation functionality to process multiaddrs and expand wildcard addresses to all available network interfaces. This is particularly useful for server configuration, network discovery, and dynamic port management.
179
289
 
180
290
 
181
291
  .. code-block:: python
182
292
 
183
293
  from multiaddr import Multiaddr
184
- from multiaddr.utils import get_thin_waist_addresses, get_network_addrs
294
+ from multiaddr.utils import get_thin_waist_addresses, get_network_addrs, interface_multiaddrs
295
+
296
+ # List local interfaces as Multiaddr objects
297
+ for ma in interface_multiaddrs():
298
+ print(ma)
299
+ # Multiaddr('/ip4/192.168.1.10'), ...
185
300
 
186
301
  # Network interface discovery
187
302
  ipv4_addrs = get_network_addrs(4)
@@ -0,0 +1,108 @@
1
+ from .exceptions import (
2
+ BinaryParseError,
3
+ ParseError,
4
+ ProtocolExistsError,
5
+ ProtocolLookupError,
6
+ ProtocolNotFoundError,
7
+ ProtocolRegistryLocked,
8
+ RecursionLimitError,
9
+ ResolutionError,
10
+ StringParseError,
11
+ )
12
+ from .filters import Action, Filters
13
+ from .multiaddr import Multiaddr
14
+ from .protocols import (
15
+ P_DNS,
16
+ P_DNS4,
17
+ P_DNS6,
18
+ P_DNSADDR,
19
+ P_IP4,
20
+ P_IP6,
21
+ P_P2P,
22
+ P_TCP,
23
+ P_UDP,
24
+ PROTOCOLS,
25
+ REGISTRY,
26
+ Protocol,
27
+ protocol_with_code,
28
+ protocol_with_name,
29
+ )
30
+ from .utils import (
31
+ IP4_LOOPBACK,
32
+ IP4_UNSPECIFIED,
33
+ IP6_LOOPBACK,
34
+ IP6_UNSPECIFIED,
35
+ PRIVATE4,
36
+ PRIVATE6,
37
+ dial_args,
38
+ from_net_addr,
39
+ get_multiaddr_options,
40
+ get_network_addrs,
41
+ get_thin_waist_addresses,
42
+ interface_multiaddrs,
43
+ is_ip6_link_local,
44
+ is_ip_loopback,
45
+ is_ip_unspecified,
46
+ is_link_local_ip,
47
+ is_nat64_ipv4_converted_ipv6_addr,
48
+ is_private_addr,
49
+ is_public_addr,
50
+ is_thin_waist,
51
+ is_wildcard,
52
+ to_net_addr,
53
+ )
54
+
55
+ __author__ = "Steven Buss"
56
+ __email__ = "steven.buss@gmail.com"
57
+ __version__ = "0.3.0"
58
+
59
+ __all__ = [
60
+ "IP4_LOOPBACK",
61
+ "IP4_UNSPECIFIED",
62
+ "IP6_LOOPBACK",
63
+ "IP6_UNSPECIFIED",
64
+ "PRIVATE4",
65
+ "PRIVATE6",
66
+ "PROTOCOLS",
67
+ "P_DNS",
68
+ "P_DNS4",
69
+ "P_DNS6",
70
+ "P_DNSADDR",
71
+ "P_IP4",
72
+ "P_IP6",
73
+ "P_P2P",
74
+ "P_TCP",
75
+ "P_UDP",
76
+ "REGISTRY",
77
+ "Action",
78
+ "BinaryParseError",
79
+ "Filters",
80
+ "Multiaddr",
81
+ "ParseError",
82
+ "Protocol",
83
+ "ProtocolExistsError",
84
+ "ProtocolLookupError",
85
+ "ProtocolNotFoundError",
86
+ "ProtocolRegistryLocked",
87
+ "RecursionLimitError",
88
+ "ResolutionError",
89
+ "StringParseError",
90
+ "dial_args",
91
+ "from_net_addr",
92
+ "get_multiaddr_options",
93
+ "get_network_addrs",
94
+ "get_thin_waist_addresses",
95
+ "interface_multiaddrs",
96
+ "is_ip6_link_local",
97
+ "is_ip_loopback",
98
+ "is_ip_unspecified",
99
+ "is_link_local_ip",
100
+ "is_nat64_ipv4_converted_ipv6_addr",
101
+ "is_private_addr",
102
+ "is_public_addr",
103
+ "is_thin_waist",
104
+ "is_wildcard",
105
+ "protocol_with_code",
106
+ "protocol_with_name",
107
+ "to_net_addr",
108
+ ]
@@ -0,0 +1,61 @@
1
+ import argparse
2
+ import json
3
+ import sys
4
+ from typing import Any
5
+
6
+ from . import __version__
7
+ from .multiaddr import Multiaddr
8
+ from .transforms import bytes_iter
9
+
10
+
11
+ def main() -> None:
12
+ parser = argparse.ArgumentParser(description="Inspect multiaddrs")
13
+ parser.add_argument("addr", help="Multiaddr string or hex bytes (0x...)")
14
+ parser.add_argument("-c", "--compact", action="store_true", help="Output compact JSON")
15
+ parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
16
+
17
+ args = parser.parse_args()
18
+
19
+ try:
20
+ if args.addr.startswith("0x"):
21
+ addr_bytes = bytes.fromhex(args.addr[2:])
22
+ addr = Multiaddr(addr_bytes)
23
+ else:
24
+ addr = Multiaddr(args.addr)
25
+ except Exception as e:
26
+ print(f"Error parsing multiaddr: {e}", file=sys.stderr)
27
+ sys.exit(1)
28
+
29
+ try:
30
+ components = []
31
+ for _, proto, codec, value_bytes in bytes_iter(addr.to_bytes()):
32
+ component: dict[str, Any] = {
33
+ "protocol": proto.name,
34
+ "code": proto.code,
35
+ }
36
+ if codec.SIZE != 0:
37
+ component["value"] = codec.to_string(proto, value_bytes)
38
+ component["rawValue"] = "0x" + value_bytes.hex()
39
+ else:
40
+ component["value"] = None
41
+ component["rawValue"] = None
42
+ components.append(component)
43
+
44
+ except Exception as e:
45
+ print(f"Error decoding multiaddr components: {e}", file=sys.stderr)
46
+ sys.exit(1)
47
+
48
+ indent = None if args.compact else 2
49
+
50
+ output = {
51
+ "string": str(addr),
52
+ "packed": "0x" + addr.to_bytes().hex(),
53
+ "packedSize": len(addr.to_bytes()),
54
+ "components": components,
55
+ }
56
+
57
+ print(json.dumps(output, indent=indent))
58
+
59
+
60
+ if __name__ == "__main__":
61
+ main()
@@ -2,12 +2,12 @@ import urllib.parse
2
2
  from typing import Any
3
3
 
4
4
  from ..exceptions import BinaryParseError
5
- from . import CodecBase
5
+ from . import LENGTH_PREFIXED_VAR_SIZE, CodecBase
6
6
 
7
7
 
8
8
  class Codec(CodecBase):
9
- SIZE = 0 # Variable size
10
- IS_PATH = False # Default to False, will be set to True for ip6zone protocol
9
+ SIZE = LENGTH_PREFIXED_VAR_SIZE
10
+ IS_PATH = False
11
11
 
12
12
  def to_bytes(self, proto: Any, string: str) -> bytes:
13
13
  """Convert a UTF-8 string to its binary representation."""
@@ -19,6 +19,9 @@ class Codec(CodecBase):
19
19
  string = string.strip()
20
20
  if not string:
21
21
  raise ValueError("Zone identifier cannot be empty after stripping whitespace")
22
+ if "/" in string:
23
+ # Matches go-multiaddr: a '/' would make the text form unparseable
24
+ raise ValueError("Zone identifier cannot contain '/'")
22
25
  else:
23
26
  # URL decode the string to handle special characters for other protocols
24
27
  string = urllib.parse.unquote(string)
@@ -42,6 +45,8 @@ class Codec(CodecBase):
42
45
  value = value.strip()
43
46
  if not value:
44
47
  raise ValueError("Zone identifier cannot be empty after stripping whitespace")
48
+ if "/" in value:
49
+ raise ValueError("Zone identifier cannot contain '/'")
45
50
  return value
46
51
  # For other protocols, URL encode special characters
47
52
  return urllib.parse.quote(value, safe="%")