multiaddr 0.0.9__tar.gz → 0.0.11__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 (81) hide show
  1. multiaddr-0.0.11/AUTHORS +18 -0
  2. {multiaddr-0.0.9 → multiaddr-0.0.11}/CONTRIBUTING.rst +49 -14
  3. multiaddr-0.0.11/HISTORY.rst +82 -0
  4. multiaddr-0.0.11/LICENSE-APACHE2 +7 -0
  5. multiaddr-0.0.11/LICENSE-MIT +22 -0
  6. {multiaddr-0.0.9 → multiaddr-0.0.11}/MANIFEST.in +7 -3
  7. multiaddr-0.0.11/PKG-INFO +351 -0
  8. multiaddr-0.0.11/README.rst +293 -0
  9. multiaddr-0.0.11/multiaddr/__init__.py +5 -0
  10. multiaddr-0.0.11/multiaddr/codecs/__init__.py +43 -0
  11. multiaddr-0.0.11/multiaddr/codecs/cid.py +177 -0
  12. multiaddr-0.0.11/multiaddr/codecs/domain.py +52 -0
  13. multiaddr-0.0.11/multiaddr/codecs/fspath.py +73 -0
  14. multiaddr-0.0.11/multiaddr/codecs/ip4.py +23 -0
  15. multiaddr-0.0.11/multiaddr/codecs/ip6.py +19 -0
  16. multiaddr-0.0.11/multiaddr/codecs/memory.py +30 -0
  17. multiaddr-0.0.11/multiaddr/codecs/onion.py +54 -0
  18. multiaddr-0.0.11/multiaddr/codecs/onion3.py +56 -0
  19. multiaddr-0.0.11/multiaddr/codecs/uint16be.py +25 -0
  20. multiaddr-0.0.11/multiaddr/codecs/utf8.py +49 -0
  21. multiaddr-0.0.11/multiaddr/exceptions.py +150 -0
  22. multiaddr-0.0.11/multiaddr/multiaddr.py +504 -0
  23. multiaddr-0.0.11/multiaddr/protocols.py +491 -0
  24. multiaddr-0.0.11/multiaddr/resolvers/__init__.py +6 -0
  25. multiaddr-0.0.11/multiaddr/resolvers/base.py +29 -0
  26. multiaddr-0.0.11/multiaddr/resolvers/dns.py +408 -0
  27. multiaddr-0.0.11/multiaddr/transforms.py +174 -0
  28. multiaddr-0.0.11/multiaddr/utils.py +119 -0
  29. multiaddr-0.0.11/multiaddr.egg-info/PKG-INFO +351 -0
  30. {multiaddr-0.0.9 → multiaddr-0.0.11}/multiaddr.egg-info/SOURCES.txt +12 -16
  31. multiaddr-0.0.11/multiaddr.egg-info/requires.txt +32 -0
  32. multiaddr-0.0.11/pyproject.toml +206 -0
  33. multiaddr-0.0.11/setup.cfg +4 -0
  34. multiaddr-0.0.11/tests/__init__.py +0 -0
  35. multiaddr-0.0.11/tests/test_multiaddr.py +827 -0
  36. multiaddr-0.0.11/tests/test_protocols.py +271 -0
  37. multiaddr-0.0.11/tests/test_resolvers.py +410 -0
  38. multiaddr-0.0.11/tests/test_thin_waist_addresses.py +72 -0
  39. multiaddr-0.0.11/tests/test_transforms.py +236 -0
  40. multiaddr-0.0.9/AUTHORS +0 -3
  41. multiaddr-0.0.9/HISTORY.rst +0 -34
  42. multiaddr-0.0.9/PKG-INFO +0 -186
  43. multiaddr-0.0.9/README.rst +0 -125
  44. multiaddr-0.0.9/docs/Makefile +0 -177
  45. multiaddr-0.0.9/docs/authors.rst +0 -21
  46. multiaddr-0.0.9/docs/conf.py +0 -275
  47. multiaddr-0.0.9/docs/contributing.rst +0 -1
  48. multiaddr-0.0.9/docs/history.rst +0 -1
  49. multiaddr-0.0.9/docs/index.rst +0 -26
  50. multiaddr-0.0.9/docs/installation.rst +0 -9
  51. multiaddr-0.0.9/docs/make.bat +0 -242
  52. multiaddr-0.0.9/docs/modules.rst +0 -7
  53. multiaddr-0.0.9/docs/multiaddr.rst +0 -46
  54. multiaddr-0.0.9/docs/readme.rst +0 -1
  55. multiaddr-0.0.9/multiaddr/__init__.py +0 -6
  56. multiaddr-0.0.9/multiaddr/codecs/__init__.py +0 -24
  57. multiaddr-0.0.9/multiaddr/codecs/_util.py +0 -8
  58. multiaddr-0.0.9/multiaddr/codecs/fspath.py +0 -35
  59. multiaddr-0.0.9/multiaddr/codecs/idna.py +0 -17
  60. multiaddr-0.0.9/multiaddr/codecs/ip4.py +0 -19
  61. multiaddr-0.0.9/multiaddr/codecs/ip6.py +0 -19
  62. multiaddr-0.0.9/multiaddr/codecs/onion.py +0 -40
  63. multiaddr-0.0.9/multiaddr/codecs/onion3.py +0 -40
  64. multiaddr-0.0.9/multiaddr/codecs/p2p.py +0 -24
  65. multiaddr-0.0.9/multiaddr/codecs/uint16be.py +0 -23
  66. multiaddr-0.0.9/multiaddr/codecs/utf8.py +0 -19
  67. multiaddr-0.0.9/multiaddr/exceptions.py +0 -89
  68. multiaddr-0.0.9/multiaddr/multiaddr.py +0 -260
  69. multiaddr-0.0.9/multiaddr/protocols.py +0 -205
  70. multiaddr-0.0.9/multiaddr/transforms.py +0 -103
  71. multiaddr-0.0.9/multiaddr.egg-info/PKG-INFO +0 -186
  72. multiaddr-0.0.9/multiaddr.egg-info/requires.txt +0 -4
  73. multiaddr-0.0.9/setup.cfg +0 -22
  74. multiaddr-0.0.9/setup.py +0 -65
  75. multiaddr-0.0.9/tests/__init__.py +0 -1
  76. multiaddr-0.0.9/tests/test_multiaddr.py +0 -363
  77. multiaddr-0.0.9/tests/test_protocols.py +0 -165
  78. multiaddr-0.0.9/tests/test_transforms.py +0 -168
  79. {multiaddr-0.0.9 → multiaddr-0.0.11}/multiaddr.egg-info/dependency_links.txt +0 -0
  80. {multiaddr-0.0.9 → multiaddr-0.0.11}/multiaddr.egg-info/not-zip-safe +0 -0
  81. {multiaddr-0.0.9 → multiaddr-0.0.11}/multiaddr.egg-info/top_level.txt +0 -0
