py2neo.client – Low-level client connections for Neo4j

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

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

property age

The age of this connection in seconds.

begin(graph_name, readonly=False, after=None, metadata=None, timeout=None)[source]

Begin a transaction.

Parameters
  • graph_name

  • readonly

  • after

  • metadata

  • timeout

Returns

new Transaction object

Raises

TransactionError – if a new transaction cannot be created

property broken

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

property closed

True if the connection has been closed by the client.

release()[source]

Signal that this connection is no longer in use.

supports_multi()[source]

Detect whether or not this connection supports multi-database.

sync(result)[source]

Perform network synchronisation required to make available a given result.

class py2neo.client.ConnectionPool[source]

Abstract connection pool interface.

abstract acquire(graph_name=None, readonly=False, timeout=None, force_reset=False)[source]

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 – 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

abstract close()[source]

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.

abstract property in_use

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

abstract property max_age

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

abstract property max_size

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

abstract property profile

The initial connection profile for connections in this pool.

abstract prune()[source]

Close all free connections in this pool.

abstract release(cx, force_reset=False)[source]

Release a connection back into the pool.

abstract property size

The total number of connections in this pool, both in-use and free.

abstract property user_agent

The user agent for connections in this pool.

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

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)[source]

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 – 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

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

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

begin(graph_name, readonly=False, after=None, metadata=None, timeout=None)[source]

Begin a new explicit transaction.

close()[source]

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)[source]

Commit a transaction.

Parameters

tx – the transaction to commit

Returns

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

Raises

TypeError – if the transaction is invalid

default_graph_name()[source]

Fetch the default graph database name for the service.

graph_names()[source]

Fetch a list of available graph database names.

property in_use

The number of connections attached to this connector that are currently in use.

property max_age

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

property max_size

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

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

Create a new connector.

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

property profile

The initial connection profile for this connector.

prune()[source]

Close all free connections.

release(cx, force_reset=False)[source]

Release a connection back into the pool.

rollback(tx)[source]

Roll back a transaction.

run_in_tx(tx, cypher, parameters=None, hydrant=None)[source]

Run a Cypher query within an open explicit transaction.

property size

The total number of connections (both in-use and free) currently attached to this connector.

property user_agent

The user agent for connections attached to this connector.

class py2neo.client.DirectConnectionPool(profile, user_agent, max_size, max_age, on_bind, on_unbind)[source]

A connection pool targeting a single Neo4j server.

acquire(graph_name=None, readonly=False, timeout=None, force_reset=False)[source]

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()[source]

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.

property in_use

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

property max_age

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

property 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)[source]

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

property profile

The connection profile for which this pool operates.

prune()[source]

Close all free connections.

release(cx, force_reset=False)[source]

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

property size

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

property user_agent

The user agent for connections in this pool.

exception py2neo.client.Failure(message, code)[source]
class py2neo.client.RoutingConnectionPool(connector, profile, user_agent, init_size, max_size, max_age, on_bind, on_unbind)[source]

A connection pool targeting a system of interconnected machines bound by a routing table.

acquire(graph_name=None, readonly=False, timeout=None, force_reset=False)[source]

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 – 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

close()[source]

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.

property in_use

The number of connections attached to this connector that are currently in use.

property max_age

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

property max_size

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

property profile

The initial connection profile for this connector.

prune()[source]

Close all free connections.

release(cx, force_reset=False)[source]

Release a connection back into the pool.

property size

The total number of connections (both in-use and free) currently attached to this connector.

property user_agent

The user agent for connections attached to this connector.