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='yarn', plies=2, weight=28, color='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.

Parameters:

name (str)
plies (int)
weight (float)
color (str)

name: str = 'yarn'

plies: int = 2

weight: float = 28

color: str = 'green'

__str__()[source]

Get a formatted string representation of the yarn properties.

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

__repr__()[source]

Get the name of the yarn for debugging purposes.

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

static default_yarn()[source]

Create a default yarn properties instance.

Returns:: A default yarn instance with standard properties.
Return type:: Yarn_Properties

__eq__(other)[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__()[source]

Get hash value for use in sets and dictionaries.

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

__init__(name='yarn', plies=2, weight=28, color='green')

Parameters:

name (str)
plies (int)
weight (float)
color (str)

class Yarn(yarn_properties=None, knit_graph=None)[source]

Bases: object

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.

loop_graph

The directed graph loops connected by yarn-wise float edges.

Type:: DiGraph

properties

The physical and visual properties of this yarn.

Type:: Yarn_Properties

Parameters:

yarn_properties (Optional[Yarn_Properties])
knit_graph (Optional[Knit_Graph])

__init__(yarn_properties=None, knit_graph=None)[source]

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

Parameters:

yarn_properties (None | Yarn_Properties, optional) – The properties defining this yarn. If None, uses default properties. Defaults to standard properties.
knit_graph (None | Knit_Graph, optional) – The knit graph that will own this yarn. Can be None for standalone yarns. Defaults to None.

property knit_graph: None | Knit_Graph

Get the knit graph that owns this yarn.

Returns:: The knit graph that owns this yarn, or None if not associated with a graph.
Return type:: None | Knit_Graph

has_float(u, v)[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

add_loop_in_front_of_float(front_loop, u, v)[source]

Record that a loop falls in front of the float between two other loops.

Parameters:

front_loop (Loop) – The loop that is positioned in front of the float.
u (Loop) – The first loop in the float pair.
v (Loop) – The second loop in the float pair.

Return type:

None

add_loop_behind_float(back_loop, u, v)[source]

Record that a loop falls behind the float between two other loops.

Parameters:

back_loop (Loop) – The loop that is positioned behind the float.
u (Loop) – The first loop in the float pair.
v (Loop) – The second loop in the float pair.

Return type:

None

get_loops_in_front_of_float(u, v)[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, v)[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]

property last_loop: Loop | 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: Loop | 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 yarn_id: str

Get the string identifier for this yarn.

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

__str__()[source]

Get the string representation of this yarn.

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

__repr__()[source]

Get the representation string of this yarn for debugging.

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

__hash__()[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

__len__()[source]

Get the number of loops on this yarn.

Returns:: The total number of loops on this yarn.
Return type:: int

make_loop_on_end()[source]

Create and add a new loop at the end of the yarn.

Returns:: The newly created loop that was added to the end of this yarn.
Return type:: Loop

add_loop_to_end(loop)[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, prior_loop=None)[source]

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

Parameters:

loop (Loop) – The loop to be added to 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).

Return type:

None

next_loop(loop)[source]

Get the loop that follows the specified loop on this yarn.

Parameters:: loop (Loop) – 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:: Loop | None
Raises:: KeyError – If the specified loop is not on this yarn.

prior_loop(loop)[source]

Get the loop that precedes the specified loop on this yarn.

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.

__contains__(item)[source]

Check if a loop is contained on this yarn.

Parameters:: item (Loop | int) – The loop or loop ID being checked for in the yarn.
Returns:: True if the loop is on the yarn, False otherwise.
Return type:: bool

__iter__()[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]

edge_iter()[source]

Iterate over the edges between loops on this yarn.

Returns:: An iterator over tuples of connected loops representing the yarn path.
Return type:: Iterator[tuple[Loop, Loop]]

loops_in_front_of_floats()[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()[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]]]

__getitem__(item)[source]

Get a loop by its ID from this yarn.

Parameters:: item (int) – The loop ID to retrieve from this yarn.
Returns:: The loop on the yarn with the matching ID.
Return type:: Loop
Raises:: KeyError – If the loop ID is not found on this yarn.