Python API overview

From ClusterpointWiki2

Jump to: navigation, search

Clusterpoint Python API - Pycps - provides easier access to CPS from Python.

Contents

Install

You can get the latest Pycps from it's github repository.

Connections

All interactions with the Clusterpoint Storage happen through a Connection class instance. The Connection object manages connection to the Clusterpoint server and provides methods for Clusterpoint Storage commands like insert() and search(). For Connection's constructor You must specify these arguments:

  1. An host address string. Example: '192.168.1.103'
  2. A port number. Example : 80
  3. The name of a Clusterpoint Storage You wish to connect to
  4. A username for authentication
  5. A password for authentification

You can also optionally specify some named arguments, like:

storage policy, is not "/document/id". You have to specify the relative path to the root, separated by slashes, like "./id" for the default value.

# Create a connection to a Clusterpoint storage.
con = pycps.Connection('192.168.1.103', 80, 'test_storage', 'root', 'password')

Request methods

The command methods take various parameters depending on command and return one of Response objects that contains all information received from the Clusterpoint Storage.

# Insert multiple documents in the Storage (the keys of the dict will be used as the document ids).
con.insert({5: '<text>foobar</text>',
            6: '<text>baz</text>',
            'id7': {'title': 'Loerem Ipsum', 'text': 'Long, long text'}})

# Delete two of the inserted documents.
con.delete([5, 'id7'])

The full list of available command methods see in the API reference.

Requests

For situations where the same or similar requests are being sent repeatedly it might be useful to construct and send the underlying Request object manually instead of using the Connection class's methods. For most of the command methods there exist the underlying Request class, except for some simple commands the base Request class is used.

All Request classes take as their first argument the Connection instance they are to use.

# Manually send clear command request.
req = pycps.Request(con, 'clear')
req.send()

# Make a request object that can be used repeatedly for searching for similar text to the given text.
text = "Long interesting text be here."
req = pycps.SimilarRequest(con, text, 10, 5, mode='text')
req.send()

Responses

Both command methods and the underlying Request classes will return a appropriate response object. Response objects provide property fields for obtaining common Clusterpoint Storage response information like lenght of processing time (seconds), the name of the Storage (storage_name) and the command the response was generated for (command). Every Response class also allows obtains the whole content part of the Storage response in various formats with get_content_dict(), get_content_string(), get_content_etree() methods. Specific command information is also made available in the corresponding responses. Se the reference for listing of available information in each Response object.

# Get status
resp = con.status()
# Dump the status dict
print("Processed in {0}; dump:\n{1}". format(resp.seconds, resp.status))

# Get a ListResponse with last added documents.
resp = con.retrieve_last(docs=10, offset=0)
# Use the returned documents.
if resp.found:
    for document in resp.get_docuemens(doc_format='string'):
        print(document)
  1. Insert a couple of documents yielding a ModifiedResponse.

resp = con.insert({1: {'text': 'Lorem Ipsum ...', 'title': 'Test'}, 2: '
'})

  1. Get list of inserted documents.

print("Modified:\n" + '\n'.join(resp.modified_ids()))

Document formats

For modify type commands documents to be inserted in the Storage can be specified in one of the supported formats -

All these formats are also available from ListResponse via method get_documents() specifying the doc_format named parameter accordingly. The Whole XML response's content is available in these formats through get_content_etree(), get_content_string() and get_content_dict() respectively.

Errors

The Pycps package will raise exceptions if there are problems with connecting to the Clusterpoint Storage and for some incorrect parameter values or malformed xml structures. Pycps will also raise the all important Clusterpoint transaction errors that are received from the Clusterpoint Storage as exceptions and all nonfatal errors (not resulting in data loss) as warnings. Especially APIError and APIWarning objects contain useful information on what went wrong.

try:
    con = pycps.Connection('192.168.1.103', 80, 'test_storage', 'root', 'password')
except ConnectionError:
    print("Can't Reach the server!")

try:
    con.delete([1,4,6,7])
except APIError as e:
    print("Could not delete all documents as these document's don't exist: " + ' ,  '.join(e.document_id))

Note that multi-document modifying requests might return errors only for some of the document ids, while the rest of the modifications will take place successfully. In order to detect these situations, You can check the document_id list of the APIException object.

Personal tools
Namespaces
Variants
Actions
Download
Developer area
Admin area
Toolbox
Navigation