ers Documentation Release 0.13 ers-devs

Transcription

1 ers Documentation Release 0.13 ers-devs November 14, 2013

2

3 Contents 1 Installation 3 2 Run as Virtual Machine 5 3 ers Package ers Package daemon Module ers Module models Module sync_global Module utils Module zeroconf Module Indices and tables 9 i

4 ii

5 Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Installation 3

8 4 Chapter 1. Installation

9 CHAPTER 2 Run as Virtual Machine 1. Download the Virtual Machine with a pre-configured ERS setup: 2. Run the Virtual Machine using virtualization software, like VirtualBox. 5

10 6 Chapter 2. Run as Virtual Machine

11 CHAPTER 3 ers Package 3.1 ers Package 3.2 daemon Module class ers.daemon.ersdaemon(peer_type= contrib, port=5984, dbname= ers-public, pidfile= /var/run/ers_daemon.pid, tries=10, logger=none) The daemon class for the ERS daemon. dbname = None logger = None peer_type = None pidfile = None port = None peer_type ( contrib or bridge ) type of daemon instance port (int.) TCP port number of CouchDB dbname (str.) CouchDB database name pidfile (str.) filepath to a PID file for this ERS daemon instance tries (int.) number of tries to connect to CouchDB logger (Logger instance) logger for the daemon to use start() Starting up an ERS daemon. stop() Stopping an ERS daemon. tries = None class ers.daemon.erspeerinfo(service_name, host, ip, port, dbname= ers-public, peer_type= contrib ) Bases: ers.zeroconf.servicepeer 7

12 This class contains information on an ERS peer. dbname = None static from_service_peer(svc_peer) Get an ERSPeerInfo instance from a given service peer. svc_peer (ServicePeer instance) a service peer Return type ERSPeerInfo instance peer_type = None to_json() Returns the ERS peer information from this instance in JSON format. Return type dict. ers.daemon.run() Parse the given arguments for setting up the daemon and run it. ers.daemon.setup_logging(args) Setup a file or system logger. args (Object) has a logtype attribute (which can be file or syslog ). Return type Logger instance 3.3 ers Module class ers.ers.erslocal(server_url= dbname= ers, model=<ers.models.models object at 0x3a287d0>, fixed_peers=(), local_only=false, reset_database=false) Bases: ers.ers.ersreadonly The read-write local class for an ERS peer. server_url (str.) peer s server URL dbname (str.) CouchDB database name model (LocalModelBase instance) document model fixed_peers (tuple) known peers local_only (bool.) whether or not the peer is local-only reset_database whether or not to reset the CouchDB database on the given server add_data(s, p, o, g) Add a value for a property in an entity in the given graph (create the entity if it does not exist yet). s (str.) RDF subject p (str.) RDF property o (str.) RDF object g (str.) RDF graph 8 Chapter 3. ers Package

13 cache_entity(entity) Place an entity in the cache. This mark the entity as being cached and store the currently loaded documents in the cache. Later on, ERS will automatically update the description of this entity with new / updated entity An entity object create_entity(entity_name) Create a new entity, return it and store in as a new document in the public store delete_entity(entity, graph=none) Delete an entity from the given graph. entity (str.) entity to delete graph (str.) graph to delete from Returns success status Return type bool. delete_value(entity, prop, graph=none) Delete all of the peer s values for a property in an entity from the given graph. entity (str.) entity to delete for prop (str.) property to delete for graph (str.) graph to delete from Returns success status Return type bool. a unique identifier for this ERS node is_cached(entity_name) Check if an entity is listed as being cached persist_entity(entity) Save an updated entity update_value(subject, object, graph=none) Update a value for an identifier + property pair (create it if it does not exist yet). [Not yet implemented] subject (str.) subject to update for object (str.) object to update graph (str.) graph to use for updating write_cache(cache, graph) Write cache to the given graph. cache (array) cache to write graph (str.) graph to write to 3.3. ers Module 9

