knit-graphs 0.0.11__py3-none-any.whl → 0.0.12__py3-none-any.whl

knit_graphs/Course.py

@@ -5,34 +5,45 @@ This module contains the Course class which represents a horizontal row of loops
 
 from __future__ import annotations
 
-from collections.abc import Iterator
-from typing import TYPE_CHECKING, cast
+from collections.abc import Iterator, Sequence
+from typing import TYPE_CHECKING, Generic, TypeVar, overload
 
 from knit_graphs.Loop import Loop
 
 if TYPE_CHECKING:
     from knit_graphs.Knit_Graph import Knit_Graph
 
+LoopT = TypeVar("LoopT", bound=Loop)
 
-class Course:
+
+class Course(Sequence[LoopT], Generic[LoopT]):
     """Course object for organizing loops into knitting rows.
 
     A Course represents a horizontal row of loops in a knitting pattern.
     It maintains an ordered list of loops and provides methods for analyzing the structure and relationships between courses in the knitted fabric.
     """
 
-    def __init__(self, knit_graph: Knit_Graph) -> None:
+    def __init__(self, course_number: int, knit_graph: Knit_Graph[LoopT]) -> None:
         """Initialize an empty course associated with a knit graph.
 
         Args:
             knit_graph (Knit_Graph): The knit graph that this course belongs to.
         """
-        self._knit_graph: Knit_Graph = knit_graph
-        self._loops_in_order: list[Loop] = []
-        self._loop_set: set[Loop] = set()
+        self._course_number: int = course_number
+        self._knit_graph: Knit_Graph[LoopT] = knit_graph
+        self._loops_in_order: list[LoopT] = []
+        self._loop_set: set[LoopT] = set()
 
     @property
-    def loops_in_order(self) -> list[Loop]:
+    def course_number(self) -> int:
+        """
+        Returns:
+            int: The course number of the course.
+        """
+        return self._course_number
+
+    @property
+    def loops_in_order(self) -> list[LoopT]:
         """
         Returns:
             list[Loop]: The list of loops in this course.
@@ -40,22 +51,34 @@ class Course:
         return self._loops_in_order
 
     @property
-    def knit_graph(self) -> Knit_Graph:
+    def loop_ids_in_course(self) -> list[int]:
+        """
+        Returns:
+            list[int]: The loop ids in the course in the order the occur in the course.
+        """
+        return [l.loop_id for l in self.loops_in_order]
+
+    @property
+    def knit_graph(self) -> Knit_Graph[LoopT]:
         """
         Returns:
             Knit_Graph: The knit graph that this course belongs to.
         """
         return self._knit_graph
 
-    def add_loop(self, loop: Loop, index: int | None = None) -> None:
+    def add_loop(self, loop: LoopT, index: int | None = None) -> None:
         """Add a loop to the course at the specified index or at the end.
 
         Args:
             loop (Loop): The loop to add to this course.
             index (int | None, optional): The index position to insert the loop at. If None, appends to the end.
+
+        Raises:
+            ValueError: If the loop is a parent to any loops already in the course.
         """
         for parent_loop in loop.parent_loops:
-            assert parent_loop not in self, f"{loop} has parent {parent_loop}, cannot be added to same course"
+            if parent_loop in self:
+                raise ValueError(f"{loop} has parent {parent_loop}, cannot be added to same course")
         self._loop_set.add(loop)
         if index is None:
             self.loops_in_order.append(loop)
@@ -68,7 +91,7 @@ class Course:
         Returns:
             bool: True if the course has at least one yarn over (loop with no parent loops) to start new wales.
         """
-        return any(not loop.has_parent_loops() for loop in self)
+        return any(not loop.has_parent_loops for loop in self)
 
     def has_decrease(self) -> bool:
         """Check if this course contains any decrease stitches that merge wales.
@@ -78,18 +101,7 @@ class Course:
         """
         return any(len(loop.parent_loops) > 1 for loop in self)
 
-    def __getitem__(self, index: int | slice) -> Loop | list[Loop]:
-        """Get loop(s) at the specified index or slice.
-
-        Args:
-            index (int | slice): The index or slice to retrieve from the course.
-
-        Returns:
-            Loop | list[Loop]: The loop at the specified index, or list of loops for a slice.
-        """
-        return self.loops_in_order[index]
-
-    def in_round_with(self, next_course: Course) -> bool:
+    def in_round_with(self, next_course: Course[LoopT]) -> bool:
         """Check if the next course connects to this course in a circular pattern.
 
         This method determines if the courses are connected in the round (circular knitting) by checking if the next course starts at the beginning of this course.
@@ -100,14 +112,14 @@ class Course:
         Returns:
             bool: True if the next course starts at the beginning of this course, indicating circular knitting.
         """
