Housekeeping

.github/workflows/analyze.yml

@@ -37,7 +37,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL

.github/workflows/build.yml

@@ -1,9 +1,8 @@
 name: build
 on:
   workflow_dispatch:
-  push:
-    branches: [ master ]
   pull_request:
+  push:
     branches: [ master ]
 env:
   PACKAGE_DIR: adbnx_adapter
@@ -13,34 +12,47 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.7", "3.8", "3.9", "3.10"]
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     name: Python ${{ matrix.python }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+
       - name: Setup Python ${{ matrix.python }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
+          cache: 'pip'
+          cache-dependency-path: setup.py
+
       - name: Set up ArangoDB Instance via Docker
-        run: docker create --name adb -p 8529:8529 -e ARANGO_ROOT_PASSWORD= arangodb/arangodb:3.9.1
+        run: docker create --name adb -p 8529:8529 -e ARANGO_ROOT_PASSWORD= arangodb/arangodb
+
       - name: Start ArangoDB Instance
         run: docker start adb
+
       - name: Setup pip
         run: python -m pip install --upgrade pip setuptools wheel
+
       - name: Install packages
         run: pip install .[dev]
+
       - name: Run black
         run: black --check --verbose --diff --color ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
+
       - name: Run flake8
         run: flake8 ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
+
       - name: Run isort
         run: isort --check --profile=black ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
+
       - name: Run mypy
         run: mypy ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
+
       - name: Run pytest
         run: pytest --cov=${{env.PACKAGE_DIR}} --cov-report xml --cov-report term-missing -v --color=yes --no-cov-on-fail --code-highlight=yes
+
       - name: Publish to coveralls.io
-        if: matrix.python == '3.8'
+        if: matrix.python == '3.10'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: coveralls --service=github

.github/workflows/release.yml

@@ -3,76 +3,34 @@ on:
   workflow_dispatch:
   release:
     types: [published]
-env:
-  PACKAGE_DIR: adbnx_adapter
-  TESTS_DIR: tests
 jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python: ["3.7", "3.8", "3.9", "3.10"]
-    name: Python ${{ matrix.python }}
-    steps:
-      - uses: actions/checkout@v2
-      - name: Setup Python ${{ matrix.python }}
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python }}
-      - name: Set up ArangoDB Instance via Docker
-        run: docker create --name adb -p 8529:8529 -e ARANGO_ROOT_PASSWORD= arangodb/arangodb:3.9.1
-      - name: Start ArangoDB Instance
-        run: docker start adb
-      - name: Setup pip
-        run: python -m pip install --upgrade pip setuptools wheel
-      - name: Install packages
-        run: pip install .[dev]
-      - name: Run black
-        run: black --check --verbose --diff --color ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
-      - name: Run flake8
-        run: flake8 ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
-      - name: Run isort
-        run: isort --check --profile=black ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
-      - name: Run mypy
-        run: mypy ${{env.PACKAGE_DIR}} ${{env.TESTS_DIR}}
-      - name: Run pytest
-        run: pytest --cov=${{env.PACKAGE_DIR}} --cov-report xml --cov-report term-missing -v --color=yes --no-cov-on-fail --code-highlight=yes
-      - name: Publish to coveralls.io
-        if: matrix.python == '3.8'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: coveralls --service=github
-
   release:
-    needs: build
     runs-on: ubuntu-latest
     name: Release package
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Fetch complete history for all tags and branches
         run: git fetch --prune --unshallow
 
-      - name: Setup python
-        uses: actions/setup-python@v2
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: "3.10"
 
       - name: Install release packages
         run: pip install setuptools wheel twine setuptools-scm[toml]
 
-      - name: Install dependencies
-        run: pip install .[dev]
-
       - name: Build distribution
         run: python setup.py sdist bdist_wheel
 
