knit-graphs 0.0.6__py3-none-any.whl → 0.0.7__py3-none-any.whl

knit_graphs/Loop.py

@@ -1,155 +1,141 @@
-"""Module containing the Loop Class"""
-
-
-class Loop:
-    """
-    A class to represent a single loop structure for modeling a single loop in a knitting pattern.
-
-    Attributes:
-    -----------
-    _loop_id : int
-        a unique identifier for the loop
-    yarn : Yarn
-        the Yarn variable that creates and holds this loop
-    parent_loops : list
-        the list of parent loops
-    front_floats : dict
-        a dictionary of loops in front of the float
-    back_floats : dict
-        a dictionary of loops behind the float
-
-    Methods:
-    -----------
-    add_loop_in_front_of_float(u, v)
-        Set this loop to be in front of the float between u and v
-    add_loop_behind_float(u, v)
-        Set this loop to be behind the float between u and v
-    is_in_front_of_float(u, v)
-        Check if the float between u and v is in front of this loop
-    is_behind_float(u, v)
-        Check if the float between u and v is behind this loop
-    prior_loop_on_yarn()
-        Return the prior loop on yarn or None if first loop on yarn
-    next_loop_on_yarn()
-        Return the next loop on yarn or None if last loop on yarn
-    has_parent_loops()
-        Check if loop has stitch-edge parents
-    add_parent_loop(parent, stack_position)
-        Add the parent Loop onto the stack of parent_loops
-    """
-
-    def __init__(self, loop_id: int, yarn):
-        """
-        Constructs the Loop object.
-
-        Parameters:
-        -----------
-        loop_id : int
-            a unique identifier for the loop, must be non-negative
-        yarn : Yarn
-            the Yarn variable that creates and holds this loop
-        """
-        assert loop_id >= 0, f"{loop_id}: Loop_id must be non-negative"
-        self._loop_id: int = loop_id
-        self.yarn = yarn
-        self.parent_loops: list[Loop] = []
-        self.front_floats: dict[Loop, set[Loop]] = {}
-        self.back_floats: dict[Loop, set[Loop]] = {}
-
-    def add_loop_in_front_of_float(self, u, v):
-        """
-        Set this loop to be in front of the float between u and v
-        :param u: First loop in float
-        :param v: Second loop in float
-        """
-        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 add_loop_behind_float(self, u, v):
-        """
-        Set this loop to be behind the float between u and v
-        :param u: First loop in float
-        :param v: Second loop in float
-        """
-        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 is_in_front_of_float(self, u, v) -> bool:
-        """
-        :param u: First loop in float.
-        :param v: Second loop in float.
-        :return: True if the float between u and v is in front of this 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, v) -> bool:
-        """
-        :param u: First loop in float.
-        :param v: Second loop in float.
-        :return: True if the float between u and v is behind this 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):
-        """
-        :return: Prior loop on yarn or None if first loop on yarn
-        """
-        return self.yarn.prior_loop(self)
-
-    def next_loop_on_yarn(self):
-        """
-        :return: Next loop on yarn or Non if last loop on yarn
-        """
-        return self.yarn.next_loop(self)
-
-    def has_parent_loops(self) -> bool:
-        """
-        :return: True if loop has stitch-edge parents
-        """
-        return len(self.parent_loops) > 0
-
-    def add_parent_loop(self, parent, stack_position: int | None = None):
-        """
-        Adds the parent Loop onto the stack of parent_loops
-        :param parent: the Loop to be added onto the stack
-        :param stack_position: The position to insert the parent into, by default add on top of the stack
-        """
-        if stack_position is not None:
-            self.parent_loops.insert(stack_position, parent)
-        else:
-            self.parent_loops.append(parent)
-
-    @property
-    def loop_id(self) -> int:
-        """
-        :return: the id of the loop
-        """
-        return self._loop_id
-
-    def __hash__(self):
-        return self.loop_id
-
-    def __eq__(self, other):
-        return isinstance(other, Loop) and self.loop_id == other.loop_id and self.yarn == other.yarn
-
-    def __lt__(self, other):
-        assert isinstance(other, Loop)
-        return self.loop_id < other.loop_id
-
-    def __gt__(self, other):
-        assert isinstance(other, Loop)
-        return self.loop_id > other.loop_id
-
-    def __str__(self):
-        return f"{self.loop_id} on yarn {self.yarn}"
-
-    def __repr__(self):
-        return str(self.loop_id)
+"""Module containing the Loop Class.
+
+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 cast
+
+from knit_graphs._base_classes import _Base_Loop, _Base_Yarn
+
+
+class Loop(_Base_Loop):
+    """A class to represent a single loop structure for modeling a single loop in a knitting pattern.
+
+    The Loop class manages yarn relationships, parent-child connections for stitches, and float positioning for complex knitting structures.
+    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.
+        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.
+    """
+
+    def __init__(self, loop_id: int, yarn: _Base_Yarn) -> 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 (_Base_Yarn): The yarn that creates and holds this loop.
+        """
+        super().__init__(loop_id)
+        self.yarn: _Base_Yarn = yarn
+        self.parent_loops: list[Loop] = []
+        self.front_floats: dict[Loop, set[Loop]] = {}
+        self.back_floats: dict[Loop, set[Loop]] = {}
+
+    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.
+
+        This method establishes that this loop passes in front of 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.
+        """
+        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 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.
+
+        Args:
+            u (Loop): The first loop in the float pair.
+            v (Loop): The second loop in the float pair.
+        """
+        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 is_in_front_of_float(self, u: Loop, v: Loop) -> bool:
+        """Check if this loop is positioned in front of the float between loops u and v.
+
+        Args:
+            u (Loop): The first loop in the float pair.
+            v (Loop): The second loop in the float pair.
+
+        Returns:
+            bool: True if the float between u and v passes behind this loop, False otherwise.
+        """
+        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:
+        """Check if this loop is positioned behind the float between loops u and v.
+
+        Args:
+            u (Loop): The first loop in the float pair.
+            v (Loop): The second loop in the float pair.
+
+        Returns:
+            bool: True if the float between u and v passes in front of this loop, False otherwise.
+        """
+        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.
+
+        Returns:
+            Loop | None: The prior loop on the yarn, or None if this is the first loop on the yarn.
+        """
+        loop = self.yarn.prior_loop(self)
+        if loop is None:
+            return None
+        else:
+            return cast(Loop, loop)
+
+    def next_loop_on_yarn(self) -> Loop:
+        """Get the loop that follows this loop on the same yarn.
+
+        Returns:
+            Loop: The next loop on the yarn, or None if this is the last loop on the yarn.
+        """
+        return cast(Loop, self.yarn.next_loop(self))
+
+    def has_parent_loops(self) -> bool:
+        """Check if this loop has any parent loops connected through stitch edges.
+
+        Returns:
+            bool: True if the loop has stitch-edge parents, False otherwise.
+        """
+        return len(self.parent_loops) > 0
+
+    def add_parent_loop(self, parent: Loop, stack_position: int | None = None) -> None:
+        """Add a parent loop to this loop's parent stack.
+
+        Args:
+            parent (Loop): The loop to be added as a parent to this loop.
+            stack_position (int | None, optional): The position to insert the parent into the parent stack. If None, adds the parent on top of the stack. Defaults to None.
+        """
+        if stack_position is not None:
+            self.parent_loops.insert(stack_position, parent)
+        else:
+            self.parent_loops.append(parent)
+
+    def __str__(self) -> str:
+        """Get a string representation of this loop.
+
+        Returns:
+            str: String representation showing the loop ID and associated yarn.
+        """
+        return f"{self.loop_id} on yarn {self.yarn}"

knit_graphs/Pull_Direction.py

@@ -1,23 +1,68 @@
-"""Enumerator used to define the two pull-direction of a loop through other loops"""
-from enum import Enum
-
-
-class Pull_Direction(Enum):
-    """An enumerator of the two pull-directions of a loop."""
-    BtF = "Knit"
-    FtB = "Purl"
-
-    def opposite(self):
-        """
-        :return: returns the opposite pull direction of self
-        """
-        if self is Pull_Direction.BtF:
-            return Pull_Direction.FtB
-        else:
-            return Pull_Direction.BtF
-
-    def __str__(self):
-        return self.value
-
-    def __repr__(self):
-        return self.value
+"""Enumerator used to define the two pull-directions of a loop through other loops.
+
+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
+
+
+class Pull_Direction(Enum):
+    """An enumerator of the two pull-directions of a loop in knitting operations.
+
+    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"
+
+    def opposite(self) -> Pull_Direction:
+        """Get the opposite pull direction of this direction.
+
+        Returns:
+            Pull_Direction: The opposite pull direction. If this is BtF, returns FtB. If this is FtB, returns BtF.
+        """
+        if self is Pull_Direction.BtF:
+            return Pull_Direction.FtB
+        else:
+            return Pull_Direction.BtF
+
+    def __neg__(self) -> Pull_Direction:
+        """Get the opposite pull direction using the negation operator.
+
+        Returns:
+            Pull_Direction: The opposite pull direction, same as calling opposite().
+        """
+        return self.opposite()
+
+    def __invert__(self) -> Pull_Direction:
+        """Get the opposite pull direction using the bitwise inversion operator.
+
+        Returns:
+            Pull_Direction: The opposite pull direction, same as calling opposite().
+        """
+        return self.opposite()
+
+    def __str__(self) -> str:
+        """Get the string representation of the pull direction.
+
+        Returns:
+            str: The value of the pull direction ("Knit" for BtF, "Purl" for FtB).
+        """
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        """Get the representation string of the pull direction for debugging.
+
+        Returns:
+            str: The name of the pull direction ("BtF" or "FtB").
+        """
+        return self.name
+
+    def __hash__(self) -> int:
+        """Get the hash value of the pull direction for use in sets and dictionaries.
+
+        Returns:
+            int: Hash value based on the pull direction name.
+        """
+        return hash(self.name)