basic-ipfs 1.0.0__tar.gz → 1.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. {basic_ipfs-1.0.0/basic_ipfs.egg-info → basic_ipfs-1.3.0}/PKG-INFO +149 -8
  2. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/README.md +148 -7
  3. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs/__init__.py +881 -99
  4. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs/cli.py +6 -2
  5. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs/kubo_checksums.py +2 -2
  6. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0/basic_ipfs.egg-info}/PKG-INFO +149 -8
  7. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs.egg-info/SOURCES.txt +6 -0
  8. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/pyproject.toml +2 -2
  9. basic_ipfs-1.3.0/tests/test_announcing.py +170 -0
  10. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/tests/test_basic.py +13 -1
  11. basic_ipfs-1.3.0/tests/test_blocks.py +104 -0
  12. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/tests/test_download.py +190 -2
  13. basic_ipfs-1.3.0/tests/test_in_place.py +222 -0
  14. basic_ipfs-1.3.0/tests/test_ranges_and_endpoints.py +112 -0
  15. basic_ipfs-1.3.0/tests/test_streams.py +174 -0
  16. basic_ipfs-1.3.0/tests/test_topics.py +123 -0
  17. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/tests/test_two_node.py +17 -4
  18. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/tests/test_unit.py +155 -0
  19. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/LICENSE +0 -0
  20. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/MANIFEST.in +0 -0
  21. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/SECURITY.md +0 -0
  22. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs/py.typed +0 -0
  23. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs.egg-info/dependency_links.txt +0 -0
  24. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs.egg-info/entry_points.txt +0 -0
  25. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs.egg-info/requires.txt +0 -0
  26. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/basic_ipfs.egg-info/top_level.txt +0 -0
  27. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/setup.cfg +0 -0
  28. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/tests/test_cli.py +0 -0
  29. {basic_ipfs-1.0.0 → basic_ipfs-1.3.0}/tests/test_concurrency.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: basic-ipfs
3
- Version: 1.0.0
3
+ Version: 1.3.0
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
@@ -79,8 +79,9 @@ import basic_ipfs
79
79
  cid = basic_ipfs.add("photo.jpg")
80
80
  cid = basic_ipfs.add(b"hello world")
81
81
 
82
- # Pass provide=False to skip the public-DHT announce (content stays
83
- # locally addressable, but its presence is not broadcast)
82
+ # provide=False is passed to Kubo, which (as of 0.40) ignores it and
83
+ # announces every block it holds: to keep something out of the DHT, see
84
+ # "What your node tells the world it has".
84
85
  cid = basic_ipfs.add(b"private data", provide=False)
85
86
 
86
87
  # Announce — adds to IPFS without pinning; content may be GC'd later
@@ -141,7 +142,7 @@ Installing the package also adds a `basic-ipfs` command:
141
142
  basic-ipfs status
142
143
  basic-ipfs add photo.jpg # prints the CID, pins content
143
144
  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 add-folder ./mydir # recursive add + pin (skips dotfiles; --hidden includes them)
145
146
  basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
146
147
  basic-ipfs get <cid> [output-path] # stdout or file
147
148
  basic-ipfs pin <cid> [<cid> ...]
@@ -182,6 +183,143 @@ basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
182
183
 
183
184
  Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
184
185
 
