pyneoinstance 1.1.0__tar.gz → 1.1.2__tar.gz

{pyneoinstance-1.1.0/pyneoinstance.egg-info → pyneoinstance-1.1.2}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: pyneoinstance
-Version: 1.1.0
+Version: 1.1.2
 Summary: Handle Neo4j read and write transactions
-Author-email: Jose A Alvarado-Guzma <jalvarado-guzman@neo4j.com>
+Author-email: "Jose A. Alvarado-Guzman" <jose.alvarado-guzman@neo4j.com>
 License: GNU GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007
         
@@ -685,17 +685,22 @@ Classifier: Development Status :: 4 - Beta
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: neo4j>=5.0.0
+Requires-Dist: pandas
+Requires-Dist: PyYAML
 
 # PyNeoInstance Package
 
 ## What is it?
 
-Is a Python package that provides a user friendly API for submitting Cypher queries to Neo4j.
+PyNeoInstance is a Python package that provides a user friendly API for submitting Cypher queries to Neo4j.
 It supports the following features:
 
-- __Read query__: Submit a Cypher query and get the result of it as a Pandas DataFrame.
-- __Write query__: Sumbmit a Cypher query to update an existing database.
-- __Write query with data__: Update a database based on a Pandas DataFrame and one or more Cypher queries.
+- __Read query__: Submit a Cypher read query, with or without parameters, and get a Pandas Data Frame with the results.
+- __Write query__: Submit a write Cypher query, with or without parameters, to update an existing database.
+- __Write queries__: Submit a list of Cypher queries to update an existing database.
+- __Write query with data__: Update a database based on a Pandas Data Frame and a Cypher query.
+- __Write queries with data__: Update a database based on a Pandas Data Frame and a list of Cypher queries.
 
 ## How to install it?
 
@@ -707,16 +712,16 @@ pip install pyneoinstance
 
 ### Instantiating the Neo4jInstance class
 
-In order to use this package you first need to import the Neo4jInstance class.
+In order to use this package, you first need to import the Neo4jInstance class.
 
 ```python
-from pyneoingest import Neo4jInstance
+from pyneoinstance import Neo4jInstance
 ```
 
 Once imported, you need to instantiate this class by providing the following arguments:
 
 - _uri_: The Neo4j instance unique resource identifier.
-- _user_: The user name use to authenticate. 
+- _user_: The user name used to authenticate. 
 - _password_: The user name password.
 
 ```python
@@ -737,7 +742,7 @@ user = os.environ['NEO4J_USER']
 password = os.environ['NEO4J_PASSWORD']
 graph = Neo4jInstance(uri,user,password)
 ```
-Another alternative is to create a YAML configutation file to store this infromation.
+Another alternative is to create a YAML configuration file to store this information.
 
 ```yaml
 # configuration.yaml
@@ -745,9 +750,10 @@ db_info:
   uri: neo4j_uri
   user: neo4j_user
   password: user_password
+  database: neo4j
 ```
 
-This YAML file can then be loaded in Python and these information can be retrieve.
+This YAML file can then be loaded in Python and this information can be retrieve.
 
 ```python
 from pyneoinstance import load_yaml_file
@@ -758,7 +764,7 @@ graph = Neo4jInstance(db_info['uri'], db_info['user'], db_info['password'])
 ```
 ### Submitting a Cypher read query
 
-Once you instantiated the Neo4jInstance class, you can submit a Cypher read query by using the class method execute\_read\_query. This method receive the Cypher query string as an argument and optionally the name of the database on which the query should be executed. If the database name is not provided the query will be execute using your default Neo4j database. The results of the query is return as a a Pandas DataFrame. To avoid unwanted column names in the resulting DataFrame, always provide aliases for all return properties.
+Once you instantiated the Neo4jInstance class, you can submit a Cypher read query by using the class method execute\_read\_query. This method receives the Cypher query string as an argument and optionally the name of the database on which the query should be executed. If the database name is not provided the query will be execute using your default Neo4j database. The results of the query are return as a Pandas Data Frame. To avoid unwanted column names in the resulting Data Frame, always provide aliases for all returned properties.
 
 ```python
 query = """
@@ -768,35 +774,56 @@ query = """
            m.tagline AS tagline;
 """
 
-data = graph.execute_read_query(query)
+data = graph.execute_read_query(query,db_info['database'])
 ```
+
+### Submitting a Cypher read query with parameters
+
+The method execute\_read\_query can optionally received a Python Dictionary with the parameters required as part of you Cypher query.
+
+```python
+query = """
+    MATCH (m:Movie {title: $movie_title})
+    RETURN m.tile AS title,
+           m.released AS releasedYear,
+           m.tagline AS tagline;
+"""
+
+data = graph.execute_read_query(query, db_info['database'], db_info['database'], parameters={'movie_title':'The Matrix'})
+```
+
 ### Submitting a Cypher write query
 
-We submit a Cypher write query using the method execute\_write\_query. The signature of this method is identical to the execute\_read\_query. This method returns a dictionary containing the updates made to the database.
+You can submit a Cypher write query using the method execute_write_query. The signature of this method is identical to the execute_read_query. This method returns a dictionary containing the updates made to the database. As with read queries you can also specify a Python dictionary containing Cypher parameters.
 
 ```python
 query = """
-    MERGE(m:Movie {title:'Wakanda Forever'})
+    MERGE(m:Movie {title:$movie_title})
     ON CREATE SET
-        m.release=2022,
-        m.tagline = 'Wakanda Forever! Long Live Wakanda! For Honor, For Legacy, For Wakanda!'
+        m.release = $year,
+        m.tagline = $tagline
 """
 
-results = graph.execute_write_query(query)
+results = graph.execute_write_query(query, db_info['database'],
+  parameters={
+    'movie_title':'Wakanda Forever',
+    'year'=2022,
+    tagline=''Wakanda Forever! Long Live Wakanda! For Honor, For Legacy, For Wakanda!''
+  })
 ```
 
 ### Updating a database with data in a DataFrame: Sequentially
 
