multiaddr 0.1.1__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 (66) hide show
  1. {multiaddr-0.1.1 → multiaddr-0.3.0}/CONTRIBUTING.rst +17 -0
  2. multiaddr-0.3.0/HISTORY.rst +209 -0
  3. {multiaddr-0.1.1 → multiaddr-0.3.0}/PKG-INFO +125 -9
  4. {multiaddr-0.1.1 → 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.1.1 → multiaddr-0.3.0}/multiaddr/codecs/certhash.py +11 -1
  8. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/domain.py +0 -13
  9. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/utf8.py +8 -3
  10. multiaddr-0.3.0/multiaddr/codecs/wg.py +88 -0
  11. multiaddr-0.3.0/multiaddr/filters.py +86 -0
  12. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/multiaddr.py +51 -7
  13. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/protocols.py +12 -3
  14. multiaddr-0.3.0/multiaddr/resolvers/__init__.py +17 -0
  15. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/resolvers/dns.py +6 -3
  16. multiaddr-0.3.0/multiaddr/resolvers/util.py +173 -0
  17. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/transforms.py +15 -35
  18. multiaddr-0.3.0/multiaddr/utils.py +313 -0
  19. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr.egg-info/PKG-INFO +125 -9
  20. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr.egg-info/SOURCES.txt +16 -1
  21. multiaddr-0.3.0/multiaddr.egg-info/entry_points.txt +2 -0
  22. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr.egg-info/requires.txt +6 -5
  23. {multiaddr-0.1.1 → multiaddr-0.3.0}/pyproject.toml +20 -8
  24. multiaddr-0.3.0/tests/test_benchmarks.py +41 -0
  25. multiaddr-0.3.0/tests/test_cli.py +59 -0
  26. multiaddr-0.3.0/tests/test_dial_args.py +27 -0
  27. multiaddr-0.3.0/tests/test_filters.py +55 -0
  28. multiaddr-0.3.0/tests/test_interface_multiaddrs.py +18 -0
  29. multiaddr-0.3.0/tests/test_ip_classification.py +65 -0
  30. {multiaddr-0.1.1 → multiaddr-0.3.0}/tests/test_multiaddr.py +80 -6
  31. multiaddr-0.3.0/tests/test_net_addr.py +31 -0
  32. multiaddr-0.3.0/tests/test_package_exports.py +79 -0
  33. multiaddr-0.3.0/tests/test_protocol_codec_cache.py +18 -0
  34. {multiaddr-0.1.1 → multiaddr-0.3.0}/tests/test_protocols.py +115 -1
  35. {multiaddr-0.1.1 → multiaddr-0.3.0}/tests/test_resolvers.py +404 -1
  36. {multiaddr-0.1.1 → multiaddr-0.3.0}/tests/test_transforms.py +29 -1
  37. multiaddr-0.3.0/tests/test_transforms_no_debug.py +11 -0
  38. multiaddr-0.1.1/HISTORY.rst +0 -131
  39. multiaddr-0.1.1/multiaddr/__init__.py +0 -5
  40. multiaddr-0.1.1/multiaddr/resolvers/__init__.py +0 -6
  41. multiaddr-0.1.1/multiaddr/utils.py +0 -119
  42. {multiaddr-0.1.1 → multiaddr-0.3.0}/AUTHORS +0 -0
  43. {multiaddr-0.1.1 → multiaddr-0.3.0}/LICENSE-APACHE2 +0 -0
  44. {multiaddr-0.1.1 → multiaddr-0.3.0}/LICENSE-MIT +0 -0
  45. {multiaddr-0.1.1 → multiaddr-0.3.0}/MANIFEST.in +0 -0
  46. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/__init__.py +0 -0
  47. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/cid.py +0 -0
  48. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/fspath.py +0 -0
  49. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/garlic32.py +0 -0
  50. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/garlic64.py +0 -0
  51. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/http_path.py +0 -0
  52. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/ip4.py +0 -0
  53. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/ip6.py +0 -0
  54. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/ipcidr.py +0 -0
  55. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/memory.py +0 -0
  56. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/onion.py +0 -0
  57. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/onion3.py +0 -0
  58. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/codecs/uint16be.py +0 -0
  59. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/exceptions.py +0 -0
  60. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr/resolvers/base.py +0 -0
  61. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr.egg-info/dependency_links.txt +0 -0
  62. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr.egg-info/not-zip-safe +0 -0
  63. {multiaddr-0.1.1 → multiaddr-0.3.0}/multiaddr.egg-info/top_level.txt +0 -0
  64. {multiaddr-0.1.1 → multiaddr-0.3.0}/setup.cfg +0 -0
  65. {multiaddr-0.1.1 → multiaddr-0.3.0}/tests/__init__.py +0 -0
  66. {multiaddr-0.1.1 → 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
 
@@ -0,0 +1,209 @@
1
+ History
2
+ =======
3
+
4
+ .. towncrier release notes start
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
+
58
+ py-multiaddr v0.2.0 (2026-03-17)
59
+ --------------------------------
60
+
61
+ Features
62
+ ~~~~~~~~
63
+
64
+ - Add resolver utility functions ported from go-multiaddr-dns: ``matches()``, ``resolve_all()``, ``is_fqdn()``, ``fqdn()``, ``addr_len()``, and ``offset_addr()``. These utilities support DNS-based multiaddr resolution workflows including iterative resolution and FQDN handling. (`#101 <https://github.com/multiformats/py-multiaddr/issues/101>`__)
65
+
66
+
67
+ Internal Changes - for py-multiaddr Contributors
68
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69
+
70
+ - Updated the tox GitHub Actions workflow so lint runs only once on Linux with
71
+ Python 3.10, while core tests continue to run across all configured Python
72
+ versions. (`#104 <https://github.com/multiformats/py-multiaddr/issues/104>`__)
73
+ - Aligned local tox defaults with CI by running lint only in ``py310-lint``,
74
+ while keeping core test environments for all configured Python versions. (`#106 <https://github.com/multiformats/py-multiaddr/issues/106>`__)
75
+
76
+
77
+ Removals
78
+ ~~~~~~~~
79
+
80
+ - Removed the module-level ``to_bytes`` and ``to_string`` helpers from ``multiaddr.codecs.domain``.
81
+ Domain codec behavior remains available through ``multiaddr.codecs.domain.Codec``. (`#100 <https://github.com/multiformats/py-multiaddr/issues/100>`__)
82
+
83
+
84
+ py-multiaddr v0.1.1 (2025-12-07)
85
+ --------------------------------
86
+
87
+ Bugfixes
88
+ ~~~~~~~~
89
+
90
+ - Fixed validation for tag-only protocols (protocols that do not accept values).
91
+ Tag-only protocols like ``http``, ``https``, ``tls``, ``noise``, ``webrtc``, etc.
92
+ now correctly reject invalid value assignments via both ``/tag/value`` and
93
+ ``/tag=value`` syntax, raising clear error messages that do not include the
94
+ invalid value. (`#98 <https://github.com/multiformats/py-multiaddr/issues/98>`__)
95
+
96
+
97
+ py-multiaddr v0.1.0 (2025-10-27)
98
+ --------------------------------
99
+
100
+ Features
101
+ ~~~~~~~~
102
+
103
+ - Added the following protocols in reference with go-multiaddr
104
+
105
+ - SNI: 0x01C1
106
+ - NOISE: 0x01C6
107
+ - CERTHASH:
108
+ - WEBRTC:
109
+ - WEBRTC-DIRECT: (`#181 <https://github.com/multiformats/py-multiaddr/issues/181>`__)
110
+
111
+
112
+ py-multiaddr v0.0.12 (2025-10-21)
113
+ ---------------------------------
114
+
115
+ Features
116
+ ~~~~~~~~
117
+
118
+ - Added the http-path protocol in reference with go-multiaddr. (`#94 <https://github.com/multiformats/py-multiaddr/issues/94>`__)
119
+ - Added ipcidr protocol support to py-multiaddr
120
+
121
+ - Implements protocol code 43 (0x2B) for CIDR notation support
122
+ - Full compatibility with Go multiaddr implementation
123
+ - Comprehensive test coverage including edge cases (`#95 <https://github.com/multiformats/py-multiaddr/issues/95>`__)
124
+ - Added garlic32 and garlic64 protocol support to py-multiaddr
125
+
126
+ - Implements protocol code 446 and 447.
127
+ - Full compatibility with Go multiaddr implementation
128
+ - Comprehensive test coverage including edge cases
129
+ - Complete documentation and examples in examples/garlic/garlic_examples.py
130
+ - Integration with multiaddr documentation system (`#96 <https://github.com/multiformats/py-multiaddr/issues/96>`__)
131
+
132
+
133
+ py-multiaddr v0.0.11 (2025-09-15)
134
+ ---------------------------------
135
+
136
+ Improved Documentation
137
+ ~~~~~~~~~~~~~~~~~~~~~~
138
+
139
+ - Adds example of DNS address resolution. (`#75 <https://github.com/multiformats/py-multiaddr/issues/75>`__)
140
+
141
+
142
+ Features
143
+ ~~~~~~~~
144
+
145
+ - Added support for CIDv1 format and improved sequence protocol handling with enhanced indexing and slicing operations. (`#65 <https://github.com/multiformats/py-multiaddr/issues/65>`__)
146
+ - Add quic tests. new quic example (`#66 <https://github.com/multiformats/py-multiaddr/issues/66>`__)
147
+ - Adds DNSADDR protocol support. (`#68 <https://github.com/multiformats/py-multiaddr/issues/68>`__)
148
+ - Add thin waist address validation (`#72 <https://github.com/multiformats/py-multiaddr/issues/72>`__)
149
+ - Adds support for p2p-circuit addresses. (`#74 <https://github.com/multiformats/py-multiaddr/issues/74>`__)
150
+ - Added full support for dnsaddr protocol and dns4 and dns6 as well (`#80 <https://github.com/multiformats/py-multiaddr/issues/80>`__)
151
+ - Integrated the memory protocol, in reference with go-libp2p (`#92 <https://github.com/multiformats/py-multiaddr/issues/92>`__)
152
+
153
+
154
+ Internal Changes - for py-multiaddr Contributors
155
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156
+
157
+ - Enhanced type safety with comprehensive type hints, improved validation, and expanded test coverage for better code reliability and maintainability. (`#65 <https://github.com/multiformats/py-multiaddr/issues/65>`__)
158
+ - Added full tests and doc. All typecheck passes (`#80 <https://github.com/multiformats/py-multiaddr/issues/80>`__)
159
+ - Drop python3.9 and run py-upgrade, set up CI, add readthedocs config, updates to Makefile (`#85 <https://github.com/multiformats/py-multiaddr/issues/85>`__)
160
+
161
+
162
+ 0.0.10 (2025-6-18)
163
+ ------------------
164
+
165
+ * Fix Type Issues and add strict type checks using Ruff & Pyright
166
+ * Spec updates, Python 3.4- unsupport & custom registries by @ntninja in #59
167
+ * add quic-v1 protocol by @justheuristic in #63
168
+ * Fix/typecheck by @acul71 in #65
169
+ * chore: rm local pyrightconfig.json by @arcinston in #70
170
+
171
+ 0.0.9 (2019-12-23)
172
+ ------------------
173
+
174
+ * Add Multiaddr.__hash__ method for hashable multiaddrs
175
+ * Add onion3 address support
176
+ * Fix broken reST and links in documentation
177
+ * Remove emoji from README.rst
178
+
179
+ 0.0.7 (2019-5-8)
180
+ ----------------
181
+
182
+ * include subpackage
183
+ * refactor util and codec
184
+
185
+ 0.0.5 (2019-5-7)
186
+ ----------------
187
+
188
+ * unhexilified bytes
189
+ * new exceptions
190
+ * miscellaneous improvements [via alexander255_ `#42`_]
191
+
192
+ .. _alexander255: https://github.com/alexander255
193
+ .. _`#42`: https://github.com/multiformats/py-multiaddr/pull/42
194
+
195
+ 0.0.2 (2016-5-4)
196
+ ----------------
197
+
198
+ * Fix a bug in decapsulate that threw an IndexError instead of a copy of the
199
+ Multiaddr when the original multiaddr does not contain the multiaddr to
200
+ decapsulate. [via fredthomsen_ `#9`_]
201
+ * Increase test coverage [via fredthomsen_ `#9`_]
202
+
203
+ .. _fredthomsen: https://github.com/fredthomsen
204
+ .. _`#9`: https://github.com/multiformats/py-multiaddr/pull/9
205
+
206
+ 0.0.1 (2016-1-22)
207
+ ------------------
208
+
209
+ * First release on PyPI.
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: multiaddr
3
- Version: 0.1.1
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.1.1
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
+ ]