basic-ipfs 1.0.1__tar.gz → 1.3.1__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.1/basic_ipfs.egg-info → basic_ipfs-1.3.1}/PKG-INFO +162 -10
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/README.md +161 -9
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/__init__.py +830 -90
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/cli.py +5 -1
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1/basic_ipfs.egg-info}/PKG-INFO +162 -10
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/SOURCES.txt +6 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/pyproject.toml +2 -2
- basic_ipfs-1.3.1/tests/test_announcing.py +170 -0
- basic_ipfs-1.3.1/tests/test_blocks.py +104 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_download.py +69 -0
- basic_ipfs-1.3.1/tests/test_in_place.py +222 -0
- basic_ipfs-1.3.1/tests/test_ranges_and_endpoints.py +112 -0
- basic_ipfs-1.3.1/tests/test_streams.py +174 -0
- basic_ipfs-1.3.1/tests/test_topics.py +123 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_unit.py +155 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/LICENSE +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/MANIFEST.in +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/SECURITY.md +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/kubo_checksums.py +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/py.typed +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/dependency_links.txt +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/entry_points.txt +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/requires.txt +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/top_level.txt +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/setup.cfg +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_basic.py +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_cli.py +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_concurrency.py +0 -0
- {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_two_node.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: basic-ipfs
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.3.1
|
|
4
4
|
Summary: An intentionally tiny IPFS library for Python. Auto-manages a real Kubo node.
|
|
5
5
|
Author: Luke Profits
|
|
6
6
|
License: MIT License
|
|
@@ -48,7 +48,7 @@ An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under
|
|
|
48
48
|
|
|
49
49
|
### Description
|
|
50
50
|
|
|
51
|
-
`basic-ipfs` does
|
|
51
|
+
At its core `basic-ipfs` does five things:
|
|
52
52
|
|
|
53
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
54
|
- Announce a file or bytes to IPFS without pinning (returns a CID — content may be GC'd)
|
|
@@ -56,6 +56,11 @@ An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under
|
|
|
56
56
|
- Pin one CID or a list of CIDs (so they never get garbage-collected)
|
|
57
57
|
- Unpin one CID or a list of CIDs (idempotent — safe to re-run)
|
|
58
58
|
|
|
59
|
+
For a program that needs more there is a node of its own, byte-range reads,
|
|
60
|
+
peer-to-peer streams, publish/listen topics, adding a file in place, single
|
|
61
|
+
blocks, and choosing what your node announces -- each off unless you ask (see
|
|
62
|
+
below).
|
|
63
|
+
|
|
59
64
|
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
65
|
|
|
61
66
|
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.
|
|
@@ -79,8 +84,9 @@ import basic_ipfs
|
|
|
79
84
|
cid = basic_ipfs.add("photo.jpg")
|
|
80
85
|
cid = basic_ipfs.add(b"hello world")
|
|
81
86
|
|
|
82
|
-
#
|
|
83
|
-
#
|
|
87
|
+
# provide=False is passed to Kubo, which (as of 0.40) ignores it and
|
|
88
|
+
# announces every block it holds: to keep something out of the DHT, see
|
|
89
|
+
# "What your node tells the world it has".
|
|
84
90
|
cid = basic_ipfs.add(b"private data", provide=False)
|
|
85
91
|
|
|
86
92
|
# Announce — adds to IPFS without pinning; content may be GC'd later
|
|
@@ -95,6 +101,7 @@ cid = basic_ipfs.compute_cid_locally("photo.jpg")
|
|
|
95
101
|
# Get — returns bytes, or writes to disk if you pass an output path
|
|
96
102
|
data = basic_ipfs.get(cid)
|
|
97
103
|
basic_ipfs.get(cid, "copy.jpg")
|
|
104
|
+
part = basic_ipfs.get(cid, offset=1000, length=500) # just those bytes
|
|
98
105
|
|
|
99
106
|
# Pin — one CID, or a whole list (one HTTP round-trip per ~500 CIDs)
|
|
100
107
|
basic_ipfs.pin(cid)
|
|
@@ -141,7 +148,7 @@ Installing the package also adds a `basic-ipfs` command:
|
|
|
141
148
|
basic-ipfs status
|
|
142
149
|
basic-ipfs add photo.jpg # prints the CID, pins content
|
|
143
150
|
basic-ipfs announce photo.jpg # prints the CID, no pin (may be GC'd)
|
|
144
|
-
basic-ipfs add-folder ./mydir # recursive add + pin
|
|
151
|
+
basic-ipfs add-folder ./mydir # recursive add + pin (skips dotfiles; --hidden includes them)
|
|
145
152
|
basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
|
|
146
153
|
basic-ipfs get <cid> [output-path] # stdout or file
|
|
147
154
|
basic-ipfs pin <cid> [<cid> ...]
|
|
@@ -182,6 +189,143 @@ basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
|
|
|
182
189
|
|
|
183
190
|
Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
|
|
184
191
|
|
|
192
|
+
### A node of your own
|
|
193
|
+
|
|
194
|
+
The module-level functions share one daemon. A program that wants its own --
|
|
195
|
+
or several on one machine -- makes a manager and gives it its own repo and
|
|
196
|
+
ports:
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
import basic_ipfs
|
|
200
|
+
|
|
201
|
+
node = basic_ipfs.IPFSManager(
|
|
202
|
+
port=5611, # API
|
|
203
|
+
repo="/var/lib/myapp/ipfs",
|
|
204
|
+
gateway_port=8611,
|
|
205
|
+
swarm_port=4611, # the port other nodes reach it on
|
|
206
|
+
)
|
|
207
|
+
node.start()
|
|
208
|
+
cid = node.add(b"hello")
|
|
209
|
+
print(node.peer_id())
|
|
210
|
+
node.stop() # yours to stop: only the shared daemon stops itself at exit
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Anything left out follows the module settings above.
|
|
214
|
+
|
|
215
|
+
### Streams: one program talking to another
|
|
216
|
+
|
|
217
|
+
Two programs on two machines can talk through their IPFS daemons: an
|
|
218
|
+
encrypted pipe that reaches nodes behind home routers the way IPFS does.
|
|
219
|
+
Start the daemon with `streams=True`; one side listens, the other forwards.
|
|
220
|
+
|
|
221
|
+
```python
|
|
222
|
+
# Machine A -- your program listens on local port 9001
|
|
223
|
+
a = basic_ipfs.IPFSManager(streams=True)
|
|
224
|
+
a.start()
|
|
225
|
+
a.stream_listen("chat", 9001) # "chat" streams from peers arrive on 127.0.0.1:9001
|
|
226
|
+
print(a.peer_id()) # give this to B
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
# Machine B -- connect to 127.0.0.1:9002 and you are talking to the program on A
|
|
231
|
+
b = basic_ipfs.IPFSManager(streams=True)
|
|
232
|
+
b.start()
|
|
233
|
+
b.stream_forward("chat", 9002, "<peer ID of A>")
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
`stream_close("chat")` closes the listeners and forwards of that name,
|
|
237
|
+
`stream_close("chat", port=9002)` only the forward on that local port, and
|
|
238
|
+
`stream_close()` closes them all.
|
|
239
|
+
|
|
240
|
+
Two things to know. The listening side is **not told which peer connected**:
|
|
241
|
+
if your program cares who it is talking to, it must check that itself, with
|
|
242
|
+
signatures. The forwarding side does know, because it reaches the peer it
|
|
243
|
+
named or nobody. And this is a Kubo feature still marked experimental
|
|
244
|
+
(`Libp2pStreamMounting`), which is why it is off unless you ask.
|
|
245
|
+
|
|
246
|
+
### Topics: many programs hearing each other
|
|
247
|
+
|
|
248
|
+
A topic is a name. Any node may publish to it, and every node listening on it
|
|
249
|
+
hears what is published. Start the daemon with `topics=True`.
|
|
250
|
+
|
|
251
|
+
```python
|
|
252
|
+
node = basic_ipfs.IPFSManager(topics=True)
|
|
253
|
+
node.start()
|
|
254
|
+
|
|
255
|
+
def heard(data, sender): # bytes, and the peer ID that published them
|
|
256
|
+
print(sender, data)
|
|
257
|
+
|
|
258
|
+
stop = node.topic_listen("weather", heard)
|
|
259
|
+
node.topic_publish("weather", b"rain")
|
|
260
|
+
stop()
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Three things to know. A message reaches the listeners your node is connected
|
|
264
|
+
to, directly or through other listeners, so two nodes that have never met
|
|
265
|
+
need to connect first (`swarm_connect`). Nothing is stored: a node that
|
|
266
|
+
starts listening later has missed it. And this is Kubo's experimental pubsub
|
|
267
|
+
(`Pubsub.Enabled`), which Kubo's maintainers describe as tuned for IPNS and
|
|
268
|
+
may change, which is why it is off unless you ask.
|
|
269
|
+
|
|
270
|
+
### Adding a file in place
|
|
271
|
+
|
|
272
|
+
An ordinary `add` copies the file into the node's repository. For a large
|
|
273
|
+
file that is already where you want it -- on another drive, say -- the node
|
|
274
|
+
can leave it there and serve it from where it is. Start the daemon with
|
|
275
|
+
`in_place=True`.
|
|
276
|
+
|
|
277
|
+
```python
|
|
278
|
+
node = basic_ipfs.IPFSManager(repo="/home/me/node/ipfs", in_place=True)
|
|
279
|
+
node.start()
|
|
280
|
+
cid = node.add("/home/me/node/films/big.mkv", in_place=True)
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Five things to know. The file must be in the folder that holds the
|
|
284
|
+
repository (`/home/me/node` above) or below it; a link there to a folder on
|
|
285
|
+
another drive counts, so `ln -s /mnt/big /home/me/node/big` and then
|
|
286
|
+
`node.add("/home/me/node/big/film.mkv", in_place=True)` works. The file must
|
|
287
|
+
stay as it is: moved, changed or on an unplugged drive, reads of it fail
|
|
288
|
+
until it is back, and the node carries on. Unpinning never deletes the file;
|
|
289
|
+
that is yours to do. (`node.cat(cid, local_only=True)` reads only what this
|
|
290
|
+
node has and never fetches from another node, so it tells you whether the
|
|
291
|
+
file is still there: if it is not, the read fails or comes back short.)
|
|
292
|
+
Bytes the repository already holds are not taken from the file, which would
|
|
293
|
+
then be a copy nobody reads; `node.discard(cid)` deletes the repository's
|
|
294
|
+
copy first. And this is Kubo's experimental filestore
|
|
295
|
+
(`Experimental.FilestoreEnabled`), which is why it is off unless you ask.
|
|
296
|
+
|
|
297
|
+
### Blocks one at a time
|
|
298
|
+
|
|
299
|
+
For a program that builds its own DAG nodes: `block_put(data, codec="dag-pb")`
|
|
300
|
+
stores one block and returns its CID; `block_get(cid)` reads one back (from
|
|
301
|
+
the network if this node lacks it, unless `local_only=True`). A block is not
|
|
302
|
+
pinned by being put: `pin_add(cid, recursive=False)` keeps that block alone
|
|
303
|
+
and nothing it links to, and `pin_rm(cid, recursive=False)` lets it go.
|
|
304
|
+
`provide(cid)` tells the DHT this node has it, and
|
|
305
|
+
`who_has(cid, limit=20)` asks the DHT which peers say they have it
|
|
306
|
+
(peer IDs, this node's own included if it announced it).
|
|
307
|
+
|
|
308
|
+
### What your node tells the world it has
|
|
309
|
+
|
|
310
|
+
Kubo announces to the DHT **every block it has**, again every day: that is its
|
|
311
|
+
`Provide.Strategy` of `"all"`, and `add(..., provide=False)` does not change
|
|
312
|
+
it. Anyone can then look up a CID and find your node. For a program whose
|
|
313
|
+
node holds things it must not be seen to hold, start the daemon with
|
|
314
|
+
`provide_strategy="mfs"`: then only what is in the node's MFS is announced,
|
|
315
|
+
and `mfs_add(cid, "/shown/<cid>")` / `mfs_remove(path)` are how you choose.
|
|
316
|
+
`"mfs"` announces every block under what is listed; `"mfs+entities"` only
|
|
317
|
+
the root of each file. A manager given a strategy will not attach to a
|
|
318
|
+
daemon already running with another: `start()` raises rather than let it
|
|
319
|
+
announce more than you asked.
|
|
320
|
+
|
|
321
|
+
```python
|
|
322
|
+
node = basic_ipfs.IPFSManager(provide_strategy="mfs")
|
|
323
|
+
node.start()
|
|
324
|
+
cid = node.add(b"for everyone")
|
|
325
|
+
node.mfs_add(cid, f"/shown/{cid}") # announced, and kept from GC
|
|
326
|
+
node.mfs_remove(f"/shown/{cid}") # no longer announced
|
|
327
|
+
```
|
|
328
|
+
|
|
185
329
|
### Two-node example
|
|
186
330
|
|
|
187
331
|
Anything you `add()` on one machine can be `get()`-ed on another that knows
|
|
@@ -234,7 +378,9 @@ REQUESTS_CA_BUNDLE=/etc/ssl/corp-ca.pem \
|
|
|
234
378
|
python your_script.py
|
|
235
379
|
```
|
|
236
380
|
|
|
237
|
-
If
|
|
381
|
+
If `dist.ipfs.tech` cannot be reached, the first call fails in about a
|
|
382
|
+
minute with `IPFSBinaryNotFound`, naming the URL and the exact path to put
|
|
383
|
+
the binary at. If outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
|
|
238
384
|
`<user_data_dir>/basic_ipfs/bin/<platform>/ipfs` (or `ipfs.exe` on Windows)
|
|
239
385
|
and `basic-ipfs` will skip the download entirely. The bundled
|
|
240
386
|
`<site-packages>/basic_ipfs/bin/<platform>/ipfs` path is also honoured
|
|
@@ -286,8 +432,10 @@ consequences you should understand before publishing anything sensitive:
|
|
|
286
432
|
|
|
287
433
|
- **CIDs are advertised.** `add()` announces the content's CID to the
|
|
288
434
|
public DHT. Anyone monitoring the DHT (and crawlers do) can record that
|
|
289
|
-
your node holds that CID.
|
|
290
|
-
|
|
435
|
+
your node holds that CID. `provide=False` does not prevent it: Kubo
|
|
436
|
+
(as of 0.40) ignores it, and its default `Provide.Strategy` (`"all"`)
|
|
437
|
+
announces every block it holds. Start the daemon with
|
|
438
|
+
`provide_strategy="mfs"` to announce only what you list.
|
|
291
439
|
- **`get()` is observable.** Fetching an unknown CID dials peers and may
|
|
292
440
|
fall back to public gateways operated by third parties (Protocol Labs,
|
|
293
441
|
Cloudflare). Those parties learn what you asked for.
|
|
@@ -304,8 +452,12 @@ For non-public data, you have three escape hatches — pick what fits:
|
|
|
304
452
|
```python
|
|
305
453
|
import basic_ipfs
|
|
306
454
|
|
|
307
|
-
# 1.
|
|
308
|
-
|
|
455
|
+
# 1. Announce only what you choose: a node of your own that tells the
|
|
456
|
+
# DHT only what you list (add(provide=False) alone does not do this).
|
|
457
|
+
node = basic_ipfs.IPFSManager(provide_strategy="mfs")
|
|
458
|
+
node.start()
|
|
459
|
+
cid = node.add(b"private") # kept, not announced
|
|
460
|
+
node.mfs_add(cid, f"/shown/{cid}") # only if you want it found
|
|
309
461
|
|
|
310
462
|
# 2. Private network: only peers with the same 256-bit swarm key can
|
|
311
463
|
# connect. Run BEFORE start() / the first IPFS operation.
|
|
@@ -4,7 +4,7 @@ An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under
|
|
|
4
4
|
|
|
5
5
|
### Description
|
|
6
6
|
|
|
7
|
-
`basic-ipfs` does
|
|
7
|
+
At its core `basic-ipfs` does five things:
|
|
8
8
|
|
|
9
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
10
|
- Announce a file or bytes to IPFS without pinning (returns a CID — content may be GC'd)
|
|
@@ -12,6 +12,11 @@ An intentionally tiny IPFS library for Python. Zero setup, real Kubo node under
|
|
|
12
12
|
- Pin one CID or a list of CIDs (so they never get garbage-collected)
|
|
13
13
|
- Unpin one CID or a list of CIDs (idempotent — safe to re-run)
|
|
14
14
|
|
|
15
|
+
For a program that needs more there is a node of its own, byte-range reads,
|
|
16
|
+
peer-to-peer streams, publish/listen topics, adding a file in place, single
|
|
17
|
+
blocks, and choosing what your node announces -- each off unless you ask (see
|
|
18
|
+
below).
|
|
19
|
+
|
|
15
20
|
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
21
|
|
|
17
22
|
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.
|
|
@@ -35,8 +40,9 @@ import basic_ipfs
|
|
|
35
40
|
cid = basic_ipfs.add("photo.jpg")
|
|
36
41
|
cid = basic_ipfs.add(b"hello world")
|
|
37
42
|
|
|
38
|
-
#
|
|
39
|
-
#
|
|
43
|
+
# provide=False is passed to Kubo, which (as of 0.40) ignores it and
|
|
44
|
+
# announces every block it holds: to keep something out of the DHT, see
|
|
45
|
+
# "What your node tells the world it has".
|
|
40
46
|
cid = basic_ipfs.add(b"private data", provide=False)
|
|
41
47
|
|
|
42
48
|
# Announce — adds to IPFS without pinning; content may be GC'd later
|
|
@@ -51,6 +57,7 @@ cid = basic_ipfs.compute_cid_locally("photo.jpg")
|
|
|
51
57
|
# Get — returns bytes, or writes to disk if you pass an output path
|
|
52
58
|
data = basic_ipfs.get(cid)
|
|
53
59
|
basic_ipfs.get(cid, "copy.jpg")
|
|
60
|
+
part = basic_ipfs.get(cid, offset=1000, length=500) # just those bytes
|
|
54
61
|
|
|
55
62
|
# Pin — one CID, or a whole list (one HTTP round-trip per ~500 CIDs)
|
|
56
63
|
basic_ipfs.pin(cid)
|
|
@@ -97,7 +104,7 @@ Installing the package also adds a `basic-ipfs` command:
|
|
|
97
104
|
basic-ipfs status
|
|
98
105
|
basic-ipfs add photo.jpg # prints the CID, pins content
|
|
99
106
|
basic-ipfs announce photo.jpg # prints the CID, no pin (may be GC'd)
|
|
100
|
-
basic-ipfs add-folder ./mydir # recursive add + pin
|
|
107
|
+
basic-ipfs add-folder ./mydir # recursive add + pin (skips dotfiles; --hidden includes them)
|
|
101
108
|
basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
|
|
102
109
|
basic-ipfs get <cid> [output-path] # stdout or file
|
|
103
110
|
basic-ipfs pin <cid> [<cid> ...]
|
|
@@ -138,6 +145,143 @@ basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
|
|
|
138
145
|
|
|
139
146
|
Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
|
|
140
147
|
|
|
148
|
+
### A node of your own
|
|
149
|
+
|
|
150
|
+
The module-level functions share one daemon. A program that wants its own --
|
|
151
|
+
or several on one machine -- makes a manager and gives it its own repo and
|
|
152
|
+
ports:
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
import basic_ipfs
|
|
156
|
+
|
|
157
|
+
node = basic_ipfs.IPFSManager(
|
|
158
|
+
port=5611, # API
|
|
159
|
+
repo="/var/lib/myapp/ipfs",
|
|
160
|
+
gateway_port=8611,
|
|
161
|
+
swarm_port=4611, # the port other nodes reach it on
|
|
162
|
+
)
|
|
163
|
+
node.start()
|
|
164
|
+
cid = node.add(b"hello")
|
|
165
|
+
print(node.peer_id())
|
|
166
|
+
node.stop() # yours to stop: only the shared daemon stops itself at exit
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Anything left out follows the module settings above.
|
|
170
|
+
|
|
171
|
+
### Streams: one program talking to another
|
|
172
|
+
|
|
173
|
+
Two programs on two machines can talk through their IPFS daemons: an
|
|
174
|
+
encrypted pipe that reaches nodes behind home routers the way IPFS does.
|
|
175
|
+
Start the daemon with `streams=True`; one side listens, the other forwards.
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
# Machine A -- your program listens on local port 9001
|
|
179
|
+
a = basic_ipfs.IPFSManager(streams=True)
|
|
180
|
+
a.start()
|
|
181
|
+
a.stream_listen("chat", 9001) # "chat" streams from peers arrive on 127.0.0.1:9001
|
|
182
|
+
print(a.peer_id()) # give this to B
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
# Machine B -- connect to 127.0.0.1:9002 and you are talking to the program on A
|
|
187
|
+
b = basic_ipfs.IPFSManager(streams=True)
|
|
188
|
+
b.start()
|
|
189
|
+
b.stream_forward("chat", 9002, "<peer ID of A>")
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`stream_close("chat")` closes the listeners and forwards of that name,
|
|
193
|
+
`stream_close("chat", port=9002)` only the forward on that local port, and
|
|
194
|
+
`stream_close()` closes them all.
|
|
195
|
+
|
|
196
|
+
Two things to know. The listening side is **not told which peer connected**:
|
|
197
|
+
if your program cares who it is talking to, it must check that itself, with
|
|
198
|
+
signatures. The forwarding side does know, because it reaches the peer it
|
|
199
|
+
named or nobody. And this is a Kubo feature still marked experimental
|
|
200
|
+
(`Libp2pStreamMounting`), which is why it is off unless you ask.
|
|
201
|
+
|
|
202
|
+
### Topics: many programs hearing each other
|
|
203
|
+
|
|
204
|
+
A topic is a name. Any node may publish to it, and every node listening on it
|
|
205
|
+
hears what is published. Start the daemon with `topics=True`.
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
node = basic_ipfs.IPFSManager(topics=True)
|
|
209
|
+
node.start()
|
|
210
|
+
|
|
211
|
+
def heard(data, sender): # bytes, and the peer ID that published them
|
|
212
|
+
print(sender, data)
|
|
213
|
+
|
|
214
|
+
stop = node.topic_listen("weather", heard)
|
|
215
|
+
node.topic_publish("weather", b"rain")
|
|
216
|
+
stop()
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Three things to know. A message reaches the listeners your node is connected
|
|
220
|
+
to, directly or through other listeners, so two nodes that have never met
|
|
221
|
+
need to connect first (`swarm_connect`). Nothing is stored: a node that
|
|
222
|
+
starts listening later has missed it. And this is Kubo's experimental pubsub
|
|
223
|
+
(`Pubsub.Enabled`), which Kubo's maintainers describe as tuned for IPNS and
|
|
224
|
+
may change, which is why it is off unless you ask.
|
|
225
|
+
|
|
226
|
+
### Adding a file in place
|
|
227
|
+
|
|
228
|
+
An ordinary `add` copies the file into the node's repository. For a large
|
|
229
|
+
file that is already where you want it -- on another drive, say -- the node
|
|
230
|
+
can leave it there and serve it from where it is. Start the daemon with
|
|
231
|
+
`in_place=True`.
|
|
232
|
+
|
|
233
|
+
```python
|
|
234
|
+
node = basic_ipfs.IPFSManager(repo="/home/me/node/ipfs", in_place=True)
|
|
235
|
+
node.start()
|
|
236
|
+
cid = node.add("/home/me/node/films/big.mkv", in_place=True)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Five things to know. The file must be in the folder that holds the
|
|
240
|
+
repository (`/home/me/node` above) or below it; a link there to a folder on
|
|
241
|
+
another drive counts, so `ln -s /mnt/big /home/me/node/big` and then
|
|
242
|
+
`node.add("/home/me/node/big/film.mkv", in_place=True)` works. The file must
|
|
243
|
+
stay as it is: moved, changed or on an unplugged drive, reads of it fail
|
|
244
|
+
until it is back, and the node carries on. Unpinning never deletes the file;
|
|
245
|
+
that is yours to do. (`node.cat(cid, local_only=True)` reads only what this
|
|
246
|
+
node has and never fetches from another node, so it tells you whether the
|
|
247
|
+
file is still there: if it is not, the read fails or comes back short.)
|
|
248
|
+
Bytes the repository already holds are not taken from the file, which would
|
|
249
|
+
then be a copy nobody reads; `node.discard(cid)` deletes the repository's
|
|
250
|
+
copy first. And this is Kubo's experimental filestore
|
|
251
|
+
(`Experimental.FilestoreEnabled`), which is why it is off unless you ask.
|
|
252
|
+
|
|
253
|
+
### Blocks one at a time
|
|
254
|
+
|
|
255
|
+
For a program that builds its own DAG nodes: `block_put(data, codec="dag-pb")`
|
|
256
|
+
stores one block and returns its CID; `block_get(cid)` reads one back (from
|
|
257
|
+
the network if this node lacks it, unless `local_only=True`). A block is not
|
|
258
|
+
pinned by being put: `pin_add(cid, recursive=False)` keeps that block alone
|
|
259
|
+
and nothing it links to, and `pin_rm(cid, recursive=False)` lets it go.
|
|
260
|
+
`provide(cid)` tells the DHT this node has it, and
|
|
261
|
+
`who_has(cid, limit=20)` asks the DHT which peers say they have it
|
|
262
|
+
(peer IDs, this node's own included if it announced it).
|
|
263
|
+
|
|
264
|
+
### What your node tells the world it has
|
|
265
|
+
|
|
266
|
+
Kubo announces to the DHT **every block it has**, again every day: that is its
|
|
267
|
+
`Provide.Strategy` of `"all"`, and `add(..., provide=False)` does not change
|
|
268
|
+
it. Anyone can then look up a CID and find your node. For a program whose
|
|
269
|
+
node holds things it must not be seen to hold, start the daemon with
|
|
270
|
+
`provide_strategy="mfs"`: then only what is in the node's MFS is announced,
|
|
271
|
+
and `mfs_add(cid, "/shown/<cid>")` / `mfs_remove(path)` are how you choose.
|
|
272
|
+
`"mfs"` announces every block under what is listed; `"mfs+entities"` only
|
|
273
|
+
the root of each file. A manager given a strategy will not attach to a
|
|
274
|
+
daemon already running with another: `start()` raises rather than let it
|
|
275
|
+
announce more than you asked.
|
|
276
|
+
|
|
277
|
+
```python
|
|
278
|
+
node = basic_ipfs.IPFSManager(provide_strategy="mfs")
|
|
279
|
+
node.start()
|
|
280
|
+
cid = node.add(b"for everyone")
|
|
281
|
+
node.mfs_add(cid, f"/shown/{cid}") # announced, and kept from GC
|
|
282
|
+
node.mfs_remove(f"/shown/{cid}") # no longer announced
|
|
283
|
+
```
|
|
284
|
+
|
|
141
285
|
### Two-node example
|
|
142
286
|
|
|
143
287
|
Anything you `add()` on one machine can be `get()`-ed on another that knows
|
|
@@ -190,7 +334,9 @@ REQUESTS_CA_BUNDLE=/etc/ssl/corp-ca.pem \
|
|
|
190
334
|
python your_script.py
|
|
191
335
|
```
|
|
192
336
|
|
|
193
|
-
If
|
|
337
|
+
If `dist.ipfs.tech` cannot be reached, the first call fails in about a
|
|
338
|
+
minute with `IPFSBinaryNotFound`, naming the URL and the exact path to put
|
|
339
|
+
the binary at. If outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
|
|
194
340
|
`<user_data_dir>/basic_ipfs/bin/<platform>/ipfs` (or `ipfs.exe` on Windows)
|
|
195
341
|
and `basic-ipfs` will skip the download entirely. The bundled
|
|
196
342
|
`<site-packages>/basic_ipfs/bin/<platform>/ipfs` path is also honoured
|
|
@@ -242,8 +388,10 @@ consequences you should understand before publishing anything sensitive:
|
|
|
242
388
|
|
|
243
389
|
- **CIDs are advertised.** `add()` announces the content's CID to the
|
|
244
390
|
public DHT. Anyone monitoring the DHT (and crawlers do) can record that
|
|
245
|
-
your node holds that CID.
|
|
246
|
-
|
|
391
|
+
your node holds that CID. `provide=False` does not prevent it: Kubo
|
|
392
|
+
(as of 0.40) ignores it, and its default `Provide.Strategy` (`"all"`)
|
|
393
|
+
announces every block it holds. Start the daemon with
|
|
394
|
+
`provide_strategy="mfs"` to announce only what you list.
|
|
247
395
|
- **`get()` is observable.** Fetching an unknown CID dials peers and may
|
|
248
396
|
fall back to public gateways operated by third parties (Protocol Labs,
|
|
249
397
|
Cloudflare). Those parties learn what you asked for.
|
|
@@ -260,8 +408,12 @@ For non-public data, you have three escape hatches — pick what fits:
|
|
|
260
408
|
```python
|
|
261
409
|
import basic_ipfs
|
|
262
410
|
|
|
263
|
-
# 1.
|
|
264
|
-
|
|
411
|
+
# 1. Announce only what you choose: a node of your own that tells the
|
|
412
|
+
# DHT only what you list (add(provide=False) alone does not do this).
|
|
413
|
+
node = basic_ipfs.IPFSManager(provide_strategy="mfs")
|
|
414
|
+
node.start()
|
|
415
|
+
cid = node.add(b"private") # kept, not announced
|
|
416
|
+
node.mfs_add(cid, f"/shown/{cid}") # only if you want it found
|
|
265
417
|
|
|
266
418
|
# 2. Private network: only peers with the same 256-bit swarm key can
|
|
267
419
|
# connect. Run BEFORE start() / the first IPFS operation.
|