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

knit_graphs/Loop.py

@@ -6,9 +6,13 @@ Loops are the fundamental building blocks of knitted structures and maintain rel
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Self, cast
+
+from knit_graphs.Pull_Direction import Pull_Direction
 
 if TYPE_CHECKING:
+    from knit_graphs.Knit_Graph import Knit_Graph
     from knit_graphs.Yarn import Yarn
 
 
@@ -19,94 +23,94 @@ class Loop:
     Each loop maintains its position in the yarn sequence and its relationships to other loops through stitch connections and floating elements.
 
     Attributes:
-        yarn (Yarn): The yarn that creates and holds this loop.
+        yarn (Yarn[Self]): The yarn that creates and holds this loop.
         parent_loops (list[Loop]): The list of parent loops that this loop is connected to through stitch edges.
-        front_floats (dict[Loop, set[Loop]]): A dictionary tracking loops that this loop floats in front of.
-        back_floats (dict[Loop, set[Loop]]): A dictionary tracking loops that this loop floats behind.
+        front_floats (dict[Loop, set[Loop]]): Mapping of loops involved in floats in front of this loop to the paired loops in the float.
+        back_floats (dict[Loop, set[Loop]]): Mapping of loops involved in floats behind this loop to the paired loops in the float.
     """
 
-    def __init__(self, loop_id: int, yarn: Yarn) -> None:
+    def __init__(self, loop_id: int, yarn: Yarn[Self], knit_graph: Knit_Graph[Self]) -> None:
         """Construct a Loop object with the specified identifier and yarn.
 
         Args:
             loop_id (int): A unique identifier for the loop, must be non-negative.
-            yarn (Yarn): The yarn that creates and holds this loop.
+            yarn (Typed_Yarn): The yarn that creates and holds this loop.
         """
         if loop_id < 0:
             raise ValueError(f"Loop identifier must be non-negative but got {loop_id}")
         self._loop_id: int = loop_id
-        self.yarn: Yarn = yarn
-        self.parent_loops: list[Loop] = []
-        self.front_floats: dict[Loop, set[Loop]] = {}
-        self.back_floats: dict[Loop, set[Loop]] = {}
+        self.yarn: Yarn[Self] = yarn
+        self._knit_graph: Knit_Graph[Self] = knit_graph
+        self.parent_loops: list[Self] = []
+        self.front_floats: dict[Self, set[Self]] = {}
+        self.back_floats: dict[Self, set[Self]] = {}
 
-    def add_loop_in_front_of_float(self, u: Loop, v: Loop) -> None:
-        """Set this loop to be in front of the float between loops u and v.
+    @property
+    def loop_id(self) -> int:
+        """Get the unique identifier of this loop.
 
-        This method establishes that this loop passes in front of a floating yarn segment between two other loops.
+        Returns:
+            int: The id of the loop.
+        """
+        return self._loop_id
 
-        Args:
-            u (Loop): The first loop in the float pair.
-            v (Loop): The second loop in the float pair.
+    @property
+    def has_parent_loops(self) -> bool:
+        """Check if this loop has any parent loops connected through stitch edges.
 
-        Raises:
-            ValueError: If u and v are not on the same yarn.
+        Returns:
+            bool: True if the loop has stitch-edge parents, False otherwise.
         """
-        if u.yarn != v.yarn:
-            raise ValueError("Loops of a float must share a yarn.")
-        if u not in self.back_floats:
-            self.back_floats[u] = set()
-        if v not in self.back_floats:
-            self.back_floats[v] = set()
-        self.back_floats[u].add(v)
-        self.back_floats[v].add(u)
+        return len(self.parent_loops) > 0
 
-    def remove_loop_from_front_floats(self) -> None:
+    @property
+    def parent_loop_ids(self) -> list[int]:
         """
-        Removes this loop from being in front of all marked floats. Mutates the yarns that own edges of those floats.
+        Returns:
+            list[int]: The ids of the parent loops of this loop in their stacking order.
         """
-        visited: set[Loop] = set()
-        for u, v_loops in self.front_floats.items():
-            visited.add(u)
-            for v in v_loops:
-                if v not in visited and v in u.yarn:  # float shares a yarn
-                    u.yarn.loop_graph.edges[u, v]["Back_Loops"].remove(self)
-        self.front_floats = {}
-
-    def add_loop_behind_float(self, u: Loop, v: Loop) -> None:
-        """Set this loop to be behind the float between loops u and v.
-
-        This method establishes that this loop passes behind a floating yarn segment between two other loops.
+        return [p.loop_id for p in self.parent_loops]
 
-        Args:
-            u (Loop): The first loop in the float pair.
-            v (Loop): The second loop in the float pair.
+    @property
+    def pull_directions(self) -> list[Pull_Direction]:
+        """
+        Returns:
+            list[Pull_Direction]: The pull direction of the stitches formed by this loop and its parents in stacking order of its parents.
+        """
+        return [self._knit_graph.get_pull_direction(p, cast(Self, self)) for p in self.parent_loops]
 
-        Raises:
-            ValueError: If u and v are not on the same yarn.
+    @property
+    def pull_direction(self) -> Pull_Direction:
         """