-      - name: Publish to PyPI Test
+      - name: Publish to Test PyPi
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD_TEST }}
         run: twine upload --repository testpypi dist/* #--skip-existing
-      - name: Publish to PyPI
+
+      - name: Publish to PyPi
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
@@ -83,7 +41,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Update Changelog
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -95,10 +53,10 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Setup python
-        uses: actions/setup-python@v2
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: "3.10"
 
       - name: Install release packages
         run: pip install wheel gitchangelog pystache
@@ -110,12 +68,12 @@ jobs:
         run: gitchangelog ${{env.VERSION}} > CHANGELOG.md
 
       - name: Make commit for auto-generated changelog
-        uses: EndBug/add-and-commit@v7
+        uses: EndBug/add-and-commit@v9
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           add: "CHANGELOG.md"
-          branch: actions/changelog
+          new_branch: actions/changelog
           message: "!gitchangelog"
 
       - name: Create pull request for the auto generated changelog

README.md

@@ -9,7 +9,7 @@
 
 [![License](https://img.shields.io/github/license/arangoml/networkx-adapter?color=9E2165&style=for-the-badge)](https://github.com/arangoml/networkx-adapter/blob/master/LICENSE)
 [![Code style: black](https://img.shields.io/static/v1?style=for-the-badge&label=code%20style&message=black&color=black)](https://github.com/psf/black)
-[![Downloads](https://img.shields.io/badge/dynamic/json?style=for-the-badge&color=282661&label=Downloads&query=total_downloads&url=https://api.pepy.tech/api/projects/adbnx-adapter)](https://pepy.tech/project/adbnx-adapter)
+[![Downloads](https://img.shields.io/badge/dynamic/json?style=for-the-badge&color=282661&label=Downloads&query=total_downloads&url=https://api.pepy.tech/api/v2/projects/adbnx-adapter)](https://pepy.tech/project/adbnx-adapter)
 
 <a href="https://www.arangodb.com/" rel="arangodb.com">![](https://raw.githubusercontent.com/arangoml/networkx-adapter/master/examples/assets/logos/ArangoDB_logo.png)</a>
 <a href="https://networkx.org/" rel="networkx.org">![](https://raw.githubusercontent.com/arangoml/networkx-adapter/master/examples/assets/logos/networkx_logo.svg)</a>
@@ -45,30 +45,40 @@ pip install git+https://github.com/arangoml/networkx-adapter.git
 Also available as an ArangoDB Lunch & Learn session: [Graph & Beyond Course #2.9](https://www.arangodb.com/resources/lunch-sessions/graph-beyond-lunch-break-2-9-introducing-the-arangodb-networkx-adapter/)
 
 ```py
-from arango import ArangoClient # Python-Arango driver
 import networkx as nx
 
+from arango import ArangoClient
 from adbnx_adapter import ADBNX_Adapter, ADBNX_Controller
 
-# Let's assume that the ArangoDB "fraud detection" dataset is imported to this endpoint
-db = ArangoClient(hosts="http://localhost:8529").db("_system", username="root", password="")
+# Connect to ArangoDB
+db = ArangoClient().db()
 
+# Instantiate the adapter
 adbnx_adapter = ADBNX_Adapter(db)
 ```
 
 ### ArangoDB to NetworkX
 ```py
-# 1.1: ArangoDB to NetworkX via Graph name
+#######################
+# 1.1: via Graph name #
+#######################
+
 nx_g = adbnx_adapter.arangodb_graph_to_networkx("fraud-detection")
 
-# 1.2: ArangoDB to NetworkX via Collection names
+#############################
+# 1.2: via Collection names #
+#############################
+
 nx_g = adbnx_adapter.arangodb_collections_to_networkx(
     "fraud-detection", 
     {"account", "bank", "branch", "Class", "customer"}, # Vertex collections
     {"accountHolder", "Relationship", "transaction"} # Edge collections
 )
 
-# 1.3: ArangoDB to NetworkX via Metagraph
+######################
+# 1.3: via Metagraph #
+######################
+
 metagraph = {
     "vertexCollections": {
         "account": {"Balance", "account_type", "customer_id", "rank"},
@@ -79,10 +89,13 @@ metagraph = {
         "accountHolder": {},
     },
 }
+
 nx_g = adbnx_adapter.arangodb_to_networkx("fraud-detection", metagraph)
 
+#######################################
+# 1.4: with a custom ADBNX Controller #
+#######################################
 
-# 1.4: ArangoDB to NetworkX with a custom ADBNX Controller
 class Custom_ADBNX_Controller(ADBNX_Controller):
     """ArangoDB-NetworkX controller.
 
@@ -113,7 +126,10 @@ nx_g = ADBNX_Adapter(db, Custom_ADBNX_Controller()).arangodb_graph_to_networkx("
 
 ### NetworkX to ArangoDB
 ```py
-# 2.1: NetworkX Homogeneous graph to ArangoDB
+#################################
+# 2.1: with a Homogeneous Graph #
+#################################
+
 nx_g = nx.grid_2d_graph(5, 5)
 edge_definitions = [
     {
@@ -122,29 +138,44 @@ edge_definitions = [
         "to_vertex_collections": ["Grid_Node"],
     }
 ]
+
 adb_g = adbnx_adapter.networkx_to_arangodb("Grid", nx_g, edge_definitions)
 
-# 2.2: NetworkX Heterogeneous graph to ArangoDB with ArangoDB node IDs
-edges = []
-for i in range(1, 101):
-    for j in range(1, 101):
-        if j % i == 0:
-            # Notice that the NetworkX node IDs are following ArangoDB _id formatting standards (i.e `collection_name/node_key`)
-            edges.append((f"numbers_j/{j}", f"numbers_i/{i}", j / i)) 
+#############################################################
+# 2.2: with a Homogeneous Graph & a custom ADBNX Controller #
+#############################################################
 
-nx_g = nx.MultiDiGraph()
-nx_g.add_weighted_edges_from(edges)
+class Custom_ADBNX_Controller(ADBNX_Controller):
+    """ArangoDB-NetworkX controller.
 
-edge_definitions = [
-    {
-        "edge_collection": "is_divisible_by",
-        "from_vertex_collections": ["numbers_j"],
-        "to_vertex_collections": ["numbers_i"],
-    }
-]
-adb_g = adbnx_adapter.networkx_to_arangodb("Divisibility", nx_g, edge_definitions, keyify_nodes=True)
+    Responsible for controlling how nodes & edges are handled when
+    transitioning from ArangoDB to NetworkX, and vice-versa.
+    """
+
+    def _prepare_networkx_node(self, nx_node: dict, col: str) -> None:
+        """Prepare a NetworkX node before it gets inserted into the ArangoDB
+        collection **col**.
+
+        :param nx_node: The NetworkX node object to (optionally) modify.
+        :param col: The ArangoDB collection the node belongs to.
+        """
+        nx_node["foo"] = "bar"
+
+    def _prepare_networkx_edge(self, nx_edge: dict, col: str) -> None:
+        """Prepare a NetworkX edge before it gets inserted into the ArangoDB
+        collection **col**.
+
+        :param nx_edge: The NetworkX edge object to (optionally) modify.
+        :param col: The ArangoDB collection the edge belongs to.
+        """
+        nx_edge["bar"] = "foo"
+
+adb_g = ADBNX_Adapter(db, Custom_ADBNX_Controller()).networkx_to_arangodb("Grid", nx_g, edge_definitions)
+
+###################################
+# 2.3: with a Heterogeneous Graph #
+###################################
 
-# 2.3 NetworkX Heterogeneous graph to ArangoDB with non-ArangoDB node IDs
 edges = [
    ('student:101', 'lecture:101'), 
    ('student:102', 'lecture:102'), 
@@ -160,7 +191,10 @@ edges = [
 nx_g = nx.MultiDiGraph()
 nx_g.add_edges_from(edges)
 
-### Learn how this example is handled in Colab: https://colab.research.google.com/github/arangoml/networkx-adapter/blob/master/examples/ArangoDB_NetworkX_Adapter.ipynb#scrollTo=OuU0J7p1E9OM
+# ...
+
+# Learn how this example is handled in Colab:
+# https://colab.research.google.com/github/arangoml/networkx-adapter/blob/master/examples/ArangoDB_NetworkX_Adapter.ipynb#scrollTo=OuU0J7p1E9OM
 ```
 
 ##  Development & Testing

adbnx_adapter/__init__.py

@@ -1,2 +1,5 @@
 from adbnx_adapter.adapter import ADBNX_Adapter  # noqa: F401
-from adbnx_adapter.controller import ADBNX_Controller  # noqa: F401
+from adbnx_adapter.controller import (  # noqa: F401
+    ADBNX_Controller,
+    ADBNX_Controller_Full_Cycle,
+)