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.

auto_run(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:

begin(graph_name, readonly=False)

Begin a transaction. This method may invoke network activity.

Parameters:

• graph_name –
• readonly –

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

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

Open a 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

Raises:

ValueError if the profile references an unsupported scheme

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

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

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, on_broken=None)

A pool of connections targeting a single Neo4j server.

acquire(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 raise ConnectionUnavailable if the maximum size of the pool is set to zero, if the pool is full and all connections are in use, or if a new connection attempt is made which fails.

Parameters: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 Raises:ConnectionUnavailable if no connection can be acquired

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, on_broken=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
• on_broken – callback to execute when a connection in the pool is broken; this must accept an argument representing the connection profile and a second with an error message

Raises:

ConnectionUnavailable if connections cannot be successfully made to seed the pool

Raises:

ValueError if the profile references an unsupported scheme

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.

exception py2neo.client.ConnectionUnavailable

Raised when a connection cannot be established.

class py2neo.client.Connector(profile, user_agent=None, init_size=None, max_size=None, max_age=None, routing=False)

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

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
• routing – flag to switch on client-side routing across a cluster

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 – the graph database name for which a connection must be acquired
• 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 – for how long (in seconds) to continue to attempt to acquire a connection
• 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 Connection object

Raises:

ConnectionUnavailable if a connection could not be acquired within the time limit

add_pools(*profiles)

Adds connection pools for one or more connection profiles. Pools that already exist will be skipped.

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

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.

get_pools(graph_name=None, readonly=False)

Obtain a list of connection pools for a particular graph database and read/write mode.

If, for any reason, the routing table is not valid, a RoutingTable.Invalid exception will be raised. Possible reasons are: - No routing table exists for the given graph database - The routing table has expired - No appropriate readonly or read-write servers are listed

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.

profile

The initial connection profile for this connector.

prune(profile)

Close all free connections for the given profile.

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.

records()

Iterate through the remaining records, yielding each one in turn. This method may carry out network activity.

Returns:record iterator 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.