186
+ ### A node of your own
187
+
188
+ The module-level functions share one daemon. A program that wants its own --
189
+ or several on one machine -- makes a manager and gives it its own repo and
190
+ ports:
191
+
192
+ ```python
193
+ import basic_ipfs
194
+
195
+ node = basic_ipfs.IPFSManager(
196
+ port=5611, # API
197
+ repo="/var/lib/myapp/ipfs",
198
+ gateway_port=8611,
199
+ swarm_port=4611, # the port other nodes reach it on
200
+ )
201
+ node.start()
202
+ cid = node.add(b"hello")
203
+ print(node.peer_id())
204
+ node.stop() # yours to stop: only the shared daemon stops itself at exit
205
+ ```
206
+
207
+ Anything left out follows the module settings above.
208
+
209
+ ### Streams: one program talking to another
210
+
211
+ Two programs on two machines can talk through their IPFS daemons: an
212
+ encrypted pipe that reaches nodes behind home routers the way IPFS does.
213
+ Start the daemon with `streams=True`; one side listens, the other forwards.
214
+
215
+ ```python
216
+ # Machine A -- your program listens on local port 9001
217
+ a = basic_ipfs.IPFSManager(streams=True)
218
+ a.start()
219
+ a.stream_listen("chat", 9001) # "chat" streams from peers arrive on 127.0.0.1:9001
220
+ print(a.peer_id()) # give this to B
221
+ ```
222
+
223
+ ```python
224
+ # Machine B -- connect to 127.0.0.1:9002 and you are talking to the program on A
225
+ b = basic_ipfs.IPFSManager(streams=True)
226
+ b.start()
227
+ b.stream_forward("chat", 9002, "<peer ID of A>")
228
+ ```
229
+
230
+ `stream_close("chat")` closes the listeners and forwards of that name,
231
+ `stream_close("chat", port=9002)` only the forward on that local port, and
232
+ `stream_close()` closes them all.
233
+
234
+ Two things to know. The listening side is **not told which peer connected**:
235
+ if your program cares who it is talking to, it must check that itself, with
236
+ signatures. The forwarding side does know, because it reaches the peer it
237
+ named or nobody. And this is a Kubo feature still marked experimental
238
+ (`Libp2pStreamMounting`), which is why it is off unless you ask.
239
+
240
+ ### Topics: many programs hearing each other
241
+
242
+ A topic is a name. Any node may publish to it, and every node listening on it
243
+ hears what is published. Start the daemon with `topics=True`.
244
+
245
+ ```python
246
+ node = basic_ipfs.IPFSManager(topics=True)
247
+ node.start()
248
+
249
+ def heard(data, sender): # bytes, and the peer ID that published them
250
+ print(sender, data)
251
+
252
+ stop = node.topic_listen("weather", heard)
253
+ node.topic_publish("weather", b"rain")
254
+ stop()
255
+ ```
256
+
257
+ Three things to know. A message reaches the listeners your node is connected
258
+ to, directly or through other listeners, so two nodes that have never met
259
+ need to connect first (`swarm_connect`). Nothing is stored: a node that
260
+ starts listening later has missed it. And this is Kubo's experimental pubsub
261
+ (`Pubsub.Enabled`), which Kubo's maintainers describe as tuned for IPNS and
262
+ may change, which is why it is off unless you ask.
263
+
264
+ ### Adding a file in place
265
+
266
+ An ordinary `add` copies the file into the node's repository. For a large
267
+ file that is already where you want it -- on another drive, say -- the node
268
+ can leave it there and serve it from where it is. Start the daemon with
269
+ `in_place=True`.
270
+
271
+ ```python
272
+ node = basic_ipfs.IPFSManager(repo="/home/me/node/ipfs", in_place=True)
273
+ node.start()
274
+ cid = node.add("/home/me/node/films/big.mkv", in_place=True)
275
+ ```
276
+
277
+ Five things to know. The file must be in the folder that holds the
278
+ repository (`/home/me/node` above) or below it; a link there to a folder on
279
+ another drive counts, so `ln -s /mnt/big /home/me/node/big` and then
280
+ `node.add("/home/me/node/big/film.mkv", in_place=True)` works. The file must
281
+ stay as it is: moved, changed or on an unplugged drive, reads of it fail
282
+ until it is back, and the node carries on. Unpinning never deletes the file;
283
+ that is yours to do. (`node.cat(cid, local_only=True)` reads only what this
284
+ node has and never fetches from another node, so it tells you whether the
285
+ file is still there: if it is not, the read fails or comes back short.)
286
+ Bytes the repository already holds are not taken from the file, which would
287
+ then be a copy nobody reads; `node.discard(cid)` deletes the repository's
288
+ copy first. And this is Kubo's experimental filestore
289
+ (`Experimental.FilestoreEnabled`), which is why it is off unless you ask.
290
+
291
+ ### Blocks one at a time
292
+
293
+ For a program that builds its own DAG nodes: `block_put(data, codec="dag-pb")`
294
+ stores one block and returns its CID; `block_get(cid)` reads one back (from
295
+ the network if this node lacks it, unless `local_only=True`). A block is not
296
+ pinned by being put: `pin_add(cid, recursive=False)` keeps that block alone
297
+ and nothing it links to, and `pin_rm(cid, recursive=False)` lets it go.
298
+ `provide(cid)` tells the DHT this node has it, and
299
+ `who_has(cid, limit=20)` asks the DHT which peers say they have it
300
+ (peer IDs, this node's own included if it announced it).
301
+
302
+ ### What your node tells the world it has
303
+
304
+ Kubo announces to the DHT **every block it has**, again every day: that is its
305
+ `Provide.Strategy` of `"all"`, and `add(..., provide=False)` does not change
306
+ it. Anyone can then look up a CID and find your node. For a program whose
307
+ node holds things it must not be seen to hold, start the daemon with
308
+ `provide_strategy="mfs"`: then only what is in the node's MFS is announced,
309
+ and `mfs_add(cid, "/shown/<cid>")` / `mfs_remove(path)` are how you choose.
310
+ `"mfs"` announces every block under what is listed; `"mfs+entities"` only
311
+ the root of each file. A manager given a strategy will not attach to a
312
+ daemon already running with another: `start()` raises rather than let it
313
+ announce more than you asked.
314
+
315
+ ```python
316
+ node = basic_ipfs.IPFSManager(provide_strategy="mfs")
317
+ node.start()
318
+ cid = node.add(b"for everyone")
319
+ node.mfs_add(cid, f"/shown/{cid}") # announced, and kept from GC
320
+ node.mfs_remove(f"/shown/{cid}") # no longer announced
321
+ ```
322
+
185
323
  ### Two-node example
186
324
 
187
325
  Anything you `add()` on one machine can be `get()`-ed on another that knows
@@ -262,8 +400,9 @@ Auto-download is verified against an SHA-512 hash baked into the wheel
262
400
  (`basic_ipfs/kubo_checksums.py`) using a constant-time compare. Versions
263
401
  not in the table are refused — fetching a digest from the same origin as
264
402
  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).