-        next_start: Loop = cast(Loop, next_course[0])
+        next_start = next_course[0]
         i = 1
-        while not next_start.has_parent_loops():
-            next_start = cast(Loop, next_course[i])
+        while not next_start.has_parent_loops:
+            next_start = next_course[i]
             i += 1
         return self[0] in next_start.parent_loops
 
-    def in_row_with(self, next_course: Course) -> bool:
+    def in_row_with(self, next_course: Course[LoopT]) -> bool:
         """Check if the next course connects to this course in a flat/row pattern.
 
         This method determines if the courses are connected in flat knitting (back and forth) by checking if the next course starts at the end of this course.
@@ -118,39 +130,48 @@ class Course:
         Returns:
             bool: True if the next course starts at the end of this course, indicating flat/row knitting.
         """
-        next_start: Loop = cast(Loop, next_course[0])
+        next_start: LoopT = next_course[0]
         i = 1
-        while not next_start.has_parent_loops():
-            next_start = cast(Loop, next_course[i])
+        while not next_start.has_parent_loops:
+            next_start = next_course[i]
             i += 1
         return self[-1] in next_start.parent_loops
 
-    def __contains__(self, loop: Loop) -> bool:
+    def __contains__(self, loop: object) -> bool:
         """Check if a loop is contained in this course.
 
         Args:
-            loop (Loop): The loop to check for membership in this course.
+            loop (LoopT): The loop to check for membership in this course.
 
         Returns:
             bool: True if the loop is in this course, False otherwise.
         """
         return loop in self._loop_set
 
-    def __iter__(self) -> Iterator[Loop]:
-        """Iterate over loops in this course in order.
+    @overload
+    def __getitem__(self, index: int) -> LoopT: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[LoopT]: ...
+
+    def __getitem__(self, index: int | slice) -> LoopT | list[LoopT]:
+        """Get loop(s) at the specified index or slice.
+
+        Args:
+            index (int | slice): The index or slice to retrieve from the course.
 
         Returns:
-            Iterator[Loop]: An iterator over the loops in this course in their natural order.
+            Loop | list[Loop]: The loop at the specified index, or list of loops for a slice.
         """
-        return iter(self.loops_in_order)
+        return self.loops_in_order[index]
 
-    def __reversed__(self) -> Iterator[Loop]:
-        """Iterate over loops in this course in reverse order.
+    def __iter__(self) -> Iterator[LoopT]:
+        """Iterate over loops in this course in order.
 
         Returns:
-            Iterator[Loop]: An iterator over the loops in this course in reverse order.
+            Iterator[Loop]: An iterator over the loops in this course in their natural order.
         """
-        return reversed(self.loops_in_order)
+        return iter(self.loops_in_order)
 
     def __len__(self) -> int:
         """Get the number of loops in this course.
@@ -166,7 +187,7 @@ class Course:
         Returns:
             str: String representation showing the ordered list of loops.
         """
-        return str(self.loops_in_order)
+        return f"Course {self.course_number}: {self.loops_in_order}"
 
     def __repr__(self) -> str:
         """Get string representation of this course for debugging.

knit_graphs/Knit_Graph.py

@@ -7,21 +7,22 @@ It manages the relationships between loops, yarns, and structural elements like
 from __future__ import annotations
 
 from collections.abc import Iterator
-from typing import Any, cast
-
-from networkx import DiGraph
+from typing import TypeVar
 
 from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
 from knit_graphs.artin_wale_braids.Loop_Braid_Graph import Loop_Braid_Graph
 from knit_graphs.artin_wale_braids.Wale import Wale
 from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
 from knit_graphs.Course import Course
+from knit_graphs.directed_loop_graph import Directed_Loop_Graph
 from knit_graphs.Loop import Loop
 from knit_graphs.Pull_Direction import Pull_Direction
 from knit_graphs.Yarn import Yarn
 
+LoopT = TypeVar("LoopT", bound=Loop)
+
 
-class Knit_Graph:
+class Knit_Graph(Directed_Loop_Graph[LoopT, Pull_Direction]):
     """A representation of knitted structures as connections between loops on yarns.
 
     The Knit_Graph class is the main data structure for representing knitted fabrics.
