Skip to content

Commit 14bf176

Browse files
committed
Introduce API Redesign
1 parent a41f827 commit 14bf176

File tree

5 files changed

+107
-2
lines changed

5 files changed

+107
-2
lines changed

neo4j/_sync/driver.py

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -392,6 +392,23 @@ def supports_multi_db(self):
392392
session._connect(READ_ACCESS)
393393
return session._connection.supports_multiple_databases
394394

395+
def query(self, query, parameters=None, **kwargs):
396+
"""
397+
:param query: cypher query
398+
:type query: str, neo4j.Query
399+
:param parameters: dictionary of parameters
400+
:type parameters: dict
401+
:param kwargs: additional keyword parameters
402+
:returns: a new :class:`neo4j.QueryResult` object
403+
:rtype: QueryResult
404+
"""
405+
session_kwargs = {}
406+
if "database" in kwargs:
407+
session_kwargs["database"] = kwargs.pop("database")
408+
409+
with self.session(**session_kwargs) as session:
410+
return session.query(query, parameters, **kwargs)
411+
395412

396413
class BoltDriver(_Direct, Driver):
397414
""":class:`.BoltDriver` is instantiated for ``bolt`` URIs and

neo4j/_sync/work/result.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -707,3 +707,13 @@ def closed(self):
707707
.. versionadded:: 5.0
708708
"""
709709
return self._out_of_scope or self._consumed
710+
711+
712+
class QueryResult:
713+
"""The result of Cypher query execution. Instances
714+
of this class are typically constructed and returned by
715+
:meth:`.Session.query` and :meth:`.Transaction.query`.
716+
"""
717+
def __init__(self, summary, records):
718+
self.summary = summary
719+
self.records = records

neo4j/_sync/work/session.py

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@
3030
Bookmarks,
3131
READ_ACCESS,
3232
WRITE_ACCESS,
33+
CLUSTER_AUTO_ACCESS,
34+
CLUSTER_READERS_ACCESS,
35+
CLUSTER_WRITERS_ACCESS
3336
)
3437
from ...exceptions import (
3538
ClientError,
@@ -40,7 +43,7 @@
4043
TransactionError,
4144
)
4245
from ...work import Query
43-
from .result import Result
46+
from .result import QueryResult, Result
4447
from .transaction import (
4548
ManagedTransaction,
4649
Transaction,
@@ -239,6 +242,42 @@ def run(self, query, parameters=None, **kwargs):
239242

240243
return self._auto_result
241244

245+
def query(self, query, parameters=None, **kwargs):
246+
"""
247+
:param query: cypher query
248+
:type query: str, neo4j.Query
249+
:param parameters: dictionary of parameters
250+
:type parameters: dict
251+
:param kwargs: additional keyword parameters
252+
:returns: a new :class:`neo4j.QueryResult` object
253+
:rtype: QueryResult
254+
"""
255+
cluster_member_access = kwargs.pop(
256+
"cluster_member_access", CLUSTER_AUTO_ACCESS)
257+
skip_records = kwargs.pop("skip_records", False)
258+
tx_kargs = {}
259+
260+
if "timeout" in kwargs:
261+
tx_kargs["timeout"] = kwargs.pop("timeout")
262+
263+
if "metadata" in kwargs:
264+
tx_kargs["metadata"] = kwargs.pop("metadata")
265+
266+
def job(tx):
267+
if skip_records:
268+
summary = tx.run(query, parameters, **kwargs)
269+
return QueryResult(summary, [])
270+
return tx.query(query, parameters, **kwargs)
271+
272+
# This logic will be moved to the Session.execute method
273+
if cluster_member_access == CLUSTER_READERS_ACCESS:
274+
return self.read_transaction(job, **tx_kargs)
275+
276+
if cluster_member_access == CLUSTER_WRITERS_ACCESS:
277+
return self.write_transaction(job, **tx_kargs)
278+
279+
raise ValueError("Invalid cluster_member_access")
280+
242281
@deprecated(
243282
"`last_bookmark` has been deprecated in favor of `last_bookmarks`. "
244283
"This method can lead to unexpected behaviour."

neo4j/_sync/work/transaction.py

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
from ...exceptions import TransactionError
2323
from ...work import Query
2424
from ..io import ConnectionErrorHandler
25-
from .result import Result
25+
from .result import QueryResult, Result
2626

2727

2828
__all__ = ("Transaction", "ManagedTransaction")
@@ -131,6 +131,41 @@ def run(self, query, parameters=None, **kwparameters):
131131

132132
return result
133133

134+
def query(self, query, parameters=None, **kwparameters):
135+
""" Run a Cypher query within the context of this transaction.
136+
137+
Cypher is typically expressed as a query template plus a
138+
set of named parameters. In Python, parameters may be expressed
139+
through a dictionary of parameters, through individual parameter
140+
arguments, or as a mixture of both. For example, the `run`
141+
queries below are all equivalent::
142+
143+
>>> query = "CREATE (a:Person { name: $name, age: $age })"
144+
>>> query_result = tx.run(query, {"name": "Alice", "age": 33})
145+
>>> query_result = tx.run(query, {"name": "Alice"}, age=33)
146+
>>> query_result = tx.run(query, name="Alice", age=33)
147+
148+
Parameter values can be of any type supported by the Neo4j type
149+
system. In Python, this includes :class:`bool`, :class:`int`,
150+
:class:`str`, :class:`list` and :class:`dict`. Note however that
151+
:class:`list` properties must be homogenous.
152+
153+
:param query: cypher query
154+
:type query: str
155+
:param parameters: dictionary of parameters
156+
:type parameters: dict
157+
:param kwparameters: additional keyword parameters
158+
159+
:returns: a new :class:`neo4j.QueryResult` object
160+
:rtype: :class:`neo4j.QueryResult`
161+
162+
:raise TransactionError: if the transaction is already closed
163+
"""
164+
result = self.run(query, parameters, **kwparameters)
165+
records = list(result)
166+
summary = result.consume()
167+
return QueryResult(summary, records)
168+
134169
def _commit(self):
135170
"""Mark this transaction as successful and close in order to trigger a COMMIT.
136171

neo4j/api.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@
3131
READ_ACCESS = "READ"
3232
WRITE_ACCESS = "WRITE"
3333

34+
CLUSTER_AUTO_ACCESS = "AUTOMATIC"
35+
CLUSTER_READERS_ACCESS = "READERS"
36+
CLUSTER_WRITERS_ACCESS = "WRITERS"
37+
3438
DRIVER_BOLT = "DRIVER_BOLT"
3539
DRIVER_NEO4j = "DRIVER_NEO4J"
3640

0 commit comments

Comments
 (0)