Merge pull request #763 from neo4j-contrib/rc/5.2.0

Rc/5.2.0

.github/workflows/integration-tests.yml

@@ -33,7 +33,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e '.[dev]'
+        pip install -e '.[dev,pandas,numpy]'
     - name: Test with pytest
       env:
         AURA_TEST_DB_USER: ${{ secrets.AURA_TEST_DB_USER }}

Changelog

@@ -1,3 +1,11 @@
+Version 5.2.0 2023-11
+* Add an option to pass your own driver instead of relying on the automatically created one. See set_connection method. NB : only accepts the synchronous driver for now.
+* Add a close_connection method to explicitly close the driver to match Neo4j deprecation.
+* Add a DATABASE_NAME config option, available for both auto- and self-managed driver modes.
+* Add neomodel_inspect_database script, which inspects an existing database and creates neomodel class definitions for all objects.
+* Add support for pandas DataFrame and Series ; numpy Array
+* Add relationship uniqueness constraints - for Neo4j >= 5.7
+
 Version 5.1.2 2023-09
 * Raise ValueError on reserved keywords ; add tests #590 #623
 * Add support for relationship property uniqueness constraints. Introduced in Neo4j 5.7.

README.md

@@ -0,0 +1,114 @@
+![neomodel](https://raw.githubusercontent.com/neo4j-contrib/neomodel/master/doc/source/_static/neomodel-300.png)
+
+An Object Graph Mapper (OGM) for the [neo4j](https://neo4j.com/) graph
+database, built on the awesome
+[neo4j_driver](https://github.com/neo4j/neo4j-python-driver)
+
+If you need assistance with neomodel, please create an issue on the
+GitHub repo found at <https://github.com/neo4j-contrib/neomodel/>.
+
+-   Familiar class based model definitions with proper inheritance.
+-   Powerful query API.
+-   Schema enforcement through cardinality restrictions.
+-   Full transaction support.
+-   Thread safe.
+-   Pre/post save/delete hooks.
+-   Django integration via
+    [django_neomodel](https://github.com/neo4j-contrib/django-neomodel)
+
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=neo4j-contrib_neomodel&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=neo4j-contrib_neomodel)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=neo4j-contrib_neomodel&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=neo4j-contrib_neomodel)
+[![Documentation Status](https://readthedocs.org/projects/neomodel/badge/?version=latest)](https://neomodel.readthedocs.io/en/latest/?badge=latest)
+
+# Requirements
+
+**For neomodel releases 5.x :**
+
+-   Python 3.7+
+-   Neo4j 5.x, 4.4 (LTS)
+
+**For neomodel releases 4.x :**
+
+-   Python 3.7 -\> 3.10
+-   Neo4j 4.x (including 4.4 LTS for neomodel version 4.0.10)
+
+# Documentation
+
+(Needs an update, but) Available on
+[readthedocs](http://neomodel.readthedocs.org).
+
+# Upcoming breaking changes notice - \>=5.3
+
+Based on Python version [status](https://devguide.python.org/versions/),
+neomodel will be dropping support for Python 3.7 in the next release
+(5.3). This does not mean neomodel will stop working on Python 3.7, but
+it will no longer be tested against it. Instead, we will try to add
+support for Python 3.12.
+
+Another potential breaking change coming up is adding async support to
+neomodel. But we do not know when this will happen yet, or if it will
+actually be a breaking change. We will definitely push this in a major
+release though. More to come on that later.
+
+Finally, we are looking at refactoring some standalone methods into the
+Database() class. More to come on that later.
+
+# Installation
+
+Install from pypi (recommended):
+
+    $ pip install neomodel ($ source dev # To install all things needed in a Python3 venv)
+
+    # Neomodel has some optional dependencies (including Shapely), to install these use:
+
+    $ pip install neomodel['extras']
+
+To install from github:
+
+    $ pip install git+git://github.com/neo4j-contrib/neomodel.git@HEAD#egg=neomodel-dev
+
+# Contributing
+
+Ideas, bugs, tests and pull requests always welcome. Please use
+GitHub\'s Issues page to track these.
+
+If you are interested in developing `neomodel` further, pick a subject
+from the Issues page and open a Pull Request (PR) for it. If you are
+adding a feature that is not captured in that list yet, consider if the
+work for it could also contribute towards delivering any of the existing
+issues too.
+
+## Running the test suite
+
+Make sure you have a Neo4j database version 4 or higher to run the tests
+on.:
+
+    $ export NEO4J_BOLT_URL=bolt://<username>:<password>@localhost:7687 # check your username and password
+
+Ensure `dbms.security.auth_enabled=true` in your database configuration
+file. Setup a virtual environment, install neomodel for development and
+run the test suite: :
+
+    $ pip install -e '.[dev]'
+    $ pytest
+
+The tests in \"test_connection.py\" will fail locally if you don\'t
+specify the following environment variables:
+
+    $ export AURA_TEST_DB_USER=username
+    $ export AURA_TEST_DB_PASSWORD=password
+    $ export AURA_TEST_DB_HOSTNAME=url
+
+If you are running a neo4j database for the first time the test suite
+will set the password to \'test\'. If the database is already populated,
+the test suite will abort with an error message and ask you to re-run it
+with the `--resetdb` switch. This is a safeguard to ensure that the test
+suite does not accidentally wipe out a database if you happen to not
+have restarted your Neo4j server to point to a (usually named)
+`debug.db` database.
+
+If you have `docker-compose` installed, you can run the test suite
+against all supported Python interpreters and neo4j versions: :
+
+    # in the project's root folder:
+    $ sh ./tests-with-docker-compose.sh

doc/source/conf.py

@@ -57,7 +57,7 @@
 
 # General information about the project.
 project = __package__
-copyright = "2019, " + __author__
+copyright = "2023, " + __author__
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/source/configuration.rst

@@ -3,14 +3,24 @@ Configuration
 
 This section is covering the Neomodel 'config' module and its variables.
 
-Database
---------
+.. _connection_options_doc:
 
-Setting the connection URL::
+Connection
+----------
+
+There are two ways to define your connection to the database :
+
+1. Provide a Neo4j URL and some options - Driver will be managed by neomodel
+2. Create your own Neo4j driver and pass it to neomodel
+
+neomodel-managed (default)
+--------------------------
+
+Set the connection URL::
 
     config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687`
 
-Adjust driver configuration::
+Adjust driver configuration - these options are only available for this connection method::
 
     config.MAX_CONNECTION_POOL_SIZE = 100  # default
     config.CONNECTION_ACQUISITION_TIMEOUT = 60.0  # default
@@ -22,12 +32,90 @@ Adjust driver configuration::
     config.MAX_TRANSACTION_RETRY_TIME = 30.0  # default
     config.RESOLVER = None  # default
     config.TRUST = neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES  # default
-    config.USER_AGENT = neomodel/vNeo4j.Major.minor  # default
+    config.USER_AGENT = neomodel/v5.2.0  # default
 
-Setting the database name, for neo4j >= 4::
+Setting the database name, if different from the default one::
 
+    # Using the URL only
     config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687/mydb`
 
+    # Using config option
+    config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687`
+    config.DATABASE_NAME = 'mydb'
+
+self-managed
+------------
+
+Create a Neo4j driver::
+    
+    from neo4j import GraphDatabase
+    my_driver = GraphDatabase().driver('bolt://localhost:7687', auth=('neo4j', 'password'))
+    config.DRIVER = my_driver
+
+See the `driver documentation <https://neo4j.com/docs/api/python-driver/current/api.html#graphdatabase>` here.
+
+This mode allows you to use all the available driver options that neomodel doesn't implement, for example auth tokens for SSO.
+Note that you have to manage the driver's lifecycle yourself.
+
+However, everything else is still handled by neomodel : sessions, transactions, etc...
+
+NB : Only the synchronous driver will work in this way. The asynchronous driver is not supported yet.
+
+Change/Close the connection
+---------------------------
+
+Optionally, you can change the connection at any time by calling ``set_connection``::
+
+    from neomodel import db
+    # Using URL - auto-managed
+    db.set_connection(url='bolt://neo4j:neo4j@localhost:7687')
+
+    # Using self-managed driver
+    db.set_connection(driver=my_driver)
+
+The new connection url will be applied to the current thread or process.
+
+Since Neo4j version 5, driver auto-close is deprecated. Make sure to close the connection anytime you want to replace it,
+as well as at the end of your application's lifecycle by calling ``close_connection``::
+
+    from neomodel import db
+    db.close_connection()
+
+    # If you then want a new connection
+    db.set_connection(url=url)
+
+This will close the Neo4j driver, and clean up everything that neomodel creates for its internal workings.
+
+Protect your credentials
+------------------------
+
+You should `avoid setting database access credentials in plain sight <https://
+www.ndss-symposium.org/wp-content/uploads/2019/02/ndss2019_04B-3_Meli_paper.pdf>`_. Neo4J defines a number of
+`environment variables <https://neo4j.com/developer/kb/how-do-i-authenticate-with-cypher-shell-without-specifying-the-
+username-and-password-on-the-command-line/>`_ that are used in its tools and these can be re-used for other applications
+too.
+
+These are:
+
+* ``NEO4J_USERNAME``
+* ``NEO4J_PASSWORD``
+* ``NEO4J_BOLT_URL``
+
+By setting these with (for example): ::
+
+    $ export NEO4J_USERNAME=neo4j
+    $ export NEO4J_PASSWORD=neo4j
+    $ export NEO4J_BOLT_URL="bolt://$NEO4J_USERNAME:$NEO4J_PASSWORD@localhost:7687"
+
+They can be accessed from a Python script via the ``environ`` dict of module ``os`` and be used to set the connection
+with something like: ::
+
+    import os
+    from neomodel import config
+
+    config.DATABASE_URL = os.environ["NEO4J_BOLT_URL"]
+
+
 Enable automatic index and constraint creation
 ----------------------------------------------