@@ -0,0 +1,18 @@
1
+ Steven Buss <steven.buss@gmail.com>
2
+ Alexander Schlarb <alexander@ninetailed.ninja>
3
+ Fred Thomsen <fredthomsen@fredthomsen.net>
4
+ Jesse Weinstein <jesse@wefu.org>
5
+ mhchia
6
+ acul71
7
+ arcinston
8
+ pacrob
9
+ raulk
10
+ robzajac
11
+ zixuanzh
12
+ hugovk
13
+ justheuristic
14
+ manusheel
15
+ rodvagg
16
+ venkat
17
+ fredthomsen
18
+ web3-bot
@@ -20,6 +20,7 @@ Report bugs at https://github.com/multiformats/py-multiaddr/issues.
20
20
  If you are reporting a bug, please include:
21
21
 
22
22
  * Your operating system name and version.
23
+ * Python version.
23
24
  * Any details about your local setup that might be helpful in troubleshooting.
24
25
  * Detailed steps to reproduce the bug.
25
26
 
@@ -62,13 +63,13 @@ Ready to contribute? Here's how to set up `multiaddr` for local development.
62
63
  1. Fork the `multiaddr` repo on GitHub.
63
64
  2. Clone your fork locally::
64
65
 
65
- $ git clone git@github.com:your_name_here/multiaddr.git
66
+ $ git clone git@github.com:your_name_here/py-multiaddr.git
66
67
 
