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
andHTTP
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, readonly=False)[source]¶ Begin a transaction. This method may invoke network activity.
Parameters: - graph_name –
- readonly –
Returns: new
Transaction
objectRaises: Failure – 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)[source]¶ 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
- ValueError – if the supplied
-
get_cluster_overview
(tx=None)[source]¶ Fetch an overview of the cluster of which the server is a member. If the server is not part of a cluster, a
TypeError
is raised.Parameters: tx – transaction in which this call should be carried out, if any Returns: dictionary of cluster membership, keyed by unique server ID Raises: TypeError
if the server is not a member of a cluster
-
get_config
(tx=None)[source]¶ Fetch a dictionary of configuration for the server to which this connection is established.
Parameters: tx – transaction in which this call should be carried out, if any Returns: dictionary of name-value pairs for each setting
-
get_connections
(tx=None)[source]¶ Fetch a list of connections to the server to which this connection is established.
This method calls the dbms.listConnections procedure, which is available with the following versions of Neo4j:
- Community Edition - version 4.2 and above
- Enterprise Edition - all versions
Returns: list of ConnectionRecord
objectsRaises: TypeError – if the dbms.listConnections procedure is not supported by the underlying Neo4j installation
-
get_management_data
(tx=None)[source]¶ Fetch a dictionary of management data for the server to which this connection is established. This method calls the dbms.queryJmx procedure.
The structure and format of the data returned may vary depending on the underlying version and edition of Neo4j.
-
get_queries
(tx=None)[source]¶ Fetch a list of queries currently active on the server to which this connection is established.
This method calls the dbms.listQueries procedure, which is available with the following versions of Neo4j:
- Community Edition - version 4.2 and above
- Enterprise Edition - all versions
Returns: list of QueryRecord
objectsRaises: TypeError – if the dbms.listQueries procedure is not supported by the underlying Neo4j installation
-
get_transactions
(tx=None)[source]¶ Fetch a list of transactions currently active on the server to which this connection is established.
This method calls the dbms.listTransactions procedure, which is available with the following versions of Neo4j:
- Community Edition - version 4.2 and above
- Enterprise Edition - all versions
Returns: list of TransactionRecord
objectsRaises: TypeError – if the dbms.listTransactions procedure is not supported by the underlying Neo4j installation
-
neo4j_edition
¶ The edition of Neo4j to which this connection is established.
-
neo4j_version
¶ The version of Neo4j to which this connection is established.
-
classmethod
open
(profile=None, user_agent=None, on_bind=None, on_unbind=None, on_release=None, on_broken=None)[source]¶ 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 objectRaises: ConnectionUnavailable
if a connection cannot be openedRaises: ValueError if the profile references an unsupported scheme
- profile –
-
rollback
(tx)[source]¶ 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
- ValueError – if the supplied
-
route
(graph_name=None, context=None)[source]¶ 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.
ConnectionPool
(profile, user_agent=None, max_size=None, max_age=None, on_bind=None, on_unbind=None, on_broken=None)[source]¶ A pool of connections targeting a single Neo4j server.
-
acquire
(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 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
()[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.
-
connect
()[source]¶ Open a new connection, adding it to a list of opened connections in order to collect statistics. This method also collects stats from closed or broken connections into a pool-wide running total.
-
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)[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
- 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 poolRaises: ValueError if the profile references an unsupported scheme
- profile – a
-
profile
¶ The connection profile for which this pool operates.
-
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
-
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.
ConnectionRecord
(cxid, since, client_address, server_profile, user_agent)¶ -
client_address
¶ Alias for field number 2
-
cxid
¶ Alias for field number 0
-
server_profile
¶ Alias for field number 3
-
since
¶ Alias for field number 1
-
user_agent
¶ Alias for field number 4
-
Raised when a connection cannot be acquired.
-
class
py2neo.client.
Connector
(profile, user_agent=None, init_size=None, max_size=None, max_age=None, routing=False)[source]¶ 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
-
add_pools
(*profiles)[source]¶ Adds connection pools for one or more connection profiles. Pools that already exist will be skipped.
-
begin
(graph_name, readonly=False)[source]¶ Begin a new explicit transaction.
Parameters: - graph_name –
- readonly –
Returns: new
Transaction
objectRaises: - ConnectionUnavailable – if a begin attempt cannot be made
- ConnectionBroken – if a begin attempt is made, but fails due to disconnection
- Failure – if the server signals a failure condition
-
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: dictionary of transaction summary information
Raises: - ValueError – if the transaction is not valid to be committed
- ConnectionUnavailable – if a commit attempt cannot be made
- ConnectionBroken – if a commit attempt is made, but fails due to disconnection
- Failure – if the server signals a failure condition
-
get_pools
(graph_name=None, readonly=False)[source]¶ 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
-
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.
-
rollback
(tx)[source]¶ Roll back a transaction.
Parameters: tx – the transaction to rollback
Returns: dictionary of transaction summary information
Raises: - ValueError – if the transaction is not valid to be rolled back
- ConnectionUnavailable – if a rollback attempt cannot be made
- ConnectionBroken – if a rollback attempt is made, but fails due to disconnection
- Failure – if the server signals a failure condition
-
run_prog
(graph_name, cypher, parameters=None, readonly=False)[source]¶ Run a Cypher query within a new auto-commit transaction.
Parameters: - graph_name –
- cypher –
- parameters –
- readonly –
Returns: Result
objectRaises: - ConnectionUnavailable – if an attempt to run cannot be made
- ConnectionBroken – if an attempt to run is made, but fails due to disconnection
- Failure – if the server signals a failure condition
-
run_query
(tx, cypher, parameters=None)[source]¶ Run a Cypher query within an open explicit transaction.
Parameters: - tx –
- cypher –
- parameters –
Returns: Result
objectRaises: - ConnectionUnavailable – if an attempt to run cannot be made
- ConnectionBroken – if an attempt to run is made, but fails due to disconnection
- Failure – if the server signals a failure condition
-
user_agent
¶ The user agent for connections attached to this connector.
- profile – a
-
exception
py2neo.client.
ProtocolError
[source]¶ Raised when a protocol violation or other unrecoverable protocol error occurs. These errors cannot be recovered from automatically, and may result from a bug in the driver or server software.
-
class
py2neo.client.
QueryRecord
(qid, since, cxid, client_address, server_profile, metadata, database, query, parameters, planner, runtime, indexes, status, stats)¶ -
client_address
¶ Alias for field number 3
-
cxid
¶ Alias for field number 2
-
database
¶ Alias for field number 6
-
indexes
¶ Alias for field number 11
-
metadata
¶ Alias for field number 5
-
parameters
¶ Alias for field number 8
-
planner
¶ Alias for field number 9
-
qid
¶ Alias for field number 0
-
query
¶ Alias for field number 7
-
runtime
¶ Alias for field number 10
-
server_profile
¶ Alias for field number 4
-
since
¶ Alias for field number 1
-
stats
¶ Alias for field number 13
-
status
¶ Alias for field number 12
-
-
class
py2neo.client.
Result
(graph_name)[source]¶ Abstract base class representing the result of a Cypher query.
-
buffer
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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)[source]¶ 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
()[source]¶ 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.
-
records
()[source]¶ Iterate through the remaining records, yielding each one in turn. This method may carry out network activity.
Returns: record iterator Raises: ConnectionBroken
if the transaction is broken by an unexpected network event.
-
-
class
py2neo.client.
TransactionRecord
(txid, since, cxid, client_address, server_profile, metadata, database, current_qid, current_query, status, stats)¶ -
client_address
¶ Alias for field number 3
-
current_qid
¶ Alias for field number 7
-
current_query
¶ Alias for field number 8
-
cxid
¶ Alias for field number 2
-
database
¶ Alias for field number 6
-
metadata
¶ Alias for field number 5
-
server_profile
¶ Alias for field number 4
-
since
¶ Alias for field number 1
-
stats
¶ Alias for field number 10
-
status
¶ Alias for field number 9
-
txid
¶ Alias for field number 0
-