@@ -31,30 +32,44 @@ class Knit_Graph:
 
     def __init__(self) -> None:
         """Initialize an empty knit graph with no loops or yarns."""
-        self.stitch_graph: DiGraph = DiGraph()
-        self.braid_graph: Loop_Braid_Graph = Loop_Braid_Graph()
-        self._last_loop: None | Loop = None
-        self.yarns: set[Yarn] = set()
+        super().__init__()
+        self.braid_graph: Loop_Braid_Graph[LoopT] = Loop_Braid_Graph()
+        self._last_loop: LoopT | None = None
+        self.yarns: set[Yarn[LoopT]] = set()
 
     @property
-    def last_loop(self) -> None | Loop:
+    def last_loop(self) -> LoopT | None:
         """Get the most recently added loop in the graph.
 
         Returns:
-            None | Loop: The last loop added to the graph, or None if no loops have been added.
+            Loop | None: The last loop added to the graph, or None if no loops have been added.
         """
         return self._last_loop
 
     @property
-    def has_loop(self) -> bool:
-        """Check if the graph contains any loops.
+    def stitch_iter(self) -> Iterator[tuple[LoopT, LoopT, Pull_Direction]]:
+        """
+        Returns:
+            Iterator[tuple[LoopT, LoopT, Pull_Direction]]: Iterator over the edges and edge-data in the graph.
+
+        Notes:
+            No guarantees about the order of the edges.
+        """
+        return self.edge_iter
+
+    def get_pull_direction(self, parent: LoopT | int, child: LoopT | int) -> Pull_Direction:
+        """Get the pull direction of the stitch edge between parent and child loops.
+
+        Args:
+            parent (Loop | int): The parent loop of the stitch edge.
+            child (Loop | int): The child loop of the stitch edge.
 
         Returns:
-            bool: True if the graph has at least one loop, False otherwise.
+            Pull_Direction: The pull direction of the stitch-edge between the parent and child.
         """
-        return self.last_loop is not None
+        return self.get_edge(parent, child)
 
-    def add_crossing(self, left_loop: Loop, right_loop: Loop, crossing_direction: Crossing_Direction) -> None:
+    def add_crossing(self, left_loop: LoopT, right_loop: LoopT, crossing_direction: Crossing_Direction) -> None:
         """Add a cable crossing between two loops with the specified crossing direction.
 
         Args:
@@ -64,41 +79,41 @@ class Knit_Graph:
         """
         self.braid_graph.add_crossing(left_loop, right_loop, crossing_direction)
 
-    def add_loop(self, loop: Loop) -> None:
+    def add_loop(self, loop: LoopT) -> None:
         """Add a loop to the knit graph as a node.
 
         Args:
             loop (Loop): The loop to be added as a node in the graph. If the loop's yarn is not already in the graph, it will be added automatically.
         """
-        self.stitch_graph.add_node(loop)
+        super().add_loop(loop)
         if loop.yarn not in self.yarns:
             self.add_yarn(loop.yarn)
         if self._last_loop is None or loop > self._last_loop:
             self._last_loop = loop
 
-    def remove_loop(self, loop: Loop) -> None:
+    def remove_loop(self, loop: LoopT | int) -> None:
         """
         Remove the given loop from the knit graph.
         Args:
-            loop (Loop): The loop to be removed.
+            loop (Loop | int): The loop or loop_id to be removed.
 
         Raises:
             KeyError: If the loop is not in the knit graph.
 
         """
-        if loop not in self:
-            raise KeyError(f"Loop {loop} not on the knit graph")
-        self.braid_graph.remove_loop(loop)  # remove any crossing associated with this loop.
+        if isinstance(loop, int):
+            loop = self.get_loop(loop)
+        if loop in self.braid_graph:
+            self.braid_graph.remove_loop(loop)  # remove any crossing associated with this loop.
         # Remove any stitch edges involving this loop.
-        loop.remove_parent_loops()
         if self.has_child_loop(loop):
             child_loop = self.get_child_loop(loop)
-            assert isinstance(child_loop, Loop)
-            child_loop.remove_parent(loop)
-        self.stitch_graph.remove_node(loop)
+            if child_loop is not None:
+                child_loop.remove_parent(loop)
+        super().remove_loop(loop)
         # Remove loop from any floating positions
-        loop.remove_loop_from_front_floats()
-        loop.remove_loop_from_back_floats()
+        for yarn in self.yarns:
+            yarn.remove_loop_relative_to_floats(loop)
         # Remove loop from yarn
         yarn = loop.yarn
         yarn.remove_loop(loop)
@@ -107,23 +122,22 @@ class Knit_Graph:
         # Reset last loop
         if loop is self.last_loop:
             if len(self.yarns) == 0:  # No loops left
-                assert len(self.stitch_graph.nodes) == 0
                 self._last_loop = None
             else:  # Set to the newest loop formed at the end of any yarns.
-                self._last_loop = max(y.last_loop for y in self.yarns if isinstance(y.last_loop, Loop))
+                self._last_loop = max(y.last_loop for y in self.yarns if y.last_loop is not None)
 
-    def add_yarn(self, yarn: Yarn) -> None:
+    def add_yarn(self, yarn: Yarn[LoopT]) -> None:
         """Add a yarn to the graph without adding its loops.
 
         Args:
-            yarn (Yarn): The yarn to be added to the graph structure. This method assumes that loops do not need to be added separately.
+            yarn (Yarn[LoopT]): The yarn to be added to the graph structure. This method assumes that loops do not need to be added separately.
         """
         self.yarns.add(yarn)
 
     def connect_loops(
         self,
-        parent_loop: Loop,
-        child_loop: Loop,
+        parent_loop: LoopT,
+        child_loop: LoopT,
         pull_direction: Pull_Direction = Pull_Direction.BtF,
         stack_position: int | None = None,
     ) -> None:
@@ -138,28 +152,24 @@ class Knit_Graph:
         Raises:
             KeyError: If either the parent_loop or child_loop is not already in the knit graph.
         """
-        if parent_loop not in self:
-            raise KeyError(f"parent loop {parent_loop} not in Knit Graph")
-        if child_loop not in self:
-            raise KeyError(f"child loop {parent_loop} not in Knit Graph")
-        self.stitch_graph.add_edge(parent_loop, child_loop, pull_direction=pull_direction)
+        super().add_edge(parent_loop, child_loop, pull_direction)
         child_loop.add_parent_loop(parent_loop, stack_position)
 
-    def get_wales_ending_with_loop(self, last_loop: Loop) -> set[Wale]:
+    def get_wales_ending_with_loop(self, last_loop: LoopT) -> set[Wale[LoopT]]:
         """Get all wales (vertical columns of stitches) that end at the specified loop.
 
         Args:
             last_loop (Loop): The last loop of the joined set of wales.
 
         Returns:
-            set[Wale]: The set of wales that end at this loop.
+            set[Wale[LoopT]]: The set of wales that end at this loop.
         """
         if len(last_loop.parent_loops) == 0:
-            return {Wale(last_loop, self)}
-        ancestors = last_loop.ancestor_loops()
-        return {Wale(ancestor_loop, self) for ancestor_loop in ancestors}
+            return {Wale[LoopT](last_loop, self)}
+        sources = self.source_loops(last_loop)
+        return {Wale[LoopT](source, self) for source in sources}
 
-    def get_terminal_wales(self) -> dict[Loop, list[Wale]]:
+    def get_terminal_wales(self) -> dict[LoopT, list[Wale]]:
         """
         Get wale groups organized by their terminal loops.
 
@@ -167,24 +177,24 @@ class Knit_Graph:
             dict[Loop, list[Wale]]: Dictionary mapping terminal loops to list of wales that terminate that wale.
         """
         wale_groups = {}
-        for loop in self.terminal_loops():
+        for loop in self.terminal_loops:
             wale_groups[loop] = list(self.get_wales_ending_with_loop(loop))
         return wale_groups
 
-    def get_courses(self) -> list[Course]:
+    def get_courses(self) -> list[Course[LoopT]]:
         """Get all courses (horizontal rows) in the knit graph in chronological order.
 
         Returns:
-            list[Course]: A list of courses representing horizontal rows of loops.
+            list[Course[LoopT]: A list of courses representing horizontal rows of loops.
             The first course contains the initial set of loops. A course change occurs when a loop has a parent loop in the previous course.
         """
         courses = []
-        course = Course(self)
-        for loop in self.sorted_loops():
+        course = Course(0, self)
+        for loop in self.sorted_loops:
             for parent in loop.parent_loops:
                 if parent in course:  # start a new course
                     courses.append(course)
-                    course = Course(self)
+                    course = Course(course.course_number + 1, self)
                     break
             course.add_loop(loop)
         courses.append(course)