403
+ download also pins its redirect target to `dist.ipfs.tech` (and its
404
+ subdomains) at every hop in the chain — not just the final URL — and
405
+ requires HTTPS on every hop.
267
406
 
268
407
  Two trust assumptions worth knowing before deploying on a shared host:
269
408
 
@@ -285,8 +424,10 @@ consequences you should understand before publishing anything sensitive:
285
424
 
286
425
  - **CIDs are advertised.** `add()` announces the content's CID to the
287
426
  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.
427
+ your node holds that CID. `provide=False` does not prevent it: Kubo
428
+ (as of 0.40) ignores it, and its default `Provide.Strategy` (`"all"`)
429
+ announces every block it holds. Start the daemon with
430
+ `provide_strategy="mfs"` to announce only what you list.
290
431
  - **`get()` is observable.** Fetching an unknown CID dials peers and may
291
432
  fall back to public gateways operated by third parties (Protocol Labs,
292
433
  Cloudflare). Those parties learn what you asked for.
@@ -35,8 +35,9 @@ import basic_ipfs
35
35
  cid = basic_ipfs.add("photo.jpg")
36
36
  cid = basic_ipfs.add(b"hello world")
37
37
 
38
- # Pass provide=False to skip the public-DHT announce (content stays
39
- # locally addressable, but its presence is not broadcast)
38
+ # provide=False is passed to Kubo, which (as of 0.40) ignores it and
39
+ # announces every block it holds: to keep something out of the DHT, see
40
+ # "What your node tells the world it has".
40
41
  cid = basic_ipfs.add(b"private data", provide=False)
41
42
 
42
43
  # Announce — adds to IPFS without pinning; content may be GC'd later
@@ -97,7 +98,7 @@ Installing the package also adds a `basic-ipfs` command:
97
98
  basic-ipfs status
98
99
  basic-ipfs add photo.jpg # prints the CID, pins content
99
100
  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 add-folder ./mydir # recursive add + pin (skips dotfiles; --hidden includes them)
101
102
  basic-ipfs compute-cid photo.jpg # prints the CID, stores nothing, announces nothing
102
103
  basic-ipfs get <cid> [output-path] # stdout or file
103
104
  basic-ipfs pin <cid> [<cid> ...]
