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

knit_graphs/Loop.py

@@ -3,11 +3,16 @@
 This module defines the Loop class which represents individual loops in a knitting pattern.
 Loops are the fundamental building blocks of knitted structures and maintain relationships with parent loops, yarn connections, and float positions.
 """
+
 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
 
 
@@ -18,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.
+        return [p.loop_id for p in self.parent_loops]
 
-        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.
+    @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:
@@ -117,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:
@@ -129,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:
@@ -175,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.
@@ -185,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.
 
@@ -225,16 +232,16 @@ class Loop:
         """
         return self.loop_id
 
-    def __eq__(self, other: Loop) -> bool:
+    def __eq__(self, other: object) -> bool:
         """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, 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

@@ -2,6 +2,7 @@
 
 This module defines the Pull_Direction enumeration which represents the two ways a loop can be pulled through other loops in knitting: from back to front (knit) or from front to back (purl).
 """
+
 from __future__ import annotations
 
 from enum import Enum
@@ -13,9 +14,11 @@ class Pull_Direction(Enum):
     This enumeration represents the two directions that yarn can be pulled through loops to create different stitch types.
     BtF (Back to Front) creates knit stitches, while FtB (Front to Back) creates purl stitches.
     """
+
     BtF = "Knit"
     FtB = "Purl"
 
+    @property
     def opposite(self) -> Pull_Direction:
         """Get the opposite pull direction of this direction.
 
@@ -33,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.
@@ -41,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.