topolib 0.0.0__py3-none-any.whl

diagrams/class_diagram.puml

@@ -0,0 +1,75 @@
+@startuml TopolibModularClassDiagram
+
+package topolib.topology {
+    class Topology {
+        - {static} topologies
+        -nodes: List<Node>
+        -links: List<Link>
+        +add_node(node: Node)
+        +remove_node(node_id: int)
+        +add_link(link: Link)
+        +remove_link(link_id: int)
+        +update_metrics()
+        +export_json(): str
+        +get_geographic_area(): float
+        +get_diameter(): float
+        +calculate_laplacian(): Matrix
+        +get_shortest_paths(s: int, d: int, N: int): List<Path>
+        +get_disjoint_paths(s: int, d: int, N: int): List<Path>
+    }
+
+    class Path {
+        -nodes: List<Node>
+        -total_length: float
+        +get_summary(): str
+    }
+}
+
+package topolib.elements {
+    class Node {
+        -id: int
+        -name: str
+        -latitude: float
+        -longitude: float
+        +coordinates(): Tuple[float, float]
+    }
+
+    class Link {
+        -id: int
+        -source: Node
+        -target: Node
+        -length: float
+    }
+}
+
+package topolib.analysis {
+    class Metrics {
+        +get_max_node_degree(topology: Topology): int
+        +get_min_node_degree(topology: Topology): int
+        +get_avg_node_degree(topology: Topology): float
+        +get_max_link_length(topology: Topology): float
+        +get_min_link_length(topology: Topology): float
+        +get_avg_link_length(topology: Topology): float
+        +get_connection_matrix(topology: Topology): numpy.ndarray
+        +get_link_value_matrix(topology: Topology): numpy.ndarray
+        +get_node_degree_matrix(topology: Topology): numpy.ndarray
+    }
+}
+
+package topolib.visualization {
+    class MapView {
+        +display_osm(topology: Topology)
+        +display_paper(topology: Topology)
+    }
+}
+
+topolib.topology.Topology --> topolib.elements.Node : uses
+topolib.topology.Topology --> topolib.elements.Link : uses
+topolib.topology.Topology --> topolib.analysis.Metrics : calculates
+topolib.topology.Topology --> topolib.visualization.MapView : visualizes
+topolib.topology.Topology --> topolib.topology.Path : generates
+
+topolib.elements.Link --> topolib.elements.Node : connects
+topolib.topology.Path --> topolib.elements.Node : traverses
+
+@enduml

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

docs/source/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Add project root to sys.path for autodoc --
+import os
+import sys
+sys.path.insert(0, os.path.abspath(
+    os.path.join(os.path.dirname(__file__), '../../')))
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'topolib'
+copyright = '2025, Danilo Borquez'
+author = 'Danilo Borquez'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+language = 'en'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,33 @@
+.. topolib documentation master file, created by
+   sphinx-quickstart on Wed Oct  8 18:21:25 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+Welcome to Topolib's documentation!
+===================================
+
+**Topolib** is a compact Python library for modeling, analyzing, and visualizing optical network topologies.
+It provides a clean, object-oriented API for nodes, links, topologies, metrics, and visualization tools, making it ideal for research, teaching, and rapid prototyping in network science and engineering.
+
+**Key features:**
+
+- Modular design: elements, topology, analysis, and visualization
+- Easy-to-use classes for nodes, links, and paths
+- Built-in metrics and analysis helpers
+- JSON import/export and interoperability
+- Ready for integration with Sphinx, Read the Docs, and PyPI
+
+Get started by exploring the modules below, or see the README for quick usage examples.
+
+.. note::
+   This documentation is generated automatically from the source code and is always up to date with the latest release.
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+

docs/source/modules.rst

@@ -0,0 +1,7 @@
+topolib
+=======
+
+.. toctree::
+   :maxdepth: 4
+
+   topolib

docs/source/topolib.analysis.rst

@@ -0,0 +1,21 @@
+topolib.analysis package
+========================
+
+Submodules
+----------
+
+topolib.analysis.metrics module
+-------------------------------
+
+.. automodule:: topolib.analysis.metrics
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: topolib.analysis
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/topolib.elements.rst

@@ -0,0 +1,23 @@
+topolib.elements package
+========================
+
+Submodules
+----------
+
+topolib.elements.link module
+----------------------------
+
+.. automodule:: topolib.elements.link
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+topolib.elements.node module
+----------------------------
+
+.. automodule:: topolib.elements.node
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+

docs/source/topolib.rst

