basic-ipfs 1.0.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.
- basic_ipfs-1.0.0/LICENSE +21 -0
- basic_ipfs-1.0.0/MANIFEST.in +7 -0
- basic_ipfs-1.0.0/PKG-INFO +343 -0
- basic_ipfs-1.0.0/README.md +299 -0
- basic_ipfs-1.0.0/SECURITY.md +177 -0
- basic_ipfs-1.0.0/basic_ipfs/__init__.py +2229 -0
- basic_ipfs-1.0.0/basic_ipfs/cli.py +301 -0
- basic_ipfs-1.0.0/basic_ipfs/kubo_checksums.py +28 -0
- basic_ipfs-1.0.0/basic_ipfs/py.typed +0 -0
- basic_ipfs-1.0.0/basic_ipfs.egg-info/PKG-INFO +343 -0
- basic_ipfs-1.0.0/basic_ipfs.egg-info/SOURCES.txt +21 -0
- basic_ipfs-1.0.0/basic_ipfs.egg-info/dependency_links.txt +1 -0
- basic_ipfs-1.0.0/basic_ipfs.egg-info/entry_points.txt +2 -0
- basic_ipfs-1.0.0/basic_ipfs.egg-info/requires.txt +9 -0
- basic_ipfs-1.0.0/basic_ipfs.egg-info/top_level.txt +1 -0
- basic_ipfs-1.0.0/pyproject.toml +83 -0
- basic_ipfs-1.0.0/setup.cfg +4 -0
- basic_ipfs-1.0.0/tests/test_basic.py +344 -0
- basic_ipfs-1.0.0/tests/test_cli.py +83 -0
- basic_ipfs-1.0.0/tests/test_concurrency.py +94 -0
- basic_ipfs-1.0.0/tests/test_download.py +408 -0
- basic_ipfs-1.0.0/tests/test_two_node.py +126 -0
- basic_ipfs-1.0.0/tests/test_unit.py +904 -0
basic_ipfs-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Luke Profits
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: basic-ipfs
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: An intentionally tiny IPFS library for Python. Auto-manages a real Kubo node.
|
|
5
|
+
Author: Luke Profits
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 Luke Profits
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/lukeprofits/basic-ipfs
|
|
29
|
+
Classifier: Programming Language :: Python :: 3
|
|
30
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
31
|
+
Classifier: Operating System :: OS Independent
|
|
32
|
+
Requires-Python: >=3.9
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
License-File: LICENSE
|
|
35
|
+
Requires-Dist: requests>=2.28
|
|
36
|
+
Requires-Dist: platformdirs>=3.0
|
|
37
|
+
Provides-Extra: dev
|
|
38
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
39
|
+
Requires-Dist: build>=1.0; extra == "dev"
|
|
40
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
41
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
42
|
+
Requires-Dist: types-requests; extra == "dev"
|
|
43
|
+
Dynamic: license-file
|
|
44
|
+
|
|
45
|
+
# basic-ipfs
|
|
46
|
+
|
|
47
|
+
An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under the hood.
|
|
48
|
+
|
|
49
|
+
### Description
|
|
50
|
+
|
|
51
|
+
`basic-ipfs` does exactly five things:
|
|
52
|
+
|
|
53
|
+
- Add a file or bytes to [IPFS](https://ipfs.tech/) and pin it (returns a [CID](https://docs.ipfs.tech/concepts/content-addressing/))
|
|
54
|
+
- Announce a file or bytes to IPFS without pinning (returns a CID — content may be GC'd)
|
|
55
|
+
- Get content back by CID (as bytes, or written to disk)
|
|
56
|
+
- Pin one CID or a list of CIDs (so they never get garbage-collected)
|
|
57
|
+
- Unpin one CID or a list of CIDs (idempotent — safe to re-run)
|
|
58
|
+
|
|
59
|
+
It also runs and manages a real [Kubo](https://github.com/ipfs/kubo) node for you — auto-downloaded on first use, auto-shutdown on exit. No daemon to install, no config files to edit, no accounts. (See [Privacy](#privacy) below — the default daemon does join the public IPFS network.)
|
|
60
|
+
|
|
61
|
+
I made `basic-ipfs` because no other Python packages make it this simple. Every existing client assumes you already have an IPFS daemon running. This one just works.
|
|
62
|
+
|
|
63
|
+
If it does exactly what you need → great, use it. If it doesn't → don't use it. Simple as that.
|
|
64
|
+
|
|
65
|
+
### Install
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
pip install basic-ipfs
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
First call downloads the Kubo binary (~115 MB, SHA-512 verified) into your per-user data directory (`~/.local/share/basic_ipfs/bin/<platform>/ipfs` on Linux; `platformdirs` picks the right path per OS) and starts it as a background subprocess. The daemon stops automatically when your program exits.
|
|
72
|
+
|
|
73
|
+
### Usage
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import basic_ipfs
|
|
77
|
+
|
|
78
|
+
# Add — pins content permanently so it's never garbage-collected
|
|
79
|
+
cid = basic_ipfs.add("photo.jpg")
|
|
80
|
+
cid = basic_ipfs.add(b"hello world")
|
|
81
|
+
|
|
82
|
+
# Pass provide=False to skip the public-DHT announce (content stays
|
|
83
|
+
# locally addressable, but its presence is not broadcast)
|
|
84
|
+
cid = basic_ipfs.add(b"private data", provide=False)
|
|
85
|
+
|
|
86
|
+
# Announce — adds to IPFS without pinning; content may be GC'd later
|
|
87
|
+
cid = basic_ipfs.announce("photo.jpg")
|
|
88
|
+
cid = basic_ipfs.announce(b"temporary data")
|
|
89
|
+
|
|
90
|
+
# Just compute the CID locally — does NOT store, pin, or announce anything.
|
|
91
|
+
# Useful for previewing the CID of content you have not yet decided to publish.
|
|
92
|
+
cid = basic_ipfs.compute_cid_locally(b"hello world")
|
|
93
|
+
cid = basic_ipfs.compute_cid_locally("photo.jpg")
|
|
94
|
+
|
|
95
|
+
# Get — returns bytes, or writes to disk if you pass an output path
|
|
96
|
+
data = basic_ipfs.get(cid)
|
|
97
|
+
basic_ipfs.get(cid, "copy.jpg")
|
|
98
|
+
|
|
99
|
+
# Pin — one CID, or a whole list (one HTTP round-trip per ~500 CIDs)
|
|
100
|
+
basic_ipfs.pin(cid)
|
|
101
|
+
basic_ipfs.pin([cid1, cid2, cid3, ...])
|
|
102
|
+
|
|
103
|
+
# Unpin — same shape, always idempotent
|
|
104
|
+
basic_ipfs.unpin(cid)
|
|
105
|
+
basic_ipfs.unpin([cid1, cid2, cid3, ...])
|
|
106
|
+
|
|
107
|
+
# List all pinned CIDs
|
|
108
|
+
cids = basic_ipfs.get_all_pins() # → ['Qm...', 'baf...', ...]
|
|
109
|
+
|
|
110
|
+
# Debug info
|
|
111
|
+
basic_ipfs.status() # {peer_id, agent_version, repo_size_bytes, pinned_cids, ...}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
That's the core API. There are also helpers for networking, private
|
|
115
|
+
networks, identity rotation, and lockdown — see [Privacy](#privacy).
|
|
116
|
+
|
|
117
|
+
Explicit lifecycle, if you want it (you usually don't — the daemon starts lazily on the first call and stops on process exit):
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
basic_ipfs.start()
|
|
121
|
+
basic_ipfs.stop()
|
|
122
|
+
|
|
123
|
+
with basic_ipfs.node():
|
|
124
|
+
basic_ipfs.add(b"hi")
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
All failures raise `basic_ipfs.IPFSError`. Subclasses, all with actionable messages:
|
|
128
|
+
|
|
129
|
+
- `IPFSBinaryNotFound` — Kubo missing and auto-download failed (no network, disk full, unsupported platform).
|
|
130
|
+
- `IPFSDaemonTimeout` — daemon didn't reach a healthy state in 60 s.
|
|
131
|
+
- `IPFSOperationError` — an `/api/v0/...` call returned an error.
|
|
132
|
+
- `IPFSPortInUse` — `API_PORT` (default 5001) is bound by something that isn't ours. Set `basic_ipfs.API_PORT` to something free.
|
|
133
|
+
- `IPFSRepoLocked` — another Kubo daemon already owns the repo. One process per repo.
|
|
134
|
+
- `IPFSRepoCorrupt` — repo on disk failed a sanity check. Investigate; don't auto-delete.
|
|
135
|
+
|
|
136
|
+
### CLI
|
|
137
|
+
|
|
138
|
+
Installing the package also adds a `basic-ipfs` command:
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
basic-ipfs status
|
|
142
|
+
basic-ipfs add photo.jpg # prints the CID, pins content
|
|
143
|
+
basic-ipfs announce photo.jpg # prints the CID, no pin (may be GC'd)
|
|
144
|
+
basic-ipfs add-folder ./mydir # recursive add + pin
|
|
145
|
+
basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
|
|
146
|
+
basic-ipfs get <cid> [output-path] # stdout or file
|
|
147
|
+
basic-ipfs pin <cid> [<cid> ...]
|
|
148
|
+
basic-ipfs unpin <cid> [<cid> ...]
|
|
149
|
+
basic-ipfs is-pinned <cid> # exit 0 if pinned, 1 if not
|
|
150
|
+
basic-ipfs exists <cid> # exit 0 if locally available
|
|
151
|
+
basic-ipfs pins # list all pinned CIDs
|
|
152
|
+
basic-ipfs gc # run garbage collection
|
|
153
|
+
|
|
154
|
+
# Networking
|
|
155
|
+
basic-ipfs peers # list connected peers
|
|
156
|
+
basic-ipfs my-addr # this node's shareable multiaddrs
|
|
157
|
+
basic-ipfs connect <multiaddr> # dial a peer
|
|
158
|
+
|
|
159
|
+
# Privacy
|
|
160
|
+
basic-ipfs create-private-network # generate swarm key (run before first op)
|
|
161
|
+
basic-ipfs join-private-network <key> # join an existing private network
|
|
162
|
+
basic-ipfs network-key # print this node's swarm key
|
|
163
|
+
basic-ipfs rotate-identity # new peer ID; daemon must be stopped
|
|
164
|
+
basic-ipfs lockdown # disable DHT, bootstrap, gateway fetch
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Config
|
|
168
|
+
|
|
169
|
+
Override module variables **before** the first call if you want non-defaults:
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
import basic_ipfs
|
|
173
|
+
|
|
174
|
+
basic_ipfs.APP_NAME = "MyApp" # changes default repo location
|
|
175
|
+
basic_ipfs.REPO_PATH = "/mnt/data/ipfs" # or pin an exact path
|
|
176
|
+
basic_ipfs.KUBO_VERSION = "v0.40.1" # must be in kubo_checksums.py
|
|
177
|
+
basic_ipfs.API_PORT = 5099 # if 5001 is taken
|
|
178
|
+
basic_ipfs.GATEWAY_PORT = 8099 # if 8080 is taken (or running 2 nodes)
|
|
179
|
+
basic_ipfs.SWARM_ADDRESSES = ["/ip4/127.0.0.1/tcp/4001"] # loopback-only swarm
|
|
180
|
+
basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
|
|
184
|
+
|
|
185
|
+
### Two-node example
|
|
186
|
+
|
|
187
|
+
Anything you `add()` on one machine can be `get()`-ed on another that knows
|
|
188
|
+
your peer address. Smallest possible demo:
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
# Node A
|
|
192
|
+
import basic_ipfs
|
|
193
|
+
basic_ipfs.start()
|
|
194
|
+
ipv4, _ = basic_ipfs.my_node_multiaddress()
|
|
195
|
+
print("share this with node B:", ipv4)
|
|
196
|
+
cid = basic_ipfs.add(b"hello from A")
|
|
197
|
+
print("share this CID:", cid)
|
|
198
|
+
input("press enter to stop…")
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
# Node B
|
|
203
|
+
import basic_ipfs
|
|
204
|
+
basic_ipfs.start()
|
|
205
|
+
basic_ipfs.connect_to_node("<ipv4 from node A>")
|
|
206
|
+
print(basic_ipfs.get("<cid from node A>")) # → b"hello from A"
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
For an isolated network where only your nodes can see each other, use
|
|
210
|
+
`create_private_network()` on the first node and `join_private_network(key)`
|
|
211
|
+
on the rest, both *before* `start()`. See [Privacy](#privacy) below.
|
|
212
|
+
|
|
213
|
+
### Troubleshooting
|
|
214
|
+
|
|
215
|
+
**`IPFSPortInUse` on startup.** Something else is on port 5001 (often another
|
|
216
|
+
IPFS daemon you forgot about, or some unrelated dev service). Either stop it,
|
|
217
|
+
or pick a different port *before* the first call:
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
import basic_ipfs
|
|
221
|
+
basic_ipfs.API_PORT = 5099
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
**`IPFSRepoLocked` on startup.** Another `basic-ipfs`-using process owns the
|
|
225
|
+
repo. Run only one process per repo — or set `basic_ipfs.REPO_PATH` to a
|
|
226
|
+
different path before starting.
|
|
227
|
+
|
|
228
|
+
**Auto-download fails (corporate proxy / firewall).** The downloader honors
|
|
229
|
+
the standard environment variables:
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
HTTPS_PROXY=http://corp-proxy:3128 \
|
|
233
|
+
REQUESTS_CA_BUNDLE=/etc/ssl/corp-ca.pem \
|
|
234
|
+
python your_script.py
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
If outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
|
|
238
|
+
`<user_data_dir>/basic_ipfs/bin/<platform>/ipfs` (or `ipfs.exe` on Windows)
|
|
239
|
+
and `basic-ipfs` will skip the download entirely. The bundled
|
|
240
|
+
`<site-packages>/basic_ipfs/bin/<platform>/ipfs` path is also honoured
|
|
241
|
+
for PyInstaller / Briefcase deploys. Supported platform strings:
|
|
242
|
+
`linux-amd64`, `linux-arm64`, `linux-riscv64`, `darwin-amd64`,
|
|
243
|
+
`darwin-arm64`, `windows-amd64`.
|
|
244
|
+
|
|
245
|
+
**Alpine / musl Linux.** Kubo upstream ships glibc binaries only.
|
|
246
|
+
`apk add gcompat` may be enough; otherwise place a musl-compatible
|
|
247
|
+
`ipfs` binary at the path above.
|
|
248
|
+
|
|
249
|
+
**32-bit ARM (Raspberry Pi 3 and older).** Kubo no longer publishes 32-bit
|
|
250
|
+
ARM builds. Run a 64-bit OS (e.g. Raspberry Pi OS 64-bit) on Pi 4/5.
|
|
251
|
+
|
|
252
|
+
**Slow first run.** Auto-download is ~115 MB. Subsequent starts are fast
|
|
253
|
+
(daemon comes up in ~1–3 s). The binary lives in `platformdirs.user_data_dir("basic_ipfs")`
|
|
254
|
+
so it survives reinstalls. To wipe it, delete that directory.
|
|
255
|
+
|
|
256
|
+
**Want to inspect the daemon log.** It's at
|
|
257
|
+
`<repo>/basic_ipfs_daemon.log` (rotated at 5 MB, one `.old` kept).
|
|
258
|
+
|
|
259
|
+
### Security
|
|
260
|
+
|
|
261
|
+
Auto-download is verified against an SHA-512 hash baked into the wheel
|
|
262
|
+
(`basic_ipfs/kubo_checksums.py`) using a constant-time compare. Versions
|
|
263
|
+
not in the table are refused — fetching a digest from the same origin as
|
|
264
|
+
the archive adds no real protection, so the install is fail-closed. The
|
|
265
|
+
download also pins its redirect target to `*.ipfs.tech` at every hop in
|
|
266
|
+
the chain (not just the final URL).
|
|
267
|
+
|
|
268
|
+
Two trust assumptions worth knowing before deploying on a shared host:
|
|
269
|
+
|
|
270
|
+
- **The local Kubo HTTP API on `127.0.0.1:5001` is unauthenticated.**
|
|
271
|
+
Any process running as the same user can drive the full Kubo API,
|
|
272
|
+
including `key/*` and `config`. Single-user dev boxes are fine;
|
|
273
|
+
multi-tenant hosts need additional hardening (`API.Authorizations`).
|
|
274
|
+
- **`connect_to_node(multiaddr)` forwards its argument verbatim.** If
|
|
275
|
+
your code feeds untrusted input into it, the daemon becomes an SSRF
|
|
276
|
+
probe.
|
|
277
|
+
|
|
278
|
+
See [`SECURITY.md`](SECURITY.md) for the full threat model and how to
|
|
279
|
+
verify the binary manually.
|
|
280
|
+
|
|
281
|
+
### Privacy
|
|
282
|
+
|
|
283
|
+
**By default, the daemon joins the public IPFS network.** That has real
|
|
284
|
+
consequences you should understand before publishing anything sensitive:
|
|
285
|
+
|
|
286
|
+
- **CIDs are advertised.** `add()` announces the content's CID to the
|
|
287
|
+
public DHT. Anyone monitoring the DHT (and crawlers do) can record that
|
|
288
|
+
your node holds that CID. Pass `provide=False` to skip the announce —
|
|
289
|
+
the content is still addressable, but its presence is not broadcast.
|
|
290
|
+
- **`get()` is observable.** Fetching an unknown CID dials peers and may
|
|
291
|
+
fall back to public gateways operated by third parties (Protocol Labs,
|
|
292
|
+
Cloudflare). Those parties learn what you asked for.
|
|
293
|
+
- **Peer ID is persistent.** The repo is created once and reused, so all
|
|
294
|
+
your IPFS activity over time is linkable to one stable peer ID.
|
|
295
|
+
- **Bootstrap nodes are third parties.** The daemon dials Kubo's stock
|
|
296
|
+
bootstrap list on startup (Protocol Labs / Cloudflare hosts).
|
|
297
|
+
- **Swarm port is exposed.** Kubo listens on `0.0.0.0:4001` for inbound
|
|
298
|
+
peers; on a multi-tenant or hostile LAN, treat that port like any other
|
|
299
|
+
public service.
|
|
300
|
+
|
|
301
|
+
For non-public data, you have three escape hatches — pick what fits:
|
|
302
|
+
|
|
303
|
+
```python
|
|
304
|
+
import basic_ipfs
|
|
305
|
+
|
|
306
|
+
# 1. Per-call: skip the DHT announce on a single add()
|
|
307
|
+
cid = basic_ipfs.add(b"private", provide=False)
|
|
308
|
+
|
|
309
|
+
# 2. Private network: only peers with the same 256-bit swarm key can
|
|
310
|
+
# connect. Run BEFORE start() / the first IPFS operation.
|
|
311
|
+
key = basic_ipfs.create_private_network()
|
|
312
|
+
# share key + multiaddr with peers via a trusted channel
|
|
313
|
+
|
|
314
|
+
# 3. Lockdown: disable the public DHT, bootstrap dialing, gateway
|
|
315
|
+
# fetch, and pin the swarm listener to loopback. Right starting
|
|
316
|
+
# point for encrypted-content stores or air-gapped pipelines.
|
|
317
|
+
basic_ipfs.lockdown_mode()
|
|
318
|
+
|
|
319
|
+
# Bonus: rotate the libp2p keypair to sever peer-ID linkability with
|
|
320
|
+
# prior runs (daemon must be stopped first; pins are preserved).
|
|
321
|
+
new_peer_id = basic_ipfs.rotate_identity()
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
A private network refuses connections from any peer without the matching
|
|
325
|
+
swarm key, so the DHT/bootstrap concerns above do not apply. See
|
|
326
|
+
[`SECURITY.md`](SECURITY.md) for the full threat model.
|
|
327
|
+
|
|
328
|
+
### How it works
|
|
329
|
+
|
|
330
|
+
`basic-ipfs` bundles the reference IPFS implementation — [Kubo](https://github.com/ipfs/kubo), the Go daemon maintained by Protocol Labs — and runs it as a subprocess. Your Python calls are translated into HTTP requests to Kubo's local `/api/v0` endpoint.
|
|
331
|
+
|
|
332
|
+
- **Auto-download:** the Kubo binary fetches from `dist.ipfs.tech` on first use, checksum-verified, and cached. The Python wheel itself stays tiny (~28 KB, `py3-none-any`) because it ships no binaries.
|
|
333
|
+
- **Content is immutable:** a CID is a hash of the content. The same bytes always produce the same CID, anywhere in the world.
|
|
334
|
+
- **Pinning is persistence:** Kubo garbage-collects unpinned content. `pin()` marks content permanent. `unpin()` undoes that.
|
|
335
|
+
- **PyInstaller / Briefcase friendly:** respects `sys._MEIPASS`, so bundled apps find the binary correctly.
|
|
336
|
+
|
|
337
|
+
### Contributing
|
|
338
|
+
|
|
339
|
+
If you want to add functionality, open a PR. I'll merge it if it keeps the library simple and matches the existing patterns.
|
|
340
|
+
|
|
341
|
+
### License
|
|
342
|
+
|
|
343
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
# basic-ipfs
|
|
2
|
+
|
|
3
|
+
An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under the hood.
|
|
4
|
+
|
|
5
|
+
### Description
|
|
6
|
+
|
|
7
|
+
`basic-ipfs` does exactly five things:
|
|
8
|
+
|
|
9
|
+
- Add a file or bytes to [IPFS](https://ipfs.tech/) and pin it (returns a [CID](https://docs.ipfs.tech/concepts/content-addressing/))
|
|
10
|
+
- Announce a file or bytes to IPFS without pinning (returns a CID — content may be GC'd)
|
|
11
|
+
- Get content back by CID (as bytes, or written to disk)
|
|
12
|
+
- Pin one CID or a list of CIDs (so they never get garbage-collected)
|
|
13
|
+
- Unpin one CID or a list of CIDs (idempotent — safe to re-run)
|
|
14
|
+
|
|
15
|
+
It also runs and manages a real [Kubo](https://github.com/ipfs/kubo) node for you — auto-downloaded on first use, auto-shutdown on exit. No daemon to install, no config files to edit, no accounts. (See [Privacy](#privacy) below — the default daemon does join the public IPFS network.)
|
|
16
|
+
|
|
17
|
+
I made `basic-ipfs` because no other Python packages make it this simple. Every existing client assumes you already have an IPFS daemon running. This one just works.
|
|
18
|
+
|
|
19
|
+
If it does exactly what you need → great, use it. If it doesn't → don't use it. Simple as that.
|
|
20
|
+
|
|
21
|
+
### Install
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
pip install basic-ipfs
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
First call downloads the Kubo binary (~115 MB, SHA-512 verified) into your per-user data directory (`~/.local/share/basic_ipfs/bin/<platform>/ipfs` on Linux; `platformdirs` picks the right path per OS) and starts it as a background subprocess. The daemon stops automatically when your program exits.
|
|
28
|
+
|
|
29
|
+
### Usage
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
import basic_ipfs
|
|
33
|
+
|
|
34
|
+
# Add — pins content permanently so it's never garbage-collected
|
|
35
|
+
cid = basic_ipfs.add("photo.jpg")
|
|
36
|
+
cid = basic_ipfs.add(b"hello world")
|
|
37
|
+
|
|
38
|
+
# Pass provide=False to skip the public-DHT announce (content stays
|
|
39
|
+
# locally addressable, but its presence is not broadcast)
|
|
40
|
+
cid = basic_ipfs.add(b"private data", provide=False)
|
|
41
|
+
|
|
42
|
+
# Announce — adds to IPFS without pinning; content may be GC'd later
|
|
43
|
+
cid = basic_ipfs.announce("photo.jpg")
|
|
44
|
+
cid = basic_ipfs.announce(b"temporary data")
|
|
45
|
+
|
|
46
|
+
# Just compute the CID locally — does NOT store, pin, or announce anything.
|
|
47
|
+
# Useful for previewing the CID of content you have not yet decided to publish.
|
|
48
|
+
cid = basic_ipfs.compute_cid_locally(b"hello world")
|
|
49
|
+
cid = basic_ipfs.compute_cid_locally("photo.jpg")
|
|
50
|
+
|
|
51
|
+
# Get — returns bytes, or writes to disk if you pass an output path
|
|
52
|
+
data = basic_ipfs.get(cid)
|
|
53
|
+
basic_ipfs.get(cid, "copy.jpg")
|
|
54
|
+
|
|
55
|
+
# Pin — one CID, or a whole list (one HTTP round-trip per ~500 CIDs)
|
|
56
|
+
basic_ipfs.pin(cid)
|
|
57
|
+
basic_ipfs.pin([cid1, cid2, cid3, ...])
|
|
58
|
+
|
|
59
|
+
# Unpin — same shape, always idempotent
|
|
60
|
+
basic_ipfs.unpin(cid)
|
|
61
|
+
basic_ipfs.unpin([cid1, cid2, cid3, ...])
|
|
62
|
+
|
|
63
|
+
# List all pinned CIDs
|
|
64
|
+
cids = basic_ipfs.get_all_pins() # → ['Qm...', 'baf...', ...]
|
|
65
|
+
|
|
66
|
+
# Debug info
|
|
67
|
+
basic_ipfs.status() # {peer_id, agent_version, repo_size_bytes, pinned_cids, ...}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
That's the core API. There are also helpers for networking, private
|
|
71
|
+
networks, identity rotation, and lockdown — see [Privacy](#privacy).
|
|
72
|
+
|
|
73
|
+
Explicit lifecycle, if you want it (you usually don't — the daemon starts lazily on the first call and stops on process exit):
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
basic_ipfs.start()
|
|
77
|
+
basic_ipfs.stop()
|
|
78
|
+
|
|
79
|
+
with basic_ipfs.node():
|
|
80
|
+
basic_ipfs.add(b"hi")
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
All failures raise `basic_ipfs.IPFSError`. Subclasses, all with actionable messages:
|
|
84
|
+
|
|
85
|
+
- `IPFSBinaryNotFound` — Kubo missing and auto-download failed (no network, disk full, unsupported platform).
|
|
86
|
+
- `IPFSDaemonTimeout` — daemon didn't reach a healthy state in 60 s.
|
|
87
|
+
- `IPFSOperationError` — an `/api/v0/...` call returned an error.
|
|
88
|
+
- `IPFSPortInUse` — `API_PORT` (default 5001) is bound by something that isn't ours. Set `basic_ipfs.API_PORT` to something free.
|
|
89
|
+
- `IPFSRepoLocked` — another Kubo daemon already owns the repo. One process per repo.
|
|
90
|
+
- `IPFSRepoCorrupt` — repo on disk failed a sanity check. Investigate; don't auto-delete.
|
|
91
|
+
|
|
92
|
+
### CLI
|
|
93
|
+
|
|
94
|
+
Installing the package also adds a `basic-ipfs` command:
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
basic-ipfs status
|
|
98
|
+
basic-ipfs add photo.jpg # prints the CID, pins content
|
|
99
|
+
basic-ipfs announce photo.jpg # prints the CID, no pin (may be GC'd)
|
|
100
|
+
basic-ipfs add-folder ./mydir # recursive add + pin
|
|
101
|
+
basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
|
|
102
|
+
basic-ipfs get <cid> [output-path] # stdout or file
|
|
103
|
+
basic-ipfs pin <cid> [<cid> ...]
|
|
104
|
+
basic-ipfs unpin <cid> [<cid> ...]
|
|
105
|
+
basic-ipfs is-pinned <cid> # exit 0 if pinned, 1 if not
|
|
106
|
+
basic-ipfs exists <cid> # exit 0 if locally available
|
|
107
|
+
basic-ipfs pins # list all pinned CIDs
|
|
108
|
+
basic-ipfs gc # run garbage collection
|
|
109
|
+
|
|
110
|
+
# Networking
|
|
111
|
+
basic-ipfs peers # list connected peers
|
|
112
|
+
basic-ipfs my-addr # this node's shareable multiaddrs
|
|
113
|
+
basic-ipfs connect <multiaddr> # dial a peer
|
|
114
|
+
|
|
115
|
+
# Privacy
|
|
116
|
+
basic-ipfs create-private-network # generate swarm key (run before first op)
|
|
117
|
+
basic-ipfs join-private-network <key> # join an existing private network
|
|
118
|
+
basic-ipfs network-key # print this node's swarm key
|
|
119
|
+
basic-ipfs rotate-identity # new peer ID; daemon must be stopped
|
|
120
|
+
basic-ipfs lockdown # disable DHT, bootstrap, gateway fetch
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Config
|
|
124
|
+
|
|
125
|
+
Override module variables **before** the first call if you want non-defaults:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
import basic_ipfs
|
|
129
|
+
|
|
130
|
+
basic_ipfs.APP_NAME = "MyApp" # changes default repo location
|
|
131
|
+
basic_ipfs.REPO_PATH = "/mnt/data/ipfs" # or pin an exact path
|
|
132
|
+
basic_ipfs.KUBO_VERSION = "v0.40.1" # must be in kubo_checksums.py
|
|
133
|
+
basic_ipfs.API_PORT = 5099 # if 5001 is taken
|
|
134
|
+
basic_ipfs.GATEWAY_PORT = 8099 # if 8080 is taken (or running 2 nodes)
|
|
135
|
+
basic_ipfs.SWARM_ADDRESSES = ["/ip4/127.0.0.1/tcp/4001"] # loopback-only swarm
|
|
136
|
+
basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
|
|
140
|
+
|
|
141
|
+
### Two-node example
|
|
142
|
+
|
|
143
|
+
Anything you `add()` on one machine can be `get()`-ed on another that knows
|
|
144
|
+
your peer address. Smallest possible demo:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
# Node A
|
|
148
|
+
import basic_ipfs
|
|
149
|
+
basic_ipfs.start()
|
|
150
|
+
ipv4, _ = basic_ipfs.my_node_multiaddress()
|
|
151
|
+
print("share this with node B:", ipv4)
|
|
152
|
+
cid = basic_ipfs.add(b"hello from A")
|
|
153
|
+
print("share this CID:", cid)
|
|
154
|
+
input("press enter to stop…")
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
# Node B
|
|
159
|
+
import basic_ipfs
|
|
160
|
+
basic_ipfs.start()
|
|
161
|
+
basic_ipfs.connect_to_node("<ipv4 from node A>")
|
|
162
|
+
print(basic_ipfs.get("<cid from node A>")) # → b"hello from A"
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
For an isolated network where only your nodes can see each other, use
|
|
166
|
+
`create_private_network()` on the first node and `join_private_network(key)`
|
|
167
|
+
on the rest, both *before* `start()`. See [Privacy](#privacy) below.
|
|
168
|
+
|
|
169
|
+
### Troubleshooting
|
|
170
|
+
|
|
171
|
+
**`IPFSPortInUse` on startup.** Something else is on port 5001 (often another
|
|
172
|
+
IPFS daemon you forgot about, or some unrelated dev service). Either stop it,
|
|
173
|
+
or pick a different port *before* the first call:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
import basic_ipfs
|
|
177
|
+
basic_ipfs.API_PORT = 5099
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
**`IPFSRepoLocked` on startup.** Another `basic-ipfs`-using process owns the
|
|
181
|
+
repo. Run only one process per repo — or set `basic_ipfs.REPO_PATH` to a
|
|
182
|
+
different path before starting.
|
|
183
|
+
|
|
184
|
+
**Auto-download fails (corporate proxy / firewall).** The downloader honors
|
|
185
|
+
the standard environment variables:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
HTTPS_PROXY=http://corp-proxy:3128 \
|
|
189
|
+
REQUESTS_CA_BUNDLE=/etc/ssl/corp-ca.pem \
|
|
190
|
+
python your_script.py
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
If outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
|
|
194
|
+
`<user_data_dir>/basic_ipfs/bin/<platform>/ipfs` (or `ipfs.exe` on Windows)
|
|
195
|
+
and `basic-ipfs` will skip the download entirely. The bundled
|
|
196
|
+
`<site-packages>/basic_ipfs/bin/<platform>/ipfs` path is also honoured
|
|
197
|
+
for PyInstaller / Briefcase deploys. Supported platform strings:
|
|
198
|
+
`linux-amd64`, `linux-arm64`, `linux-riscv64`, `darwin-amd64`,
|
|
199
|
+
`darwin-arm64`, `windows-amd64`.
|
|
200
|
+
|
|
201
|
+
**Alpine / musl Linux.** Kubo upstream ships glibc binaries only.
|
|
202
|
+
`apk add gcompat` may be enough; otherwise place a musl-compatible
|
|
203
|
+
`ipfs` binary at the path above.
|
|
204
|
+
|
|
205
|
+
**32-bit ARM (Raspberry Pi 3 and older).** Kubo no longer publishes 32-bit
|
|
206
|
+
ARM builds. Run a 64-bit OS (e.g. Raspberry Pi OS 64-bit) on Pi 4/5.
|
|
207
|
+
|
|
208
|
+
**Slow first run.** Auto-download is ~115 MB. Subsequent starts are fast
|
|
209
|
+
(daemon comes up in ~1–3 s). The binary lives in `platformdirs.user_data_dir("basic_ipfs")`
|
|
210
|
+
so it survives reinstalls. To wipe it, delete that directory.
|
|
211
|
+
|
|
212
|
+
**Want to inspect the daemon log.** It's at
|
|
213
|
+
`<repo>/basic_ipfs_daemon.log` (rotated at 5 MB, one `.old` kept).
|
|
214
|
+
|
|
215
|
+
### Security
|
|
216
|
+
|
|
217
|
+
Auto-download is verified against an SHA-512 hash baked into the wheel
|
|
218
|
+
(`basic_ipfs/kubo_checksums.py`) using a constant-time compare. Versions
|
|
219
|
+
not in the table are refused — fetching a digest from the same origin as
|
|
220
|
+
the archive adds no real protection, so the install is fail-closed. The
|
|
221
|
+
download also pins its redirect target to `*.ipfs.tech` at every hop in
|
|
222
|
+
the chain (not just the final URL).
|
|
223
|
+
|
|
224
|
+
Two trust assumptions worth knowing before deploying on a shared host:
|
|
225
|
+
|
|
226
|
+
- **The local Kubo HTTP API on `127.0.0.1:5001` is unauthenticated.**
|
|
227
|
+
Any process running as the same user can drive the full Kubo API,
|
|
228
|
+
including `key/*` and `config`. Single-user dev boxes are fine;
|
|
229
|
+
multi-tenant hosts need additional hardening (`API.Authorizations`).
|
|
230
|
+
- **`connect_to_node(multiaddr)` forwards its argument verbatim.** If
|
|
231
|
+
your code feeds untrusted input into it, the daemon becomes an SSRF
|
|
232
|
+
probe.
|
|
233
|
+
|
|
234
|
+
See [`SECURITY.md`](SECURITY.md) for the full threat model and how to
|
|
235
|
+
verify the binary manually.
|
|
236
|
+
|
|
237
|
+
### Privacy
|
|
238
|
+
|
|
239
|
+
**By default, the daemon joins the public IPFS network.** That has real
|
|
240
|
+
consequences you should understand before publishing anything sensitive:
|
|
241
|
+
|
|
242
|
+
- **CIDs are advertised.** `add()` announces the content's CID to the
|
|
243
|
+
public DHT. Anyone monitoring the DHT (and crawlers do) can record that
|
|
244
|
+
your node holds that CID. Pass `provide=False` to skip the announce —
|
|
245
|
+
the content is still addressable, but its presence is not broadcast.
|
|
246
|
+
- **`get()` is observable.** Fetching an unknown CID dials peers and may
|
|
247
|
+
fall back to public gateways operated by third parties (Protocol Labs,
|
|
248
|
+
Cloudflare). Those parties learn what you asked for.
|
|
249
|
+
- **Peer ID is persistent.** The repo is created once and reused, so all
|
|
250
|
+
your IPFS activity over time is linkable to one stable peer ID.
|
|
251
|
+
- **Bootstrap nodes are third parties.** The daemon dials Kubo's stock
|
|
252
|
+
bootstrap list on startup (Protocol Labs / Cloudflare hosts).
|
|
253
|
+
- **Swarm port is exposed.** Kubo listens on `0.0.0.0:4001` for inbound
|
|
254
|
+
peers; on a multi-tenant or hostile LAN, treat that port like any other
|
|
255
|
+
public service.
|
|
256
|
+
|
|
257
|
+
For non-public data, you have three escape hatches — pick what fits:
|
|
258
|
+
|
|
259
|
+
```python
|
|
260
|
+
import basic_ipfs
|
|
261
|
+
|
|
262
|
+
# 1. Per-call: skip the DHT announce on a single add()
|
|
263
|
+
cid = basic_ipfs.add(b"private", provide=False)
|
|
264
|
+
|
|
265
|
+
# 2. Private network: only peers with the same 256-bit swarm key can
|
|
266
|
+
# connect. Run BEFORE start() / the first IPFS operation.
|
|
267
|
+
key = basic_ipfs.create_private_network()
|
|
268
|
+
# share key + multiaddr with peers via a trusted channel
|
|
269
|
+
|
|
270
|
+
# 3. Lockdown: disable the public DHT, bootstrap dialing, gateway
|
|
271
|
+
# fetch, and pin the swarm listener to loopback. Right starting
|
|
272
|
+
# point for encrypted-content stores or air-gapped pipelines.
|
|
273
|
+
basic_ipfs.lockdown_mode()
|
|
274
|
+
|
|
275
|
+
# Bonus: rotate the libp2p keypair to sever peer-ID linkability with
|
|
276
|
+
# prior runs (daemon must be stopped first; pins are preserved).
|
|
277
|
+
new_peer_id = basic_ipfs.rotate_identity()
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
A private network refuses connections from any peer without the matching
|
|
281
|
+
swarm key, so the DHT/bootstrap concerns above do not apply. See
|
|
282
|
+
[`SECURITY.md`](SECURITY.md) for the full threat model.
|
|
283
|
+
|
|
284
|
+
### How it works
|
|
285
|
+
|
|
286
|
+
`basic-ipfs` bundles the reference IPFS implementation — [Kubo](https://github.com/ipfs/kubo), the Go daemon maintained by Protocol Labs — and runs it as a subprocess. Your Python calls are translated into HTTP requests to Kubo's local `/api/v0` endpoint.
|
|
287
|
+
|
|
288
|
+
- **Auto-download:** the Kubo binary fetches from `dist.ipfs.tech` on first use, checksum-verified, and cached. The Python wheel itself stays tiny (~28 KB, `py3-none-any`) because it ships no binaries.
|
|
289
|
+
- **Content is immutable:** a CID is a hash of the content. The same bytes always produce the same CID, anywhere in the world.
|
|
290
|
+
- **Pinning is persistence:** Kubo garbage-collects unpinned content. `pin()` marks content permanent. `unpin()` undoes that.
|
|
291
|
+
- **PyInstaller / Briefcase friendly:** respects `sys._MEIPASS`, so bundled apps find the binary correctly.
|
|
292
|
+
|
|
293
|
+
### Contributing
|
|
294
|
+
|
|
295
|
+
If you want to add functionality, open a PR. I'll merge it if it keeps the library simple and matches the existing patterns.
|
|
296
|
+
|
|
297
|
+
### License
|
|
298
|
+
|
|
299
|
+
MIT. See [LICENSE](LICENSE).
|