knit_graphs.Yarn module

The Yarn Data Structure.

This module contains the Yarn class and Yarn_Properties dataclass which together represent the physical yarn used in knitting patterns. The Yarn class manages the sequence of loops along a yarn and their floating relationships.

class Yarn_Properties(name: str = 'yarn', color: str = 'green')[source]

Bases: object

Dataclass structure for maintaining relevant physical properties of a yarn.

This frozen dataclass contains all the physical and visual properties that characterize a yarn, including its structure, weight, and appearance.

name: str = 'yarn'

color: str = 'green'

__str__() → str[source]

Get a formatted string representation of the yarn properties.

Returns:: String representation in format “name(plies-weight,color)”.
Return type:: str

__repr__() → str[source]

Get the name of the yarn for debugging purposes.

Returns:: The name of the yarn.
Return type:: str

__eq__(other: object) → bool[source]

Check equality with another Yarn_Properties instance.

Parameters:: other (Yarn_Properties) – The other yarn properties to compare with.
Returns:: True if all properties (name, plies, weight, color) are equal, False otherwise.
Return type:: bool

__hash__() → int[source]

Get hash value for use in sets and dictionaries.

Returns:: Hash value based on all yarn properties.
Return type:: int

__init__(name: str = 'yarn', color: str = 'green') → None

class Yarn(knit_graph: Knit_Graph[LoopT], yarn_properties: Yarn_Properties | None = None, instance: int = 0, **_kwargs: Any)[source]

Bases: Directed_Loop_Graph[LoopT, Float_Edge[LoopT]]

A class to represent a yarn structure as a sequence of connected loops.

The Yarn class manages a directed graph of loops representing the physical yarn path through a knitted structure. It maintains the sequential order of loops and their floating relationships, providing methods for navigation and manipulation of the yarn structure.

properties

The physical and visual properties of this yarn.

Type:: Yarn_Properties

__init__(knit_graph: Knit_Graph[LoopT], yarn_properties: Yarn_Properties | None = None, instance: int = 0, **_kwargs: Any)[source]

Initialize a yarn with the specified properties and optional knit graph association.

Parameters:

knit_graph (None | Knit_Graph, optional) – The knit graph that will own this yarn. Can be None for standalone yarns. Defaults to None.
yarn_properties (None | Yarn_Properties, optional) – The properties defining this yarn. If None, uses default properties. Defaults to standard properties.
instance (int, optional) – The instance of this yarn. As new yarns are formed by cuts, the instance will increase. Defaults to 0 (first instance of this yarn).

property knit_graph: Knit_Graph[LoopT]: Returns: Knit_Graph | Knit_Graph: The knit graph that owns this yarn, or None if not associated with a graph.

property last_loop: LoopT | None

Get the most recently added loop at the end of the yarn.

Returns:: The last loop on this yarn, or None if no loops have been added.
Return type:: Loop | None

property first_loop: LoopT | None

Get the first loop at the beginning of the yarn.

Returns:: The first loop on this yarn, or None if no loops have been added.
Return type:: Loop | None

property has_loops: bool

Check if the yarn has any loops on it.

Returns:: True if the yarn has at least one loop, False otherwise.
Return type:: bool

property is_cut: bool: Returns: bool: True if yarn has been cut and will no longer form loops, False otherwise.

property yarn_id: str

Get the string identifier for this yarn.

Returns:: The string representation of the yarn properties.
Return type:: str

property float_iter: Iterator[tuple[LoopT, LoopT]]: Returns: Iterator[tuple[Loop, Loop]]: An iterator over tuples of connected loops representing the yarn path.

loops_in_front_of_floats() → Iterator[tuple[LoopT, LoopT, set[LoopT]]][source]

Get all float segments with loops positioned in front of them.

Returns:: List of tuples containing the two loops defining each float and the set of loops positioned in front of that float. Only includes floats that have loops in front of them.
Return type:: list[tuple[Loop, Loop, set[Loop]]]

loops_behind_floats() → Iterator[tuple[LoopT, LoopT, set[LoopT]]][source]

Get all float segments with loops positioned behind them.

Returns:: List of tuples containing the two loops defining each float and the set of loops positioned behind that float. Only includes floats that have loops behind them.
Return type:: list[tuple[Loop, Loop, set[Loop]]]

next_loop(loop: LoopT) → LoopT | None[source]

Parameters:: loop (LoopT) – The loop to find the next loop from.
Returns:: The next loop on yarn after the specified loop, or None if it’s the last loop.
Return type:: LoopT | None
Raises:: KeyError – If the specified loop is not on this yarn.

following_float(loop: LoopT) → Float_Edge[LoopT] | None[source]

Parameters:: loop (LoopT) – The loop at the start of the desired float.
Returns:: The float-edge between the given loop and the next loop on the yarn or None if it’s the last loop.
Return type:: Float_Edge[LoopT] | None

prior_loop(loop: LoopT) → LoopT | None[source]