@@ -0,0 +1,20 @@
+topolib package
+===============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   topolib.analysis
+   topolib.elements
+   topolib.topology
+
+Module contents
+---------------
+
+.. automodule:: topolib
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/topolib.topology.rst

@@ -0,0 +1,29 @@
+topolib.topology package
+========================
+
+Submodules
+----------
+
+topolib.topology.path module
+----------------------------
+
+.. automodule:: topolib.topology.path
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+topolib.topology.topology module
+--------------------------------
+
+.. automodule:: topolib.topology.topology
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: topolib.topology
+   :members:
+   :undoc-members:
+   :show-inheritance:

examples/show_topology_in_map.py

@@ -0,0 +1,11 @@
+from topolib.visualization.mapview import MapView
+from topolib.topology.topology import Topology
+
+if __name__ == "__main__":
+    # Load real topology from JSON (you can change the file to another one from assets)
+    topo = Topology.from_json("topolib/assets/China_pop.json")
+    mapview = MapView(topo)
+    mapview.show_map()
+    topo = Topology.from_json("topolib/assets/DT-50_pop.json")
+    mapview = MapView(topo)
+    mapview.show_map()

tests/__init__.py

@@ -0,0 +1 @@
+# This file marks the tests directory as a Python package.

tests/test_link.py

@@ -0,0 +1,77 @@
+import pytest
+from topolib.elements.node import Node
+from topolib.elements.link import Link
+
+
+def test_link_creation_and_properties():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    link = Link(10, n1, n2, 5.5)
+
+    assert link.id == 10
+    assert link.source is n1
+    assert link.target is n2
+    assert link.length == 5.5
+
+
+def test_link_length_validation():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    with pytest.raises(ValueError):
+        Link(1, n1, n2, -1)
+    with pytest.raises(TypeError):
+        Link(1, n1, n2, "not-a-number")
+
+
+def test_link_endpoint_validation():
+    n1 = Node(1, "A", 0.0, 0.0)
+
+    # a dummy object without node attributes
+    class Dummy:
+        pass
+
+    with pytest.raises(TypeError):
+        Link(1, Dummy(), n1, 1.0)
+    with pytest.raises(TypeError):
+        Link(1, n1, Dummy(), 1.0)
+
+
+def test_endpoints_and_repr():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    link = Link(2, n1, n2, 10)
+    assert link.endpoints() == (n1, n2)
+    assert "Link(id=2" in repr(link)
+
+
+def test_link_setters_and_errors():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    link = Link(99, n1, n2, 1.0)
+    # Test id setter
+    link.id = 123
+    assert link.id == 123
+
+    # Test source setter error
+    class Dummy:
+        pass
+
+    with pytest.raises(TypeError):
+        link.source = Dummy()
+    # Test target setter error
+    with pytest.raises(TypeError):
+        link.target = Dummy()
+    # Test length setter error (non-numeric)
+    with pytest.raises(TypeError):
+        link.length = "bad"
+    # Test length setter error (negative)
+    with pytest.raises(ValueError):
+        link.length = -5
+
+
+def test_link_length_setter_typeerror():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    link = Link(1, n1, n2, 1.0)
+    with pytest.raises(TypeError):
+        link.length = object()  # No convertible a float, cubre el except

tests/test_mapview.py

@@ -0,0 +1,33 @@
+"""
+Unit tests for the MapView class in topolib.visualization.mapview.
+Covers interface and error raising for unimplemented methods.
+"""
+
+import pytest
+from topolib.visualization import MapView
+from topolib.topology import Topology
+from topolib.elements.node import Node
+from topolib.elements.link import Link
+import matplotlib.pyplot as plt
+
+
+def test_mapview_show_map_runs(monkeypatch):
+    """
+    Smoke test for MapView.show_map():
+    - Creates a minimal topology (2 nodes, 1 link)
+    - Instantiates MapView
+    - Mocks plt.show to avoid GUI popup
+    - Asserts that show_map() runs without error
+    """
+    # Create minimal topology
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    l1 = Link(1, n1, n2, 10.0)
+    topo = Topology(nodes=[n1, n2], links=[l1], name="TestNet")
+    mv = MapView(topo)
+
+    # Mock plt.show to avoid opening a window
+    monkeypatch.setattr(plt, "show", lambda: None)
+
+    # Should not raise any exception
+    mv.show_map()

tests/test_metrics.py