67
- 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
68
+ 3. Install your local copy into a virtual environment::
68
69
 
69
- $ mkvirtualenv multiaddr
70
- $ cd multiaddr/
71
- $ python setup.py develop
70
+ $ python -m venv venv
71
+ $ source venv/bin/activate # On Windows: venv\Scripts\activate
72
+ $ pip install -e ".[dev]"
72
73
 
73
74
  4. Create a branch for local development::
74
75
 
@@ -76,13 +77,19 @@ Ready to contribute? Here's how to set up `multiaddr` for local development.
76
77
 
77
78
  Now you can make your changes locally.
78
79
 
79
- 5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
80
+ 5. When you're done making changes, run the development workflow::
80
81
 
81
- $ flake8 multiaddr tests
82
- $ python setup.py test
83
- $ tox
82
+ $ make pr
84
83
 
85
- To get flake8 and tox, just pip install them into your virtualenv.
84
+ This will run: clean → fix → lint → typecheck → test
85
+
86
+ Or run individual commands::
87
+
88
+ $ make fix # Fix formatting & linting issues with ruff
89
+ $ make lint # Run pre-commit hooks on all files
90
+ $ make typecheck # Run mypy and pyrefly type checking
91
+ $ make test # Run tests with pytest
92
+ $ make coverage # Run tests with coverage report
86
93
 
87
94
  6. Commit your changes and push your branch to GitHub::
88
95
 
@@ -101,13 +108,41 @@ Before you submit a pull request, check that it meets these guidelines:
101
108
  2. If the pull request adds functionality, the docs should be updated. Put
102
109
  your new functionality into a function with a docstring, and add the
103
110
  feature to the list in README.rst.
104
- 3. The pull request should work for Python 2.7, 3.4+ and PyPy3. Check
105
- https://travis-ci.org/multiformats/py-multiaddr/pull_requests
106
- and make sure that the tests pass for all supported Python versions.
111
+ 3. The pull request should work for Python 3.10+ (Python 3.9 support was dropped).
112
+ 4. All type checking must pass (mypy and pyrefly).
113
+ 5. All pre-commit hooks must pass.
114
+ 6. Code must be formatted with ruff.
115
+
116
+ Development Workflow
117
+ --------------------
118
+
119
+ The project follows a py-libp2p-style development workflow:
120
+
121
+ 1. **Clean**: Remove build artifacts
122
+ 2. **Fix**: Auto-fix formatting and linting issues
123
+ 3. **Lint**: Run pre-commit hooks
124
+ 4. **Typecheck**: Run mypy and pyrefly
125
+ 5. **Test**: Run the test suite
126
+
127
+ Use ``make pr`` to run the complete workflow.
128
+
129
+ Release Notes
130
+ -------------
131
+
132
+ When contributing, please add a newsfragment file in the ``newsfragments/`` directory.
133
+ See ``newsfragments/README.md`` for details on the format and types.
107
134
 
108
135
  Tips
109
136
  ----
110
137
 
111
138
  To run a subset of tests::
112
139
 
