topolib 0.3.0__tar.gz

topolib-0.3.0/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 Danilo Bórquez-Paredes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topolib-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+recursive-include topolib/assets *.json
+recursive-include diagrams *.puml
+recursive-include docs/source *

topolib-0.3.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: topolib
+Version: 0.3.0
+Summary: A compact Python library for modeling, analyzing, and visualizing optical network topologies.
+Author-email: Danilo Bórquez-Paredes <danilo.borquez.p@uai.cl>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/DaniloBorquez/topolib
+Project-URL: Documentation, https://topolib.readthedocs.io/
+Project-URL: Source, https://gitlab.com/DaniloBorquez/topolib
+Project-URL: Issues, https://gitlab.com/DaniloBorquez/topolib/-/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: networkx>=2.6
+Dynamic: license-file
+
+# Topolib 🚀
+
+
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)
+[![Issues](https://img.shields.io/badge/issues-on%20GitLab-blue.svg)](https://gitlab.com/DaniloBorquez/topolib/-/issues)
+[![Develop coverage](https://gitlab.com/DaniloBorquez/topolib/badges/develop/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=develop)
+[![Release coverage](https://gitlab.com/DaniloBorquez/topolib/badges/release/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=release)
+[![Documentation Status](https://readthedocs.org/projects/topolib/badge/?version=latest)](https://topolib.readthedocs.io/en/latest/?badge=latest)
+
+A compact Python library for working with optical network topologies: nodes, links, metrics and visualization tools. 🌐
+
+## Overview
+
+Topolib models network topologies with three main modules:
+
+- `topolib.elements` — Definitions of elementary building blocks
+  - `Node` — represents a network node with id, name and geographic coordinates
+  - `Link` — connects two `Node` objects and stores link length and id
+
+- `topolib.topology` — High-level topology model
+  - `Topology` — holds nodes and links, provides methods to add/remove nodes and links, compute metrics, export JSON, and compute shortest/disjoint paths
+  - `Path` — represents a path through the topology
+
+- `topolib.analysis` — Metrics and analysis helpers
+  - `Metrics` — functions to compute node degree, link length statistics, connection matrices, etc.
+
+- `topolib.visualization` — Visualization helpers
+  - `MapView` — functions to display topology with OSM or paper-style maps
+
+(These components are derived from the project's class diagram in `diagrams/class_diagram.puml`.)
+
+## 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 Sphinx, Read the Docs, and PyPI
+
+## Quickstart ⚡
+
+Create and activate a virtual environment, install dev dependencies and run tests:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -r dev-requirements.txt
+python -m pytest -q
+```
+
+## Installation
+
+```bash
+pip install topolib
+```
+
+Or for development:
+
+```bash
+git clone https://gitlab.com/DaniloBorquez/topolib.git
+cd topolib
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install -r dev-requirements.txt
+```
+
+## Documentation
+
+Full documentation: [https://topolib.readthedocs.io/](https://topolib.readthedocs.io/)
+
+## Basic usage example
+
+```py
+from topolib.elements.node import Node
+from topolib.topology.topology import Topology
+
+# Create nodes
+n1 = Node(1, 'A', 10.0, 20.0)
+n2 = Node(2, 'B', 11.0, 21.0)
+
+# Build topology
+topo = Topology()
+topo.add_node(n1)
+topo.add_node(n2)
+# add links, compute metrics, visualize
+```
+
+
+## Development 🛠️
+
+See `CONTRIBUTING.md` for development guidelines, commit message rules and pre-commit setup.
+
+
+
+## Class diagram
+
+![](diagrams/class_diagram.puml)
+
+(If you prefer a rendered image of the UML, render the PlantUML file locally or in your CI pipeline.)
+
+## License
+
+See `LICENSE` in the project root.

topolib-0.3.0/README.md

@@ -0,0 +1,105 @@
+# Topolib 🚀
+
+
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)
+[![Issues](https://img.shields.io/badge/issues-on%20GitLab-blue.svg)](https://gitlab.com/DaniloBorquez/topolib/-/issues)
+[![Develop coverage](https://gitlab.com/DaniloBorquez/topolib/badges/develop/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=develop)
+[![Release coverage](https://gitlab.com/DaniloBorquez/topolib/badges/release/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=release)
+[![Documentation Status](https://readthedocs.org/projects/topolib/badge/?version=latest)](https://topolib.readthedocs.io/en/latest/?badge=latest)
+
+A compact Python library for working with optical network topologies: nodes, links, metrics and visualization tools. 🌐
+
+## Overview
+
+Topolib models network topologies with three main modules:
+
+- `topolib.elements` — Definitions of elementary building blocks
+  - `Node` — represents a network node with id, name and geographic coordinates
+  - `Link` — connects two `Node` objects and stores link length and id
+
+- `topolib.topology` — High-level topology model
+  - `Topology` — holds nodes and links, provides methods to add/remove nodes and links, compute metrics, export JSON, and compute shortest/disjoint paths
+  - `Path` — represents a path through the topology
+
+- `topolib.analysis` — Metrics and analysis helpers
+  - `Metrics` — functions to compute node degree, link length statistics, connection matrices, etc.
+
+- `topolib.visualization` — Visualization helpers
+  - `MapView` — functions to display topology with OSM or paper-style maps
+
+(These components are derived from the project's class diagram in `diagrams/class_diagram.puml`.)
+
+## 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 Sphinx, Read the Docs, and PyPI
+
+## Quickstart ⚡
+
+Create and activate a virtual environment, install dev dependencies and run tests:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -r dev-requirements.txt
+python -m pytest -q
+```
+
+## Installation
+
+```bash
+pip install topolib
+```
+
+Or for development:
+
+```bash
+git clone https://gitlab.com/DaniloBorquez/topolib.git
+cd topolib
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install -r dev-requirements.txt
+```
+
+## Documentation
+
+Full documentation: [https://topolib.readthedocs.io/](https://topolib.readthedocs.io/)
+
+## Basic usage example
+
+```py
+from topolib.elements.node import Node
+from topolib.topology.topology import Topology
+
+# Create nodes
+n1 = Node(1, 'A', 10.0, 20.0)
+n2 = Node(2, 'B', 11.0, 21.0)
+
+# Build topology
+topo = Topology()
+topo.add_node(n1)
+topo.add_node(n2)
+# add links, compute metrics, visualize
+```
+
+
+## Development 🛠️
+
+See `CONTRIBUTING.md` for development guidelines, commit message rules and pre-commit setup.
+
+
+
+## Class diagram
+
+![](diagrams/class_diagram.puml)
+
+(If you prefer a rendered image of the UML, render the PlantUML file locally or in your CI pipeline.)
+
+## License
+
+See `LICENSE` in the project root.

topolib-0.3.0/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

topolib-0.3.0/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']

topolib-0.3.0/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
+

topolib-0.3.0/docs/source/modules.rst

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

topolib-0.3.0/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:

topolib-0.3.0/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:
+
+

topolib-0.3.0/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:

topolib-0.3.0/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:

topolib-0.3.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "topolib"
+version = "0.3.0"
+description = "A compact Python library for modeling, analyzing, and visualizing optical network topologies."
+authors = [
+    { name = "Danilo Bórquez-Paredes", email = "danilo.borquez.p@uai.cl" }
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.21",
+    "networkx>=2.6"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/DaniloBorquez/topolib"
+Documentation = "https://topolib.readthedocs.io/"
+Source = "https://gitlab.com/DaniloBorquez/topolib"
+Issues = "https://gitlab.com/DaniloBorquez/topolib/-/issues"
+
+[tool.setuptools.packages.find]
+where = ["topolib"]
+
+[tool.setuptools]
+include-package-data = true

topolib-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

topolib-0.3.0/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

topolib-0.3.0/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],
+    ]