Modernize packaging (#867)

 * Introducing `pyproject.toml` https://peps.python.org/pep-0621/
 * Migrate from flat-layout to src-layout
 * Deprecate legacy package name `neo4j-driver` in favor of `neo4j` + warn about
   it

Author: robsdedude

.coveragerc

@@ -33,11 +33,11 @@ repos:
         name: unasync
         entry: bin/make-unasync
         language: system
-        files: "^(neo4j/_async|tests/(unit|integration)/async_|testkitbackend/_async)/.*"
+        files: "^(src/neo4j/_async|tests/(unit|integration)/async_|testkitbackend/_async)/.*"
       - id: mypy
         name: mypy static type check
         entry: mypy
-        args: [ --show-error-codes, neo4j, tests, testkitbackend ]
+        args: [ --show-error-codes, src, tests, testkitbackend ]
         'types_or': [ python, pyi ]
         language: system
         pass_filenames: false

.pre-commit-config.yaml

@@ -54,7 +54,7 @@ Remember that many community members have become regular contributors and some a
 ## Specifically for this project:
 
 All code in `_sync` or `sync` folders is auto-generated. Don't change it, but
-install the pre-commit hooks as described below insted. They will take care of
+install the pre-commit hooks as described below instead. They will take care of
 updating the code if necessary.
 
 Setting up the development environment:

CONTRIBUTING.md

@@ -1,2 +1,3 @@
-global-exclude *.class *.pyc *.pyo *.so *.dll __pycache__
-prune tests
+include NOTICE* src/**/py.typed
+global-exclude *.class *.py[cod] *.so *.dll __pycache__
+prune test*

MANIFEST.in

@@ -32,6 +32,15 @@ To install the latest stable version, use:
     pip install neo4j
 
 
+.. TODO: 7.0 - remove this note
+
+.. note::
+
+    ``neo4j-driver`` is the old name for this package. It is now deprecated and
+    and will receive no further updates starting with 6.0.0. Make sure to
+    install ``neo4j`` as shown above.
+
+
 Quick Example
 =============
 

README.rst

@@ -2,26 +2,41 @@
 set -e
 
 ROOT=$(dirname "$0")/..
+SRC="${ROOT}/src"
 DIST="${ROOT}/dist"
 
 function get_package
 {
+    cd "${SRC}"
     python -c "from neo4j._meta import package; print(package)"
+    cd - > /dev/null
 }
 
 function set_package
 {
-    sed -i 's/^package = .*/package = "'$1'"/g' neo4j/_meta.py
+    sed -i 's/^package = .*/package = "'$1'"/g' "${SRC}/neo4j/_meta.py"
 }
 
 function get_version
 {
+    cd "${SRC}"
     python -c "from neo4j._meta import version; print(version)"
+    cd - > /dev/null
 }
 
 function set_version
 {
-    sed -i 's/^version = .*/version = "'$1'"/g' neo4j/_meta.py
+    sed -i 's/^version = .*/version = "'$1'"/g' "${SRC}/neo4j/_meta.py"
+}
+
+function get_deprecated {
+    cd "${SRC}"
+    python -c "from neo4j._meta import deprecated_package; print(deprecated_package)"
+    cd - > /dev/null
+}
+
+function set_deprecated {
+    sed -i 's/^deprecated_package = .*/deprecated_package = '$1'/g' "${SRC}/neo4j/_meta.py"
 }
 
 function check_file
@@ -40,54 +55,61 @@ function check_file
 function set_metadata_and_setup
 {
     PACKAGE="$1"; shift
+    DEPRECATED="$1"; shift
     VERSION="$1"; shift
 
-    cd ${ROOT}
+    cd "${ROOT}"
 
     # Capture original package metadata
     ORIGINAL_PACKAGE=$(get_package)
     ORIGINAL_VERSION=$(get_version)
-    echo "Source code originally configured for package ${ORIGINAL_PACKAGE}/${ORIGINAL_VERSION}"
+    ORIGINAL_DEPRECATED=$(get_deprecated)
+    echo "Source code originally configured for package ${ORIGINAL_PACKAGE}/${ORIGINAL_VERSION}/deprecated=${ORIGINAL_DEPRECATED}"
     echo "----------------------------------------"
-    grep "package\s\+=" neo4j/_meta.py
-    grep "version\s\+=" neo4j/_meta.py
+    grep "package\s\+=" "${SRC}/neo4j/_meta.py"
+    grep "version\s\+=" "${SRC}/neo4j/_meta.py"
+    grep "deprecated_package\s\+=" "${SRC}/neo4j/_meta.py"
     echo "----------------------------------------"
 
     function cleanup() {
       # Reset to original package metadata
       set_package "${ORIGINAL_PACKAGE}"
       set_version "${ORIGINAL_VERSION}"
-      echo "Source code reconfigured back to original package ${ORIGINAL_PACKAGE}/${ORIGINAL_VERSION}"
+      set_deprecated "${ORIGINAL_DEPRECATED}"
+      echo "Source code reconfigured back to original package ${ORIGINAL_PACKAGE}/${ORIGINAL_VERSION}/deprecated=${ORIGINAL_DEPRECATED}"
       echo "----------------------------------------"
-      grep "package\s\+=" neo4j/_meta.py
-      grep "version\s\+=" neo4j/_meta.py
+      grep "package\s\+=" "${SRC}/neo4j/_meta.py"
+      grep "version\s\+=" "${SRC}/neo4j/_meta.py"
+      grep "deprecated_package\s\+=" "${SRC}/neo4j/_meta.py"
       echo "----------------------------------------"
     }
     trap cleanup EXIT
 
     # Temporarily override package metadata
     set_package "${PACKAGE}"
     set_version "${VERSION}"
-    echo "Source code reconfigured for package ${PACKAGE}/${VERSION}"
+    set_deprecated "${DEPRECATED}"
+    echo "Source code reconfigured for package ${PACKAGE}/${VERSION}/deprecated=${DEPRECATED}"
     echo "----------------------------------------"
-    grep "package\s\+=" neo4j/_meta.py
-    grep "version\s\+=" neo4j/_meta.py
+    grep "package\s\+=" "${SRC}/neo4j/_meta.py"
+    grep "version\s\+=" "${SRC}/neo4j/_meta.py"
+    grep "deprecated_package\s\+=" "${SRC}/neo4j/_meta.py"
     echo "----------------------------------------"
 
     # Create source distribution
     find . -name *.pyc -delete
-    rm -rf ${ROOT}/*.egg-info 2> /dev/null
+    rm -rf "${SRC}/*.egg-info" 2> /dev/null
     python setup.py $*
     check_file "${DIST}/${PACKAGE}-${VERSION}.tar.gz"
 
-  trap - EXIT
-  cleanup
+    trap - EXIT
+    cleanup
 }
 
 function setup
 {
     ARGS="$*"
     rm -rf ${DIST} 2> /dev/null
-    set_metadata_and_setup "neo4j-driver" ${ARGS}   # Legacy package; can be removed in 2.0
-    set_metadata_and_setup "neo4j" ${ARGS}
+    set_metadata_and_setup "neo4j-driver" "True" ${ARGS}   # Legacy package; can be removed in 2.0
+    set_metadata_and_setup "neo4j" "False" ${ARGS}
 }

bin/dist-functions

@@ -32,8 +32,8 @@ import unasync
 
 
 ROOT_DIR = Path(__file__).parents[1].absolute()
-ASYNC_DIR = ROOT_DIR / "neo4j" / "_async"
-SYNC_DIR = ROOT_DIR / "neo4j" / "_sync"
+ASYNC_DIR = ROOT_DIR / "src" / "neo4j" / "_async"
+SYNC_DIR = ROOT_DIR / "src" / "neo4j" / "_sync"
 ASYNC_UNIT_TEST_DIR = ROOT_DIR / "tests" / "unit" / "async_"
 SYNC_UNIT_TEST_DIR = ROOT_DIR / "tests" / "unit" / "sync"
 ASYNC_INTEGRATION_TEST_DIR = ROOT_DIR / "tests" / "integration" / "async_"

bin/make-unasync

@@ -0,0 +1,111 @@
+# Copyright (c) "Neo4j"
+# Neo4j Sweden AB [https://neo4j.com]
+#
+# This file is part of Neo4j.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[project]
+name = "neo4j"
+description = "Neo4j Bolt driver for Python"
+license = {text = "Apache License, Version 2.0"}
+#TODO: 6.0 - static readme
+#readme = "README.rst"
+authors = [
+    {name = "Neo4j, Inc.", email = "drivers@neo4j.com"},
+]
+dependencies = ["pytz"]
+requires-python = ">=3.7"
+keywords = ["neo4j", "graph", "database"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Topic :: Database",
+    "Topic :: Software Development",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dynamic = ["version", "readme"]
+
+[project.urls]
+Homepage = "https://github.com/neo4j/neo4j-python-driver"
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.0.0"]
+
+[build-system]
+requires = ["setuptools~=65.6", "tomlkit~=0.11.6"]
+build-backend = "setuptools.build_meta"
+
+# still in beta
+#[tool.setuptools.dynamic]
+#version = {attr = "neo4j._meta.version"}
+
+
+[tool.coverage]
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+omit = [
+    ".*/*",
+    "tests/*",
+    "src/neo4j/meta.py",
+    "*virtualenv*",
+    "*venv*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "except ImportError",
+]
+
+
+[tool.isort]
+combine_as_imports = true
+ensure_newline_before_comments = true
+force_grid_wrap = 2
+# breaks order of relative imports
+# https://github.com/PyCQA/isort/issues/1944
+#force_sort_within_sections = true
+include_trailing_comma = true
+# currently broken
+# https://github.com/PyCQA/isort/issues/1855
+#lines_before_imports = 2
+lines_after_imports = 2
+lines_between_sections = 1
+multi_line_output = 3
+order_by_type = false
+remove_redundant_aliases = true
+use_parentheses = true
+
+
+[tool.pytest.ini_options]
+mock_use_standalone_module = true
+asyncio_mode = "auto"
+
+
+[tool.mypy]
+
+[[tool.mypy.overrides]]
+module = "pandas.*"
+ignore_missing_imports = true

pyproject.toml

@@ -1,13 +1,29 @@
+# the driver itself
+-e .
+
 # auto-generate sync driver from async code
 unasync>=0.5.0
+# pre-commit hooks and tools
 pre-commit>=2.15.0
 isort>=5.10.0
 mypy>=0.971
 typing-extensions>=4.3.0
 types-pytz>=2022.1.2
 
-# needed for running tests
--r tests/requirements.txt
+# for packaging
+setuptools~=65.6
+# TODO: 6.0 - can be removed once `setup.py` is simplified
+tomlkit~=0.11.6
 
-# production dependencies
--r requirements.txt
+# needed for running tests
+coverage[toml]>=5.5
+mock>=4.0.3
+pandas>=1.0.0
+pytest>=6.2.5
+pytest-asyncio>=0.16.0
+pytest-benchmark>=3.4.1
+pytest-cov>=3.0.0
+pytest-mock>=3.6.1
+teamcity-messages>=1.29
+tox>=3.27.1
+tox-factor>=0.1.2