113
- $ python -m unittest tests.test_multiaddr
140
+ $ python -m pytest tests/test_multiaddr.py
141
+
142
+ To run with coverage::
143
+
144
+ $ make coverage
145
+
146
+ To build documentation::
147
+
148
+ $ make docs
@@ -0,0 +1,82 @@
1
+ History
2
+ =======
3
+
4
+ .. towncrier release notes start
5
+
6
+ py-multiaddr v0.0.11 (2025-09-15)
7
+ ---------------------------------
8
+
9
+ Improved Documentation
10
+ ~~~~~~~~~~~~~~~~~~~~~~
11
+
12
+ - Adds example of DNS address resolution. (`#75 <https://github.com/multiformats/py-multiaddr/issues/75>`__)
13
+
14
+
15
+ Features
16
+ ~~~~~~~~
17
+
18
+ - 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>`__)
19
+ - Add quic tests. new quic example (`#66 <https://github.com/multiformats/py-multiaddr/issues/66>`__)
20
+ - Adds DNSADDR protocol support. (`#68 <https://github.com/multiformats/py-multiaddr/issues/68>`__)
21
+ - Add thin waist address validation (`#72 <https://github.com/multiformats/py-multiaddr/issues/72>`__)
22
+ - Adds support for p2p-circuit addresses. (`#74 <https://github.com/multiformats/py-multiaddr/issues/74>`__)
23
+ - Added full support for dnsaddr protocol and dns4 and dns6 as well (`#80 <https://github.com/multiformats/py-multiaddr/issues/80>`__)
24
+ - Integrated the memory protocol, in reference with go-libp2p (`#92 <https://github.com/multiformats/py-multiaddr/issues/92>`__)
25
+
26
+
27
+ Internal Changes - for py-multiaddr Contributors
28
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29
+
30
+ - 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>`__)
31
+ - Added full tests and doc. All typecheck passes (`#80 <https://github.com/multiformats/py-multiaddr/issues/80>`__)
32
+ - 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>`__)
33
+
34
+
35
+ 0.0.10 (2025-6-18)
36
+ ------------------
37
+
38
+ * Fix Type Issues and add strict type checks using Ruff & Pyright
39
+ * Spec updates, Python 3.4- unsupport & custom registries by @ntninja in #59
40
+ * add quic-v1 protocol by @justheuristic in #63
41
+ * Fix/typecheck by @acul71 in #65
42
+ * chore: rm local pyrightconfig.json by @arcinston in #70
43
+
44
+ 0.0.9 (2019-12-23)
45
+ ------------------
46
+
47
+ * Add Multiaddr.__hash__ method for hashable multiaddrs
48
+ * Add onion3 address support
49
+ * Fix broken reST and links in documentation
50
+ * Remove emoji from README.rst
51
+
52
+ 0.0.7 (2019-5-8)
53
+ ----------------
54
+
55
+ * include subpackage
56
+ * refactor util and codec
57
+
58
+ 0.0.5 (2019-5-7)
59
+ ----------------
60
+
61
+ * unhexilified bytes
62
+ * new exceptions
63
+ * miscellaneous improvements [via alexander255_ `#42`_]
64
+
65
+ .. _alexander255: https://github.com/alexander255
66
+ .. _`#42`: https://github.com/multiformats/py-multiaddr/pull/42
67
+
68
+ 0.0.2 (2016-5-4)
69
+ ----------------
70
+
71
+ * Fix a bug in decapsulate that threw an IndexError instead of a copy of the
72
+ Multiaddr when the original multiaddr does not contain the multiaddr to
73
+ decapsulate. [via fredthomsen_ `#9`_]
74
+ * Increase test coverage [via fredthomsen_ `#9`_]
75
+
76
+ .. _fredthomsen: https://github.com/fredthomsen
77
+ .. _`#9`: https://github.com/multiformats/py-multiaddr/pull/9
78
+
79
+ 0.0.1 (2016-1-22)
80
+ ------------------
81
+
82
+ * First release on PyPI.
@@ -0,0 +1,7 @@
1
+ Copyright (c) 2018 Steven Buss
2
+
3
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
4
+
5
+ http://www.apache.org/licenses/LICENSE-2.0
6
+
7
+ Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
@@ -0,0 +1,22 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2014-2015 Steven Buss
4
+ Copyright (c) 2019-2020 Alexander Schlarb
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
@@ -1,11 +1,15 @@
1
1
  include AUTHORS
2
2
  include CONTRIBUTING.rst
3
3
  include HISTORY.rst
4
- include LICENSE
4
+ include LICENSE-APACHE2
5
+ include LICENSE-MIT
5
6
  include README.rst
6
7
 
7
8
  recursive-include tests *
9
+
10
+ global-include *.pyi
11
+
8
12
  recursive-exclude * __pycache__