@@ -0,0 +1,53 @@
+import pytest
+
+from topolib.analysis.metrics import Metrics
+from topolib.topology import Topology
+
+
+from topolib.elements.node import Node
+from topolib.elements.link import Link
+
+
+def test_node_degree():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    n3 = Node(3, "C", 2.0, 2.0)
+    l1 = Link(1, n1, n2, 10)
+    l2 = Link(2, n2, n3, 20)
+    topo = Topology(nodes=[n1, n2, n3], links=[l1, l2])
+    result = Metrics.node_degree(topo)
+    assert result == {1: 1, 2: 2, 3: 1}
+
+
+def test_link_length_stats():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    l1 = Link(1, n1, n2, 10)
+    l2 = Link(2, n2, n1, 20)
+    topo = Topology(nodes=[n1, n2], links=[l1, l2])
+    stats = Metrics.link_length_stats(topo)
+    assert stats["min"] == 10
+    assert stats["max"] == 20
+    assert stats["avg"] == 15
+    # Empty case
+    topo_empty = Topology()
+    assert Metrics.link_length_stats(topo_empty) == {
+        "min": None,
+        "max": None,
+        "avg": None,
+    }
+
+
+def test_connection_matrix():
+    n1 = Node(1, "A", 0.0, 0.0)
+    n2 = Node(2, "B", 1.0, 1.0)
+    n3 = Node(3, "C", 2.0, 2.0)
+    l1 = Link(1, n1, n2, 10)
+    l2 = Link(2, n2, n3, 20)
+    topo = Topology(nodes=[n1, n2, n3], links=[l1, l2])
+    matrix = Metrics.connection_matrix(topo)
+    assert matrix == [
+        [0, 1, 0],
+        [1, 0, 1],
+        [0, 1, 0],
+    ]

tests/test_node.py

@@ -0,0 +1,44 @@
+import pytest
+from topolib.elements.node import Node
+
+
+def test_node_creation():
+    node = Node(1, "A", -33.45, -70.66, weight=2.5, pop=100000)
+    assert node.id == 1
+    assert node.name == "A"
+    assert node.latitude == -33.45
+    assert node.longitude == -70.66
+    assert node.weight == 2.5
+    assert node.pop == 100000
+
+
+def test_node_setters():
+    node = Node(0, "", 0.0, 0.0)
+    node.id = 10
+    node.name = "TestNode"
+    node.latitude = 55.5
+    node.longitude = -120.1
+    node.weight = 3.7
+    node.pop = 12345
+    assert node.id == 10
+    assert node.name == "TestNode"
+    assert node.latitude == 55.5
+    assert node.longitude == -120.1
+    assert node.weight == 3.7
+    assert node.pop == 12345
+
+
+def test_node_coordinates():
+    node = Node(2, "B", 10.0, 20.0)
+    coords = node.coordinates()
+    assert coords == (10.0, 20.0)
+
+
+def test_node_dc_ixp_attributes():
+    n = Node(1, "A", 0.0, 0.0, dc=42, ixp=7)
+    assert n.dc == 42
+    assert n.ixp == 7
+    n.dc = 100
+    n.ixp = 3
+    assert n.dc == 100
+    assert n.ixp == 3

tests/test_path.py

@@ -0,0 +1,46 @@
+import pytest
+from topolib.topology.path import Path
+
+
+class DummyNode:
+    def __init__(self, id):
+        self.id = id
+
+    def __repr__(self):
+        return f"Node({self.id})"
+
+
+class DummyLink:
+    def __init__(self, id):
+        self.id = id
+
+    def __repr__(self):
+        return f"Link({self.id})"
+
+
+def test_path_creation():
+    nodes = [DummyNode(1), DummyNode(2), DummyNode(3)]
+    links = [DummyLink("a"), DummyLink("b")]
+    path = Path(nodes, links)
+    assert path.nodes == nodes
+    assert path.links == links
+    assert path.length() == 2
+    assert path.hop_count() == 2
+    assert path.endpoints() == (nodes[0], nodes[-1])
+
+
+def test_path_invalid():
+    with pytest.raises(ValueError):
+        Path([], [])
+    with pytest.raises(ValueError):
+        Path([DummyNode(1)], [])
+    with pytest.raises(ValueError):
+        Path([DummyNode(1), DummyNode(2)], [DummyLink("a"), DummyLink("b")])
+
+
+def test_path_repr():
+    nodes = [DummyNode(1), DummyNode(2)]
+    links = [DummyLink("a")]
+    path = Path(nodes, links)
+    s = repr(path)
+    assert s.startswith("Path(nodes=")