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.
Files changed (29) hide show
  1. {basic_ipfs-1.0.1/basic_ipfs.egg-info → basic_ipfs-1.3.1}/PKG-INFO +162 -10
  2. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/README.md +161 -9
  3. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/__init__.py +830 -90
  4. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/cli.py +5 -1
  5. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1/basic_ipfs.egg-info}/PKG-INFO +162 -10
  6. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/SOURCES.txt +6 -0
  7. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/pyproject.toml +2 -2
  8. basic_ipfs-1.3.1/tests/test_announcing.py +170 -0
  9. basic_ipfs-1.3.1/tests/test_blocks.py +104 -0
  10. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_download.py +69 -0
  11. basic_ipfs-1.3.1/tests/test_in_place.py +222 -0
  12. basic_ipfs-1.3.1/tests/test_ranges_and_endpoints.py +112 -0
  13. basic_ipfs-1.3.1/tests/test_streams.py +174 -0
  14. basic_ipfs-1.3.1/tests/test_topics.py +123 -0
  15. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_unit.py +155 -0
  16. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/LICENSE +0 -0
  17. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/MANIFEST.in +0 -0
  18. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/SECURITY.md +0 -0
  19. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/kubo_checksums.py +0 -0
  20. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs/py.typed +0 -0
  21. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/dependency_links.txt +0 -0
  22. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/entry_points.txt +0 -0
  23. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/requires.txt +0 -0
  24. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/basic_ipfs.egg-info/top_level.txt +0 -0
  25. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/setup.cfg +0 -0
  26. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_basic.py +0 -0
  27. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_cli.py +0 -0
  28. {basic_ipfs-1.0.1 → basic_ipfs-1.3.1}/tests/test_concurrency.py +0 -0
  29. {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.0.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 exactly five things:
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
- # Pass provide=False to skip the public-DHT announce (content stays
83
- # locally addressable, but its presence is not broadcast)
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 outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
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. Pass `provide=False` to skip the announce —
290
- the content is still addressable, but its presence is not broadcast.
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. Per-call: skip the DHT announce on a single add()
308
- cid = basic_ipfs.add(b"private", provide=False)
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 exactly five things:
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
- # Pass provide=False to skip the public-DHT announce (content stays
39
- # locally addressable, but its presence is not broadcast)
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 outbound access to `dist.ipfs.tech` is blocked, pre-place the binary at
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. Pass `provide=False` to skip the announce —
246
- the content is still addressable, but its presence is not broadcast.
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. Per-call: skip the DHT announce on a single add()
264
- cid = basic_ipfs.add(b"private", provide=False)
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.