-
Notifications
You must be signed in to change notification settings - Fork 200
/
object.py
351 lines (271 loc) · 9.85 KB
/
object.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
# -*- coding: utf-8 -*-
from __future__ import absolute_import
from . import base
from .. import multipart
class PatchSection(base.SectionBase):
@base.returns_single_item
def add_link(self, root, name, ref, create=False, **kwargs):
"""Creates a new merkledag object based on an existing one.
The new object will have a link to the provided object.
.. code-block:: python
>>> client.object.patch.add_link(
... 'QmR79zQQj2aDfnrNgczUhvf2qWapEfQ82YQRt3QjrbhSb2',
... 'Johnny',
... 'QmR79zQQj2aDfnrNgczUhvf2qWapEfQ82YQRt3QjrbhSb2'
... )
{'Hash': 'QmNtXbF3AjAk59gQKRgEdVabHcSsiPUnJwHnZKyj2x8Z3k'}
Parameters
----------
root : str
IPFS hash for the object being modified
name : str
name for the new link
ref : str
IPFS hash for the object being linked to
create : bool
Create intermediary nodes
Returns
-------
dict
+------+----------------------------------+
| Hash | Hash of the newly derived object |
+------+----------------------------------+
"""
kwargs.setdefault("opts", {})["create"] = create
args = ((root, name, ref),)
return self._client.request('/object/patch/add-link', args, decoder='json', **kwargs)
@base.returns_single_item
def append_data(self, cid, new_data, **kwargs):
"""Creates a new merkledag object based on an existing one.
The new object will have the provided data appended to it,
and will thus have a new Hash.
.. code-block:: python
>>> client.object.patch.append_data("QmZZmY … fTqm", io.BytesIO(b"bla"))
{'Hash': 'QmR79zQQj2aDfnrNgczUhvf2qWapEfQ82YQRt3QjrbhSb2'}
Parameters
----------
cid : Union[str, cid.CIDv0, cid.CIDv1]
The hash of an ipfs object to modify
new_data : Union[str, bytes, os.PathLike, io.IOBase, int]
The data to append to the object's data section
Returns
-------
dict
+------+----------------------------------+
| Hash | Hash of the newly derived object |
+------+----------------------------------+
"""
args = (str(cid),)
body, headers = multipart.stream_files(new_data, self.chunk_size)
return self._client.request('/object/patch/append-data', args, decoder='json',
data=body, headers=headers, **kwargs)
@base.returns_single_item
def rm_link(self, root, link, **kwargs):
"""Creates a new merkledag object based on an existing one.
The new object will lack a link to the specified object.
.. code-block:: python
>>> client.object.patch.rm_link(
... 'QmNtXbF3AjAk59gQKRgEdVabHcSsiPUnJwHnZKyj2x8Z3k',
... 'Johnny'
... )
{'Hash': 'QmR79zQQj2aDfnrNgczUhvf2qWapEfQ82YQRt3QjrbhSb2'}
Parameters
----------
root : str
IPFS hash of the object to modify
link : str
name of the link to remove
Returns
-------
dict
+------+----------------------------------+
| Hash | Hash of the newly derived object |
+------+----------------------------------+
"""
args = ((root, link),)
return self._client.request('/object/patch/rm-link', args, decoder='json', **kwargs)
@base.returns_single_item
def set_data(self, root, data, **kwargs):
"""Creates a new merkledag object based on an existing one.
The new object will have the same links as the old object but
with the provided data instead of the old object's data contents.
.. code-block:: python
>>> client.object.patch.set_data(
... 'QmNtXbF3AjAk59gQKRgEdVabHcSsiPUnJwHnZKyj2x8Z3k',
... io.BytesIO(b'bla')
... )
{'Hash': 'QmSw3k2qkv4ZPsbu9DVEJaTMszAQWNgM1FTFYpfZeNQWrd'}
Parameters
----------
root : str
IPFS hash of the object to modify
data : Union[str, bytes, os.PathLike, io.IOBase, int]
The new data to store in root
Returns
-------
dict
+------+----------------------------------+
| Hash | Hash of the newly derived object |
+------+----------------------------------+
"""
args = (root,)
body, headers = multipart.stream_files(data, self.chunk_size)
return self._client.request('/object/patch/set-data', args, decoder='json', data=body,
headers=headers, **kwargs)
class Section(base.SectionBase):
patch = base.SectionProperty(PatchSection)
def data(self, cid, **kwargs):
r"""Returns the raw bytes in an IPFS object.
.. code-block:: python
>>> client.object.data('QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D')
b'\x08\x01'
Parameters
----------
cid : Union[str, cid.CIDv0, cid.CIDv1]
Key of the object to retrieve, in CID format
Returns
-------
bytes
Raw object data
"""
args = (str(cid),)
return self._client.request('/object/data', args, **kwargs)
@base.returns_single_item
def get(self, cid, **kwargs):
"""Get and serialize the DAG node named by CID.
.. code-block:: python
>>> client.object.get('QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D')
{'Data': '\x08\x01',
'Links': [
{'Hash': 'Qmd2xkBfEwEs9oMTk77A6jrsgurpF3ugXSg7dtPNFkcNMV',
'Name': 'Makefile', 'Size': 174},
{'Hash': 'QmeKozNssnkJ4NcyRidYgDY2jfRZqVEoRGfipkgath71bX',
'Name': 'example', 'Size': 1474},
{'Hash': 'QmZAL3oHMQYqsV61tGvoAVtQLs1WzRe1zkkamv9qxqnDuK',
'Name': 'home', 'Size': 3947},
{'Hash': 'QmZNPyKVriMsZwJSNXeQtVQSNU4v4KEKGUQaMT61LPahso',
'Name': 'lib', 'Size': 268261},
{'Hash': 'QmSY8RfVntt3VdxWppv9w5hWgNrE31uctgTiYwKir8eXJY',
'Name': 'published-version', 'Size': 55}
]}
Parameters
----------
cid : Union[str, cid.CIDv0, cid.CIDv1]
Key of the object to retrieve, in CID format
Returns
-------
dict
+-------+------------------------------------------------+
| Data | Raw object data (ISO-8859-1 decoded) |
+-------+------------------------------------------------+
| Links | List of links associated with the given object |
+-------+------------------------------------------------+
"""
args = (str(cid),)
return self._client.request('/object/get', args, decoder='json', **kwargs)
@base.returns_single_item
def links(self, cid, **kwargs):
"""Returns the links pointed to by the specified object.
.. code-block:: python
>>> client.object.links('QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDx … ca7D')
{'Hash': 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D',
'Links': [
{'Hash': 'Qmd2xkBfEwEs9oMTk77A6jrsgurpF3ugXSg7dtPNFkcNMV',
'Name': 'Makefile', 'Size': 174},
{'Hash': 'QmeKozNssnkJ4NcyRidYgDY2jfRZqVEoRGfipkgath71bX',
'Name': 'example', 'Size': 1474},
{'Hash': 'QmZAL3oHMQYqsV61tGvoAVtQLs1WzRe1zkkamv9qxqnDuK',
'Name': 'home', 'Size': 3947},
{'Hash': 'QmZNPyKVriMsZwJSNXeQtVQSNU4v4KEKGUQaMT61LPahso',
'Name': 'lib', 'Size': 268261},
{'Hash': 'QmSY8RfVntt3VdxWppv9w5hWgNrE31uctgTiYwKir8eXJY',
'Name': 'published-version', 'Size': 55}]}
Parameters
----------
cid : Union[str, cid.CIDv0, cid.CIDv1]
Key of the object to retrieve, in CID format
Returns
-------
dict
+-------+------------------------------------------------+
| Hash | The requested object CID |
+-------+------------------------------------------------+
| Links | List of links associated with the given object |
+-------+------------------------------------------------+
"""
args = (str(cid),)
return self._client.request('/object/links', args, decoder='json', **kwargs)
@base.returns_single_item
def new(self, template=None, **kwargs):
"""Creates a new object from an IPFS template.
By default this creates and returns a new empty merkledag node, but you
may pass an optional template argument to create a preformatted node.
.. code-block:: python
>>> client.object.new()
{'Hash': 'QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n'}
Parameters
----------
template : str
Blueprints from which to construct the new object. Possible values:
* ``"unixfs-dir"``
* ``None``
Returns
-------
dict
+-------+----------------------------------------+
| Hash | The hash of the requested empty object |
+-------+----------------------------------------+
"""
args = (template,) if template is not None else ()
return self._client.request('/object/new', args, decoder='json', **kwargs)
@base.returns_single_item
def put(self, file, **kwargs):
"""Stores input as a DAG object and returns its key.
.. code-block:: python
>>> client.object.put(io.BytesIO(b'''
... {
... "Data": "another",
... "Links": [ {
... "Name": "some link",
... "Hash": "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCV … R39V",
... "Size": 8
... } ]
... }'''))
{'Hash': 'QmZZmY4KCu9r3e7M2Pcn46Fc5qbn6NpzaAGaYb22kbfTqm',
'Links': [
{'Hash': 'QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V',
'Size': 8, 'Name': 'some link'}
]
}
Parameters
----------
file : Union[str, bytes, os.PathLike, io.IOBase, int]
(JSON) object from which the DAG object will be created
Returns
-------
dict
Hash and links of the created DAG object
See the :meth:`~ipfshttpclient.Client.object.links` method for
details.
"""
body, headers = multipart.stream_files(file, self.chunk_size)
return self._client.request('/object/put', decoder='json', data=body,
headers=headers, **kwargs)
@base.returns_single_item
def stat(self, cid, **kwargs):
"""Get stats for the DAG node named by cid.
.. code-block:: python
>>> client.object.stat('QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D')
{'LinksSize': 256, 'NumLinks': 5,
'Hash': 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D',
'BlockSize': 258, 'CumulativeSize': 274169, 'DataSize': 2}
Parameters
----------
cid : Union[str, cid.CIDv0, cid.CIDv1]
Key of the object to retrieve, in CID format
Returns
-------
dict
"""
args = (str(cid),)
return self._client.request('/object/stat', args, decoder='json', **kwargs)