topolib 0.5.0__tar.gz → 0.6.0__tar.gz

{topolib-0.5.0 → topolib-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topolib
-Version: 0.5.0
+Version: 0.6.0
 Summary: A compact Python library for modeling, analyzing, and visualizing optical network topologies.
 License: MIT
 License-File: LICENSE
@@ -50,8 +50,12 @@ Description-Content-Type: text/markdown
 
 ## 📂 Examples
 
-Explore ready-to-run usage examples in the [`examples/`](examples/) folder!  
-- [Show topology on a map](examples/show_topology_in_map.py) 🗺️  
+
+Explore ready-to-run usage examples in the [`examples/`](examples/) folder!
+
+- [Show topology on a map](examples/show_topology_in_map.py) 🗺️
+- [Show default topology in map](examples/show_default_topology_in_map.py) 🗺️
+- [Export topology as PNG](examples/export_topology_png.py) 🖼️
 - [Export topology to CSV and JSON](examples/export_csv_json.py) 📄
 - [Export topology and k-shortest paths for FlexNetSim](examples/export_flexnetsim.py) 🔀
 

{topolib-0.5.0 → topolib-0.6.0}/README.md

@@ -17,8 +17,12 @@
 
 ## 📂 Examples
 
-Explore ready-to-run usage examples in the [`examples/`](examples/) folder!  
-- [Show topology on a map](examples/show_topology_in_map.py) 🗺️  
+
+Explore ready-to-run usage examples in the [`examples/`](examples/) folder!
+
+- [Show topology on a map](examples/show_topology_in_map.py) 🗺️
+- [Show default topology in map](examples/show_default_topology_in_map.py) 🗺️
+- [Export topology as PNG](examples/export_topology_png.py) 🖼️
 - [Export topology to CSV and JSON](examples/export_csv_json.py) 📄
 - [Export topology and k-shortest paths for FlexNetSim](examples/export_flexnetsim.py) 🔀
 

{topolib-0.5.0 → topolib-0.6.0}/pyproject.toml

@@ -2,7 +2,7 @@
 [tool.poetry]
 name = "topolib"
 # Poetry requires a version field, but poetry-dynamic-versioning will override it
-version = "0.5.0"
+version = "0.6.0"
 description = "A compact Python library for modeling, analyzing, and visualizing optical network topologies."
 authors = ["Danilo Bórquez-Paredes <danilo.borquez.p@uai.cl>"]
 license = "MIT"

topolib-0.6.0/topolib/elements/__init__.py

@@ -0,0 +1,5 @@
+
+from .node import Node
+from .link import Link
+
+__all__ = ["Node", "Link"]

{topolib-0.5.0 → topolib-0.6.0}/topolib/elements/link.py

@@ -9,8 +9,6 @@ if TYPE_CHECKING:
 class Link:
 
     """
-    .. :noindex:
-
     Represents a link between two nodes.
 
     Parameters
@@ -24,17 +22,6 @@ class Link:
     length : float
         Length of the link (must be non-negative).
 
-    Attributes
-    ----------
-    id : int
-        Unique identifier for the link.
-    source : :class:`topolib.elements.node.Node`
-        Source node of the link.
-    target : :class:`topolib.elements.node.Node`
-        Target node of the link.
-    length : float
-        Length of the link.
-
     Examples
     --------
     >>> link = Link(1, nodeA, nodeB, 10.5)
@@ -50,8 +37,6 @@ class Link:
     @property
     def id(self) -> int:
         """
-        .. :noindex:
-
         int: Unique identifier for the link.
         """
         return self._id
@@ -66,8 +51,6 @@ class Link:
     @property
     def source(self) -> "Node":
         """
-        .. :noindex:
-
         :class:`topolib.elements.node.Node`: Source node of the link.
         """
         return self._source
@@ -87,8 +70,6 @@ class Link:
     @property
     def target(self) -> "Node":
         """
-        .. :noindex:
-
         :class:`topolib.elements.node.Node`: Target node of the link.
         """
         return self._target
@@ -108,8 +89,6 @@ class Link:
     @property
     def length(self) -> float:
         """
-        .. :noindex:
-
         float: Length of the link (non-negative).
         """
         return self._length

{topolib-0.5.0 → topolib-0.6.0}/topolib/elements/node.py

@@ -9,8 +9,6 @@ from typing import Tuple
 
 class Node:
     """
-    .. :noindex:
-
     Represents a node in an optical network topology.
 
     :param id: Unique identifier for the node.

{topolib-0.5.0 → topolib-0.6.0}/topolib/topology/topology.py

@@ -10,12 +10,23 @@ https://github.com/networkx/networkx/blob/main/LICENSE.txt
 
 from typing import List, Optional, Any
 from numpy.typing import NDArray
-import numpy as np
-import networkx as nx
+
+
+# Standard library imports
 import json
-import jsonschema
 import csv
+from pathlib import Path
+
+# Third-party imports
+import numpy as np
 import networkx as nx
+import jsonschema
+import matplotlib.pyplot as plt
+import contextily as ctx
+import geopandas as gpd
+from shapely.geometry import Point
+
+# Local imports
 from topolib.elements.node import Node
 from topolib.elements.link import Link
 
@@ -144,7 +155,8 @@ class Topology:
         # Crear un dict para mapear id a Node
         node_dict = {n.id: n for n in nodes}
         links = [
-            Link(l["id"], node_dict[l["src"]], node_dict[l["dst"]], l["length"])
+            Link(l["id"], node_dict[l["src"]],
+                 node_dict[l["dst"]], l["length"])
             for l in data["links"]
         ]
         name = data.get("name", None)
@@ -217,40 +229,35 @@ class Topology:
 
     def export_to_json(self, file_path: str) -> None:
         """
-        Exporta la topología actual al formato JSON usado en la carpeta assets.
+        Export the current topology to the JSON format used in the assets folder.
 
-        :param file_path: Ruta donde se guardará el archivo JSON.
+        :param file_path: Path where the JSON file will be saved.
         :type file_path: str
 
-        **Ejemplo de uso**
-            >>> topo.export_to_json("/ruta/salida.json")
-
-        **Ejemplo de formato de salida**
-        {
-            "name": "Abilene",
-            "nodes": [
-                {
-                    "id": 0,
-                    "name": "Seattle",
-                    "weight": 0,
-                    "longitude": -122.3328481,
-                    "latitude": 47.6061389,
-                    "pop": 780995,
-                    "DC": 58,
-                    "IXP": 5
-                },
-                # ...
-            ],
-            "links": [
-                {
-                    "id": 0,
-                    "src": 0,
-                    "dst": 1,
-                    "length": 1482.26
-                },
-                # ...
-            ]
-        }
+        Example usage::
+
+            topo.export_to_json("/path/output.json")
+
+        Example output format::
+
+            {
+                "name": "Abilene",
+                "nodes": [
+                    {
+                        "id": 0,
+                        "name": "Seattle",
+                        ...
+                    }
+                ],
+                "links": [
+                    {
+                        "id": 0,
+                        "src": 0,
+                        "dst": 1,
+                        "length": 1482.26
+                    }
+                ]
+            }
         """
         nodes_list: list[dict[str, Any]] = []
         for n in self.nodes:
@@ -300,7 +307,8 @@ class Topology:
             writer = csv.writer(f)
             # Header
             writer.writerow(
-                ["id", "name", "weight", "latitude", "longitude", "pop", "DC", "IXP"]
+                ["id", "name", "weight", "latitude",
+                    "longitude", "pop", "DC", "IXP"]
             )
             for n in self.nodes:
                 writer.writerow(
@@ -376,21 +384,23 @@ class Topology:
         :param k: Number of shortest paths to compute for each node pair (default: 3).
         :type k: int
 
-        The output format matches Flex Net Sim's routes.json:
-        {
-            "name": self.name,
-            "alias": self.name,
-            "routes": [
-                {"src": <id>, "dst": <id>, "paths": [[id, ...], ...]},
-                ...
-            ]
-        }
+        Example output format::
+
+            {
+                "name": self.name,
+                "alias": self.name,
+                "routes": [
+                    {"src": <id>, "dst": <id>, "paths": [[id, ...], ...]},
+                    ...
+                ]
+            }
         """
 
         # Build a weighted graph using link length as edge weight
         G = nx.DiGraph()
         for l in self.links:
-            G.add_edge(l.source.id, l.target.id, weight=getattr(l, "length", 1))
+            G.add_edge(l.source.id, l.target.id,
+                       weight=getattr(l, "length", 1))
         routes = []
         node_ids = [n.id for n in self.nodes]
         for src in node_ids:
@@ -399,7 +409,8 @@ class Topology:
                     continue
                 try:
                     # Compute k shortest paths using link length as weight
-                    paths_gen = nx.shortest_simple_paths(G, src, dst, weight="weight")
+                    paths_gen = nx.shortest_simple_paths(
+                        G, src, dst, weight="weight")
                     paths = []
                     for i, path in enumerate(paths_gen):
                         if i >= k:
@@ -415,3 +426,88 @@ class Topology:
         }
         with open(file_path, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=4, ensure_ascii=False)
+
+    @classmethod
+    def list_available_topologies(cls) -> list[dict]:
+        """
+        List available topologies in the assets folder.
+
+        Returns a list of dictionaries with keys:
+        - 'name': topology name (filename without extension)
+        - 'nodes': number of nodes
+        - 'links': number of links
+
+        :return: List of available topologies with metadata.
+        :rtype: list[dict]
+        """
+        asset_dir = Path(__file__).parent.parent / "assets"
+        result = []
+        for json_path in asset_dir.glob("*.json"):
+            try:
+                topo = cls.from_json(str(json_path))
+                result.append({
+                    "name": json_path.stem,
+                    "nodes": len(topo.nodes),
+                    "links": len(topo.links),
+                })
+            except Exception:
+                continue
+        return result
+
+    @staticmethod
+    def load_default_topology(name: str) -> "Topology":
+        """
+        Load a default topology from the assets folder by name (filename without extension).
+
+        :param name: Name of the topology asset (without .json extension)
+        :type name: str
+        :return: Topology instance loaded from the asset file
+        :rtype: Topology
+        :raises FileNotFoundError: If the asset file does not exist
+        """
+        asset_dir = Path(__file__).parent.parent / "assets"
+        asset_path = asset_dir / f"{name}.json"
+        if not asset_path.exists():
+            raise FileNotFoundError(
+                f"Topology asset '{name}.json' not found in assets directory.")
+        return Topology.from_json(str(asset_path))
+
+    def export_graph_png(self, filename: str, dpi: int = 150) -> None:
+        """
+        Export the topology graph as a PNG image using Matplotlib and Contextily.
+
+        :param filename: Output PNG file path.
+        :type filename: str
+        :param dpi: Dots per inch for the saved image (default: 150).
+        :type dpi: int
+        """
+        lons = [node.longitude for node in self.nodes]
+        lats = [node.latitude for node in self.nodes]
+        names = [node.name for node in self.nodes]
+        gdf = gpd.GeoDataFrame(
+            {"name": names},
+            geometry=[Point(x, y) for x, y in zip(lons, lats)],
+            crs="EPSG:4326",
+        )
+        gdf = gdf.to_crs(epsg=3857)
+        node_id_to_xy = {node.id: (pt.x, pt.y)
+                         for node, pt in zip(self.nodes, gdf.geometry)}
+        topo_name = self.name if self.name else "Topology"
+        fig, ax = plt.subplots(figsize=(10, 7))
+        fig.suptitle(topo_name, fontsize=16)
+        for link in self.links:
+            src_id = link.source.id
+            tgt_id = link.target.id
+            if src_id in node_id_to_xy and tgt_id in node_id_to_xy:
+                x0, y0 = node_id_to_xy[src_id]
+                x1, y1 = node_id_to_xy[tgt_id]
+                ax.plot([x0, x1], [y0, y1], color="gray",
+                        linewidth=1, alpha=0.7, zorder=2)
+        gdf.plot(ax=ax, color="blue", markersize=40, zorder=5)
+        for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
+            ax.text(x, y, name, fontsize=8, ha="right",
+                    va="bottom", color="black")
+        ax.set_axis_off()
+        plt.tight_layout()
+        plt.savefig(filename, dpi=dpi)
+        plt.close(fig)

{topolib-0.5.0 → topolib-0.6.0}/topolib/visualization/mapview.py

@@ -67,9 +67,61 @@ class MapView:
         # Draw nodes
         gdf.plot(ax=ax, color="blue", markersize=40, zorder=5)
         for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
-            ax.text(x, y, name, fontsize=8, ha="right", va="bottom", color="black")
+            ax.text(x, y, name, fontsize=8, ha="right",
+                    va="bottom", color="black")
         ctx.add_basemap(ax, source=ctx.providers.OpenStreetMap.Mapnik)
         ax.set_axis_off()
         ax.set_title(f"Nodes and links ({topo_name})")
         plt.tight_layout()
         plt.show()
+
+    def export_map_png(self, filename: str, dpi: int = 150) -> None:
+        """
+        Export the topology map as a PNG image using Matplotlib and Contextily.
+
+        :param filename: Output PNG file path.
+        :type filename: str
+        :param dpi: Dots per inch for the saved image (default: 150).
+        :type dpi: int
+        """
+        lons: list[float] = [node.longitude for node in self.topology.nodes]
+        lats: list[float] = [node.latitude for node in self.topology.nodes]
+        names: list[str] = [node.name for node in self.topology.nodes]
+        gdf: gpd.GeoDataFrame = gpd.GeoDataFrame(
+            {"name": names},
+            geometry=[Point(x, y) for x, y in zip(lons, lats)],
+            crs="EPSG:4326",
+        )
+        gdf = gdf.to_crs(epsg=3857)
+
+        node_id_to_xy = {
+            node.id: (pt.x, pt.y) for node, pt in zip(self.topology.nodes, gdf.geometry)
+        }
+
+        topo_name = getattr(self.topology, "name", None)
+        if topo_name is None:
+            topo_name = getattr(self.topology, "_name", None)
+        if topo_name is None:
+            topo_name = "Topology"
+
+        fig, ax = plt.subplots(figsize=(10, 7))
+        fig.suptitle(topo_name, fontsize=16)
+        for link in getattr(self.topology, "links", []):
+            src_id = getattr(link, "source").id
+            tgt_id = getattr(link, "target").id
+            if src_id in node_id_to_xy and tgt_id in node_id_to_xy:
+                x0, y0 = node_id_to_xy[src_id]
+                x1, y1 = node_id_to_xy[tgt_id]
+                ax.plot(
+                    [x0, x1], [y0, y1], color="gray", linewidth=1, alpha=0.7, zorder=2
+                )
+        gdf.plot(ax=ax, color="blue", markersize=40, zorder=5)
+        for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
+            ax.text(x, y, name, fontsize=8, ha="right",
+                    va="bottom", color="black")
+        ctx.add_basemap(ax, source=ctx.providers.OpenStreetMap.Mapnik)
+        ax.set_axis_off()
+        ax.set_title(f"Nodes and links ({topo_name})")
+        plt.tight_layout()
+        plt.savefig(filename, dpi=dpi)
+        plt.close(fig)

topolib-0.5.0/topolib/elements/__init__.py

@@ -1,8 +0,0 @@
-
-from .node import Node
-from .link import Link
-
-# Hide re-exported Link from Sphinx index to avoid duplicate warnings
-Link.__doc__ = """.. :noindex:"""
-
-__all__ = ["Node", "Link"]