-We can update a Neo4j database with data contained in a Pandas DataFrame using the methods execute\_write\_query\_with\_data or execute\_write\_queries\_with\_data. These methos return a dictionary containing the numbers and types of updates made to the database. Besides taking the query or list of queries as an argument, we can pass to these methods the following arguments:
+We can update a Neo4j database with data contained in a Pandas Data Frame using the methods execute\_write\_query\_with\_data or execute\_write\_queries\_with\_data. These methods return a dictionary containing the numbers and types of updates made to the database. Besides taking the query or list of queries as an argument, we can pass to these methods the following arguments:
 
-- _data_: Pandas DataFrame containing data to process.
-- _database_: Optional, database on which to execute the quieries.
-- _partitions_: Optional, number of partitions use to break the DataFrame in smaller chucks.
-- _parallel_: Wheather to execute the query using multiple Python process.
+- _data_: Pandas Data Frame containing data to process.
+- _database_: Optional, database on which to execute the queries.
+- _partitions_: Optional, number of partitions use to break the Data Frame in smaller chucks.
+- _parallel_: Whether to execute the query using multiple Python process.
 - _workers_: The number of processes to spawn to execute the queries in parallel.
 - _parameters_: Extra arguments containing optional cypher parameters.
 
-To illustrates how to use this methods lets imagine we have a csv file that looks like this:
+To illustrates how to use these methods lets imagine we have a csv file that looks like this:
 
 ```python
 # people.csv
@@ -812,11 +839,11 @@ personId,name,birthYear,deathYear
 3482,Chus Lampreave,1930,
 ```
 
-We want to update our database by loading this data as a node with the label Person containing the properties id, name, birthYear and deathYear. To accomplish this, we need to performe the following steps:
+We want to update our database by loading this data as a node with the label Person containing the properties id, name, birthYear and deathYear. To accomplish this, we need to performed the following steps:
 
-1. Load the csv to Python as a DataFrame.
-2. Develop the Cypher query that is going to be use to load the DataFrame into Neo4j.
-3. Call the execute\_write\_query\_with\_data of an existing instance of the Neo4jInstance class passing the DataFrame, Cypher query and any other optinal arguments to this method. 
+1. Load the csv to Python as a Data Frame.
+2. Develop the Cypher query that is going to be use to load the Data Frame into Neo4j.
+3. Call the execute\_write\_query\_with\_data of an existing instance of the Neo4jInstance class passing the Data Frame, Cypher query and any other optional arguments to this method. 
 
 ```python
 import pandas as pd
@@ -834,10 +861,10 @@ person_load_query = """
           p.deathYear = toInteger(row.deathYear)
 """
 
-person_load_result = graph.execute_write_query_with_data(person_data, person_load_query)
+person_load_result = graph.execute_write_query_with_data(person_load_query, person_data, db_info['database'])
 ```
 
-Is not a good practice to store your Cypher queries as strings within your Python modules. To solve this we can extend our YAML configuration file to store all our Cypher queries.
+It is not a good practice to store your Cypher queries as strings within your Python modules. To solve this, we can extend our YAML configuration file to store all our Cypher queries.
 
 ```yaml
 # configuration.yaml
@@ -845,9 +872,10 @@ db_info:
   uri: neo4j_uri
   user: neo4j_user
   password: user_password
+  database: neo4j
 loading_queries:
   nodes:
-    person: |
+    Person: |
       WITH $rows AS rows
       UNWIND rows AS row
       MERGE(p:Person {id:row.personId})
@@ -867,28 +895,33 @@ person_data = pd.read_csv('people.csv')
 
 node_load_queries = config['loading_queries']['nodes']
 
-person_load_result = graph.execute_write_query_with_data(person_data, node_load_queries['person'])
+person_load_result = graph.execute_write_query_with_data(node_load_queries['Person'], person_data, db_info['database'])
 ```
 
-If the number of rows in your DataFrame is 100K or more it is reccomended to break the DataFrame in smaller chunks so that they can be process in different transactions. This will avoid running out of heap error. To do this, just indicate in the _partitions_ argument how many partitions would you like to break this DataFrame into. This partitions will be loaded in different sequential transactions unless you specified loading them in parallel by setting the _parallel_ argument to true. We will discuss this process in the next section.
+If the number of rows in your Data Frame is 100K or more it is recommended to break the Data Frame in smaller chunks so that they can be process in different transactions. This will avoid running out of heap error. To do this, just indicate in the _partitions_ argument how many partitions would you like to break this Data Frame into. These partitions will be loaded in different sequential transactions unless you specified loading them in parallel by setting the _parallel_ argument to true. We will discuss this process in the next section.
 
 ```python
 person_load_result = graph.execute_write_query_with_data(
-    person_data,
     node_load_queries['person'],
+    person_data,
+    db_info['database'],
     partitions = 5
     )
 ```
-## Updating a database with data in a DataFrame: Parallel  
+## Updating a database with data in a Data Frame: Parallel  
 
-To load the data in the DataFrame in parallel, we need to partition the DataFrame by incrementing the _partitions_ argument and set the _parallel_ argument to true. By default this will use all the available virtual CPUs in the machine. If you need to use less, you can specified how many to use by setting the _workers_ argument.
+To load the data in the Data Frame in parallel, we need to partition the Data Frame by incrementing the _partitions_ argument and set the _parallel_ argument to true. By default, this will use all the available virtual CPUs in the machine. If you need to use less, you can specify how many to use by setting the _workers_ argument.
 
 ```python
 person_load_result = graph.execute_write_query_with_data(
-    person_data,
     node_load_queries['person'],
+    person_data,
     partitions = 5,
     parallel = True,
     workers = 5
     )
 ```
