gdp / lang / python / README @ master
History | View | Annotate | Download (16 KB)
1 | d7cb3879 | Nitesh Mor | # ----- BEGIN LICENSE BLOCK ----- |
---|---|---|---|
2 | # GDP: Global Data Plane |
||
3 | # From the Ubiquitous Swarm Lab, 490 Cory Hall, U.C. Berkeley. |
||
4 | # |
||
5 | c87dd166 | Eric Allman | # Copyright (c) 2015-2019, Regents of the University of California. |
6 | d7cb3879 | Nitesh Mor | # All rights reserved. |
7 | # |
||
8 | # Permission is hereby granted, without written agreement and without |
||
9 | # license or royalty fees, to use, copy, modify, and distribute this |
||
10 | # software and its documentation for any purpose, provided that the above |
||
11 | # copyright notice and the following two paragraphs appear in all copies |
||
12 | # of this software. |
||
13 | # |
||
14 | # IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, |
||
15 | # SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST |
||
16 | # PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, |
||
17 | # EVEN IF REGENTS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||
18 | # |
||
19 | # REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT |
||
20 | # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS |
||
21 | # FOR A PARTICULAR PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, |
||
22 | # IF ANY, PROVIDED HEREUNDER IS PROVIDED "AS IS". REGENTS HAS NO |
||
23 | # OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, |
||
24 | # OR MODIFICATIONS. |
||
25 | # ----- END LICENSE BLOCK ----- |
||
26 | |||
27 | |||
28 | fae38f90 | Nitesh Mor | NOTE: |
29 | For latest version of this, use `pydoc`. |
||
30 | 9d041c43 | Nitesh Mor | |
31 | Help on package gdp: |
||
32 | |||
33 | NAME |
||
34 | gdp |
||
35 | |||
36 | DESCRIPTION |
||
37 | A Python API for libgdp. Uses ctypes and shared library versions of |
||
38 | libgdp and libep. |
||
39 | |||
40 | a3d5bf5f | Nitesh Mor | This package exports a number of classes, and a few utility functions. |
41 | Here is a very brief summary, but please see the detailed C-api docs. |
||
42 | 9d041c43 | Nitesh Mor | |
43 | a3d5bf5f | Nitesh Mor | - GDP_NAME: a name in GDP |
44 | - GDP_GIN : a GDP instance |
||
45 | - GDP_EVENT: an asynchronous event |
||
46 | - GDP_DATUM: a GDP datum: (kind of) a record in memory |
||
47 | - GDP_HASH: a cryptographic hash |
||
48 | - GDP_SIG: a signature |
||
49 | - GDP_BUF: a generic buffer |
||
50 | - GDP_MD: a metadata object |
||
51 | - GDP_OPEN_INFO: information regarding metadata |
||
52 | 9d041c43 | Nitesh Mor | |
53 | a3d5bf5f | Nitesh Mor | Note that a number of methods take a NULL/None value, which implies |
54 | that the underlying C-library makes a decision on what value to |
||
55 | use (based on configuration parameters or defaults). Providing a |
||
56 | non-null argument is simply a way to override these defaults. |
||
57 | |||
58 | 9d041c43 | Nitesh Mor | |
59 | a3d5bf5f | Nitesh Mor | Help on class GDP_GIN in gdp: |
60 | |||
61 | gdp.GDP_GIN = class GDP_GIN(__builtin__.object) |
||
62 | | A class that represents a GDP Instance. A GIN resembles an open |
||
63 | | file handle in various ways. |
||
64 | | |
||
65 | | Note that get_next_event is both a class method (for events on any of |
||
66 | | the GIN's) as well as an instance method (for events on a particular |
||
67 | | GIN). The auto-generated documentation might not show this, but |
||
68 | | something to keep in mind. |
||
69 | | |
||
70 | | Methods defined here: |
||
71 | | |
||
72 | | __del__(self) |
||
73 | | close this GCL handle, and free the allocated resources |
||
74 | | |
||
75 | | __eq__(self, other) |
||
76 | | |
||
77 | | __init__(self, name, iomode, open_info={}, **kwargs) |
||
78 | | Open a GDP instance for a GDP object with given name and io-mode. |
||
79 | | |
||
80 | | name=<name-of-gin>, iomode=<mode> |
||
81 | | name is a GDP_NAME object for the GDP object |
||
82 | | mode is one of the following: GDP_MODE_ANY, GDP_MODE_RO, |
||
83 | | GDP_MODE_AO, GDP_MODE_RA |
||
84 | | open_info is a dictionary. It contains extra information |
||
85 | | such as the private signature key, etc. The key may be |
||
86 | | optional, depending on how the log was created and if a |
||
87 | | log-server is set up to reject unsigned appends, for example. |
||
88 | | |
||
89 | | append(self, datum, prevhash=None) |
||
90 | | Write a datum to the GCL. If prevhash is not supplied, the |
||
91 | | C library inserts a reasonable value. |
||
92 | | |
||
93 | | append_async(self, datum, prevhash=None) |
||
94 | | Async version of append. A writer ought to check return status |
||
95 | | by invoking get_next_event, potentially in a different thread. |
||
96 | | |
||
97 | | [This is different than the C library version: The C-library |
||
98 | | version expects a list of datuns, but we only support a single |
||
99 | | datum at a time... at least for the moment] |
||
100 | | |
||
101 | | getmetadata(self) |
||
102 | | return the metadata included at creation time. |
||
103 | | Represented as a python dict |
||
104 | | |
||
105 | | getname(self) |
||
106 | | Get the name of the corresponding GOB, returns a GDP_NAME object |
||
107 | | |
||
108 | | getnrecs(self) |
||
109 | | Get number of records |
||
110 | | |
||
111 | | print_to_file(self, fh) |
||
112 | | Print this GDP object to a file. Could be sys.stdout |
||
113 | | The actual printing is done by the C library |
||
114 | | |
||
115 | | read_by_hash(self, hashbytes) |
||
116 | | Same as read_by_recno, except takes a hash instead of recno |
||
117 | | |
||
118 | | read_by_hash_async(self, starthash, numrecs) |
||
119 | | Asynchronous version of `read_by_hash` that supports reading |
||
120 | | multiple records at a time. |
||
121 | | For now, callbacks are not exposed to end-user. Events are |
||
122 | | generated instead. |
||
123 | | |
||
124 | | read_by_recno(self, recno) |
||
125 | | Returns a GDP_DATUM object corresponding to specified recno |
||
126 | | |
||
127 | | read_by_recno_async(self, start, numrecs) |
||
128 | | Asynchronous version of `read_by_recno` that supports reading |
||
129 | | multiple records at a time. |
||
130 | | For now, callbacks are not exposed to end-user. Events are |
||
131 | | generated instead. |
||
132 | | |
||
133 | | read_by_ts(self, tsdict) |
||
134 | | Same as 'read_by_recno', but takes a time-stamp dictionary |
||
135 | | instead of a record number. |
||
136 | | The time-stamp dictionary has the following fields: |
||
137 | | - tv_sec: seconds since epoch (an integer) |
||
138 | | - tv_nsec: nano seconds (an integer) |
||
139 | | - tv_accuracy: accuracy (a float) |
||
140 | | |
||
141 | | read_by_ts_async(self, startdict, numrecs) |
||
142 | | Asynchronous version of `read_by_ts` that supports reading |
||
143 | | multiple records at a time. |
||
144 | | For now, callbacks are not exposed to end-user. Events are |
||
145 | | generated instead. |
||
146 | | |
||
147 | | subscribe_by_hash(self, starthash, numrecs, timeout) |
||
148 | | Subscriptions, but by a hash instead of a record number |
||
149 | | |
||
150 | | subscribe_by_recno(self, start, numrecs, timeout) |
||
151 | | Subscriptions by a record number. |
||
152 | | Refer to the C-API for more details. |
||
153 | | For now, callbacks are not exposed to end-user. Events are |
||
154 | | generated instead. |
||
155 | | |
||
156 | | subscribe_by_ts(self, startdict, numrecs, timeout) |
||
157 | | Subscriptions, but by a timestamp dictionary instead of recno |
||
158 | | |
||
159 | | unsubscribe(self, cbfunc=None, cbarg=None) |
||
160 | | Terminates existing subscription. |
||
161 | | |
||
162 | | ---------------------------------------------------------------------- |
||
163 | | Class methods defined here: |
||
164 | | |
||
165 | | create(cls, name, logd_name, metadata) from __builtin__.type |
||
166 | | create a new GCL with 'name' on 'logd_name' |
||
167 | | metadata is a dictionary with keys as 32-bit unsigned integers |
||
168 | | |
||
169 | | get_next_event(cls, timeout) from __builtin__.type |
||
170 | | Get events for ANY open gin |
||
171 | | |
||
172 | | ---------------------------------------------------------------------- |
||
173 | | Data descriptors defined here: |
||
174 | | |
||
175 | | __dict__ |
||
176 | | dictionary for instance variables (if defined) |
||
177 | | |
||
178 | | __weakref__ |
||
179 | | list of weak references to the object (if defined) |
||
180 | | |
||
181 | | ---------------------------------------------------------------------- |
||
182 | | Data and other attributes defined here: |
||
183 | | |
||
184 | | gdp_gin_sub_cbfunc_t = <class 'ctypes.CFunctionType'> |
||
185 | | |
||
186 | | |
||
187 | | gdp_gin_t = <class 'gdp.GDP_GIN.gdp_gin_t'> |
||
188 | | Corresponds to gdp_gin_t structure exported by C library |
||
189 | 9d041c43 | Nitesh Mor | |
190 | c118066e | Nitesh Mor | Help on class GDP_NAME in gdp: |
191 | |||
192 | 9d041c43 | Nitesh Mor | gdp.GDP_NAME = class GDP_NAME |
193 | a3d5bf5f | Nitesh Mor | | Represents a GDP name. Each GDP name has potentially up to three |
194 | | different representations: |
||
195 | | - a 256 bit binary version |
||
196 | | - a Base-64(ish) representation |
||
197 | | - (optional) a more memorable version; for the moment, this is |
||
198 | | hashed to get the binary version |
||
199 | 9d041c43 | Nitesh Mor | | |
200 | | Methods defined here: |
||
201 | | |
||
202 | a3d5bf5f | Nitesh Mor | | __init__(self, name, force_internal=False) |
203 | 9d041c43 | Nitesh Mor | | takes either an internal name, or a printable name, or a human friendly |
204 | | name, and creates a python object that can be passed around for the |
||
205 | | various GDP calls |
||
206 | | |
||
207 | | internal_name(self) |
||
208 | | Returns a python string that represents the internal binray name |
||
209 | | |
||
210 | | is_valid(self) |
||
211 | | Borrowed from the GDP C api, tells if the name is valid or not |
||
212 | | |
||
213 | | printable_name(self) |
||
214 | | Returns a python string that represents the printable name |
||
215 | | |
||
216 | | ---------------------------------------------------------------------- |
||
217 | | Data and other attributes defined here: |
||
218 | | |
||
219 | | PNAME_LEN = 43 |
||
220 | | |
||
221 | | name_t = <class 'gdp.GDP_NAME.c_ubyte_Array_32'> |
||
222 | | |
||
223 | | |
||
224 | | pname_t = <class 'gdp.GDP_NAME.c_ubyte_Array_44'> |
||
225 | |||
226 | a3d5bf5f | Nitesh Mor | Help on class GDP_DATUM in gdp: |
227 | c118066e | Nitesh Mor | |
228 | a3d5bf5f | Nitesh Mor | gdp.GDP_DATUM = class GDP_DATUM |
229 | | A class only for internal use. The C datum equivalent exposed to |
||
230 | | python users is of a dictionary. |
||
231 | 9d041c43 | Nitesh Mor | | |
232 | a3d5bf5f | Nitesh Mor | | This is to avoid any side effects that the underlying buffer |
233 | | implementation may cause. |
||
234 | c118066e | Nitesh Mor | | |
235 | 9d041c43 | Nitesh Mor | | Methods defined here: |
236 | | |
||
237 | | __del__(self) |
||
238 | a3d5bf5f | Nitesh Mor | | Destructor: Does nothing if this GDP datum was created by |
239 | | passing an exisiting datum pointer |
||
240 | | |
||
241 | | __getitem__(self, key) |
||
242 | | |
||
243 | | __init__(self, **kwargs) |
||
244 | | Constructor: Two ways of creating a new pythong GDP datum object: |
||
245 | | - Create a new object and allocate new memeory for it by calling |
||
246 | | the C library function |
||
247 | | - Create a new object, but associate it with an existing memory |
||
248 | | location. |
||
249 | | In the first case: we need to free the memory when it is no longer |
||
250 | | needed. In the second case: we shouldn't free memory allocated by |
||
251 | | someone else. |
||
252 | | |
||
253 | | getbuf(self) |
||
254 | | Return the GDP_BUF associated with this GDP_DATUM. |
||
255 | | |
||
256 | | getdlen(self) |
||
257 | | Returns the length of the data in GDP_BUF associated with |
||
258 | | this GDP_DATUM. |
||
259 | | |
||
260 | | gethash(self, gin) |
||
261 | | Compute the hash of the datum for a given log? |
||
262 | | |
||
263 | | getrecno(self) |
||
264 | | Get the corresponding record number associated with this datum |
||
265 | | |
||
266 | | getsig(self) |
||
267 | | Return the signature as a binary string. |
||
268 | | As of current, the signature is over (recno|data) |
||
269 | | |
||
270 | | getts(self) |
||
271 | | Return the timestamp associated with this GDP_DATUM in the form of a |
||
272 | | dictionary. The keys are: tv_sec, tv_nsec and tv_accuracy |
||
273 | | |
||
274 | | print_(self, fh, flags) |
||
275 | | Print the GDP datum C memory location contents to a file handle fh. |
||
276 | | fh could be sys.stdout, or any other open file handle. Flags are |
||
277 | | predefined constants (see GDP_DATUM_PR*) |
||
278 | | |
||
279 | | Note: This just calls the corresponding C library function which |
||
280 | | handles the printing |
||
281 | 9d041c43 | Nitesh Mor | | |
282 | a3d5bf5f | Nitesh Mor | | reset(self) |
283 | | Reset the datum |
||
284 | 9d041c43 | Nitesh Mor | | |
285 | a3d5bf5f | Nitesh Mor | | ---------------------------------------------------------------------- |
286 | | Data and other attributes defined here: |
||
287 | fae38f90 | Nitesh Mor | | |
288 | a3d5bf5f | Nitesh Mor | | gdp_datum_t = <class 'gdp.GDP_DATUM.gdp_datum_t'> |
289 | |||
290 | Help on class GDP_EVENT in gdp: |
||
291 | |||
292 | gdp.GDP_EVENT = class GDP_EVENT |
||
293 | | A class that represents a GDP event |
||
294 | c118066e | Nitesh Mor | | |
295 | a3d5bf5f | Nitesh Mor | | Methods defined here: |
296 | 9d041c43 | Nitesh Mor | | |
297 | a3d5bf5f | Nitesh Mor | | __del__(self) |
298 | | Destructor: Does nothing if this GDP datum was created by |
||
299 | | passing an exisiting datum pointer |
||
300 | 9d041c43 | Nitesh Mor | | |
301 | a3d5bf5f | Nitesh Mor | | __getitem__(self, key) |
302 | fae38f90 | Nitesh Mor | | |
303 | a3d5bf5f | Nitesh Mor | | __init__(self, **kwargs) |
304 | | Creates a new object, but associate it with an existing memory |
||
305 | | location. |
||
306 | | |
||
307 | | getdatum(self) |
||
308 | | |
||
309 | | getgin(self) |
||
310 | | |
||
311 | | getstat(self) |
||
312 | | |
||
313 | | gettype(self) |
||
314 | | Get the event type for this event |
||
315 | | |
||
316 | | getudata(self) |
||
317 | | |
||
318 | | print_(self, fh) |
||
319 | | Print the GDP event C memory location contents to a file handle fh. |
||
320 | | fh could be sys.stdout, or any other open file handle. Flags are |
||
321 | | predefined constants (see GDP_EVENT_PR*) |
||
322 | | |
||
323 | | Note: This just calls the corresponding C library function which |
||
324 | | handles the printing |
||
325 | fae38f90 | Nitesh Mor | | |
326 | 9d041c43 | Nitesh Mor | | ---------------------------------------------------------------------- |
327 | a3d5bf5f | Nitesh Mor | | Data and other attributes defined here: |
328 | 9d041c43 | Nitesh Mor | | |
329 | a3d5bf5f | Nitesh Mor | | gdp_event_t = <class 'gdp.GDP_EVENT.gdp_event_t'> |
330 | |||
331 | Help on class GDP_BUF in gdp: |
||
332 | |||
333 | gdp.GDP_BUF = class GDP_BUF(__builtin__.object) |
||
334 | | A class only for internal use. It is only a partially |
||
335 | | implemented interface for the moment. |
||
336 | c118066e | Nitesh Mor | | |
337 | a3d5bf5f | Nitesh Mor | | Methods defined here: |
338 | | |
||
339 | | __del__(self) |
||
340 | | Free the memory, but only if we allocated it. |
||
341 | | |
||
342 | | __init__(self, **kwargs) |
||
343 | | Creates a new buffer structure by calling C functions, unless |
||
344 | | an existing pointer to a C-structure is provided to us |
||
345 | | externally (by using a 'ptr=x' argument). |
||
346 | | |
||
347 | | drain(self) |
||
348 | | simply remove the data from the buffer |
||
349 | | |
||
350 | | getlength(self) |
||
351 | | Returns the length of the data associated with this buffer |
||
352 | | |
||
353 | | peek(self) |
||
354 | | Peek into a buffer (does not drain it) |
||
355 | | |
||
356 | | read(self) |
||
357 | | Read data from buffer (effectively drains it too) |
||
358 | | |
||
359 | | reset(self) |
||
360 | | Reset the buffer |
||
361 | | |
||
362 | | write(self, data) |
||
363 | | write data to buffer |
||
364 | 9d041c43 | Nitesh Mor | | |
365 | | ---------------------------------------------------------------------- |
||
366 | a3d5bf5f | Nitesh Mor | | Data descriptors defined here: |
367 | | |
||
368 | | __dict__ |
||
369 | | dictionary for instance variables (if defined) |
||
370 | | |
||
371 | | __weakref__ |
||
372 | | list of weak references to the object (if defined) |
||
373 | | |
||
374 | | ---------------------------------------------------------------------- |
||
375 | | Data and other attributes defined here: |
||
376 | | |
||
377 | | gdp_buf_t = <class 'gdp.GDP_BUF.gdp_buf_t'> |
||
378 | |||
379 | Help on class GDP_HASH in gdp: |
||
380 | |||
381 | gdp.GDP_HASH = class GDP_HASH(__builtin__.object) |
||
382 | | A class only for internal use. It is only a partially |
||
383 | | implemented interface for the moment. |
||
384 | | |
||
385 | | Methods defined here: |
||
386 | | |
||
387 | | __del__(self) |
||
388 | | Free the memory |
||
389 | | |
||
390 | | __eq__(self, other) |
||
391 | | |
||
392 | | __init__(self, alg, hashbytes, **kwargs) |
||
393 | | Creates a new hash structure by calling C functions |
||
394 | | |
||
395 | | get(self) |
||
396 | | Read data from hash structure |
||
397 | | |
||
398 | | getlength(self) |
||
399 | | Returns the length of the data associated with this hash structure |
||
400 | | |
||
401 | | reset(self) |
||
402 | | Reset the hash structure |
||
403 | | |
||
404 | | set(self, hashbytes) |
||
405 | | write hashbytes to hash structure |
||
406 | | |
||
407 | | ---------------------------------------------------------------------- |
||
408 | | Data descriptors defined here: |
||
409 | | |
||
410 | | __dict__ |
||
411 | | dictionary for instance variables (if defined) |
||
412 | | |
||
413 | | __weakref__ |
||
414 | | list of weak references to the object (if defined) |
||
415 | | |
||
416 | | ---------------------------------------------------------------------- |
||
417 | | Data and other attributes defined here: |
||
418 | | |
||
419 | | gdp_hash_t = <class 'gdp.GDP_HASH.gdp_hash_t'> |
||
420 | |||
421 | Help on class GDP_SIG in gdp: |
||
422 | |||
423 | gdp.GDP_SIG = class GDP_SIG(__builtin__.object) |
||
424 | | A class only for internal use. It is only a partially |
||
425 | | implemented interface for the moment. |
||
426 | | |
||
427 | | Methods defined here: |
||
428 | | |
||
429 | | __del__(self) |
||
430 | | Free the memory |
||
431 | | |
||
432 | | __init__(self, alg, sigbytes, **kwargs) |
||
433 | | Creates a new sig structure by calling C functions |
||
434 | | |
||
435 | | get(self) |
||
436 | | Read data from sig structure |
||
437 | | |
||
438 | | getlength(self) |
||
439 | | Returns the length of the data associated with this sig structure |
||
440 | | |
||
441 | | reset(self) |
||
442 | | Reset the sig structure |
||
443 | | |
||
444 | | set(self, sigbytes) |
||
445 | | write sigbytes to sig structure |
||
446 | 56dc2fe6 | Nitesh Mor | | |
447 | | ---------------------------------------------------------------------- |
||
448 | | Data descriptors defined here: |
||
449 | | |
||
450 | | __dict__ |
||
451 | | dictionary for instance variables (if defined) |
||
452 | | |
||
453 | | __weakref__ |
||
454 | | list of weak references to the object (if defined) |
||
455 | | |
||
456 | | ---------------------------------------------------------------------- |
||
457 | 9d041c43 | Nitesh Mor | | Data and other attributes defined here: |
458 | | |
||
459 | a3d5bf5f | Nitesh Mor | | gdp_sig_t = <class 'gdp.GDP_SIG.gdp_sig_t'> |
460 | |||
461 | Help on class GDP_MD in gdp: |
||
462 | |||
463 | gdp.GDP_MD = class GDP_MD |
||
464 | | GCL Metadata equivalent -- for internal use only. |
||
465 | | The C equivalent exposed to python users is of a dictionary. |
||
466 | | |
||
467 | | Methods defined here: |
||
468 | | |
||
469 | | __del__(self) |
||
470 | | Destructor: Frees the C structure |
||
471 | | |
||
472 | | __init__(self, **kwargs) |
||
473 | | Constructor: calls the C-function to allocate memory. |
||
474 | | |
||
475 | | add(self, md_id, data) |
||
476 | | Add a new entry to the metadata set |
||
477 | | |
||
478 | | dump(self, fh, detail, indent) |
||
479 | | Print the gdp_md C memory location contents to a file handle fh. |
||
480 | | fh could be sys.stdout, or any other open file handle. |
||
481 | | Note: This just calls the corresponding C library function which |
||
482 | | handles the printing, details, and indentation. |
||
483 | 9d041c43 | Nitesh Mor | | |
484 | a3d5bf5f | Nitesh Mor | | find(self, md_id) |
485 | | Get a new entry from the metadata set by id |
||
486 | 9d041c43 | Nitesh Mor | | |
487 | a3d5bf5f | Nitesh Mor | | get(self, index) |
488 | | Get a new entry from the metadata set by index |
||
489 | 9d041c43 | Nitesh Mor | | |
490 | a3d5bf5f | Nitesh Mor | | ---------------------------------------------------------------------- |
491 | | Data and other attributes defined here: |
||
492 | 9d041c43 | Nitesh Mor | | |
493 | a3d5bf5f | Nitesh Mor | | gdp_md_t = <class 'gdp.GDP_MD.gdp_md_t'> |