Parameters:: loop (Loop) – The loop to find the prior loop from.
Returns:: The prior loop on yarn before the specified loop, or None if it’s the first loop.
Return type:: Loop | None
Raises:: KeyError – If the specified loop is not on this yarn.

proceeding_float(loop: LoopT) → Float_Edge[LoopT] | None[source]

Parameters:: loop (LoopT) – The loop at the end of the desired float.
Returns:: The float-edge from the loop prior to the given loop and to the next loop or None if it’s the first loop.
Return type:: Float_Edge[LoopT] | None

has_float(u: LoopT, v: LoopT) → bool[source]

Check if there is a float edge between two loops on this yarn.

Parameters:

u (Loop) – The first loop to check for float connection.
v (Loop) – The second loop to check for float connection.

Returns:

True if there is a float edge between the loops, False otherwise.

Return type:

bool

get_loops_in_front_of_float(u: LoopT, v: LoopT) → set[LoopT][source]

Get all loops positioned in front of the float between two loops.

Parameters:

u (Loop) – The first loop in the float pair.
v (Loop) – The second loop in the float pair.

Returns:

Set of loops positioned in front of the float between u and v, or empty set if no float exists.

Return type:

set[Loop]

get_loops_behind_float(u: LoopT, v: LoopT) → set[LoopT][source]

Get all loops positioned behind the float between two loops.

Parameters:

u (Loop) – The first loop in the float pair.
v (Loop) – The second loop in the float pair.

Returns:

Set of loops positioned behind the float between u and v, or empty set if no float exists.

Return type:

set[Loop]

next_loop_id() → int[source]

Returns:: The ID of the next loop to be added to this yarn based on the knit graph or, if no knit graph is associated with this yarn, based on the last loop on this yarn.
Return type:: int

remove_loop(loop: LoopT | int) → None[source]

Remove the given loop from the yarn. Reconnects any neighboring loops to form a new float with the positioned in-front-of or behind the original floats positioned accordingly. Resets the first_loop and last_loop properties if the removed loop was the tail of the yarn.

Parameters:: loop (LoopT) – The loop to remove from the yarn.
Raises:: KeyError – The given loop does not exist in the yarn.

add_loop_to_end(loop: LoopT) → LoopT[source]

Add an existing loop to the end of this yarn and associated knit graph.

Parameters:: loop (Loop) – The loop to be added at the end of this yarn.
Returns:: The loop that was added to the end of the yarn.
Return type:: Loop

insert_loop(loop: LoopT, prior_loop: LoopT | None = None) → None[source]

Insert a loop into the yarn sequence after the specified prior loop.

Parameters:

loop (Loop | int, optional) – The loop or loop id to create a new loop. Defaults to a new loop with the id of the next loop along this yarn.
prior_loop (Loop | None) – The loop that should come before this loop on the yarn. If None, defaults to the last loop (adding to end of yarn).

Raises:

Use_Cut_Yarn_ValueError – If the yarn is cut and should not form new loops.

remove_loop_relative_to_floats(loop: LoopT) → None[source]

Removes the given loop from positions relative to floats along this yarn.

Parameters:: loop (LoopT) – The loop to remove from positions relative to floats on this yarn.

cut_yarn() → Self[source]

Cut yarn to make it no longer active and create a new yarn instance of the same type.

Returns:: New yarn of the same type after cutting this yarn.
Return type:: Yarn[LoopT]

__str__() → str[source]

Get the string representation of this yarn.

Returns:: The yarn identifier string.
Return type:: str

__repr__() → str[source]

Get the representation string of this yarn for debugging.

Returns:: The representation of the yarn properties.
Return type:: str

__hash__() → int[source]

Get the hash value of this yarn for use in sets and dictionaries.

Returns:: Hash value based on the yarn properties.
Return type:: int

__iter__() → Iterator[LoopT][source]

Iterate over loops on this yarn in sequence from first to last.

Returns:: An iterator over the loops on this yarn in their natural sequence order.
Return type:: Iterator[Loop]

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__contains__(item: LoopT | int | tuple[LoopT | int, LoopT | int]) → bool

Parameters:: item (LoopT | int | tuple[LoopT | int, LoopT | int]) – The loop, loop-id, or a pair of loops in a directed edge to search for.
Returns:: True if the graph contains the given loop or edge.
Return type:: bool

__len__() → int

Returns:: The number of loops in the graph.
Return type:: int

add_edge(u: LoopT | int, v: LoopT | int, edge_data: EdgeT) → None

Connect the given loop u to the loop v with the given edge data. :param u: The loop to connect to. :type u: LoopT | int :param v: The loop to connect to. :type v: LoopT | int :param edge_data: The edge data to associate with the connection. :type edge_data: EdgeT

Raises:: KeyError – Either of the given loops does not exist in the graph.

add_loop(loop: LoopT) → None: Add the given loop to the loop graph. :param loop: The loop to add to the graph. :type loop: LoopT

ancestors(loop: LoopT) → set[LoopT]

Parameters:: loop (LoopT) – The loop to get the ancestors of from the graph.
Returns:: The ancestors of the given loop.
Return type:: set[LoopT]

