Feature/benchman (#17)

* Update the jupyter notebook
* Cleanup
* use standalone benchman
* Drop Python 3.8 support (typing)
* Store name in setup.cfg (not setup.py)
* tox_benchmarks.ini
* Create baseline
* Add benchmarks
* Update tests.yml

.github/workflows/tests.yml

@@ -41,7 +41,7 @@ jobs:
           sudo apt-get install graphviz
           python -V
           python -m pip install --upgrade pip
-          python -m pip install pydot pytest pytest-cov pytest-html rdflib ruff
+          python -m pip install benchman pydot pytest pytest-cov pytest-html rdflib ruff
           # if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           python -m pip install -e .
           python -m pip list

.gitignore

@@ -133,3 +133,4 @@ tests/test_dev_local*.py
 .DS_Store
 tests/temp/
 .ruff_cache/
+/.benchman

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 ## 0.11.2 (unreleased)
+- Add benchmarks (using [Benchman](https://github.com/mar10/benchman)).
 
 ## 0.11.1 (2024-11-08)
 - `t0.diff(t1, ...)` adds nodes from t1 when possible, so the new status is 

Pipfile

@@ -4,11 +4,12 @@ verify_ssl = true
 name = "pypi"
 
 [dev-packages]
+benchman = "*"
+# benchman = {file = "../benchman", editable = true}
 fabulist="*"
 ipykernel = "*"
 mypy = "*"
 notebook = "*"
-# pandoc = "*" # jupyter nbconvert --to rst
 pre-commit = "*"
 pydot = "*"
 pyright = "*"

docs/jupyter/tutorial.ipynb

@@ -0,0 +1,310 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Nutree Tutorial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Nutree organizes arbitrary object instances in an unobtrusive way. <br>\n",
+    "That means, we can add existing objects without havin to derrive from a common \n",
+    "base class or having them implement a specific protocol."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Setup some sample classes and objects"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 31,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import uuid\n",
+    "\n",
+    "\n",
+    "class Department:\n",
+    "    def __init__(self, name: str):\n",
+    "        self.guid = uuid.uuid4()\n",
+    "        self.name = name\n",
+    "\n",
+    "    def __str__(self):\n",
+    "        return f\"Department<{self.name}>\"\n",
+    "\n",
+    "\n",
+    "class Person:\n",
+    "    def __init__(self, name: str, age: int):\n",
+    "        self.guid = uuid.uuid4()\n",
+    "        self.name = name\n",
+    "        self.age = age\n",
+    "\n",
+    "    def __str__(self):\n",
+    "        return f\"Person<{self.name} ({self.age})>\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now create some instances"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 32,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "development_dep = Department(\"Development\")\n",
+    "test__dep = Department(\"Test\")\n",
+    "marketing_dep = Department(\"Marketing\")\n",
+    "\n",
+    "alice = Person(\"Alice\", 25)\n",
+    "bob = Person(\"Bob\", 35)\n",
+    "claire = Person(\"Claire\", 45)\n",
+    "dave = Person(\"Dave\", 55)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's organize these objects in a hierarchical structure:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 33,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Tree<'Organization'>\n",
+      "├── <__main__.Department object at 0x111f04e00>\n",
+      "│   ├── <__main__.Department object at 0x111b89f70>\n",
+      "│   │   ╰── <__main__.Person object at 0x111f05520>\n",
+      "│   ╰── <__main__.Person object at 0x111f04da0>\n",
+      "├── <__main__.Department object at 0x111edac90>\n",
+      "│   ╰── <__main__.Person object at 0x111f06a50>\n",
+      "╰── <__main__.Person object at 0x111ed9880>\n"
+     ]
+    }
+   ],
+   "source": [
+    "from nutree import Tree\n",
+    "\n",
+    "tree = Tree(\"Organization\")\n",
+    "\n",
+    "dev_node = tree.add(development_dep)\n",
+    "test_node = dev_node.add(test__dep)\n",
+    "mkt_node = tree.add(marketing_dep)\n",
+    "\n",
+    "tree.add(alice)\n",
+    "dev_node.add(bob)\n",
+    "test_node.add(claire)\n",
+    "mkt_node.add(dave)\n",
+    "\n",
+    "tree.print()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Tree nodes store a reference to the object in the `node.data` attribute.\n",
+    "\n",
+    "The nodes are formatted by the object's  `__repr__` implementation by default. <br>\n",
+    "We can overide ths by passing an f-string as `repr` argument:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 34,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Tree<'Organization'>\n",
+      "├── Department<Development>\n",
+      "│   ├── Department<Test>\n",
+      "│   │   ╰── Person<Claire (45)>\n",
+      "│   ╰── Person<Bob (35)>\n",
+      "├── Department<Marketing>\n",
+      "│   ╰── Person<Dave (55)>\n",
+      "╰── Person<Alice (25)>\n"
+     ]
+    }
+   ],
+   "source": [
+    "tree.print(repr=\"{node.data}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Iteration and Searching"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Mutation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Data IDs and Clones"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 35,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Node<'Department<Development>', data_id=287245536>\n",
+      "├── Node<'Department<Test>', data_id=287017463>\n",
+      "│   ╰── Node<'Person<Claire (45)>', data_id=287245650>\n",
+      "╰── Node<'Person<Bob (35)>', data_id=287245530>\n",
+      "Node<'Department<Marketing>', data_id=287234761>\n",
+      "╰── Node<'Person<Dave (55)>', data_id=287245989>\n",
+      "Node<'Person<Alice (25)>', data_id=287234440>\n"
+     ]
+    }
+   ],
+   "source": [
+    "tree.print(repr=\"{node}\", title=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Serialization"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 36,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[{'data': 'Department<Development>',\n",
+       "  'children': [{'data': 'Department<Test>',\n",
+       "    'children': [{'data': 'Person<Claire (45)>'}]},\n",
+       "   {'data': 'Person<Bob (35)>'}]},\n",
+       " {'data': 'Department<Marketing>',\n",
+       "  'children': [{'data': 'Person<Dave (55)>'}]},\n",
+       " {'data': 'Person<Alice (25)>'}]"
+      ]
+     },
+     "execution_count": 36,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "tree.to_dict_list()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 37,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[(0, {}), (1, {}), (2, {}), (1, {}), (0, {}), (5, {}), (0, {})]"
+      ]
+     },
+     "execution_count": 37,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "list(tree.to_list_iter())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 38,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Tree<'4595934048'>\n",
+      "╰── 'A'\n"
+     ]
+    }
+   ],
+   "source": [
+    "t = Tree._from_list([(0, \"A\")])\n",
+    "print(t.format())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.6"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}