@@ -138,6 +139,143 @@ basic_ipfs.STORAGE_MAX = "100GB" # repo size cap ("" = unlimited)
138
139
 
139
140
  Default repo location is `~/.local/share/basic_ipfs/ipfs_repo` (`platformdirs` picks the right path per OS).
140
141
 
142
+ ### A node of your own
143
+
144
+ The module-level functions share one daemon. A program that wants its own --
145
+ or several on one machine -- makes a manager and gives it its own repo and
146
+ ports:
147
+
148
+ ```python
149
+ import basic_ipfs
150
+
151
+ node = basic_ipfs.IPFSManager(
152
+ port=5611, # API
153
+ repo="/var/lib/myapp/ipfs",
154
+ gateway_port=8611,
155
+ swarm_port=4611, # the port other nodes reach it on
156
+ )
157
+ node.start()
158
+ cid = node.add(b"hello")
159
+ print(node.peer_id())
160
+ node.stop() # yours to stop: only the shared daemon stops itself at exit
161
+ ```
162
+
163
+ Anything left out follows the module settings above.
164
+
165
+ ### Streams: one program talking to another
166
+
167
+ Two programs on two machines can talk through their IPFS daemons: an
168
+ encrypted pipe that reaches nodes behind home routers the way IPFS does.
169
+ Start the daemon with `streams=True`; one side listens, the other forwards.
170
+
171
+ ```python
172
+ # Machine A -- your program listens on local port 9001
173
+ a = basic_ipfs.IPFSManager(streams=True)
174
+ a.start()
175
+ a.stream_listen("chat", 9001) # "chat" streams from peers arrive on 127.0.0.1:9001
176
+ print(a.peer_id()) # give this to B
177
+ ```
178
+
179
+ ```python
180
+ # Machine B -- connect to 127.0.0.1:9002 and you are talking to the program on A
181
+ b = basic_ipfs.IPFSManager(streams=True)
182
+ b.start()
183
+ b.stream_forward("chat", 9002, "<peer ID of A>")
184
+ ```
185
+
186
+ `stream_close("chat")` closes the listeners and forwards of that name,
187
+ `stream_close("chat", port=9002)` only the forward on that local port, and
188
+ `stream_close()` closes them all.
189
+
190
+ Two things to know. The listening side is **not told which peer connected**:
191
+ if your program cares who it is talking to, it must check that itself, with
192
+ signatures. The forwarding side does know, because it reaches the peer it
193
+ named or nobody. And this is a Kubo feature still marked experimental
194
+ (`Libp2pStreamMounting`), which is why it is off unless you ask.
195
+
196
+ ### Topics: many programs hearing each other
197
+
198
+ A topic is a name. Any node may publish to it, and every node listening on it
199
+ hears what is published. Start the daemon with `topics=True`.
200
+
201
+ ```python
202
+ node = basic_ipfs.IPFSManager(topics=True)
203
+ node.start()
204
+
205
+ def heard(data, sender): # bytes, and the peer ID that published them
206
+ print(sender, data)
207
+
208
+ stop = node.topic_listen("weather", heard)
209
+ node.topic_publish("weather", b"rain")
210
+ stop()
211
+ ```
212
+
213
+ Three things to know. A message reaches the listeners your node is connected
214
+ to, directly or through other listeners, so two nodes that have never met
215
+ need to connect first (`swarm_connect`). Nothing is stored: a node that
216
+ starts listening later has missed it. And this is Kubo's experimental pubsub
217
+ (`Pubsub.Enabled`), which Kubo's maintainers describe as tuned for IPNS and
218
+ may change, which is why it is off unless you ask.
219
+
220
+ ### Adding a file in place
221
+
222
+ An ordinary `add` copies the file into the node's repository. For a large
223
+ file that is already where you want it -- on another drive, say -- the node
224
+ can leave it there and serve it from where it is. Start the daemon with
225
+ `in_place=True`.
226
+
227
+ ```python
228
+ node = basic_ipfs.IPFSManager(repo="/home/me/node/ipfs", in_place=True)
229
+ node.start()
230
+ cid = node.add("/home/me/node/films/big.mkv", in_place=True)
231
+ ```
232
+
233
+ Five things to know. The file must be in the folder that holds the
234
+ repository (`/home/me/node` above) or below it; a link there to a folder on
235
+ another drive counts, so `ln -s /mnt/big /home/me/node/big` and then
236
+ `node.add("/home/me/node/big/film.mkv", in_place=True)` works. The file must
237
+ stay as it is: moved, changed or on an unplugged drive, reads of it fail
238
+ until it is back, and the node carries on. Unpinning never deletes the file;
239
+ that is yours to do. (`node.cat(cid, local_only=True)` reads only what this
240
+ node has and never fetches from another node, so it tells you whether the
241
+ file is still there: if it is not, the read fails or comes back short.)
242
+ Bytes the repository already holds are not taken from the file, which would
243
+ then be a copy nobody reads; `node.discard(cid)` deletes the repository's
244
+ copy first. And this is Kubo's experimental filestore
245
+ (`Experimental.FilestoreEnabled`), which is why it is off unless you ask.
246
+
247
+ ### Blocks one at a time
248
+
249
+ For a program that builds its own DAG nodes: `block_put(data, codec="dag-pb")`
250
+ stores one block and returns its CID; `block_get(cid)` reads one back (from
251
+ the network if this node lacks it, unless `local_only=True`). A block is not
252
+ pinned by being put: `pin_add(cid, recursive=False)` keeps that block alone
253
+ and nothing it links to, and `pin_rm(cid, recursive=False)` lets it go.
254
+ `provide(cid)` tells the DHT this node has it, and
255
+ `who_has(cid, limit=20)` asks the DHT which peers say they have it
256
+ (peer IDs, this node's own included if it announced it).
257
+
258
+ ### What your node tells the world it has
259
+
260
+ Kubo announces to the DHT **every block it has**, again every day: that is its
261
+ `Provide.Strategy` of `"all"`, and `add(..., provide=False)` does not change
262
+ it. Anyone can then look up a CID and find your node. For a program whose
263
+ node holds things it must not be seen to hold, start the daemon with
264
+ `provide_strategy="mfs"`: then only what is in the node's MFS is announced,
265
+ and `mfs_add(cid, "/shown/<cid>")` / `mfs_remove(path)` are how you choose.
266
+ `"mfs"` announces every block under what is listed; `"mfs+entities"` only
267
+ the root of each file. A manager given a strategy will not attach to a
268
+ daemon already running with another: `start()` raises rather than let it
269
+ announce more than you asked.
270
+
271
+ ```python
272
+ node = basic_ipfs.IPFSManager(provide_strategy="mfs")
273
+ node.start()
274
+ cid = node.add(b"for everyone")
275
+ node.mfs_add(cid, f"/shown/{cid}") # announced, and kept from GC
276
+ node.mfs_remove(f"/shown/{cid}") # no longer announced
277
+ ```
278
+
141
279
  ### Two-node example
142
280
 
143
281
  Anything you `add()` on one machine can be `get()`-ed on another that knows
@@ -218,8 +356,9 @@ Auto-download is verified against an SHA-512 hash baked into the wheel
218
356
  (`basic_ipfs/kubo_checksums.py`) using a constant-time compare. Versions
219
357
  not in the table are refused — fetching a digest from the same origin as
220
358
  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).
359
+ download also pins its redirect target to `dist.ipfs.tech` (and its
360
+ subdomains) at every hop in the chain — not just the final URL — and
361
+ requires HTTPS on every hop.
223
362
 
224
363
  Two trust assumptions worth knowing before deploying on a shared host:
225
364
 
@@ -241,8 +380,10 @@ consequences you should understand before publishing anything sensitive:
241
380
 
242
381
  - **CIDs are advertised.** `add()` announces the content's CID to the
243
382
  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.
383
+ your node holds that CID. `provide=False` does not prevent it: Kubo
384
+ (as of 0.40) ignores it, and its default `Provide.Strategy` (`"all"`)
385
+ announces every block it holds. Start the daemon with
386
+ `provide_strategy="mfs"` to announce only what you list.
246
387
  - **`get()` is observable.** Fetching an unknown CID dials peers and may
247
388
  fall back to public gateways operated by third parties (Protocol Labs,
248
389
  Cloudflare). Those parties learn what you asked for.