py2neo.client.bolt – Low-level Bolt client for Neo4j

This module contains client implementations for the Bolt messaging protocol. It contains a base Bolt class, which is a type of Connection, and which is further extended by a separate class for each protocol version. Bolt1 extends Bolt, Bolt2 extends Bolt1, and so on.

Each subclass therefore introduces deltas atop the previous protocol version. This reduces duplication of client code at the expense of more work should an old protocol version be removed.

As of Bolt 4.0, the protocol versioning scheme aligned directly with that of Neo4j itself. Prior to this, the protocol was versioned with a single integer that did not necessarily increment in line with each Neo4j product release.

class py2neo.client.bolt.Bolt(wire, profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

This is the base class for Bolt client connections. This class is not intended to be instantiated directly, but contains an open() factory method that returns an instance of the appropriate subclass, once a connection has been successfully established.

broken

True if the connection has been broken by the server or network.

close()

Close the connection.

closed

True if the connection has been closed by the client.

classmethod open(profile=None, user_agent=None, on_bind=None, on_unbind=None, on_release=None, on_broken=None)

Open a Bolt connection to a server.

Parameters:

• profile – ConnectionProfile detailing how and where to connect
• user_agent –
• on_bind –
• on_unbind –
• on_release –
• on_broken –

Returns:

Bolt connection object

Raises:

ConnectionUnavailable if a connection cannot be opened, or a protocol version cannot be agreed

supports_multi()

Detect whether or not this connection supports multi-database.

class py2neo.client.bolt.Bolt1(wire, profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

begin(graph_name, readonly=False)

Begin a transaction. This method may invoke network activity.

Parameters:

• graph_name –
• readonly –

Returns:

new Transaction object

Raises:

Failure – if a new transaction cannot be created

commit(tx)

Commit a transaction. This method will always invoke network activity.

Parameters:

tx – the transaction to commit

Returns:

bookmark

Raises:

• ValueError – if the supplied Transaction object is not valid for committing
• ConnectionBroken – if the transaction cannot be committed

rollback(tx)

Rollback a transaction. This method will always invoke network activity.

Parameters:

tx – the transaction to rollback

Returns:

bookmark

Raises:

• ValueError – if the supplied Transaction object is not valid for rolling back
• ConnectionBroken – if the transaction cannot be rolled back

route(graph_name=None, context=None)

Fetch the routing table for a given database.

Parameters:

• graph_name – the name of the graph database for which to retrieve a routing table; None references the default database
• context – an optional dictionary of routing context information

Returns:

4-tuple of router, reader, writer connection profiles, plus ttl

Raises:

TypeError – if routing is not supported

run_prog(graph_name, cypher, parameters=None, readonly=False)

Run a single query within an auto-commit transaction. This method may invoke network activity

Parameters:

• graph_name –
• cypher –
• parameters –
• readonly –

Returns:

sync(result)

Perform network synchronisation required to make available a given result.

class py2neo.client.bolt.Bolt2(wire, profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

class py2neo.client.bolt.Bolt3(wire, profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

begin(graph_name, readonly=False)

Begin a transaction. This method may invoke network activity.

Parameters:

• graph_name –
• readonly –

Returns:

new Transaction object

Raises:

Failure – if a new transaction cannot be created

commit(tx)

Commit a transaction. This method will always invoke network activity.

Parameters:

tx – the transaction to commit

Returns:

bookmark

Raises:

• ValueError – if the supplied Transaction object is not valid for committing
• ConnectionBroken – if the transaction cannot be committed

rollback(tx)

Rollback a transaction. This method will always invoke network activity.

Parameters:

tx – the transaction to rollback

Returns:

bookmark

Raises:

• ValueError – if the supplied Transaction object is not valid for rolling back
• ConnectionBroken – if the transaction cannot be rolled back

run_prog(graph_name, cypher, parameters=None, readonly=False)

Run a single query within an auto-commit transaction. This method may invoke network activity

Parameters:

• graph_name –
• cypher –
• parameters –
• readonly –

Returns:

class py2neo.client.bolt.Bolt4x0(wire, profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

route(graph_name=None, context=None)

Fetch the routing table for a given database.

Parameters:

• graph_name – the name of the graph database for which to retrieve a routing table; None references the default database
• context – an optional dictionary of routing context information

Returns:

4-tuple of router, reader, writer connection profiles, plus ttl

Raises:

TypeError – if routing is not supported

class py2neo.client.bolt.Bolt4x1(wire, profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

class py2neo.client.bolt.BoltTransactionRef(graph_name, protocol_version, readonly=False, after=None, metadata=None, timeout=None)

class py2neo.client.bolt.BoltResult(graph_name, cx, response)

The result of a query carried out over a Bolt connection.

Implementation-wise, this form of query is comprised of a number of individual message exchanges. Each of these exchanges may succeed or fail in its own right, but contribute to the overall success or failure of the query.

buffer()

Fetch the remainder of the result into memory. This method may carry out network activity.

Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

fetch()

Fetch and return the next record in this result, or None if at the end of the result. This method may carry out network activity.

Returns:the next available record, or None Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

fields()

Return the list of field names for records in this result. This method may carry out network activity.

Returns:list of field names Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

graph_name

Return the name of the database from which this result originates.

Returns:database name

has_records()

Return True if this result contains buffered records, False otherwise. This method does not carry out any network activity.

Returns:boolean indicator

peek_records(limit)

Return up to limit records from the buffer if available. This method does not carry out any network activity.

Returns:list of records

protocol_version

Return the underlying protocol version used to transfer this result, or None if not applicable.

Returns:protocol version

query_id

Return the ID of the query behind this result. This method may carry out network activity.

Returns:query ID or None Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

summary()

Gather and return summary information as relates to the current progress of query execution and result retrieval. This method does not carry out any network activity.

Returns:summary information

take_record()

Return the next record from the buffer if one is available, None otherwise. This method does not carry out any network activity.

Returns:record or None