14 class ers.ers.ersreadonly(server_url= dbname= ers, model=<ers.models.models object at 0x3a287d0>, fixed_peers=(), local_only=false) Bases: object The read-only class for an ERS peer. server_url (str.) peer s server URL dbname (str.) CouchDB database name model (LocalModelBase instance) document model fixed_peers (tuple) known peers local_only (bool.) whether or not the peer is local-only contains_entity(entity_name) Search in the public DB is there is already a document for describing that entity exist(subject, graph) Check whether a subject exists in a given graph. subject (str.) subject to check for graph (str.) graph to use for checking Return type bool. get_annotation(entity) Get data from self and known peers for a given subject. entity (str.) subject to get data for Return type dict. get_data(subject, graph=none) Get all property + value pairs for a given subject and graph. subject (str.) subject to get data for graph (str.) graph to get data for Return type property-value dictionary get_doc(subject, graph) Get the documents for a given subject and graph. subject (str.) subject to get data for graph (str.) graph to get data for Return type array get_entity(entity_name) Create an entity object, fill it will all the relevant documents get_peers() Get the known peers. Return type array 10 Chapter 3. ers Package

15 get_values(entity, prop) Get the value for an identifier + property pair (return null or a special value if it does not exist). entity (str.) entity to get data for prop (str.) property to get data for Returns list of values or an empty list search(prop, value=none) Search entities by property or property + value pair. prop (str.) property to search for value (str.) value to search for Returns list of unique (entity, graph) pairs class ers.ers.entity(entity_name) An entity description is contained in various CouchDB documents add_document(document, source) Add a document to the list of documents that compose this entity add_property(property, value) Add a property to the description of the entity TODO: we can only edit the local or private documents delete_property(property, value) Delete a property to the description of the entity TODO: we can only edit the local or private documents get_documents() Return all the documents associated to this entity and their source get_documents_ids() Get the identifiers of all the documents associated to the entity the name of that entity get_properties() Get the aggregated properties out of all the individual documents get_raw_documents() Get the content of all the documents associated to the entity 3.4 models Module class ers.models.localmodelbase Bases: object Base class for all the serialisations add_data(couch_doc, cache) cache_key(couch_key) Get the default CouchDB cache key. Return type str. content_doc() 3.4. models Module 11

16 couch_key(cache_key, graph) Get the default CouchDB key. Return type str. delete_property(couch_doc, prop, value) get_data(doc, subject, graph) index_doc() Get the default CouchDB index design document. Return type JSON object initial_docs() Get the default initial CouchDB documents (index design document and state document). Return type array initial_docs_cache() initial_docs_private() initial_docs_public() state_doc() Get the default CouchDB state document. Return type JSON object view_name = _all_docs class ers.models.models Bases: ers.models.localmodelbase The model class for document model type S. Example document: { _id : _rev : 1- e004c4ac4b5f ad417d364a85e, : [ } Tim Berners-Lee ], : [ ] TimBL, timbl add_data(couch_doc, cache) Add cache data to a CouchDB document. couch_doc (CouchDB document object) the CouchDB document to add data to cache (dict.) the cache data to add add_property(couch_doc, prop, value) cache_key(couch_key) Get the CouchDB cache key. couch_key (str.) the CouchDB key Return type str. 12 Chapter 3. ers Package

17 couch_key(cache_key, graph) Get the CouchDB key. cache_key (str.) the CouchDB cache key graph (str.) the RDF graph Return type str. delete_property(couch_doc, prop, value) Deletes a property from the given CouchDB document. couch_doc (CouchDB document object) the CouchDB document prop (str.) the property to delete get_data(doc, subject, graph) Get data from a CouchDB document given a subject and graph (call with subject=none and graph=none to get data from a document without an _id). doc (CouchDB document object) the CouchDB document from which to get data subject (str.) the subject to get data for graph (str.) the graph to get data for Return type property-value dictionary classmethod index_doc() Get the CouchDB index design document (containing two views). Return type JSON object 3.5 sync_global Module class ers.sync_global.graphsynch(ersreadwrite, name, graph) Bases: threading.thread Synchronizes a peer s graph data with the global aggregator (creates a synch thread for a given graph using _changes feed). ERSReadWrite (ERSReadWrite instance) ERSReadWrite to used for synchronization name (str.) thread name graph (str.) graph to use for synchronization dump_changes_to_file(prev_seq, stream) Save the changes made to a log file. prev_seq (int.) sequence number of the previous successfully synchronized sequence from the global aggregator stream (ChangesStream instance) stream of made changes 3.5. sync_global Module 13