+
+## More detailed examples
+
+For more detailed examples please referred to this [article](https://medium.com/@a-gilmore/pyneoinstance-a-user-friendly-python-library-for-neo4j-dbefa3117bb2).

pyneoinstance-1.1.2/README.md

@@ -0,0 +1,236 @@
+# PyNeoInstance Package
+
+## What is it?
+
+PyNeoInstance is a Python package that provides a user friendly API for submitting Cypher queries to Neo4j.
+It supports the following features:
+
+- __Read query__: Submit a Cypher read query, with or without parameters, and get a Pandas Data Frame with the results.
+- __Write query__: Submit a write Cypher query, with or without parameters, to update an existing database.
+- __Write queries__: Submit a list of Cypher queries to update an existing database.
+- __Write query with data__: Update a database based on a Pandas Data Frame and a Cypher query.
+- __Write queries with data__: Update a database based on a Pandas Data Frame and a list of Cypher queries.
+
+## How to install it?
+
+```python
+pip install pyneoinstance
+```
+
+## How to use it?
+
+### Instantiating the Neo4jInstance class
+
+In order to use this package, you first need to import the Neo4jInstance class.
+
+```python
+from pyneoinstance import Neo4jInstance
+```
+
+Once imported, you need to instantiate this class by providing the following arguments:
+
+- _uri_: The Neo4j instance unique resource identifier.
+- _user_: The user name used to authenticate. 
+- _password_: The user name password.
+
+```python
+uri = 'bolt://localhost:7687'
+user = 'neo4j'
+password = 'password'
+
+graph = Neo4jInstance(uri, user, password)
+```
+
+Although the previous code is valid, it is not recommended to hard code your user credentials in your application. As an alternative you can store this information as part of your OS user environment variables and then retrieve them in Python.
+
+```python
+import os
+
+uri = os.environ['NEO4J_URI']
+user = os.environ['NEO4J_USER']
+password = os.environ['NEO4J_PASSWORD']
+graph = Neo4jInstance(uri,user,password)
+```
+Another alternative is to create a YAML configuration file to store this information.
+
+```yaml
+# configuration.yaml
+db_info:
+  uri: neo4j_uri
+  user: neo4j_user
+  password: user_password
+  database: neo4j
+```
+
+This YAML file can then be loaded in Python and this information can be retrieve.
+
+```python
+from pyneoinstance import load_yaml_file
+
+config = load_yaml_file(configuration.yaml)
+db_info = config['db_info']
+graph = Neo4jInstance(db_info['uri'], db_info['user'], db_info['password'])
+```
+### Submitting a Cypher read query
+
+Once you instantiated the Neo4jInstance class, you can submit a Cypher read query by using the class method execute\_read\_query. This method receives the Cypher query string as an argument and optionally the name of the database on which the query should be executed. If the database name is not provided the query will be execute using your default Neo4j database. The results of the query are return as a Pandas Data Frame. To avoid unwanted column names in the resulting Data Frame, always provide aliases for all returned properties.
+
+```python
+query = """
+    MATCH (m:Movie {title: "The Matrix"})
+    RETURN m.tile AS title,
+           m.released AS releasedYear,
+           m.tagline AS tagline;
+"""
+
+data = graph.execute_read_query(query,db_info['database'])
+```
+
+### Submitting a Cypher read query with parameters
+
+The method execute\_read\_query can optionally received a Python Dictionary with the parameters required as part of you Cypher query.
+
+```python
+query = """
+    MATCH (m:Movie {title: $movie_title})
+    RETURN m.tile AS title,
+           m.released AS releasedYear,
+           m.tagline AS tagline;
+"""
+
+data = graph.execute_read_query(query, db_info['database'], db_info['database'], parameters={'movie_title':'The Matrix'})
+```
+
+### Submitting a Cypher write query
+
+You can submit a Cypher write query using the method execute_write_query. The signature of this method is identical to the execute_read_query. This method returns a dictionary containing the updates made to the database. As with read queries you can also specify a Python dictionary containing Cypher parameters.
+
+```python
+query = """
+    MERGE(m:Movie {title:$movie_title})
+    ON CREATE SET
+        m.release = $year,
+        m.tagline = $tagline
+"""
+
+results = graph.execute_write_query(query, db_info['database'],
+  parameters={
+    'movie_title':'Wakanda Forever',
+    'year'=2022,
+    tagline=''Wakanda Forever! Long Live Wakanda! For Honor, For Legacy, For Wakanda!''
+  })
+```
+
+### Updating a database with data in a DataFrame: Sequentially
+
+We can update a Neo4j database with data contained in a Pandas Data Frame using the methods execute\_write\_query\_with\_data or execute\_write\_queries\_with\_data. These methods return a dictionary containing the numbers and types of updates made to the database. Besides taking the query or list of queries as an argument, we can pass to these methods the following arguments:
+
+- _data_: Pandas Data Frame containing data to process.
+- _database_: Optional, database on which to execute the queries.
+- _partitions_: Optional, number of partitions use to break the Data Frame in smaller chucks.
+- _parallel_: Whether to execute the query using multiple Python process.
+- _workers_: The number of processes to spawn to execute the queries in parallel.
+- _parameters_: Extra arguments containing optional cypher parameters.
+
+To illustrates how to use these methods lets imagine we have a csv file that looks like this:
+
+```python
+# people.csv
+personId,name,birthYear,deathYear
+23945,Gérard Pirès,1942,
+553509,Helen Reddy,1941,
+113934,Susan Flannery,1939,
+26706,David Rintoul,1948,
+237537,Rita Marley,1946,
+11502,Harry Davenport,1866,1949
+11792,George Dickerson,1933,
+7242,Temuera Morrison,1960,
+3482,Chus Lampreave,1930,
+```
+
+We want to update our database by loading this data as a node with the label Person containing the properties id, name, birthYear and deathYear. To accomplish this, we need to performed the following steps:
+
+1. Load the csv to Python as a Data Frame.
+2. Develop the Cypher query that is going to be use to load the Data Frame into Neo4j.
+3. Call the execute\_write\_query\_with\_data of an existing instance of the Neo4jInstance class passing the Data Frame, Cypher query and any other optional arguments to this method. 
+
+```python
+import pandas as pd
+
+person_data = pd.read_csv('people.csv')
+
+person_load_query = """
+  WITH $rows AS rows
+  UNWIND rows AS row
+  MERGE(p:Person {id:row.personId})
+    ON CREATE
+      SET p.id = row.personId,
+          p.name = row.name,
+          p.birthYear=toInteger(row.birthYear),
+          p.deathYear = toInteger(row.deathYear)
+"""
+
+person_load_result = graph.execute_write_query_with_data(person_load_query, person_data, db_info['database'])
+```
+
+It is not a good practice to store your Cypher queries as strings within your Python modules. To solve this, we can extend our YAML configuration file to store all our Cypher queries.
+
+```yaml
+# configuration.yaml
+db_info:
+  uri: neo4j_uri
+  user: neo4j_user
+  password: user_password
+  database: neo4j
+loading_queries:
+  nodes:
+    Person: |
+      WITH $rows AS rows
+      UNWIND rows AS row
+      MERGE(p:Person {id:row.personId})
+        ON CREATE
+          SET p.id = row.personId,
+              p.name = row.name,
+              p.birthYear=toInteger(row.birthYear),
+              p.deathYear = toInteger(row.deathYear)
+```
+
+Now that we added the loading query to our configuration file, lets re-write our Python script to get this query from the configuration file.
+
+```python
+import pandas as pd
+
+person_data = pd.read_csv('people.csv')
+
+node_load_queries = config['loading_queries']['nodes']
+
+person_load_result = graph.execute_write_query_with_data(node_load_queries['Person'], person_data, db_info['database'])
+```
+
+If the number of rows in your Data Frame is 100K or more it is recommended to break the Data Frame in smaller chunks so that they can be process in different transactions. This will avoid running out of heap error. To do this, just indicate in the _partitions_ argument how many partitions would you like to break this Data Frame into. These partitions will be loaded in different sequential transactions unless you specified loading them in parallel by setting the _parallel_ argument to true. We will discuss this process in the next section.
+
+```python
+person_load_result = graph.execute_write_query_with_data(
+    node_load_queries['person'],
+    person_data,
+    db_info['database'],
+    partitions = 5
+    )
+```
+## Updating a database with data in a Data Frame: Parallel  
+
+To load the data in the Data Frame in parallel, we need to partition the Data Frame by incrementing the _partitions_ argument and set the _parallel_ argument to true. By default, this will use all the available virtual CPUs in the machine. If you need to use less, you can specify how many to use by setting the _workers_ argument.
+
+```python
+person_load_result = graph.execute_write_query_with_data(
+    node_load_queries['person'],
+    person_data,
+    partitions = 5,
+    parallel = True,
+    workers = 5
+    )
+```
+
+## More detailed examples
+
+For more detailed examples please referred to this [article](https://medium.com/@a-gilmore/pyneoinstance-a-user-friendly-python-library-for-neo4j-dbefa3117bb2).

{pyneoinstance-1.1.0 → pyneoinstance-1.1.2}/pyneoinstance/__init__.py

@@ -1,4 +1,4 @@
 from .database.neo4jdbms import Neo4jInstance
 from .fileload.loadyaml import load_yaml_file
 
-__version__ = '1.1.0'
+__version__ = '1.1.2'

{pyneoinstance-1.1.0 → pyneoinstance-1.1.2}/pyneoinstance/database/neo4jdbms.py

@@ -20,10 +20,8 @@ from neo4j.exceptions import ServiceUnavailable
 from neo4j.exceptions import AuthError
 from neo4j.exceptions import ClientError
 from neo4j.exceptions import ConfigurationError
-from .context import get_logger
 
 def _get_driver(neo_info : Dict[str, str]):
-    logger = get_logger('pyneoinstance', logging.INFO)
     try:
         if neo_info['encrypted'] != '':
             driver = GraphDatabase.driver(
@@ -169,12 +167,11 @@ class Neo4jInstance:
         self.neo_info['password'] = password
         self.neo_info['encrypted'] = kwargs.get('encrypted') or ''
         self.__results = defaultdict(int)
-        self.__logger = get_logger('pyneoinstance', logging.INFO)
 
 
     def execute_read_query(self, query: str,
                            database: Optional[str] = None,
-                           **kwargs: Optional[Dict[str, Any]]
+                           parameters: Optional[Dict[str, Any]] = None
                           ) -> DataFrame:
         """Execute a read transaction to a specific database.
 
@@ -186,7 +183,7 @@ class Neo4jInstance:
             Name of the Neo4j database of which to execute the
             transaction. If not provided the default database is going to
             be use.
-        kwargs : Dict[str, Any], optional
+        parameters: Dict[str, Any], optional
             Extra arguments containing optional cypher parameters.
 
         Return
@@ -201,11 +198,15 @@ class Neo4jInstance:
         ClientError
             When there is a Cypher syntax error or datatype error.
     """
+        if parameters:
+            params = parameters
+        else:
+            params = {}
         with _get_driver(self.neo_info) as driver:
             with _get_session(driver, database) as session:
                 try:
                     result = session.execute_read(
-                        _read_transaction_function,query=query,**kwargs)
+                        _read_transaction_function,query=query,**params)
                 except ServiceUnavailable as exception:
                     raise ServiceUnavailable() from exception
                 except ClientError as exception:
@@ -214,7 +215,7 @@ class Neo4jInstance:
 
     def execute_write_queries(self, queries: List[str],
                             database: Optional[str] = None,
-                            **kwargs: Optional[Dict[str, Any]]
+                            parameters: Optional[Dict[str, Any]] = None
                            ) -> Dict[str, int]:
         """Execute a write query to a specific database.
 
@@ -225,7 +226,7 @@ class Neo4jInstance:
             database : str, optional
                 Name of the Neo4j database of which to execute the transaction.
                 If not provided the default database is going to be use.
-            kwargs : Dict[str, Any], optional
+            parameters : Dict[str, Any], optional
                 Extra arguments containing optional cypher parameters.
 
             Returns
@@ -241,20 +242,23 @@ class Neo4jInstance:
             ClientError
                 When their is a Cypher syntax error or datatype error.
         """
+        if parameters:
+            params = parameters
+        else:
+            params = {}
         results = defaultdict(int)
         with _get_driver(self.neo_info) as driver:
             with _get_session(driver, database) as session:
                 for query in queries:
-                    result = _execute_write(session, query, **kwargs)
+                    result = _execute_write(session, query, parameters=params)
                     for key, value in result.items():
                         if key != '_contains_updates':
                             results[key] += value
-                self.__logger.info(f'Loading stats: {dict(results)}')
         return dict(results)
 
     def execute_write_query(self, query: str,
                             database: Optional[str] = None,
-                            **kwargs: Optional[Dict['str',Any]]
+                            parameters: Optional[Dict['str',Any]] = None
                            ) -> Dict[str, Any]:
         """Execute a write query to a specific database.
 
@@ -265,7 +269,7 @@ class Neo4jInstance:
             database : str, optional
                 Name of the Neo4j database of which to execute the transaction.
                 If not provided the default database is going to be use.
-            kwargs : Dict[str, Any], optional
+            parameters : Dict[str, Any], optional
                 Extra arguments containing optional cypher parameters.
 
             Returns
@@ -281,7 +285,7 @@ class Neo4jInstance:
             ClientError
                 When their is a Cypher syntax error or datatype error.
         """
-        result = self.execute_write_queries([query], database, **kwargs)
+        result = self.execute_write_queries([query], database, parameters)
         return  result
 
     def execute_write_queries_with_data(self, queries: List[str], data: DataFrame,
@@ -364,7 +368,6 @@ class Neo4jInstance:
                     self.__results[key] += value
         results = dict(self.__results.copy())
         self.__results.clear()
-        self.__logger.info(f'Loading stats: {results}')
         return results
 
     def execute_write_query_with_data(self,

{pyneoinstance-1.1.0 → pyneoinstance-1.1.2/pyneoinstance.egg-info}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: pyneoinstance
-Version: 1.1.0
+Version: 1.1.2
 Summary: Handle Neo4j read and write transactions
-Author-email: Jose A Alvarado-Guzma <jalvarado-guzman@neo4j.com>
+Author-email: "Jose A. Alvarado-Guzman" <jose.alvarado-guzman@neo4j.com>
 License: GNU GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007
         
@@ -685,17 +685,22 @@ Classifier: Development Status :: 4 - Beta
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: neo4j>=5.0.0
+Requires-Dist: pandas
+Requires-Dist: PyYAML
 
 # PyNeoInstance Package
 
 ## What is it?
 
-Is a Python package that provides a user friendly API for submitting Cypher queries to Neo4j.
+PyNeoInstance is a Python package that provides a user friendly API for submitting Cypher queries to Neo4j.
 It supports the following features:
 
-- __Read query__: Submit a Cypher query and get the result of it as a Pandas DataFrame.
-- __Write query__: Sumbmit a Cypher query to update an existing database.
-- __Write query with data__: Update a database based on a Pandas DataFrame and one or more Cypher queries.
+- __Read query__: Submit a Cypher read query, with or without parameters, and get a Pandas Data Frame with the results.
+- __Write query__: Submit a write Cypher query, with or without parameters, to update an existing database.
+- __Write queries__: Submit a list of Cypher queries to update an existing database.
+- __Write query with data__: Update a database based on a Pandas Data Frame and a Cypher query.
+- __Write queries with data__: Update a database based on a Pandas Data Frame and a list of Cypher queries.
 
 ## How to install it?
 
@@ -707,16 +712,16 @@ pip install pyneoinstance
 
 ### Instantiating the Neo4jInstance class
 
-In order to use this package you first need to import the Neo4jInstance class.
+In order to use this package, you first need to import the Neo4jInstance class.
 
 ```python
-from pyneoingest import Neo4jInstance
+from pyneoinstance import Neo4jInstance
 ```
 
 Once imported, you need to instantiate this class by providing the following arguments:
 
 - _uri_: The Neo4j instance unique resource identifier.
-- _user_: The user name use to authenticate. 
+- _user_: The user name used to authenticate. 
 - _password_: The user name password.
 
 ```python
@@ -737,7 +742,7 @@ user = os.environ['NEO4J_USER']
 password = os.environ['NEO4J_PASSWORD']
 graph = Neo4jInstance(uri,user,password)
 ```
-Another alternative is to create a YAML configutation file to store this infromation.
+Another alternative is to create a YAML configuration file to store this information.
 
 ```yaml
 # configuration.yaml
@@ -745,9 +750,10 @@ db_info:
   uri: neo4j_uri
   user: neo4j_user
   password: user_password
+  database: neo4j
 ```
 
-This YAML file can then be loaded in Python and these information can be retrieve.
+This YAML file can then be loaded in Python and this information can be retrieve.
 
 ```python
 from pyneoinstance import load_yaml_file
@@ -758,7 +764,7 @@ graph = Neo4jInstance(db_info['uri'], db_info['user'], db_info['password'])
 ```
 ### Submitting a Cypher read query
 
-Once you instantiated the Neo4jInstance class, you can submit a Cypher read query by using the class method execute\_read\_query. This method receive the Cypher query string as an argument and optionally the name of the database on which the query should be executed. If the database name is not provided the query will be execute using your default Neo4j database. The results of the query is return as a a Pandas DataFrame. To avoid unwanted column names in the resulting DataFrame, always provide aliases for all return properties.
+Once you instantiated the Neo4jInstance class, you can submit a Cypher read query by using the class method execute\_read\_query. This method receives the Cypher query string as an argument and optionally the name of the database on which the query should be executed. If the database name is not provided the query will be execute using your default Neo4j database. The results of the query are return as a Pandas Data Frame. To avoid unwanted column names in the resulting Data Frame, always provide aliases for all returned properties.
 
 ```python
 query = """
@@ -768,35 +774,56 @@ query = """
            m.tagline AS tagline;
 """
 
-data = graph.execute_read_query(query)
+data = graph.execute_read_query(query,db_info['database'])
 ```
+
+### Submitting a Cypher read query with parameters
+
+The method execute\_read\_query can optionally received a Python Dictionary with the parameters required as part of you Cypher query.
+
+```python
+query = """
+    MATCH (m:Movie {title: $movie_title})
+    RETURN m.tile AS title,
+           m.released AS releasedYear,
+           m.tagline AS tagline;
+"""
+
+data = graph.execute_read_query(query, db_info['database'], db_info['database'], parameters={'movie_title':'The Matrix'})
+```
+
 ### Submitting a Cypher write query
 
-We submit a Cypher write query using the method execute\_write\_query. The signature of this method is identical to the execute\_read\_query. This method returns a dictionary containing the updates made to the database.
+You can submit a Cypher write query using the method execute_write_query. The signature of this method is identical to the execute_read_query. This method returns a dictionary containing the updates made to the database. As with read queries you can also specify a Python dictionary containing Cypher parameters.
 
 ```python
 query = """
-    MERGE(m:Movie {title:'Wakanda Forever'})
+    MERGE(m:Movie {title:$movie_title})
     ON CREATE SET
-        m.release=2022,
-        m.tagline = 'Wakanda Forever! Long Live Wakanda! For Honor, For Legacy, For Wakanda!'
+        m.release = $year,
+        m.tagline = $tagline
 """
 
-results = graph.execute_write_query(query)
+results = graph.execute_write_query(query, db_info['database'],
+  parameters={
+    'movie_title':'Wakanda Forever',
+    'year'=2022,
+    tagline=''Wakanda Forever! Long Live Wakanda! For Honor, For Legacy, For Wakanda!''
+  })
 ```
 
 ### Updating a database with data in a DataFrame: Sequentially
 
-We can update a Neo4j database with data contained in a Pandas DataFrame using the methods execute\_write\_query\_with\_data or execute\_write\_queries\_with\_data. These methos return a dictionary containing the numbers and types of updates made to the database. Besides taking the query or list of queries as an argument, we can pass to these methods the following arguments:
+We can update a Neo4j database with data contained in a Pandas Data Frame using the methods execute\_write\_query\_with\_data or execute\_write\_queries\_with\_data. These methods return a dictionary containing the numbers and types of updates made to the database. Besides taking the query or list of queries as an argument, we can pass to these methods the following arguments:
 
-- _data_: Pandas DataFrame containing data to process.
-- _database_: Optional, database on which to execute the quieries.
-- _partitions_: Optional, number of partitions use to break the DataFrame in smaller chucks.
-- _parallel_: Wheather to execute the query using multiple Python process.
+- _data_: Pandas Data Frame containing data to process.
+- _database_: Optional, database on which to execute the queries.
+- _partitions_: Optional, number of partitions use to break the Data Frame in smaller chucks.
+- _parallel_: Whether to execute the query using multiple Python process.
 - _workers_: The number of processes to spawn to execute the queries in parallel.
 - _parameters_: Extra arguments containing optional cypher parameters.
 
-To illustrates how to use this methods lets imagine we have a csv file that looks like this:
+To illustrates how to use these methods lets imagine we have a csv file that looks like this:
 
 ```python
 # people.csv
@@ -812,11 +839,11 @@ personId,name,birthYear,deathYear
 3482,Chus Lampreave,1930,
 ```
 
-We want to update our database by loading this data as a node with the label Person containing the properties id, name, birthYear and deathYear. To accomplish this, we need to performe the following steps:
+We want to update our database by loading this data as a node with the label Person containing the properties id, name, birthYear and deathYear. To accomplish this, we need to performed the following steps:
 
-1. Load the csv to Python as a DataFrame.
-2. Develop the Cypher query that is going to be use to load the DataFrame into Neo4j.
-3. Call the execute\_write\_query\_with\_data of an existing instance of the Neo4jInstance class passing the DataFrame, Cypher query and any other optinal arguments to this method. 
+1. Load the csv to Python as a Data Frame.
+2. Develop the Cypher query that is going to be use to load the Data Frame into Neo4j.
+3. Call the execute\_write\_query\_with\_data of an existing instance of the Neo4jInstance class passing the Data Frame, Cypher query and any other optional arguments to this method. 
 
 ```python
 import pandas as pd
@@ -834,10 +861,10 @@ person_load_query = """
           p.deathYear = toInteger(row.deathYear)
 """
 
-person_load_result = graph.execute_write_query_with_data(person_data, person_load_query)
+person_load_result = graph.execute_write_query_with_data(person_load_query, person_data, db_info['database'])
 ```
 
-Is not a good practice to store your Cypher queries as strings within your Python modules. To solve this we can extend our YAML configuration file to store all our Cypher queries.
+It is not a good practice to store your Cypher queries as strings within your Python modules. To solve this, we can extend our YAML configuration file to store all our Cypher queries.
 
 ```yaml
 # configuration.yaml
@@ -845,9 +872,10 @@ db_info:
   uri: neo4j_uri
   user: neo4j_user
   password: user_password
+  database: neo4j
 loading_queries:
   nodes:
-    person: |
+    Person: |
       WITH $rows AS rows
       UNWIND rows AS row
       MERGE(p:Person {id:row.personId})
@@ -867,28 +895,33 @@ person_data = pd.read_csv('people.csv')
 
 node_load_queries = config['loading_queries']['nodes']
 
-person_load_result = graph.execute_write_query_with_data(person_data, node_load_queries['person'])
+person_load_result = graph.execute_write_query_with_data(node_load_queries['Person'], person_data, db_info['database'])
 ```
 
-If the number of rows in your DataFrame is 100K or more it is reccomended to break the DataFrame in smaller chunks so that they can be process in different transactions. This will avoid running out of heap error. To do this, just indicate in the _partitions_ argument how many partitions would you like to break this DataFrame into. This partitions will be loaded in different sequential transactions unless you specified loading them in parallel by setting the _parallel_ argument to true. We will discuss this process in the next section.
+If the number of rows in your Data Frame is 100K or more it is recommended to break the Data Frame in smaller chunks so that they can be process in different transactions. This will avoid running out of heap error. To do this, just indicate in the _partitions_ argument how many partitions would you like to break this Data Frame into. These partitions will be loaded in different sequential transactions unless you specified loading them in parallel by setting the _parallel_ argument to true. We will discuss this process in the next section.
 
 ```python
 person_load_result = graph.execute_write_query_with_data(
-    person_data,
     node_load_queries['person'],
+    person_data,
+    db_info['database'],
     partitions = 5
     )
 ```
-## Updating a database with data in a DataFrame: Parallel  
+## Updating a database with data in a Data Frame: Parallel  
 
-To load the data in the DataFrame in parallel, we need to partition the DataFrame by incrementing the _partitions_ argument and set the _parallel_ argument to true. By default this will use all the available virtual CPUs in the machine. If you need to use less, you can specified how many to use by setting the _workers_ argument.
+To load the data in the Data Frame in parallel, we need to partition the Data Frame by incrementing the _partitions_ argument and set the _parallel_ argument to true. By default, this will use all the available virtual CPUs in the machine. If you need to use less, you can specify how many to use by setting the _workers_ argument.
 
 ```python
 person_load_result = graph.execute_write_query_with_data(
-    person_data,
     node_load_queries['person'],
+    person_data,
     partitions = 5,
     parallel = True,
     workers = 5
     )
 ```
+
+## More detailed examples
+
+For more detailed examples please referred to this [article](https://medium.com/@a-gilmore/pyneoinstance-a-user-friendly-python-library-for-neo4j-dbefa3117bb2).

{pyneoinstance-1.1.0 → pyneoinstance-1.1.2}/pyproject.toml

@@ -6,10 +6,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyneoinstance"
-version = "1.1.0"
+version = "1.1.2"
 description = "Handle Neo4j read and write transactions"
 readme = "README.md"
-authors = [{ name = "Jose A Alvarado-Guzma",email = "jalvarado-guzman@neo4j.com" }]
+authors = [{ name = "Jose A. Alvarado-Guzman",email = "jose.alvarado-guzman@neo4j.com" }]
 license = { file = "LICENSE" }
 classifiers = [
     "License :: OSI Approved :: GNU General Public License (GPL)",

{pyneoinstance-1.1.0 → pyneoinstance-1.1.2}/test/cypher_queries.yaml

@@ -4,8 +4,7 @@ pre_ingest:
   - CREATE CONSTRAINT nkMovie IF NOT EXISTS FOR(n:Movie) REQUIRE (n.movieId) IS NODE KEY;
 
 queries:
-  load_person:
-      |
+  load_person: |
       WITH $rows AS rows
       UNWIND rows AS row
       MERGE(p:Person {personId:row.personId})
@@ -13,8 +12,7 @@ queries:
           SET p.personId=row.personId,
               p.name=row.name,
               p.birthYear=toInteger(row.birthYear)
-  load_movie:
-      |
+  load_movie: |
       WITH $rows AS rows
       UNWIND rows AS row
       MERGE(m:Movie {movieId:row.movieId})
@@ -24,11 +22,16 @@ queries:
               m.averageVote=toFloat(row.avgVote),
               m.releaseYear=toInteger(row.releaseYear),
               m.genres=split(row.genres,':')
-  load_role:
-      |
+  load_role: |
       WITH $rows AS rows
       UNWIND rows AS row
       MATCH(p:Person {personId:row.personId}),(m:Movie {movieId:row.movieId})
       MERGE(p)-[r:ACTED_IN]->(m)
         ON CREATE
         SET r.character=split(row.character,':')
+  create_actor: |
+      MERGE(p:Person:Actor {personId:$id})
+        ON CREATE
+          SET p.personId=$id,
+              p.name=$name,
+              p.birthYear=$year

{pyneoinstance-1.1.0 → pyneoinstance-1.1.2}/test/test_neo4jdb.py

@@ -93,11 +93,21 @@ class TestNeo4jInstance(unittest.TestCase):
         # Test the execute_read_query_using cypher parameters
         movie = "The Matrix"
         query = "MATCH(m:Movie) WHERE m.title=$movie_name RETURN m.title AS movie"
-        print('Parameters')
+        print('Read Parameters')
         result = self.graph.execute_read_query(query,
                                                self.queries['database'],
-                                               movie_name=movie)
+                                               {'movie_name':movie})
         self.assertEqual(movie,result['movie'][0])
 
+        # Test the execute_write_query_using cypher parameters
+        print('Write Parameters')
+        result = self.graph.execute_write_query(
+            self.queries['queries']['create_actor'],
+            self.queries['database'],
+            parameters={'id':-1,'name':'Darth Vader','year':'1977'})
+        solution = {'nodes_created':1,'labels_added':2,
+                    'properties_set':4}
+        self.assertEqual(solution, result)
+
 if __name__ == '__main__':
     unittest.main()

pyneoinstance-1.1.0/README.md

@@ -1,206 +0,0 @@
-# PyNeoInstance Package
-
-## What is it?
-
-Is a Python package that provides a user friendly API for submitting Cypher queries to Neo4j.
-It supports the following features:
-
-- __Read query__: Submit a Cypher query and get the result of it as a Pandas DataFrame.
-- __Write query__: Sumbmit a Cypher query to update an existing database.
-- __Write query with data__: Update a database based on a Pandas DataFrame and one or more Cypher queries.
-
-## How to install it?
-
-```python
-pip install pyneoinstance
-```
-
-## How to use it?
-
-### Instantiating the Neo4jInstance class
-
-In order to use this package you first need to import the Neo4jInstance class.
-
-```python
-from pyneoingest import Neo4jInstance
-```
-
-Once imported, you need to instantiate this class by providing the following arguments:
-
-- _uri_: The Neo4j instance unique resource identifier.
-- _user_: The user name use to authenticate. 
-- _password_: The user name password.
-
-```python
-uri = 'bolt://localhost:7687'
-user = 'neo4j'
-password = 'password'
-
-graph = Neo4jInstance(uri, user, password)
-```
-
-Although the previous code is valid, it is not recommended to hard code your user credentials in your application. As an alternative you can store this information as part of your OS user environment variables and then retrieve them in Python.
-
-```python
-import os
-
-uri = os.environ['NEO4J_URI']
-user = os.environ['NEO4J_USER']
-password = os.environ['NEO4J_PASSWORD']
-graph = Neo4jInstance(uri,user,password)
-```
-Another alternative is to create a YAML configutation file to store this infromation.
-
-```yaml
-# configuration.yaml
-db_info:
-  uri: neo4j_uri
-  user: neo4j_user
-  password: user_password
-```
-
-This YAML file can then be loaded in Python and these information can be retrieve.
-
-```python
-from pyneoinstance import load_yaml_file
-
-config = load_yaml_file(configuration.yaml)
-db_info = config['db_info']
-graph = Neo4jInstance(db_info['uri'], db_info['user'], db_info['password'])
-```
-### Submitting a Cypher read query
-
-Once you instantiated the Neo4jInstance class, you can submit a Cypher read query by using the class method execute\_read\_query. This method receive the Cypher query string as an argument and optionally the name of the database on which the query should be executed. If the database name is not provided the query will be execute using your default Neo4j database. The results of the query is return as a a Pandas DataFrame. To avoid unwanted column names in the resulting DataFrame, always provide aliases for all return properties.
-
-```python
-query = """
-    MATCH (m:Movie {title: "The Matrix"})
-    RETURN m.tile AS title,
-           m.released AS releasedYear,
-           m.tagline AS tagline;
-"""
-
-data = graph.execute_read_query(query)
-```
-### Submitting a Cypher write query
-
-We submit a Cypher write query using the method execute\_write\_query. The signature of this method is identical to the execute\_read\_query. This method returns a dictionary containing the updates made to the database.
-
-```python
-query = """
-    MERGE(m:Movie {title:'Wakanda Forever'})
-    ON CREATE SET
-        m.release=2022,
-        m.tagline = 'Wakanda Forever! Long Live Wakanda! For Honor, For Legacy, For Wakanda!'
-"""
-
-results = graph.execute_write_query(query)
-```
-
-### Updating a database with data in a DataFrame: Sequentially
-
-We can update a Neo4j database with data contained in a Pandas DataFrame using the methods execute\_write\_query\_with\_data or execute\_write\_queries\_with\_data. These methos return a dictionary containing the numbers and types of updates made to the database. Besides taking the query or list of queries as an argument, we can pass to these methods the following arguments:
-
-- _data_: Pandas DataFrame containing data to process.
-- _database_: Optional, database on which to execute the quieries.
-- _partitions_: Optional, number of partitions use to break the DataFrame in smaller chucks.
-- _parallel_: Wheather to execute the query using multiple Python process.
-- _workers_: The number of processes to spawn to execute the queries in parallel.
-- _parameters_: Extra arguments containing optional cypher parameters.
-
-To illustrates how to use this methods lets imagine we have a csv file that looks like this:
-
-```python
-# people.csv
-personId,name,birthYear,deathYear
-23945,Gérard Pirès,1942,
-553509,Helen Reddy,1941,
-113934,Susan Flannery,1939,
-26706,David Rintoul,1948,
-237537,Rita Marley,1946,
-11502,Harry Davenport,1866,1949
-11792,George Dickerson,1933,
-7242,Temuera Morrison,1960,
-3482,Chus Lampreave,1930,
-```
-
-We want to update our database by loading this data as a node with the label Person containing the properties id, name, birthYear and deathYear. To accomplish this, we need to performe the following steps:
-
-1. Load the csv to Python as a DataFrame.
-2. Develop the Cypher query that is going to be use to load the DataFrame into Neo4j.
-3. Call the execute\_write\_query\_with\_data of an existing instance of the Neo4jInstance class passing the DataFrame, Cypher query and any other optinal arguments to this method. 
-
-```python
-import pandas as pd
-
-person_data = pd.read_csv('people.csv')
-
-person_load_query = """
-  WITH $rows AS rows
-  UNWIND rows AS row
-  MERGE(p:Person {id:row.personId})
-    ON CREATE
-      SET p.id = row.personId,
-          p.name = row.name,
-          p.birthYear=toInteger(row.birthYear),
-          p.deathYear = toInteger(row.deathYear)
-"""
-
-person_load_result = graph.execute_write_query_with_data(person_data, person_load_query)
-```
-
-Is not a good practice to store your Cypher queries as strings within your Python modules. To solve this we can extend our YAML configuration file to store all our Cypher queries.
-
-```yaml
-# configuration.yaml
-db_info:
-  uri: neo4j_uri
-  user: neo4j_user
-  password: user_password
-loading_queries:
-  nodes:
-    person: |
-      WITH $rows AS rows
-      UNWIND rows AS row
-      MERGE(p:Person {id:row.personId})
-        ON CREATE
-          SET p.id = row.personId,
-              p.name = row.name,
-              p.birthYear=toInteger(row.birthYear),
-              p.deathYear = toInteger(row.deathYear)
-```
-
-Now that we added the loading query to our configuration file, lets re-write our Python script to get this query from the configuration file.
-
-```python
-import pandas as pd
-
-person_data = pd.read_csv('people.csv')
-
-node_load_queries = config['loading_queries']['nodes']
-
-person_load_result = graph.execute_write_query_with_data(person_data, node_load_queries['person'])
-```
-
-If the number of rows in your DataFrame is 100K or more it is reccomended to break the DataFrame in smaller chunks so that they can be process in different transactions. This will avoid running out of heap error. To do this, just indicate in the _partitions_ argument how many partitions would you like to break this DataFrame into. This partitions will be loaded in different sequential transactions unless you specified loading them in parallel by setting the _parallel_ argument to true. We will discuss this process in the next section.
-
-```python
-person_load_result = graph.execute_write_query_with_data(
-    person_data,
-    node_load_queries['person'],
-    partitions = 5
-    )
-```
-## Updating a database with data in a DataFrame: Parallel  
-
-To load the data in the DataFrame in parallel, we need to partition the DataFrame by incrementing the _partitions_ argument and set the _parallel_ argument to true. By default this will use all the available virtual CPUs in the machine. If you need to use less, you can specified how many to use by setting the _workers_ argument.
-
-```python
-person_load_result = graph.execute_write_query_with_data(
-    person_data,
-    node_load_queries['person'],
-    partitions = 5,
-    parallel = True,
-    workers = 5
-    )
-```