topolib 0.8.0__py3-none-any.whl

topolib/elements/__init__.py

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

topolib/elements/link.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from topolib.elements.node import Node
+
+
+class Link:
+    """
+    Represents a link between two nodes.
+
+    Parameters
+    ----------
+    id : int
+        Unique identifier for the link.
+    source : :class:`topolib.elements.node.Node`
+        Source node-like object (must have id, name, latitude, longitude).
+    target : :class:`topolib.elements.node.Node`
+        Target node-like object (must have id, name, latitude, longitude).
+    length : float
+        Length of the link (must be non-negative).
+
+    Examples
+    --------
+    >>> link = Link(1, nodeA, nodeB, 10.5)
+    >>> link.length
+    """
+
+    def __init__(self, id: int, source: "Node", target: "Node", length: float):
+        self._id = id
+        self.source = source
+        self.target = target
+        self.length = length
+
+    @property
+    def id(self) -> int:
+        """
+        int: Unique identifier for the link.
+        """
+        return self._id
+
+    @id.setter
+    def id(self, value: int) -> None:
+        """
+        Set the link's unique identifier.
+        """
+        self._id = value
+
+    @property
+    def source(self) -> "Node":
+        """
+        :class:`topolib.elements.node.Node`: Source node of the link.
+        """
+        return self._source
+
+    @source.setter
+    def source(self, value: "Node") -> None:
+        """
+        Set the source node. Must have id, name, latitude, longitude.
+        """
+        required_attrs = ("id", "name", "latitude", "longitude")
+        for attr in required_attrs:
+            if not hasattr(value, attr):
+                raise TypeError(f"source must behave like a Node (missing {attr})")
+        self._source = value
+
+    @property
+    def target(self) -> "Node":
+        """
+        :class:`topolib.elements.node.Node`: Target node of the link.
+        """
+        return self._target
+
+    @target.setter
+    def target(self, value: "Node") -> None:
+        """
+        Set the target node. Must have id, name, latitude, longitude.
+        """
+        required_attrs = ("id", "name", "latitude", "longitude")
+        for attr in required_attrs:
+            if not hasattr(value, attr):
+                raise TypeError(f"target must behave like a Node (missing {attr})")
+        self._target = value
+
+    @property
+    def length(self) -> float:
+        """
+        float: Length of the link (non-negative).
+        """
+        return self._length
+
+    @length.setter
+    def length(self, value: float) -> None:
+        """
+        Set the length of the link. Must be a non-negative float.
+        """
+        try:
+            numeric = float(value)
+        except Exception:
+            raise TypeError("length must be a numeric value")
+        if numeric < 0:
+            raise ValueError("length must be non-negative")
+        self._length = numeric
+
+    def endpoints(self):
+        """
+        Return the (source, target) nodes as a tuple.
+
+        Returns
+        -------
+        tuple
+            (source_node, target_node)
+        """
+        return self._source, self._target
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the Link.
+        """
+        return f"Link(id={self._id}, source={self._source.id} ({self.source.name}), target={self._target.id} ({self.target.name}), length={self._length})"

topolib/elements/node.py

@@ -0,0 +1,230 @@
+"""
+Node class for optical network topologies.
+
+This module defines the Node class, representing a network node with geographic coordinates.
+"""
+
+from typing import Tuple
+
+
+class Node:
+    """
+    Represents a node in an optical network topology.
+
+    :param id: Unique identifier for the node.
+    :type id: int
+    :param name: Name of the node.
+    :type name: str
+    :param latitude: Latitude coordinate of the node.
+    :type latitude: float
+    :param longitude: Longitude coordinate of the node.
+    :type longitude: float
+    :param weight: Node weight (optional, default 0).
+    :type weight: float or int
+    :param pop: Node population (optional, default 0).
+    :type pop: int
+    :param dc: Datacenter (DC) value for the node (optional, default 0).
+    :type dc: int
+    :param ixp: IXP (Internet Exchange Point) value for the node (optional, default 0).
+    :type ixp: int
+    """
+
+    def __init__(
+        self,
+        id: int,
+        name: str,
+        latitude: float,
+        longitude: float,
+        weight: float = 0,
+        pop: int = 0,
+        dc: int = 0,
+        ixp: int = 0,
+    ):
+        self._id = id
+        self._name = name
+        self._latitude = latitude
+        self._longitude = longitude
+        self._weight = weight
+        self._pop = pop
+        self._dc = dc
+        self._ixp = ixp
+
+    @property
+    def dc(self) -> int:
+        """
+        Get the datacenter (DC) count or value for the node.
+
+        :return: Node DC value.
+        :rtype: int
+        """
+        return self._dc
+
+    @dc.setter
+    def dc(self, value: int) -> None:
+        """
+        Set the datacenter (DC) value for the node.
+
+        :param value: Node DC value.
+        :type value: int
+        """
+        self._dc = value
+
+    @property
+    def ixp(self) -> int:
+        """
+        Get the IXP (Internet Exchange Point) count or value for the node.
+
+        :return: Node IXP value.
+        :rtype: int
+        """
+        return self._ixp
+
+    @ixp.setter
+    def ixp(self, value: int) -> None:
+        """
+        Set the IXP (Internet Exchange Point) value for the node.
+
+        :param value: Node IXP value.
+        :type value: int
+        """
+        self._ixp = value
+
+    @property
+    def id(self) -> int:
+        """
+        Get the unique identifier of the node.
+
+        :return: Node ID.
+        :rtype: int
+        """
+        return self._id
+
+    @id.setter
+    def id(self, value: int) -> None:
+        """
+        Set the unique identifier of the node.
+
+        :param value: Node ID.
+        :type value: int
+        """
+        self._id = value
+
+    @property
+    def name(self) -> str:
+        """
+        Get the name of the node.
+
+        :return: Node name.
+        :rtype: str
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """
+        Set the name of the node.
+
+        :param value: Node name.
+        :type value: str
+        """
+        self._name = value
+
+    @property
+    def latitude(self) -> float:
+        """
+        Get the latitude coordinate of the node.
+
+        :return: Latitude value.
+        :rtype: float
+        """
+        return self._latitude
+
+    @latitude.setter
+    def latitude(self, value: float) -> None:
+        """
+        Set the latitude coordinate of the node.
+
+        :param value: Latitude value.
+        :type value: float
+        """
+        self._latitude = value
+
+    @property
+    def longitude(self) -> float:
+        """
+        Get the longitude coordinate of the node.
+
+        :return: Longitude value.
+        :rtype: float
+        """
+        return self._longitude
+
+    @longitude.setter
+    def longitude(self, value: float) -> None:
+        """
+        Set the longitude coordinate of the node.
+
+        :param value: Longitude value.
+        :type value: float
+        """
+        self._longitude = value
+
+    @property
+    def weight(self) -> float:
+        """
+        Get the weight of the node.
+
+        :return: Node weight.
+        :rtype: float
+        """
+        return self._weight
+
+    @weight.setter
+    def weight(self, value: float) -> None:
+        """
+        Set the weight of the node.
+
+        :param value: Node weight.
+        :type value: float
+        """
+        self._weight = value
+
+    @property
+    def pop(self) -> int:
+        """
+        Get the population of the node.
+
+        :return: Node population.
+        :rtype: int
+        """
+        return self._pop
+
+    @pop.setter
+    def pop(self, value: int) -> None:
+        """
+        Set the population of the node.
+
+        :param value: Node population.
+        :type value: int
+        """
+        self._pop = value
+
+    def coordinates(self) -> Tuple[float, float]:
+        """
+        Returns the (latitude, longitude) coordinates of the node.
+
+        :return: Tuple containing latitude and longitude.
+        :rtype: Tuple[float, float]
+        """
+        return self._latitude, self._longitude
+
+    def __repr__(self) -> str:
+        """Return a concise representation of the Node.
+
+        Includes id, name, latitude, longitude and additional attributes.
+        """
+        return (
+            f"Node(id={self._id}, name={self._name!r}, latitude={self._latitude}, "
+            f"longitude={self._longitude}, weight={self._weight}, pop={self._pop}, "
+            f"dc={self._dc}, ixp={self._ixp})"
+        )

