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.
- {multiaddr-0.2.0 → multiaddr-0.3.0}/CONTRIBUTING.rst +17 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/HISTORY.rst +52 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/PKG-INFO +125 -9
- {multiaddr-0.2.0 → multiaddr-0.3.0}/README.rst +117 -2
- multiaddr-0.3.0/multiaddr/__init__.py +108 -0
- multiaddr-0.3.0/multiaddr/cli.py +61 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/utf8.py +8 -3
- multiaddr-0.3.0/multiaddr/codecs/wg.py +88 -0
- multiaddr-0.3.0/multiaddr/filters.py +86 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/multiaddr.py +51 -7
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/protocols.py +12 -3
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/transforms.py +15 -35
- multiaddr-0.3.0/multiaddr/utils.py +313 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/PKG-INFO +125 -9
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/SOURCES.txt +15 -1
- multiaddr-0.3.0/multiaddr.egg-info/entry_points.txt +2 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/requires.txt +6 -5
- {multiaddr-0.2.0 → multiaddr-0.3.0}/pyproject.toml +20 -8
- multiaddr-0.3.0/tests/test_benchmarks.py +41 -0
- multiaddr-0.3.0/tests/test_cli.py +59 -0
- multiaddr-0.3.0/tests/test_dial_args.py +27 -0
- multiaddr-0.3.0/tests/test_filters.py +55 -0
- multiaddr-0.3.0/tests/test_interface_multiaddrs.py +18 -0
- multiaddr-0.3.0/tests/test_ip_classification.py +65 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_multiaddr.py +77 -4
- multiaddr-0.3.0/tests/test_net_addr.py +31 -0
- multiaddr-0.3.0/tests/test_package_exports.py +79 -0
- multiaddr-0.3.0/tests/test_protocol_codec_cache.py +18 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_protocols.py +115 -1
- {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_transforms.py +29 -1
- multiaddr-0.3.0/tests/test_transforms_no_debug.py +11 -0
- multiaddr-0.2.0/multiaddr/__init__.py +0 -5
- multiaddr-0.2.0/multiaddr/utils.py +0 -119
- {multiaddr-0.2.0 → multiaddr-0.3.0}/AUTHORS +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/LICENSE-APACHE2 +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/LICENSE-MIT +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/MANIFEST.in +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/__init__.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/certhash.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/cid.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/domain.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/fspath.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/garlic32.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/garlic64.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/http_path.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/ip4.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/ip6.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/ipcidr.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/memory.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/onion.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/onion3.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/codecs/uint16be.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/exceptions.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/__init__.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/base.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/dns.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr/resolvers/util.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/dependency_links.txt +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/not-zip-safe +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/multiaddr.egg-info/top_level.txt +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/setup.cfg +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/__init__.py +0 -0
- {multiaddr-0.2.0 → multiaddr-0.3.0}/tests/test_resolvers.py +0 -0
- {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.
|
|
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.
|
|
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.
|
|
32
|
-
Requires-Dist: py-multicodec>=
|
|
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 =
|
|
10
|
-
IS_PATH = False
|
|
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="%")
|