-        if u.yarn != v.yarn:
-            raise ValueError("Loops of a float must share a yarn.")
-        if u not in self.front_floats:
-            self.front_floats[u] = set()
-        if v not in self.front_floats:
-            self.front_floats[v] = set()
-        self.front_floats[u].add(v)
-        self.front_floats[v].add(u)
+        Returns:
+            Pull_Direction: The majority pull-direction of the stitches formed with the parent loops or Back-To-Front (knit-stitch) if this loop has no parents.
+        """
+        if not self.has_parent_loops:
+            return Pull_Direction.BtF
+        elif len(self.parent_loops) == 1:
+            return self._knit_graph.get_pull_direction(self.parent_loops[0], cast(Self, self))
+        else:
+            knits = len([pd for pd in self.pull_directions if pd is Pull_Direction.BtF])
+            purls = len(self.parent_loops) - knits
+            return Pull_Direction.BtF if knits > purls else Pull_Direction.FtB
+
+    def prior_loop_on_yarn(self) -> Self | None:
+        """Get the loop that precedes this loop on the same yarn.
 
-    def remove_loop_from_back_floats(self) -> None:
+        Returns:
+            Loop | None: The prior loop on the yarn, or None if this is the first loop on the yarn.
         """
-        Removes this loop from being behind of all marked floats. Mutates the yarns that own edges of those floats.
+        return self.yarn.prior_loop(self)
+
+    def next_loop_on_yarn(self) -> Self | None:
+        """Get the loop that follows this loop on the same yarn.
+
+        Returns:
+            Loop | None: The next loop on the yarn, or None if this is the last loop on the yarn.
         """
-        visited = set()
-        for u, v_loops in self.back_floats.items():
-            visited.add(u)
-            for v in v_loops:
-                if v not in visited and v in u.yarn:  # float shares a yarn
-                    u.yarn.loop_graph.edges[u, v]["Front_Loops"].remove(self)
-        self.back_floats = {}
-
-    def is_in_front_of_float(self, u: Loop, v: Loop) -> bool:
+        return self.yarn.next_loop(self)
+
+    def is_in_front_of_float(self, u: Self, v: Self) -> bool:
         """Check if this loop is positioned in front of the float between loops u and v.
 
         Args:
@@ -118,7 +122,7 @@ class Loop:
         """
         return u in self.back_floats and v in self.back_floats and v in self.back_floats[u]
 
-    def is_behind_float(self, u: Loop, v: Loop) -> bool:
+    def is_behind_float(self, u: Self, v: Self) -> bool:
         """Check if this loop is positioned behind the float between loops u and v.
 
         Args:
@@ -130,41 +134,67 @@ class Loop:
         """
         return u in self.front_floats and v in self.front_floats and v in self.front_floats[u]
 
-    def prior_loop_on_yarn(self) -> Loop | None:
-        """Get the loop that precedes this loop on the same yarn.
+    @staticmethod
+    def majority_pull_direction(loops: Sequence[Loop]) -> Pull_Direction:
+        """
+        Args:
+            loops (Sequence[Loop]): The loops to find the majority pull direction of.
 
         Returns:
-            Loop | None: The prior loop on the yarn, or None if this is the first loop on the yarn.
+            Pull_Direction: The majority pull direction of the given loops or Back-to-Front (i.e., knit-stitch) there are no loops.
         """
-        return self.yarn.prior_loop(self)
+        if len(loops) == 0:
+            return Pull_Direction.BtF
+        elif len(loops) == 1:
+            return loops[0].pull_direction
+        else:
+            knits = len([l.pull_direction for l in loops if l.pull_direction is Pull_Direction.BtF])
+            purls = len(loops) - knits
+            return Pull_Direction.BtF if knits > purls else Pull_Direction.FtB
 
-    def next_loop_on_yarn(self) -> Loop | None:
-        """Get the loop that follows this loop on the same yarn.
+    def add_loop_in_front_of_float(self, u: Self, v: Self) -> None:
+        """Set this loop to be in front of the float between loops u and v.
 