topolib/topology/__init__.py

@@ -0,0 +1,4 @@
+from .path import Path
+from .topology import Topology
+
+__all__ = ["Path", "Topology"]

topolib/topology/path.py

@@ -0,0 +1,84 @@
+"""
+Path class for representing a sequence of nodes and links in a topology.
+"""
+
+from typing import List, Any
+
+
+class Path:
+    """
+    Represents a path through the network topology as an ordered sequence of nodes and links.
+
+    Parameters
+    ----------
+    nodes : list
+        Ordered list of node objects in the path.
+    links : list
+        Ordered list of link objects in the path (len(links) == len(nodes) - 1).
+
+    Raises
+    ------
+    ValueError
+        If the number of nodes and links is inconsistent or empty.
+
+    Attributes
+    ----------
+    nodes : list
+        Ordered list of nodes in the path.
+    links : list
+        Ordered list of links in the path.
+
+    Examples
+    --------
+    >>> nodes = [Node(1), Node(2), Node(3)]
+    >>> links = [Link('a'), Link('b')]
+    >>> path = Path(nodes, links)
+    >>> path.length()
+    2
+    >>> path.endpoints()
+    (Node(1), Node(3))
+    """
+
+    def __init__(self, nodes: List[Any], links: List[Any]):
+        if not nodes or not links:
+            raise ValueError("A path must have at least one node and one link.")
+        if len(nodes) != len(links) + 1:
+            raise ValueError("Number of nodes must be one more than number of links.")
+        self.nodes = nodes
+        self.links = links
+
+    def length(self) -> int:
+        """
+        Return the number of links in the path.
+
+        Returns
+        -------
+        int
+            Number of links in the path.
+        """
+        return len(self.links)
+
+    def hop_count(self) -> int:
+        """
+        Return the number of hops (links) in the path.
+
+        Returns
+        -------
+        int
+            Number of hops (links) in the path.
+        """
+        return self.length()
+
+    def endpoints(self):
+        """
+        Return the source and target nodes of the path as a tuple.
+
+        Returns
+        -------
+        tuple
+            (source_node, target_node)
+        """
+        return (self.nodes[0], self.nodes[-1])
+
+    def __repr__(self):
+        return f"Path(nodes={self.nodes}, links={self.links})"