Graphinate 0.2.21__tar.gz → 0.3.0__tar.gz

{graphinate-0.2.21 → graphinate-0.3.0}/.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.9", "3.10", "3.11", "3.12" ]
+        python-version: [ "3.10", "3.11", "3.12" ]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}

{graphinate-0.2.21 → graphinate-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Graphinate
-Version: 0.2.21
+Version: 0.3.0
 Summary: Graphinate. Data to Graphs.
 Project-URL: Homepage, https://erivlis.github.io/graphinate
 Project-URL: Documentation, https://erivlis.github.io/graphinate
@@ -9,7 +9,7 @@ Project-URL: Source, https://github.com/erivlis/graphinate
 Author-email: Eran Rivlis <eran@rivlis.info>
 License-File: LICENSE
 Keywords: declarative,graph
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Intended Audience :: Science/Research
@@ -18,7 +18,6 @@ Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -26,13 +25,13 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: click>=8.1.7
-Requires-Dist: inflect>=7.2.1
+Requires-Dist: inflect>=7.3.0
 Requires-Dist: loguru>=0.7.2
-Requires-Dist: matplotlib>=3.8.4
+Requires-Dist: matplotlib>=3.9.0
 Requires-Dist: networkx>=3.3
-Requires-Dist: strawberry-graphql[asgi,opentelemetry]>=0.227.3
+Requires-Dist: strawberry-graphql[asgi,opentelemetry]>=0.235.1
 Provides-Extra: dev
 Requires-Dist: pipdeptree; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
@@ -45,17 +44,17 @@ Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocs-section-index; extra == 'docs'
 Requires-Dist: mkdocstrings-python; extra == 'docs'
 Provides-Extra: plot
-Requires-Dist: scipy>=1.12.0; extra == 'plot'
+Requires-Dist: scipy>=1.14.0; extra == 'plot'
 Provides-Extra: server
 Requires-Dist: starlette-prometheus; extra == 'server'
-Requires-Dist: uvicorn[standard]>=0.29.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30.1; extra == 'server'
 Provides-Extra: test
 Requires-Dist: faker>=23.2.1; extra == 'test'
-Requires-Dist: pytest-asyncio>=0.23.5; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23.7; extra == 'test'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
 Requires-Dist: pytest-randomly>=3.15.0; extra == 'test'
-Requires-Dist: pytest-xdist>=3.5.0; extra == 'test'
-Requires-Dist: pytest>=8.1.1; extra == 'test'
+Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
+Requires-Dist: pytest>=8.2.2; extra == 'test'
 Description-Content-Type: text/markdown
 
 # [Graphinate. Data to Graphs.](https://erivlis.github.io/graphinate/)
@@ -153,7 +152,7 @@ To install with server support
 pip install graphinate[server]
 ```
 
-**Graphinate** officially supports Python >= 3.9.
+**Graphinate** officially supports Python >= 3.10.
 
 ### Example
 

{graphinate-0.2.21 → graphinate-0.3.0}/README.md

@@ -93,7 +93,7 @@ To install with server support
 pip install graphinate[server]
 ```
 
-**Graphinate** officially supports Python >= 3.9.
+**Graphinate** officially supports Python >= 3.10.
 
 ### Example
 

{graphinate-0.2.21 → graphinate-0.3.0}/docs/start.md

@@ -17,7 +17,7 @@ To install with server support
 pip install graphinate[server]
 ```
 
-**Graphinate** officially supports Python 3.9+.
+**Graphinate** officially supports Python >= 3.10.
 
 ## Demo
 

{graphinate-0.2.21 → graphinate-0.3.0}/examples/code/python_ast.py

@@ -1,3 +1,10 @@
+"""
+Define functions to create an abstract syntax tree (AST) graph model using the 'graphinate' library.
+The 'ast_graph_model' function parses the AST of a specified class and creates nodes and edges for the graph model.
+The nodes represent AST nodes with their type and label, while the edges represent relationships between AST nodes.
+"""
+
+
 import ast
 import hashlib
 import inspect
@@ -35,6 +42,13 @@ def _ast_edge(parsed_ast: AST):
 
 
 def ast_graph_model():
+    """
+    Create an abstract syntax tree (AST) graph model.
+
+    Returns:
+        GraphModel: A graph model representing the AST nodes and their relationships.
+    """
+
     graph_model = graphinate.model(name='AST Graph')
 
     root_ast_node = ast.parse(inspect.getsource(graphinate.builders.D3Builder))

{graphinate-0.2.21 → graphinate-0.3.0}/examples/code/python_dependencies.py

@@ -6,6 +6,13 @@ from pipdeptree._non_host import handle_non_host_target
 
 
 def dependency_graph_model():
+    """
+    Generate a dependency graph model.
+
+    Returns:
+        GraphModel: A graph model representing the dependency graph.
+    """
+
     options = get_options(args=None)
     handle_non_host_target(options)
 

graphinate-0.3.0/examples/github/_client.py

@@ -0,0 +1,132 @@
+import functools
+import os
+from collections.abc import Iterable
+from typing import Optional, Union
+
+# see requirements.txt
+from github import Auth, Github
+from github.AuthenticatedUser import AuthenticatedUser
+from github.Commit import Commit
+from github.File import File
+from github.NamedUser import NamedUser
+from github.Repository import Repository
+
+# define a 'GITHUB_TOKEN' Env Var.
+token = os.getenv('GITHUB_TOKEN')
+
+# using an access token
+auth = Auth.Token(token)
+
+# Public Web GitHub
+client = Github(auth=auth)
+
+
+# or GitHub Enterprise with custom hostname
+# g = Github(auth=auth, base_url='https://{hostname}/api/v3')
+
+
+@functools.lru_cache
+def github_user(user_id: Optional[str] = None) -> Union[NamedUser, AuthenticatedUser]:
+    """
+    Get the GitHub user object for the specified user ID or the authenticated user.
+
+    Parameters:
+        user_id (Optional[str]): The ID of the user to retrieve.
+                                 If not provided, retrieve the authenticated user.
+
+    Returns:
+        Union[NamedUser, AuthenticatedUser]: The GitHub user object corresponding to the user ID provided,
+                                             or the authenticated user if no user ID is specified.
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
+    user = client.get_user(user_id) if user_id else client.get_user()
+    return user
+
+
+@functools.lru_cache
+def github_repositories(
+        user_id: Optional[str] = None,
+        repo_id: Optional[str] = None) -> Iterable[Repository]:
+    """
+    Get the GitHub repositories for the specified user ID or the authenticated user.
+
+    Parameters:
+        user_id (Optional[str]): The ID of the user whose repositories to retrieve.
+                                 If not provided, retrieve repositories of the authenticated user.
+        repo_id (Optional[str]): The ID of the repository to retrieve.
+                                 If provided, only that repository will be returned.
+
+    Returns:
+        Iterable[Repository]:
+        A list of GitHub repository objects corresponding to the user ID and/or repository ID provided.
+
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
+
+    user = github_user(user_id)
+    if repo_id and (repo := user.get_repo(name=repo_id)):
+        return [repo]
+    else:
+        return user.get_repos()
+
+
+def github_commits(
+        repo: Repository,
+        commit_id: Optional[str] = None) -> Iterable[Commit]:
+    """
+    Retrieve commits from a GitHub repository.
+
+    Parameters:
+        repo (Repository): The GitHub repository object from which to retrieve commits.
+        commit_id (str, optional): The ID of the commit to retrieve.
+                                   If provided, only that commit will be returned.
+                                   Defaults to None.
+
+    Returns:
+        Iterable[Commit]: An Iterable of Commit objects representing the commits in the repository.
+
+    Example:
+        To retrieve all commits from a repository:
+        ```
+        for commit in github_commits(repo):
+            print(commit)
+        ```
+
+        To retrieve a specific commit by ID:
+        ```
+        for commit in github_commits(repo, commit_id='abcdef123456'):
+            print(commit)
+        ```
+
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
+    if commit_id and (commit := repo.get_commit(sha=commit_id)):
+        yield commit
+    else:
+        yield from repo.get_commits()
+
+
+def github_files(
+        commit: Commit,
+        file_id: Optional[str] = None) -> Iterable[File]:
+    """
+    Retrieves Files from a GitHub Commit
+
+    Parameters:
+        commit (Commit): A Commit object from the GitHub API.
+        file_id (Optional[str]): An optional parameter specifying the filename to filter the files. Default is None.
+
+    Returns:
+        Iterable[File]: An Iterable of File objects based on the filtering criteria.
+
+    Note:
+        This function requires authentication with a valid GitHub token.
+    """
+    files: list[File] = commit.files
+    if file_id:
+        yield from [file for file in files if file.filename == file_id]
+    else:
+        yield from files

{graphinate-0.2.21 → graphinate-0.3.0}/examples/github/followers.py

@@ -1,3 +1,9 @@
+"""
+Defines a function `followers_graph_model` that creates a graph model representing GitHub followers.
+It recursively fetches followers of a given user up to a specified maximum depth.
+The function yields edges between users in the graph.
+"""
+
 from typing import Optional
 
 import graphinate
@@ -7,6 +13,16 @@ DEPTH = 0
 
 
 def followers_graph_model(max_depth: int = DEPTH):
+    """
+    Create a graph model representing GitHub followers.
+
+    Args:
+        max_depth (int): The maximum depth to fetch followers recursively (default is 0).
+
+    Returns:
+        GraphModel: A graph model representing GitHub followers.
+    """
+
     graph_model = graphinate.model(name='Github Followers Graph')
 
     def _followers(user_id: Optional[str] = None, depth: int = 0, **kwargs):

{graphinate-0.2.21 → graphinate-0.3.0}/examples/github/repositories.py

@@ -8,6 +8,13 @@ from _client import github_commits, github_files, github_repositories, github_us
 
 
 def repo_graph_model():  # noqa: C901
+    """
+    Create a graph model for GitHub repositories.
+
+    Returns:
+        GraphModel: A graph model representing GitHub repositories with nodes and edges.
+    """
+
     graph_model = graphinate.model(name='GitHub Repository Graph')
 
     @graph_model.edge

{graphinate-0.2.21 → graphinate-0.3.0}/examples/math/graph_atlas.py

@@ -35,6 +35,21 @@ def spiral_torus_edges(n, k):
 
 
 def atlas():
+    """
+    Generate a dictionary of various graph structures and models based on the provided atlas.
+    The function creates different types of graphs and models using NetworkX library.
+    The generated graphs include Tetrahedron, Cube, Octahedron, Dodecahedron, Icosahedron, Tesseract, Truncated Cube,
+    Truncated Tetrahedron, Ladder, Ring, Möbius, Cylinder, Spiral, Spiral Torus, and Circulant[10,[2]].
+    Additionally, the function includes adjacency mappings for specific named graphs like
+    Buckyball - Truncated Icosahedral Graph, D30 - Rhombic Triacontahedral Graph, Small Rhombicosidodecahedral Graph,
+    Small Rhombicuboctahedral Graph, Great Rhombicosidodecahedral Graph, Disdyakis Dodecahedral Graph,
+    Deltoidal Icositetrahedral Graph, Icosidodecahedral Graph, Deltoidal Hexecontahedral Graph, Kocohl74,
+    Utility Graph, Errara Graph, and Dragon Curve Blob 6.
+    The adjacency mappings define the connections between nodes in each named graph.
+    The function returns a dictionary
+    containing the named graphs as keys and their corresponding NetworkX graph objects as values.
+    """
+
     ladder_size = 16
     ladder = nx.ladder_graph(ladder_size)
 
@@ -775,6 +790,21 @@ def atlas():
 
 
 def models(iterable):
+    """
+    Generate a graph model based on the provided iterable of graphs.
+    The function creates a graph model named 'Graph Atlas' using the 'graphinate' library.
+    It then combines all the graphs from the input iterable into a single disjoint union graph using NetworkX library.
+    The function defines edges for the combined graph by iterating over all edges in the disjoint union graph and
+    yielding dictionaries with 'source' and 'target' keys representing the edge connections.
+    Finally, the function yields the created graph model containing the combined graph with defined edges.
+
+    Args:
+        iterable: An iterable containing graphs to be combined into a single graph model.
+
+    Yields:
+        GraphModel: A graph model containing the combined graph with defined edges.
+    """
+
     graph_model = graphinate.model('Graph Atlas')
 
     graph_atlas = nx.disjoint_union_all(g for _, g in iterable)

{graphinate-0.2.21 → graphinate-0.3.0}/examples/math/polygonal_graph.py

@@ -5,7 +5,17 @@ import networkx as nx
 N: int = 8
 
 
-def get_graph_model(number_of_sides: int = N):
+def polygonal_graph_model(number_of_sides: int = N):
+    """
+    Create a polygonal graph model.
+
+    Args:
+        number_of_sides (int): Number of sides in the polygon. Defaults to N.
+
+    Returns:
+        GraphModel: A graph model representing a polygonal graph.
+    """
+
     # Define GraphModel
     graph_model = graphinate.model(name="Octagonal Graph")
 
@@ -19,7 +29,7 @@ def get_graph_model(number_of_sides: int = N):
     return graph_model
 
 
-model = get_graph_model()
+model = polygonal_graph_model()
 
 if __name__ == '__main__':
     use_materialize = True

{graphinate-0.2.21 → graphinate-0.3.0}/examples/system/processes.py

@@ -7,6 +7,13 @@ import psutil
 
 
 def processes_graph_model():
+    """
+    Create a graph model representing processes and their parent-child relationships.
+
+    Returns:
+        GraphModel: A graph model representing processes and their parent-child relationships.
+    """
+
     graph_model = graphinate.model("Processes Graph")
 
     def processes() -> Iterable[psutil.Process]:

{graphinate-0.2.21 → graphinate-0.3.0}/examples/web/page_links.py

@@ -9,6 +9,16 @@ DEFAULT_MAX_DEPTH = 0
 
 
 def page_links_graph_model(max_depth: int = DEFAULT_MAX_DEPTH):
+    """
+    Create a graph model based on page links.
+
+    Args:
+        max_depth (int, optional): The maximum depth to crawl for page links. Defaults to DEFAULT_MAX_DEPTH.
+
+    Returns:
+        GraphModel: A graph model representing the page links.
+    """
+
     def _links(url: str, depth=0, **kwargs):
         reqs = requests.get(url)
         logger.debug('Analyzing Page: {url}')

{graphinate-0.2.21 → graphinate-0.3.0}/pyproject.toml

@@ -1,19 +1,18 @@
 [project]
 name = "Graphinate"
-version = "0.2.21"
+version = "0.3.0"
 authors = [
     { name = "Eran Rivlis", email = "eran@rivlis.info" },
 ]
 description = "Graphinate. Data to Graphs."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Intended Audience :: Information Technology",
     "Intended Audience :: Science/Research",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -29,11 +28,11 @@ classifiers = [
 keywords = ['graph', 'declarative']
 dependencies = [
     "click>=8.1.7",
-    "inflect>=7.2.1",
+    "inflect>=7.3.0",
     "loguru>=0.7.2",
-    "matplotlib>=3.8.4",
+    "matplotlib>=3.9.0",
     "networkx>=3.3",
-    "strawberry-graphql[asgi,opentelemetry]>=0.227.3"
+    "strawberry-graphql[asgi,opentelemetry]>=0.235.1"
 ]
 
 
@@ -60,18 +59,18 @@ docs = [
 ]
 test = [
     "faker>=23.2.1",
-    "pytest>=8.1.1",
-    "pytest-asyncio>=0.23.5",
+    "pytest>=8.2.2",
+    "pytest-asyncio>=0.23.7",
     "pytest-cov>=5.0.0",
     "pytest-randomly>=3.15.0",
-    "pytest-xdist>=3.5.0"
+    "pytest-xdist>=3.6.1"
 ]
 plot = [
-    "scipy>=1.12.0"
+    "scipy>=1.14.0"
 ]
 server = [
     "starlette-prometheus",
-    "uvicorn[standard]>=0.29.0"
+    "uvicorn[standard]>=0.30.1"
 ]
 
 

{graphinate-0.2.21 → graphinate-0.3.0}/src/graphinate/color.py

@@ -10,10 +10,11 @@ import networkx as nx
 def node_color_mapping(graph: nx.Graph, cmap: Union[str, mpl.colors.Colormap] = "tab20") -> Mapping:
     """
     Parameters:
-        graph: graph_id
-        cmap : str or `~matplotlib.colors.Colormap` - The colormap used to map values to RGBA colors.
+        graph: nx.Graph - The input graph for which node colors need to be mapped.
+        cmap: Union[str, mpl.colors.Colormap], optional - The colormap used to map values to RGBA colors.
+              Default is "tab20".
     Returns:
-        Nodes RGBA Color list.
+        Mapping - A dictionary mapping nodes to their corresponding RGBA colors based on the colormap.
     """
     type_lookup = {t: i for i, t in enumerate(graph.graph['node_types'].keys())}
     color_lookup = {node: type_lookup.get(data.get('type'), 0) for node, data in graph.nodes.data()}

{graphinate-0.2.21 → graphinate-0.3.0}/src/graphinate/materializers/matplotlib.py

@@ -8,11 +8,12 @@ def draw(graph: nx.Graph,
          with_node_labels: bool = True,
          with_edge_labels: bool = False):
     """
+    Draws the given networkx graph with optional node and edge labels.
 
-    Args:
-        graph:
-        with_node_labels:
-        with_edge_labels:
+    Parameters:
+        graph (nx.Graph): The input graph to be drawn.
+        with_node_labels (bool): Whether to display node labels. Default is True.
+        with_edge_labels (bool): Whether to display edge labels. Default is False.
 
     Returns:
         None
@@ -54,11 +55,12 @@ def plot(graph: nx.Graph,
          with_node_labels: bool = True,
          with_edge_labels: bool = False):
     """
+    Plots the given networkx graph with optional node and edge labels.
 
     Args:
-        graph:
-        with_node_labels:
-        with_edge_labels:
+        graph (nx.Graph): The input graph to be plotted.
+        with_node_labels (bool): Whether to display node labels. Default is True.
+        with_edge_labels (bool): Whether to display edge labels. Default is False.
 
     Returns:
         None

graphinate-0.3.0/src/graphinate/server/__init__.py

@@ -0,0 +1,80 @@
+import contextlib
+import webbrowser
+
+import strawberry
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.schemas import SchemaGenerator
+from starlette.types import ASGIApp
+from strawberry.asgi import GraphQL
+from strawberry.extensions.tracing import OpenTelemetryExtension
+
+from .starlette import routes
+
+DEFAULT_PORT: int = 8072
+
+GRAPHQL_ROUTE_PATH = "/graphql"
+
+
+def openapi_schema(request: Request) -> ASGIApp:
+    """
+    Generates an OpenAPI schema for the GraphQL API and other routes.
+
+    Args:
+        request (Request): The HTTP request object.
+
+    Returns:
+        ASGIApp: An OpenAPI response containing the schema for the specified routes.
+    """
+    schema_data = {
+        'openapi': '3.0.0',
+        'info': {'title': 'Graphinate API', 'version': '1.0'},
+        'paths': {
+            '/graphql': {'get': {'responses': {200: {'description': 'GraphQL'}}}},
+            '/graphiql': {'get': {'responses': {200: {'description': 'GraphiQL UI.'}}}},
+            '/metrics': {'get': {'responses': {200: {'description': 'Prometheus metrics.'}}}},
+            '/viewer': {'get': {'responses': {200: {'description': '3D Force-Directed Graph Viewer'}}}},
+            '/voyager': {'get': {'responses': {200: {'description': 'Voyager GraphQL Schema Viewer'}}}}
+        }
+    }
+
+    schema = SchemaGenerator(schema_data)
+    return schema.OpenAPIResponse(request=request)
+
+
+def graphql(graphql_schema: strawberry.Schema, port: int = DEFAULT_PORT):
+    """
+
+    Args:
+        graphql_schema:
+        port:
+
+    Returns:
+
+    """
+    graphql_schema.extensions.append(OpenTelemetryExtension)
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette):  # pragma: no cover
+        def open_url():
+            for app_name in ('voyager', 'graphiql', 'viewer'):
+                webbrowser.open(f'http://localhost:{port}/{app_name}')
+
+        open_url()
+        yield
+
+    graphql_app: GraphQL = GraphQL(graphql_schema)
+    app = Starlette(
+        lifespan=lifespan,
+        routes=routes()
+    )
+    app.add_route(GRAPHQL_ROUTE_PATH, graphql_app)
+    app.add_websocket_route(GRAPHQL_ROUTE_PATH, graphql_app)
+
+    from starlette_prometheus import PrometheusMiddleware, metrics
+    app.add_middleware(PrometheusMiddleware)
+    app.add_route("/metrics", metrics)
+    app.add_route("/schema", route=openapi_schema, include_in_schema=False)
+
+    import uvicorn
+    uvicorn.run(app, host='0.0.0.0', port=port)