18 Returns last synchronized sequence number filter_by_graph_doc() Defines the filter document by graph. One DB stores multiple graphs. Returns a CouchDB filter design document Return type JSON object get_previous_seq_num() Ask global server what was the last synchronized sequence number for this graph. Returns previous sequence number (-1 if server request didn t succeed) Return type int. run() Start the synchronization process set_finished() Set the synchronization status to finished. set_new_seq_num(new_seq) Update the global last synchronized sequence number for this graph. new_seq (int.) new sequence number Returns success status Return type bool. class ers.sync_global.synchronizationmanager(ersreadwrite) Bases: object Manages a synchronization process. ERSReadWrite (ERSReadWrite instance) ERSReadWrite to used for synchronization exists_synch_thread(graph) Check whether a synchronization process exists for the given graph. graph (str.) graph to use for synchronization Return type bool. get_thread_name(graph) Get the tread name of the synchronization process. graph (str.) graph used for synchronization Return type str. start_synch(graph) Start the synchronization process. graph (str.) graph to use for synchronization start_synch_everything() stop_synch(graph) Stop the synchronization process. graph (str.) graph used for synchronization stop_synch_everything() ers.sync_global.test() 14 Chapter 3. ers Package

19 3.6 utils Module class ers.utils.entitycache Bases: collections.defaultdict Equivalent to defaultdict(lambda: defaultdict(set)). add(s, p, o) Add <s, p, o> to cache. s (str.) RDF subject p (str.) RDF property o (str.) RDF object parse_nt(**kwargs) Parse N-Triples data. Returns self parse_nt_rdflib(**kwargs) Parse N-Triples data using rdflib. Returns self ers.utils.import_nt(registry, file_name, target_graph) Import N-Triples file. registry (ERSLocal instance) registry used for writing the data file_name (str.) file name target_graph (str.) graph to write to ers.utils.import_nt_rdflib(registry, file_name, target_graph) Import N-Triples file using rdflib. registry (ERSLocal instance) registry used for writing the data file_name (str.) file name target_graph (str.) graph to write to 3.7 zeroconf Module This module contains functions for publishing and discovering services over Zeroconf protocols. Currently only Avahi is supported. class ers.zeroconf.publishedservice(name, service_type, port, domain=, host=, text= ) This class represents a service published over Zeroconf. domain = None host = None name = None 3.6. utils Module 15

20 port = None publish() Publishes the service defined by this handle. service_type = None text = None unpublish() Unpublishes the service. class ers.zeroconf.servicemonitor(service_type, on_join=none, on_leave=none, on_error=none, see_self=false) This class represents a monitor for services of a given type advertised over the network. Whenever a peer that publishes a service of type service_type comes into range, a series on on_join functions specified by the user will be called. They will receive as their only parameter an object describing the peer (its IP, port, etc.). The object also acts as a handle for recognizing a peer that has gone offline (in which case the on_leave functions are similarly called). Finally, the on_error functions will be called whenever an error occurs in the monitoring process. Notes: In order for the monitor to work, you must have a GTK mainloop running in your application. This library does not automatically create one. When the monitor starts up, a series of join events will be perceived for every peer that is currently online, even if the service was published some time in the past. Note: If see_self is set to True, the monitor will also report services published locally. get_peers() Gets a dictionary of all currently online peers for this service. on_error = None on_join = None on_leave = None see_self = None service_type = None shutdown() Shuts down this monitor. start() Starts the monitor. class ers.zeroconf.servicepeer(service_name, service_type, host, ip, port) This class represents a peer over a given service published via Zeroconf on the network. host = None ip = None port = None service_name = None service_type = None ers.zeroconf.test() Runs a test of this module. 16 Chapter 3. ers Package

21 Note: This test requires user interaction zeroconf Module 17

22 18 Chapter 3. ers Package

23 CHAPTER 4 Indices and tables genindex modindex search 19

24 20 Chapter 4. Indices and tables

25 Python Module Index e ers. init,?? ers.daemon,?? ers.ers,?? ers.models,?? ers.sync_global,?? ers.utils,?? ers.zeroconf,?? 21