@@ -196,112 +206,4 @@ class Knit_Graph:
         Returns:
             set[Wale_Group]: The set of wale-groups that lead to the terminal loops of this graph. Each wale group represents a collection of wales that end at the same terminal loop.
         """
-        return {Wale_Group(terminal_loop, self) for terminal_loop in self.terminal_loops()}
-
-    def __contains__(self, item: Loop | tuple[Loop, Loop]) -> bool:
-        """Check if a loop is contained in the knit graph.
-
-        Args:
-            item (Loop | tuple[Loop, Loop]): The loop being checked for in the graph or the parent-child stitch edge to check for in the knit graph.
-
-        Returns:
-            bool: True if the given loop or stitch edge is in the graph, False otherwise.
-        """
-        if isinstance(item, Loop):
-            return bool(self.stitch_graph.has_node(item))
-        else:
-            return bool(self.stitch_graph.has_edge(item[0], item[1]))
-
-    def __iter__(self) -> Iterator[Loop]:
-        """
-        Returns:
-            Iterator[Loop]: An iterator over all loops in the knit graph.
-        """
-        return cast(Iterator[Loop], iter(self.stitch_graph.nodes))
-
-    def __getitem__(self, item: int) -> Loop:
-        loop = next((loop for loop in self if loop.loop_id == item), None)
-        if loop is None:
-            raise KeyError(f"Loop of id {item} not in knit graph")
-        return loop
-
-    def sorted_loops(self) -> list[Loop]:
-        """
-        Returns:
-            list[Loop]: The list of loops in the stitch graph sorted from the earliest formed loop to the latest formed loop.
-        """
-        return sorted(self.stitch_graph.nodes)
-
-    def get_pull_direction(self, parent: Loop, child: Loop) -> Pull_Direction | None:
-        """Get the pull direction of the stitch edge between parent and child loops.
-
-        Args:
-            parent (Loop): The parent loop of the stitch edge.
-            child (Loop): The child loop of the stitch edge.
-
-        Returns:
-            Pull_Direction | None: The pull direction of the stitch-edge between the parent and child, or None if there is no edge between these loops.
-        """
-        edge = self.get_stitch_edge(parent, child)
-        if edge is None:
-            return None
-        else:
-            return cast(Pull_Direction, edge["pull_direction"])
-
-    def get_stitch_edge(self, parent: Loop, child: Loop) -> dict[str, Any] | None:
-        """Get the stitch edge data between two loops.
-
-        Args:
-            parent (Loop): The parent loop of the stitch edge.
-            child (Loop): The child loop of the stitch edge.
-
-        Returns:
-            dict[str, Any] | None: The edge data dictionary for this stitch edge, or None if no edge exists between these loops.
-        """
-        if self.stitch_graph.has_edge(parent, child):
-            return cast(dict[str, Any], self.stitch_graph.get_edge_data(parent, child))
-        else:
-            return None
-
-    def get_child_loop(self, loop: Loop) -> Loop | None:
-        """Get the child loop of the specified parent loop.
-
-        Args:
-            loop (Loop): The loop to look for a child loop from.
-
-        Returns:
-            Loop | None: The child loop if one exists, or None if no child loop is found.
-        """
-        successors = [*self.stitch_graph.successors(loop)]
-        if len(successors) == 0:
-            return None
-        return cast(Loop, successors[0])
-
-    def has_child_loop(self, loop: Loop) -> bool:
-        """Check if a loop has a child loop connected to it.
-
-        Args:
-            loop (Loop): The loop to check for child connections.
-
-        Returns:
-            bool: True if the loop has a child loop, False otherwise.
-        """
-        return self.get_child_loop(loop) is not None
-
-    def is_terminal_loop(self, loop: Loop) -> bool:
-        """Check if a loop is terminal (has no child loops and terminates a wale).
-
-        Args:
-            loop (Loop): The loop to check for terminal status.
-
-        Returns:
-            bool: True if the loop has no child loops and terminates a wale, False otherwise.
-        """
-        return not self.has_child_loop(loop)
-
-    def terminal_loops(self) -> Iterator[Loop]:
-        """
-        Returns:
-            Iterator[Loop]: An iterator over all terminal loops in the knit graph.
-        """
-        return iter(loop for loop in self if self.is_terminal_loop(loop))
+        return {Wale_Group(terminal_loop, self) for terminal_loop in self.terminal_loops}