-        Returns:
-            Loop | None: The next loop on the yarn, or None if this is the last loop on the yarn.
-        """
-        return self.yarn.next_loop(self)
+        This method establishes that this loop passes in front of a floating yarn segment between two other loops.
 
-    def remove_parent_loops(self) -> list[Loop]:
-        """
-        Removes the list of parent loops from this loop.
-        Returns:
-            list[Loop]: The list of parent loops that were removed.
+        Args:
+            u (Loop): The first loop in the float pair.
+            v (Loop): The second loop in the float pair.
+
+        Raises:
+            ValueError: If u and v are not on the same yarn.
         """
-        parents = self.parent_loops
-        self.parent_loops = []
-        return parents
+        if u.yarn != v.yarn:
+            raise ValueError("Loops of a float must share a yarn.")
+        if u not in self.back_floats:
+            self.back_floats[u] = set()
+        if v not in self.back_floats:
+            self.back_floats[v] = set()
+        self.back_floats[u].add(v)
+        self.back_floats[v].add(u)
 
-    def has_parent_loops(self) -> bool:
-        """Check if this loop has any parent loops connected through stitch edges.
+    def add_loop_behind_float(self, u: Self, v: Self) -> None:
+        """Set this loop to be behind the float between loops u and v.
 
-        Returns:
-            bool: True if the loop has stitch-edge parents, False otherwise.
+        This method establishes that this loop passes behind a floating yarn segment between two other loops.
+
+        Args:
+            u (Loop): The first loop in the float pair.
+            v (Loop): The second loop in the float pair.
+
+        Raises:
+            ValueError: If u and v are not on the same yarn.
         """
-        return len(self.parent_loops) > 0
+        if u.yarn != v.yarn:
+            raise ValueError("Loops of a float must share a yarn.")
+        if u not in self.front_floats:
+            self.front_floats[u] = set()
+        if v not in self.front_floats:
+            self.front_floats[v] = set()
+        self.front_floats[u].add(v)
+        self.front_floats[v].add(u)
 
-    def add_parent_loop(self, parent: Loop, stack_position: int | None = None) -> None:
+    def add_parent_loop(self, parent: Self, stack_position: int | None = None) -> None:
         """Add a parent loop to this loop's parent stack.
 
         Args:
@@ -176,7 +206,7 @@ class Loop:
         else:
             self.parent_loops.append(parent)
 
-    def remove_parent(self, parent: Loop) -> None:
+    def remove_parent(self, parent: Self) -> None:
         """
         Removes the given parent loop from the set of parents of this loop.
         If the given loop is not a parent of this loop, nothing happens.
@@ -186,30 +216,6 @@ class Loop:
         if parent in self.parent_loops:
             self.parent_loops.remove(parent)
 
-    def ancestor_loops(self) -> set[Loop]:
-        """
-        Returns:
-            set[Loop]: The set of loops that initiate all wales that lead to this loop. The empty set if this loop has no parents.
-        """
-        if not self.has_parent_loops():
-            return set()
-        ancestors = set()
-        for parent_loop in self.parent_loops:
-            if parent_loop.has_parent_loops():
-                ancestors.update(parent_loop.ancestor_loops())
-            else:
-                ancestors.add(parent_loop)
-        return ancestors
-
-    @property
-    def loop_id(self) -> int:
-        """Get the unique identifier of this loop.
-
-        Returns:
-            int: The id of the loop.
-        """
-        return self._loop_id
-
     def __hash__(self) -> int:
         """Return hash value based on loop_id for use in sets and dictionaries.
 
@@ -230,12 +236,12 @@ class Loop:
         """Check equality with another base loop based on loop_id and type.
 
         Args:
-            other (Loop): The other loop to compare with.
+            other (Self): The other loop to compare with.
 
         Returns:
             bool: True if both loops have the same class and loop_id, False otherwise.
         """
-        return isinstance(other, Loop) and isinstance(other, other.__class__) and self.loop_id == other.loop_id
+        return isinstance(other, type(self)) and self.loop_id == other.loop_id
 
     def __lt__(self, other: Loop | int) -> bool:
         """Compare loop_id with another loop or integer for ordering.

knit_graphs/Pull_Direction.py

@@ -18,6 +18,7 @@ class Pull_Direction(Enum):
     BtF = "Knit"
     FtB = "Purl"
 
+    @property
     def opposite(self) -> Pull_Direction:
         """Get the opposite pull direction of this direction.
 
@@ -35,7 +36,7 @@ class Pull_Direction(Enum):
         Returns:
             Pull_Direction: The opposite pull direction, same as calling opposite().
         """
-        return self.opposite()
+        return self.opposite
 
     def __invert__(self) -> Pull_Direction:
         """Get the opposite pull direction using the bitwise inversion operator.
@@ -43,7 +44,7 @@ class Pull_Direction(Enum):
         Returns:
             Pull_Direction: The opposite pull direction, same as calling opposite().
         """
-        return self.opposite()
+        return self.opposite
 
     def __str__(self) -> str:
         """Get the string representation of the pull direction.