9
13
  recursive-exclude * *.py[co]
10
-
11
- recursive-include docs *.rst conf.py Makefile make.bat
14
+ prune .tox
15
+ prune venv*
@@ -0,0 +1,351 @@
1
+ Metadata-Version: 2.4
2
+ Name: multiaddr
3
+ Version: 0.0.11
4
+ Summary: Python implementation of jbenet's multiaddr
5
+ Author-email: Steven Buss <steven.buss@gmail.com>
6
+ Maintainer: acul71
7
+ Maintainer-email: pacrob <pacrob@protonmail.com>, Manu Sheel Gupta <manu@seeta.in>
8
+ License: MIT License
9
+ Project-URL: Homepage, https://github.com/multiformats/py-multiaddr
10
+ Project-URL: Download, https://github.com/multiformats/py-multiaddr/tarball/0.0.11
11
+ Keywords: multiaddr
12
+ Classifier: Development Status :: 2 - Pre-Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Natural Language :: English
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Requires-Python: <4.0,>=3.10
22
+ Description-Content-Type: text/x-rst
23
+ License-File: LICENSE-APACHE2
24
+ License-File: LICENSE-MIT
25
+ License-File: AUTHORS
26
+ Requires-Dist: base58
27
+ Requires-Dist: dnspython>=2.7.0
28
+ Requires-Dist: idna
29
+ Requires-Dist: netaddr
30
+ Requires-Dist: psutil
31
+ Requires-Dist: py-cid>=0.3.1
32
+ Requires-Dist: py-multicodec>=0.2.0
33
+ Requires-Dist: trio-typing>=0.0.4
34
+ Requires-Dist: trio>=0.26.0
35
+ Requires-Dist: varint
36
+ Provides-Extra: dev
37
+ Requires-Dist: Sphinx>=5.0.0; extra == "dev"
38
+ Requires-Dist: build>=0.9.0; extra == "dev"
39
+ Requires-Dist: bump_my_version>=1.2.0; extra == "dev"
40
+ Requires-Dist: coverage>=6.5.0; extra == "dev"
41
+ Requires-Dist: mypy; extra == "dev"
42
+ Requires-Dist: pre-commit; extra == "dev"
43
+ Requires-Dist: pyrefly; extra == "dev"
44
+ Requires-Dist: pyright; extra == "dev"
45
+ Requires-Dist: pytest; extra == "dev"
46
+ Requires-Dist: pytest-cov; extra == "dev"
47
+ Requires-Dist: pytest-runner; extra == "dev"
48
+ Requires-Dist: pytest-trio>=0.5.2; extra == "dev"
49
+ Requires-Dist: ruff; extra == "dev"
50
+ Requires-Dist: towncrier<25,>=24; extra == "dev"
51
+ Requires-Dist: tox>=4.10.0; extra == "dev"
52
+ Requires-Dist: twine; extra == "dev"
53
+ Requires-Dist: types-netaddr; extra == "dev"
54
+ Requires-Dist: types-psutil; extra == "dev"
55
+ Requires-Dist: watchdog>=3.0.0; extra == "dev"
56
+ Requires-Dist: wheel>=0.31.0; extra == "dev"
57
+ Dynamic: license-file
58
+
59
+ py-multiaddr
60
+ ==========================
61
+
62
+ .. image:: https://img.shields.io/pypi/v/multiaddr.svg
63
+ :target: https://pypi.python.org/pypi/multiaddr
64
+
65
+ .. image:: https://github.com/multiformats/py-multiaddr/actions/workflows/ci.yml/badge.svg
66
+ :target: https://github.com/multiformats/py-multiaddr/actions
67
+
68
+ .. image:: https://codecov.io/github/multiformats/py-multiaddr/coverage.svg?branch=master
69
+ :target: https://codecov.io/github/multiformats/py-multiaddr?branch=master
70
+
71
+ .. image:: https://readthedocs.org/projects/multiaddr/badge/?version=latest
72
+ :target: https://readthedocs.org/projects/multiaddr/?badge=latest
73
+ :alt: Documentation Status
74
+ ..
75
+
76
+ multiaddr_ implementation in Python
77
+
78
+ .. _multiaddr: https://github.com/multiformats/multiaddr
79
+
80
+ ..
81
+
82
+
83
+ .. contents:: :local:
84
+
85
+ Installation
86
+ ============
87
+
88
+ .. code-block:: bash
89
+
90
+ pip install multiaddr
91
+
92
+ Requirements
93
+ ------------
94
+
95
+ - Python 3.10+
96
+ - trio (for async DNS resolution)
97
+
98
+ Usage
99
+ =====
100
+
101
+ Simple
102
+ ------
103
+
104
+ .. code-block:: python
105
+
106
+ from multiaddr import Multiaddr
107
+
108
+ # construct from a string
109
+ m1 = Multiaddr("/ip4/127.0.0.1/udp/1234")
110
+
111
+ # construct from bytes
112
+ #m2 = Multiaddr(bytes_addr=m1.to_bytes()) # deprecated
113
+ m2 = Multiaddr(m1.to_bytes())
114
+
115
+ assert str(m1) == "/ip4/127.0.0.1/udp/1234"
116
+ assert str(m1) == str(m2)
117
+ assert m1.to_bytes() == m2.to_bytes()
118
+ assert m1 == m2
119
+ assert m2 == m1
120
+ assert not (m1 != m2)
121
+ assert not (m2 != m1)
122
+
123
+
124
+ Protocols
125
+ ---------
126
+
127
+ .. code-block:: python
128
+
129
+ from multiaddr import Multiaddr
130
+
131
+ m1 = Multiaddr("/ip4/127.0.0.1/udp/1234")
132
+
133
+ # get the multiaddr protocol description objects
134
+ m1.protocols()
135
+ # [Protocol(code=4, name='ip4', size=32), Protocol(code=17, name='udp', size=16)]
136
+
137
+
138
+ En/decapsulate
139
+ --------------
140
+
141
+ .. code-block:: python
142
+
143
+ from multiaddr import Multiaddr
144
+
145
+ m1 = Multiaddr("/ip4/127.0.0.1/udp/1234")
146
+ m1.encapsulate(Multiaddr("/sctp/5678"))
147
+ # <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>
148
+ m1.decapsulate(Multiaddr("/udp"))
149
+ # <Multiaddr /ip4/127.0.0.1>
150
+
151
+ # Decapsulate by protocol code
152
+ m2 = Multiaddr("/ip4/192.168.1.1/tcp/8080/udp/1234")
153
+ m2.decapsulate_code(6) # TCP protocol code
154
+ # <Multiaddr /ip4/192.168.1.1>
155
+
156
+ # Decapsulate multiple layers
157
+ m3 = Multiaddr("/ip4/10.0.0.1/tcp/443/tls/p2p/QmPeer")
158
+ m3.decapsulate_code(6) # Remove TCP and everything after
159
+ # <Multiaddr /ip4/10.0.0.1>
160
+
161
+
162
+ Tunneling
163
+ ---------
164
+
165
+ Multiaddr allows expressing tunnels very nicely.
166
+
167
+
168
+ .. code-block:: python
169
+
170
+ printer = Multiaddr("/ip4/192.168.0.13/tcp/80")
171
+ proxy = Multiaddr("/ip4/10.20.30.40/tcp/443")
172
+ printerOverProxy = proxy.encapsulate(printer)
173
+ print(printerOverProxy)
174
+ # /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80
175
+
176
+ proxyAgain = printerOverProxy.decapsulate(printer)
177
+ print(proxyAgain)
178
+ # /ip4/10.20.30.40/tcp/443
179
+
180
+ DNS Resolution
181
+ --------------
182
+
183
+ Multiaddr supports DNS-based address resolution using the DNSADDR protocol. This is particularly useful for resolving bootstrap node addresses and maintaining peer IDs during resolution.
184
+
185
+
186
+ .. code-block:: python
187
+
188
+ from multiaddr import Multiaddr
189
+ import trio
190
+
191
+ # Basic DNS resolution
192
+ ma = Multiaddr("/dns/example.com")
193
+ resolved = await ma.resolve()
194
+ print(resolved)
195
+ # [Multiaddr("/ip4/93.184.216.34"), Multiaddr("/ip6/2606:2800:220:1:248:1893:25c8:1946")]
196
+
197
+ # DNSADDR with peer ID (bootstrap node style)
198
+ ma_with_peer = Multiaddr("/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN")
199
+ resolved_with_peer = await ma_with_peer.resolve()
200
+ print(resolved_with_peer)
201
+ # [Multiaddr("/ip4/147.75.83.83/tcp/4001/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN")]
202
+
203
+ # DNS4 and DNS6 resolution (IPv4/IPv6 specific)
204
+ ma_dns4 = Multiaddr("/dns4/example.com/tcp/443")
205
+ resolved_dns4 = await ma_dns4.resolve()
206
+ print(resolved_dns4)
207
+ # [Multiaddr("/ip4/93.184.216.34/tcp/443")]
208
+
209
+ ma_dns6 = Multiaddr("/dns6/example.com/tcp/443")
210
+ resolved_dns6 = await ma_dns6.resolve()
211
+ print(resolved_dns6)
212
+ # [Multiaddr("/ip6/2606:2800:220:1:248:1893:25c8:1946/tcp/443")]
213
+
214
+ # Using the DNS resolver directly
215
+ from multiaddr.resolvers import DNSResolver
216
+ resolver = DNSResolver()
217
+ resolved = await resolver.resolve(ma)
218
+ print(resolved)
219
+ # [Multiaddr("/ip4/93.184.216.34"), Multiaddr("/ip6/2606:2800:220:1:248:1893:25c8:1946")]
220
+
221
+ # Peer ID preservation test
222
+ original_peer_id = ma_with_peer.get_peer_id()
223
+ print(f"Original peer ID: {original_peer_id}")
224
+ # Original peer ID: QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN
225
+
226
+ for resolved_addr in resolved_with_peer:
227
+ preserved_peer_id = resolved_addr.get_peer_id()
228
+ print(f"Resolved peer ID: {preserved_peer_id}")
229
+ # Resolved peer ID: QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN
230
+
231
+ 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.
232
+
233
+ Thin Waist Address Validation
234
+ -----------------------------
235
+
236
+ 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.
237
+
238
+
239
+ .. code-block:: python
240
+
241
+ from multiaddr import Multiaddr
242
+ from multiaddr.utils import get_thin_waist_addresses, get_network_addrs
243
+
244
+ # Network interface discovery
245
+ ipv4_addrs = get_network_addrs(4)
246
+ print(f"Available IPv4 addresses: {ipv4_addrs}")
247
+ # Available IPv4 addresses: ['192.168.1.12', '10.152.168.99']
248
+
249
+ # Specific address (no expansion)
250
+ addr = Multiaddr("/ip4/192.168.1.100/tcp/8080")
251
+ result = get_thin_waist_addresses(addr)
252
+ print(result)
253
+ # [<Multiaddr /ip4/192.168.1.100/tcp/8080>]
254
+
255
+ # IPv4 wildcard expansion
256
+ addr = Multiaddr("/ip4/0.0.0.0/tcp/8080")
257
+ result = get_thin_waist_addresses(addr)
258
+ print(result)
259
+ # [<Multiaddr /ip4/192.168.1.12/tcp/8080>, <Multiaddr /ip4/10.152.168.99/tcp/8080>]
260
+
261
+ # IPv6 wildcard expansion
262
+ addr = Multiaddr("/ip6/::/tcp/8080")
263
+ result = get_thin_waist_addresses(addr)
264
+ print(result)
265
+ # [<Multiaddr /ip6/::1/tcp/8080>, <Multiaddr /ip6/fd9b:9eba:8224:1:41a1:8939:231a:b414/tcp/8080>]
266
+
267
+ # Port override
268
+ addr = Multiaddr("/ip4/0.0.0.0/tcp/8080")
269
+ result = get_thin_waist_addresses(addr, port=9000)
270
+ print(result)
271
+ # [<Multiaddr /ip4/192.168.1.12/tcp/9000>, <Multiaddr /ip4/10.152.168.99/tcp/9000>]
272
+
273
+ # UDP transport support
274
+ addr = Multiaddr("/ip4/0.0.0.0/udp/1234")
275
+ result = get_thin_waist_addresses(addr)
276
+ print(result)
277
+ # [<Multiaddr /ip4/192.168.1.12/udp/1234>, <Multiaddr /ip4/10.152.168.99/udp/1234>]
278
+
279
+ # Server binding scenario
280
+ wildcard = Multiaddr("/ip4/0.0.0.0/tcp/8080")
281
+ interfaces = get_thin_waist_addresses(wildcard)
282
+ print("Available interfaces for server binding:")
283
+ for i, interface in enumerate(interfaces, 1):
284
+ print(f" {i}. {interface}")
285
+ # Available interfaces for server binding:
286
+ # 1. /ip4/192.168.1.12/tcp/8080
287
+ # 2. /ip4/10.152.168.99/tcp/8080
288
+
289
+ For comprehensive examples including error handling, practical usage scenarios, and detailed network interface information, see the `thin waist examples <https://github.com/multiformats/py-multiaddr/tree/master/examples/thin_waist>`_ in the examples directory.
290
+
291
+ Features
292
+ ========
293
+
294
+ - **Multiaddr Protocol Support**: Full support for the multiaddr specification
295
+ - **DNS Resolution**: Async DNS and DNSADDR resolution with trio
296
+ - **Thin Waist Validation**: Network interface discovery and wildcard expansion
297
+ - **Protocol Support**: IPv4, IPv6, TCP, UDP, DNS, DNS4, DNS6, DNSADDR, p2p, p2p-circuit, onion, onion3, quic, tls, and more
298
+ - **Type Safety**: Full type hints and mypy support
299
+ - **Modern Python**: Python 3.10+ support with modern tooling
300
+
301
+ Maintainers
302
+ ===========
303
+
304
+ Original author: `@sbuss`_.
305
+
306
+ Current maintainers: `@acul71`_, `@pacrob`_, `@manusheel`_.
307
+
308
+ Contribute
309
+ ==========
310
+
311
+ Contributions welcome. Please check out `the issues`_.
312
+
313
+ Check out our `contributing document`_ for more information on how we work, and about contributing in general.
314
+ Please be aware that all interactions related to multiformats are subject to the IPFS `Code of Conduct`_.
315
+
316
+ Development
317
+ -----------
318
+
319
+ For development setup, see `py-multiaddr contributing`_.
320
+
321
+ .. code-block:: bash
322
+
323
+ # Clone the repository
324
+ git clone https://github.com/multiformats/py-multiaddr.git
325
+ cd py-multiaddr
326
+
327
+ # Install in development mode
328
+ pip install -e ".[dev]"
329
+
330
+ # Run the development workflow
331
+ make pr
332
+
333
+ License
334
+ =======
335
+
336
+ Dual-licensed:
337
+
338
+ - `MIT`_ © 2014 Steven Buss
339
+ - `Apache 2`_ © 2014 Steven Buss
340
+
341
+ .. _the issues: https://github.com/multiformats/py-multiaddr/issues
342
+ .. _contributing document: https://github.com/multiformats/multiformats/blob/master/contributing.md
343
+ .. _py-multiaddr contributing: https://github.com/multiformats/py-multiaddr/blob/master/CONTRIBUTING.rst
344
+ .. _Code of Conduct: https://github.com/ipfs/community/blob/master/code-of-conduct.md
345
+ .. _standard-readme: https://github.com/RichardLitt/standard-readme
346
+ .. _MIT: LICENSE-MIT
347
+ .. _Apache 2: LICENSE-APACHE2
348
+ .. _`@sbuss`: https://github.com/sbuss
349
+ .. _`@acul71`: https://github.com/acul71
350
+ .. _`@pacrob`: https://github.com/pacrob
351
+ .. _`@manusheel`: https://github.com/manusheel