API Specification
  • Updated on 12 Nov 2019
  • 88 minutes to read
  • Contributors
  • Print
  • Share
  • Dark
    Light

API Specification

  • Print
  • Share
  • Dark
    Light

API Specification

API documentation for module c8 {#c8}

Sub-modules

Module c8.api

Class APIWrapper {#c8.api.APIWrapper}

class APIWrapper(connection, executor)

Base class for API wrappers.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor

Descendants

Instance variables

Variable context {#c8.api.APIWrapper.context}

Return the API execution context.

:return: API execution context. Possible values are "default", "async",
"batch" and "transaction".
:rtype: str | unicode

Variable fabric_name {#c8.api.APIWrapper.fabric_name}

Return the name of the current fabric.

:return: Fabric name.
:rtype: str | unicode

Variable fn_name {#c8.api.APIWrapper.fn_name}

Return the name of the current function.

:return: Fabric name.
:rtype: str | unicode

Variable stream_name {#c8.api.APIWrapper.stream_name}

Return the name of the current stream.

:return: Stream name.
:rtype: str | unicode

Variable tenant_name {#c8.api.APIWrapper.tenant_name}

Return the name of the current tenant.

:return: tenant name.
:rtype: str | unicode

Variable topic_name {#c8.api.APIWrapper.topic_name}

Return the name of the current topic.

:return: topic name.
:rtype: str | unicode

Variable topic_persistence {#c8.api.APIWrapper.topic_persistence}

Return true if it is a persistent topic.

:return: topic persistence.
:rtype: bool

Variable username {#c8.api.APIWrapper.username}

Return the username.

:returns: Username.
:rtype: str | unicode

Module c8.c8ql {#c8.c8ql}

Classes

Class C8QL {#c8.c8ql.C8QL}

class C8QL(connection, executor)

C8QL (C8Db Query Language) API wrapper.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor

Ancestors (in MRO)

Instance variables

Variable cache {#c8.c8ql.C8QL.cache}

Return the query cache API wrapper.

:return: Query cache API wrapper.
:rtype: c8.c8ql.C8QLQueryCache

Methods

Method clear_slow_queries {#c8.c8ql.C8QL.clear_slow_queries}

def clear_slow_queries(self)

Clear slow C8QL queries.

:return: True if slow queries were cleared successfully.
:rtype: bool
:raise c8.exceptions.C8QLQueryClearError: If operation fails.

Method execute {#c8.c8ql.C8QL.execute}

def execute(self, query, count=False, bind_vars=None, cache=None, profile=None)

Execute the query and return the result cursor.

:param query: Query to execute.
:type query: str | unicode
:param count: If set to True, the total document count is included in
the result cursor.
:type count: bool
:param bind_vars: Bind variables for the query.
:type bind_vars: dict
:param cache: If set to True, the query cache is used. The operation
mode of the query cache must be set to "on" or "demand".
:type cache: bool
:param profile: Return additional profiling details in the cursor,
unless the query cache is used.
:type profile: bool
:return: Result cursor.
:rtype: c8.cursor.Cursor
:raise c8.exceptions.C8QLQueryExecuteError: If execute fails.

Method explain {#c8.c8ql.C8QL.explain}

def explain(self, query, all_plans=False, max_plans=None, opt_rules=None)

Inspect the query and return its metadata without executing it.

:param query: Query to inspect.
:type query: str | unicode
:param all_plans: If set to True, all possible execution plans are
returned in the result. If set to False, only the optimal plan
is returned.
:type all_plans: bool
:param max_plans: Total number of plans generated by the optimizer.
:type max_plans: int
:param opt_rules: List of optimizer rules.
:type opt_rules: list
:return: Execution plan, or plans if all_plans was set to True.
:rtype: dict | list
:raise c8.exceptions.C8QLQueryExplainError: If explain fails.

Method kill {#c8.c8ql.C8QL.kill}

def kill(self, query_id)

Kill a running query.

:param query_id: Query ID.
:type query_id: str | unicode
:return: True if kill request was sent successfully.
:rtype: bool
:raise c8.exceptions.C8QLQueryKillError: If the send fails.

Method queries {#c8.c8ql.C8QL.queries}

def queries(self)

Return the currently running C8QL queries.

:return: Running C8QL queries.
:rtype: [dict]
:raise c8.exceptions.C8QLQueryListError: If retrieval fails.

Method slow_queries {#c8.c8ql.C8QL.slow_queries}

def slow_queries(self)

Return a list of all slow C8QL queries.

:return: Slow C8QL queries.
:rtype: [dict]
:raise c8.exceptions.C8QLQueryListError: If retrieval fails.

Method validate {#c8.c8ql.C8QL.validate}

def validate(self, query)

Parse and validate the query without executing it.

:param query: Query to validate.
:type query: str | unicode
:return: Query details.
:rtype: dict
:raise c8.exceptions.C8QLQueryValidateError: If validation fails.

Module c8.client {#c8.client}

Classes

Class C8Client {#c8.client.C8Client}

class C8Client(protocol='http', host='127.0.0.1', port=80, stream_port='6650', http_client=None)

C8Db client.

:param protocol: Internet transfer protocol (default: "http").
:type protocol: str | unicode
:param host: C8Db host (default: "127.0.0.1").
:type host: str | unicode
:param port: C8Db port (default: 8529).
:type port: int
:param http_client: User-defined HTTP client.
:type http_client: c8.http.HTTPClient

Instance variables

Variable base_url {#c8.client.C8Client.base_url}

Return the C8Db base URL.

:return: C8Db base URL.
:rtype: str | unicode

Variable host {#c8.client.C8Client.host}

Return the C8Db host.

:return: C8Db host.
:rtype: str | unicode

Variable port {#c8.client.C8Client.port}

Return the C8Db port.

:return: C8Db port.
:rtype: int

Variable protocol {#c8.client.C8Client.protocol}

Return the internet transfer protocol (e.g. "http").

:return: Internet transfer protocol.
:rtype: str | unicode

Variable version {#c8.client.C8Client.version}

Return the client version.

:return: Client version.
:rtype: str | unicode

Methods

Method fabric {#c8.client.C8Client.fabric}

def fabric(self, tenant, name, username, password, verify=False)

Connect to a fabric and return the fabric API wrapper.

:param name: Fabric name.
:type name: str | unicode
:param username: Username for basic authentication.
:type username: str | unicode
:param password: Password for basic authentication.
:type password: str | unicode
:param verify: Verify the connection by sending a test request.
:type verify: bool
:return: Standard fabric API wrapper.
:rtype: c8.fabric.StandardFabric
:raise c8.exceptions.ServerConnectionError: If verify was set
to True and the connection to C8Db fails.

Method tenant {#c8.client.C8Client.tenant}

def tenant(self, name, fabricname, username, password, verify=False)

Connect to a fabric and return the fabric API wrapper.

:param name: Tenant name.
:type name: str | unicode
:param fabricname: Tenant fabric name.
:type name: str | unicode
:param username: Username for basic authentication.
:type username: str | unicode
:param password: Password for basic authentication.
:type password: str | unicode
:param verify: Verify the connection by sending a test request.
:type verify: bool
:return: Standard fabric API wrapper.
:rtype: c8.fabric.StandardFabric
:raise c8.exceptions.ServerConnectionError: If verify was set
to True and the connection to C8Db fails.

Module c8.collection {#c8.collection}

Classes

Class EdgeCollection {#c8.collection.EdgeCollection}

class EdgeCollection(connection, executor, graph, name)

C8Db edge collection API wrapper.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor
:param graph: Graph name.
:type graph: str | unicode
:param name: Edge collection name.
:type name: str | unicode

Ancestors (in MRO)

Instance variables

Variable graph {#c8.collection.EdgeCollection.graph}

Return the graph name.

:return: Graph name.
:rtype: str | unicode

Methods

Method delete {#c8.collection.EdgeCollection.delete}

def delete(self, edge, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete an edge document.

:param edge: Edge document ID, key or body. Document body must contain
the "_id" or "_key" field.
:type edge: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in edge if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:param ignore_missing: Do not raise an exception on missing document.
This parameter has no effect in transactions where an exception is
always raised on failures.
:type ignore_missing: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: True if edge was deleted successfully, False if edge was not
found and ignore_missing was set to True (does not apply in
transactions).
:rtype: bool
:raise c8.exceptions.DocumentDeleteError: If delete fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method edges {#c8.collection.EdgeCollection.edges}

def edges(self, vertex, direction=None)

Return the edge documents coming in and/or out of the vertex.

:param vertex: Vertex document ID or body with "_id" field.
:type vertex: str | unicode | dict
:param direction: The direction of the edges. Allowed values are "in"
and "out". If not set, edges in both directions are returned.
:type direction: str | unicode
:return: List of edges
:rtype: dict
:raise c8.exceptions.EdgeListError: If retrieval fails.

Method get {#c8.collection.EdgeCollection.get}

def get(self, edge, rev=None, check_rev=True)

Return an edge document.

:param edge: Edge document ID, key or body. Document body must contain
the "_id" or "_key" field.
:type edge: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in edge if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:return: Edge document or None if not found.
:rtype: dict | None
:raise c8.exceptions.DocumentGetError: If retrieval fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method insert {#c8.collection.EdgeCollection.insert}

def insert(self, edge, sync=None, silent=False)

Insert a new edge document.

:param edge: New edge document to insert. It must contain "_from" and
"_to" fields. If it has "_key" or "_id" field, its value is used
as key of the new edge document (otherwise it is auto-generated).
Any "_rev" field is ignored.
:type edge: dict
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method link {#c8.collection.EdgeCollection.link}

def link(self, from_vertex, to_vertex, data=None, sync=None, silent=False)

Insert a new edge document linking the given vertices.

:param from_vertex: "From" vertex document ID or body with "_id" field.
:type from_vertex: str | unicode | dict
:param to_vertex: "To" vertex document ID or body with "_id" field.
:type to_vertex: str | unicode | dict
:param data: Any extra data for the new edge document. If it has "_key"
or "_id" field, its value is used as key of the new edge document
(otherwise it is auto-generated).
:type data: dict
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method replace {#c8.collection.EdgeCollection.replace}

def replace(self, edge, check_rev=True, sync=None, silent=False)

Replace an edge document.

:param edge: New edge document to replace the old one with. It must
contain the "_key" or "_id" field. It must also contain the "_from"
and "_to" fields.
:type edge: dict
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentReplaceError: If replace fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method update {#c8.collection.EdgeCollection.update}

def update(self, edge, check_rev=True, keep_none=True, sync=None, silent=False)

Update an edge document.

:param edge: Partial or full edge document with updated values. It must
contain the "_key" or "_id" field.
:type edge: dict
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:param keep_none: If set to True, fields with value None are retained
in the document. If set to False, they are removed completely.
:type keep_none: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentUpdateError: If update fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Class StandardCollection {#c8.collection.StandardCollection}

class StandardCollection(connection, executor, name)

Standard C8Db collection API wrapper.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor
:param name: Collection name.
:type name: str | unicode

Ancestors (in MRO)

Methods

Method delete {#c8.collection.StandardCollection.delete}

def delete(self, document, rev=None, check_rev=True, ignore_missing=False, return_old=False, sync=None, silent=False)

Delete a document.

:param document: Document ID, key or body. Document body must contain
the "_id" or "_key" field.
:type document: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in document if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of document (if given)
is compared against the revision of target document.
:type check_rev: bool
:param ignore_missing: Do not raise an exception on missing document.
This parameter has no effect in transactions where an exception is
always raised on failures.
:type ignore_missing: bool
:param return_old: Include body of the old document in the result.
:type return_old: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision), or True if
parameter silent was set to True, or False if document was not
found and ignore_missing was set to True (does not apply in
transactions).
:rtype: bool | dict
:raise c8.exceptions.DocumentDeleteError: If delete fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method delete_many {#c8.collection.StandardCollection.delete_many}

def delete_many(self, documents, return_old=False, check_rev=True, sync=None, silent=False)

Delete multiple documents.

If deleting a document fails, the exception object is placed in the
result list instead of document metadata.

:param documents: Document IDs, keys or bodies. Document bodies must
contain the "_id" or "_key" fields.
:type documents: [str | unicode | dict]
:param return_old: Include bodies of the old documents in the result.
:type return_old: bool
:param check_rev: If set to True, revisions of documents (if given)
are compared against the revisions of target documents.
:type check_rev: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: List of document metadata (e.g. document keys, revisions) and
any exceptions, or True if parameter silent was set to True.
:rtype: [dict | C8Error] | bool
:raise c8.exceptions.DocumentDeleteError: If delete fails.

Method delete_match {#c8.collection.StandardCollection.delete_match}

def delete_match(self, filters, limit=None, sync=None)

Delete matching documents.

:param filters: Document filters.
:type filters: dict
:param limit: Max number of documents to delete. If the limit is lower
than the number of matched documents, random documents are chosen.
:type limit: int
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: Number of documents deleted.
:rtype: dict
:raise c8.exceptions.DocumentDeleteError: If delete fails.

Method get {#c8.collection.StandardCollection.get}

def get(self, document, rev=None, check_rev=True)

Return a document.

:param document: Document ID, key or body. Document body must contain
the "_id" or "_key" field.
:type document: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in document if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of document (if given)
is compared against the revision of target document.
:type check_rev: bool
:return: Document, or None if not found.
:rtype: dict | None
:raise c8.exceptions.DocumentGetError: If retrieval fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method get_documents_from_file {#c8.collection.StandardCollection.get_documents_from_file}

def get_documents_from_file(self, data, index)

Method import_bulk {#c8.collection.StandardCollection.import_bulk}

def import_bulk(self, documents, halt_on_error=True, details=True, from_prefix=None, to_prefix=None, overwrite=None, on_duplicate=None, sync=None)

Insert multiple documents into the collection.

This is faster than :func:c8.collection.Collection.insert_many
but does not return as much information.

:param documents: List of new documents to insert. If they contain the
"_key" or "_id" fields, the values are used as the keys of the new
documents (auto-generated otherwise). Any "_rev" field is ignored.
:type documents: [dict]
:param halt_on_error: Halt the entire import on an error.
:type halt_on_error: bool
:param details: If set to True, the returned result will include an
additional list of detailed error messages.
:type details: bool
:param from_prefix: String prefix prepended to the value of "_from"
field in each edge document inserted. For example, prefix "foo"
prepended to "_from": "bar" will result in "_from": "foo/bar".
Applies only to edge collections.
:type from_prefix: str | unicode
:param to_prefix: String prefix prepended to the value of "_to" field
in edge document inserted. For example, prefix "foo" prepended to
"_to": "bar" will result in "_to": "foo/bar". Applies only to edge
collections.
:type to_prefix: str | unicode
:param overwrite: If set to True, all existing documents are removed
prior to the import. Indexes are still preserved.
:type overwrite: bool
:param on_duplicate: Action to take on unique key constraint violations
(for documents with "_key" fields). Allowed values are "error" (do
not import the new documents and count them as errors), "update"
(update the existing documents while preserving any fields missing
in the new ones), "replace" (replace the existing documents with
new ones), and "ignore" (do not import the new documents and count
them as ignored, as opposed to counting them as errors). Options
"update" and "replace" may fail on secondary unique key constraint
violations.
:type on_duplicate: str | unicode
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: Result of the bulk import.
:rtype: dict
:raise c8.exceptions.DocumentInsertError: If import fails.

Method insert {#c8.collection.StandardCollection.insert}

def insert(self, document, return_new=False, sync=None, silent=False)

Insert a new document.

:param document: Document to insert. If it contains the "_key" or "_id"
field, the value is used as the key of the new document (otherwise
it is auto-generated). Any "_rev" field is ignored.
:type document: dict
:param return_new: Include body of the new document in the returned
metadata. Ignored if parameter silent is set to True.
:type return_new: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method insert_from_file {#c8.collection.StandardCollection.insert_from_file}

def insert_from_file(self, csv_filepath, return_new=False, sync=None, silent=False)

Insert a documents from csv file.

:param csv_filepath: CSV file path which contains documents
:type csv_filepath: str
:param return_new: Include body of the new document in the returned
metadata. Ignored if parameter silent is set to True.
:type return_new: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method insert_many {#c8.collection.StandardCollection.insert_many}

def insert_many(self, documents, return_new=False, sync=None, silent=False)

Insert multiple documents.

If inserting a document fails, the exception object is placed in the
result list instead of document metadata.

:param documents: List of new documents to insert. If they contain the
"_key" or "_id" fields, the values are used as the keys of the new
documents (auto-generated otherwise). Any "_rev" field is ignored.
:type documents: [dict]
:param return_new: Include bodies of the new documents in the returned
metadata. Ignored if parameter silent is set to True
:type return_new: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: List of document metadata (e.g. document keys, revisions) and
any exception, or True if parameter silent was set to True.
:rtype: [dict | C8Error] | bool
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method replace {#c8.collection.StandardCollection.replace}

def replace(self, document, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

Replace a document.

:param document: New document to replace the old one with. It must
contain the "_id" or "_key" field. Edge document must also have
"_from" and "_to" fields.
:type document: dict
:param check_rev: If set to True, revision of document (if given)
is compared against the revision of target document.
:type check_rev: bool
:param return_new: Include body of the new document in the result.
:type return_new: bool
:param return_old: Include body of the old document in the result.
:type return_old: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentReplaceError: If replace fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method replace_many {#c8.collection.StandardCollection.replace_many}

def replace_many(self, documents, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

Replace multiple documents.

If replacing a document fails, the exception object is placed in the
result list instead of document metadata.

:param documents: New documents to replace the old ones with. They must
contain the "_id" or "_key" fields. Edge documents must also have
"_from" and "_to" fields.
:type documents: [dict]
:param check_rev: If set to True, revisions of documents (if given)
are compared against the revisions of target documents.
:type check_rev: bool
:param return_new: Include bodies of the new documents in the result.
:type return_new: bool
:param return_old: Include bodies of the old documents in the result.
:type return_old: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: List of document metadata (e.g. document keys, revisions) and
any exceptions, or True if parameter silent was set to True.
:rtype: [dict | C8Error] | bool
:raise c8.exceptions.DocumentReplaceError: If replace fails.

Method replace_match {#c8.collection.StandardCollection.replace_match}

def replace_match(self, filters, body, limit=None, sync=None)

Replace matching documents.

:param filters: Document filters.
:type filters: dict
:param body: New document body.
:type body: dict
:param limit: Max number of documents to replace. If the limit is lower
than the number of matched documents, random documents are chosen.
:type limit: int
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: Number of documents replaced.
:rtype: int
:raise c8.exceptions.DocumentReplaceError: If replace fails.

Method update {#c8.collection.StandardCollection.update}

def update(self, document, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

Update a document.

:param document: Partial or full document with the updated values. It
must contain the "_id" or "_key" field.
:type document: dict
:param check_rev: If set to True, revision of document (if given)
is compared against the revision of target document.
:type check_rev: bool
:param merge: If set to True, sub-dictionaries are merged instead of
the new one overwriting the old one.
:type merge: bool
:param keep_none: If set to True, fields with value None are retained
in the document. Otherwise, they are removed completely.
:type keep_none: bool
:param return_new: Include body of the new document in the result.
:type return_new: bool
:param return_old: Include body of the old document in the result.
:type return_old: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentUpdateError: If update fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method update_many {#c8.collection.StandardCollection.update_many}

def update_many(self, documents, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

Update multiple documents.

If updating a document fails, the exception object is placed in the
result list instead of document metadata.

:param documents: Partial or full documents with the updated values.
They must contain the "_id" or "_key" fields.
:type documents: [dict]
:param check_rev: If set to True, revisions of documents (if given)
are compared against the revisions of target documents.
:type check_rev: bool
:param merge: If set to True, sub-dictionaries are merged instead of
the new ones overwriting the old ones.
:type merge: bool
:param keep_none: If set to True, fields with value None are retained
in the document. Otherwise, they are removed completely.
:type keep_none: bool
:param return_new: Include bodies of the new documents in the result.
:type return_new: bool
:param return_old: Include bodies of the old documents in the result.
:type return_old: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: List of document metadata (e.g. document keys, revisions) and
any exceptions, or True if parameter silent was set to True.
:rtype: [dict | C8Error] | bool
:raise c8.exceptions.DocumentUpdateError: If update fails.

Method update_match {#c8.collection.StandardCollection.update_match}

def update_match(self, filters, body, limit=None, keep_none=True, sync=None, merge=True)

Update matching documents.

:param filters: Document filters.
:type filters: dict
:param body: Full or partial document body with the updates.
:type body: dict
:param limit: Max number of documents to update. If the limit is lower
than the number of matched documents, random documents are
chosen. This parameter is not supported on sharded collections.
:type limit: int
:param keep_none: If set to True, fields with value None are retained
in the document. Otherwise, they are removed completely.
:type keep_none: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param merge: If set to True, sub-dictionaries are merged instead of
the new ones overwriting the old ones.
:type merge: bool
:return: Number of documents updated.
:rtype: int
:raise c8.exceptions.DocumentUpdateError: If update fails.

Class VertexCollection {#c8.collection.VertexCollection}

class VertexCollection(connection, executor, graph, name)

Vertex collection API wrapper.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor
:param graph: Graph name.
:type graph: str | unicode
:param name: Vertex collection name.
:type name: str | unicode

Ancestors (in MRO)

Instance variables

Variable graph {#c8.collection.VertexCollection.graph}

Return the graph name.

:return: Graph name.
:rtype: str | unicode

Methods

Method delete {#c8.collection.VertexCollection.delete}

def delete(self, vertex, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete a vertex document.

:param vertex: Vertex document ID, key or body. Document body must
contain the "_id" or "_key" field.
:type vertex: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in vertex if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:param ignore_missing: Do not raise an exception on missing document.
This parameter has no effect in transactions where an exception is
always raised on failures.
:type ignore_missing: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: True if vertex was deleted successfully, False if vertex was
not found and ignore_missing was set to True (does not apply in
transactions).
:rtype: bool
:raise c8.exceptions.DocumentDeleteError: If delete fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method get {#c8.collection.VertexCollection.get}

def get(self, vertex, rev=None, check_rev=True)

Return a vertex document.

:param vertex: Vertex document ID, key or body. Document body must
contain the "_id" or "_key" field.
:type vertex: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in vertex if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:return: Vertex document or None if not found.
:rtype: dict | None
:raise c8.exceptions.DocumentGetError: If retrieval fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method insert {#c8.collection.VertexCollection.insert}

def insert(self, vertex, sync=None, silent=False)

Insert a new vertex document.

:param vertex: New vertex document to insert. If it has "_key" or "_id"
field, its value is used as key of the new vertex (otherwise it is
auto-generated). Any "_rev" field is ignored.
:type vertex: dict
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method replace {#c8.collection.VertexCollection.replace}

def replace(self, vertex, check_rev=True, sync=None, silent=False)

Replace a vertex document.

:param vertex: New vertex document to replace the old one with. It must
contain the "_key" or "_id" field.
:type vertex: dict
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentReplaceError: If replace fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method update {#c8.collection.VertexCollection.update}

def update(self, vertex, check_rev=True, keep_none=True, sync=None, silent=False)

Update a vertex document.

:param vertex: Partial or full vertex document with updated values. It
must contain the "_key" or "_id" field.
:type vertex: dict
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:param keep_none: If set to True, fields with value None are retained
in the document. If set to False, they are removed completely.
:type keep_none: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentUpdateError: If update fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Module c8.connection {#c8.connection}

Classes

Class Connection {#c8.connection.Connection}

class Connection(url, tenantname, fabric_or_stream_name, username, password, http_client, is_fabric=True)

HTTP connection to specific C8 tenant.

:param url: C8Db base URL.
:type url: str | unicode
:param fabric: Fabric name.
:type fabric: str | unicode
:param username: Username.
:type username: str | unicode
:param password: Password.
:type password: str | unicode
:param http_client: User-defined HTTP client.
:type http_client: c8.http.HTTPClient
:param is_fabric: Whether this a DB or streams call.
Anything other than streams is a DB call.
:type is_fabric: bool

Descendants

  • c8.connection.TenantConnection
  • c8.connection.FabricConnection
  • c8.connection.StreamConnection
  • c8.connection.RealtimeConnection

Instance variables

Variable fabric_name {#c8.connection.Connection.fabric_name}

Return the DB name if it was called from the DB class

:returns: DB name.
:rtype: str | unicode

Variable stream_name {#c8.connection.Connection.stream_name}

Return the Stream name if it was called from the Stream class

:returns: Stream name.
:rtype: str | unicode

Variable tenant_name {#c8.connection.Connection.tenant_name}

Return the tenant name.

:returns: tenant name.
:rtype: str | unicode

Variable url_prefix {#c8.connection.Connection.url_prefix}

Return the C8 URL prefix (base URL + tenant name).

:returns: C8 URL prefix.
:rtype: str | unicode

Variable username {#c8.connection.Connection.username}

Return the username.

:returns: Username.
:rtype: str | unicode

Methods

Method send_request {#c8.connection.Connection.send_request}

def send_request(self, request)

Send an HTTP request to C8 server.

:param request: HTTP request.
:type request: c8.request.Request
:return: HTTP response.
:rtype: c8.response.Response

Method set_url_prefix {#c8.connection.Connection.set_url_prefix}

def set_url_prefix(self, new_prefix)

Set the URL prefix to the new prefix,
returns (old_prefix,new_prefix) so it can be tracked.

Module c8.constants {#c8.constants}

Module c8.cursor {#c8.cursor}

Classes

Class Cursor {#c8.cursor.Cursor}

class Cursor(connection, init_data, cursor_type='cursor')

Cursor API wrapper.

Cursors fetch query results from C8Db server in batches. Cursor objects
are stateful as they store the fetched items in-memory. They must not be
shared across threads without proper locking mechanism.

In transactions, the entire result set is loaded into the cursor. Therefore
you must be mindful of client-side memory capacity when running queries
that can potentially return a large result set.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param init_data: Cursor initialization data.
:type init_data: dict | list
:param cursor_type: Cursor type ("cursor" or "export").
:type cursor_type: str | unicode

Instance variables

Variable id {#c8.cursor.Cursor.id}

Return the cursor ID.

:return: Cursor ID.
:rtype: str | unicode

Variable type {#c8.cursor.Cursor.type}

Return the cursor type.

:return: Cursor type ("cursor" or "export").
:rtype: str | unicode

Methods

Method batch {#c8.cursor.Cursor.batch}

def batch(self)

Return the current batch of results.

:return: Current batch.
:rtype: collections.deque

Method cached {#c8.cursor.Cursor.cached}

def cached(self)

Return True if results are cached.

:return: True if results are cached.
:rtype: bool

Method close {#c8.cursor.Cursor.close}

def close(self, ignore_missing=False)

Close the cursor and free any server resources tied to it.

:param ignore_missing: Do not raise exception on missing cursors.
:type ignore_missing: bool
:return: True if cursor was closed successfully, False if cursor was
missing on the server and ignore_missing was set to True, None
if there are no cursors to close server-side (e.g. result set is
smaller than the batch size, or in transactions).
:rtype: bool | None
:raise c8.exceptions.CursorCloseError: If operation fails.
:raise c8.exceptions.CursorStateError: If cursor ID is not set.

Method count {#c8.cursor.Cursor.count}

def count(self)

Return the total number of documents in the entire result set.

:return: Total number of documents, or None if the count option
was not enabled during cursor initialization.
:rtype: int | None

Method empty {#c8.cursor.Cursor.empty}

def empty(self)

Check if the current batch is empty.

:return: True if current batch is empty, False otherwise.
:rtype: bool

Method fetch {#c8.cursor.Cursor.fetch}

def fetch(self)

Fetch the next batch from server and update the cursor.

:return: New batch details.
:rtype: dict
:raise c8.exceptions.CursorNextError: If batch retrieval fails.
:raise c8.exceptions.CursorStateError: If cursor ID is not set.

Method has_more {#c8.cursor.Cursor.has_more}

def has_more(self)

Return True if more results are available on the server.

:return: True if more results are available on the server.
:rtype: bool

Method next {#c8.cursor.Cursor.next}

def next(self)

Pop the next item from the current batch.

If current batch is empty/depleted, an API request is automatically
sent to C8Db server to fetch the next batch and update the cursor.

:return: Next item in current batch.
:rtype: str | unicode | bool | int | list | dict
:raise StopIteration: If the result set is depleted.
:raise c8.exceptions.CursorNextError: If batch retrieval fails.
:raise c8.exceptions.CursorStateError: If cursor ID is not set.

Method pop {#c8.cursor.Cursor.pop}

def pop(self)

Pop the next item from current batch.

If current batch is empty/depleted, an exception is raised. You must
call :func:Cursor.fetch() to manually fetch the next
batch from server.

:return: Next item in current batch.
:rtype: str | unicode | bool | int | list | dict
:raise c8.exceptions.CursorEmptyError: If current batch is empty.

Method profile {#c8.cursor.Cursor.profile}

def profile(self)

Return cursor performance profile.

:return: Cursor performance profile.
:rtype: dict

Method warnings {#c8.cursor.Cursor.warnings}

def warnings(self)

Return any warnings from the query execution.

:return: Warnings, or None if there are none.
:rtype: list

Module c8.exceptions {#c8.exceptions}

Classes

Class AsyncExecuteError {#c8.exceptions.AsyncExecuteError}

class AsyncExecuteError(resp, request, msg=None)

Failed to execute async API request.

Ancestors (in MRO)

Class AsyncJobCancelError {#c8.exceptions.AsyncJobCancelError}

class AsyncJobCancelError(resp, request, msg=None)

Failed to cancel async job.

Ancestors (in MRO)

Class AsyncJobClearError {#c8.exceptions.AsyncJobClearError}

class AsyncJobClearError(resp, request, msg=None)

Failed to clear async job results.

Ancestors (in MRO)

Class AsyncJobListError {#c8.exceptions.AsyncJobListError}

class AsyncJobListError(resp, request, msg=None)

Failed to retrieve async jobs.

Ancestors (in MRO)

Class AsyncJobResultError {#c8.exceptions.AsyncJobResultError}

class AsyncJobResultError(resp, request, msg=None)

Failed to retrieve async job result.

Ancestors (in MRO)

Class AsyncJobStatusError {#c8.exceptions.AsyncJobStatusError}

class AsyncJobStatusError(resp, request, msg=None)

Failed to retrieve async job status.

Ancestors (in MRO)

Class BatchExecuteError {#c8.exceptions.BatchExecuteError}

class BatchExecuteError(resp, request, msg=None)

Failed to execute batch API request.

Ancestors (in MRO)

Class BatchJobResultError {#c8.exceptions.BatchJobResultError}

class BatchJobResultError(msg)

Failed to retrieve batch job result.

Ancestors (in MRO)

Class BatchStateError {#c8.exceptions.BatchStateError}

class BatchStateError(msg)

The batch object was in a bad state.

Ancestors (in MRO)

Class C8ClientError {#c8.exceptions.C8ClientError}

class C8ClientError(msg)

Base class for errors originating from pyC8 client.

:param msg: Error message.
:type msg: str | unicode

:cvar source: Source of the error (always set to "client").
:vartype source: str | unicode
:ivar message: Error message.
:vartype message: str | unicode

Ancestors (in MRO)

Descendants

Class variables

Variable source {#c8.exceptions.C8ClientError.source}

Class C8Error {#c8.exceptions.C8Error}

class C8Error(*args, **kwargs)

Base class for all exceptions in pyC8.

Ancestors (in MRO)

  • builtins.Exception
  • builtins.BaseException

Descendants

Class C8QLFunctionCreateError {#c8.exceptions.C8QLFunctionCreateError}

class C8QLFunctionCreateError(resp, request, msg=None)

Failed to create C8QL user function.

Ancestors (in MRO)

Class C8QLFunctionDeleteError {#c8.exceptions.C8QLFunctionDeleteError}

class C8QLFunctionDeleteError(resp, request, msg=None)

Failed to delete C8QL user function.

Ancestors (in MRO)

Class C8QLFunctionListError {#c8.exceptions.C8QLFunctionListError}

class C8QLFunctionListError(resp, request, msg=None)

Failed to retrieve C8QL user functions.

Ancestors (in MRO)

Class C8QLQueryClearError {#c8.exceptions.C8QLQueryClearError}

class C8QLQueryClearError(resp, request, msg=None)

Failed to clear slow C8QL queries.

Ancestors (in MRO)

Class C8QLQueryExecuteError {#c8.exceptions.C8QLQueryExecuteError}

class C8QLQueryExecuteError(resp, request, msg=None)

Failed to execute query.

Ancestors (in MRO)

Class C8QLQueryExplainError {#c8.exceptions.C8QLQueryExplainError}

class C8QLQueryExplainError(resp, request, msg=None)

Failed to parse and explain query.

Ancestors (in MRO)

Class C8QLQueryKillError {#c8.exceptions.C8QLQueryKillError}

class C8QLQueryKillError(resp, request, msg=None)

Failed to kill the query.

Ancestors (in MRO)

Class C8QLQueryListError {#c8.exceptions.C8QLQueryListError}

class C8QLQueryListError(resp, request, msg=None)

Failed to retrieve running C8QL queries.

Ancestors (in MRO)

Class C8QLQueryValidateError {#c8.exceptions.C8QLQueryValidateError}

class C8QLQueryValidateError(resp, request, msg=None)

Failed to parse and validate query.

Ancestors (in MRO)

Class C8ServerError {#c8.exceptions.C8ServerError}

class C8ServerError(resp, request, msg=None)

Base class for errors originating from C8Db server.

:param resp: HTTP response.
:type resp: c8.response.Response
:param msg: Error message override.
:type msg: str | unicode

:cvar source: Source of the error (always set to "server").
:vartype source: str | unicode
:ivar message: Exception message.
:vartype message: str | unicode
:ivar url: API URL.
:vartype url: str | unicode
:ivar response: HTTP response object.
:vartype response: c8.response.Response
:ivar request: HTTP request object.
:vartype request: c8.request.Request
:ivar http_method: HTTP method in lowercase (e.g. "post").
:vartype http_method: str | unicode
:ivar http_code: HTTP status code.
:vartype http_code: int
:ivar http_headers: Response headers.
:vartype http_headers: requests.structures.CaseInsensitiveDict | dict
:ivar error_code: Error code from C8Db server.
:vartype error_code: int
:ivar error_message: Raw error message from C8Db server.
:vartype error_message: str | unicode

Ancestors (in MRO)

Descendants

Class variables

Variable source {#c8.exceptions.C8ServerError.source}

Class CollectionCreateError {#c8.exceptions.CollectionCreateError}

class CollectionCreateError(resp, request, msg=None)

Failed to create collection.

Ancestors (in MRO)

Class CollectionDeleteError {#c8.exceptions.CollectionDeleteError}

class CollectionDeleteError(resp, request, msg=None)

Failed to delete collection.

Ancestors (in MRO)

Class CollectionListError {#c8.exceptions.CollectionListError}

class CollectionListError(resp, request, msg=None)

Failed to retrieve collections.

Ancestors (in MRO)

Class CollectionRenameError {#c8.exceptions.CollectionRenameError}

class CollectionRenameError(resp, request, msg=None)

Failed to rename collection.

Ancestors (in MRO)

Class CollectionTruncateError {#c8.exceptions.CollectionTruncateError}

class CollectionTruncateError(resp, request, msg=None)

Failed to truncate collection.

Ancestors (in MRO)

Class CompactionCreateError {#c8.exceptions.CompactionCreateError}

class CompactionCreateError(resp, request, msg=None)

Compaction already exists

Ancestors (in MRO)

Class CursorCloseError {#c8.exceptions.CursorCloseError}

class CursorCloseError(resp, request, msg=None)

Failed to delete the cursor result from server.

Ancestors (in MRO)

Class CursorEmptyError {#c8.exceptions.CursorEmptyError}

class CursorEmptyError(msg)

The current batch in cursor was empty.

Ancestors (in MRO)

Class CursorNextError {#c8.exceptions.CursorNextError}

class CursorNextError(resp, request, msg=None)

Failed to retrieve the next result batch from server.

Ancestors (in MRO)

Class CursorStateError {#c8.exceptions.CursorStateError}

class CursorStateError(msg)

The cursor object was in a bad state.

Ancestors (in MRO)

Class DocumentCountError {#c8.exceptions.DocumentCountError}

class DocumentCountError(resp, request, msg=None)

Failed to retrieve document count.

Ancestors (in MRO)

Class DocumentDeleteError {#c8.exceptions.DocumentDeleteError}

class DocumentDeleteError(resp, request, msg=None)

Failed to delete document.

Ancestors (in MRO)

Class DocumentGetError {#c8.exceptions.DocumentGetError}

class DocumentGetError(resp, request, msg=None)

Failed to retrieve document.

Ancestors (in MRO)

Class DocumentIDsError {#c8.exceptions.DocumentIDsError}

class DocumentIDsError(resp, request, msg=None)

Failed to retrieve document IDs.

Ancestors (in MRO)

Class DocumentInError {#c8.exceptions.DocumentInError}

class DocumentInError(resp, request, msg=None)

Failed to check whether document exists.

Ancestors (in MRO)

Class DocumentInsertError {#c8.exceptions.DocumentInsertError}

class DocumentInsertError(resp, request, msg=None)

Failed to insert document.

Ancestors (in MRO)

Class DocumentKeysError {#c8.exceptions.DocumentKeysError}

class DocumentKeysError(resp, request, msg=None)

Failed to retrieve document keys.

Ancestors (in MRO)

Class DocumentParseError {#c8.exceptions.DocumentParseError}

class DocumentParseError(msg)

Failed to parse document input.

Ancestors (in MRO)

Class DocumentReplaceError {#c8.exceptions.DocumentReplaceError}

class DocumentReplaceError(resp, request, msg=None)

Failed to replace document.

Ancestors (in MRO)

Class DocumentRevisionError {#c8.exceptions.DocumentRevisionError}

class DocumentRevisionError(resp, request, msg=None)

The expected and actual document revisions mismatched.

Ancestors (in MRO)

Class DocumentUpdateError {#c8.exceptions.DocumentUpdateError}

class DocumentUpdateError(resp, request, msg=None)

Failed to update document.

Ancestors (in MRO)

Class EdgeDefinitionCreateError {#c8.exceptions.EdgeDefinitionCreateError}

class EdgeDefinitionCreateError(resp, request, msg=None)

Failed to create edge definition.

Ancestors (in MRO)

Class EdgeDefinitionDeleteError {#c8.exceptions.EdgeDefinitionDeleteError}

class EdgeDefinitionDeleteError(resp, request, msg=None)

Failed to delete edge definition.

Ancestors (in MRO)

Class EdgeDefinitionListError {#c8.exceptions.EdgeDefinitionListError}

class EdgeDefinitionListError(resp, request, msg=None)

Failed to retrieve edge definitions.

Ancestors (in MRO)

Class EdgeDefinitionReplaceError {#c8.exceptions.EdgeDefinitionReplaceError}

class EdgeDefinitionReplaceError(resp, request, msg=None)

Failed to replace edge definition.

Ancestors (in MRO)

Class EdgeListError {#c8.exceptions.EdgeListError}

class EdgeListError(resp, request, msg=None)

Failed to retrieve edges coming in and out of a vertex.

Ancestors (in MRO)

Class FabricCreateError {#c8.exceptions.FabricCreateError}

class FabricCreateError(resp, request, msg=None)

Failed to create fabric.

Ancestors (in MRO)

Class FabricDeleteError {#c8.exceptions.FabricDeleteError}

class FabricDeleteError(resp, request, msg=None)

Failed to delete fabric.

Ancestors (in MRO)

Class FabricListError {#c8.exceptions.FabricListError}

class FabricListError(resp, request, msg=None)

Failed to retrieve fabrics.

Ancestors (in MRO)

Class FabricPropertiesError {#c8.exceptions.FabricPropertiesError}

class FabricPropertiesError(resp, request, msg=None)

Failed to retrieve fabric properties.

Ancestors (in MRO)

Class GraphCreateError {#c8.exceptions.GraphCreateError}

class GraphCreateError(resp, request, msg=None)

Failed to create the graph.

Ancestors (in MRO)

Class GraphDeleteError {#c8.exceptions.GraphDeleteError}

class GraphDeleteError(resp, request, msg=None)

Failed to delete the graph.

Ancestors (in MRO)

Class GraphListError {#c8.exceptions.GraphListError}

class GraphListError(resp, request, msg=None)

Failed to retrieve graphs.

Ancestors (in MRO)

Class GraphPropertiesError {#c8.exceptions.GraphPropertiesError}

class GraphPropertiesError(resp, request, msg=None)

Failed to retrieve graph properties.

Ancestors (in MRO)

Class IndexCreateError {#c8.exceptions.IndexCreateError}

class IndexCreateError(resp, request, msg=None)

Failed to create collection index.

Ancestors (in MRO)

Class IndexDeleteError {#c8.exceptions.IndexDeleteError}

class IndexDeleteError(resp, request, msg=None)

Failed to delete collection index.

Ancestors (in MRO)

Class IndexListError {#c8.exceptions.IndexListError}

class IndexListError(resp, request, msg=None)

Failed to retrieve collection indexes.

Ancestors (in MRO)

Class PermissionGetError {#c8.exceptions.PermissionGetError}

class PermissionGetError(resp, request, msg=None)

Failed to retrieve user permission.

Ancestors (in MRO)

Class PermissionListError {#c8.exceptions.PermissionListError}

class PermissionListError(resp, request, msg=None)

Failed to list user permissions.

Ancestors (in MRO)

Class PermissionResetError {#c8.exceptions.PermissionResetError}

class PermissionResetError(resp, request, msg=None)

Failed to reset user permission.

Ancestors (in MRO)

Class PermissionUpdateError {#c8.exceptions.PermissionUpdateError}

class PermissionUpdateError(resp, request, msg=None)

Failed to update user permission.

Ancestors (in MRO)

Class RestqlCreateError {#c8.exceptions.RestqlCreateError}

class RestqlCreateError(resp, request, msg=None)

Failed to create restql.

Ancestors (in MRO)

Class RestqlDeleteError {#c8.exceptions.RestqlDeleteError}

class RestqlDeleteError(resp, request, msg=None)

Failed to delete restql.

Ancestors (in MRO)

Class RestqlExecuteError {#c8.exceptions.RestqlExecuteError}

class RestqlExecuteError(resp, request, msg=None)

Failed to execute restql.

Ancestors (in MRO)

Class RestqlListError {#c8.exceptions.RestqlListError}

class RestqlListError(resp, request, msg=None)

Failed to get restql details.

Ancestors (in MRO)

Class RestqlUpdateError {#c8.exceptions.RestqlUpdateError}

class RestqlUpdateError(resp, request, msg=None)

Failed to update restql.

Ancestors (in MRO)

Class RestqlValidationError {#c8.exceptions.RestqlValidationError}

class RestqlValidationError(msg)

Failed to validate restql data.

Ancestors (in MRO)

Class ServerConnectionError {#c8.exceptions.ServerConnectionError}

class ServerConnectionError(msg)

Failed to connect to C8Db server.

Ancestors (in MRO)

Class ServerDetailsError {#c8.exceptions.ServerDetailsError}

class ServerDetailsError(resp, request, msg=None)

Failed to retrieve server details.

Ancestors (in MRO)

Class ServerTimeError {#c8.exceptions.ServerTimeError}

class ServerTimeError(resp, request, msg=None)

Failed to retrieve server system time.

Ancestors (in MRO)

Class ServerVersionError {#c8.exceptions.ServerVersionError}

class ServerVersionError(resp, request, msg=None)

Failed to retrieve server version.

Ancestors (in MRO)

Class SpotRegionAssignError {#c8.exceptions.SpotRegionAssignError}

class SpotRegionAssignError(resp, request, msg=None)

Fails to assign region as Spot Region

Ancestors (in MRO)

Class SpotRegionUpdateError {#c8.exceptions.SpotRegionUpdateError}

class SpotRegionUpdateError(resp, request, msg=None)

Failed to update Spot Region

Ancestors (in MRO)

Class StreamBadInputError {#c8.exceptions.StreamBadInputError}

class StreamBadInputError(msg)

If the request doesn’t have the expected format.

Ancestors (in MRO)

Class StreamCommunicationError {#c8.exceptions.StreamCommunicationError}

class StreamCommunicationError(resp, request, msg=None)

If an error related to C8Streams communication was encountered.

Ancestors (in MRO)

Class StreamConnectionError {#c8.exceptions.StreamConnectionError}

class StreamConnectionError(resp, request, msg=None)

Failed to connect to C8 stream.

Ancestors (in MRO)

Class StreamCreateError {#c8.exceptions.StreamCreateError}

class StreamCreateError(resp, request, msg=None)

Failed to create stream.

Ancestors (in MRO)

Class StreamDeleteError {#c8.exceptions.StreamDeleteError}

class StreamDeleteError(resp, request, msg=None)

Failed to delete stream.

Ancestors (in MRO)

Class StreamEventError {#c8.exceptions.StreamEventError}

class StreamEventError(msg)

Failed to process the event from C8 stream.

Ancestors (in MRO)

Class StreamListError {#c8.exceptions.StreamListError}

class StreamListError(resp, request, msg=None)

Failed to retrieve streams.

Ancestors (in MRO)

Class StreamPermissionError {#c8.exceptions.StreamPermissionError}

class StreamPermissionError(resp, request, msg=None)

Don't have permission

Ancestors (in MRO)

Class StreamProducerError {#c8.exceptions.StreamProducerError}

class StreamProducerError(msg)

Failed to create Stream Producer

Ancestors (in MRO)

Class StreamPropertiesError {#c8.exceptions.StreamPropertiesError}

class StreamPropertiesError(resp, request, msg=None)

Failed to retrieve stream properties.

Ancestors (in MRO)

Class StreamStatisticsError {#c8.exceptions.StreamStatisticsError}

class StreamStatisticsError(resp, request, msg=None)

Failed to get stream stats.

Ancestors (in MRO)

Class StreamSubscriberError {#c8.exceptions.StreamSubscriberError}

class StreamSubscriberError(msg)

Failed to create Stream Subscriber

Ancestors (in MRO)

Class StreamUpdateError {#c8.exceptions.StreamUpdateError}

class StreamUpdateError(resp, request, msg=None)

Failed to update stream content.

Ancestors (in MRO)

Class SubscriptionDeleteError {#c8.exceptions.SubscriptionDeleteError}

class SubscriptionDeleteError(resp, request, msg=None)

Failed to delete subscription.

Ancestors (in MRO)

Class SubscriptionUpdateError {#c8.exceptions.SubscriptionUpdateError}

class SubscriptionUpdateError(resp, request, msg=None)

Failed to update subscription.

Ancestors (in MRO)

Class TenantCreateError {#c8.exceptions.TenantCreateError}

class TenantCreateError(resp, request, msg=None)

Failed to create tenant.

Ancestors (in MRO)

Class TenantDcListError {#c8.exceptions.TenantDcListError}

class TenantDcListError(resp, request, msg=None)

Failed to retrieve list of C8 Data Centers.

Ancestors (in MRO)

Class TenantDeleteError {#c8.exceptions.TenantDeleteError}

class TenantDeleteError(resp, request, msg=None)

Failed to delete tenant.

Ancestors (in MRO)

Class TenantListError {#c8.exceptions.TenantListError}

class TenantListError(resp, request, msg=None)

Failed to retrieve tenants.

Ancestors (in MRO)

Class TenantPropertiesError {#c8.exceptions.TenantPropertiesError}

class TenantPropertiesError(resp, request, msg=None)

Failed to retrieve tenant properties.

Ancestors (in MRO)

Class TenantUpdateError {#c8.exceptions.TenantUpdateError}

class TenantUpdateError(msg)

Failed to update tenant.

Ancestors (in MRO)

Class TopicCreateError {#c8.exceptions.TopicCreateError}

class TopicCreateError(resp, request, msg=None)

Failed to create topic.

Ancestors (in MRO)

Class TopicDeleteError {#c8.exceptions.TopicDeleteError}

class TopicDeleteError(resp, request, msg=None)

Failed to delete topic.

Ancestors (in MRO)

Class TopicListError {#c8.exceptions.TopicListError}

class TopicListError(resp, request, msg=None)

Failed to retrieve topic.

Ancestors (in MRO)

Class TopicPropertiesError {#c8.exceptions.TopicPropertiesError}

class TopicPropertiesError(resp, request, msg=None)

Failed to retrieve topic properties.

Ancestors (in MRO)

Class TopicStatisticsError {#c8.exceptions.TopicStatisticsError}

class TopicStatisticsError(resp, request, msg=None)

Failed to get topic stats.

Ancestors (in MRO)

Class TransactionExecuteError {#c8.exceptions.TransactionExecuteError}

class TransactionExecuteError(resp, request, msg=None)

Failed to execute transaction API request

Ancestors (in MRO)

Class TransactionJobResultError {#c8.exceptions.TransactionJobResultError}

class TransactionJobResultError(msg)

Failed to retrieve transaction job result.

Ancestors (in MRO)

Class TransactionStateError {#c8.exceptions.TransactionStateError}

class TransactionStateError(msg)

The transaction object was in bad state.

Ancestors (in MRO)

Class UserCreateError {#c8.exceptions.UserCreateError}

class UserCreateError(resp, request, msg=None)

Failed to create user.

Ancestors (in MRO)

Class UserDeleteError {#c8.exceptions.UserDeleteError}

class UserDeleteError(resp, request, msg=None)

Failed to delete user.

Ancestors (in MRO)

Class UserGetError {#c8.exceptions.UserGetError}

class UserGetError(resp, request, msg=None)

Failed to retrieve user details.

Ancestors (in MRO)

Class UserListError {#c8.exceptions.UserListError}

class UserListError(resp, request, msg=None)

Failed to retrieve users.

Ancestors (in MRO)

Class UserReplaceError {#c8.exceptions.UserReplaceError}

class UserReplaceError(resp, request, msg=None)

Failed to replace user.

Ancestors (in MRO)

Class UserUpdateError {#c8.exceptions.UserUpdateError}

class UserUpdateError(resp, request, msg=None)

Failed to update user.

Ancestors (in MRO)

Class VertexCollectionCreateError {#c8.exceptions.VertexCollectionCreateError}

class VertexCollectionCreateError(resp, request, msg=None)

Failed to create vertex collection.

Ancestors (in MRO)

Class VertexCollectionDeleteError {#c8.exceptions.VertexCollectionDeleteError}

class VertexCollectionDeleteError(resp, request, msg=None)

Failed to delete vertex collection.

Ancestors (in MRO)

Class VertexCollectionListError {#c8.exceptions.VertexCollectionListError}

class VertexCollectionListError(resp, request, msg=None)

Failed to retrieve vertex collections.

Ancestors (in MRO)

Module c8.executor {#c8.executor}

Classes

Class AsyncExecutor {#c8.executor.AsyncExecutor}

class AsyncExecutor(connection, return_result)

Async API Executor.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param return_result: If set to True, API executions return instances of
:class:AsyncJob and results can be retrieved from server
once available. If set to False, API executions return None and no
results are stored on server.
:type return_result: bool

Ancestors (in MRO)

  • c8.executor.Executor

Class variables

Variable context {#c8.executor.AsyncExecutor.context}

Methods

Method execute {#c8.executor.AsyncExecutor.execute}

def execute(self, request, response_handler)

Execute an API request asynchronously.

:param request: HTTP request.
:type request: c8.request.Request
:param response_handler: HTTP response handler.
:type response_handler: callable
:return: Async job or None if return_result parameter was set to
False during initialization.
:rtype: c8.job.AsyncJob | None

Class BatchExecutor {#c8.executor.BatchExecutor}

class BatchExecutor(connection, return_result)

Batch API executor.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param return_result: If set to True, API executions return instances of
:class:BatchJob that are populated with results on commit.
If set to False, API executions return None and no results are tracked
client-side.
:type return_result: bool

Ancestors (in MRO)

  • c8.executor.Executor

Class variables

Variable context {#c8.executor.BatchExecutor.context}

Instance variables

Variable jobs {#c8.executor.BatchExecutor.jobs}

Return the queued batch jobs.

:return: Batch jobs or None if return_result parameter was set to
False during initialization.
:rtype: [c8.job.BatchJob] | None

Methods

Method commit {#c8.executor.BatchExecutor.commit}

def commit(self)

Execute the queued requests in a single batch API request.

If return_result parameter was set to True during initialization,
:class:BatchJob instances are populated with results.

:return: Batch jobs or None if return_result parameter was set to
False during initialization.
:rtype: [c8.job.BatchJob] | None
:raise c8.exceptions.BatchStateError: If batch state is invalid
(e.g. batch was already committed or size of response from server
did not match the expected).
:raise c8.exceptions.BatchExecuteError: If commit fails.

Method execute {#c8.executor.BatchExecutor.execute}

def execute(self, request, response_handler)

Place the request in the batch queue.

:param request: HTTP request.
:type request: c8.request.Request
:param response_handler: HTTP response handler.
:type response_handler: callable
:return: Batch job or None if return_result parameter was set to
False during initialization.
:rtype: c8.job.BatchJob | None
:raise c8.exceptions.BatchStateError: If batch was already
committed.

Class DefaultExecutor {#c8.executor.DefaultExecutor}

class DefaultExecutor(connection)

Default API executor.

:param connection: HTTP connection.
:type connection: c8.connection.Connection

Ancestors (in MRO)

  • c8.executor.Executor

Class variables

Variable context {#c8.executor.DefaultExecutor.context}

Methods

Method execute {#c8.executor.DefaultExecutor.execute}

def execute(self, request, response_handler)

Execute an API request and return the result.

:param request: HTTP request.
:type request: c8.request.Request
:param response_handler: HTTP response handler.
:type response_handler: callable
:return: API execution result.
:rtype: str | unicode | bool | int | list | dict

Class TransactionExecutor {#c8.executor.TransactionExecutor}

class TransactionExecutor(connection, return_result, read, write, timeout, sync)

Executes transaction API requests.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param return_result: If set to True, API executions return instances of
:class:TransactionJob that are populated with results on
commit. If set to False, API executions return None and no results are
tracked client-side.
:type return_result: bool
:param timeout: Timeout for waiting on collection locks. If set to 0,
C8Db server waits indefinitely. If not set, system default value
is used.
:type timeout: int
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param read: Names of collections read during transaction.
:type read: [str | unicode]
:param write: Names of collections written to during transaction.
:type write: [str | unicode]

Ancestors (in MRO)

  • c8.executor.Executor

Class variables

Variable context {#c8.executor.TransactionExecutor.context}

Instance variables

Variable jobs {#c8.executor.TransactionExecutor.jobs}

Return the queued transaction jobs.

:return: Transaction jobs or None if return_result parameter was
set to False during initialization.
:rtype: [c8.job.TransactionJob] | None

Methods

Method commit {#c8.executor.TransactionExecutor.commit}

def commit(self)

Execute the queued requests in a single transaction API request.

If return_result parameter was set to True during initialization,
:class:TransactionJob instances are populated with
results.

:return: Transaction jobs or None if return_result parameter was
set to False during initialization.
:rtype: [c8.job.TransactionJob] | None
:raise c8.exceptions.TransactionStateError: If the transaction was
already committed.
:raise c8.exceptions.TransactionExecuteError: If commit fails.

Method execute {#c8.executor.TransactionExecutor.execute}

def execute(self, request, response_handler)

Place the request in the transaction queue.

:param request: HTTP request.
:type request: c8.request.Request
:param response_handler: HTTP response handler.
:type response_handler: callable
:return: Transaction job or None if return_result parameter was
set to False during initialization.
:rtype: c8.job.TransactionJob | None
:raise c8.exceptions.TransactionStateError: If the transaction was
already committed or if the action does not support transactions.

Module c8.fabric {#c8.fabric}

Classes

Class AsyncFabric {#c8.fabric.AsyncFabric}

class AsyncFabric(connection, return_result)

Fabric API wrapper tailored specifically for async execution.

See :func:StandardFabric.begin_async_execution().

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param return_result: If set to True, API executions return instances of
:class:AsyncJob, which you can use to retrieve results
from server once available. If set to False, API executions return None
and no results are stored on server.
:type return_result: bool

Ancestors (in MRO)

Class BatchFabric {#c8.fabric.BatchFabric}

class BatchFabric(connection, return_result)

Fabric API wrapper tailored specifically for batch execution.

See :func:StandardFabric.begin_batch_execution().

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param return_result: If set to True, API executions return instances of
:class:BatchJob that are populated with results on commit.
If set to False, API executions return None and no results are tracked
client-side.
:type return_result: bool

Ancestors (in MRO)

Methods

Method commit {#c8.fabric.BatchFabric.commit}

def commit(self)

Execute the queued requests in a single batch API request.

If return_result parameter was set to True during initialization,
:class:BatchJob instances are populated with results.

:return: Batch jobs, or None if return_result parameter was set to
False during initialization.
:rtype: [c8.job.BatchJob] | None
:raise c8.exceptions.BatchStateError: If batch state is invalid
(e.g. batch was already committed or the response size did not
match expected).
:raise c8.exceptions.BatchExecuteError: If commit fails.

Method queued_jobs {#c8.fabric.BatchFabric.queued_jobs}

def queued_jobs(self)

Return the queued batch jobs.

:return: Queued batch jobs or None if return_result parameter was
set to False during initialization.
:rtype: [c8.job.BatchJob] | None

Class StandardFabric {#c8.fabric.StandardFabric}

class StandardFabric(connection)

Standard fabric API wrapper.

:param connection: HTTP connection.
:type connection: c8.connection.Connection

Ancestors (in MRO)

Methods

Method begin_async_execution {#c8.fabric.StandardFabric.begin_async_execution}

def begin_async_execution(self, return_result=True)

Begin async execution.

:param return_result: If set to True, API executions return instances
of :class:AsyncJob, which you can use to retrieve
results from server once available. If set to False, API executions
return None and no results are stored on server.
:type return_result: bool
:return: Fabric API wrapper built specifically for async execution.
:rtype: c8.fabric.AsyncFabric

Method begin_batch_execution {#c8.fabric.StandardFabric.begin_batch_execution}

def begin_batch_execution(self, return_result=True)

Begin batch execution.

:param return_result: If set to True, API executions return instances
of :class:BatchJob that are populated with results on
commit. If set to False, API executions return None and no results
are tracked client-side.
:type return_result: bool
:return: Fabric API wrapper built specifically for batch execution.
:rtype: c8.fabric.BatchFabric

Method begin_transaction {#c8.fabric.StandardFabric.begin_transaction}

def begin_transaction(self, return_result=True, timeout=None, sync=None, read=None, write=None)

Begin transaction.

:param return_result: If set to True, API executions return instances
of :class:TransactionJob that are populated with
results on commit. If set to False, API executions return None and
no results are tracked client-side.
:type return_result: bool
:param read: Names of collections read during transaction. If not
specified, they are added automatically as jobs are queued.
:type read: [str | unicode]
:param write: Names of collections written to during transaction.
If not specified, they are added automatically as jobs are queued.
:type write: [str | unicode]
:param timeout: Timeout for waiting on collection locks. If set to 0,
C8Db server waits indefinitely. If not set, system default
value is used.
:type timeout: int
:param sync: Block until the transaction is synchronized to disk.
:type sync: bool
:return: Fabric API wrapper built specifically for transactions.
:rtype: c8.fabric.TransactionFabric

Class TransactionFabric {#c8.fabric.TransactionFabric}

class TransactionFabric(connection, return_result, read, write, timeout, sync)

Fabric API wrapper tailored specifically for transactions.

See :func:StandardFabric.begin_transaction().

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param return_result: If set to True, API executions return instances of
:class:TransactionJob that are populated with results on
commit. If set to False, API executions return None and no results are
tracked client-side.
:type return_result: bool
:param read: Names of collections read during transaction.
:type read: [str | unicode]
:param write: Names of collections written to during transaction.
:type write: [str | unicode]
:param timeout: Timeout for waiting on collection locks. If set to 0, the
C8Db server waits indefinitely. If not set, system default value
is used.
:type timeout: int
:param sync: Block until operation is synchronized to disk.
:type sync: bool

Ancestors (in MRO)

Methods

Method commit {#c8.fabric.TransactionFabric.commit}

def commit(self)

Execute the queued requests in a single transaction API request.

If return_result parameter was set to True during initialization,
:class:TransactionJob instances are populated with
results.

:return: Transaction jobs, or None if return_result parameter was
set to False during initialization.
:rtype: [c8.job.TransactionJob] | None
:raise c8.exceptions.TransactionStateError: If the transaction was
already committed.
:raise c8.exceptions.TransactionExecuteError: If commit fails.

Method queued_jobs {#c8.fabric.TransactionFabric.queued_jobs}

def queued_jobs(self)

Return the queued transaction jobs.

:return: Queued transaction jobs, or None if return_result was set
to False during initialization.
:rtype: [c8.job.TransactionJob] | None

Module c8.graph {#c8.graph}

Classes

Class Graph {#c8.graph.Graph}

class Graph(connection, executor, name)

Graph API wrapper.

:param executor: API executor.
:type executor: c8.executor.Executor
:param name: Graph name.
:type name: str | unicode

Ancestors (in MRO)

Instance variables

Variable name {#c8.graph.Graph.name}

Return the graph name.

:return: Graph name.
:rtype: str | unicode

Methods

Method create_edge_definition {#c8.graph.Graph.create_edge_definition}

def create_edge_definition(self, edge_collection, from_vertex_collections, to_vertex_collections)

Create a new edge definition.

An edge definition consists of an edge collection, "from" vertex
collection(s) and "to" vertex collection(s). Here is an example entry:

Example:


    {
        'edge_collection': 'edge_collection_name',
        'from_vertex_collections': ['from_vertex_collection_name'],
        'to_vertex_collections': ['to_vertex_collection_name']
    }

:param edge_collection: Edge collection name.
:type edge_collection: str | unicode
:param from_vertex_collections: Names of "from" vertex collections.
:type from_vertex_collections: [str | unicode]
:param to_vertex_collections: Names of "to" vertex collections.
:type to_vertex_collections: [str | unicode]
:return: Edge collection API wrapper.
:rtype: c8.collection.EdgeCollection
:raise c8.exceptions.EdgeDefinitionCreateError: If create fails.

Method create_vertex_collection {#c8.graph.Graph.create_vertex_collection}

def create_vertex_collection(self, name)

Create a vertex collection in the graph.

:param name: Vertex collection name.
:type name: str | unicode
:return: Vertex collection API wrapper.
:rtype: c8.collection.VertexCollection
:raise c8.exceptions.VertexCollectionCreateError: If create fails.

Method delete_edge {#c8.graph.Graph.delete_edge}

def delete_edge(self, edge, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete an edge document.

:param edge: Edge document ID or body with "_id" field.
:type edge: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in edge if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:param ignore_missing: Do not raise an exception on missing document.
This parameter has no effect in transactions where an exception is
always raised on failures.
:type ignore_missing: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: True if edge was deleted successfully, False if edge was not
found and ignore_missing was set to True (does not apply in
transactions).
:rtype: bool
:raise c8.exceptions.DocumentDeleteError: If delete fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method delete_edge_definition {#c8.graph.Graph.delete_edge_definition}

def delete_edge_definition(self, name, purge=False)

Delete an edge definition from the graph.

:param name: Edge collection name.
:type name: str | unicode
:param purge: If set to True, the edge definition is not just removed
from the graph but the edge collection is also deleted completely
from the fabric.
:type purge: bool
:return: True if edge definition was deleted successfully.
:rtype: bool
:raise c8.exceptions.EdgeDefinitionDeleteError: If delete fails.

Method delete_vertex {#c8.graph.Graph.delete_vertex}

def delete_vertex(self, vertex, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete a vertex document.

:param vertex: Vertex document ID or body with "_id" field.
:type vertex: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in vertex if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:param ignore_missing: Do not raise an exception on missing document.
This parameter has no effect in transactions where an exception is
always raised on failures.
:type ignore_missing: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:return: True if vertex was deleted successfully, False if vertex was
not found and ignore_missing was set to True (does not apply in
transactions).
:rtype: bool
:raise c8.exceptions.DocumentDeleteError: If delete fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method delete_vertex_collection {#c8.graph.Graph.delete_vertex_collection}

def delete_vertex_collection(self, name, purge=False)

Remove a vertex collection from the graph.

:param name: Vertex collection name.
:type name: str | unicode
:param purge: If set to True, the vertex collection is not just deleted
from the graph but also from the fabric completely.
:type purge: bool
:return: True if vertex collection was deleted successfully.
:rtype: bool
:raise c8.exceptions.VertexCollectionDeleteError: If delete fails.

Method edge {#c8.graph.Graph.edge}

def edge(self, edge, rev=None, check_rev=True)

Return an edge document.

:param edge: Edge document ID or body with "_id" field.
:type edge: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in edge if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:return: Edge document or None if not found.
:rtype: dict | None
:raise c8.exceptions.DocumentGetError: If retrieval fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method edge_collection {#c8.graph.Graph.edge_collection}

def edge_collection(self, name)

Return the edge collection API wrapper.

:param name: Edge collection name.
:type name: str | unicode
:return: Edge collection API wrapper.
:rtype: c8.collection.EdgeCollection

Method edge_definitions {#c8.graph.Graph.edge_definitions}

def edge_definitions(self)

Return the edge definitions of the graph.

:return: Edge definitions of the graph.
:rtype: [dict]
:raise c8.exceptions.EdgeDefinitionListError: If retrieval fails.

Method edges {#c8.graph.Graph.edges}

def edges(self, collection, vertex, direction=None)

Return the edge documents coming in and/or out of given vertex.

:param collection: Edge collection name.
:type collection: str | unicode
:param vertex: Vertex document ID or body with "_id" field.
:type vertex: str | unicode | dict
:param direction: The direction of the edges. Allowed values are "in"
and "out". If not set, edges in both directions are returned.
:type direction: str | unicode
:return: List of edges
:rtype: dict
:raise c8.exceptions.EdgeListError: If retrieval fails.

Method has_edge {#c8.graph.Graph.has_edge}

def has_edge(self, edge, rev=None, check_rev=True)

Check if the given edge document exists in the graph.

:param edge: Edge document ID or body with "_id" field.
:type edge: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in edge if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:return: True if edge document exists, False otherwise.
:rtype: bool
:raise c8.exceptions.DocumentInError: If check fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method has_edge_collection {#c8.graph.Graph.has_edge_collection}

def has_edge_collection(self, name)

Check if the graph has the given edge collection.

:param name: Edge collection name.
:type name: str | unicode
:return: True if edge collection exists, False otherwise.
:rtype: bool

Method has_edge_definition {#c8.graph.Graph.has_edge_definition}

def has_edge_definition(self, name)

Check if the graph has the given edge definition.

:param name: Edge collection name.
:type name: str | unicode
:return: True if edge definition exists, False otherwise.
:rtype: bool

Method has_vertex {#c8.graph.Graph.has_vertex}

def has_vertex(self, vertex, rev=None, check_rev=True)

Check if the given vertex document exists in the graph.

:param vertex: Vertex document ID or body with "_id" field.
:type vertex: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in vertex if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:return: True if vertex document exists, False otherwise.
:rtype: bool
:raise c8.exceptions.DocumentGetError: If check fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method has_vertex_collection {#c8.graph.Graph.has_vertex_collection}

def has_vertex_collection(self, name)

Check if the graph has the given vertex collection.

:param name: Vertex collection name.
:type name: str | unicode
:return: True if vertex collection exists, False otherwise.
:rtype: bool

Method insert_edge {#c8.graph.Graph.insert_edge}

def insert_edge(self, collection, edge, sync=None, silent=False)

Insert a new edge document.

:param collection: Edge collection name.
:type collection: str | unicode
:param edge: New edge document to insert. It must contain "_from" and
"_to" fields. If it has "_key" or "_id" field, its value is used
as key of the new edge document (otherwise it is auto-generated).
Any "_rev" field is ignored.
:type edge: dict
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method insert_vertex {#c8.graph.Graph.insert_vertex}

def insert_vertex(self, collection, vertex, sync=None, silent=False)

Insert a new vertex document.

:param collection: Vertex collection name.
:type collection: str | unicode
:param vertex: New vertex document to insert. If it has "_key" or "_id"
field, its value is used as key of the new vertex (otherwise it is
auto-generated). Any "_rev" field is ignored.
:type vertex: dict
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method link {#c8.graph.Graph.link}

def link(self, collection, from_vertex, to_vertex, data=None, sync=None, silent=False)

Insert a new edge document linking the given vertices.

:param collection: Edge collection name.
:type collection: str | unicode
:param from_vertex: "From" vertex document ID or body with "_id" field.
:type from_vertex: str | unicode | dict
:param to_vertex: "To" vertex document ID or body with "_id" field.
:type to_vertex: str | unicode | dict
:param data: Any extra data for the new edge document. If it has "_key"
or "_id" field, its value is used as key of the new edge document
(otherwise it is auto-generated).
:type data: dict
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentInsertError: If insert fails.

Method properties {#c8.graph.Graph.properties}

def properties(self)

Return graph properties.

:return: Graph properties.
:rtype: dict
:raise c8.exceptions.GraphPropertiesError: If retrieval fails.

Method replace_edge {#c8.graph.Graph.replace_edge}

def replace_edge(self, edge, check_rev=True, sync=None, silent=False)

Replace an edge document.

:param edge: New edge document to replace the old one with. It must
contain the "_id" field. It must also contain the "_from" and "_to"
fields.
:type edge: dict
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentReplaceError: If replace fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method replace_edge_definition {#c8.graph.Graph.replace_edge_definition}

def replace_edge_definition(self, edge_collection, from_vertex_collections, to_vertex_collections)

Replace an edge definition.

:param edge_collection: Edge collection name.
:type edge_collection: str | unicode
:param from_vertex_collections: Names of "from" vertex collections.
:type from_vertex_collections: [str | unicode]
:param to_vertex_collections: Names of "to" vertex collections.
:type to_vertex_collections: [str | unicode]
:return: True if edge definition was replaced successfully.
:rtype: bool
:raise c8.exceptions.EdgeDefinitionReplaceError: If replace fails.

Method replace_vertex {#c8.graph.Graph.replace_vertex}

def replace_vertex(self, vertex, check_rev=True, sync=None, silent=False)

Replace a vertex document.

:param vertex: New vertex document to replace the old one with. It must
contain the "_id" field.
:type vertex: dict
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentReplaceError: If replace fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method update_edge {#c8.graph.Graph.update_edge}

def update_edge(self, edge, check_rev=True, keep_none=True, sync=None, silent=False)

Update an edge document.

:param edge: Partial or full edge document with updated values. It must
contain the "_id" field.
:type edge: dict
:param check_rev: If set to True, revision of edge (if given) is
compared against the revision of target edge document.
:type check_rev: bool
:param keep_none: If set to True, fields with value None are retained
in the document. If set to False, they are removed completely.
:type keep_none: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentUpdateError: If update fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method update_vertex {#c8.graph.Graph.update_vertex}

def update_vertex(self, vertex, check_rev=True, keep_none=True, sync=None, silent=False)

Update a vertex document.

:param vertex: Partial or full vertex document with updated values. It
must contain the "_id" field.
:type vertex: dict
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:param keep_none: If set to True, fields with value None are retained
in the document. If set to False, they are removed completely.
:type keep_none: bool
:param sync: Block until operation is synchronized to disk.
:type sync: bool
:param silent: If set to True, no document metadata is returned. This
can be used to save resources.
:type silent: bool
:return: Document metadata (e.g. document key, revision) or True if
parameter silent was set to True.
:rtype: bool | dict
:raise c8.exceptions.DocumentUpdateError: If update fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method vertex {#c8.graph.Graph.vertex}

def vertex(self, vertex, rev=None, check_rev=True)

Return a vertex document.

:param vertex: Vertex document ID or body with "_id" field.
:type vertex: str | unicode | dict
:param rev: Expected document revision. Overrides the value of "_rev"
field in vertex if present.
:type rev: str | unicode
:param check_rev: If set to True, revision of vertex (if given) is
compared against the revision of target vertex document.
:type check_rev: bool
:return: Vertex document or None if not found.
:rtype: dict | None
:raise c8.exceptions.DocumentGetError: If retrieval fails.
:raise c8.exceptions.DocumentRevisionError: If revisions mismatch.

Method vertex_collection {#c8.graph.Graph.vertex_collection}

def vertex_collection(self, name)

Return the vertex collection API wrapper.

:param name: Vertex collection name.
:type name: str | unicode
:return: Vertex collection API wrapper.
:rtype: c8.collection.VertexCollection

Method vertex_collections {#c8.graph.Graph.vertex_collections}

def vertex_collections(self)

Return vertex collections in the graph that are not orphaned.

:return: Names of vertex collections that are not orphaned.
:rtype: [str | unicode]
:raise c8.exceptions.VertexCollectionListError: If retrieval fails.

Module c8.http {#c8.http}

Classes

Class DefaultHTTPClient {#c8.http.DefaultHTTPClient}

class DefaultHTTPClient()

Default HTTP client implementation.

Ancestors (in MRO)

  • c8.http.HTTPClient

Methods

Method send_request {#c8.http.DefaultHTTPClient.send_request}

def send_request(self, method, url, params=None, data=None, headers=None, auth=None)

Send an HTTP request.

:param method: HTTP method in lowercase (e.g. "post").
:type method: str | unicode
:param url: Request URL.
:type url: str | unicode
:param headers: Request headers.
:type headers: dict
:param params: URL (query) parameters.
:type params: dict
:param data: Request payload.
:type data: str | unicode | bool | int | list | dict
:param auth: Username and password.
:type auth: tuple
:returns: HTTP response.
:rtype: c8.response.Response

Class HTTPClient {#c8.http.HTTPClient}

class HTTPClient(*args, **kwargs)

Abstract base class for HTTP clients.

Descendants

  • c8.http.DefaultHTTPClient

Methods

Method send_request {#c8.http.HTTPClient.send_request}

def send_request(self, method, url, headers=None, params=None, data=None, auth=None)

Send an HTTP request.

This method must be overridden by the user.

:param method: HTTP method in lowercase (e.g. "post").
:type method: str | unicode
:param url: Request URL.
:type url: str | unicode
:param headers: Request headers.
:type headers: dict
:param params: URL (query) parameters.
:type params: dict
:param data: Request payload.
:type data: str | unicode | bool | int | list | dict
:param auth: Username and password.
:type auth: tuple
:returns: HTTP response.
:rtype: c8.response.Response

Module c8.job {#c8.job}

Classes

Class AsyncJob {#c8.job.AsyncJob}

class AsyncJob(connection, job_id, response_handler)

Job for tracking and retrieving result of an async execution.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param job_id: Async job ID.
:type job_id: str | unicode
:param response_handler: HTTP response handler.
:type response_handler: callable

Ancestors (in MRO)

  • c8.job.Job

Instance variables

Variable id {#c8.job.AsyncJob.id}

Return the async job ID.

:return: Async job ID.
:rtype: str | unicode

Methods

Method cancel {#c8.job.AsyncJob.cancel}

def cancel(self, ignore_missing=False)

Cancel the async job.

An async job cannot be cancelled once it is taken out of the queue.

:param ignore_missing: Do not raise an exception on missing job.
:type ignore_missing: bool
:return: True if job was cancelled successfully, False if the job
was not found but ignore_missing was set to True.
:rtype: bool
:raise c8.exceptions.AsyncJobCancelError: If cancel fails.

Method clear {#c8.job.AsyncJob.clear}

def clear(self, ignore_missing=False)

Delete the job result from the server.

:param ignore_missing: Do not raise an exception on missing job.
:type ignore_missing: bool
:return: True if result was deleted successfully, False if the job
was not found but ignore_missing was set to True.
:rtype: bool
:raise c8.exceptions.AsyncJobClearError: If delete fails.

Method result {#c8.job.AsyncJob.result}

def result(self)

Return the async job result from server.

If the job raised an exception, it is propagated up at this point.

Once job result is retrieved, it is deleted from server and subsequent
queries for result will fail.

:return: Async job result.
:rtype: str | unicode | bool | int | list | dict
:raise c8.exceptions.C8Error: If the job raised an exception.
:raise c8.exceptions.AsyncJobResultError: If retrieval fails.

Method status {#c8.job.AsyncJob.status}

def status(self)

Return the async job status from server.

Once a job result is retrieved via func:AsyncJob.result()
method, it is deleted from server and subsequent status queries will
fail.

:return: Async job status. Possible values are "pending" (job is still
in queue), "done" (job finished or raised an error), or "cancelled"
(job was cancelled before completion).
:rtype: str | unicode
:raise c8.exceptions.AsyncJobStatusError: If retrieval fails.

Class BatchJob {#c8.job.BatchJob}

class BatchJob(response_handler)

Job for tracking and retrieving result of batch execution.

:param response_handler: HTTP response handler.
:type response_handler: callable

Ancestors (in MRO)

Instance variables

Variable id {#c8.job.BatchJob.id}

Return the batch job ID.

:return: Batch job ID.
:rtype: str | unicode

Methods

Method result {#c8.job.BatchJob.result}

def result(self)

Return the batch job result.

If the job raised an exception, it is propagated up at this point.

:return: Batch job result.
:rtype: str | unicode | bool | int | list | dict
:raise c8.exceptions.C8Error: If the job raised an exception.
:raise c8.exceptions.BatchJobResultError: If job result is not
available (i.e. batch is not committed yet).

Method status {#c8.job.BatchJob.status}

def status(self)

Return the batch job status.

:return: Batch job status. Possible values are "pending" (job is still
waiting for batch to be committed), or "done" (batch was committed
and the job is updated with the result).
:rtype: str | unicode

Class Job {#c8.job.Job}

class Job(*args, **kwargs)

Base class for API execution jobs.

Jobs are used to track progress of API executions, and retrieve results.

Descendants

Instance variables

Variable id {#c8.job.Job.id}

Return the job ID.

:return: Job ID.
:rtype: str | unicode

Methods

Method result {#c8.job.Job.result}

def result(self)

Return the job result (if available).

:return: Job result.
:rtype: str | unicode | bool | int | list | dict
:raise c8.exceptions.C8Error: If result was an error.

Method status {#c8.job.Job.status}

def status(self)

Return the job status.

:return: Job status.
:rtype: str | unicode

Class TransactionJob {#c8.job.TransactionJob}

class TransactionJob(response_handler)

Transaction API execution job.

:param response_handler: HTTP response handler.
:type response_handler: callable

Ancestors (in MRO)

Instance variables

Variable id {#c8.job.TransactionJob.id}

Return the transaction job ID.

:return: Transaction job ID.
:rtype: str | unicode

Methods

Method result {#c8.job.TransactionJob.result}

def result(self)

Return the transaction job result.

:return: Transaction job result.
:rtype: str | unicode | bool | int | list | dict
:raise c8.exceptions.C8Error: If the job raised an exception.
:raise c8.exceptions.TransactionJobResultError: If job result is
not available (i.e. transaction is not committed yet or failed).

Method status {#c8.job.TransactionJob.status}

def status(self)

Return the transaction job status.

:return: Transaction job status. Possible values are "pending" (job is
waiting for transaction to be committed, or transaction failed and
job is orphaned), or "done" (transaction was committed and job is
updated with the result).
:rtype: str | unicode

Module c8.request {#c8.request}

Classes

Class Request {#c8.request.Request}

class Request(method, endpoint, auth_tok=None, headers=None, params=None, data=None, command=None, read=None, write=None)

HTTP request.

:param method: HTTP method in lowercase (e.g. "post").
:type method: str | unicode
:param endpoint: API endpoint.
:type endpoint: str | unicode
:param headers: Request headers.
:type headers: dict
:param params: URL parameters.
:type params: dict
:param data: Request payload.
:type data: str | unicode | bool | int | list | dict
:param command: C8Sh command.
:type command: str | unicode
:param read: Names of collections read during transaction.
:type read: str | unicode | [str | unicode]
:param write: Names of collections written to during transaction.
:type write: str | unicode | [str | unicode]

:ivar method: HTTP method in lowercase (e.g. "post").
:vartype method: str | unicode
:ivar endpoint: API endpoint.
:vartype endpoint: str | unicode
:ivar headers: Request headers.
:vartype headers: dict
:ivar params: URL (query) parameters.
:vartype params: dict
:ivar data: Request payload.
:vartype data: str | unicode | bool | int | list | dict
:ivar command: C8Sh command.
:vartype command: str | unicode | None
:ivar read: Names of collections read during transaction.
:vartype read: str | unicode | [str | unicode] | None
:ivar write: Names of collections written to during transaction.
:vartype write: str | unicode | [str | unicode] | None

Instance variables

Variable command {#c8.request.Request.command}

Variable data {#c8.request.Request.data}

Variable endpoint {#c8.request.Request.endpoint}

Variable headers {#c8.request.Request.headers}

Variable method {#c8.request.Request.method}

Variable params {#c8.request.Request.params}

Variable read {#c8.request.Request.read}

Variable write {#c8.request.Request.write}

Methods

Method set_auth_token_in_header {#c8.request.Request.set_auth_token_in_header}

def set_auth_token_in_header(self, auth_tok)

Set the Authorization header with the specified JWT auth token.

:param auth_tok: JWT Autentication to use in this request
:type auth_tok: str | unicode

Module c8.response {#c8.response}

Classes

Class Response {#c8.response.Response}

class Response(method, url, headers, status_code, status_text, raw_body)

HTTP response.

:param method: HTTP method in lowercase (e.g. "post").
:type method: str | unicode
:param url: API URL.
:type url: str | unicode
:param headers: Response headers.
:type headers: requests.structures.CaseInsensitiveDict | dict
:param status_code: Response status code.
:type status_code: int
:param status_text: Response status text.
:type status_text: str | unicode
:param raw_body: Raw response body.
:type raw_body: str | unicode

:ivar method: HTTP method in lowercase (e.g. "post").
:vartype method: str | unicode
:ivar url: API URL.
:vartype url: str | unicode
:ivar headers: Response headers.
:vartype headers: requests.structures.CaseInsensitiveDict | dict
:ivar status_code: Response status code.
:vartype status_code: int
:ivar status_text: Response status text.
:vartype status_text: str | unicode
:ivar body: JSON-deserialized response body.
:vartype body: str | unicode | bool | int | list | dict
:ivar raw_body: Raw response body.
:vartype raw_body: str | unicode
:ivar error_code: Error code from C8Db server.
:vartype error_code: int
:ivar error_message: Error message from C8Db server.
:vartype error_message: str | unicode
:ivar is_success: True if response status code was 2XX.
:vartype is_success: bool

Instance variables

Variable body {#c8.response.Response.body}

Variable error_code {#c8.response.Response.error_code}

Variable error_message {#c8.response.Response.error_message}

Variable headers {#c8.response.Response.headers}

Variable is_success {#c8.response.Response.is_success}

Variable method {#c8.response.Response.method}

Variable raw_body {#c8.response.Response.raw_body}

Variable status_code {#c8.response.Response.status_code}

Variable status_text {#c8.response.Response.status_text}

Variable url {#c8.response.Response.url}

Module c8.stream_collection {#c8.stream_collection}

Classes

Class StreamCollection {#c8.stream_collection.StreamCollection}

class StreamCollection(fabric, connection, executor, url, port, operation_timeout_seconds)

Stream Client.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor

Create a new Stream client instance.
Args

  • service_url: Streams service url eg: pulsar://my-broker.com:6650/
    Options
  • authentication:
    Set the authentication provider to be used with the broker.
  • operation_timeout_seconds:
    Set timeout on client operations (subscribe, create producer, close,
    unsubscribe).
  • io_threads:
    Set the number of IO threads to be used by the Pulsar client.
  • message_listener_threads:
    Set the number of threads to be used by the Pulsar client when
    delivering messages through message listener. The default is 1 thread
    per Pulsar client. If using more than 1 thread, messages for distinct
    message_listeners will be delivered in different threads, however a
    single MessageListener will always be assigned to the same thread.
  • concurrent_lookup_requests:
    Number of concurrent lookup-requests allowed on each broker
    connection to prevent overload on the broker.
  • log_conf_file_path:
    Initialize log4cxx from a configuration file.
  • use_tls:
    Configure whether to use TLS encryption on the connection. This
    setting is deprecated. TLS will be automatically enabled if the
    serviceUrl is set to pulsar+ssl:// or <https://>
  • tls_trust_certs_file_path:
    Set the path to the trusted TLS certificate file.
  • tls_allow_insecure_connection:
    Configure whether the Pulsar client accepts untrusted TLS
    certificates from the broker.

Ancestors (in MRO)

Class variables

Variable COMPRESSION_TYPES {#c8.stream_collection.StreamCollection.COMPRESSION_TYPES}

Variable CONSUMER_TYPES {#c8.stream_collection.StreamCollection.CONSUMER_TYPES}

Variable ROUTING_MODE {#c8.stream_collection.StreamCollection.ROUTING_MODE}

Variable types {#c8.stream_collection.StreamCollection.types}

Methods

Method clear_stream_backlog {#c8.stream_collection.StreamCollection.clear_stream_backlog}

def clear_stream_backlog(self, subscription)

Clear backlog for the given stream on a stream fabric
:param: name of subscription
:return: 200, OK if operation successful
:raise c8.exceptions.StreamPermissionError: If clearing backlogs for
all streams fails.

Method clear_streams_backlog {#c8.stream_collection.StreamCollection.clear_streams_backlog}

def clear_streams_backlog(self)

Clear backlog for all streams on a stream fabric
:return: 200, OK if operation successful
:raise c8.exceptions.StreamPermissionError: If clearing backlogs for
all streams fails.

Method close {#c8.stream_collection.StreamCollection.close}

def close(self)

Close the client and all the associated producers and consumers

Method create_producer {#c8.stream_collection.StreamCollection.create_producer}

def create_producer(self, stream, local=False, producer_name=None, initial_sequence_id=None, send_timeout_millis=30000, compression_type=_pulsar.CompressionType.NONE, max_pending_messages=1000, block_if_queue_full=False, batching_enabled=False, batching_max_messages=1000, batching_max_allowed_size_in_bytes=131072, batching_max_publish_delay_ms=10, message_routing_mode=_pulsar.PartitionsRoutingMode.RoundRobinDistribution)

Create a new producer on a given stream.
Args

  • stream: The stream name
    Options
  • persistent: If the stream_stream is persistent or non-persistent
    default its persitent
  • local: If the stream_stream is local or global default its global
  • producer_name: Specify a name for the producer. If not assigned,
    the system will generate a globally unique name
    which can be accessed with
    Producer.producer_name(). When specifying a name,
    it is app to the user to ensure that, for a given
    topic, the producer name is unique across all
    Pulsar's clusters.
  • initial_sequence_id: Set the baseline for the sequence ids for
    messages published by the producer. First
    message will be using
    `(initialSequenceId + 1)`` as its sequence id
    and subsequent messages will be assigned
    incremental sequence ids, if not otherwise
    specified.
  • send_timeout_seconds: If a message is not acknowledged by the
    server before the send_timeout expires, an
    error will be reported.
  • compression_type: Set the compression type for the producer. By
    default, message payloads are not compressed.
    Supported compression types are
    CompressionType.LZ4 and CompressionType.ZLib.
  • max_pending_messages: Set the max size of the queue holding the
    messages pending to receive
    an acknowledgment from the broker.
  • block_if_queue_full: Set whether send_async operations should
    block when the outgoing message queue is full.
  • message_routing_mode: Set the message routing mode for the
    partitioned producer. Default is
    PartitionsRoutingMode.RoundRobinDistribution, # noqa
    other option is
    PartitionsRoutingMode.UseSinglePartition

Method create_reader {#c8.stream_collection.StreamCollection.create_reader}

def create_reader(self, stream, start_message_id, local=False, reader_listener=None, receiver_queue_size=1000, reader_name=None, subscription_role_prefix=None)

Create a reader on a particular topic
Args

  • stream: The name of the stream.
  • start_message_id: The initial reader positioning is done by
    specifying a message id.
    Options
  • local: If the stream_stream is local or global default its global
  • reader_listener:
    Sets a message listener for the reader. When the listener is set,
    the application will receive messages through it. Calls to
    reader.read_next() will not be allowed. The listener function
    needs to accept (reader, message), for example:
  • receiver_queue_size:
    Sets the size of the reader receive queue. The reader receive
    queue controls how many messages can be accumulated by the reader
    before the application calls read_next(). Using a higher value
    could potentially increase the reader throughput at the expense of
    higher memory utilization.
  • reader_name: Sets the reader name.
  • subscription_role_prefix: Sets the subscription role prefix.

Method delete_stream_subscription {#c8.stream_collection.StreamCollection.delete_stream_subscription}

def delete_stream_subscription(self, stream, subscription, local=False)

Delete a subscription.

:param stream: name of stream
:param subscription: name of subscription
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamDeleteError: If Subscription has active
consumers

Method enum {#c8.stream_collection.StreamCollection.enum}

def enum(**enums)

Method expire_messages_for_all_subscription {#c8.stream_collection.StreamCollection.expire_messages_for_all_subscription}

def expire_messages_for_all_subscription(self, stream, expire_time, local=False)

Expire messages on a stream subscription

:param stream:
:param subscription:
:param expire_time:
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError:Don't have permission

Method expire_messages_for_subscription {#c8.stream_collection.StreamCollection.expire_messages_for_subscription}

def expire_messages_for_subscription(self, stream, subscription, expire_time, local=False)

Method expire_messages_for_subscriptions {#c8.stream_collection.StreamCollection.expire_messages_for_subscriptions}

def expire_messages_for_subscriptions(self, stream, expire_time, local=False)

Expire messages on all subscriptions of stream

:param stream:
:param subscription:
:param expire_time:
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError:Don't have permission

Method get_stream_backlog {#c8.stream_collection.StreamCollection.get_stream_backlog}

def get_stream_backlog(self, stream, local=False)

Get estimated backlog for offline stream.

:param stream: name of stream
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError: If getting subscriptions
for a stream fails.

Method get_stream_compaction_status {#c8.stream_collection.StreamCollection.get_stream_compaction_status}

def get_stream_compaction_status(self, stream, local=False)

Get the status of a compaction operation for a stream
:param stream: Name of stream
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError: Dont have permission.

Method get_stream_stats {#c8.stream_collection.StreamCollection.get_stream_stats}

def get_stream_stats(self, stream, local=False)

Get the stats for the given stream

:param stream: name of stream
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError: If getting subscriptions
for a stream fails.

Method get_stream_subscriptions {#c8.stream_collection.StreamCollection.get_stream_subscriptions}

def get_stream_subscriptions(self, stream, local=False)

Get the list of persistent subscriptions for a given stream.

:param stream: name of stream
:param local: Operate on a local stream instead of a global one.
:return: List of stream subscription, OK if operation successful
:raise: c8.exceptions.StreamPermissionError: If getting subscriptions
for a stream fails.

Method put_stream_compaction_status {#c8.stream_collection.StreamCollection.put_stream_compaction_status}

def put_stream_compaction_status(self, stream, local=False)

Trigger a compaction operation on a stream

:param stream: Name of stream
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError: Dont have permission.

Method reset_message_for_subscription {#c8.stream_collection.StreamCollection.reset_message_for_subscription}

def reset_message_for_subscription(self, stream, subscription, local=False)

Reset subscription to message position closest to given position

:param stream: Name of stream
:param subscription: Name of subscription
:param timestamp: Timestamp
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamDeleteError: If Subscription has active
consumers

Method reset_message_subscription {#c8.stream_collection.StreamCollection.reset_message_subscription}

def reset_message_subscription(self, stream, subscription, message_id, local=False)

Reset subscription to message position closest to given position.

:param stream: name of stream
:param subscription: name of subscription
:param message_id: message object consisting of
{ ledgerId integer, entryId integer, partitionIndex integer }
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamUpdateError: If Subscription has active
consumers

Method reset_message_subscription_by_position {#c8.stream_collection.StreamCollection.reset_message_subscription_by_position}

def reset_message_subscription_by_position(self, stream, subscription, message_position)

It fence cursor and disconnects all active consumers before reseting
cursor.

:param stream: Name of stream
:param subscription: Name of subscription
:param message_position: Integer
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamDeleteError: If Subscription has active
consumers

Method reset_message_subscription_by_timestamp {#c8.stream_collection.StreamCollection.reset_message_subscription_by_timestamp}

def reset_message_subscription_by_timestamp(self, stream, subscription, timestamp)

Reset subscription to message position closest to absolute timestamp

:param stream:
:param subscription:
:param timestamp:
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError:Don't have permission

Method skip_all_messages_for_subscription {#c8.stream_collection.StreamCollection.skip_all_messages_for_subscription}

def skip_all_messages_for_subscription(self, stream, subscription, local=False)

Skip all messages on a stream subscription

:param stream: name of stream
:param subscription: name of subscription
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError:Don't have permission

Method skip_messages_for_subscription {#c8.stream_collection.StreamCollection.skip_messages_for_subscription}

def skip_messages_for_subscription(self, stream, subscription, num_of_messages, local=False)

Skip num messages on a topic subscription

:param stream: Name of stream
:param subscription: Name of subscription
:param num_of_messages: Number of messages
:param local: Operate on a local stream instead of a global one.
:return: 200, OK if operation successful
:raise: c8.exceptions.StreamPermissionError:Don't have permission

Method subscribe {#c8.stream_collection.StreamCollection.subscribe}

def subscribe(self, stream, local=False, subscription_name=None, consumer_type=_pulsar.ConsumerType.Exclusive, message_listener=None, receiver_queue_size=1000, consumer_name=None, unacked_messages_timeout_ms=None, broker_consumer_stats_cache_time_ms=30000, is_read_compacted=False)

Subscribe to the given topic and subscription combination.
Args

  • stream: The name of the stream.
  • subscription: The name of the subscription.
    Options
  • local: If the stream_stream is local or global default its global
  • consumer_type: Select the subscription type to be used when
    subscribing to the topic.
  • message_listener: Sets a message listener for the consumer. When
    the listener is set, the application will receive
    messages through it. Calls to
    consumer.receive() will not be allowed. The
    listener function needs to accept
    (consumer, message)
  • receiver_queue_size:
    Sets the size of the consumer receive queue. The consumer receive
    queue controls how many messages can be accumulated by the consumer
    before the application calls receive(). Using a higher value
    could potentially increase the consumer throughput at the expense
    of higher memory utilization. Setting the consumer queue size to
    zero decreases the throughput of the consumer by disabling
    pre-fetching of messages. This approach improves the message
    distribution on shared subscription by pushing messages only to
    those consumers that are ready to process them. Neither receive
    with timeout nor partitioned topics can be used if the consumer
    queue size is zero. The receive() function call should not be
    interrupted when the consumer queue size is zero. The default value
    is 1000 messages and should work well for most use cases.
  • consumer_name: Sets the consumer name.
  • unacked_messages_timeout_ms:
    Sets the timeout in milliseconds for unacknowledged messages.
    The timeout needs to be greater than 10 seconds. An exception is
    thrown if the given value is less than 10 seconds. If a successful
    acknowledgement is not sent within the timeout, all the
    unacknowledged messages are redelivered.
  • broker_consumer_stats_cache_time_ms:
    Sets the time duration for which the broker-side consumer stats
    will be cached in the client.

Method unsubscribe {#c8.stream_collection.StreamCollection.unsubscribe}

def unsubscribe(self, subscription)

Unsubscribes the given subscription on all streams on a stream fabric
:param subscription
:return: 200, OK if operation successful
raise c8.exceptions.StreamPermissionError: If unsubscribing fails.

Module c8.tenant {#c8.tenant}

Classes

Class Tenant {#c8.tenant.Tenant}

class Tenant(connection)

Base class for Tenant API wrappers.

:param connection: HTTP connection.
:type connection: c8.connection.Connection
:param executor: API executor.
:type executor: c8.executor.Executor

Ancestors (in MRO)

Instance variables

Variable auth_token {#c8.tenant.Tenant.auth_token}

Return the stored JWT auth token for this tenant & user, if stored.
This will be stored after calling get_auth_token_from_server() above.

:return: JWT auth token stored for this tenant user
:rtype: str | unicode

Variable name {#c8.tenant.Tenant.name}

Return tenant name.

:return: tenant name.
:rtype: str | unicode

Methods

Method assign_dc_spot {#c8.tenant.Tenant.assign_dc_spot}

def assign_dc_spot(self, dc, spot_region=False)

Assigns spot region of a fed

:param: dc: dc name
:type: str
:param: spot_region: If True, makes the region a spot region
:type: bool
:return: True if request successful,false otherwise
:rtype: bool
:raise c8.exceptions.SpotRegionAssignError: If assignment fails.

Note:-
tenant needs to have Geo fabrics feature gate enabled to create geofabric.

Method create_tenant {#c8.tenant.Tenant.create_tenant}

def create_tenant(self, name, passwd='', dclist=[], extra={})

Create a new tenant.
:param name: Tenant name.
:type name: str | unicode
:param passwd: What I presume is the tenant admin user password.
:type passwd: str
:param dclist: comma separated list of region where tenant will be
created. If no value passed tenant will be created
globally.
:type dclist: list
:param extra: Extra config info.
:type extra: dict
:return: True if tenant was created successfully.
:rtype: bool
:raise c8.exceptions.TenantCreateError: If create fails.

Here is an example entry for parameter users:

Example:


    {
        'name': 'john',
        'passwd': 'password',
        'extra': {'Department': 'IT'}
    }

Method create_user {#c8.tenant.Tenant.create_user}

def create_user(self, username, password, active=True, extra=None)

Create a new user.

:param username: Username.
:type username: str | unicode
:param password: Password.
:type password: str | unicode
:param active: True if user is active, False otherwise.
:type active: bool
:param extra: Additional data for the user.
:type extra: dict
:return: New user details.
:rtype: dict
:raise c8.exceptions.UserCreateError: If create fails.

Method dclist {#c8.tenant.Tenant.dclist}

def dclist(self, detail=False)

Return the list of names of Datacenters

:param detail: detail list of DCs if set to true else only DC names
:type: boolean
:return: DC List.
:rtype: [str | unicode ]
:raise c8.exceptions.TenantListError: If retrieval fails.

Method delete_tenant {#c8.tenant.Tenant.delete_tenant}

def delete_tenant(self, name, ignore_missing=False)

Delete the tenant.
:param name: Tenant name.
:type name: str | unicode
:param ignore_missing: Do not raise an exception on missing tenant.
:type ignore_missing: bool
:return: True if tenant was deleted successfully, False if tenant
was not found and ignore_missing was set to True.
:rtype: bool
:raise c8.exceptions.TenantDeleteError: If delete fails.

Method delete_user {#c8.tenant.Tenant.delete_user}

def delete_user(self, username, ignore_missing=False)

Delete a user.

:param username: Username.
:type username: str | unicode
:param ignore_missing: Do not raise an exception on missing user.
:type ignore_missing: bool
:return: True if user was deleted successfully, False if user was not
found and ignore_missing was set to True.
:rtype: bool
:raise c8.exceptions.UserDeleteError: If delete fails.

Method get_auth_token_from_server {#c8.tenant.Tenant.get_auth_token_from_server}

def get_auth_token_from_server(self)

Returns the JWT auth token which can be used in subsequent requests
The login for the auth token is done using the username and password
for the current tenant object.

Method has_tenant {#c8.tenant.Tenant.has_tenant}

def has_tenant(self, name)

Check if a tenant exists.

:param name: Tenant name.
:type name: str | unicode
:return: True if tenant exists, False otherwise.
:rtype: bool

Method has_user {#c8.tenant.Tenant.has_user}

def has_user(self, username)

Check if user exists.

:param username: Username.
:type username: str | unicode
:return: True if user exists, False otherwise.
:rtype: bool

Method localdc {#c8.tenant.Tenant.localdc}

def localdc(self, detail=True)

Return the list of local Datacenters

:param detail: detail list of DCs if set to true else only DC names
:type: boolean
:return: DC List.
:rtype: [str | dict ]
:raise c8.exceptions.TenantListError: If retrieval fails.

Method permission {#c8.tenant.Tenant.permission}

def permission(self, username, fabric, collection=None)

Return user permission for a specific fabric or collection.

:param username: Username.
:type username: str | unicode
:param fabric: fabric name.
:type fabric: str | unicode
:param collection: Collection name.
:type collection: str | unicode
:return: Permission for given fabric or collection.
:rtype: str | unicode
:raise: c8.exceptions.PermissionGetError: If retrieval fails.

Method permissions {#c8.tenant.Tenant.permissions}

def permissions(self, username)

Return user permissions for all fabrics and collections.

:param username: Username.
:type username: str | unicode
:return: User permissions for all fabrics and collections.
:rtype: dict
:raise: c8.exceptions.PermissionListError: If retrieval fails.

Method replace_user {#c8.tenant.Tenant.replace_user}

def replace_user(self, username, password, active=None, extra=None)

Replace a user.

:param username: Username.
:type username: str | unicode
:param password: New password.
:type password: str | unicode
:param active: Whether the user is active.
:type active: bool
:param extra: Additional data for the user.
:type extra: dict
:return: New user details.
:rtype: dict
:raise c8.exceptions.UserReplaceError: If replace fails.

Method reset_permission {#c8.tenant.Tenant.reset_permission}

def reset_permission(self, username, fabric, collection=None)

Reset user permission for a specific fabric or collection.

:param username: Username.
:type username: str | unicode
:param fabric: fabric name.
:type fabric: str | unicode
:param collection: Collection name.
:type collection: str | unicode
:return: True if permission was reset successfully.
:rtype: bool
:raise c8.exceptions.PermissionRestError: If reset fails.

Method tenants {#c8.tenant.Tenant.tenants}

def tenants(self)

Return the names all tenants.

:return: Tenant names.
:rtype: [str | unicode]
:raise c8.exceptions.TenantListError: If retrieval fails.

Method update_permission {#c8.tenant.Tenant.update_permission}

def update_permission(self, username, permission, fabric, collection=None)

Update user permission for a specific fabric or collection.

:param username: Username.
:type username: str | unicode
:param fabric: fabric name.
:type fabric: str | unicode
:param collection: Collection name.
:type collection: str | unicode
:param permission: Allowed values are "rw" (read and write), "ro"
(read only) or "none" (no access).
:type permission: str | unicode
:return: True if access was granted successfully.
:rtype: bool
:raise c8.exceptions.PermissionUpdateError: If update fails.

Method update_tenant {#c8.tenant.Tenant.update_tenant}

def update_tenant(self, name, passwd='', extra={})

Update a existing tenant.
:param name: Tenant name.
:type name: str | unicode
:param passwd: What I presume is the tenant admin user password.
:param extra: Extra config info.
:type extra: [dict]
:return: True if tenant was created successfully.
:rtype: bool
:raise c8.exceptions.TenantCreateError: If create fails.

Here is an example entry for parameter users:

Example:


    {
        'username': 'john',
        'password': 'password',
        'active': True,
        'extra': {'Department': 'IT'}
    }

Method update_user {#c8.tenant.Tenant.update_user}

def update_user(self, username, password=None, active=None, extra=None)

Update a user.

:param username: Username.
:type username: str | unicode
:param password: New password.
:type password: str | unicode
:param active: Whether the user is active.
:type active: bool
:param extra: Additional data for the user.
:type extra: dict
:return: New user details.
:rtype: dict
:raise c8.exceptions.UserUpdateError: If update fails.

Method user {#c8.tenant.Tenant.user}

def user(self, username)

Return user details.

:param username: Username.
:type username: str | unicode
:return: User details.
:rtype: dict
:raise c8.exceptions.UserGetError: If retrieval fails.

Method users {#c8.tenant.Tenant.users}

def users(self)

Return all user details.

:return: List of user details.
:rtype: [dict]
:raise c8.exceptions.UserListError: If retrieval fails.

Module c8.utils {#c8.utils}

Functions

Function get_col_name {#c8.utils.get_col_name}

def get_col_name(doc)

Return the collection name from input.

:param doc: Document ID or body with "_id" field.
:type doc: str | unicode | dict
:return: Collection name.
:rtype: [str | unicode]
:raise c8.exceptions.DocumentParseError: If document ID is missing.

Function get_doc_id {#c8.utils.get_doc_id}

def get_doc_id(doc)

Return the document ID from input.

:param doc: Document ID or body with "_id" field.
:type doc: str | unicode | dict
:return: Document ID.
:rtype: str | unicode
:raise c8.exceptions.DocumentParseError: If document ID is missing.

Function is_none_or_int {#c8.utils.is_none_or_int}

def is_none_or_int(obj)

Check if obj is None or an integer.

:param obj: Object to check.
:type obj: object
:return: True if object is None or an integer.
:rtype: bool

Function is_none_or_str {#c8.utils.is_none_or_str}

def is_none_or_str(obj)

Check if obj is None or a string.

:param obj: Object to check.
:type obj: object
:return: True if object is None or a string.
:rtype: bool

Function suppress_warning {#c8.utils.suppress_warning}

def suppress_warning(logger_name)

Suppress logger messages.

:param logger_name: Full name of the logger.
:type logger_name: str | unicode

Module c8.version {#c8.version}

Was this article helpful?