Graphinate 0.6.0__tar.gz → 0.8.0__tar.gz

{graphinate-0.6.0 → graphinate-0.8.0}/.github/workflows/codeql.yml

@@ -13,10 +13,10 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ "master" ]
+    branches: [ "main" ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ "master" ]
+    branches: [ "main" ]
   schedule:
     - cron: '44 6 * * 4'
 
@@ -50,7 +50,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -64,7 +64,7 @@ jobs:
     # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -77,6 +77,6 @@ jobs:
     #     ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3
       with:
         category: "/language:${{matrix.language}}"

{graphinate-0.6.0 → graphinate-0.8.0}/.gitignore

@@ -781,4 +781,5 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-/.idea/**
+/.idea/**
+.qodo

{graphinate-0.6.0 → graphinate-0.8.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: Graphinate
-Version: 0.6.0
-Summary: 𝔾raphinate. Data to Graphs.
+Version: 0.8.0
+Summary: Graphinate. Data to Graphs.
 Project-URL: Homepage, https://erivlis.github.io/graphinate
 Project-URL: Documentation, https://erivlis.github.io/graphinate
 Project-URL: Bug Tracker, https://github.com/erivlis/graphinate/issues
@@ -30,8 +30,10 @@ Requires-Python: >=3.10
 Requires-Dist: click
 Requires-Dist: inflect
 Requires-Dist: loguru
+Requires-Dist: mappingtools
 Requires-Dist: matplotlib
 Requires-Dist: networkx
+Requires-Dist: networkx-mermaid>=0.1.0
 Requires-Dist: strawberry-graphql[asgi,opentelemetry]
 Provides-Extra: plot
 Requires-Dist: scipy; extra == 'plot'
@@ -40,7 +42,7 @@ Requires-Dist: starlette-prometheus; extra == 'server'
 Requires-Dist: uvicorn[standard]; extra == 'server'
 Description-Content-Type: text/markdown
 
-# [𝔾raphinate. Data to Graphs.](https://erivlis.github.io/graphinate/)
+# [Graphinate. Data to Graphs.](https://erivlis.github.io/graphinate/)
 
 <img height="360" src="https://github.com/erivlis/graphinate/assets/9897520/dae41f9f-69e5-4eb5-a488-87ce7f51fa32" alt="Graphinate. Data to Graphs.">
 
@@ -117,6 +119,38 @@ Description-Content-Type: text/markdown
   </tr>
 </table>
 
+## Table of Contents
+
+- [Introduction](#introduction)
+    - [What is Graphinate?](#what-is-graphinate)
+    - [Links](#links)
+- [Quick Start](#quick-start)
+    - [Install](#install)
+    - [Example](#example)
+- [CLI](#cli)
+    - [Commands](#commands)
+        - [Save](#save)
+        - [Server](#server)
+- [Gallery](#gallery)
+    - [Python AST](#python-ast)
+    - [GitHub Repository](#github-repository)
+    - [Python AST - 3D Force-Directed Animation](#python-ast---3d-force-directed-animation)
+    - [Web Page Links](#web-page-links)
+- [Development](#development)
+    - [Ruff](#ruff)
+    - [Test](#test)
+        - [Standard (cobertura) XML Coverage Report](#standard-cobertura-xml-coverage-report)
+        - [HTML Coverage Report](#html-coverage-report)
+    - [Docs](#docs)
+        - [test](#test-1)
+        - [build](#build)
+- [Acknowledgements](#acknowledgements)
+    - [Dependencies](#dependencies)
+        - [Python](#python)
+        - [Javascript and HTML](#javascript-and-html)
+    - [Dev Tools](#dev-tools)
+    - [IDE](#ide)
+
 ## Introduction
 
 ### What is Graphinate?
@@ -157,6 +191,7 @@ pip install graphinate[server]
 ### Example
 
 ```python title="Octagonal Graph"
+import examples.math.materializers
 import graphinate
 
 N: int = 8
@@ -174,10 +209,16 @@ def edge():
 
 
 # Choose builder and handler
-builder, handler = graphinate.materializers.Materializers.NetworkX_with_edge_labels.value
+builder, handler = examples.math.materializers.Materializers.NetworkX_with_edge_labels.value
+
+# Use the NetworkX Builder
+builder = graphinate.builders.NetworkxBuilder(graph_model)
 
-# Materialize the GraphModel
-graphinate.materialize(graph_model, builder=builder, builder_output_handler=handler)
+# build the NetworkX graph
+graph = builder.build()
+
+# plot the graph using matplotlib
+graphinate.plot(graph, with_edge_labels=True)
 ```
 
 #### `graphinate.model` function
@@ -186,11 +227,6 @@ graphinate.materialize(graph_model, builder=builder, builder_output_handler=hand
 > This function creates `GraphModel` class that is used to declaratively register _Edge_ and/or _Node_ data
 > supplier functions by using the `GraphModel.node()` and `GraphModel.edge()` decorators.
 
-#### `graphinate.materialize` function
-
-> [!NOTE]
-> This function can be used to easily generate an output from a `GraphModel` instance.
-
 ## CLI
 
 ### Commands
@@ -257,12 +293,35 @@ Options:
 
 ## Development
 
+### Install dependencies
+
+Use UV to install all dependencies
+
+```shell
+uv sync --all-extras --all-groups
+```
+
+### Update dependencies
+
+```shell
+uv lock --upgrade
+uv sync --all-extras --all-groups
+```
+
 ### Ruff
 
+#### Report issues
+
 ```shell
 ruff check src
 ```
 
+#### Fix issues
+
+```shell
+ruff check src --fix
+```
+
 ### Test
 
 #### Standard (cobertura) XML Coverage Report
@@ -277,6 +336,12 @@ ruff check src
 python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=html --junitxml=test_results.xml
 ```
 
+#### Terminal Coverage Report
+
+```shell
+python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=term --junitxml=test_results.xml
+```
+
 ### Docs
 
 #### test
@@ -321,8 +386,12 @@ python -m mkdocs build
 
 <a href="https://www.jetbrains.com/pycharm/"><img height="60" style="background: linear-gradient(-45deg, #FCF84A, #3DEA62, #21D789);" src="https://resources.jetbrains.com/storage/products/company/brand/logos/PyCharm.png" alt="PyCharm logo"></a>
 
----------------------
+--------------------------------
+
+![Alt](https://repobeats.axiom.co/api/embed/683f50f1d2de0e13e468c34a692612c2de4d56bd.svg "Repobeats analytics image")
+
+--------------------------------
 
 <img alt="Star Chart" src="https://forthebadge.com/images/badges/works-on-my-machine.svg">
 
-Copyright © 2023 Eran Rivlis
+Copyright © 2023-2025 Eran Rivlis

{graphinate-0.6.0 → graphinate-0.8.0}/README.md

@@ -1,4 +1,4 @@
-# [𝔾raphinate. Data to Graphs.](https://erivlis.github.io/graphinate/)
+# [Graphinate. Data to Graphs.](https://erivlis.github.io/graphinate/)
 
 <img height="360" src="https://github.com/erivlis/graphinate/assets/9897520/dae41f9f-69e5-4eb5-a488-87ce7f51fa32" alt="Graphinate. Data to Graphs.">
 
@@ -75,6 +75,38 @@
   </tr>
 </table>
 
+## Table of Contents
+
+- [Introduction](#introduction)
+    - [What is Graphinate?](#what-is-graphinate)
+    - [Links](#links)
+- [Quick Start](#quick-start)
+    - [Install](#install)
+    - [Example](#example)
+- [CLI](#cli)
+    - [Commands](#commands)
+        - [Save](#save)
+        - [Server](#server)
+- [Gallery](#gallery)
+    - [Python AST](#python-ast)
+    - [GitHub Repository](#github-repository)
+    - [Python AST - 3D Force-Directed Animation](#python-ast---3d-force-directed-animation)
+    - [Web Page Links](#web-page-links)
+- [Development](#development)
+    - [Ruff](#ruff)
+    - [Test](#test)
+        - [Standard (cobertura) XML Coverage Report](#standard-cobertura-xml-coverage-report)
+        - [HTML Coverage Report](#html-coverage-report)
+    - [Docs](#docs)
+        - [test](#test-1)
+        - [build](#build)
+- [Acknowledgements](#acknowledgements)
+    - [Dependencies](#dependencies)
+        - [Python](#python)
+        - [Javascript and HTML](#javascript-and-html)
+    - [Dev Tools](#dev-tools)
+    - [IDE](#ide)
+
 ## Introduction
 
 ### What is Graphinate?
@@ -115,6 +147,7 @@ pip install graphinate[server]
 ### Example
 
 ```python title="Octagonal Graph"
+import examples.math.materializers
 import graphinate
 
 N: int = 8
@@ -132,10 +165,16 @@ def edge():
 
 
 # Choose builder and handler
-builder, handler = graphinate.materializers.Materializers.NetworkX_with_edge_labels.value
+builder, handler = examples.math.materializers.Materializers.NetworkX_with_edge_labels.value
+
+# Use the NetworkX Builder
+builder = graphinate.builders.NetworkxBuilder(graph_model)
 
-# Materialize the GraphModel
-graphinate.materialize(graph_model, builder=builder, builder_output_handler=handler)
+# build the NetworkX graph
+graph = builder.build()
+
+# plot the graph using matplotlib
+graphinate.plot(graph, with_edge_labels=True)
 ```
 
 #### `graphinate.model` function
@@ -144,11 +183,6 @@ graphinate.materialize(graph_model, builder=builder, builder_output_handler=hand
 > This function creates `GraphModel` class that is used to declaratively register _Edge_ and/or _Node_ data
 > supplier functions by using the `GraphModel.node()` and `GraphModel.edge()` decorators.
 
-#### `graphinate.materialize` function
-
-> [!NOTE]
-> This function can be used to easily generate an output from a `GraphModel` instance.
-
 ## CLI
 
 ### Commands
@@ -215,12 +249,35 @@ Options:
 
 ## Development
 
+### Install dependencies
+
+Use UV to install all dependencies
+
+```shell
+uv sync --all-extras --all-groups
+```
+
+### Update dependencies
+
+```shell
+uv lock --upgrade
+uv sync --all-extras --all-groups
+```
+
 ### Ruff
 
+#### Report issues
+
 ```shell
 ruff check src
 ```
 
+#### Fix issues
+
+```shell
+ruff check src --fix
+```
+
 ### Test
 
 #### Standard (cobertura) XML Coverage Report
@@ -235,6 +292,12 @@ ruff check src
 python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=html --junitxml=test_results.xml
 ```
 
+#### Terminal Coverage Report
+
+```shell
+python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=term --junitxml=test_results.xml
+```
+
 ### Docs
 
 #### test
@@ -279,8 +342,12 @@ python -m mkdocs build
 
 <a href="https://www.jetbrains.com/pycharm/"><img height="60" style="background: linear-gradient(-45deg, #FCF84A, #3DEA62, #21D789);" src="https://resources.jetbrains.com/storage/products/company/brand/logos/PyCharm.png" alt="PyCharm logo"></a>
 
----------------------
+--------------------------------
+
+![Alt](https://repobeats.axiom.co/api/embed/683f50f1d2de0e13e468c34a692612c2de4d56bd.svg "Repobeats analytics image")
+
+--------------------------------
 
 <img alt="Star Chart" src="https://forthebadge.com/images/badges/works-on-my-machine.svg">
 
-Copyright © 2023 Eran Rivlis
+Copyright © 2023-2025 Eran Rivlis

graphinate-0.8.0/docs/.dates_cache.json

@@ -0,0 +1,86 @@
+{
+  "acknowledge.md": {
+    "created": "2023-08-20T00:21:55.621436",
+    "modified": "2024-07-23T19:55:37.245608"
+  },
+  "index.md": {
+    "created": "2023-08-15T00:05:21.586874",
+    "modified": "2025-03-08T22:16:20.899386"
+  },
+  "intro.md": {
+    "created": "2023-08-19T23:54:18.668094",
+    "modified": "2025-03-07T10:45:53.488431"
+  },
+  "start.md": {
+    "created": "2023-08-20T00:07:42.683716",
+    "modified": "2025-03-02T01:05:03.715683"
+  },
+  "tutorial.md": {
+    "created": "2025-02-26T00:03:30.194156",
+    "modified": "2025-03-07T12:16:22.526422"
+  },
+  "examples\\code.md": {
+    "created": "2023-08-20T00:09:32.677003",
+    "modified": "2025-03-07T10:14:05.629365"
+  },
+  "examples\\github.md": {
+    "created": "2023-10-05T11:43:15.316025",
+    "modified": "2025-01-28T23:47:41.840220"
+  },
+  "examples\\math.md": {
+    "created": "2023-10-05T11:43:22.861997",
+    "modified": "2025-01-28T23:54:42.968373"
+  },
+  "examples\\social.md": {
+    "created": "2025-02-24T23:49:35.972953",
+    "modified": "2025-02-24T23:51:09.584738"
+  },
+  "examples\\system.md": {
+    "created": "2024-03-27T01:28:38.922865",
+    "modified": "2024-03-27T01:51:20.126046"
+  },
+  "examples\\web.md": {
+    "created": "2023-10-05T11:43:30.550657",
+    "modified": "2025-03-07T10:25:30.054257"
+  },
+  "reference\\SUMMARY.md": {
+    "created": "2025-03-08T20:51:52.801367",
+    "modified": "2025-03-08T20:51:52.807370"
+  },
+  "usage\\cli.md": {
+    "created": "2023-09-27T21:23:44.140564",
+    "modified": "2025-03-01T23:56:33.595498"
+  },
+  "usage\\lib.md": {
+    "created": "2023-09-27T21:23:44.133584",
+    "modified": "2025-03-07T12:07:02.708943"
+  },
+  "reference\\graphinate\\builders.md": {
+    "created": "2025-03-08T20:51:52.788270",
+    "modified": "2025-03-08T20:51:52.792269"
+  },
+  "reference\\graphinate\\index.md": {
+    "created": "2025-03-08T20:51:52.786270",
+    "modified": "2025-03-08T20:51:52.788270"
+  },
+  "reference\\graphinate\\modeling.md": {
+    "created": "2025-03-08T20:51:52.792269",
+    "modified": "2025-03-08T20:51:52.795269"
+  },
+  "reference\\graphinate\\typing.md": {
+    "created": "2025-03-08T20:51:52.800360",
+    "modified": "2025-03-08T20:51:52.805368"
+  },
+  "reference\\graphinate\\renderers\\graphql.md": {
+    "created": "2025-03-08T20:51:52.796358",
+    "modified": "2025-03-08T20:51:52.800360"
+  },
+  "reference\\graphinate\\renderers\\index.md": {
+    "created": "2025-03-08T20:51:52.794269",
+    "modified": "2025-03-08T20:51:52.798361"
+  },
+  "reference\\graphinate\\renderers\\matplotlib.md": {
+    "created": "2025-03-08T20:51:52.798361",
+    "modified": "2025-03-08T20:51:52.803367"
+  }
+}

{graphinate-0.6.0 → graphinate-0.8.0}/docs/examples/code.md

@@ -1,10 +1,20 @@
 # Code
 
+## GIT Commits
+
+=== "GIT Commits"
+
+    ``` python title="examples/code/git_commits.py" linenums="1"
+     --8<-- "examples/code/git_commits.py"
+    ```
+
+---
+
 ## Python AST
 
 === "Python AST"
 
-    ``` python title="examples/code/python_ast.py" linenums="1"
+    ```python title="examples/code/python_ast.py" linenums="1"
      --8<-- "examples/code/python_ast.py"
     ```
 
@@ -24,12 +34,7 @@
 
 === "Python Dependencies"
 
-    ``` python title="examples/code/python_dependencies.py" linenums="1"
+    ```python title="examples/code/python_dependencies.py" linenums="1"
      --8<-- "examples/code/python_dependencies.py"
     ```
 
-=== "Requirements"
-
-    ``` text title="examples/code/requirements.txt" linenums="1"
-    --8<-- "examples/code/requirements.txt"
-    ```

graphinate-0.8.0/docs/examples/social.md

@@ -0,0 +1,15 @@
+# Social
+
+## Music
+
+=== "Music"
+
+    ``` python title="examples/social/music.py" linenums="1"
+    --8<-- "examples/social/music.py"
+    ```
+
+=== "Dependencies"
+
+    ``` text title="examples/social/requirements.txt" linenums="1"
+    --8<-- "examples/social/requirements.txt"
+    ```

graphinate-0.8.0/docs/examples/web.md

@@ -0,0 +1,35 @@
+# Web
+
+## Web Page Links
+
+=== "Web Page Links"
+
+    ``` python title="examples/web/page_links.py" linenums="1"
+    --8<-- "examples/web/page_links.py"
+    ```
+
+=== "Dependencies"
+
+    ``` text title="examples/web/requirements.txt" linenums="1"
+    --8<-- "examples/web/requirements.txt"
+    ```
+
+=== "Plot"
+
+    ![Web Page Links](https://github.com/erivlis/graphinate/assets/9897520/ea5b00a2-75d1-4d0e-86af-272f20973149)
+
+---
+
+## HTML DOM
+
+=== "HTML DOM"
+
+    ``` python title="examples/web/html_dom.py" linenums="1"
+    --8<-- "examples/web/html_page_dom.py"
+    ```
+
+=== "Dependencies"
+
+    ``` text title="examples/web/requirements.txt" linenums="1"
+    --8<-- "examples/web/requirements.txt"
+    ```

{graphinate-0.6.0 → graphinate-0.8.0}/docs/gen_ref_pages.py

@@ -6,7 +6,7 @@ import mkdocs_gen_files
 
 nav = mkdocs_gen_files.Nav()
 
-ignore = ('server', 'cli.py', 'color.py', 'tools')
+ignore = ('cli.py', 'color.py', 'converters.py', 'constants.py', 'server', 'tools')
 
 for path in sorted(Path("src").rglob("*.py")):
     if any(v in path.as_posix() for v in ignore):

graphinate-0.8.0/docs/index.md

@@ -0,0 +1,4 @@
+# Graphinate. Data to Graphs.
+
+<img height="360" src="https://github.com/erivlis/graphinate/assets/9897520/dae41f9f-69e5-4eb5-a488-87ce7f51fa32" alt="Graphinate. Data to Graphs.">
+

{graphinate-0.6.0 → graphinate-0.8.0}/docs/intro.md

@@ -1,5 +1,18 @@
 # Introduction
 
+## Why?
+
+### Why Graphs?
+
+Graphs are a powerful data structure that can be used to model a wide range of problems.
+They are used in many fields, such as computer science, mathematics, physics, biology, and social sciences.
+
+### Why Graphinate?
+
+Usually the creation phase of a Graph is a tedious and error-prone process.
+It requires a lot of boilerplate code to transform data into a Graph.
+This process can be automated and simplified. This is where **Graphinate** comes in.
+
 ## What?
 
 ### What is Graphinate?
@@ -51,14 +64,19 @@ A Graph consists of two types of elements:
 
 A Graph Node can be any Python Hashable object. Usually it will be a primitive type such as an integer or a string,
 in particular when the node in itself has no specific meaning.
+
 One can also add attributes to the node to describe additional information. This information can be anything.
 Often attributes are used to store scalar dimensions (e.g., weight, area, width, age, etc.)
 or stylistic information (e.g., color, size, shape, label, etc.).
 
+Nodes are usually visualized as circles or points.
+
 #### Edges
 
 A Graph Edge is a pair of two node values. It can also have additional attributes in the same vain as a Graph Node.
 
+Edges are usually visualized as lines connecting two nodes.
+
 ### Defining a Graph
 
 One can define a Graph in two general ways:

{graphinate-0.6.0 → graphinate-0.8.0}/docs/start.md

@@ -23,6 +23,7 @@ pip install graphinate[server]
 ## Demo
 
 ```python title="Octagonal Graph"
+import examples.math.materializers
 import graphinate
 
 N: int = 8
@@ -40,8 +41,14 @@ def edge():
 
 
 # Choose builder and handler
-builder, handler = graphinate.materializers.Materializers.NetworkX_with_edge_labels.value
+builder, handler = examples.math.materializers.Materializers.NetworkX_with_edge_labels.value
 
-# Materialize the GraphModel
-graphinate.materialize(graph_model, builder=builder, builder_output_handler=handler)
+# Use the NetworkX Builder
+builder = graphinate.builders.NetworkxBuilder(graph_model)
+
+# build the NetworkX graph
+graph = builder.build()
+
+# plot the graph using matplotlib
+graphinate.plot(graph, with_edge_labels=True)
 ```