Project

General

Profile

Statistics
| Branch: | Tag: | Revision:

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'>