property contains_loops: bool: Returns: bool: True if the graph has at least one loop, False otherwise.

dfs_edges(loop: LoopT) → Iterator[tuple[LoopT, LoopT]]

Parameters:: loop (LoopT) – The loop to start iteration over edges from.
Returns:: The depth-first-search ordering of edges starting from the given loop.

dfs_preorder_loops(loop: LoopT) → Iterator[LoopT]

Parameters:: loop (LoopT) – The loop to start iteration from.
Returns:: The depth-first-search ordering of loops in the graph starting from the given loop.
Return type:: Iterator[LoopT]

property edge_count: int: Returns: int: The number of edges in the graph.

property edge_iter: Iterator[tuple[LoopT, LoopT, EdgeT]]

Returns:: Iterator over the edges and edge-data in the graph.
Return type:: Iterator[tuple[LoopT, LoopT, EdgeT]]

Notes

No guarantees about the order of the edges.

get_child_loop(loop: LoopT) → LoopT | None

Parameters:: loop (LoopT) – The loop to look for a child loop from.
Returns:: The child loop if one exists, or None if no child loop is found.
Return type:: LoopT | None

get_edge(u: LoopT | int, v: LoopT | int) → EdgeT

Parameters:

u (LoopT | int) – The loop or id of the first loop in the edge.
v (LoopT | int) – The loop or id of the second loop in the edge.

Returns:

The data about the edge from loop u to v.

Return type:

EdgeT

get_loop(loop_id: int) → LoopT

Parameters:: loop_id (int) – The loop id of the loop to get from the graph.
Returns:: The loop node in the graph.
Return type:: LoopT

has_child_loop(loop: LoopT) → bool

Parameters:: loop (Loop) – The loop to check for child connections.
Returns:: True if the loop has a child loop, False otherwise.
Return type:: bool

has_edge(u: LoopT | int, v: LoopT | int) → bool

Parameters:

u (LoopT | int) – The loop or id of the first loop in the edge.
v (LoopT | int) – The loop or id of the second loop in the edge.

Returns:

True if the graph has an edge from loop u to v. False, otherwise.

Return type:

bool

has_loop(loop: int | LoopT) → bool

Parameters:: loop (int | LoopT) – The loop or loop id to check for in the graph.
Returns:: True if the loop id is in the graph. False, otherwise.
Return type:: bool

is_descendant(ancestor: LoopT, descendant: LoopT) → bool

Parameters:

ancestor (LoopT) – The loop to check if it is an ancestor of the other loop.
descendant (LoopT) – The loop to check if it is a descendant of the other loop.

Returns:

True if there is a directed path from the ancestor to the descendant, False otherwise.

Return type:

bool

is_terminal_loop(loop: LoopT) → bool

Parameters:: loop (LoopT) – The loop to check for terminal status.
Returns:: True if the loop has no child loops, False otherwise.
Return type:: bool

property loop_count: int: Returns: int: The number of loops in the graph.

predecessors(loop: int | LoopT) → set[LoopT]

Parameters:: loop (int | LoopT) – The loop to get the predecessors of from the graph.
Returns:: The successors of the loop.
Return type:: set[LoopT]

remove_edge(u: LoopT | int, v: LoopT | int) → None

Removes the edge from loop u to the loop v from the graph. :param u: The loop to connect to. :type u: LoopT | int :param v: The loop to connect to. :type v: LoopT | int

Raises:: KeyError – The given edge does not exist in the graph.

property sorted_loops: list[LoopT]: Returns: list[Loop]: The list of loops in the graph sorted from the earliest formed loop to the latest formed loop.

source_loops(loop: LoopT) → set[LoopT]

Parameters:: loop (LoopT) – The loop to get the sources of.
Returns:: The source loops of the given loop. These are the loops that are the source of all ancestors to the given loop.
Return type:: set[LoopT]

successors(loop: int | LoopT) → set[LoopT]

Parameters:: loop (int | LoopT) – The loop to get the successors of from the graph.
Returns:: The successors of the loop.
Return type:: set[LoopT]

property terminal_loops: Iterator[LoopT]: Returns: Iterator[Loop]: An iterator over all terminal loops in the graph.

__getitem__(item: int) → LoopT[source]

__getitem__(item: tuple[LoopT | int, LoopT | int]) → Float_Edge[LoopT]

__getitem__(item: slice) → list[LoopT]

Get a loop by its ID from this yarn.

Parameters:: item (int | tuple[LoopT | int, LoopT | int] | slice) – The loop ,loop ID, or float between two loops to retrieve from this yarn. If given a slice, it will retrieve the elements between the specified indices in the standard ordering of loops along the yarn.
Returns:: The loop on the yarn with the matching ID. Float_Edge[LoopT]: The float data for the given pair of loops forming a float. list[LoopT]: The loops in the slice of the yarn based on their ordering along the yarn.
Return type:: LoopT
Raises:: KeyError – If the item is not found on this yarn.