py2neo.client – Low-level client connections for Neo4j

exception py2neo.client.BrokenTransactionError

Raised when a transaction is broken by the network or remote peer.

class py2neo.client.Connection(profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

A single point-to-point connection between a client and a server.

This base class is extended by both Bolt and HTTP implementations and contains interfaces for the basic operations provided by both.

Variables:

• Connection.profile – connection profile
• Connection.user_agent –

age

The age of this connection in seconds.

begin(graph_name)

Begin a transaction. This method may invoke network activity.

Parameters:graph_name – Returns:new Transaction object Raises:TransactionError – if a new transaction cannot be created

broken

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

closed

True if the connection has been closed by the client.

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
• BrokenTransactionError – if the transaction cannot be committed

release()

Signal that this connection is no longer in use.

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
• BrokenTransactionError – if the transaction cannot be rolled back

supports_multi()

Detect whether or not this connection supports multi-database.

sync(result)

Perform network synchronisation required to make available a given result.

class py2neo.client.ConnectionPool(profile, user_agent=None, max_size=None, max_age=None, on_bind=None, on_unbind=None)

A pool of connections targeting a single Neo4j server.

acquire(graph_name=None, readonly=False, timeout=None, force_reset=False)

Acquire a connection from the pool.

In the simplest case, this will return an existing open connection, if one is free. If not, and the pool is not full, a new connection will be created. If the pool is full and no free connections are available, this will block until a connection is released, or until the acquire call is cancelled.

This method will return None if and only if the maximum size of the pool is set to zero. In this special case, no amount of waiting would result in the acquisition of a connection. This will be the case if the pool has been closed.

Parameters:

• graph_name –
• readonly –
• timeout –
• force_reset – if true, the connection will be forcibly reset before being returned; if false, this will only occur if the connection is not already in a clean state

Returns:

a Bolt connection object

close()

Close all connections immediately.

This does not permanently disable the connection pool. Instead, it sets the maximum pool size to zero before shutting down all open connections, including those in use.

To reuse the pool, the maximum size will need to be set to a a value greater than zero before connections can once again be acquired.

To close gracefully, allowing work in progress to continue until connections are released, use the following sequence instead:

pool.max_size = 0 pool.prune()

This will force all future connection acquisitions to be rejected, and released connections will be closed instead of being returned to the pool.

in_use

The number of connections in this pool that are currently in use.

max_age

The maximum permitted age, in seconds, for connections to be retained in this pool.

max_size

The maximum permitted number of simultaneous connections that may be owned by this pool, both in-use and free.

classmethod open(profile=None, user_agent=None, init_size=None, max_size=None, max_age=None, on_bind=None, on_unbind=None)

Create a new connection pool, with an option to seed one or more initial connections.

Parameters:

• profile – a ConnectionProfile describing how to connect to the remote service for which this pool operates
• user_agent – a user agent string identifying the client software
• init_size – the number of seed connections to open
• max_size – the maximum permitted number of simultaneous connections that may be owned by this pool, both in-use and free
• max_age – the maximum permitted age, in seconds, for connections to be retained in this pool
• on_bind – callback to execute when binding a transaction to a connection; this must accept two arguments representing the transaction and the connection
• on_unbind – callback to execute when unbinding a transaction from a connection; this must accept an argument representing the transaction

profile

The connection profile for which this pool operates.

prune()

Close all free connections.

release(cx, force_reset=False)

Release a Bolt connection, putting it back into the pool if the connection is healthy and the pool is not already at capacity.

Parameters:

• cx – the connection to release
• force_reset – if true, the connection will be forcibly reset before being released back into the pool; if false, this will only occur if the connection is not already in a clean state

Raises:

ValueError – if the connection does not belong to this pool

size

The total number of connections (both in-use and free) currently owned by this connection pool.

user_agent

The user agent for connections in this pool.

class py2neo.client.Connector(profile, user_agent, init_size, max_size, max_age)

A connection pool abstraction that uses an appropriate connection pool implementation and is coupled with a transaction manager.

acquire(graph_name=None, readonly=False, timeout=None, force_reset=False)

Acquire a connection from a pool owned by this connector.

In the simplest case, this will return an existing open connection, if one is free. If not, and the pool is not full, a new connection will be created. If the pool is full and no free connections are available, this will block until a connection is released, or until the acquire call is cancelled.

This method will return None if and only if the maximum size of the pool is set to zero. In this special case, no amount of waiting would result in the acquisition of a connection. This will be the case if the pool has been closed.

Parameters:

• graph_name –
• readonly – if true, a readonly server will be selected, if available; if no such servers are available, a regular server will be used instead
• timeout –
• force_reset – if true, the connection will be forcibly reset before being returned; if false, this will only occur if the connection is not already in a clean state

Returns:

a Bolt connection object

add_pool(profile, reader=False, runner=False, router=False)

Add a connection pool for a given connection profile.

auto_run(graph_name, cypher, parameters=None, hydrant=None, readonly=False)

Run a Cypher query within a new auto-commit transaction.

begin(graph_name, readonly=False)

Begin a new explicit transaction.

close()

Close all connections immediately.

This does not permanently disable the connection pool. Instead, it sets the maximum pool size to zero before shutting down all open connections, including those in use.

To reuse the pool, the maximum size will need to be set to a a value greater than zero before connections can once again be acquired.

To close gracefully, allowing work in progress to continue until connections are released, use the following sequence instead:

pool.max_size = 0 pool.prune()

This will force all future connection acquisitions to be rejected, and released connections will be closed instead of being returned to the pool.

commit(tx)

Commit a transaction.

Parameters:

tx – the transaction to commit

Returns:

a Bookmark representing the point in transactional history immediately after this transaction

Raises:

• ValueError – if the transaction is not valid to be committed
• BrokenTransactionError – if the transaction fails to commit

default_graph_name()

Fetch the default graph database name for the service.

graph_names()

Fetch a list of available graph database names.

in_use

A dictionary mapping each profile to the number of connections currently pooled for that profile that are currently in use.

classmethod open(profile, user_agent=None, init_size=None, max_size=None, max_age=None)

Create a new connector, opening a pool for the initial connection profile.

Parameters:

• profile – a ConnectionProfile describing how to connect to the remote graph database service
• user_agent – a user agent string identifying the client software
• init_size – the number of seed connections to open in the initial pool
• max_size – the maximum permitted number of simultaneous connections that may be owned by pools held by this connector, both in-use and free
• max_age – the maximum permitted age, in seconds, for connections to be retained within pools held by this connector

profile

The initial connection profile for this connector.

prune()

Close all free connections.

release(cx, force_reset=False)

Release a connection back into the pool.

rollback(tx)

Roll back a transaction.

Parameters:

tx – the transaction to rollback

Returns:

a Bookmark representing the point in transactional history immediately after this transaction

Raises:

• ValueError – if the transaction is not valid to be rolled back
• BrokenTransactionError – if the transaction fails to rollback

run_in_tx(tx, cypher, parameters=None, hydrant=None)

Run a Cypher query within an open explicit transaction.

user_agent

The user agent for connections attached to this connector.

exception py2neo.client.Failure(message, code)

class py2neo.client.Result(graph_name)

Abstract base class representing the result of a Cypher query.

buffer()

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

Raises:BrokenTransactionError 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:BrokenTransactionError 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:BrokenTransactionError 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:BrokenTransactionError 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

exception py2neo.client.TransactionError

Raised when an error occurs in relation to a transaction.